Skip to content

v1.9.0: Slimmer dependencies and a pluggable JSON codec

Latest

Choose a tag to compare

@github-actions github-actions released this 10 Nov 22:18
· 2 commits to main since this release
1b74ca8

This release removes the strictmiddleware packages, which pulled every supported web framework into the dependency graph of every program that imports the runtime, and which generated code has not used since oapi-codegen v2.7.0. It adds a process-wide JSON codec that the upcoming oapi-codegen v2.9.0 will route all generated JSON encoding and decoding through, binds uuid.UUID fields in deepObject parameters, and fixes label and matrix path parameters whose value contains the style's delimiter. The minimum Go version is now 1.26.

Notable Changes

☢️ Breaking: the strictmiddleware packages are gone

The strictmiddleware/{echo,echo-v5,gin,iris,nethttp} packages held a handful of StrictHandlerFunc and StrictMiddlewareFunc type definitions, and nothing else. To define them, the runtime had to import Echo, Gin and Iris, so every program importing github.com/oapi-codegen/runtime dragged all three frameworks and their transitive dependencies into its go.mod, whether it used them or not. Removing the packages (#181, closes #180) takes the root module from 5 direct and 66 indirect requirements down to 4 direct and 1 indirect, with no web framework among them. The separate strictmiddleware/echo-v5 module is removed as well.

Code generated by oapi-codegen v2.7.0 and later declares these types itself and never imports the packages, so for anyone on a current generator the upgrade is a go get and a go mod tidy that deletes a lot of lines. Code generated by oapi-codegen v2.6.0 or earlier still imports them and will not compile against this release.

Important

If your project uses generated code from oapi-codegen v2.6.0 or earlier, stay on runtime v1.8.0 until you have regenerated with v2.7.0 or later. Do not upgrade the runtime first.

Pluggable JSON codec

Everything the runtime encodes or decodes as JSON now goes through a single, process-wide codec (#183). The default is encoding/json, unchanged, and a program can replace it in its main package:

runtime.SetJSONCodec(myCodec) // any value with Marshal(any) ([]byte, error) and Unmarshal([]byte, any) error

The API is:

  • JSONCodec: the two-method interface a replacement implements. StdJSONCodec is encoding/json's pair, and can be embedded to override just one method, for instance to turn off HTML escaping.
  • StreamingJSONCodec: an optional second interface, MarshalWrite(io.Writer, any) and UnmarshalRead(io.Reader, any), for codecs that can stream request and response bodies instead of buffering them. A codec without it is buffered through Marshal and Unmarshal.
  • JSONMarshal, JSONUnmarshal, JSONMarshalWrite and JSONUnmarshalRead: the functions that generated code and the runtime itself call. JSONUnmarshalRead returns io.EOF for an empty body whichever codec is in use, which is how strict servers detect an optional body that was left out.
  • SetJSONCodec(nil) restores the default.

Within the runtime, deepObject and form parameter encoding, BindJSONBody, and the types package's Date, Duration, Email and File all use the codec already. Generated code still calls encoding/json directly today. oapi-codegen v2.9.0 will switch every generated json.Marshal, json.Unmarshal and strict response encoder over to these functions, at which point one SetJSONCodec call covers a whole program: models, clients and servers. This replaces the per-package json-encoding configuration proposed in oapi-codegen/oapi-codegen#2371, where the design discussion lives, and it is the intended path to encoding/json/v2. Thanks to @CRaLFa for the implementation.

uuid.UUID fields bind in deepObject parameters

A deepObject query parameter with a format: uuid field, such as ?filter[entity]=6ba7b810-9dad-11d1-80b4-00c04fd430c8, failed with unhandled type: uuid.UUID. uuid.UUID is a [16]byte, so it never reached the branch that checks for encoding.TextUnmarshaler. Array-kind types that implement UnmarshalText now bind, as they already did everywhere else in the runtime; uuid.UUID, *uuid.UUID, slices and map values all work. Other fixed-size arrays are still rejected as before. Thanks to @youdie006 (#171).

label and matrix scalar path parameters are no longer split

A scalar label or matrix path parameter whose value contained the style's delimiter, such as big,red sent as .big%2Cred, was rejected with "expected single value, got N parts" once the router had decoded the segment. The primitive branch now strips only the style prefix and never splits the value, matching the fix #114 made for the simple style. Arrays, structs and maps are unchanged (#182, closes #175).

Go 1.26

The module now requires Go 1.26, the oldest supported Go release, and all remaining dependencies are at their latest versions (#178).

☢️ Breaking changes

🚀 New features and improvements

🐛 Bug fixes

📦 Dependency updates

8 changes

🔐 Security

Sponsors

We would like to thank our sponsors for their support during this release.

DevZero logo

Cybozu logo

New contributors