active_saga 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2bf52fe5b851576cd054d43f636cb86410c395d57737b6291c7bace1d6a9a43
+  data.tar.gz: c3c6ff1b642992fe0f70dc163ff6535f0fe62477fb854d810ff2de19207fc1e4
+SHA512:
+  metadata.gz: ccec4ca4cbc4b6e85a7a63dc667f0621a818046430b0772988e6785f84e5ffee49b081debf18a87536116725989cb5f296f85efc6dcfc436769f7b79638dc049
+  data.tar.gz: ae5f9a4576295244f9a8d2c9b09100b8bba352c41df97d2ea7637e014a4922513849be049476230a46f720b503e7d8052e99dc08123c9e3a8662b35c31bfb7e3

data/ADAPTERS.md

@@ -0,0 +1,63 @@
+# Store Adapters
+
+ActiveWorkflow persists workflow state through a strategy interface. This document explains the
+contract adapters must implement and the behaviours the engine expects.
+
+## Base Contract
+
+All adapters inherit from `ActiveWorkflow::Stores::Base` and must implement:
+
+- `start_execution(workflow_class:, context:, steps:, idempotency_key:, timeout:, metadata:)`
+- `load_execution(id)`
+- `process_execution(execution_id)`
+- `complete_step!(execution_id, step_name, payload:, idempotency_key:)`
+- `fail_step!(execution_id, step_name, error_class:, message:, details:, idempotency_key:)`
+- `extend_timeout!(execution_id, step_name, by:)`
+- `heartbeat!(execution_id, step_name, at:)`
+- `signal!(execution_id, name, payload:)`
+- `enqueue_runner(execution_id, run_at: nil)` – adapters may simply enqueue the internal runner job.
+- `cancel_execution!(execution_id, reason: nil)` – run compensations and cancel remaining steps.
+
+The methods must be **atomic**: never run business code outside a transaction or lock that protects
+against concurrent runners.
+
+## Step Lifecycle Responsibilities
+
+Adapters are responsible for:
+
+1. **Idempotency** – enforce unique workflow `idempotency_key` presence and step completion keys.
+2. **Exactly-once** step completion – step must transition `pending → running → completed` without
+   double execution when jobs retry.
+3. **Wait semantics** – async steps transition to `waiting` with timeout scheduling and resume only
+   via completion, failure, or timeout.
+4. **Retry bookkeeping** – store attempts, backoff, jitter, and next scheduled run.
+5. **Compensation triggering** – when execution fails terminally, invoke compensations in reverse
+   order.
+6. **Cancellation** – honour `cancel_execution!` requests by stopping progression, running
+   compensations, and marking remaining work cancelled.
+7. **Observability** – emit `ActiveSupport::Notifications` listed in the README.
+
+## Extending the ActiveRecord Store
+
+The built-in adapter is designed for relational databases and uses three tables:
+
+- `aw_executions` – workflow metadata and context.
+- `aw_steps` – per-step state machine and retry/timeout metadata.
+- `aw_events` – signal payloads awaiting consumption.
+
+If you need to customise the schema (prefixed table names, auditing columns), pass your own models or
+subclass the adapter. Ensure indexes that protect idempotency keys remain unique.
+
+## Testing Adapters
+
+Use the acceptance spec suite as a smoke test for new adapters. You can swap the store in
+`spec_helper.rb` to your implementation and assert the scenarios continue to pass:
+
+```ruby
+ActiveWorkflow.configure do |config|
+  config.store = MyRedisStore.new
+end
+```
+
+Because workflows rely on precise concurrency guarantees, add stress tests around jobs retrying,
+timeouts, and simulated crashes before deploying alternative stores to production.

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented here.
+
+## [0.1.0] - 2025-12-10
+
+- Initial release of ActiveWorkflow with ActiveRecord store, async steps, signals, retries, compensations, cancellation API, idempotency, and generators.

data/GUIDE.md

