Blog Entries


OneOf: Union Attributes in Goa

Goa v3.7.0: Union Attributes in Goa

Goa v3.7.0 adds the ability to define union attributes in the Goa DSL. Union attributes enumerate multiple potential attribute values for a single type attribute.

Union attributes are defined using the new OneOf function. OneOf may be used wherever Attribute or Field can be used, for example:

var Dog = Type("Dog", func() {
    Description("Dogs are cool")
    Field(1, "Name")
    Field(2, "Breed")
    Required("Name", "Breed")
})

var Cat = Type("Cat", func() {
    Description("Cats are cool too")
    Field(1, "Name")
    Field(2, "Age", Int)
    Required("Name", "Age")
})

var PetOwner = Type("PetOwner", func() {
    Description("A pet owner")
    OneOf("pet", func() {
        Description("The owner's pet")
        Field(1, "dog", Dog)
        Field(2, "cat", Cat)
    })
})

Union attributes are generated as Go interfaces that implement a private method. Each potential attribute type implements the private method thereby guaranteeing that only attributes with these types may be used to assign a value to the corresponding field.


Goa v3.6.0

Go v3.6.0 is out! There were many bug fixes made in the past 6 months (since 3.5.0), see the complete list on GitHub. v3.6.0 also brings many new features and improvements.

New Features

Multi-Server Mounting

The newly generated Use function on the generated HTTP server structs makes it possible to mount multiple servers at the same time on the same underlying muxer (PR 2974).

// Doing
s := goahttp.Server{s1, s2, s3}
s.Use(httpmiddleware.RequestID())
s.Mount(mux)

// Instead of
s := goahttp.Server{s1, s2, s3}
s.Use(httpmiddleware.RequestID())

server1.Mount(mux, s1)
server2.Mount(mux, s2)
server3.Mount(mux, s3)

Contributor: Ernesto Jiménez


Goa v3.2.0

I am very excited to announce the release of Goa v3.2.0! This release includes a few key improvements as well as many bug fixes.

HTTP Cookies

v3.2.0 adds native support for HTTP cookies in Goa designs. Prior to this release cookies could be read and written by Goa services using HTTP middlewares that would read (or inject) the values from (into) the context. For example:

// NOT NECESSARY ANYMORE
package cookie

type cookieKeyType int // private so key is unique
var CookieKey cookieKeyType = iota + 1

// ReadCookie returns a HTTP middleware that reads the value of the cookie with
// the given name and adds it to the request context under cookiectx.CookieKey.
func ReadCookie(name string) func(http.Handler) http.Handler {
    return func(h http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            c, err := req.Cookie(name)
            if err != nil {
                goto skip
            } 
            ctx := context.WithValue(r.Context(), cookiectx.CookieKey, c.Value)
            r = r.WithContext(ctx)
        skip:
            h.ServeHTTP(w, r)
        })
    }
}

// Usage:
// Mount middleware when creating the server:
srv := calcsvr.New(calcEndpoints, mux, dec, enc, eh, nil)
srv.Use(cookie.ReadCookie("session_uid"))

// Use the value from the context in the service methods:
func (s *Service) Endpoint(ctx context.Context, p *Payload) (*Result, error) {
    sessionUID := ctx.Value(cookie.CookieKey)
    // ...
}

Goa now makes it possible to provide the same functionality by simply adding the following to the HTTP expression of the method:


Goa v3.0.3

