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.

Why Release v1.1.0 Now?

Many goa users prefer to stick to the official release tags rather than to follow the v1 branch. There are a number of bug fixes that would benefit these users in v1.1.0 and as we get close to the end of the year the choice was between releasing now or waiting until next year, so now it is!

Releasing every 4 months seems like a good release cadence as well, look for another release in April 2017.

What’s New?

The complete list of commits is available on GitHub. Here are the most noteworthy additions in this new release.

Programmatic Code Generation

This contribution from Alexandre Bourget makes it convenient to invoke the generators programmatically rather than through goagen. See Code-based generation and vendoring for additional details.

Pull Request:

• Make a nice API to programmatically generate your code, and facilitate vendoring.

Swagger Support Improvements

Many bug fixes and improvements were made to the Swagger support. Most notably Taichi Sasaki added support for Swagger extensions through the use of Metadata.

Swagger generation can now also be disabled for specific endpoints using the new swagger:generate Metadata.

The main fixes include properly setting the collection format on parameters of type Array (fix from @fede-bitlogic) and proper generation of the Any type (issue initially reported by Peter Dulačka).

Pull Requests:

• Support swagger extensions
• Add ability to set JSON encoded Swagger extension values
• Try to use swagger extensions as JSON by default
• Implement “swagger:generate” metadata
• swagger ui fails to send a proper request when a paramter is Arrayof(…)
• Generate empty schema for Any type

Query String Array Parameters

Proper support for arrays in query strings was added (initially reported by Thorsten von Eicken).

Pull Request:

• Properly handle array params

Security Improvements

Evgeny Gavrilov also cleaned up the Swagger specification generated for the JWT security scheme.

Pull Requests:

• Do not add a list of security scopes in the description swagger, if it is empty

CORS Support Improvements

CORS origins can now be matched using regular expressions thanks to a PR from Matteo Suppo. Matteo also fixed the value of the Access-Control-Allow-Origin response header returned by goa when an origin matches the specification.

CORS support was also added for file servers (issue initially reported by Peter Dulačka).

Pull Requests:

• Allow cors spec to be defined as regexps
• Generate cors headers without wildcards
• Generate CORS preflight handler for file server endpoints

Support for Modifying the goa Error Response Content-Type

This PR addresses a common request which is the ability to override the error media type identifier used by goa when validation errors occur. With this change it is now possible to override the identifier returned in the Content-Type header of error responses.

Pull Request:

• Make ErrorMediaIdentifier a variable instead of a constant

Support for UUID parameters on the CLI

Aslak Knutsen added proper support for UUID parameters in the code generation algorithms used to generate the client CLI.

Pull Request:

• Generate direct access to cmd.FieldName when resolving path params

Logging

The log messages now include the name of the controller and action thanks to a PR from Konstantin Dzreev. Craig Brookes also made it possible to log the complete backtrace of errors are returned by controllers that are wrapped using Dave Cheney’s errors package Wrap function.

Pull Requests:

• Add “ctrl” and “action” key/values to the “completed” log message
• Add ability to log backtraces to ErrorHandler middleware

DSL

The DSL UseTrait function was improved by Jeroen Simonetti to allow invoking more than one trait in a single call.

Pull Request:

• Change UseTrait APIDSL function to be variadic

Miscellaneous

Yusuke Hatanaka added the Serve method to the Service struct making it convenient for goa services to listen on Unix sockets for example.

Jeroen Simonetti made it possible to pass arguments to custom generator on the command line by appending them after a final -- separator.

Finally Taichi Sasaki contributed a change to the generated code headers that tells github to ignore the generated files in PR diffs (very cool!).

Pull Requests:

• Add unix domain socket listener to service.ListenAndServeUnix
• Pass arguments to final generator
• Suppress diffs of generated codes on GitHub

What’s Fixed?

This release includes many bug fixes as well, including:

Payload Type Generation

A fix done shortly after the release of v1.0.0 was the removal of the generation of duplicated structs for payload types. The DSL makes it possible to refer to a user type in the Payload function and optionally to further customize it for example by specifying required attributes. Only in this case will two types be generated after this fix.

@ikawaha fixed the code generation so that DateTime default values are now properly set (this applies to media type as well).

@KerwinKoo fixed the marshaling of UUID values in JSON.

• Fix potential duplicate generation of payload types
• Fix setting a default value to datetime
• Add (Un)Marshal Text/Binary methods to support json parsing

Media Type Generation

The value specified in the ContentType DSL function is now properly honored in the generated code thanks to a fix by George Dobrovolsky). George also reported an issue with how examples for links were generated.

Pull Request:

• Fix ContentType isn’t applied in MediaType
• Fix generation of examples for media types

Examples Generation

Generated examples for media type now properly take into account the view (issue initially reported by George Dobrovolsky).

Pull Request:

• Fix generation of examples for media types

Validations Generation

@ikawaha fixed the generation of length validation for strings that contain multi-byte UTF-8 characters.

Another fix corrects the code generated for float64 minimum and maximum values (issue initially reported by Luna Duclos).

The validation code generated for arrays of user types now properly checks for nil elements (issue initially reported by Robert Lee).

Pull Requests:

• Fix length validations to count the length of the string using by utf8.RuneCountInString()
• Properly handle float range errors
• Protect array validation against nil elements

Test generation

There were many fixes done to the generated test helpers. One notable addition is a PR from Kannan Manickam which changes the generated code to use an interface instead of testing.T directly. This makes it convenient to pass other structs that implement the interface for example provided by different test packages.

Craig Brookes also added proper header comments to the generated code.

Finally Ian Delahorne added a missing import statement for the guid package.

Pull Requests:

• Fix test helper panic when controller does not write media type
• Fail test fatally if media type is not of the right type
• Add an interface instead of using testing.T
• address issue 738 by creating a title for the test file
• Add uuid to test helper imports. Fixes #870

Logging

Jim Slattery cleaned up the code used to append the values in the log context when using the standard logger to avoid possible concurrent modifications.

Pull Request:

• removed unneeded check which would make an unsafe concurrent modification

Swagger generation

Taichi Sasaki fixed the handling of Metadata tags in the generated Swagger specification. He also made sure data structure tags are generated in alphabetical order.

@ikawaha also fixed a bug where the Required field for payload would always be set to true even for optional payloads.

Pull Requests:

• Fix to contain only valid tags in gen_swagger
• Fix a bug that the payload is always required ’true’ in swagger documents.

Metrics collection

Xander Guzman made sure that metrics tags are properly escaped before being reported to the metrics server.

Pull Request:

• Modify metrics so that names are normalized to legal chars

Client

The API key signer now properly signs requests and the key is properly escaped when specified on the command line in the generated CLI tool.

The code generated for clients that use required UUID values in headers now compiles properly (issue initially reported by Naoya Yoshizawa).

The client methods now only include a ContentType argument is the API supports multiple decodings. Many thanks to Konrad Kleine for fixing the mess I created with the first commit…

Pull Requests:

• Fix API key signer
• Properly format query string API keys from command line arguments
• Fix code that sets request headers in client package
• Fixup for 2e83b0dfdd45e1e54615606924dca565b547b08b

goagen

Sye van der Veen reported and fixed issues with the handling of the --notool flag.

Conclusion

This list only covers the main contributions, it is clear that a lot of work went into this release. A big thank you to all the contributors! As the work on v2 proceeds, expect at least one more v1 release with additional bug fixes and new features. In the mean time though enjoy v1.1.0!