Documentation
¶
Overview ¶
Package handler is part of the GoFastr framework. See https://github.com/DonaldMurillo/gofastr for documentation.
Index ¶
- func Bind(r *http.Request, dst any) error
- func CheckObjectKeys(data []byte, fold func(string) string) error
- func CheckTopLevelKeys(data []byte, fold func(string) string) error
- func DecodeStrict(r io.Reader, dst any) error
- func GetLogger(ctx context.Context) (any, bool)
- func GetRequestID(ctx context.Context) (string, bool)
- func GetTenant(ctx context.Context) (any, bool)
- func GetUser(ctx context.Context) (any, bool)
- func HandlerAdapter[I, O any](h Handler[I, O]) http.HandlerFunc
- func IsCrossSiteRequest(r *http.Request) bool
- func IsCrossSiteRequestStrict(r *http.Request) bool
- func IsForgeableRequest(r *http.Request) bool
- func RequestFromContext(ctx context.Context) (*http.Request, bool)
- func Respond(w http.ResponseWriter, r *http.Request, out any)
- func SSEStream(w http.ResponseWriter, events <-chan SSE)
- func SetLogger(ctx context.Context, logger any) context.Context
- func SetRequestID(ctx context.Context, id string) context.Context
- func SetTenant(ctx context.Context, tenant any) context.Context
- func SetUser(ctx context.Context, user any) context.Context
- func UnmarshalStrict(data []byte, dst any) error
- func WriteError(w http.ResponseWriter, err error)
- type Error
- type HTML
- type Handler
- type RawBytes
- type ResponseType
- type SSE
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bind ¶
Bind populates dst by merging values from all sources: 1. Header values (via `header:"X-Request-ID"` tag) 2. Query parameters (via `query:"name"` tag) 3. Path parameters (via `path:"id"` tag) 4. JSON body (decodes entire struct, highest priority)
If the request has a JSON body and Content-Type is application/json, the body is decoded first. Then query/path/header values fill in any zero-valued fields.
If the body is present but not valid JSON, a 400 error is returned. If dst is not a pointer, Bind panics.
func CheckObjectKeys ¶ added in v0.82.0
CheckObjectKeys is CheckTopLevelKeys applied to every object at every nesting depth: no object anywhere in the value may repeat a key or hold two keys that fold to the same name. Non-object values and tokenisation failures return nil so the caller's decoder reports them under its own error contract.
func CheckTopLevelKeys ¶ added in v0.82.0
CheckTopLevelKeys walks the top level of a JSON object and refuses any key that repeats, or that collides with an earlier key once both are passed through fold. Callers with their own key normalisation (crud folds camelCase and snake_case spellings of one column onto each other) pass that normaliser as fold; nil means exact keys only. Non-object bodies and tokenisation failures return nil so the caller's decoder reports them under its own error contract.
func DecodeStrict ¶ added in v0.82.0
DecodeStrict reads one JSON value from r into dst with the same top-level key rule Bind applies to request bodies, for every decode site that is not a plain handler.Bind consumer: JSON-RPC envelopes, websocket frames, buffered bodies replayed through a helper, dev-tool endpoints. Stdlib encoding/json keeps the LAST duplicate key and matches struct tags case-insensitively, so {"action":"safe", "Action":"danger"} runs the second action while a reviewer (or an intercepting log) reads the first. The ambiguity itself is the bug; refusing it is the only resolution that does not privilege one parser's pick.
Struct destinations: every top-level key must exactly match a json tag (case-folded spellings and unknown keys are refused, as Bind does) and no key may repeat. Map and other destinations: no key may repeat, and no two keys may fold to the same name under ASCII case folding. Bodies that are not a top-level object decode unchanged. Errors are *Error with code 400, so a handler can hand them to respond/Error directly.
Size is the caller's job: wrap the reader in http.MaxBytesReader (or io.LimitReader) before calling. The probes that pinned each surface live beside the callers as *_security_test.go.
func GetRequestID ¶
GetRequestID retrieves the request ID from the context.
func HandlerAdapter ¶
func HandlerAdapter[I, O any](h Handler[I, O]) http.HandlerFunc
HandlerAdapter bridges a typed Handler into a standard http.HandlerFunc. It handles input binding, panic recovery, and output serialization.
func IsCrossSiteRequest ¶ added in v0.85.0
IsCrossSiteRequest reports whether the request came from another origin, using Fetch Metadata first and the Origin header as the fallback. This is the ONE implementation of the repo's cross-site form guard; every battery and tool that refuses cross-site POSTs calls it and keeps only its own response shape.
Sec-Fetch-Site is authoritative where the browser sends it: "same-origin" and "none" (a user-initiated navigation: address bar, bookmark) are safe, "cross-site" is refused outright. "same-site" is NOT proof of same-origin: the site computation drops the port and folds sibling subdomains, so a page on evil.example.com (or on a sibling port of a localhost tool) is same-site while its Origin names a different origin, and a SameSite cookie still attaches. It falls through to the Origin-host comparison, as does any unknown value. Two copies of this guard (battery/setup, kiln/chat) trusted "same-site" and were driven to an attacker-owned admin account and an approved destructive plan by the 2026-09-06 probes; the copies are gone.
Without Fetch Metadata, an Origin whose host differs from r.Host is cross-site. An absent or opaque ("null") Origin cannot prove an attack and is allowed: a legitimate top-level same-origin form navigation sends Origin: null too, and non-browser clients (curl, tests, native apps) send neither header.
func IsCrossSiteRequestStrict ¶ added in v0.85.0
IsCrossSiteRequestStrict is IsCrossSiteRequest for surfaces that are only ever called by fetch(), never by a form navigation: there an opaque "Origin: null" with no Fetch Metadata to vouch for it is the sandboxed-iframe / cross-origin-redirect shape, not a legitimate top-level navigation, so it is refused too. Where the browser sends Sec-Fetch-Site the header decides exactly as in IsCrossSiteRequest.
func IsForgeableRequest ¶ added in v0.85.0
IsForgeableRequest reports whether a cross-site page could have sent this request WITHOUT a CORS preflight: the CORS "simple request" content types plus the absent header (a bodyless fetch() sends no Content-Type). application/json and every other type are not forgeable: a cross-site POST carrying one is preflighted.
func RequestFromContext ¶
RequestFromContext retrieves the *http.Request stored by HandlerAdapter.
func Respond ¶
func Respond(w http.ResponseWriter, r *http.Request, out any)
Respond writes out the response based on out's type:
- nil → 204 No Content
- ResponseType → delegates to the custom type
- any other value → JSON serialization, 200 OK
func SSEStream ¶
func SSEStream(w http.ResponseWriter, events <-chan SSE)
SSEStream writes a channel of SSE events as a streaming response.
func SetRequestID ¶
SetRequestID stores a request ID in the context.
func UnmarshalStrict ¶ added in v0.82.0
UnmarshalStrict is DecodeStrict over bytes already in memory (a websocket frame, a buffered body).
func WriteError ¶
func WriteError(w http.ResponseWriter, err error)
WriteError writes a structured error response to w.
An *Error is rendered verbatim (its Code, Message, and Fields are what the developer chose to expose). Any other error type is treated as an internal failure: the response message is a generic "internal server error" with status 500, and the original error stays out of the response body. Callers that *do* want the inner message to reach the client must wrap explicitly via Errorf or WrapError (the latter keeps the cause for `errors.Is/As` without leaking it).
This prevents accidental leaks of database errors, driver-specific strings ("pq: password authentication failed for user \"admin\""), or wrapped stack traces.
Types ¶
type Error ¶
type Error struct {
Code int // HTTP status code
Message string // human-readable message
Err error // wrapped cause (optional)
Fields map[string][]string // field-level validation errors (optional)
}
Error is a structured HTTP error with optional field-level validation errors.
func ValidationError ¶
ValidationError creates a 400 error with field-level validation messages.
type HTML ¶
type HTML string
HTML is a response type that writes text/html.
func (HTML) ContentType ¶
type Handler ¶
Handler is a typed function that processes an input of type I and returns an output of type O. It receives a context (which carries the *http.Request via RequestFromContext) and a fully-bound input struct.
type RawBytes ¶
RawBytes is a response type for raw bytes with an explicit content type.
func (RawBytes) ContentType ¶
type ResponseType ¶
type ResponseType interface {
// ContentType returns the MIME type for the response.
ContentType() string
// WriteBody writes the response body to w.
WriteBody(w http.ResponseWriter) error
}
ResponseType is an interface for custom response types that control how they are serialized and what Content-Type is used.
Source Files