goa

package module
v0.0.0-...-3014a84 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 20, 2015 License: MIT Imports: 28 Imported by: 0

README

goa

goa is a framework for building RESTful microservices in Go.

Build Status License Godoc Slack Intro

Why goa?

There are a number of good Go packages for writing modular web services out there so why build another one? Glad you asked! The existing packages tend to focus on providing small and highly modular frameworks that are purposefully narrowly focused. The intent is to keep things simple and to avoid mixing concerns.

This is great when writing simple APIs that tend to change rarely. However there are a number of problems that any non trivial API implementation must address. Things like request validation, response media type definitions or documentation are hard to do in a way that stays consistent and flexible as the API surface evolves.

goa takes a different approach to building web applications: instead of focusing solely on helping with implementation, goa makes it possible to describe the design of an API in an holistic way. goa then uses that description to provide specialized helper code to the implementation and to generate documentation, API clients, tests, even custom artifacts.

The goa design language allows writing self-explanatory code that describes the resources exposed by the API and for each resource the properties and actions. goa comes with the goagen tool which runs the design language and generates various types of artifacts from the resulting metadata.

One of the goagen output is glue code that binds your code with the underlying HTTP server. This code is specific to your API so that for example there is no need to cast or "bind" any handler argument prior to using them. Each generated handler has a signature that is specific to the corresponding resource action. It's not just the parameters though, each handler also has access to specific helper methods that generate the possible responses for that action. The metadata can also include validation rules so that the generated code also takes care of validating the incoming request parameters and payload prior to invoking your code.

The end result is controller code that is terse and clean, the boilerplate is all gone. Another big benefit is the clean separation of concern between design and implementation: on bigger projects it's often the case that API design changes require careful review, being able to generate a new version of the documentation without having to write a single line of implementation is a big boon.

This idea of separating design and implementation is not new, the excellent Praxis framework from RightScale follows the same pattern and was an inspiration to goa.

The Whys and Hows

If you are new to goa I can't recommend enough that you read the Gopher Academy blog post. goa may look a little bit different at first, the post explains the thinking behind it so that you can better take advantage of the framework.

Installation

Assuming you have a working Go setup:

go get github.com/raphael/goa/goagen

The code generation functionality relies on goimports:

go get golang.org/x/tools/cmd/goimports

Middlewares

goa includes a number of built-in middlewares. Additional middlewares can be found in the goa-middleware repo.

Getting Started

Can't wait to give it a try? the easiest way is to follow the short getting started guide.

Contributing

Did you fix a bug? write docs or additional tests? or implement some new awesome functionality? You're a rock star!! Just make sure that make succeeds (or that TravisCI is green) and send a PR over.

And if you're looking for inspiration the wookie contains a roadmap document with many good suggestions...

Documentation

Overview

Package goa provides the runtime support for goa web services. See also http://goa.design.

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

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

Code Generation

