content

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 11, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package content provides immutable per-validator HTTP body codec registries.

Decoders convert request and response bodies into the JSON-compatible values consumed by schema validation. Encoders are used only when opt-in request default application rewrites a body. Registry lookup precedence is exact media type, structured suffix, type wildcard, then global wildcard.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Canonicalize

func Canonicalize(value any) (any, error)

Canonicalize recursively converts decoded values to the JSON validation data model. It rejects maps with non-string keys and values outside the documented primitive, []any, map[string]any, []byte, json.Number, and time.Time set.

func NormalizeMediaType

func NormalizeMediaType(value string) (string, map[string]string)

NormalizeMediaType parses a media type and lowercases its lookup key.

func ParseScalar

func ParseScalar(value, kind string) any

ParseScalar converts a string to a JSON-compatible primitive when requested by custom codecs.

Types

type CompatibilityDecoder

type CompatibilityDecoder interface {
	Decoder
	// CompatibilityKind identifies the legacy adapter that must replace this marker.
	CompatibilityKind() string
}

CompatibilityDecoder marks a decoder placeholder that is replaced by a schema-aware validator adapter.

type DecodeInput

type DecodeInput struct {
	Context context.Context // Context is the request context.
	Body    io.Reader       // Body is a fresh reader over the immutable body snapshot.
	Header  http.Header     // Header contains the request or response headers.
	// MediaType is the normalized media type without parameters.
	MediaType string
	// Parameters contains parsed media-type parameters such as charset or boundary.
	Parameters map[string]string
	Schema     *base.Schema // Schema is the OpenAPI media-type schema.
	// Encoding contains OpenAPI per-property encoding metadata when available.
	Encoding  interface{ GetOrZero(string) *v3.Encoding }
	Direction Direction // Direction identifies request or response processing.
}

DecodeInput contains the complete body-decoding context supplied by a validator.

type Decoder

type Decoder interface {
	// Decode returns a JSON-compatible validation value.
	Decode(*DecodeInput) (any, error)
}

Decoder converts an HTTP entity into a JSON-compatible validation value.

func BinaryDecoder

func BinaryDecoder() Decoder

BinaryDecoder returns a decoder for string/binary schemas.

func CSVDecoder

func CSVDecoder() Decoder

CSVDecoder validates CSV syntax and preserves the original body as a string.

func FormCompatibilityDecoder

func FormCompatibilityDecoder() Decoder

FormCompatibilityDecoder returns the marker used by the legacy form validation option.

func FormDecoder

func FormDecoder() Decoder

FormDecoder returns a URL-encoded form decoder.

func JSONDecoder

func JSONDecoder() Decoder

JSONDecoder returns the compatibility JSON decoder.

func MultipartDecoder

func MultipartDecoder() Decoder

MultipartDecoder returns a form-data decoder using the boundary parameter.

func TextDecoder

func TextDecoder() Decoder

TextDecoder returns a decoder that preserves the body as a string.

func XMLCompatibilityDecoder

func XMLCompatibilityDecoder() Decoder

XMLCompatibilityDecoder returns the marker used by the legacy XML validation option.

func XMLDecoder

func XMLDecoder() Decoder

XMLDecoder returns a generic XML object decoder.

func YAMLDecoder

func YAMLDecoder() Decoder

YAMLDecoder returns a YAML decoder with JSON-compatible canonicalization.

func ZIPDecoder

func ZIPDecoder(limits ZipLimits) Decoder

ZIPDecoder returns a decoder that validates archive metadata against limits and returns the original archive bytes as a string for schema validation. It does not extract archive entries. All limits must be positive.

type DecoderFunc

type DecoderFunc func(*DecodeInput) (any, error)

DecoderFunc adapts a function to Decoder.

func (DecoderFunc) Decode

func (f DecoderFunc) Decode(input *DecodeInput) (any, error)

Decode calls f with input.

type DecodingError

type DecodingError struct {
	MediaType string    // MediaType is the normalized type selected for decoding.
	Direction Direction // Direction identifies request or response decoding.
	Err       error     // Err is the underlying decoder or canonicalization error.
}

DecodingError retains codec context while exposing the decoder failure.

func (*DecodingError) Error

func (e *DecodingError) Error() string

Error describes the media type, direction, and underlying decoder failure.

func (*DecodingError) Unwrap

func (e *DecodingError) Unwrap() error

