Documentation
¶
Overview ¶
Package httpkit is what every HTTP server built on the anfra packages shares: the request id, the root span, the request log line, panic recovery, and the one renderer of an error, with the HTTP status of each code served. apikit's HTTP adapter renders through it, and so do servers that are not op APIs (the git service of anfra-cloud, say).
It holds nothing a particular server decides: its catalog of codes and their statuses are passed in (Codes), and routing, credentials, CSRF and body limits stay with the server that needs them.
Index ¶
- func Canceled(ctx context.Context)
- func RenderError(r *http.Request, err error) apperr.Response
- func Routed(ctx context.Context, op, route string)
- func Serve(ctx context.Context, srv *http.Server) error
- func Wrap(h http.Handler, cfg Config) http.Handler
- func WriteError(w http.ResponseWriter, r *http.Request, err error)
- func WriteJSON(w http.ResponseWriter, status int, v any)
- type Codes
- type Config
- type RetryAfter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Canceled ¶
Canceled records that the client went away before a response: the log line says so, at info, and nothing is written to it.
func RenderError ¶ added in v0.11.1
RenderError is an error as WriteError would answer it, for a response that has already begun — a stream, whose status is sent — to carry in its body. It records the error for the request's log line, as WriteError does.
func Routed ¶
Routed records the operation a request was routed to: op names it on the log line, and route (POST-only, so "/api/<op>" or "/rpc/<name>") names the root span and labels the request's metrics. An unrouted request keeps its method alone, so a stream of junk paths cannot create a span name or metric series each.
func Serve ¶
Serve runs srv until ctx ends, then drains it, giving in-flight requests ten seconds. A listener that fails — the port taken, say — ends it too, with that error.
func Wrap ¶
Wrap puts the shared middleware in front of h, outermost first: request id, root span, request log line, recovery. A handler inside reports what the log line and the span cannot see for themselves through Routed and Canceled, and renders every error through WriteError.
func WriteError ¶
func WriteError(w http.ResponseWriter, r *http.Request, err error)
WriteError is the one place an HTTP error is rendered: the public code's status, the envelope, and Retry-After when the details know it. It records the error for the request's log line.
Types ¶
type Codes ¶
type Codes struct {
// Namespaces are the server's own catalogs.
Namespaces []apperr.Namespace
// Imported are a library's public codes the server serves as they are, one
// by one: a library whose contract is the server's for the operations it
// serves, as the engine's is a hosted server's for the engine's ops. The library's other
// codes still fail closed.
Imported []apperr.Code
// Status is the status of each of their public codes. The generic codes'
// statuses are known here.
Status map[apperr.Code]int
}
Codes is what a server answers its clients with: the public codes of its own namespaces, besides apperr's generic ones, which every server serves, and the HTTP status of each. A code carries no status: only served codes reach the wire, and HTTP is the one transport that has a status to give them.
func (Codes) Render ¶
Render is err's wire form: the response of its served code, with that code's status. The status is HTTP's, repeated in the body so the body is the same over every transport.
type Config ¶
type Config struct {
Logger *slog.Logger // slog.Default() when nil
// Codes are what the server serves: every error is rendered, and logged, as
// its served code.
Codes Codes
// TrustTraceparent continues a caller's trace, for a server whose callers are
// this deployment's own services. Otherwise the endpoint is public: a caller's
// traceparent is kept as a link, and the request starts a trace of ours.
TrustTraceparent bool
}
Config is what a server tells the shared middleware about itself.
type RetryAfter ¶
type RetryAfter interface{ RetryAfterSeconds() int }
RetryAfter is implemented by error details that know how long a client should wait before trying again; WriteError sends it as the Retry-After header.