goa

Overview ¶

Package goa provides the runtime support for goa web applications.

see also http://goa.design

package cors: https://godoc.org/github.com/raphael/goa/cors

package design: https://godoc.org/github.com/raphael/goa/design

package dsl: https://godoc.org/github.com/raphael/goa/design/dsl

Code Generation ¶

goa applications development begins with writing the *design* of an application. The design is described using the goa language implemented by the github.com/raphael/goa/design/dsl package. The goagen tool consumes the metadata produced from executing the DSL to generate application specific code that glues the underlying HTTP server with action specific code and data structures.

The goa package contains supporting functionality for the generated code including basic request and response state management through the Context data structure, error handling via the application ErrorHandler field, middleware support via the Middleware data structure and finally input (and output) format validation algorithms.

Request Context ¶

The Context data structure provides access to both the request and response state. It implements the golang.org/x/net/Context interface so that deadlines and cancelation signals may also be implemented with it.

The request state is accessible through the Get, GetMany and Payload methods which return the values of the request parameters, query strings and request body. Action specific contexts wrap Context and expose properly typed fields corresponding to the request parameters and body data structure descriptions appearing in the design.

The response state can be accessed through the ResponseStatus, ResponseLength and Header methods. The Context type implements the http.ResponseWriter interface and thus action contexts can be used in places http.ResponseWriter can. Action contexts provide action specific helper methods that write the responses as described in the design optionally taking an instance of the media type for responses that contain a body.

Here is an example showing an "update" action corresponding to following design (extract):

Resource("bottle", func() {
	DefaultMedia(Bottle)
	Action("update", func() {
		Params(func() {
			Param("bottleID", Integer)
		})
		Payload(UpdateBottlePayload)
		Response(OK)
		Response(NotFound)
	})
})

The action signature generated by goagen is:

type BottleController interface {
	Update(*UpdateBottleContext) error
}

where UpdateBottleContext is:

	type UpdateBottleContext struct {
        	*goa.Context
        	BottleID  int
        	Payload   *UpdateBottlePayload
	}

and implements:

func (ctx *UpdateBottleContext) OK(resp *Bottle) error
func (ctx *UpdateBottleContext) NotFound() error

The definitions of the Bottle and UpdateBottlePayload data structures are ommitted for brievity.

Error Handling ¶

The controller action methods generated by goagen such as the Update method of the BottleController interface shown above all return an error value. The application error handler function is invoked whenever the value returned by a controller action is not nil. The handler gets both the request context and the error as argument.

The default handler implementation returns a response with status code 500 containing the error message in the body. A different error handler can be specificied using the SetErrorHandler function. goa comes with an alternative error handler - the TerseErrorHandler - which also returns a response with status 500 but does not write the error message to the body of the response.

Middleware ¶

A goa middleware is a function that takes and returns a Handler. A Handler a the low level function which handles incoming HTTP requests. goagen generates the handlers code so each handler creates the action specific context and calls the controller action with it.

Middleware can be added to a goa application using the Application type Use method. goa comes with a few stock middleware that handle common needs such as logging, panic recovery or using the RequestID header to trace requests across multiple services.

Validation ¶

The goa design language documented in the dsl package makes it possible to attach validations to data structure definitions. One specific type of validation consists of defining the format that a data structure string field must follow. Example of formats include email, data time, hostnames etc. The ValidateFormat function provides the implementation for the format validation invoked from the code generated by goagen.

Package goa standardizes on structured error responses: a request that fails because of invalid input or unexpected condition produces a response that contains one or more structured error(s). Each error object has three keys: a id (number), a title and a message. The title for a given id is always the same, the intent is to provide a human friendly categorization. The message is specific to the error occurrence and provides additional details that often include contextual information (name of parameters etc.).

The basic data structure backing errors is TypedError which simply contains the id and message. Multiple errors (not just TypedError instances) can be encapsulated in a MultiError. Both TypedError and MultiError implement the error interface, the Error methods return valid JSON that can be written directly to a response body.

The code generated by goagen calls the helper functions exposed in this file when it encounters invalid data (wrong type, validation errors etc.) such as InvalidParamTypeError, InvalidAttributeTypeError etc. These methods take and return an error which is a MultiError that gets built over time. The final MultiError object then gets serialized into the response and sent back to the client. The response status code is inferred from the type wrapping the error object: a BadRequestError produces a 400 status code while any other error produce a 500. This behavior can be overridden by setting a custom ErrorHandler in the application.