doc.go

/*
Package goa provides the runtime support for goa web applications.

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