Documentation
¶
Overview ¶
Package httpserver builds the HTTP transport every service in this repo runs on: CORS, access logging with correlation IDs, panic recovery, and the Serve/Shutdown lifecycle pkg/boot.Service expects. A service package supplies only its own routes and gets the rest for free instead of rebuilding http.Server and its middleware chain by hand.
One Server hosts any number of Registrations on one mux behind one CORS and access-logging layer; http.ServeMux precedence decides which route a request gets, and panics at boot on a pattern two of them claim. The routes a Registration declares public get the public CORS policy instead.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Check ¶ added in v1.86.1
Check reports whether a registration can serve; a non-nil error says why not. It runs on every merged /health request, so it must be cheap and bounded, e.g. a database ping with its own timeout.
type Config ¶
type Config struct {
Name string
Component string
Address string
CORS config.CORSConfig
Timeouts config.HTTPDefaults
// Metrics, when non-nil, adds request metrics to the chain. Set by
// pkg/boot.Boot for every service, so a service package never decides
// whether its HTTP surface is instrumented.
Metrics *metrics.Metrics
// Registrations are the hosted services: one for a standalone binary.
Registrations []Registration
}
Config is what pkg/boot.Boot builds from Registrations plus what only the platform layer decides: name, listen address, and the CORS/timeout defaults every HTTP server in this repo shares.
type PublicRoute ¶ added in v1.135.0
PublicRoute is one exact path any origin may call without credentials, with the methods and request headers a preflight for it may ask for.
type Registration ¶
type Registration struct {
// SetupRoutes registers the service's handlers on mux. Required.
SetupRoutes func(mux *http.ServeMux)
// HealthCheck is what Merge folds into the consolidated binary's one
// /health; a registration without one counts as healthy there. New does
// not read it: a service running alone serves its own health route from
// SetupRoutes.
HealthCheck Check
// Closers are closed, in order, after the HTTP server has shut down.
Closers []io.Closer
// PublicRoutes are served under config.PublicCORS instead of the
// configured policy; see withCORS. A route here must still be registered
// in SetupRoutes.
PublicRoutes []PublicRoute
}
Registration is what a service provides: its routes, never the transport around them.
func Merge ¶ added in v1.86.1
func Merge(first Registration, rest ...Registration) Registration
Merge hosts several registrations as one, for the consolidated binary. Each registration's routes live on their own mux and a request goes to the first one, in argument order, with a matching route; a path two of them claim therefore does not panic at boot. The merged /health shadows theirs with the body auth's own /health sends, ok only when every HealthCheck passes. Closers and PublicRoutes are concatenated.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
func New ¶
New builds a Server hosting cfg.Registrations. Like http.ServeMux it panics on programmer error: an empty registration list, or a pattern two registrations both claim. It returns an error only if the request metrics can't be registered.
Source Files