fire

README

Go on Fire

An idiomatic micro-framework for building Ember.js compatible APIs with Go.

Go on Fire is built on top of the wonderful built-in http package, implements the JSON API specification through the dedicated jsonapi library, uses the very stable mgo driver for persisting resources with MongoDB and leverages the dedicated oauth2 library to provide out of the box support for OAuth2 authentication using JWT tokens.

The deliberate and tight integration of these components provides a very simple and extensible set of abstractions for rapidly building backend services for websites that use Ember.js as their frontend framework. Of course it can also be used in conjunction with any other single page application framework or as a backend for native mobile applications.

To quickly get started with building an API with Go on Fire follow the quickstart guide, read the detailed sections in this documentation and refer to the package documentation for more detailed information on the used types and methods.

License

The MIT License (MIT)

Copyright (c) 2016 Joël Gähwiler

Documentation

Index

• Constants
• func Compose(chain ...interface{}) http.Handler
• func Fatal(err error) error
• type Action
  • func (a Action) Read() bool
  • func (a Action) Write() bool
• type Callback
  • func BasicAuthorizer(credentials map[string]string) Callback
  • func DependentResourcesValidator(resources map[string]string) Callback
  • func Except(cb Callback, actions ...Action) Callback
  • func MatchingReferencesValidator(collection, reference string, matcher map[string]string) Callback
  • func ModelValidator() Callback
  • func Only(cb Callback, actions ...Action) Callback
  • func ProtectedAttributesValidator(attributes map[string]interface{}) Callback
  • func RelationshipValidator(model coal.Model, catalog *coal.Catalog, excludedFields ...string) Callback
  • func UniqueAttributeValidator(uniqueAttribute string, filters ...string) Callback
  • func VerifyReferencesValidator(references map[string]string) Callback
• type Context
  • func (c *Context) Original() (coal.Model, error)
• type Controller
• type CustomAction
• type Group
  • func NewGroup() *Group
  • func (g *Group) Add(controllers ...*Controller)
  • func (g *Group) Endpoint(prefix string) http.Handler
  • func (g *Group) Find(pluralName string) *Controller
  • func (g *Group) List() []*Controller
• type L
• type M
• type S
• type Tester
  • func NewTester(store *coal.Store, models ...coal.Model) *Tester
  • func (t *Tester) Assign(prefix string, controllers ...*Controller)
  • func (t *Tester) Clean()
  • func (t *Tester) DebugRequest(r *http.Request, rr *httptest.ResponseRecorder) string
  • func (t *Tester) FindLast(model coal.Model) coal.Model
  • func (t *Tester) Path(path string) string
  • func (t *Tester) Request(method, path string, payload string, ...)
  • func (t *Tester) RunAuthorizer(action Action, query bson.M, model coal.Model, validator Callback) error
  • func (t *Tester) RunValidator(action Action, model coal.Model, validator Callback) error
  • func (t *Tester) Save(model coal.Model) coal.Model

Constants

const NoDefault value = iota

NoDefault marks the specified field to have no default that needs to be enforced while executing the ProtectedAttributesValidator.

Functions

func Compose

func Compose(chain ...interface{}) http.Handler

Compose is a short-hand for chaining the specified middleware and handler together.

func Fatal

func Fatal(err error) error

Fatal wraps an error and marks it as fatal.

Types

type Action

type Action int

An Action describes the currently called action on the API.

const (
	List Action
	Find
	Create
	Update
	Delete
	Custom
)

All the available actions.

func (Action) Read

func (a Action) Read() bool

Read will return true when this action does only read data.

func (Action) Write

func (a Action) Write() bool

Write will return true when this action does write data.

type Callback

type Callback func(*Context) error

A Callback is called during execution of a controller.

Note: If the callback returns an error wrapped using Fatal() the API returns an InternalServerError status and the error will be logged. All other errors are serialized to an error object and returned.

func BasicAuthorizer

func BasicAuthorizer(credentials map[string]string) Callback

BasicAuthorizer authorizes requests based on a simple credentials list.

func DependentResourcesValidator

func DependentResourcesValidator(resources map[string]string) Callback

DependentResourcesValidator counts documents in the supplied collections and returns an error if some get found. This callback is meant to protect resources from breaking relations when requested to be deleted.

Dependent resources are defined by passing pairs of collections and database fields that hold the current models id:

DependentResourcesValidator(map[string]string{
	C(&Post{}): F(&Post{}, "Author"),
	C(&Comment{}): F(&Comment{}, "Author"),
})

func Except

func Except(cb Callback, actions ...Action) Callback

Except will return a callback that runs the specified callback only when none of the supplied actions match.

func MatchingReferencesValidator

func MatchingReferencesValidator(collection, reference string, matcher map[string]string) Callback

MatchingReferencesValidator compares the model with a related model and checks if certain references are shared.

The target model is defined by passing its collection and the referencing field on the current model. The matcher is defined by passing pairs of database fields on the target and current model:

MatchingReferencesValidator(C(&Blog{}), F(&Post{}, "Blog"), map[string]string{
	F(&Blog{}, "Owner"): F(&Post{}, "Owner"),
})

