binding

package
v1.2.0 Latest Latest
Warning

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

Go to latest
Published: Mar 22, 2026 License: MPL-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package binding handles the extraction and conversion of HTTP request data into Go types, including path/query/header parameter binding, request body deserialization, multipart form processing, and response output writing.

Index

Constants

This section is empty.

Variables

View Source
var ErrUnparsable = errors.New("unparsable value")

ErrUnparsable is returned when a value cannot be parsed into the target type.

Functions

func GetParamValue

func GetParamValue(p ParamFieldInfo, ctx core.Context, cookies map[string]*http.Cookie) string

GetParamValue extracts the raw string value for a parameter from the request context based on its location (path, query, header, or cookie), falling back to the default value if empty.

func HasMultipartFields

func HasMultipartFields(t reflect.Type) bool

HasMultipartFields reports whether the struct type t contains any exported fields with a "form" tag that represent file uploads.

func IsMultipartFormFilesType

func IsMultipartFormFilesType(t reflect.Type) bool

IsMultipartFormFilesType reports whether t is a MultipartFormFiles wrapper type.

func ParseDeepObjectQuery

func ParseDeepObjectQuery(query url.Values, name string) map[string]string

ParseDeepObjectQuery extracts key-value pairs from query parameters encoded in OpenAPI deepObject style (e.g., "filter[name]=value").

func ParseInto

func ParseInto(ctx core.Context, f reflect.Value, value string, preSplit []string, p ParamFieldInfo, parsedQuery ...url.Values) (any, error)

ParseInto parses a string parameter value into the reflect.Value f based on the type information in p. For slice types, preSplit or exploded query values are used. It returns the parsed value or an error if parsing fails.

func SetDeepObjectValue

func SetDeepObjectValue(pb *core.PathBuffer, res *core.ValidateResult, f reflect.Value, data map[string]string) map[string]any

SetDeepObjectValue populates a struct or map field from deep object query data, recording validation errors in res. It returns the parsed key-value pairs as a map for further validation.

func SetupMultipartRequestBody

func SetupMultipartRequestBody(op *core.Operation, registry core.Registry, fields []MultipartFieldInfo)

SetupMultipartRequestBody configures the operation's OpenAPI request body schema for multipart/form-data based on the provided field metadata.

func WriteHeader

func WriteHeader(write func(string, string), info *HeaderInfo, f reflect.Value)

WriteHeader writes a single response header by converting the field value f to a string and passing it to the write function along with the header name.

func WriteResponse

func WriteResponse(api core.API, ctx core.Context, status int, ct string, body any) error

WriteResponse negotiates the content type (if ct is empty), applies any registered transformers, marshals the body, and writes the HTTP response. It returns an error if content negotiation or marshaling fails.

func WriteResponseWithPanic

func WriteResponseWithPanic(api core.API, ctx core.Context, status int, ct string, body any)

WriteResponseWithPanic calls WriteResponse and panics if it returns an error.

Types

type BodyProcessingConfig

type BodyProcessingConfig struct {
	Body           []byte
	Op             core.Operation
	Value          reflect.Value
	HasInputBody   bool
	InputBodyIndex []int
	Unmarshaler    IntoUnmarshaler
	Validator      func(data any, res *core.ValidateResult)
	Defaults       *FindResult[any]
	Result         *core.ValidateResult
}

BodyProcessingConfig holds the parameters needed to validate and unmarshal a request body into the target input struct.

type ContextError

type ContextError struct {
	Code int
	Msg  string
	Errs []error
}

ContextError represents an HTTP error with a status code, message, and optional underlying errors.

func ProcessMultipartForm

func ProcessMultipartForm(ctx core.Context, cfg MultipartProcessingConfig) *ContextError

ProcessMultipartForm parses the multipart form from ctx and populates the target struct fields described by cfg. File fields are opened and assigned as FormFile values; non-file fields are parsed from their string values.

func ProcessRegularMsgBody

func ProcessRegularMsgBody(cfg BodyProcessingConfig) (int, *ContextError)

ProcessRegularMsgBody validates and unmarshals a request body according to the provided configuration. It returns the error HTTP status code (or -1 if none) and any ContextError encountered.

func ReadBody

func ReadBody(buf io.Writer, ctx core.Context, maxBytes int64) *ContextError

ReadBody reads the request body from ctx into buf, enforcing the given maxBytes limit. It returns a ContextError on timeout or size violation.

func (*ContextError) Error

func (e *ContextError) Error() string

Error returns the error message string.

type FindResult

type FindResult[T comparable] struct {
	Paths []FindResultPath[T]
}

FindResult holds the results of a recursive type scan, mapping struct field paths to their discovered values.

func (*FindResult[T]) Every

func (r *FindResult[T]) Every(v reflect.Value, f func(reflect.Value, T))

Every traverses the value v and calls f for each field that matched during the original type scan, recursing into slices and maps.

func (*FindResult[T]) EveryPB

func (r *FindResult[T]) EveryPB(pb *core.PathBuffer, v reflect.Value, f func(reflect.Value, T))

EveryPB is like Every but also tracks the JSON/parameter path in pb for use in validation error reporting.

type FindResultPath

type FindResultPath[T comparable] struct {
	Path  []int
	Value T
}

FindResultPath pairs a struct field index path with its associated value found during type traversal.

type HeaderInfo

type HeaderInfo struct {
	Field      reflect.StructField
	Name       string
	TimeFormat string
}

HeaderInfo describes a response header field, including the struct field it maps to, the HTTP header name, and an optional time format string.

type InputMeta

type InputMeta struct {
	Params             *FindResult[*ParamFieldInfo]
	InputBodyIndex     []int
	HasInputBody       bool
	RawBodyIndex       []int
	InSchema           *core.Schema
	Resolvers          *FindResult[bool]
	Defaults           *FindResult[any]
	MultipartFields    []MultipartFieldInfo
	MultipartBodyIndex []int
}

InputMeta holds metadata about a request input type, including parameter locations, body schema, resolvers, and default values.

func AnalyzeInput

func AnalyzeInput[I any](op *core.Operation, registry core.Registry, fieldsOptionalByDefault bool) *InputMeta

AnalyzeInput inspects the input type I and populates the operation's OpenAPI metadata (parameters, request body, schemas) while returning an InputMeta that the runtime uses to bind request data.

type IntoUnmarshaler

type IntoUnmarshaler = func(data []byte, v any) error

IntoUnmarshaler is a function type that deserializes bytes into a value.

type MultipartFieldInfo

type MultipartFieldInfo struct {
	Name        string
	Index       []int
	IsFile      bool
	IsSlice     bool
	Required    bool
	Type        reflect.Type
	StructField reflect.StructField
}

MultipartFieldInfo describes a single field within a multipart form body, including its form name, struct index path, and whether it represents a file upload.

func AnalyzeMultipartFields

func AnalyzeMultipartFields(t reflect.Type) []MultipartFieldInfo

AnalyzeMultipartFields inspects a struct type and returns metadata for each exported field that has a "form" tag, identifying file uploads and value fields.

type MultipartFormFiles

type MultipartFormFiles[T any] struct {
	// contains filtered or unexported fields
}

MultipartFormFiles wraps a struct type T whose fields represent multipart form file uploads.

func (*MultipartFormFiles[T]) Data

func (m *MultipartFormFiles[T]) Data() T

Data returns the underlying struct containing the parsed form file fields.

type MultipartProcessingConfig

type MultipartProcessingConfig struct {
	Value  reflect.Value
	Fields []MultipartFieldInfo
}

MultipartProcessingConfig holds the parameters for processing a multipart form request into the target struct value.

type OutputMeta

type OutputMeta struct {
	Headers     *FindResult[*HeaderInfo]
	StatusIndex int
	BodyIndex   int
	BodyFunc    bool
}

OutputMeta holds metadata about a response output type, including header locations, status code index, and body field index.

func AnalyzeOutput

func AnalyzeOutput[O any](op *core.Operation, registry core.Registry) *OutputMeta

AnalyzeOutput inspects the output type O and populates the operation's OpenAPI response metadata (status codes, headers, body schema) while returning an OutputMeta that the runtime uses to write responses.

type ParamFieldInfo

type ParamFieldInfo struct {
	Type       reflect.Type
	Name       string
	Loc        string
	Required   bool
	Default    string
	TimeFormat string
	Explode    bool
	Style      string
	Schema     *core.Schema
	IsPointer  bool // true when the original field is a pointer type (#393)
}

ParamFieldInfo describes a single parameter field, including its type, name, location (path/query/header/cookie), default value, and serialization style.

type ParamLocation

type ParamLocation struct {
	Explode *bool
	PFI     *ParamFieldInfo
}

ParamLocation pairs a ParamFieldInfo with its explode setting for OpenAPI parameter documentation.

type ParamReactor

type ParamReactor interface {
	OnParamSet(isSet bool, parsed any)
}

ParamReactor is implemented by types that need to be notified after a parameter is bound, receiving whether the parameter was present and its parsed value.

type ParamWrapper

type ParamWrapper interface {
	Receiver() reflect.Value
}

ParamWrapper is implemented by types that wrap a parameter value and provide the actual reflect.Value that should receive the parsed data.

Jump to

Keyboard shortcuts

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