goa service development begins with writing the *design* of a service. 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 design language to generate service 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 service and controller ErrorHandler field, middleware support via the Middleware data structure as well as 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 {
	goa.Controller
	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.

Controllers

There is one controller interface generated per resource defined via the design language. The interface exposes the controller actions as well as methods to set controller specific middleware and error handlers (see below). User code must provide data structures that implement these interfaces when mounting a controller onto a service. The controller data structure should include an anonymous field of type *goa.ApplicationController which takes care of implementing the middleware and error handler handling.

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 controller or service-wide error handler (if no controller specific 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 on either a controller or service wide. 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 is 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 service or a specific controller using the Service 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.

Index

Constants

View Source 
const (
	// ErrInvalidParamType is the error produced by the generated code when
	// a request parameter type does not match the design.
	ErrInvalidParamType = iota + 1

	// ErrMissingParam is the error produced by the generated code when a
	// required request parameter is missing.
	ErrMissingParam

	// ErrInvalidAttributeType is the error produced by the generated
	// code when a data structure attribute type does not match the design
	// definition.
	ErrInvalidAttributeType

	// ErrMissingAttribute is the error produced by the generated
	// code when a data structure attribute required by the design
	// definition is missing.
	ErrMissingAttribute

	// ErrInvalidEnumValue is the error produced by the generated code when
	// a values does not match one of the values listed in the attribute
	// definition as being valid (i.e. not part of the enum).
	ErrInvalidEnumValue

	// ErrMissingHeader is the error produced by the generated code when a
	// required header is missing.
	ErrMissingHeader

	// ErrInvalidFormat is the error produced by the generated code when
	// a value does not match the format specified in the attribute
	// definition.
	ErrInvalidFormat

	// ErrInvalidPattern is the error produced by the generated code when
	// a value does not match the regular expression specified in the
	// attribute definition.
	ErrInvalidPattern

	// ErrInvalidRange is the error produced by the generated code when
	// a value is less than the minimum specified in the design definition
	// or more than the maximum.
	ErrInvalidRange

	// ErrInvalidLength is the error produced by the generated code when
	// a value is a slice with less elements than the minimum length
	// specified in the design definition or more elements than the
	// maximum length.
	ErrInvalidLength
)
View Source 
const (
	// FormatDateTime defines RFC3339 date time values.
	FormatDateTime Format = "date-time"

	// FormatEmail defines RFC5322 email addresses.
	FormatEmail = "email"

	// FormatHostname defines RFC1035 Internet host names.
	FormatHostname = "hostname"

	// FormatIPv4 defines RFC2373 IPv4 address values.
	FormatIPv4 = "ipv4"

	// FormatIPv6 defines RFC2373 IPv6 address values.
	FormatIPv6 = "ipv6"

	// FormatURI defines RFC3986 URI values.
	FormatURI = "uri"

	// FormatMAC defines IEEE 802 MAC-48, EUI-48 or EUI-64 MAC address values.
	FormatMAC = "mac"

	// FormatCIDR defines RFC4632 and RFC4291 CIDR notation IP address values.
	FormatCIDR = "cidr"

	// FormatRegexp Regexp defines regular expression syntax accepted by RE2.
	FormatRegexp = "regexp"
)
View Source 
const ReqIDKey middlewareKey = 0

ReqIDKey is the RequestID middleware key used to store the request ID value in the context.

View Source 
const RequestIDHeader = "X-Request-Id"

RequestIDHeader is the name of the header used to transmit the request ID.

Variables

View Source 
var (
	// Log is the global logger from which other loggers (e.g. request specific loggers) are
	// derived. Configure it by setting its handler prior to calling New.
	// See https://godoc.org/github.com/inconshreveable/log15
	Log log.Logger

	// RootContext is the root context from which all request contexts are derived.
	// Set values in the root context prior to starting the server to make these values
	// available to all request handlers:
	//
	//	goa.RootContext = goa.RootContext.WithValue(key, value)
	//
	RootContext context.Context
)
View Source 
var InterruptSignals = []os.Signal{
	os.Signal(syscall.SIGINT),
	os.Signal(syscall.SIGTERM),
	os.Signal(syscall.SIGQUIT),
}

InterruptSignals is the list of signals that initiate graceful shutdown. Note that only SIGINT is supported on Windows so this list should be overridden by the caller when running on that platform.

Functions

func Cancel 

func Cancel()

Cancel sends a cancellation signal to all handlers through the action context. see https://godoc.org/golang.org/x/net/context for details on how to handle the signal.

func DefaultErrorHandler 

func DefaultErrorHandler(c *Context, e error)

DefaultErrorHandler returns a 400 response for request validation errors (instances of BadRequestError) and a 500 response for other errors. It writes the error message to the response body in both cases.

func Fatal 

func Fatal(msg string, ctx ...interface{})

Fatal logs a critical message and exits the process with status code 1. This function is meant to be used by initialization code to prevent the application from even starting up when something is obviously wrong. In particular this function should probably not be used when serving requests.

func InvalidAttributeTypeError 

func InvalidAttributeTypeError(ctx string, val interface{}, expected string, err error) error

InvalidAttributeTypeError appends a typed error of id ErrIncompatibleType to err and returns it.

func InvalidEnumValueError 

func InvalidEnumValueError(ctx string, val interface{}, allowed []interface{}, err error) error

InvalidEnumValueError appends a typed error of id ErrInvalidEnumValue to err and returns it.

func InvalidFormatError 

func InvalidFormatError(ctx, target string, format Format, formatError, err error) error

InvalidFormatError appends a typed error of id ErrInvalidFormat to err and returns it.

func InvalidLengthError 

func InvalidLengthError(ctx string, target interface{}, ln, value int, min bool, err error) error

InvalidLengthError appends a typed error of id ErrInvalidLength to err and returns it.

func InvalidParamTypeError 

func InvalidParamTypeError(name string, val interface{}, expected string, err error) error

InvalidParamTypeError appends a typed error of id ErrInvalidParamType to err and returns it.

func InvalidPatternError 

func InvalidPatternError(ctx, target string, pattern string, err error) error

InvalidPatternError appends a typed error of id ErrInvalidPattern to err and returns it.

func InvalidRangeError 

func InvalidRangeError(ctx string, target interface{}, value int, min bool, err error) error

InvalidRangeError appends a typed error of id ErrInvalidRange to err and returns it.

func MissingAttributeError 

func MissingAttributeError(ctx, name string, err error) error

MissingAttributeError appends a typed error of id ErrMissingAttribute to err and returns it.

func MissingHeaderError 

func MissingHeaderError(name string, err error) error

MissingHeaderError appends a typed error of id ErrMissingHeader to err and returns it.

func MissingParamError 

func MissingParamError(name string, err error) error

MissingParamError appends a typed error of id ErrMissingParam to err and returns it.

func ReportError 

func ReportError(err error, err2 error) error

ReportError coerces the first argument into a MultiError then appends the second argument and returns the resulting MultiError.

func TerseErrorHandler 

func TerseErrorHandler(c *Context, e error)

TerseErrorHandler behaves like DefaultErrorHandler except that it does not set the response body for internal errors.

func ValidateFormat 

func ValidateFormat(f Format, val string) error

ValidateFormat validates a string against a standard format. It returns nil if the string conforms to the format, an error otherwise. The format specification follows the json schema draft 4 validation extension. see http://json-schema.org/latest/json-schema-validation.html#anchor105 Supported formats are: - "date-time": RFC3339 date time value - "email": RFC5322 email address - "hostname": RFC1035 Internet host name - "ipv4" and "ipv6": RFC2673 and RFC2373 IP address values - "uri": RFC3986 URI value - "mac": IEEE 802 MAC-48, EUI-48 or EUI-64 MAC address value - "cidr": RFC4632 and RFC4291 CIDR notation IP address value - "regexp": Regular expression syntax accepted by RE2

func ValidatePattern 

func ValidatePattern(p string, val string) bool

ValidatePattern returns an error if val does not match the regular expression p. It makes an effort to minimize the number of times the regular expression needs to be compiled.

Types

type Application 

type Application struct {
	log.Logger // Application logger

	Router *httprouter.Router // Application router
	// contains filtered or unexported fields
}

Application represents a goa application. At the basic level an application consists of a set of controllers, each implementing a given resource actions. goagen generates global functions - one per resource - that make it possible to mount the corresponding controller onto an application. An application contains the middleware, logger and error handler shared by all its controllers. Setting up an application might look like: 

api := goa.New("my api")
api.Use(SomeMiddleware())
rc := NewResourceController()
rc.Use(SomeOtherMiddleware())
app.MountResourceController(api, rc)
api.ListenAndServe(":80")

where NewResourceController returns an object that implements the resource actions as defined by the corresponding interface generated by goagen.

func (*Application) ErrorHandler 

func (app *Application) ErrorHandler() ErrorHandler

ErrorHandler returns the currently set error handler.

func (*Application) HTTPHandler 

func (app *Application) HTTPHandler() http.Handler

HTTPHandler returns a http.Handler to the service.

func (*Application) ListenAndServe 

func (app *Application) ListenAndServe(addr string) error

ListenAndServe starts a HTTP server and sets up a listener on the given host/port.

func (*Application) ListenAndServeTLS 

func (app *Application) ListenAndServeTLS(addr, certFile, keyFile string) error

ListenAndServeTLS starts a HTTPS server and sets up a listener on the given host/port.

func (*Application) Name 

func (app *Application) Name() string

Name returns the application name.

func (*Application) NewController 

func (app *Application) NewController(resName string) Controller

NewController returns a controller for the given resource. This method is mainly intended for use by the generated code. User code shouldn't have to call it directly.

func (*Application) ServeFiles 

func (app *Application) ServeFiles(path, filename string) error

ServeFiles replies to the request with the contents of the named file or directory. The logic for what to do when the filename points to a file vs. a directory is the same as the standard http package ServeFile function. The path may end with a wildcard that matches the rest of the URL (e.g. *filepath). If it does the matching path is appended to filename to form the full file path, so: 

ServeFiles("/index.html", "/www/data/index.html")

Returns the content of the file "/www/data/index.html" when requests are sent to "/index.html" and: 

ServeFiles("/assets/*filepath", "/www/data/assets")

returns the content of the file "/www/data/assets/x/y/z" when requests are sent to "/assets/x/y/z".

func (*Application) SetErrorHandler 

func (app *Application) SetErrorHandler(handler ErrorHandler)

SetErrorHandler defines an application wide error handler. The default error handler (DefaultErrorHandler) responds with a 500 status code and the error message in the response body. TerseErrorHandler provides an alternative implementation that does not write the error message to the response body for internal errors (e.g. for production). Set it with SetErrorHandler(TerseErrorHandler). Controller specific error handlers should be set using the Controller type SetErrorHandler method instead.

func (*Application) Use 

func (app *Application) Use(m Middleware)

Use adds a middleware to the application wide middleware chain. See NewMiddleware for wrapping goa and http handlers into goa middleware. goa comes with a set of commonly used middleware, see middleware.go. Controller specific middleware should be mounted using the Controller type Use method instead.

type ApplicationController 

type ApplicationController struct {
	log.Logger // Controller logger
	// contains filtered or unexported fields
}

ApplicationController provides the common state and behavior for generated controllers.

func (*ApplicationController) ErrorHandler 

func (ctrl *ApplicationController) ErrorHandler() ErrorHandler

ErrorHandler returns the currently set error handler.

func (*ApplicationController) HandleError 

func (ctrl *ApplicationController) HandleError(ctx *Context, err error)

HandleError invokes the controller error handler or - if there isn't one - the service error handler.

func (*ApplicationController) MiddlewareChain 

func (ctrl *ApplicationController) MiddlewareChain() []Middleware

MiddlewareChain returns the controller middleware chain.

func (*ApplicationController) NewHTTPRouterHandle 

func (ctrl *ApplicationController) NewHTTPRouterHandle(actName string, h Handler) httprouter.Handle

NewHTTPRouterHandle returns a httprouter handle from a goa handler. This handle initializes the request context by loading the request state, invokes the handler and in case of error invokes the controller (if there is one) or application error handler. This function is intended for the controller generated code. User code should not need to call it directly.

func (*ApplicationController) SetErrorHandler 

func (ctrl *ApplicationController) SetErrorHandler(handler ErrorHandler)

SetErrorHandler defines a controller specific error handler. When a controller action returns an error goa checks whether the controller is equipped with a error handler and if so calls it with the error given as argument. If there is no controller error handler then goa calls the application wide error handler instead.

func (*ApplicationController) Use 

func (ctrl *ApplicationController) Use(m Middleware)

Use adds a middleware to the controller. See NewMiddleware for wrapping goa and http handlers into goa middleware. goa comes with a set of commonly used middleware, see middleware.go.

type BadRequestError 

type BadRequestError struct {
	Actual error
}

BadRequestError is the type of errors that result in a response with status code 400.

func NewBadRequestError 

func NewBadRequestError(err error) *BadRequestError

NewBadRequestError wraps the given error into a BadRequestError.

func (*BadRequestError) Error 

func (b *BadRequestError) Error() string

Error implements error.

type BasicSigner 

type BasicSigner struct {
	// Username is the basic auth user.
	Username string
	// Password is err guess what? the basic auth password.
	Password string
}

BasicSigner implements basic auth.

func (*BasicSigner) RegisterFlags 

func (s *BasicSigner) RegisterFlags(app *kingpin.Application)

RegisterFlags adds the "--user" and "--pass" flags to the client tool.

func (*BasicSigner) Sign 

func (s *BasicSigner) Sign(req *http.Request) error

Sign adds the basic auth header to the request.

type Client 

type Client struct {
	// Logger is the logger used to log client requests.
	log15.Logger
	// Client is the underlying http client.
	*http.Client
	// Signers contains the ordered list of request signers. A signer may add headers,
	// cookies etc. to a request generally to perform auth.
	Signers []Signer
	// Scheme is the HTTP scheme used to make requests to the API host.
	Scheme string
	// Host is the service hostname.
	Host string
	// UserAgent is the user agent set in requests made by the client.
	UserAgent string
	// Dump indicates whether to dump request response.
	Dump bool
}

Client is the command client data structure for all goa service clients.

func NewClient 

func NewClient() *Client

NewClient create a new API client.

func (*Client) Do 

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do wraps the underlying http client Do method and adds logging.

type Context 

type Context struct {
	context.Context // Underlying context
	log.Logger      // Context logger
}

Context is the object that provides access to the underlying HTTP request and response state. Context implements http.ResponseWriter and also provides helper methods for writing HTTP responses. It also implements the context.Context interface described at http://blog.golang.org/context.

func NewContext 

func NewContext(gctx context.Context,
	req *http.Request,
	rw http.ResponseWriter,
	params map[string]string,
	query map[string][]string,
	payload interface{}) *Context

NewContext builds a goa context from the given context.Context and request state. If gctx is nil then context.Background is used instead.

func (*Context) BadRequest 

func (ctx *Context) BadRequest(err *BadRequestError) error

BadRequest sends a HTTP response with status code 400 and the given error as body.

func (*Context) Bug 

func (ctx *Context) Bug(format string, a ...interface{}) error

Bug sends a HTTP response with status code 500 and the given body. The body can be set using a format and substituted values a la fmt.Printf.

func (*Context) Get 

func (ctx *Context) Get(name string) (string, bool)

Get returns the param or query string with the given name and true or an empty string and false if there isn't one.

func (*Context) GetMany 

func (ctx *Context) GetMany(name string) []string

GetMany returns the query string values with the given name or nil if there aren't any.

func (*Context) Header 

func (ctx *Context) Header() http.Header

Header returns the response header. It implements the http.ResponseWriter interface.

func (*Context) JSON 

func (ctx *Context) JSON(code int, body interface{}) error

JSON serializes the given body into JSON and sends a HTTP response with the given status code and JSON as body.

func (*Context) Payload 

func (ctx *Context) Payload() interface{}

Payload returns the deserialized request body or nil if body is empty.

func (*Context) Request 

func (ctx *Context) Request() *http.Request

Request returns the underlying HTTP request.

func (*Context) Respond 

func (ctx *Context) Respond(code int, body []byte) error

Respond writes the given HTTP status code and response body. This method should only be called once per request.

func (*Context) ResponseLength 

func (ctx *Context) ResponseLength() int

ResponseLength returns the response body length in bytes if the response was written to the context via one of the response methods (Respond, JSON, BadRequest, Bug), 0 otherwise.

func (*Context) ResponseStatus 

func (ctx *Context) ResponseStatus() int

ResponseStatus returns the response status if it was set via one of the context response methods (Respond, JSON, BadRequest, Bug), 0 otherwise.

func (*Context) ResponseWritten 

func (ctx *Context) ResponseWritten() bool

ResponseWritten returns true if an HTTP response was written.

func (*Context) SetValue 

func (ctx *Context) SetValue(key, val interface{})

SetValue sets the value associated with key in the context. The value can be retrieved using the Value method. Note that this changes the underlying context.Context object and thus clients holding a reference to that won't be able to access the new value. It's probably a bad idea to hold a reference to the inner context anyway...

func (*Context) Write 

func (ctx *Context) Write(body []byte) (int, error)

Write writes the HTTP response body. It implements the http.ResponseWriter interface.

func (*Context) WriteHeader 

func (ctx *Context) WriteHeader(code int)

WriteHeader writes the HTTP status code to the response. It implements the http.ResponseWriter interface.

type Controller 

type Controller interface {
	// Use adds a middleware to the controller middleware chain.
	// It is a convenient method for doing append(ctrl.MiddlewareChain(), m)
	Use(Middleware)
	// MiddlewareChain returns the controller middleware chain including the
	// service-wide middleware.
	MiddlewareChain() []Middleware
	// ErrorHandler returns the currently set error handler.
	ErrorHandler() ErrorHandler
	// SetErrorHandler sets the controller specific error handler.
	SetErrorHandler(ErrorHandler)
	// NewHTTPRouterHandle returns a httprouter handle from a goa handler.
	// This function is intended for the controller generated code.
	// User code should not need to call it directly.
	NewHTTPRouterHandle(actName string, h Handler) httprouter.Handle
}

Controller is the interface implemented by all goa controllers. A controller implements a given resource actions. There is a one-to-one relationship between designed resources and generated controllers. Controllers may override the service wide error handler and be equipped with controller specific middleware.

type ErrorHandler 

type ErrorHandler func(*Context, error)

ErrorHandler defines the application error handler signature.

type ErrorID 

type ErrorID int

ErrorID is an enum listing the possible types of errors.

func (ErrorID) Title 

func (k ErrorID) Title() string

Title returns a human friendly error title

type Format 

type Format string

Format defines a validation format.

type GracefulApplication 

type GracefulApplication struct {
	*Application
	sync.Mutex

	// Interrupted is true if the application is in the process of shutting down.
	Interrupted bool
	// contains filtered or unexported fields
}

GracefulApplication is a goa application using a graceful shutdown server. When sending any of the signals listed in InterruptSignals to the process GracefulApplication:

* disables keepalive connections.

* closes the listening socket, allowing another process to listen on that port immediately.

* calls Cancel, signaling all active handlers.

func (*GracefulApplication) ListenAndServe 

func (gapp *GracefulApplication) ListenAndServe(addr string) error

ListenAndServe starts the HTTP server and sets up a listener on the given host/port.

func (*GracefulApplication) ListenAndServeTLS 

func (gapp *GracefulApplication) ListenAndServeTLS(addr, certFile, keyFile string) error

ListenAndServeTLS starts a HTTPS server and sets up a listener on the given host/port.

func (*GracefulApplication) Shutdown 

func (gapp *GracefulApplication) Shutdown() bool

Shutdown initiates graceful shutdown of the running server once. Returns true on initial shutdown and false if already shutting down.

type Handler 

type Handler func(*Context) error

Handler defines the controller handler signatures. Controller handlers accept a context and return an error. The context provides typed access to the request and response state. It implements the golang.org/x/net/context package Context interface so that handlers may define deadlines and cancelation signals - see the Timeout middleware as an example. If a controller handler returns an error then the application error handler is invoked with the request context and the error. The error handler is responsible for writing the HTTP response. See DefaultErrorHandler and TerseErrorHandler.

type JWTSigner 

type JWTSigner struct {
	// Header is the name of the HTTP header which contains the JWT.
	// The default is "Authentication"
	Header string
	// Format represents the format used to render the JWT.
	// The default is "Bearer %s"
	Format string
	// contains filtered or unexported fields
}

JWTSigner implements JSON Web Token auth.

func (*JWTSigner) RegisterFlags 

func (s *JWTSigner) RegisterFlags(app *kingpin.Application)

RegisterFlags adds the "--jwt" flag to the client tool.

func (*JWTSigner) Sign 

func (s *JWTSigner) Sign(req *http.Request) error

Sign adds the JWT auth header.

type Middleware 

type Middleware func(Handler) Handler

Middleware represents the canonical goa middleware signature.

func LogRequest 

func LogRequest() Middleware

LogRequest creates a request logger middleware. This middleware is aware of the RequestID middleware and if registered after it leverages the request ID for logging.

func NewMiddleware 

func NewMiddleware(m interface{}) (mw Middleware, err error)

NewMiddleware creates a middleware from the given argument. The allowed types for the argument are:

- a goa middleware: goa.Middleware or func(goa.Handler) goa.Handler

- a goa handler: goa.Handler or func(*goa.Context) error

- an http middleware: func(http.Handler) http.Handler

- or an http handler: http.Handler or func(http.ResponseWriter, *http.Request)

An error is returned if the given argument is not one of the types above.

func Recover 

func Recover() Middleware

Recover is a middleware that recovers panics and returns an internal error response.

func RequestID 

func RequestID() Middleware

RequestID is a middleware that injects a request ID into the context of each request. Retrieve it using ctx.Value(ReqIDKey). If the incoming request has a RequestIDHeader header then that value is used else a random value is generated.

func RequireHeader 

func RequireHeader(
	pathPattern *regexp.Regexp,
	requiredHeaderName string,
	requiredHeaderValue *regexp.Regexp,
	failureStatus int) Middleware

RequireHeader requires a request header to match a value pattern. If the header is missing or does not match then the failureStatus is the response (e.g. http.StatusUnauthorized). If pathPattern is nil then any path is included. If requiredHeaderValue is nil then any value is accepted so long as the header is non-empty.

func Timeout 

func Timeout(timeout time.Duration) Middleware

Timeout sets a global timeout for all controller actions. The timeout notification is made through the context, it is the responsability of the request handler to handle it. For example: 

func (ctrl *Controller) DoLongRunningAction(ctx *DoLongRunningActionContext) error {
	action := NewLongRunning()      // setup long running action
	c := make(chan error, 1)        // create return channel
	go func() { c <- action.Run() } // Launch long running action goroutine
	select {
	case <- ctx.Done():             // timeout triggered
		action.Cancel()         // cancel long running action
		<-c                     // wait for Run to return.
		return ctx.Err()        // retrieve cancel reason
	case err := <-c:   		// action finished on time
		return err  		// forward its return value
	}
}

Package golang.org/x/net/context/ctxhttp contains an implementation of an HTTP client which is context-aware: 

func (ctrl *Controller) HttpAction(ctx *HttpActionContext) error {
	req, err := http.NewRequest("GET", "http://iamaslowservice.com", nil)
	// ...
	resp, err := ctxhttp.Do(ctx, nil, req) // returns if timeout triggers
	// ...
}

Controller actions can check if a timeout is set by calling the context Deadline method.

type MultiError 

type MultiError []error

MultiError records multiple errors.

func (MultiError) Error 

func (m MultiError) Error() string

Error summarizes all the underlying error messages in one JSON array.

type OAuth2Signer 

type OAuth2Signer struct {
	// RefreshURLFormat is a format that generates the refresh access token URL given a
	// refresh token.
	RefreshURLFormat string
	// RefreshToken contains the OAuth2 refresh token from which access tokens are
	// created.
	RefreshToken string
	// contains filtered or unexported fields
}

OAuth2Signer enables the use of OAuth2 refresh tokens. It takes care of creating access tokens given a refresh token and a refresh URL as defined in RFC 6749. Note that this signer does not concern itself with generating the initial refresh token, this has to be done prior to using the client. Also it assumes the response of the refresh request response is JSON encoded and of the form: 

{
	"access_token":"2YotnFZFEjr1zCsicMWpAA",
	"expires_in":3600,
	"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

where the "expires_in" and "refresh_token" properties are optional and additional properties are ignored. If the response contains a "expires_in" property then the signer takes care of making refresh requests prior to the token expiration.

func (*OAuth2Signer) Refresh 

func (s *OAuth2Signer) Refresh() error

Refresh makes a OAuth2 refresh access token request.

func (*OAuth2Signer) RegisterFlags 

func (s *OAuth2Signer) RegisterFlags(app *kingpin.Application)

RegisterFlags adds the "--refreshURL" and "--refreshToken" flags to the client tool.

func (*OAuth2Signer) Sign 

func (s *OAuth2Signer) Sign(req *http.Request) error

Sign refreshes the access token if needed and adds the OAuth header.

type Service 

type Service interface {
	// Logging methods, configure the log handler using the Logger global variable.
	log.Logger

	// Name is the name of the goa application.
	Name() string

	// ErrorHandler returns the currently set error handler, useful for middleware.
	ErrorHandler() ErrorHandler
	// SetErrorHandler allows setting the service-wide error handler.
	SetErrorHandler(ErrorHandler)

	// Use adds a middleware to the service-wide middleware chain.
	Use(m Middleware)

	// ListenAndServe starts a HTTP server on the given port.
	ListenAndServe(addr string) error
	// ListenAndServeTLS starts a HTTPS server on the given port.
	ListenAndServeTLS(add, certFile, keyFile string) error
	// ServeFiles replies to the request with the contents of the named file or
	// directory. The logic // for what to do when the filename points to a file vs. a
	// directory is the same as the standard http package ServeFile function. The path
	// may end with a wildcard that matches the rest of the URL (e.g. *filepath). If it
	// does the matching path is appended to filename to form the full file path, so:
	// 	ServeFiles("/index.html", "/www/data/index.html")
	// Returns the content of the file "/www/data/index.html" when requests are sent to
	// "/index.html" and:
	//	ServeFiles("/assets/*filepath", "/www/data/assets")
	// returns the content of the file "/www/data/assets/x/y/z" when requests are sent
	// to "/assets/x/y/z".
	ServeFiles(path, filename string) error
	// HTTPHandler returns a http.Handler interface to the underlying service.
	// Note: using the handler directly bypasses the graceful shutdown behavior of
	// services instantiated with NewGraceful.
	HTTPHandler() http.Handler

	// NewController returns a controller for the resource with the given name.
	// This method is mainly intended for use by generated code.
	NewController(resName string) Controller
}

Service is the interface implemented by all goa services. It provides methods for configuring a service and running it.

func New 

func New(name string) Service

New instantiates an application with the given name.

func NewGraceful 

func NewGraceful(name string) Service

NewGraceful returns a goa application that uses a graceful shutdown server.

type Signer 

type Signer interface {
	// Sign adds required headers, cookies etc.
	Sign(*http.Request) error
	// RegisterFlags registers the command line flags that defines the values used to
	// initialize the signer.
	RegisterFlags(app *kingpin.Application)
}

Signer is the common interface implemented by all signers.

type TypedError 

type TypedError struct {
	ID   ErrorID
	Mesg string
}

TypedError describes an error that can be returned in a HTTP response.

func (*TypedError) Error 

func (t *TypedError) Error() string

Error builds an error message from the typed error details.

func (*TypedError) MarshalJSON 

func (t *TypedError) MarshalJSON() ([]byte, error)

MarshalJSON implements the json marshaler interface.

Source Files

View all Source files

Directories

Path Synopsis
Package design defines types which describe the data types used by action controllers.
 Package design defines types which describe the data types used by action controllers.
dsl
Package dsl implements the goa design language.
 Package dsl implements the goa design language.
dsl/test
Package test contains a self-contained DSL test.
 Package test contains a self-contained DSL test.
Package examples is a dummy package whose only purpose is to allow writing tests that validate the correctness of the examples
 Package examples is a dummy package whose only purpose is to allow writing tests that validate the correctness of the examples
cellar
cellar/app
cellar/client
cellar/client/cellar-cli
cellar/controllers
cellar/design
cellar/js
cellar/schema
cellar/swagger
codegen
Package codegen contains common code used by all code generators.
 Package codegen contains common code used by all code generators.
gen_app
gen_client
Package genclient provides a generator for the client tool and package of a goa application.
 Package genclient provides a generator for the client tool and package of a goa application.
gen_gen
Package gengen provides goagen with the ability to run user provided generators (*plugins*).
 Package gengen provides goagen with the ability to run user provided generators (*plugins*).
gen_js
Package genjs provides a goa generator for a javascript client module.
 Package genjs provides a goa generator for a javascript client module.
gen_main
Package genmain provides a generator for a skeleton goa application.
 Package genmain provides a generator for a skeleton goa application.
gen_schema
Package genschema provides a generator for the JSON schema controller.
 Package genschema provides a generator for the JSON schema controller.
gen_swagger
Package genswagger provides a generator for the JSON swagger controller.
 Package genswagger provides a generator for the JSON swagger controller.
meta
Package meta is used to bootstrap the code generator.
 Package meta is used to bootstrap the code generator.
utils

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.