goa v1.1.0
Announcing 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:
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:
Security Improvements
Evgeny Gavrilov also cleaned up the Swagger specification generated for the JWT security scheme.
Pull Requests:
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:
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:
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:
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:
Examples Generation
Generated examples for media type now properly take into account the view (issue initially reported by George Dobrovolsky).
Pull Request:
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:
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:
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!