durable

Defines complex multi-step workflows using Elixir macros (workflow, step, branch, parallel, foreach) that compile to an AST-based execution plan persisted in PostgreSQL. The DSL abstracts control flow, state management, and resumability into composable building blocks, eliminating boilerplate for long-running processes. Workflows are defined as pure Elixir code with compile-time validation of step dependencies and control flow structure.

Persists complete workflow execution state (step results, context, execution history) to PostgreSQL after each step completes, enabling workflows to resume from the exact point of interruption after crashes, restarts, or arbitrary delays. Uses Ecto schemas (WorkflowExecution, StepExecution) to model workflow state as relational data with transactional consistency guarantees. Resumability is automatic—the execution engine queries persisted state and continues from the last completed step without explicit checkpointing logic.

Supports deploying Durable across multiple application instances with automatic concurrency control via database-level locking. When multiple instances attempt to execute the same workflow, the execution engine uses PostgreSQL row-level locks to ensure only one instance executes a given workflow step at a time. This enables horizontal scaling without a central coordinator. The execution engine polls for available work (steps ready to execute) and acquires locks before execution, ensuring distributed safety.

Provides comprehensive observability into workflow execution via two mechanisms: (1) automatic log capture that records all step execution logs to the database, and (2) queryable workflow state that enables inspection of execution history, step results, and context at any point in time. Logs are captured from Elixir's Logger and associated with specific step executions. Workflow state can be queried via Ecto queries or API endpoints, enabling real-time monitoring and debugging of running workflows.

Provides extensible queue and message bus adapter interfaces, enabling custom implementations for step execution scheduling and event delivery. The default implementation uses PostgreSQL polling, but adapters can implement push-based scheduling (e.g., via RabbitMQ, Kafka) or custom event delivery mechanisms. Adapters implement a standard interface (enqueue, dequeue, publish, subscribe) and are plugged into the Durable supervision tree via configuration. This enables integration with existing message infrastructure without modifying core workflow logic.

Enables cancellation of running workflows via the cancel API, which marks the workflow as cancelled and triggers cleanup of associated resources. When a workflow is cancelled, the execution engine stops executing new steps, executes compensations for completed steps (in reverse order), and marks the workflow as cancelled in the database. Cancellation is asynchronous and resumable—if the application crashes during cancellation, the process resumes from the last completed compensation.

Provides per-step retry configuration with exponential, linear, constant, and custom backoff strategies. When a step fails, the execution engine automatically reschedules it based on the configured backoff function, max retry count, and jitter settings. Retries are persisted to the database, allowing workflows to survive transient failures (network timeouts, rate limits) without manual intervention. Backoff state is tracked in StepExecution records, enabling observability into retry attempts and failure patterns.

Enables workflows to pause execution and wait for external events (webhooks, user input, approvals) or time-based delays without holding system resources. Implements three wait primitives: wait_for_event (pause until external event arrives), wait_for_input (pause until user provides data), and wait_for_approval (pause until approval is granted). Paused workflows are stored in PostgreSQL with a WaitState record indicating the resume condition. The execution engine polls or subscribes to resume events and automatically continues the workflow when the condition is met.

Executes multiple steps concurrently using the parallel macro, with configurable join semantics (wait for all, wait for first, wait for N). The execution engine spawns Elixir processes for each parallel step, persists their results independently to PostgreSQL, and coordinates joining based on the specified strategy. Parallel execution is transparent to step logic—steps execute as normal Elixir functions, and the framework handles process spawning, result aggregation, and error propagation.

Implements conditional branching via the branch macro, which evaluates a condition function and selects one of multiple execution paths based on the result. Each branch is a separate workflow sub-graph with its own steps, retries, and error handling. The execution engine evaluates the condition at runtime, persists the selected branch to the database, and executes the chosen path. Branches can be nested and combined with other control flow primitives (parallel, foreach).

Implements collection iteration via the forEach macro, which executes a step or sub-workflow for each element in a collection. The execution engine iterates over the collection, spawning a step execution for each element with the element value in the context. Iteration state is persisted to the database, enabling workflows to resume from the last completed iteration after interruption. Supports both sequential and parallel iteration strategies.

Implements the saga pattern via compensation functions, which are executed in reverse order when a workflow fails to rollback distributed transactions. Each step can define a compensate function that undoes the step's effects (e.g., refund a payment, delete a created resource). When a step fails and retries are exhausted, the execution engine executes compensations for all previously completed steps in reverse order. Compensations are persisted and resumable, ensuring rollback completes even if the application crashes.

Enables workflows to run on schedules using cron expressions via the Scheduler API. The execution engine maintains a schedule table in PostgreSQL and periodically checks for due schedules, spawning new workflow instances at the scheduled times. Schedules can be created, updated, and deleted via API calls. Scheduled workflows are treated as normal workflow instances with full durability and observability. The scheduler uses a polling mechanism (configurable interval) to detect due schedules.

Enables workflows to spawn and coordinate child workflows via parent-child relationships. A parent workflow can spawn one or more child workflows, wait for their completion, and aggregate their results. Child workflows are independent workflow instances with their own execution state, retries, and error handling, but their lifecycle is tied to the parent. The execution engine tracks parent-child relationships in the database and handles cascading cancellation and error propagation.