Documentation
¶
Overview ¶
Package ingress accepts inbound flow requests. See design docs/plans/2026-06-24-flow-engine-design.md §18.3.
Authorization model — NO cross-run tenancy. The ingress has NO notion of run ownership or tenant isolation: any caller that passes WithAuth (or any caller at all, when no authenticator is configured) may resume, get, or cancel ANY run id. The only thing protecting one caller's run from another is the UNGUESSABILITY of the GraphRunID (a crypto/rand UUIDv4, §18.3) — there is no per-run access check. A deployment that needs real tenancy/authorization MUST enforce it in the WithAuth authenticator (e.g. derive the tenant from the request and reject ids outside it) or in a fronting proxy; the ingress will not do it for you. This is by design (CLAUDE.md: the auth policy is the caller's, wired at the composition root); a built-in ownership model is out of scope here.
Index ¶
Constants ¶
const DefaultMaxBodyBytes int64 = 1 << 20
DefaultMaxBodyBytes bounds a decoded request body unless WithMaxBodyBytes overrides it (§18.3, CLAUDE.md: guard against unbounded input). 1 MiB is a sane default for an initial-state / resume-payload JSON.
Variables ¶
This section is empty.
Functions ¶
func New ¶
func New(reg *registry.Registry, cp flow.ControlPlane, store flow.CheckpointStore, opts ...Option) http.Handler
New returns an async-first REST http.Handler over reg, cp, and store (§18.3). It registers the §18.3 routes on a stdlib ServeMux using Go 1.22+ method+pattern routing and wraps the whole mux in the auth and error-recovery middleware. The idempotency map is the in-process (Tier-B) dedupe tier; durable cross-restart idempotency is the NATS layer (Phase 9).
func Server ¶
Server returns an *http.Server bound to addr serving h with SECURE DEFAULTS (§18.3, CLAUDE.md): explicit non-zero ReadHeaderTimeout/ReadTimeout/ WriteTimeout/IdleTimeout (a slow-client / Slowloris guard that the Handler alone cannot set — only the http.Server can), and a TLSConfig pinning MinVersion to TLS 1.2. Callers SHOULD use this (or set equivalent timeouts) rather than a bare &http.Server{Handler: h}. ServerOptions can override any default.
Types ¶
type Option ¶
type Option func(*config)
Option configures the ingress handler at New (§18.3). It is the functional- options seam (CLAUDE.md: wire dependencies at the composition root); a new knob is a new Option with zero edits to existing callers (open/closed).
func WithAuth ¶
WithAuth installs a caller-supplied authenticator applied to EVERY route (§18.3): a non-nil return rejects the request with 401. The ingress NEVER bakes in a scheme — the default is no auth (every request is allowed), which a caller must opt out of by supplying an authenticator (CLAUDE.md: least privilege; the auth policy is the caller's, wired at the composition root). A nil authn is ignored (stays no-auth).
func WithMaxBodyBytes ¶
WithMaxBodyBytes sets the per-request body-size limit in bytes (§18.3). A value <= 0 is ignored (the DefaultMaxBodyBytes stays in force), so a caller cannot accidentally disable the unbounded-input guard.
func WithVerboseErrors ¶
func WithVerboseErrors() Option
WithVerboseErrors surfaces the RAW task/halt error strings in a GET /v1/runs/{id} response (M1). It is OFF by default (fail secure): an Errored interruption's Cause and a Halt's Cause are a task's own error message, which can carry PII or payload fragments, and GET is a WIRE BOUNDARY — by default the handler renders a generic, non-leaking token (the interrupt/halt kind) instead. Enable this ONLY in a trusted/debug deployment where the raw cause is acceptable on the wire. Task error messages should never carry secrets regardless (CLAUDE.md: no secrets on the wire).
type ServerOption ¶
ServerOption configures the secure Server helper (§18.3). It is a separate option type from Option so the handler's knobs and the server's transport knobs stay segregated (interface segregation).
Source Files