goa

README

Goa is a framework for building micro-services and APIs in Go using a unique design-first approach.

---

Overview

Goa takes a different approach to building services by making it possible to describe the design of the service API using a simple Go DSL. goa uses the description to generate specialized service helper code, client code and documentation. Goa is extensible via plugins, for example the goakit plugin generates code that leverage the go-kit library.

The service design describes the transport independent layer of the services in the form of simple methods that accept a context and a payload and return a result and an error. The design also describes how the payloads, results and errors are serialized in the transport (HTTP or gRPC). For example a service method payload may be built from an HTTP request by extracting values from the request path, headers and body. This clean separation of layers makes it possible to expose the same service using multiple transports. It also promotes good design where the service business logic concerns are expressed and implemented separately from the transport logic.

The Goa DSL consists of Go functions so that it may be extended easily to avoid repetition and promote standards. The design code itself can easily be shared across multiple services by simply importing the corresponding Go package again promoting reuse and standardization across services.

Code Generation

The Goa tool accepts the Go design package import path as input and produces the interface as well as the glue that binds the service and client code with the underlying transport. The code is specific to the API so that for example there is no need to cast or "bind" any data structure prior to using the request payload or response result. The design may define validations in which case the generated code takes care of validating the incoming request payload prior to invoking the service method on the server, and validating the response prior to invoking the client code.

Installation

Assuming you have a working Go setup:

go get -u goa.design/goa/...

Vendoring

Since goa generates and compiles code vendoring tools are not able to automatically identify all the dependencies. In particular the generator package is only used by the generated code. To alleviate this issue simply add goa.design/goa/codegen/generator as a required package to the vendor manifest. For example if you are using dep add the following line to Gopkg.toml:

required = ["goa.design/goa/codegen/generator"]

Stable Versions

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 (v1 and v2). The recommended practice is to vendor the stable branch.

Current Release: v2.0.0-wip

Teaser

1. Design

Create the file $GOPATH/src/calcsvc/design/design.go with the following content:

package design

import . "goa.design/goa/dsl"

// API describes the global properties of the API server.
var _ = API("calc", func() {
        Title("Calculator Service")
        Description("HTTP service for adding numbers, a goa teaser")
        Server("calc", func() {
		Host("localhost", func() { URI("http://localhost:8088") })
        })
})

// Service describes a service
var _ = Service("calc", func() {
        Description("The calc service performs operations on numbers")
        // Method describes a service method (endpoint)
        Method("add", func() {
                // Payload describes the method payload
                // Here the payload is an object that consists of two fields
                Payload(func() {
                        // Attribute describes an object field
                        Attribute("a", Int, "Left operand")
                        Attribute("b", Int, "Right operand")
                        // Both attributes must be provided when invoking "add"
                        Required("a", "b")
                })
                // Result describes the method result
                // Here the result is a simple integer value
                Result(Int)
                // HTTP describes the HTTP transport mapping
                HTTP(func() {
                        // Requests to the service consist of HTTP GET requests
                        // The payload fields are encoded as path parameters
                        GET("/add/{a}/{b}")
                        // Responses use a "200 OK" HTTP status
                        // The result is encoded in the response body
                        Response(StatusOK)
                })
        })
})

This file contains the design for a calc service which accepts HTTP GET requests to /add/{a}/{b} where {a} and {b} are placeholders for integer values. The API returns the sum of a and b in the HTTP response body.

2. Implement

Now that the design is done, let's run goa on the design package:

cd $GOPATH/src/calcsvc
goa gen calcsvc/design

This produces a gen directory with the following directory structure:

gen
├── calc
│   ├── client.go
│   ├── endpoints.go
│   └── service.go
└── http
    ├── calc
    │   ├── client
    │   │   ├── cli.go
    │   │   ├── client.go
    │   │   ├── encode_decode.go
    │   │   ├── paths.go
    │   │   └── types.go
    │   └── server
    │       ├── encode_decode.go
    │       ├── paths.go
    │       ├── server.go
    │       └── types.go
    ├── cli
    │   └── calc
    │       └── cli.go
    ├── openapi.json
    └── openapi.yaml

