github.com/moorereason/goa
Package goa provides the runtime support for goa microservices. goa service development begins with writing the *design* of a service. The design is described using the goa language implemented by the github.com/goadesign/goa/design/apidsl 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 RequestData and ResponseData structs, error handling via the service and controller ErrorHandler field, middleware support via the Middleware data structure as well as decoding and encoding algorithms. The RequestData and ResponseData structs provides access to the request and response state. goa request handlers also accept a golang.org/x/net/Context interface as first parameter so that deadlines and cancelation signals may easily be implemented. The request state exposes the underlying http.Request object as well as the deserialized payload (request body) and parameters (both path and querystring parameters). Generated action specific contexts wrap the context.Context, ResponseData and RequestData data structures. They expose properly typed fields that correspond to the request parameters and body data structure descriptions appearing in the design. The response state exposes the response status and body length as well as the underlying ResponseWriter. 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): The action signature generated by goagen is: where UpdateBottleContext is: and implements: The definitions of the Bottle and UpdateBottlePayload data structures are ommitted for brievity. 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.Controller which takes care of implementing the middleware and error handler 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. 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. 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. The goa design language makes it possible to specify the encodings supported by the API both as input (Consumes) and output (Produces). goagen uses that information to registed the corresponding packages with the service encoders and decoders via the SetEncoder and SetDecoder methods. The service exposes the Decode, DecodeRequest, Encode and EncodeResponse that implement a simple content type negotiation algorithm for picking the right encoder for the "Accept" request header. 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.
Readme
goa is a framework for building RESTful microservices in Go.
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.
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.
Assuming you have a working Go setup:
go get github.com/goadesign/goa/goagen
Create the file $GOPATH/src/goa-adder/design/design.go with the following content:
package design
import (
. "github.com/goadesign/goa/design"
. "github.com/goadesign/goa/design/apidsl"
)
var _ = API("adder", func() {
Title("The adder API")
Description("A teaser for goa")
Host("localhost:8080")
Scheme("http")
})
var _ = Resource("operands", func() {
Action("add", func() {
Routing(GET("add/:left/:right"))
Description("add returns the sum of the left and right parameters in the response body")
Params(func() {
Param("left", Integer, "Left operand")
Param("right", Integer, "Right operand")
})
Response(OK, "plain/text")
})
})
This file contains the design for an adder API which accepts HTTP GET requests to /add/:x/:y
where :x and :y are placeholders for integer values. The API returns the sum of x and y in
its body.
Now that the design is done, let's run goagen on the design package:
$ cd $GOPATH/src/goa-adder
$ goagen bootstrap -d goa-adder/design
This produces the following outputs:
main.go and operands.go contain scaffolding code to help bootstrap the implementation.
running goagen again does no recreate them so that it's safe to edit their content.app package which contains glue code that binds the low level HTTP server to your
implementation.client package with a Client struct that implements a AddOperands function which calls
the API with the given arguments and returns the http.Response. The client directory also
contains the complete source for a client CLI tool (see below).swagger package with implements the GET /swagger.json API endpoint. The response contains
the full Swagger specificiation of the API.First let's implement the API - edit the file operands.go and replace the content of the Add
function with:
// Add runs the add action.
func (c *OperandsController) Add(ctx *app.AddOperandsContext) error {
sum := ctx.Left + ctx.Right
return ctx.OK([]byte(strconv.Itoa(sum)))
}
Now let's compile and run the service:
$ cd $GOPATH/src/goa-adder
$ go build
$ ./goa-adder
2016/02/16 16:39:27 [INFO] mount ctrl: Operands action: Add route: GET /add/:left/:right
2016/02/16 16:39:27 [INFO] mount file filename: swagger/swagger.json path: GET /swagger.json
2016/02/16 16:39:27 [INFO] listen address: :8080
Open a new console and compile the generated CLI tool:
cd $GOPATH/src/goa-adder/client/adder-cli
go build
The tool includes contextual help:
$ ./adder-cli --help
CLI client for the adder service
Usage:
adder-cli [command]
Available Commands:
add add returns the sum of the left and right parameters in the response body
Flags:
--dump[=false]: Dump HTTP request and response.
-H, --host="localhost:8080": API hostname
--pp[=false]: Pretty print response body
-s, --scheme="http": Set the requests scheme
-t, --timeout=20s: Set the request timeout, defaults to 20s
Use "adder-cli [command] --help" for more information about a command.
$ ./adder-cli add operands --help
Usage:
adder-cli add operands [flags]
Global Flags:
--dump[=false]: Dump HTTP request and response.
-H, --host="localhost:8080": API hostname
--pp[=false]: Pretty print response body
-s, --scheme="http": Set the requests scheme
-t, --timeout=20s: Set the request timeout, defaults to 20s
Now let's run it:
$ ./adder-cli add operands /add/1/2
2016/02/16 11:04:30 [INFO] started id: fHAaZ9tx GET: http://localhost:8080/add/1/2
2016/02/16 11:04:30 [INFO] completed id: fHAaZ9tx status: 200 time: 811.575µs
3⏎
The console running the service shows the request that was just handled:
2016/02/16 16:42:01 [INFO] started app: API ctrl: operands action: Add id: FloJa8uAbm-1 GET: /add/1/2
2016/02/16 16:42:01 [INFO] params app: API ctrl: operands action: Add id: FloJa8uAbm-1 left: 1 right: 2
2016/02/16 16:42:01 [INFO] completed app: API ctrl: operands action: Add id: FloJa8uAbm-1 status: 200 bytes: 1 time: 91.858µs
Now let's see how robust our service is and try to use non integer values:
./adder-cli add operands add/1/d
2016/02/24 11:05:15 [INFO] started id: 3F1FKVRR GET: http://localhost:8080/add/1/d
2016/02/24 11:05:15 [INFO] completed id: 3F1FKVRR status: 400 time: 1.044759ms
error: 400: "[{\"id\":1,\"title\":\"invalid parameter value\",\"msg\":\"invalid value \\\"d\\\" for parameter \\\"right\\\", must be a integer\"}]"
As you can see the generated code validated the incoming request state against the types defined in the design.
The swagger directory contains the entire Swagger specification in the swagger.json file. The
specification can also be accessed through the service:
$ curl localhost:8080/swagger.json
For open source services hosted on github swagger.goa.design provides a free service that renders the Swagger representation dynamically from goa design packages.
http://goa.design contains further information on goa.
Can't wait to give it a try? the easiest way is to follow the short getting started guide.
The middleware repo provides a number of middlewares covering most common needs. It also provides a good source of examples for writing new middlewares.
The goa-cellar repo contains the implementation for a goa service which demonstrates many aspects of the design language. It is kept up-to-date and provides a reference for testing functionality.
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.
The issues contain entries tagged with help wanted: beginners which provide a great way to get started!
FAQs
Package goa provides the runtime support for goa microservices. goa service development begins with writing the *design* of a service. The design is described using the goa language implemented by the github.com/goadesign/goa/design/apidsl 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 RequestData and ResponseData structs, error handling via the service and controller ErrorHandler field, middleware support via the Middleware data structure as well as decoding and encoding algorithms. The RequestData and ResponseData structs provides access to the request and response state. goa request handlers also accept a golang.org/x/net/Context interface as first parameter so that deadlines and cancelation signals may easily be implemented. The request state exposes the underlying http.Request object as well as the deserialized payload (request body) and parameters (both path and querystring parameters). Generated action specific contexts wrap the context.Context, ResponseData and RequestData data structures. They expose properly typed fields that correspond to the request parameters and body data structure descriptions appearing in the design. The response state exposes the response status and body length as well as the underlying ResponseWriter. 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): The action signature generated by goagen is: where UpdateBottleContext is: and implements: The definitions of the Bottle and UpdateBottlePayload data structures are ommitted for brievity. 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.Controller which takes care of implementing the middleware and error handler 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. 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. 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. The goa design language makes it possible to specify the encodings supported by the API both as input (Consumes) and output (Produces). goagen uses that information to registed the corresponding packages with the service encoders and decoders via the SetEncoder and SetDecoder methods. The service exposes the Decode, DecodeRequest, Encode and EncodeResponse that implement a simple content type negotiation algorithm for picking the right encoder for the "Accept" request header. 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.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
A new report explores how advancements in LLMs are enhancing cyber threats, including polymorphic malware, personalized spearphishing, and the risk of hijacking customer service bots.
Security News
ESLint has approved an RFC that adds support for TypeScript configuration files, which is aimed at improving the developer experience and recognizing changes in the evolving JavaScript ecosystem.
Security News
The NVD is facing a significant backlog with over 12,500 CVEs awaiting analysis, and more than 50% of known exploited vulnerabilities (KEVs) left unenriched since mid-February.