@@ -0,0 +1,80 @@
+# ActiveWorkflow Guide
+
+This guide expands on the README and focuses on advanced topics you will likely encounter when
+operating ActiveWorkflow in production.
+
+- [Security & Webhooks](#security--webhooks)
+- [Correlation Patterns](#correlation-patterns)
+- [Extending Stores](#extending-stores)
+- [Observability](#observability)
+
+## Security & Webhooks
+
+Async workflows commonly rely on webhook callbacks to call `ActiveWorkflow.complete_step!` or
+`ActiveWorkflow.fail_step!`. Treat these endpoints with the same rigor as payment webhooks:
+
+1. **Authenticate** inbound requests. Sign responses from your external system and verify via HMAC
+   in the controller before mutating workflow state.
+2. **Use correlation IDs**. The gem exposes `execution.id` and the step name. Pass a
+   deterministic correlation ID to your external service (for example `"#{execution.id}:export"`).
+3. **Enforce idempotency**. Always forward a business-level idempotency key (event id) and supply it
+   when calling `complete_step!`. The ActiveRecord store keeps the last key and will reject
+   conflicting attempts.
+4. **Rate-limit**. Protect the endpoints that mutate workflow state and monitor for abuse.
+
+Example controller snippet:
+
+```ruby
+class ExportsController < ApplicationController
+  before_action :verify_hmac!
+
+  def ready
+    ActiveWorkflow.complete_step!(params[:execution_id], :export,
+      payload: params.require(:payload).permit(:url),
+      idempotency_key: params[:event_id])
+    head :ok
+  rescue ActiveWorkflow::Errors::AsyncCompletionConflict
+    head :unprocessable_entity
+  end
+end
+```
+
+## Correlation Patterns
+
+ActiveWorkflow does not impose a single correlation strategy. Some battle-tested options:
+
+- **Execution scoped** – `"#{execution.id}:#{step_name}"` works well when the external system does
+  not need to know about your domain objects.
+- **Business scoped** – `"export:#{ctx[:user_id]}"` if a user can only have one export at a time.
+- **Composite** – combine execution and external ids to allow reconciliation jobs to find the
+  correct workflow.
+
+Whatever you choose, store the value either in `ctx` or the step's `init_result` and reuse it for
+timeouts, heartbeats, and compensations.
+
+## Extending Stores
+
+`ActiveWorkflow::Stores::Base` defines the contract for persistence. To write a custom adapter
+(Redis, DynamoDB…), inherit from the base class and implement:
+
+- `start_execution` – create an execution with initial steps and enqueue the runner job.
+- `load_execution` – return an `ActiveWorkflow::Execution` snapshot.
+- `process_execution` – pop and execute the next step atomically.
+- Async APIs – `complete_step!`, `fail_step!`, `extend_timeout!`, `heartbeat!`, `signal!`.
+
+The ActiveRecord store is heavily documented and can act as a reference implementation. When porting
+it ensure you preserve transactional guarantees around step dedupe, retries, and compensations.
+
+## Observability
+
+The store emits `ActiveSupport::Notifications` for every significant transition. Subscribe in your
+app and ship them to OpenTelemetry, Datadog, or logs. A simple logger subscriber looks like this:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/active_workflow\./) do |event|
+  Rails.logger.info({ name: event.name, payload: event.payload, duration: event.duration }.to_json)
+end
+```
+
+Use the events to drive SLIs (time-to-signal, retry depth, compensation rate) and to alert on stuck
+workflows (no heartbeat before timeout).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ActiveWorkflow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,473 @@
+# ActiveWorkflow
+
+A workflow engine with durable steps, automatic retries with backoff and jitter, compensations, async waits, signals, timeouts, idempotency, and pluggable persistence (ActiveRecord included).
+
+---
+
+## Table of Contents
+
+- [Why ActiveWorkflow?](#why-activeworkflow)
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Defining Workflows (3 equivalent styles)](#defining-workflows-3-equivalent-styles)
+  - [A) Method step](#a-method-step)
+  - [B) Task class](#b-task-class)
+  - [C) Inline block](#c-inline-block)
+- [Async Steps (vs Sync) – Concept & Lifecycle](#async-steps-vs-sync--concept--lifecycle)
+  - [Declaring async steps](#declaring-async-steps)
+  - [Completion/Failure/Timeout APIs](#completionfailuretimeout-apis)
+  - [Timeouts, retries, and re-initiation](#timeouts-retries-and-re-initiation)
+  - [Security, idempotency & race-safety](#security-idempotency--race-safety)
+  - [Sync vs Async comparison](#sync-vs-async-comparison)
+- [Signals & Waits](#signals--waits)
+- [Cancellation](#cancellation)
+- [Retries, Backoff & Jitter](#retries-backoff--jitter)
+- [Idempotency & Deduplication](#idempotency--deduplication)
+- [Configuration](#configuration)
+- [Persistence (Adapters)](#persistence-adapters)
+- [Active Job Integration](#active-job-integration)
+- [Observability (Events & Logging)](#observability-events--logging)
+- [Generators](#generators)
+- [Testing](#testing)
+- [Examples](#examples)
+- [Design Notes](#design-notes)
+- [License](#license)
+
+---
+
+## Why ActiveWorkflow?
+
+Most apps need reliable business workflows (sagas) with retries, compensations and “wait for an external thing (webhook/job)”—without operating a heavyweight orchestration service. **ActiveWorkflow** gives you that on plain Rails + Active Job.
+
+---
+
+## Features
+
+- **Flexible step definitions**: define workflow steps as methods, task classes, or inline blocks with identical semantics.
+- **Async steps**: start external work, persist correlation, **wait** for completion via API.
+- **Signals**: pause workflows until external events or triggers resume execution.
+- **Retries**: fixed/exponential backoff with jitter, per-step timeouts.
+- **Compensations**: reverse-order undo on cancel/failure.
+- **Cancellation**: explicit API to stop workflows, run compensations, and mark remaining work cancelled.
+- **Idempotency**: workflow-level keys + step dedupe + idempotent completions.
+- **Pluggable stores**: strategy interface; ships with **ActiveRecord**.
+- **Observability**: `ActiveSupport::Notifications` for steps, signals, retries, timeouts.
+
+---
+
+## Installation
+
+```bash
+# Gemfile
+gem "active_workflow"
+
+bundle install
+rails g active_workflow:install
+rails db:migrate
+```
+
+The installer creates:
+
+- `config/initializers/active_workflow.rb`
+- ActiveRecord migrations
+- Optional sample workflow
+
+---
+
+## Quick Start
+
+```ruby
+# config/initializers/active_workflow.rb
+ActiveWorkflow.configure do |c|
+  c.store      = ActiveWorkflow::Stores::ActiveRecord.new
+  c.logger     = Rails.logger
+  c.serializer = :json
+  c.clock      = -> { Time.now.utc }
+end
+```
+
+```ruby
+# app/workflows/checkout_flow.rb
+class CheckoutFlow < ActiveWorkflow::Workflow
+  idempotency_key { "checkout:#{ctx[:order_id]}" }
+  defaults retry: { max: 5, backoff: :exponential, jitter: true, first_delay: 1.second }
+  timeout 30.minutes
+
+  step :charge_card, compensate: :refund_payment, retry: { max: 6, first_delay: 2.seconds }
+  task :reserve_stock, ReserveStockTask, dedupe: true
+  task :send_receipt,  fire_and_forget: true do |ctx|
+    Mailers::Receipt.deliver_later(ctx[:order_id])
+  end
+
+  def charge_card
+    payment = PSP.charge!(order_id: ctx[:order_id], token: ctx[:payment_token])
+    ctx[:payment_id] = payment.id
+  end
+
+  def refund_payment
+    PSP.refund!(ctx[:payment_id]) if ctx[:payment_id]
+  end
+end
+```
+
+```ruby
+# Run it
+flow   = CheckoutFlow.start(order_id: 42, payment_token: "tok_123")
+result = flow.await # optional: block until terminal state
+
+# cancel if user aborts checkout
+flow.cancel!(reason: "user_aborted") if user_cancelled?
+```
+
+---
+
+## Defining Workflows (3 equivalent styles)
+
+All step forms accept the **same options**:  
+`retry:, compensate:, timeout:, async:, dedupe:, if:, unless:, args:, store_result_as:, fire_and_forget:`.
+
+### A) Method step
+
+```ruby
+class ExampleFlow < ActiveWorkflow::Workflow
+  step :do_work, compensate: :undo_work
+
+  def do_work
+    res = Service.call!(ctx[:input])
+    ctx[:output] = res
+  end
+
+  def undo_work
+    Service.undo!(ctx[:output]) if ctx[:output]
+  end
+end
+```
+
+### B) Task class
+
+```ruby
+class ReserveStockTask < ActiveWorkflow::Task
+  def call(ctx)
+    res = Inventory.reserve!(ctx[:order_id])
+    { reservation_id: res.id } # merged into ctx
+  end
+
+  def compensate(ctx, result:)
+    Inventory.release!(result[:reservation_id]) if result&.dig(:reservation_id)
+  end
+end
+
+class CheckoutFlow < ActiveWorkflow::Workflow
+  task :reserve_stock, ReserveStockTask
+end
+```
+
+### C) Inline block
+
+```ruby
+class NotifyFlow < ActiveWorkflow::Workflow
+  task :send_email do |ctx|
+    Mailers::Notice.deliver_later(ctx[:user_id])
+    nil
+  end
+end
+```
+
+---
+
+## Async Steps (vs Sync) – Concept & Lifecycle
+
+**Sync step:** runs to completion within one worker execution. Returns value → advance; raises → retry/fail.
+
+**Async step:** **initiates** external work and **returns immediately**. The engine persists the step in `waiting` state (with correlation/timeout). Later, an external caller resumes the step via `complete_step!` (or `fail_step!`). No worker thread is held while waiting.
+
+### Declaring async steps
+
+```ruby
+# Per-step option
+task :arrange_fulfillment, FulfillmentTask, async: true, timeout: 15.minutes
+
+# Class-level declaration
+class FulfillmentTask < ActiveWorkflow::Task
+  async! timeout: 15.minutes
+  def call(ctx)
+    job = FulfillmentAPI.create_job!(order_id: ctx[:order_id]) # initiate
+    { fulfillment_job_id: job.id }                              # merge into ctx
+  end
+end
+```
+
+**Engine behavior when async:**
+
+- Runs `call` once to initiate work.
+- If `call` returns, **persist** step → `waiting`, set `waiting_since`, compute `timeout_at`.
+- If `call` raises, treat like sync failure (retry policy).
+- Does **not** advance the cursor until a completion arrives.
+
+### Completion/Failure/Timeout APIs
+
+```ruby
+# Mark an async step as completed and advance the flow
+ActiveWorkflow.complete_step!(execution_id, :arrange_fulfillment,
+  payload: { tracking: "XYZ" }, idempotency_key: params[:event_id])
+
+# Explicit failure path while waiting
+ActiveWorkflow.fail_step!(execution_id, :arrange_fulfillment,
+  error_class: "RemoteError", message: "Timeout from vendor", details: { ... },
+  idempotency_key: params[:event_id])
+
+# Optional: extend waiting timeout
+ActiveWorkflow.extend_timeout!(execution_id, :arrange_fulfillment, by: 10.minutes)
+
+# Optional: heartbeat for monitoring
+ActiveWorkflow.heartbeat!(execution_id, :arrange_fulfillment)
+```
+
+**Payload storage:**
+
+- Initiation return (from `call`) is merged into `ctx` immediately.
+- Completion payload is stored under `ctx[step_name]` (or `store_result_as:` key).
+
+### Timeouts, retries, and re-initiation
+
+- `timeout:` caps **waiting** time. On timeout:
+  - If `retry` configured → **re-initiate** the step (re-run `call`) with backoff+jitter.
+  - Else mark step `failed`; apply flow failure/compensation policy.
+- Re-initiation must be **idempotent**—use business idempotency keys (e.g., `execution_id:step_name`) for external calls.
+
+### Security, idempotency & race-safety
+
+- `complete_step!` / `fail_step!` are **idempotent** (accept `idempotency_key`).
+- Optionally verify a **correlation_id** created during initiation before accepting completion.
+- Use DB transactional updates and row locks so only one runner transitions a step.
+- If a step isn’t `waiting`, completion/failure is a safe no-op.
+
+### Sync vs Async comparison
+
+| Aspect                | Sync step                              | Async step                                                               |
+| --------------------- | -------------------------------------- | ------------------------------------------------------------------------ |
+| Worker time           | Runs to completion in one job          | Initiates work, returns immediately; later resumed via API               |
+| State progression     | `pending → running → completed/failed` | `pending → running → waiting → (completed/failed/timed_out)`             |
+| Cursor advancement    | Immediately after success              | After `complete_step!`                                                   |
+| Failure while waiting | N/A                                    | `fail_step!` or timeout triggers retry/fail                              |
+| Timeouts              | Caps execution time                    | Caps waiting time; can `extend_timeout!` or `heartbeat!`                 |
+| Idempotency           | Step-level `dedupe`                    | Idempotent completions with `idempotency_key`; re-init safe with backoff |
+
+---
+
+## Signals & Waits
+
+Pause the workflow until a signal arrives.
+
+```ruby
+class ApprovalFlow < ActiveWorkflow::Workflow
+  task :prepare, PrepareTask
+  wait_for_signal :approval, as: :approval
+  task :finalize, FinalizeTask, args: ->(ctx) { [ctx[:approval]] }
+end
+
+# Controller/webhook sending a signal:
+ActiveWorkflow.signal!(params[:execution_id], :approval,
+  payload: { approved_by: current_user.id, decision: "approved" })
+```
+
+Signals are persisted events, consumed once, and idempotent.
+
+---
+
+## Cancellation
+
+Stop a running workflow (for example, when the user backs out).
+
+```ruby
+# Cancel via execution id (runs compensations, cancels remaining steps)
+ActiveWorkflow.cancel!(execution.id, reason: "user_request")
+
+# Or on the execution instance
+execution.cancel!(reason: "user_request")
+```
+
+Cancellation:
+
+- Runs compensations for completed steps in reverse order.
+- Marks pending/running/waiting steps as `cancelled` and clears scheduled timeouts.
+- Transitions the execution to the terminal `cancelled` state (`cancelled_at` timestamp set).
+- Emits `active_workflow.execution.cancelled` for observability.
+
+Repeated calls are safe (idempotent).
+
+---
+
+## Retries, Backoff & Jitter
+
+Specify per step or via `defaults`:
+
+```ruby
+defaults retry: { max: 5, backoff: :exponential, first_delay: 1.second, jitter: true }
+step :slow_call, retry: { max: 10, backoff: :fixed, delay: 5.seconds }
+```
+
+- `backoff:` `:fixed` or `:exponential`
+- `first_delay:` initial wait before first retry
+- `delay:` (for fixed)
+- `jitter: true` to randomize and reduce thundering herd
+
+---
+
+## Idempotency & Deduplication
+
+- **Workflow level**: `idempotency_key { "checkout:#{ctx[:order_id]}" }` ensures only one logical execution per business key.
+- **Step level**: `dedupe: true` skips re-executing a step that already completed successfully.
+- **Async completion**: `complete_step!(..., idempotency_key:)` prevents duplicate completions.
+
+---
+
+## Configuration
+
+```ruby
+ActiveWorkflow.configure do |c|
+  c.store      = ActiveWorkflow::Stores::ActiveRecord.new
+  c.logger     = Rails.logger
+  c.serializer = :json            # or a custom object responding to dump/load
+  c.clock      = -> { Time.now.utc }
+end
+```
+
+---
+
+## Persistence (Adapters)
+
+ActiveWorkflow uses a **Store** strategy.
+
+**ActiveRecord store** (ships with gem):
+
+- Tables (prefix `aw_`):
+  - `aw_executions`: workflow metadata (`workflow_class`, `state`, `ctx` jsonb, `cursor_step`, `idempotency_key`, `cancelled_at`, timestamps)
+  - `aw_steps`: per-step status (`pending|running|waiting|completed|failed|timed_out|compensating|compensated`), attempts, backoff data, `init_result`, `completion_payload`, `timeout_at`, `waiting_since`, `heartbeat_at`, `correlation_id`, `completion_idempotency_key`
+  - `aw_events`: signals etc. (`name`, `payload`, `consumed_at`)
+  - (Optional) `aw_timers`: scheduled timeouts/backoffs (or embed in steps)
+- Indexing: unique on `idempotency_key`; partial unique on `(execution_id, step_name, completion_idempotency_key) WHERE completion_idempotency_key IS NOT NULL`; JSONB GIN on payloads if needed.
+- Concurrency: transactional updates + row locks / SKIP LOCKED.
+
+You can implement other stores (e.g., Redis) by following the `ActiveWorkflow::Store` interface.
+
+---
+
+## Active Job Integration
+
+- A single internal job (e.g., `ActiveWorkflow::Jobs::RunnerJob`) receives execution/step IDs and performs the next transition safely.
+- **No dependency** on specific backends (Sidekiq, Solid Queue, etc.)—any Active Job adapter works.
+- Timers/backoffs are scheduled via `set(wait_until: ...)`.
+
+---
+
+## Observability (Events & Logging)
+
+Subscribe with `ActiveSupport::Notifications`:
+
+Events include:
+
+- `active_workflow.step.started`
+- `active_workflow.step.completed`
+- `active_workflow.step.failed`
+- `active_workflow.step.waiting` _(async initiation successful)_
+- `active_workflow.step.completed_async` _(after `complete_step!`)_
+- `active_workflow.step.failed_async` _(after `fail_step!`)_
+- `active_workflow.step.timeout`
+- `active_workflow.retry.scheduled`
+- `active_workflow.signal.received`
+- `active_workflow.execution.cancelled`
+
+Each event carries identifiers (execution_id, workflow, step), timings, attempts, and error details (when applicable).
+
+---
+
+## Generators
+
+```bash
+rails g active_workflow:install     # initializer + migrations + sample
+rails g active_workflow:workflow CheckoutFlow
+```
+
+The workflow generator scaffolds a class under `app/workflows/`.
+
+---
+
+## Testing
+
+- RSpec helpers (recommended):
+  - Start a flow and assert final state:
+    ```ruby
+    flow = MyFlow.start(foo: 1)
+    expect(flow.await(timeout: 10.seconds).state).to eq("completed")
+    ```
+  - Simulate async completion:
+    ```ruby
+    ActiveWorkflow.complete_step!(flow.id, :export, payload: { url: "..." }, idempotency_key: "evt-1")
+    ```
+- Cover:
+  - retries/backoff behavior,
+  - dedupe (no double execution),
+  - signals,
+  - timeouts (including re-initiation),
+  - compensation reverse order,
+  - idempotent completions,
+  - crash-safety (re-enqueue after failure mid-step).
+
+---
+
+## Examples
+
+**Signal workflow**
+
+```ruby
+class SignalWorkflow < ActiveWorkflow::Workflow
+  task :prepare, PrepareTask
+  wait_for_signal :approval, as: :approval
+  task :finalize, FinalizeTask, args: ->(ctx) { [ctx[:approval]] }
+end
+```
+
+**Async export + notify**
+
+```ruby
+class ExportFlow < ActiveWorkflow::Workflow
+  task :request_export, ExporterTask, async: true, timeout: 30.minutes
+  task :notify_user do |ctx|
+    Mailers::ExportReady.deliver_later(ctx[:user_id], ctx[:request_export][:download_url])
+  end
+end
+
+class ExporterTask < ActiveWorkflow::Task
+  async! timeout: 30.minutes
+  def call(ctx)
+    req = ExportAPI.create!(user_id: ctx[:user_id], request_id: "#{ctx[:execution_id]}:request_export")
+    { export_job_id: req.id, correlation: req.token }
+  end
+end
+```
+
+Webhook:
+
+```ruby
+def export_ready
+  ActiveWorkflow.complete_step!(params[:exec_id], :request_export,
+    payload: { download_url: params[:url] }, idempotency_key: params[:event_id])
+  head :ok
+end
+```
+
+---
+
+## Design Notes
+
+- Prefer **Task classes** for reusable/complex steps and DI; use **method** or **block** steps for quick wiring.
+- Use **business idempotency keys** in external systems (`execution_id:step_name`) for safe re-init.
+- Keep ctx small (IDs and small payloads). Store large blobs elsewhere and pass references.
+
+---
+
+## License
+
+MIT © You and contributors.

data/lib/active_workflow/backoff.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ActiveWorkflow
+  module Backoff
+    module_function
+
+    def calculate(config, attempts:)
+      normalized = (config[:strategy] || config[:backoff] || :exponential).to_sym
+      base = base_delay(config, attempts, normalized)
+      config[:jitter] ? apply_jitter(base) : base
+    end
+
+    def base_delay(config, attempts, strategy)
+      first = config[:first_delay]&.to_f || config[:delay]&.to_f || 5.0
+      delay = config[:delay]&.to_f || first
+
+      case strategy
+      when :fixed
+        attempts <= 1 ? first : delay
+      else
+        return first if attempts <= 1
+
+        exponent = attempts - 1
+        delay * (2**exponent)
+      end
+    end
+    private_class_method :base_delay
+
+    def apply_jitter(value)
+      low = value * 0.5
+      high = value * 1.5
+      rand(low..high)
+    end
+    private_class_method :apply_jitter
+  end
+end