minions

README

Minions

Overview

Minions is a collection of utility functions for building Go web applications.

Features

• Role based http.Handler protection
• Pretty printed JSON output
• Pretty printed XML output
• HTML templates loaded from directory tree with optional auto reload
• Utility structures for validation and passing arbitraty data to templates

Installation

To install this package, run:

go get github.com/nimbusec-oss/minions

Documentation

Index

• func JSON(w http.ResponseWriter, r *http.Request, code int, data interface{}) error
• func NewFileServer(prefix string, root string) http.HandlerFunc
• func XML(w http.ResponseWriter, r *http.Request, code int, data interface{}) error
• type Anonymous
  • func (a Anonymous) Authenticated() bool
  • func (a Anonymous) HasAnyRole(roles ...string) bool
• type BindingResult
  • func (br BindingResult) Fail(field, err string)
  • func (br BindingResult) Include(other BindingResult)
  • func (br BindingResult) MarshalJSON() ([]byte, error)
  • func (br BindingResult) Valid() bool
• type Guard
  • func NewGuard() *Guard
  • func (g *Guard) ForbiddenFn(fn http.HandlerFunc) *Guard
  • func (g *Guard) PrincipalFn(fn func(r *http.Request) Principal) *Guard
  • func (g *Guard) Protect(fn http.HandlerFunc, roles ...string) http.HandlerFunc
  • func (g *Guard) ProtectMiddleware(roles ...string) func(http.Handler) http.Handler
  • func (g *Guard) UnauthorizedFn(fn http.HandlerFunc) *Guard
• type Principal
• type Templates
  • func NewTemplates(dir string, reload bool) Templates
  • func (tpl Templates) Execute(w io.Writer, name string, data interface{}, ctxFuncs template.FuncMap) error
  • func (tpl Templates) Funcs(funcmap template.FuncMap) Templates
  • func (tpl Templates) HTML(w http.ResponseWriter, r *http.Request, code int, name string, ...) error
  • func (tpl Templates) Load() (Templates, error)
• type V
  • func (v V) MarshalJSON() ([]byte, error)

Functions

func JSON

func JSON(w http.ResponseWriter, r *http.Request, code int, data interface{}) error

JSON outputs the data encoded as JSON.

func NewFileServer

func NewFileServer(prefix string, root string) http.HandlerFunc

func XML

func XML(w http.ResponseWriter, r *http.Request, code int, data interface{}) error

XML outputs the data encoded as XML.

Types

type Anonymous

type Anonymous struct{}

Anonymous implements the Principal interface for unauthenticated users and can be used as a fallback principal when none is set in the current session.

func (Anonymous) Authenticated

func (a Anonymous) Authenticated() bool

Authenticated returns always false, because Anonymous users are not authenticated.

func (Anonymous) HasAnyRole

func (a Anonymous) HasAnyRole(roles ...string) bool

HasAnyRole returns always false for any role, because Anonymous users are not authenticated.

type BindingResult

type BindingResult map[string]string

BindingResult holds validation errors of the binding process from a HTML form to a Go struct.

func (BindingResult) Fail

func (br BindingResult) Fail(field, err string)

Fail marks the binding as failed and stores an error for the given field that caused the form binding to fail.

func (BindingResult) Include

func (br BindingResult) Include(other BindingResult)

Include copies all errors and state of a binding result

func (BindingResult) MarshalJSON

func (br BindingResult) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (BindingResult) Valid

func (br BindingResult) Valid() bool

Valid returns whether the binding was successful or not.

type Guard

type Guard struct {
	// contains filtered or unexported fields
}

Guard enforces a role based security model on protected resources. Before a visitor can access a procted resource, he must be authenticated and have the required roles to access. Authentication is outside the scope of the guard, the principal is fetched using a provided PrincipalFn.

func NewGuard

func NewGuard() *Guard

NewGuard creates a new guard. You wan't to overwrite at lest the PrincipalFn before the guard is of any use, otherwise the guard always returns an unauthenticated Anonymous user that is denied access to every protected resource.

func (*Guard) ForbiddenFn

func (g *Guard) ForbiddenFn(fn http.HandlerFunc) *Guard

ForbiddenFn overwrites the function used when a principal is not allowed for a request. The return value is the guard, so calls can be chained.

func (*Guard) PrincipalFn

func (g *Guard) PrincipalFn(fn func(r *http.Request) Principal) *Guard

PrincipalFn overwrites the function used to fetch a principal object for a request. The return value is the guard, so calls can be chained.

func (*Guard) Protect

func (g *Guard) Protect(fn http.HandlerFunc, roles ...string) http.HandlerFunc

Protect requires that the principal has at least one of the provided roles before the request is forwarded to the protected handler.

func (*Guard) ProtectMiddleware

func (g *Guard) ProtectMiddleware(roles ...string) func(http.Handler) http.Handler

ProtectMiddleware requires that the principal has at least one of the provided roles before the request is forwarded to the protected handler.

func (*Guard) UnauthorizedFn

func (g *Guard) UnauthorizedFn(fn http.HandlerFunc) *Guard

UnauthorizedFn overwrites the function used when a principal is missing or not authenticated for a request. The return value is the guard, so calls can be chained.

type Principal

type Principal interface {
	Authenticated() bool
	HasAnyRole(roles ...string) bool
}

Principal is an entity that can be authenticated and verified.

type Templates

type Templates struct {
	// contains filtered or unexported fields
}

Templates is a collection of HTML templates in the html/template format of the go stdlib. The templates are loaded and parsed on the first request, on every request when reload is enabled on explicitly when Load() is called.

func NewTemplates

func NewTemplates(dir string, reload bool) Templates

NewTemplates creates a new template collection. The templates are loaded from dir on the first request or when Load() is called. When reload is true, the templates are reloaded on each request.

func (Templates) Execute

func (tpl Templates) Execute(w io.Writer, name string, data interface{}, ctxFuncs template.FuncMap) error

Execute outputs a rendered template to the Writer. If you want to stream HTML to an ResponseWriter, use HTML(..) as it sets some required headers. ctxFuncs can be used to add functions to the cloned templates, so that the original templates will not be changed (multi threading)

func (Templates) Funcs

func (tpl Templates) Funcs(funcmap template.FuncMap) Templates

Funcs adds the elements of the argument map to the template's function map. The return value is the updated template.

func (Templates) HTML

func (tpl Templates) HTML(w http.ResponseWriter, r *http.Request, code int, name string, data interface{}) error

HTML outputs a rendered HTML template to the client.

func (Templates) Load

func (tpl Templates) Load() (Templates, error)

Load loads any template from the filesystem.

type V

type V map[string]interface{}

V is a helper type to quickly build variable maps for templates.

func (V) MarshalJSON

func (v V) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.