func ModelValidator

func ModelValidator() Callback

ModelValidator performs a validation of the model using the Validate function.

func Only

func Only(cb Callback, actions ...Action) Callback

Only will return a callback that runs the specified callback only when one of the supplied actions match.

func ProtectedAttributesValidator

func ProtectedAttributesValidator(attributes map[string]interface{}) Callback

ProtectedAttributesValidator compares protected attributes against their default (during Create) or stored value (during Update) and returns an error if they have been changed.

Attributes are defined by passing pairs of fields and default values:

ProtectedAttributesValidator(map[string]interface{}{
	F(&Post{}, "Title"): NoDefault, // can only be set during Create
	F(&Post{}, "Link"):  "",        // is fixed and cannot be changed
})

The special NoDefault value can be provided to skip the default enforcement on Create.

func RelationshipValidator

func RelationshipValidator(model coal.Model, catalog *coal.Catalog, excludedFields ...string) Callback

RelationshipValidator makes sure all relationships of a model are correct and in place. It does so by creating a DependentResourcesValidator and a VerifyReferencesValidator based on the specified model and group.

func UniqueAttributeValidator

func UniqueAttributeValidator(uniqueAttribute string, filters ...string) Callback

UniqueAttributeValidator ensures that the specified attribute of the controllers Model will remain unique among the specified filters.

The unique attribute is defines as the first argument. Filters are defined by passing a list of database fields:

UniqueAttributeValidator(F(&Blog{}, "Name"), F(&Blog{}, "Creator"))

func VerifyReferencesValidator

func VerifyReferencesValidator(references map[string]string) Callback

VerifyReferencesValidator makes sure all references in the document are existing by counting the references on the related collections.

References are defined by passing pairs of database fields and collections of models whose ids might be referenced on the current model:

VerifyReferencesValidator(map[string]string{
	F(&Comment{}, "Post"): C(&Post{}),
	F(&Comment{}, "Author"): C(&User{}),
})

