Custom codecs plug into the same request, response, and optional streaming contracts as the bundled dialects. Keep wire DTOs private to the package and return bounded typed errors at representation boundaries.

Contract

type Codec struct{}

var _ codec.Codec = Codec{}

func (Codec) EncodeRequest(
	req inference.Request,
	mode codec.RequestMode,
) (codec.EncodedRequest, error) {
	// Build a fresh, single-use body for this attempt.
	return codec.EncodedRequest{}, nil
}

Implement DecodeResponse for invoke. Add DecodeStream only when the native API has a stream; the returned reader must own and close the response body. Implement ServerCodec too when the gateway must accept the native request.

Ownership

The custom codec owns JSON or other wire transformations, event names, finish reason mapping, and dialect-specific typed errors. The route owns method, URL, query, and route headers. The transport owns authorization, context, status, body limits, and never replays the body. Add tests for malformed input, unsupported blocks, body-close-on-error, terminal stream metadata, and usage normalization before registering the codec.

Source and proof

Run the custom package’s tests with go test ./codec ./route ./transport.