7 directories, 15 files

• calc contains the service endpoints and interface as well as a service client.
• http contains the HTTP transport layer. This layer maps the service endpoints to HTTP handlers server side and HTTP client methods client side. The http directory also contains a complete OpenAPI 2.0 spec of the service.

The goa tool can also generate example implementations for both the service and client. These examples provide a good starting point:

goa example calcsvc/design

calc.go
cmd/calc-cli/http.go
cmd/calc-cli/main.go
cmd/calc/http.go
cmd/calc/main.go

The tool generated the main functions for two commands: one that runs the server and one the client. The tool also generated a dummy service implementation that prints a log message. Again note that the example command is intended to generate just that: an example, in particular it is not intended to be re-run each time the design changes (as opposed to the gen command which should be re-run each time the design changes).

Let's implement our service by providing a proper implementation for the add method. goa generated a payload struct for the add method that contains both fields. goa also generated the transport layer that takes care of decoding the request so all we have to do is to perform the actual sum. Edit the file calc.go and change the code of the add function as follows:

// Add returns the sum of attributes a and b of p.
func (s *calcsrvc) Add(ctx context.Context, p *calcsvc.AddPayload) (res int, err error) {
        return p.A + p.B, nil
}

That's it! we have now a full-fledged HTTP service with a corresponding OpenAPI specification and a client tool.

3. Run

Now let's compile and run the service:

cd $GOPATH/src/calcsvc/cmd/calc
go build
./calc
[calcapi] 16:10:47 HTTP "Add" mounted on GET /add/{a}/{b}
[calcapi] 16:10:47 HTTP server listening on "localhost:8088"

Open a new console and compile the generated CLI tool:

cd $GOPATH/src/calcsvc/cmd/calc-cli
go build

and run it:

./calc-cli calc add -a 1 -b 2
3

The tool includes contextual help:

./calc-cli --help

Help is also available on each command:

./calc-cli calc add --help

Now let's see how robust our code is and try to use non integer values:

./calc-cli calc add -a 1 -b foo
invalid value for b, must be INT
run './calccli --help' for detailed usage.

The generated code validates the command line arguments against the types defined in the design. The server also validates the types when decoding incoming requests so that your code only has to deal with the business logic.

4. Document

The http directory contains the OpenAPI 2.0 specification in both YAML and JSON format.

The specification can easily be served from the service itself using a file server. The Files DSL function makes it possible to server static file. Edit the file design/design.go and add:

var _ = Service("openapi", func() {
        // Serve the file with relative path ../../gen/http/openapi.json for
        // requests sent to /swagger.json.
        Files("/swagger.json", "../../gen/http/openapi.json")
})

Re-run goa gen calcsvc/design and note the new directory gen/openapi and gen/http/openapi which contain the implementation for a HTTP handler that serves the openapi.json file.

All we need to do is mount the handler on the service mux. Add the corresponding import statement to cmd/calc/http.go:

import openapisvr "calcsvc/gen/http/openapi/server"