The callbacks supports `bson.ObjectId', `*bson.ObjectId` and `[]bson.ObjectId` fields.

type Context

type Context struct {
	// The current action in process.
	Action Action

	// The query that will be used during List, Find, Update or Delete to fetch
	// a list of models or the specific requested model.
	//
	// On Find, Update and Delete, the "_id" key is preset to the document ID
	// while on List all field and relationship filters are preset.
	Query bson.M

	// The Model that will be saved during Create, updated during Update or
	// deleted during Delete.
	Model coal.Model

	// The sorting that will be used during List.
	Sorting []string

	// The document that will be written to the client during List, Find, Create
	// and partially Update. The JSON API endpoints to modify a resources
	// relationships do only respond with a header as no other information should
	// be changed.
	//
	// Note: The document will be set before notifiers are run.
	Response *jsonapi.Document

	// The custom action object is set when a Custom action is processed.
	CustomAction *CustomAction

	// The store that is used to retrieve and persist the model.
	Store *coal.SubStore

	// The underlying JSON API request.
	JSONAPIRequest *jsonapi.Request

	// The underlying HTTP request.
	HTTPRequest *http.Request

	// The Controller that is managing the request.
	Controller *Controller

	// The Group that received the request.
	Group *Group
	// contains filtered or unexported fields
}

A Context provides useful contextual information.

func (*Context) Original

func (c *Context) Original() (coal.Model, error)

Original will return the stored version of the model. This method is intended to be used to calculate the changed fields during an Update action. Any returned error is already marked as fatal.

Note: The method will panic if being used during any other action than Update.

type Controller

type Controller struct {
	// The model that this controller should provide (e.g. &Foo{}).
	Model coal.Model

	// Filters defines the attributes that are filterable.
	Filters []string

	// Sorters defines the attributes that are sortable.
	Sorters []string

	// The store that is used to retrieve and persist the model.
	Store *coal.Store

	// The Authorizers authorize the requested action on the requested resource
	// and are run before any models are loaded from the DB. Returned errors
	// will cause the abortion of the request with an Unauthorized status.
	//
	// The callbacks are expected to return an error if the requester should be
	// informed about him being unauthorized to access the resource or modify the
	// Context's Query attribute in such a way that only accessible resources
	// are returned. The later improves privacy as a protected resource would
	// just appear as being not found.
	Authorizers []Callback

	// The Validators are run to validate Create, Update and Delete actions after
	// the models are loaded from the DB and the changed attributes have been
	// assigned during an Update. Returned errors will cause the abortion of the
	// request with a Bad Request status.
	//
	// The callbacks are expected to validate the Model being created, updated or
	// deleted and return errors if the presented attributes or relationships
	// are invalid or do not comply with the stated requirements. The preceding
	// authorization checks should be repeated and now also include the model's
	// attributes and relationships.
	Validators []Callback

	// The Notifiers are run before the final response is written to the client
	// and provide a chance to modify the response and notify other systems
	// about the applied changes. Returned errors will cause the abortion of the
	// request with an Internal Server Error status.
	Notifiers []Callback

	// The NoList property can be set to true if the resource is only listed
	// through relationships from other resources. This is useful for
	// resources like comments that should never be listed alone.
	NoList bool

	// The ListLimit can be set to a value higher than 1 to enforce paginated
	// responses and restrain the page size to be within one and the limit.
	ListLimit uint64

	// The CollectionActions and ResourceActions are custom actions that are run
	// on the collection (e.g. "posts/delete-cache") or resource (e.g.
	// "posts/1/recover-password"). The request context is forwarded to
	// the specified callback after running the authorizers. No validators and
	// notifiers are run for the request. If the CustomResponse field is set on
	// the context, the content will be encoded and written as the response.
	//
	// Note: The HTTP method "POST" is assumed for both action types. Also it is
	// advised to not use the same identifier for a collection and resource
	// action.
	CollectionActions map[string]Callback
	ResourceActions   map[string]Callback
	// contains filtered or unexported fields
}

A Controller provides a JSON API based interface to a model.

Note: Controllers must not be modified after adding to a group.

type CustomAction

type CustomAction struct {
	// The name of the action.
	Name string

	// What type of actions that is being processed.
	CollectionAction bool
	ResourceAction   bool

	// The resource id for a resource action.
	ResourceID string

	// The payload that was received with the custom collection or resource action.
	Payload []byte

	// The response that will be written to the client while processing a custom
	// collection or resource action. If set, the value must be either a byte
	// slice for raw responses or a json.Marshal compatible object for json
	// responses.
	Response interface{}

	// CustomContentType denotes the content type of the custom action response.
	//
	// Note: This value is only considered if the response is set to a byte slice.
	ContentType string
}

CustomAction contains information to process a custom action.

type Group

type Group struct {

	// The Reporter function gets invoked by the controller with any occurring
	// fatal errors.
	Reporter func(error)
	// contains filtered or unexported fields
}

A Group manages access to multiple controllers and their interconnections.

func NewGroup

func NewGroup() *Group

NewGroup creates and returns a new group.

func (*Group) Add

func (g *Group) Add(controllers ...*Controller)

Add will add a controller to the group.

func (*Group) Endpoint

func (g *Group) Endpoint(prefix string) http.Handler

Endpoint will return an http handler that serves requests for this controller group. The specified prefix is used to parse the requests and generate urls for the resources.

func (*Group) Find

func (g *Group) Find(pluralName string) *Controller

Find will return the controller with the matching plural name if found.

func (*Group) List

func (g *Group) List() []*Controller

List will return a list of all added controllers.

type L

type L []Callback

L is a short-hand type to create a list of callbacks.

type M

type M map[string]Callback

M is a short-hand type to create a map of callbacks.

type S

type S []string

S is a short-and type to create list of strings.

type Tester

type Tester struct {
	// The store to use for cleaning the database.
	Store *coal.Store

	// The registered models.
	Models []coal.Model

	// The handler to be tested.
	Handler http.Handler

	// A path prefix e.g. 'api'.
	Prefix string

	// The header to be set on all requests and contexts.
	Header map[string]string

	// Context to be set on fake requests.
	Context context.Context
}

A Tester provides facilities to the test a fire API.

func NewTester

func NewTester(store *coal.Store, models ...coal.Model) *Tester

NewTester returns a new tester.

func (*Tester) Assign

func (t *Tester) Assign(prefix string, controllers ...*Controller)

Assign will create a controller group with the specified controllers and assign in to the Handler attribute of the tester.

func (*Tester) Clean

func (t *Tester) Clean()

Clean will remove the collections of models that have been registered and reset the header map.

func (*Tester) DebugRequest

func (t *Tester) DebugRequest(r *http.Request, rr *httptest.ResponseRecorder) string

DebugRequest returns a string of information to debug requests.

func (*Tester) FindLast

func (t *Tester) FindLast(model coal.Model) coal.Model

FindLast will return the last saved model.

func (*Tester) Path

func (t *Tester) Path(path string) string

Path returns a root prefixed path for the supplied path.

func (*Tester) Request

func (t *Tester) Request(method, path string, payload string, callback func(*httptest.ResponseRecorder, *http.Request))

Request will run the specified request against the registered handler. This function can be used to create custom testing facilities.

func (*Tester) RunAuthorizer

func (t *Tester) RunAuthorizer(action Action, query bson.M, model coal.Model, validator Callback) error

RunAuthorizer is a helper to test validators. The caller should assert the returned error of the validator, the state of the supplied model and maybe other objects in the database.

Note: Only the Action, Query, Model and Store are set since these are the only attributes an authorizer should rely on.

Note: A fake http request is set to allow access to request headers.

func (*Tester) RunValidator

func (t *Tester) RunValidator(action Action, model coal.Model, validator Callback) error

RunValidator is a helper to test validators. The caller should assert the returned error of the validator, the state of the supplied model and maybe other objects in the database.

Note: Only the Action, Model and Store attribute of the context are set since these are the only attributes a validator should rely on.

Note: A fake http request is set to allow access to request headers.

func (*Tester) Save

func (t *Tester) Save(model coal.Model) coal.Model

Save will save the specified model.