httpkit

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 28, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func Canceled

func Canceled(ctx context.Context)

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

func RenderError(r *http.Request, err error) apperr.Response

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

func Routed(ctx context.Context, op, route string)

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

func Serve(ctx context.Context, srv *http.Server) error

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 WithErrorHeaders added in v0.12.0

func WithErrorHeaders(h http.Handler, headers func(http.ResponseWriter, *http.Request, error)) http.Handler

WithErrorHeaders calls headers with the original error before WriteError commits a response within h. The callback may only set response headers; it must not write a status or body. Errors rendered inside a committed stream do not call it. A nil callback leaves h unchanged.

func Wrap

func Wrap(h http.Handler, cfg Config) http.Handler

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.

func WriteJSON

func WriteJSON(w http.ResponseWriter, status int, v any)

WriteJSON writes v as a JSON response, never cached: every response is per caller.

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

func (cs Codes) Render(err error, requestID string) apperr.Response

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.

func (Codes) Served

func (cs Codes) Served(c apperr.Code) apperr.Code

Served is the public code a client is answered with for c: its public code, when that is generic, in one of the server's namespaces or imported, and internal_server_error otherwise. A library's code nobody translated or imported therefore fails closed.

func (Codes) StatusOf

func (cs Codes) StatusOf(c apperr.Code) int

StatusOf is the HTTP status c is answered with: its served code's. A served code missing from Status is answered with 500; a server's test should keep that from happening.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL