github.com/vcabbage/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 error classes, 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 context.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. 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 handling. 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 corresponding Use methods. 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 controller action methods generated by goagen such as the Update method of the BottleController interface shown above all return an error value. goa defines an Error struct that action implementations can use to describe the content of the corresponding HTTP response. Errors can be created using error classes which are functions created via NewErrorClass. The ErrorHandler middleware maps errors to HTTP responses. Errors that are instances of the Error struct are mapped using the struct fields while other types of errors return responses with status code 500 and the error message in the body. 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 their Register methods. The service exposes the DecodeRequest and EncodeResponse that implement a simple content type negotiation algorithm for picking the right encoder for the "Content-Type" (decoder) or "Accept" (encoder) request header. Package goa standardizes on structured error responses: a request that fails because of an invalid input or an unexpected condition produces a response that contains a structured error. The error data structures returned to clients contains five fields: an ID, a code, a status, a detail and metadata. The ID is unique for the occurrence of the error, it helps correlate the content of the response with the content of the service logs. The code defines the class of error (e.g. "invalid_parameter_type") and the status the corresponding HTTP status (e.g. 400). The detail contains a message specific to the error occurrence. The metadata contains key/value pairs that provide contextual information (name of parameters, value of invalid parameter etc.). Instances of Error can be created via Error Class functions. See http://goa.design/implement/error_handling.html All instance of errors created via a error class implement the ServiceError interface. This interface is leveraged by the error handler middleware to produce the error responses. 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 return errors that get merged with any previously encountered error via the Error Merge method. The helper functions are error classes stored in global variable. This means your code can override their values to produce arbitrary error responses. goa includes an error handler middleware that takes care of mapping back any error returned by previously called middleware or action handler into HTTP responses. If the error was created via an error class then the corresponding content including the HTTP status is used otherwise an internal error is returned. Errors that bubble up all the way to the top (i.e. not handled by the error middleware) also generate an internal error response.
Readme
goa is a framework for building micro-services and REST APIs in Go using a unique design-first approach.
goa takes a different approach to building micro-services. Instead of focusing solely on helping with implementation, goa makes it possible to describe the design of an API using a simple DSL. goa then uses that description to provide specialized helper code to the implementation and to generate documentation, API clients, tests, even custom artifacts.
If DSLs are not your thing then consider this: you need to document your APIs so that clients (be it internal e.g. other services or external e.g. UIs) may consume them. Typically this requires maintaining a completely separate document (for example an OpenAPI specification). Making sure that the document stays up-to-date takes a lot of effort and at the end of the day you have to write that document - why not use a simple and clear Go DSL to do that instead?
Another aspect to consider is the need for properly designing APIs and making sure that the design choices remain consistent across the endpoints or even across multiple APIs. If the source code is the only place where design decisions are kept then not only is it impossible to maintain consistency it's also difficult to think about the design in the first place. The goa DSL makes it possible to think about the design explicitly and - since it's code - to re-use design elements for consistency.
The goa DSL 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 DSL and generates various types of
artifacts from the resulting data structures.
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 DSL can
also define validations in which case the generated code takes care of
validating the incoming request parameters and payload prior to invoking the
handler.
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.
Assuming you have a working Go setup:
go get github.com/goadesign/goa/...
goa follows Semantic Versioning which is a fancy way of saying it publishes
releases with version numbers of the form vX.Y.Z and makes sure that your code can upgrade to new
versions with the same X component without having to make changes.
Releases are tagged with the corresponding version number. There is also a branch for each major
version (only v1 at the moment). The recommended practice is to vendor the stable branch.
Current Release: v1.3.0
Stable Branch: v1
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, "text/plain")
})
})
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 not 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.tool directory that contains the complete source for a client CLI tool.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 import for strconv
import "strconv"
// 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/04/05 20:39:10 [INFO] mount ctrl=Operands action=Add route=GET /add/:left/:right
2016/04/05 20:39:10 [INFO] listen transport=http addr=:8080
Open a new console and compile the generated CLI tool:
cd $GOPATH/src/goa-adder/tool/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 Dump HTTP request and response.
-H, --host string API hostname (default "localhost:8080")
-s, --scheme string Set the requests scheme
-t, --timeout duration Set the request timeout (default 20s)
Use "adder-cli [command] --help" for more information about a command.
To get information on how to call a specific API use:
./adder-cli add operands --help
Usage:
adder-cli add operands [/add/LEFT/RIGHT] [flags]
Flags:
--left int Left operand
--pp Pretty print response body
--right int Right operand
Global Flags:
--dump Dump HTTP request and response.
-H, --host string API hostname (default "localhost:8080")
-s, --scheme string Set the requests scheme
-t, --timeout duration Set the request timeout (default 20s)
Now let's run it:
./adder-cli add operands /add/1/2
2016/04/05 20:43:18 [INFO] started id=HffVaGiH GET=http://localhost:8080/add/1/2
2016/04/05 20:43:18 [INFO] completed id=HffVaGiH status=200 time=1.028827ms
3⏎
This also works:
$ ./adder-cli add operands --left=1 --right=2
2016/04/25 00:08:59 [INFO] started id=ouKmwdWp GET=http://localhost:8080/add/1/2
2016/04/25 00:08:59 [INFO] completed id=ouKmwdWp status=200 time=1.097749ms
3⏎
The console running the service shows the request that was just handled:
2016/06/06 10:23:03 [INFO] started req_id=rLAtsSThLD-1 GET=/add/1/2 from=::1 ctrl=OperandsController action=Add
2016/06/06 10:23:03 [INFO] params req_id=rLAtsSThLD-1 right=2 left=1
2016/06/06 10:23:03 [INFO] completed req_id=rLAtsSThLD-1 status=200 bytes=1 time=66.25µ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/06/06 10:24:22 [INFO] started id=Q2u/lPUc GET=http://localhost:8080/add/1/d
2016/06/06 10:24:22 [INFO] completed id=Q2u/lPUc status=400 time=1.301083ms
error: 400: {"code":"invalid_request","status":400,"detail":"invalid value \"d\" for parameter \"right\", must be a integer"}
As you can see the generated code validated the incoming request against the types defined in the design.
The swagger directory contains the API Swagger (OpenAPI) specification in both
YAML and JSON format.
For open source projects hosted on
github swagger.goa.design provides a free service
that renders the Swagger representation dynamically from goa design packages.
Simply set the url query string with the import path to the design package.
For example displaying the docs for github.com/goadesign/goa-cellar/design is
done by browsing to:
http://swagger.goa.design/?url=goadesign%2Fgoa-cellar%2Fdesign
Note that the above generates the swagger spec dynamically and does not require it to be present in the Github repo.
The Swagger JSON can also easily be served from the documented service itself using a simple
Files
definition in the design. Edit the file design/design.go and add:
var _ = Resource("swagger", func() {
Origin("*", func() {
Methods("GET") // Allow all origins to retrieve the Swagger JSON (CORS)
})
Files("/swagger.json", "swagger/swagger.json")
})
Re-run goagen bootstrap -d goa-adder/design and note the new file
swagger.go containing the implementation for a controller that serves the
swagger.json file.
Mount the newly generated controller by adding the following two lines to the main function in
main.go:
cs := NewSwaggerController(service)
app.MountSwaggerController(service, cs)
Recompile and restart the service:
^C
go build
./goa-adder
2016/06/06 10:31:14 [INFO] mount ctrl=Operands action=Add route=GET /add/:left/:right
2016/06/06 10:31:14 [INFO] mount ctrl=Swagger files=swagger/swagger.json route=GET /swagger.json
2016/06/06 10:31:14 [INFO] listen transport=http addr=:8080
Note the new route /swagger.json. Requests made to it return the Swagger specification. The
generated controller also takes care of adding the proper CORS headers so that the JSON may be
retrieved from browsers using JavaScript served from a different origin (e.g. via Swagger UI). The
client also has a new download action:
cd tool/adder-cli
go build
./adder-cli download --help
Download file with given path
Usage:
adder-cli download [PATH] [flags]
Flags:
--out string Output file
Global Flags:
--dump Dump HTTP request and response.
-H, --host string API hostname (default "localhost:8080")
-s, --scheme string Set the requests scheme
-t, --timeout duration Set the request timeout (default 20s)
Which can be used like this to download the file swagger.json in the current directory:
./adder-cli download swagger.json
2016/06/06 10:36:24 [INFO] started file=swagger.json id=ciHL2VLt GET=http://localhost:8080/swagger.json
2016/06/06 10:36:24 [INFO] completed file=swagger.json id=ciHL2VLt status=200 time=1.013307ms
We now have a self-documenting API and best of all the documentation is automatically updated as the API design changes.
Consult the following resources to learn more about goa.
goa.design contains further information on goa including a getting started guide, detailed DSL documentation as well as information on how to implement a goa service.
The examples repo contains simple examples illustrating basic concepts.
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.
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 error classes, 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 context.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. 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 handling. 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 corresponding Use methods. 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 controller action methods generated by goagen such as the Update method of the BottleController interface shown above all return an error value. goa defines an Error struct that action implementations can use to describe the content of the corresponding HTTP response. Errors can be created using error classes which are functions created via NewErrorClass. The ErrorHandler middleware maps errors to HTTP responses. Errors that are instances of the Error struct are mapped using the struct fields while other types of errors return responses with status code 500 and the error message in the body. 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 their Register methods. The service exposes the DecodeRequest and EncodeResponse that implement a simple content type negotiation algorithm for picking the right encoder for the "Content-Type" (decoder) or "Accept" (encoder) request header. Package goa standardizes on structured error responses: a request that fails because of an invalid input or an unexpected condition produces a response that contains a structured error. The error data structures returned to clients contains five fields: an ID, a code, a status, a detail and metadata. The ID is unique for the occurrence of the error, it helps correlate the content of the response with the content of the service logs. The code defines the class of error (e.g. "invalid_parameter_type") and the status the corresponding HTTP status (e.g. 400). The detail contains a message specific to the error occurrence. The metadata contains key/value pairs that provide contextual information (name of parameters, value of invalid parameter etc.). Instances of Error can be created via Error Class functions. See http://goa.design/implement/error_handling.html All instance of errors created via a error class implement the ServiceError interface. This interface is leveraged by the error handler middleware to produce the error responses. 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 return errors that get merged with any previously encountered error via the Error Merge method. The helper functions are error classes stored in global variable. This means your code can override their values to produce arbitrary error responses. goa includes an error handler middleware that takes care of mapping back any error returned by previously called middleware or action handler into HTTP responses. If the error was created via an error class then the corresponding content including the HTTP status is used otherwise an internal error is returned. Errors that bubble up all the way to the top (i.e. not handled by the error middleware) also generate an internal error response.
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
The Python Software Foundation has secured a 5-year sponsorship from Fastly that supports PSF's activities and events, most notably the security and reliability of the Python Package Index (PyPI).
Security News
LDAPjs, an LDAP Client and Server API for Node.js, was decommissioned after its maintainer received an abusive email from a user, raising concerns about this form of abuse as a potential attack vector.
Security News
CISA launched a new project called Vulnrichment to enrich CVEs with details that help prioritize patching and mitigation efforts, as the NVD backlog of unenriched CVEs awaiting analysis surpasses 10,000.