The Goa community has contributed many fixes to Goa as adoption of v3 grows. This release builds on v3.0.1 and v3.0.2 and adds several more fixes. In particular:

  • Nitin Mohan fixed a couple of issues with the generated OpenAPI specifications (#2141) (#2159).
  • @ikawaha fixed a few issues with the generation of Go identifiers (#2144) (#2152) (#2172). @ikawaha also made it possible to use specific shas to point to Goa v3 in go.mod and made sure the code generation algorithms honored it (#2182).
  • Ruggero added support for plain text to the default Goa encoder and decoder (#2165).
  • Kaosisochukwu Uzokwe fixed a potential panic in the gRPC client method builder (#2186).
  • Tim Adam moved the XRay test helpers into a separate package to avoid side effects when loading the testing package (#2190).
  • Carl Quinn fixed an issue with the code generation of CLI arguments of type []byte (#2196).
  • Raphael Simon fixed a couple of issues with the handling of array attributes in responses (#2200) (#2202).

v3.0.1 and v3.0.2 added a few other fixes. A notable addition contributed by @CuBiC in v3.0.1 is the ability to set scopes on basic auth and API key security schemes. The scopes can be defined in the design and are made available to the security enforcing functions at runtime (#2120).


goa v3.0.0

After more than 2 years of work and contributions from 40 different authors, I am really proud to announce the official release of Goa v2 (and v3 see Go Modules Support below). This release includes many improvements, bug fixes and new features. Most notably Goa v2 focuses on defining a clean separation of layers both in designs and in generated code. One concrete result of this clean separation is the ability to define services that serve both HTTP and gRPC requests. Other major improvements include a more idiomatic package and generated code with fewer dependencies. The generated code is completely modular making it possible to override specific endpoints at any level (transport, endpoint or business logic level).


goa v1.4.1

goa v1.4.1 is out! This release contains a few bug fixes and mainly updates the uuid package dependency to a maintained repository.

New Features

UUID Package Update

v1.4.1 updates the import of the UUID package to github.com/gofrs/uuid instead of the original github.com/satori/go.uuid which isn’t maintained anymore.

Support for default GOPATH and Go modules

Taichi Sasaki added the ability for goagen to use the default GOPATH if none is set explicitely (as defined in Go 1.8). Taichi also added support for Go modules to goagen!


goa v1.4.0

It’s been almost a year since the last official release of goa. During that year many contributions have been made including both new features and bug fixes. The team has also been hard at work on v2 making good progress there but this post is about the latest v1 release: goa v1.4.0.

New Features

Multipart Form Encoding

Taichi Sasaki (@tchssk) added native support for multipart form encoding as described in the HTML 4 Specification. The new MultipartForm function can be used in an action design as follows:


goa v1.3.0

Another 4 months and another goa release! goa v1.3.0 is out! This version includes new features and a slew of bug fixes. Thank you to all the contributors that spent a lot of time writing (and sometimes re-writing) the code, the tests and the docs. The list below highlights the main contributions.

New Features

10x Code generation speed improvement on Windows

Klaus Post identified an issue where goagen was re-opening the generated files too often. Opening the files only once during code generation resulted in a 10x speed increase on Windows!


goa v1.2.0

Today I am very pleased to announce the release of goa v1.2.0! This release contains all the changes made in the v1 branch of goa for the past 4 months - since the release of v1.1.0.

New Team Members!

While not directly related to this release this seems like a good opportunity to officially announce that Taichi Sasaki and Michael Boke have both joined to goa team!

Taichi was one of the first contributors to goa, his contributions are always of the highest quality. Apart from fixing many bugs and contributing actively to goa v2, Taichi also helped translate the entire https://goa.design/ja website into Japanese.


Tracing goa Services with AWS X-Ray

AWS announced the availability of X-Ray in beta as one of the many product announcements that were made at the re:Invent conference.

Like most (all?) tracing solutions AWS X-Ray follows the architecture initially described in the Google Dapper paper. It even comes with a daemon that collects the metrics locally before shipping them as described in the paper (and as opposed to something like Zipkin).

The AWS X-Ray console allows running some pretty sophisticated queries against all the traces which is probably one of the most interesting aspect. Queries can use the values of annotations attached to the traces so that one may correlate fairly easily requests with other application specific identifiers such as user IDs, session IDs etc.


goa v1.1.0

Edit: the original announcement listed a PR from Jared Bischof which added the ability to dynamically change the set of JWT keys used to authorize incoming requests. This PR is not in 1.1.0 as it contains an interface breaking change. It is however in the master branch.

I am very pleased to announce the release of goa v1.1.0! This release includes all the work done in the v1 branch since the release of v1.0.0 roughly four months ago. This includes 30 bug fixes, 18 new features and many minor improvements made by 24 contributors. This being a v1.x.x release means that all existing users currently using v1.0.0 can upgrade seamlessly with no modification to the existing code.


From Design To Production

Google recently announced the open beta release of the newest set of features in Google Cloud Endpoints. The part of the announcement that got me especially excited was:

We’re also announcing support for the OpenAPI Specification. We’re a founding member of the Open API Initiative (OAI), and recognize the value of standardizing how REST APIs are described.

In other words Google Cloud Endpoints can be completely configured using an OAI spec, one for example that has been generated by goa! All the goa services (goa.design, swagger.goa.design, cellar.goa.design and talks.goa.design) already run on top of the Google Cloud Platform so I had to give Google Cloud Endpoints a shot.


Hello, goa

Today I’m very excited to announce the release of goa v1.0.0. goa provides a design first approach for building microservices in Go. It consists of three parts: a DSL for describing the API design, a code generation tool that generates an OpenAPI specification as well as boilerplate code for the service and the clients, and a set of library packages leveraged by both the generated and non generated code. This release represents the culmination of 2 years of work spanning 5 complete rewrites. During this time goa evolved from being a pet experiment to becoming a strategic tool used by many organizations and with a striving and growing community.