The maintainer has not written a description at the source.
Repo oapi-codegen/runtime, read from GitHub 1 min ago. oapi-codegen has not joined Take My Repo.
This is a bugfix release. MarshalForm now honors the style and explode of a form property's encoding, and deepObject binding rejects integers that overflow their destination instead of wrapping them. There are no API changes, and code generated by current oapi-codegen releases behaves as before.
MarshalForm honors style and explodeMarshalForm only read ContentType from a property's RequestBodyEncoding, so an array was always written with indexed keys, topic[0]=a&topic[1]=b, even when the encoding declared style: form, explode: true, which serializes as repeated keys, topic=a&topic=b. A property whose encoding sets Style or Explode is now serialized as a query parameter of that style would be: form, spaceDelimited and pipeDelimited repeat the key when exploded and write one delimited value otherwise, and deepObject is the existing bracketed form. Explode defaults to true for form and false for the other styles, as in the specification.
Properties with no encoding, or with one that sets neither field, are unchanged. Generated clients pass no encodings today, so their output is the same; a future oapi-codegen release will pass the spec's encodings through (oapi-codegen/oapi-codegen#2604). The application/json content type branch, which returned unsupported encoding for every content type including JSON, now works too (#187, closes #186).
deepObject integers that overflow are rejectedUnmarshalDeepObject parsed integer fields as 64-bit and assigned them without checking that the value fit, so ?filter[count]=4294967297 bound into an int32 as 1 with no error. Out-of-range values now fail with an overflows destination error, as they already did for the form style and the JSON binders. Thanks to @youdie006 (#185).
We would like to thank our sponsors for their support during this release.
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.
strictmiddleware packages are goneThe 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.
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 parametersA 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 splitA 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).
The module now requires Go 1.26, the oldest supported Go release, and all remaining dependencies are at their latest versions (#178).
We would like to thank our sponsors for their support during this release.
This release adds a request body binder that reuses the value a kin-openapi validation middleware already decoded, so strict servers no longer decode the body a second time with different matching rules. It also rounds out types.Date's text encoding and fixes a deepObject serialization quirk. Existing binding and serialization behaviour is unchanged unless generated code calls the new function. The root module's dependencies are unchanged; the separate strictmiddleware/echo-v5 module now requires Echo v5.4.2.
BindJSONBody: bind exactly what the validator validatedStrict servers generated by oapi-codegen decode the JSON request body with encoding/json after a validation middleware has already decoded and validated it. The two decoders do not agree on member names: encoding/json matches struct fields case-insensitively, so a body like {"role":"user","ROLE":"admin"} validates as role: user and then binds as Role: "admin". Anything the validator checked can be bypassed by a differently-cased duplicate.
BindJSONBody(r *http.Request, v any) error closes that gap. When the request has passed through a validator built on kin-openapi v0.151.0 or later with openapi3filter.Options.KeepValidatedValue set, the body carries the value the validator decoded, and BindJSONBody binds that value into the destination with BindJSONValue(value, v any) error instead of reading the body again. Binding follows encoding/json's rules (struct tags, embedded structs, json.Unmarshaler and encoding.TextUnmarshaler, base64 for []byte, float64 for any, json.Number preserved) with one deliberate difference: member names are matched to struct fields exactly.
Without a validated value, or when the value cannot be bound into the destination type, BindJSONBody falls back to json.NewDecoder(r.Body).Decode(v), so error responses are unchanged for everyone who is not running a validator. The oapi-codegen validation middlewares enable KeepValidatedValue by default as of nethttp-middleware v1.3.1, echo-middleware v1.2.1, echo-v5-middleware v0.2.1, gin-middleware v1.2.1 and iris-middleware v1.2.1. The net/http strict server template that calls BindJSONBody is landing in oapi-codegen separately (oapi-codegen/oapi-codegen#2605); the runtime side ships first so generated code can rely on it.
types.Date implements encoding.TextMarshalerDate had an UnmarshalText that parses 2006-01-02 but no MarshalText, so it inherited time.Time's RFC 3339 one. Any codec that pairs TextMarshaler with TextUnmarshaler (encoding/xml, DynamoDB mappers, and others) therefore wrote a Date it could not read back. MarshalText now formats with DateFormat, matching MarshalJSON, String and UnmarshalText. Thanks to @jusabe-kreditz.
deepObject no longer emits param[]=null for nil maps and slicesMarshalling a deepObject parameter whose field held a typed nil map or nil slice produced a param[]=null pair, because the intermediate json.Marshal turned the nil into null. Such fields are now omitted, as an empty map or slice already was. Nil pointers are still serialized as null, as before. Thanks to @SKalt (#160).
We would like to thank our sponsors for their support during this release.
This release teaches the parameter binders about OpenAPI 3.1 multi-type unions, and fixes a long-standing panic on the request binding path. As with v1.6.0, new behavior is controlled by explicit settings rather than assumptions: binding stays exactly as it was unless the new options are used.
OpenAPI 3.1 allows a parameter's type to be a list, such as type: [string, integer]. Go has no type meaning "one of these", so generated code maps such parameters to any โ which the binders previously rejected outright with can not bind to destination of type: interface, making these parameters unusable.
The binder options structs (BindStyledParameterOptions, BindQueryParameterOptions, BindStringToObjectOptions) gain a Types []string field carrying the union's member list. It is only consulted when the destination is an any; binding into every concrete Go type is completely unchanged. The value binds to the first member that parses, trying boolean, integer, number, then string โ most restrictive first, since a string always parses. Member detection follows the JSON number grammar (RFC 8259), so values like 007 or +1 bind as strings rather than being silently reinterpreted as numbers.
The bound value's dynamic type is always one of bool, int64, float64, string, or (with format: byte) []byte, so a handler's type switch is stable regardless of what the spec's format says. Applications that want format: int32 / format: float to narrow the produced types to int32 / float32 can opt in via a new package-level setting, following the same pattern as DefaultQueryEncoder from v1.6.0:
func init() { runtime.NarrowUnionNumericFormats = true }
Generator support for emitting Types is landing in oapi-codegen separately; the runtime side ships first so generated code can rely on it. Arrays of unions and deepObject-style parameters are not covered yet โ see the Types field documentation for the exact scope.
Since v1.2.0, binding a string that happens to parse as an integer into a non-[]byte slice destination panicked with reflect: call of reflect.Value.OverflowInt on slice Value, instead of returning an error. This was reachable from generated code on the request path: a nullable.Nullable[[]string] query parameter using the default form/explode serialization would panic on ?p=123 while returning a normal binding error on ?p=abc. These cases now return a clean can not bind to destination of type: slice error.
We would like to thank our sponsors for their support during this release.
This is a small release which adds a global encoding setting on the runtime, to allow users to customize how to handle spaces in query arguments. This is a new minor release, since we're adding new API, even though this is a very minor feature. I imagine that in the future, we will add more settings, rather than making behavior assumptions.
We would like to thank our sponsors for their support during this release.
We would like to thank our sponsors for their support during this release.
This is mainly a bugfix release, but we're bumping the minor version since we also introduce a new type, Duration into our types/ package, which allows for parsing and emitting RFC3339 durations. Rather than trying to parse a duration string into a time.Duration, which requires assumptions that may not be right for everyone, we decided not to make those decisions and just store all possible fields as provided. Users can convert this to Go Duration as they see fit.
We would like to thank our sponsors for their support during this release.