Unwrap exposes the underlying decoder or canonicalization failure.

type Direction

type Direction uint8

Direction identifies whether a codec is processing request or response data.

const (
	// Request identifies request-body processing.
	Request Direction = iota
	// Response identifies response-body processing.
	Response
)

type EncodeInput

type EncodeInput struct {
	Context   context.Context // Context is the request context.
	Value     any             // Value is the canonical decoded value to encode.
	Header    http.Header     // Header contains the staged request headers.
	MediaType string          // MediaType is the normalized media type.
	Schema    *base.Schema    // Schema is the OpenAPI media-type schema.
	// Encoding contains OpenAPI per-property encoding metadata when available.
	Encoding  interface{ GetOrZero(string) *v3.Encoding }
	Direction Direction // Direction identifies request or response processing.
}

EncodeInput contains the complete body-encoding context.

type Encoder

type Encoder interface {
	// Encode serializes a canonical validation value into an HTTP body.
	Encode(*EncodeInput) ([]byte, error)
}

Encoder converts a validation value back into an HTTP entity.

func JSONEncoder

func JSONEncoder() Encoder

JSONEncoder returns the standard JSON encoder.

type EncoderFunc

type EncoderFunc func(*EncodeInput) ([]byte, error)

EncoderFunc adapts a function to Encoder.

func (EncoderFunc) Encode

func (f EncoderFunc) Encode(input *EncodeInput) ([]byte, error)

Encode calls f with input.

type EncoderRegistration

type EncoderRegistration struct {
	MediaType string  // MediaType is an exact type or wildcard media range.
	Encoder   Encoder // Encoder handles values selected by MediaType.
}

EncoderRegistration associates a normalized media-range with an encoder.

type FailureContext

type FailureContext struct {
	Request   *http.Request  // Request is the request being validated.
	Response  *http.Response // Response is populated for response failures.
	Operation *v3.Operation  // Operation is the matched OpenAPI operation.
	MediaType *v3.MediaType  // MediaType is the selected OpenAPI media-type definition.
	Schema    *base.Schema   // Schema is the selected body schema.
}

FailureContext retains HTTP and OpenAPI objects associated with a decoding or rewrite failure.

type Registration

type Registration struct {
	MediaType string  // MediaType is an exact type or wildcard media range.
	Decoder   Decoder // Decoder handles values selected by MediaType.
}

Registration associates a normalized media-range with a decoder.

func StandardDecoderRegistrations

func StandardDecoderRegistrations() []Registration

StandardDecoderRegistrations returns non-archive built-in codecs.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry is an immutable, concurrency-safe, lock-free codec lookup table. Construct registries with NewRegistry and derive replacements with WithDecoder.

func NewRegistry

func NewRegistry(decoders []Registration, encoders []EncoderRegistration) *Registry

NewRegistry freezes codec registrations. Later duplicate exact registrations win.

func (*Registry) Decoder

func (r *Registry) Decoder(mediaType string) (Decoder, string, map[string]string)

Decoder resolves exact, structured-suffix, type-wildcard, then global-wildcard matches.

func (*Registry) Encoder

func (r *Registry) Encoder(mediaType string) (Encoder, string, map[string]string)

Encoder resolves an encoder with the same precedence as Decoder.

func (*Registry) ExactDecoder

func (r *Registry) ExactDecoder(mediaType string) Decoder

ExactDecoder returns only an exact normalized registration without wildcard resolution.

func (*Registry) Precompute

func (r *Registry) Precompute(mediaTypes []string) *Registry

Precompute returns a new immutable registry with resolved exact dispatch entries for declared media types.

func (*Registry) WithDecoder

func (r *Registry) WithDecoder(mediaType string, decoder Decoder) *Registry

WithDecoder returns a new immutable registry with one exact decoder replaced.

type ZipLimits

type ZipLimits struct {
	CompressedSize int64   // CompressedSize is the maximum archive size in bytes.
	ExpandedSize   int64   // ExpandedSize is the maximum total uncompressed size in bytes.
	Entries        int     // Entries is the maximum number of archive entries.
	ExpansionRatio float64 // ExpansionRatio is the maximum expanded-to-compressed size ratio.
}

ZipLimits bounds archive processing.

func (ZipLimits) Validate

func (l ZipLimits) Validate() error

Validate requires finite positive archive limits.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL