Skip to content

ADR-0044: Pipeline Pattern for Request Processing

  • Status: Accepted
  • Date: 2026-04-18
  • Supersedes: —
  • Superseded by: —

Context

The /invoke processing path currently lives in a single function in runtime.py. Authentication, rate limiting, input validation, Cedar policy evaluation, handler dispatch, provenance recording, cost tracking, and observability emission are all handled inline. This flat structure has several drawbacks:

  1. Testing is expensive. Exercising a single concern (e.g., policy evaluation) requires setting up the entire invoke context, because the concern is interleaved with everything else.
  2. Extension is fragile. Users who want to inject custom behaviour (audit logging, request transformation, tenant isolation) have no supported hook point. They resort to monkey-patching or wrapping the entire invoke function.
  3. Reordering is a code change. Moving rate limiting before auth (or vice versa) means editing deeply nested control flow rather than swapping two items in a list.
  4. Observability is tangled. Each concern emits its own events at ad-hoc points; there is no uniform lifecycle model for stages.

The Chain of Responsibility (Pipeline) pattern addresses all four: each concern becomes an isolated, testable stage that receives a shared mutable context and either processes it or aborts the pipeline.

Options considered

  1. Middleware stack (ASGI/WSGI style). Each middleware wraps the next, forming a nested call chain. Familiar but makes abort semantics awkward (must propagate exceptions through wrapper layers) and ordering is implicit in nesting depth.

  2. Event-driven hooks. Emit events at fixed points; listeners subscribe. Flexible but non-deterministic ordering, hard to abort early, and listeners cannot easily communicate via shared state.

  3. Linear pipeline of stages (this ADR). Stages execute in list order against a shared PipelineContext. Any stage can abort. Users insert/remove/reorder stages by name. Deterministic, testable, composable.

Decision

Adopt option 3: a composable Pipeline of Stage objects that process a PipelineContext in order.

Design

  • PipelineContext is a mutable dataclass carrying the capability id, arguments, principal, trace id, result, error, and an open metadata dict for inter-stage communication.
  • Stage is a protocol with a name: str attribute and an execute(ctx) -> None method.
  • Pipeline holds an ordered list of stages and provides add, insert_before, insert_after, and remove for composability.
  • Pipeline.execute(ctx) runs stages sequentially. If any stage sets ctx.aborted = True, subsequent stages are skipped.
  • A default_pipeline() factory returns the standard Trails request pipeline with all built-in stages in canonical order.

Built-in stages (canonical order)

  1. AuthStage — validate Bearer token
  2. RateLimitStage — per-IP rate limiting
  3. ValidationStage — validate arguments against @shape
  4. PolicyStage — evaluate Cedar policy
  5. InvokeStage — call the capability handler
  6. ProvStage — record PROV-O provenance
  7. CostStage — track cost
  8. ObservabilityStage — emit observability events

Extension point

Users insert custom stages at any position:

pipe = default_pipeline()
pipe.insert_after("auth", AuditLogStage())
pipe.insert_before("invoke", TenantIsolationStage())

Consequences

  • Each concern is independently testable with a minimal PipelineContext fixture — no full runtime setup required.
  • Custom stages can be added, removed, or reordered without modifying framework internals.
  • The pipeline module is standalone (trails.pipeline); wiring it into runtime.py and http_adapter.py is a separate, non-breaking step.
  • Stage ordering is explicit and visible in default_pipeline().
  • Slight runtime overhead from iterating a list of stages vs. a monolithic function; negligible for the I/O-bound workloads Trails targets.