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 ¶
- Variables
- func GetParamValue(p ParamFieldInfo, ctx core.Context, cookies map[string]*http.Cookie) string
- func HasMultipartFields(t reflect.Type) bool
- func IsMultipartFormFilesType(t reflect.Type) bool
- func ParseDeepObjectQuery(query url.Values, name string) map[string]string
- func ParseInto(ctx core.Context, f reflect.Value, value string, preSplit []string, ...) (any, error)
- func SetDeepObjectValue(pb *core.PathBuffer, res *core.ValidateResult, f reflect.Value, ...) map[string]any
- func SetupMultipartRequestBody(op *core.Operation, registry core.Registry, fields []MultipartFieldInfo)
- func WriteHeader(write func(string, string), info *HeaderInfo, f reflect.Value)
- func WriteResponse(api core.API, ctx core.Context, status int, ct string, body any) error
- func WriteResponseWithPanic(api core.API, ctx core.Context, status int, ct string, body any)
- type BodyProcessingConfig
- type ContextError
- type FindResult
- type FindResultPath
- type HeaderInfo
- type InputMeta
- type IntoUnmarshaler
- type MultipartFieldInfo
- type MultipartFormFiles
- type MultipartProcessingConfig
- type OutputMeta
- type ParamFieldInfo
- type ParamLocation
- type ParamReactor
- type ParamWrapper
Constants ¶
This section is empty.
Variables ¶
var ErrUnparsable = errors.New("unparsable value")
ErrUnparsable is returned when a value cannot be parsed into the target type.
Functions ¶
func GetParamValue ¶
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 ¶
HasMultipartFields reports whether the struct type t contains any exported fields with a "form" tag that represent file uploads.
func IsMultipartFormFilesType ¶
IsMultipartFormFilesType reports whether t is a MultipartFormFiles wrapper type.
func ParseDeepObjectQuery ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
ParamWrapper is implemented by types that wrap a parameter value and provide the actual reflect.Value that should receive the parsed data.