Documentation
¶
Overview ¶
Package api assembles Huma on Go's HTTP server with shared request policies.
Index ¶
- func Authenticated(a huma.API, authenticator Authenticator) huma.API
- func Bearer(authenticator Authenticator) func(huma.Context, func(huma.Context))
- func ClientIP(ctx context.Context) (string, error)
- func ClientIPKey(c huma.Context) (string, error)
- func CurrentUserID(ctx context.Context) (uuid.UUID, error)
- func Multipart(ctx huma.Context, next func(huma.Context))
- func ParseTrustedProxies(cidrs []string) ([]netip.Prefix, error)
- func PeerIP(ctx context.Context) (string, error)
- func PeerIPKey(c huma.Context) (string, error)
- func Principal(ctx context.Context) (auth.Principal, error)
- func RateLimit(limiter ratelimit.Limiter, limit ratelimit.Limit, ...) func(huma.Context, func(huma.Context))
- func RegisterHealthRoutes(router *http.ServeMux, ready, stopping <-chan struct{}, ...)
- func RequireCurrentUser(ctx context.Context, id uuid.UUID) error
- type Authenticator
- type Options
- type PaginationInput
- type Server
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Authenticated ¶
func Authenticated(a huma.API, authenticator Authenticator) huma.API
Authenticated keeps bearer enforcement and its OpenAPI security declaration together.
func Bearer ¶
func Bearer(authenticator Authenticator) func(huma.Context, func(huma.Context))
Bearer only accepts the Authorization header. Nil authentication fails closed. A database outage remains an operational error, never anonymous access.
func ClientIP ¶
ClientIP returns the address accepted at the HTTP boundary. With no trusted proxies it is the immediate peer. It is a rate-limit signal, not a principal.
func ClientIPKey ¶
ClientIPKey uses the address accepted by the server's trusted-proxy policy. Keep the key namespace stable for direct deployments upgrading this policy.
func CurrentUserID ¶
CurrentUserID returns the authenticated account ID without loading the account.
func Multipart ¶
Multipart bounds the complete request, spools files above 1 MiB to disk, and removes temporary files after Huma and the handler return, including on failure. Use RawBody multipart.Form and set the operation's MaxBodyBytes explicitly. Register after authentication; this middleware is the sole multipart reader.
func ParseTrustedProxies ¶
ParseTrustedProxies validates explicit IPv4/IPv6 CIDRs. Trusting all addresses would let arbitrary clients supply their own security rate-limit identity.
func PeerIP ¶
PeerIP returns the immediate peer captured by the HTTP boundary. Forwarding headers cannot change this value; trusted ingress needs an explicit policy.
func PeerIPKey ¶
PeerIPKey always uses the direct connection. Use ClientIPKey for trusted ingress. Arbitrary forwarding headers cannot change the budget. NAT clients share a limit.
func RateLimit ¶
func RateLimit(limiter ratelimit.Limiter, limit ratelimit.Limit, key func(huma.Context) (string, error)) func(huma.Context, func(huma.Context))
RateLimit applies one policy to a route group. Keys come from an explicit caller function; raw credentials and personal data should never be used as keys.
func RegisterHealthRoutes ¶
func RegisterHealthRoutes(router *http.ServeMux, ready, stopping <-chan struct{}, check func(context.Context) error)
RegisterHealthRoutes mounts unversioned health endpoints. App owns the signals: ready closes after startup; stopping closes before drain. Nil signals stay pending. Optional check must honor its context and impose a deadline. Only one check runs at a time; concurrent probes return 503 instead of adding dependency load. Dependency failures are deliberately not exposed in the response.
Types ¶
type Authenticator ¶
type Options ¶
type Options struct {
Title, Version string
// APIVersion identifies the business API in X-API-Version (default v1).
// Version above identifies the application release in the OpenAPI document.
APIVersion string
// DisableDocs hides both /docs and /openapi.json. They are enabled by default.
DisableDocs bool
Tracer trace.Tracer
Meter metric.Meter
// TrustTraceContext accepts remote trace parents from a trusted ingress.
TrustTraceContext bool
// TrustedProxies may supply X-Forwarded-For. Empty trusts no forwarding headers.
// The deployment must secure these proxy connections and sanitize the chain.
TrustedProxies []netip.Prefix
Middleware []func(http.Handler) http.Handler
}
Options configures a server without starting a listener. Zero values are usable. Middleware contains standard net/http middleware and runs inside observability.
type PaginationInput ¶
type PaginationInput struct {
Page int `query:"page" default:"1" minimum:"1"`
PerPage int `query:"per_page" default:"20" minimum:"1" maximum:"100"`
}
PaginationInput binds and validates pagination once, including ambiguous queries.
func (PaginationInput) Pagination ¶
func (in PaginationInput) Pagination() pagination.Pagination
type Server ¶
Server is a Huma API and an http.Handler. Mux accepts infrastructure handlers; modules register typed operations on the embedded API or native Huma groups. Finish all registration before serving. The application owns listener lifecycle.
Source Files
Directories