rest

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

type BuilderOption func(*Builder)

type Info = openapi.Info

type InvalidPathError struct {
	Path string // the path that failed validation
	Err  error  // the underlying constraint or codec error
}

type InvalidPathParamError struct {
	Name string // the variable name (without braces) that is not in the template
	Path string // the path template that was validated against
}

type MissingPathVarError struct {
	Name string // the variable name (without braces) that had no value
}

type Param = route.Param

type PathParam struct {
	Name        string
	Description string
	// Codec validates substituted values at [RouteHandle.BuildPath] time.
	// When non-nil, the codec's schema is also used in the OpenAPI spec.
	// Nil means no runtime validation; the spec schema will be empty.
	Codec *codex.Codec[string]
}

type PathParamError struct {
	Name  string // variable name without braces, e.g. "id"
	Value string // the value that failed validation
	Err   error  // the underlying constraint or codec error
}

type ResponseMeta struct {
	Status      string // e.g. "400", "404", "default"
	Description string
	Schema      *schema.Schema // nil for description-only responses (e.g. 404)
	SchemaName  string         // non-empty → $ref in spec
}

type RouteConfig struct {
	OperationID string
	Summary     string
	Description string
	Tags        []string

	// PathParams describes {varName} placeholder variables in the path template.
	// Each entry can add a description and/or a codec for runtime validation.
	// The codec schema is also used in the OpenAPI path parameter spec.
	//
	// PathParams is optional: the builder auto-generates a minimal parameter
	// entry for every {varName} in the path. Only specify PathParams when you
	// need a description or runtime validation for a specific variable.
	//
	// Entry names must correspond to {varName} placeholders in the path template;
	// unknown names cause [AddRoute] to return an error immediately.
	PathParams []PathParam

	// QueryParams are included in the OpenAPI spec as query parameters.
	QueryParams []route.Param

	// ReqSchemaName, when non-empty, emits a $ref for the request body schema
	// in the spec and registers the schema under that name in components/schemas.
	ReqSchemaName string

	// RespStatus is the HTTP status code for the primary success response.
	// Defaults to "201" for POST, "200" for all other methods.
	RespStatus string

	// RespDescription is the description for the primary success response.
	RespDescription string

	// RespSchemaName, when non-empty, emits a $ref for the response schema.
	RespSchemaName string

	// Responses are additional response entries (error codes, etc.) appended
	// after the primary success response in the spec.
	Responses []ResponseMeta
}

type RouteHandle[Req, Resp any] struct {
	// Descriptor is the frozen route.Route built at registration time.
	// Use it to inspect method, path, parameters, and spec metadata.
	Descriptor route.Route

	// Decode deserialises and validates a JSON request body into Req.
	// All Refine constraints on the request codec run automatically.
	Decode func(body []byte) (Req, error)

	// Encode serialises Resp to JSON bytes.
	Encode func(resp Resp) ([]byte, error)
	// contains filtered or unexported fields
}

type Server = openapi.Server