Documentation
¶
Overview ¶
Package gateway is the ingress / API gateway port (ADR-0012): program routes declaratively and serve them as an http.Handler that reverse-proxies a matched public path to a function's worker upstream.
The port is driver-independent and imports no gateway-framework library. A single in-process driver implements it: the embedded net/http/httputil reverse-proxy (internal/gateway/embedded) — pure-Go, streaming-native, and the production and in-memory driver alike (ADR-0013 made it primary; ADR-0029 dropped the optional Lura driver — an external-gateway driver is the V2 second driver). The activator (scale-from-zero buffering, ADR-0016) is a separate component that plugs in as a Route.Upstream.
Index ¶
Constants ¶
const WriteStallTimeout = 60 * time.Second
WriteStallTimeout is how long a data-plane response write may wait for the client to accept data.
Variables ¶
This section is empty.
Functions ¶
func Chain ¶
func Chain(h http.Handler, mw ...Middleware) http.Handler
Chain applies middlewares around h in declared order: Chain(h, a, b) runs a (outermost), then b, then h. A middleware that responds without calling next short-circuits the rest of the chain.
func Interim ¶ added in v0.6.1
Interim reports whether code is a 1xx that a final status follows (101 ends the exchange). httputil.ReverseProxy relays an upstream 1xx through the edge writers before the final status.
func RequestID ¶
RequestID is a middleware that ensures every request carries an X-Request-Id: it reuses an inbound id or mints one, echoes it on the response, and stores it in the request context (RequestIDFromContext reads it).
func RequestIDFromContext ¶
RequestIDFromContext returns the request id set by RequestID, or "" if none.
Types ¶
type Gateway ¶
type Gateway interface {
// ProgramRoutes replaces the live route table with the desired set.
ProgramRoutes(ctx context.Context, routes []Route) error
// Routes returns the currently programmed routes.
Routes(ctx context.Context) ([]Route, error)
// Handler returns the stable HTTP handler serving the programmed routes; it
// survives re-programs, so callers mount it once.
Handler() http.Handler
// Close releases the driver.
Close() error
}
Gateway is the ingress port: program routes declaratively and serve them as an http.Handler. Errors are api/fault; methods are ctx-first; the port imports no gateway-framework library. A route matches all HTTP methods in V1.
type Middleware ¶
Middleware wraps an http.Handler with one ingress concern (auth, rate-limit, recover, …). The composition root builds the gateway's served handler as Chain(gw.Handler(), Recover, RequestID, …) — see ADR-0013.
func Recover ¶
func Recover(logger *slog.Logger) Middleware
Recover returns a middleware that turns a handler panic into an RFC 9457 problem+json 500 instead of crashing the connection. As the operation's owner (ADR-0002 §3) it logs the panic once to logger (nil means slog.Default()), with its value, stack and request id; the client's problem omits the panic text. A panic is re-panicked when no problem can be written: http.ErrAbortHandler (net/http's signal to abort, e.g. a proxied stream whose upstream died mid-body), or any panic after the response committed (#338). net/http then aborts the connection, so the client sees the truncation, and logs any panic other than ErrAbortHandler.
func WriteStall ¶ added in v0.7.0
func WriteStall(d time.Duration) Middleware
WriteStall returns a middleware that bounds each response write by d: a client that accepts no data for d while the response has data to send fails the write, and net/http then closes the connection (HTTP/1.1) or resets the stream (HTTP/2). The deadline is in force only while a piece is being written or flushed, so a live stream of any length and a quiet stream are not cut. It is armed once more when next returns, also during a panic unwind, to bound net/http's final flush; net/http clears it on HTTP/1.1 once the response is finished, and the end of an HTTP/2 stream stops the stream's timer. d <= 0 returns next unchanged.
type Route ¶
type Route struct {
ID RouteID
Host string // optional host match ("" = any host)
PathPrefix string // e.g. "/function/echo"
Upstream string // upstream base URL, e.g. "http://10.63.0.5:8080"
}
Route maps a public path prefix (optionally host-qualified) to a function upstream. The gateway reverse-proxies a matched request to Upstream, stripping PathPrefix so the function is addressed at its own root.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package embedded implements the gateway.Gateway port with net/http/httputil — a hand-written reverse proxy behind a longest-prefix router (ADR-0012).
|
Package embedded implements the gateway.Gateway port with net/http/httputil — a hand-written reverse proxy behind a longest-prefix router (ADR-0012). |
|
Package gatewaycontract is the shared conformance suite for the gateway.Gateway port (ADR-0012).
|
Package gatewaycontract is the shared conformance suite for the gateway.Gateway port (ADR-0012). |