Documentation
¶
Overview ¶
Package server assembles and runs a web service's HTTP handler: the application's routes, health probes, the problem type pages and the single-page app, behind the middleware every service needs.
Index ¶
Constants ¶
const DefaultContentSecurityPolicy = "default-src 'self'; " +
"img-src 'self' data:; " +
"object-src 'none'; " +
"base-uri 'self'; " +
"form-action 'self'; " +
"frame-ancestors 'none'"
DefaultContentSecurityPolicy allows only same-origin resources and no inline scripts or styles.
Variables ¶
This section is empty.
Functions ¶
func New ¶
New returns the service's root handler. It serves:
- the application's Routes;
- GET /healthz, always 200, and GET /readyz, 200 when every Ready pinger answers and 503 otherwise;
- a 404 problem for any path under APIPrefix that no route matches;
- the problem type pages at /problems/;
- the single-page app for everything else.
Every response gets security headers, including a strict CSP; while the app is proxied from DevServer, the CSP also accepts spa.DevNonce. Requests that change state are refused when a browser sent them from another site, which keeps cookie sessions safe from cross-site request forgery. Each request is logged, and a panic is logged and answered with a 500.
Types ¶
type Listen ¶
type Listen struct {
Addr string
// TLSCertFile and TLSKeyFile enable in-process TLS. When unset, TLS is
// terminated in front of the service.
TLSCertFile string
TLSKeyFile string
ShutdownTimeout time.Duration
}
Listen configures Serve.
type Options ¶
type Options struct {
// Logger records requests, panics and server errors. Defaults to
// slog.Default().
Logger *slog.Logger
// Routes registers the application's handlers, such as its huma API.
Routes func(mux *http.ServeMux)
// APIPrefix is where the API lives: a path under it that matches no
// route, or panics, is answered with a problem. Defaults to "/api/".
APIPrefix string
// Problems are the application's problem types, documented at /problems/.
Problems []*problem.Registry
// Messages and Docs are the application's problem messages and page
// guidance; the /problems/ pages use them in the reader's language, which
// Locales picks.
Messages []*problem.Catalog
Docs []*problem.Docs
// Ready is checked by /readyz. Nil pingers are skipped.
Ready map[string]Pinger
// Web is the built single-page app (see spa.Handler). Nil serves no app.
Web fs.FS
// DevServer is the Vite dev server, such as "http://localhost:5173".
// While Web holds no build, the app is proxied from it.
DevServer string
// BasePath is where a host mounts the application, such as "/tandem".
// The app's index.html gets a matching <base href>. Defaults to "/".
BasePath string
// Locales sets the app's <html lang> to the reader's language.
Locales spa.Locales
// ContentSecurityPolicy replaces DefaultContentSecurityPolicy.
ContentSecurityPolicy string
// HSTS sends Strict-Transport-Security, for a service reached over HTTPS.
HSTS bool
// Wrap wraps the routes inside the security middleware, for example to
// attach the authenticated caller to each request.
Wrap func(http.Handler) http.Handler
}
Options configure New.
Source Files