foliot docs

Decisions / 0003 · Push tasks to apps over signed HTTP by default

ADR 0003: Push tasks to apps over signed HTTP by default; pull queues for the rest

Status: accepted · 2026-09-02

Context

SWF, Cadence and Temporal are pull-based: every team runs worker processes that long-poll for tasks. That is a second fleet to operate per tenant. Every Tin Bee service already has an HTTP surface.

Decision

By default Foliot POSTs each task to {handlerBaseUrl}/foliot/{workflow}/{step} with a Foliot-Signature header (HMAC-SHA256 over timestamp.body, Stripe-style), a deadline, the task token and a W3C traceparent whose trace id is the run id. A 200 with {output, next?} completes the step; a 202 defers it and the app later calls POST /tasks/{token}/complete or /fail; 4xx is permanent, 5xx and network errors retry. Steps that declare queue are offered to pull workers instead.

Consequences

  • Zero SDK needed to start; the SDK adds typed definitions, signature checking and idempotency replay.
  • Apps that cannot expose an endpoint use queue steps and POST /tasks/poll.
  • The app must be reachable from Foliot; that is the deployment constraint.