and mount the handler by adding the following line in the same file and after the mux creation (e.g. one the line after the // Configure the mux. comment):

openapisvr.Mount(mux)

That's it! we now have a self-documenting service. Stop the running service with CTRL-C. Rebuild and re-run it then make requests to the newly added /swagger.json endpoint:

^C[calcapi] 16:17:37 exiting (interrupt)
[calcapi] 16:17:37 shutting down HTTP server at "localhost:8088"
[calcapi] 16:17:37 exited
go build
./calc

In a different console:

curl localhost:8088/swagger.json
{"swagger":"2.0","info":{"title":"Calculator Service","description":...

Resources

Consult the following resources to learn more about goa.

Docs

The Getting Started Guide is a great place to start.

There is also a FAQ and a document describing error handling.

If you are coming from v1 you may also want to read the Upgrading document.

Examples

The examples directory contains simple examples illustrating basic concepts.

Contributing

See CONTRIBUTING.

Documentation

Overview

Package goa implements a Go framework for writing microservices that promotes best practice by providing a single source of truth from which server code, client code, and documentation is derived. The code generated by goa follows the clean architecture pattern where composable modules are generated for the transport, endpoint, and business logic layers. The goa package contains middleware, plugins, and other complementary functionality that can be leveraged in tandem with the generated code to implement complete microservices in an efficient manner. By using goa for developing microservices, implementers don’t have to worry with the documentation getting out of sync from the implementation as goa takes care of generating OpenAPI specifications for HTTP based services and gRPC protocol buffer files for gRPC based services (or both if the service supports both transports). Reviewers can also be assured that the implementation follows the documentation as the code is generated from the same source.

Visit https://goa.design for more information.

Index

• Constants
• func DecodePayloadError(msg string) error
• func InvalidEnumValueError(name string, val interface{}, allowed []interface{}) error
• func InvalidFieldTypeError(name string, val interface{}, expected string) error
• func InvalidFormatError(name, target string, format Format, formatError error) error
• func InvalidLengthError(name string, target interface{}, ln, value int, min bool) error
• func InvalidPatternError(name, target string, pattern string) error
• func InvalidRangeError(name string, target interface{}, value interface{}, min bool) error
• func MergeErrors(err, other error) error
• func MissingFieldError(name, context string) error
• func MissingPayloadError() error
• func NewErrorID() string
• func ValidateFormat(name string, val string, f Format) error
• func ValidatePattern(name, val, p string) error
• type Endpoint
• type Format
• type ServiceError
  • func Fault(format string, v ...interface{}) *ServiceError
  • func PermanentError(name, format string, v ...interface{}) *ServiceError
  • func PermanentTimeoutError(name, format string, v ...interface{}) *ServiceError
  • func TemporaryError(name, format string, v ...interface{}) *ServiceError
  • func TemporaryTimeoutError(name, format string, v ...interface{}) *ServiceError
  • func (s *ServiceError) Error() string
  • func (s *ServiceError) ErrorName() string

Constants

const (
	// MethodKey is the request context key used to store the name of the
	// method as defined in the design. The generated transport code
	// initializes the corresponding value prior to invoking the endpoint.
	MethodKey contextKey = iota + 1

	// ServiceKey is the request context key used to store the name of the
	// service as defined in the design. The generated transport code
	// initializes the corresponding value prior to invoking the endpoint.
	ServiceKey
)

const (
	// FormatDate describes RFC3339 date values.
	FormatDate Format = "date"

	// FormatDateTime describes RFC3339 date time values.
	FormatDateTime Format = "date-time"

	// FormatUUID describes RFC4122 UUID values.
	FormatUUID = "uuid"

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

	// FormatHostname describes RFC1035 Internet hostnames.
	FormatHostname = "hostname"

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

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

	// FormatIP describes RFC2373 IPv4 or IPv6 address values.
	FormatIP = "ip"

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

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

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

	// FormatRegexp describes regular expression syntax accepted by RE2.
	FormatRegexp = "regexp"

	// FormatJSON describes JSON text.
	FormatJSON = "json"

	// FormatRFC1123 describes RFC1123 date time values.
	FormatRFC1123 = "rfc1123"
)

Functions

func DecodePayloadError

func DecodePayloadError(msg string) error

DecodePayloadError is the error produced by the generated code when a request body cannot be decoded successfully.

func InvalidEnumValueError

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

InvalidEnumValueError is the error produced by the generated code when the value of a payload field does not match one the values defined in the design Enum validation.

func InvalidFieldTypeError

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

InvalidFieldTypeError is the error produced by the generated code when the type of a payload field does not match the type defined in the design.

func InvalidFormatError

func InvalidFormatError(name, target string, format Format, formatError error) error

InvalidFormatError is the error produced by the generated code when the value of a payload field does not match the format validation defined in the design.

func InvalidLengthError

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

InvalidLengthError is the error produced by the generated code when the value of a payload field does not match the length validation defined in the design.

func InvalidPatternError

func InvalidPatternError(name, target string, pattern string) error

InvalidPatternError is the error produced by the generated code when the value of a payload field does not match the pattern validation defined in the design.

func InvalidRangeError

func InvalidRangeError(name string, target interface{}, value interface{}, min bool) error

InvalidRangeError is the error produced by the generated code when the value of a payload field does not match the range validation defined in the design. value may be an int or a float64.

func MergeErrors

func MergeErrors(err, other error) error

MergeErrors updates an error by merging another into it. It first converts other into a ServiceError if not already one. The merge algorithm then:

* uses the name of err if a ServiceError, the name of other otherwise.

* appends both error messages.

* computes Timeout and Temporary by "and"ing the fields of both errors.

Merge returns the updated error. This makes it possible to return other when err is nil.

func MissingFieldError

func MissingFieldError(name, context string) error

MissingFieldError is the error produced by the generated code when a payload is missing a required field.

func MissingPayloadError

func MissingPayloadError() error

MissingPayloadError is the error produced by the generated code when a request is missing a required payload.

func NewErrorID

func NewErrorID() string

NewErrorID creates a unique 8 character ID that is well suited to use as an error identifier.

func ValidateFormat

func ValidateFormat(name string, val string, f Format) error

ValidateFormat validates val against f. It returns nil if the string conforms to the format, an error otherwise. name is the name of the variable used in error messages. where in a data structure the error occurred if any. 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": RFC3339 date value
• "date-time": RFC3339 date time value
• "email": RFC5322 email address
• "hostname": RFC1035 Internet host name
• "ipv4", "ipv6", "ip": 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
• "rfc1123": RFC1123 date time value

func ValidatePattern

func ValidatePattern(name, val, p string) error

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. name is the name of the variable used in error messages.

Types

type Endpoint

type Endpoint func(ctx context.Context, request interface{}) (response interface{}, err error)

Endpoint exposes service methods to remote clients independently of the underlying transport.

type Format

type Format string

Format defines a validation format.

type ServiceError

type ServiceError struct {
	// Name is a name for that class of errors.
	Name string
	// ID is a unique value for each occurrence of the error.
	ID string
	// Message contains the specific error details.
	Message string
	// Is the error a timeout?
	Timeout bool
	// Is the error temporary?
	Temporary bool
	// Is the error a server-side fault?
	Fault bool
}

ServiceError is the default error type used by the goa package to encode and decode error responses.

func Fault

func Fault(format string, v ...interface{}) *ServiceError

Fault creates an error given a format and values a la fmt.Printf. The error has the Fault field set to true.

func PermanentError

func PermanentError(name, format string, v ...interface{}) *ServiceError

PermanentError creates an error given a name and a format and values a la fmt.Printf.

func PermanentTimeoutError

func PermanentTimeoutError(name, format string, v ...interface{}) *ServiceError

PermanentTimeoutError creates an error given a name and a format and values a la fmt.Printf. The error has the Timeout field set to true.

func TemporaryError

func TemporaryError(name, format string, v ...interface{}) *ServiceError

TemporaryError is an error class that indicates that the error is temporary and that retrying the request may be successful. TemporaryError creates an error given a name and a format and values a la fmt.Printf. The error has the Temporary field set to true.

func TemporaryTimeoutError

func TemporaryTimeoutError(name, format string, v ...interface{}) *ServiceError

TemporaryTimeoutError creates an error given a name and a format and values a la fmt.Printf. The error has both the Timeout and Temporary fields set to true.

func (*ServiceError) Error

func (s *ServiceError) Error() string

Error returns the error message.

func (*ServiceError) ErrorName

func (s *ServiceError) ErrorName() string

ErrorName returns the error name.