Skip to content

Workflow 2.34.0

Latest

Choose a tag to compare

@rmcdaniel rmcdaniel released this 20 Nov 01:03
· 2 commits to main since this release
9d9332e

2.34.0 adds one migration (#1231): workflow tasks gain lost_lease_count and
last_lease_lost_at, and run summaries gain task_attention. Every column is
nullable or has a constant default, so nothing is backfilled; run
php artisan migrate when upgrading. Definition fingerprint version 2, the
workflow task job timeout and failing a run on repeated lost leases are all
opt-in. New runs still record fingerprint version 1.

  • The business state-machine API is explicitly experimental (#1069). Every
    public class, interface and enum in Workflow\V2\StateMachine, native child
    start (Workflow::startChild(), startChild() and StartedChildWorkflow) and
    DurableScope::reserveChild() are marked @experimental. They may change
    incompatibly in a minor release, never in a patch release.
    docs/api-stability.md#state-machines lists them and the release each first
    shipped in: the transition contract and TransitionRunner in 2.23.0, and the
    definitions, rules, budgets, child bindings and native child start in 2.29.0.
    Docblocks and documentation only; no behavior changes.

  • A workflow task that keeps losing its lease without completing no longer
    retries silently forever (#1231). A lease is lost when the worker running
    the task is killed, times out, or loses its connection.

    • Opt-in workflows.v2.workflow_task_job_timeout_seconds
      (DW_V2_WORKFLOW_TASK_JOB_TIMEOUT_SECONDS, unset by default) gives workflow
      task jobs their own queue timeout, kept 10 s below the connection's
      retry_after, in place of the worker's --timeout. Unset, the worker's
      --timeout applies as before. A worker on the workflow queue logs one
      warning at start when the timeout its workflow tasks run under is below
      the workflow task lease.
    • Task repair counts each lost lease on the task (lost_lease_count,
      last_lease_lost_at). The next claim logs a typed
      workflow_task_lease_lost diagnostic. No history is written, and run
      semantics are unchanged.
    • At three consecutive lost leases
      (workflows.v2.workflow_task_lost_leases.attention_threshold), the run
      summary, list items and describe carry an additive task_attention field
      (reason, consecutive, threshold), and operator metrics add
      runs.task_attention, tasks.lease_lost_repeatedly and
      tasks.max_lost_lease_count. Repair-blocked reasons, repair attention
      and can_repair are unchanged.
    • Opt-in (workflows.v2.workflow_task_lost_leases.fail_run, off by default;
      boot refuses a threshold below 2): at the threshold, the next claim fails
      the run with a typed WorkflowTaskLeaseLostException (task_failure)
      instead of retrying.
    • The migration adds the columns outside a transaction under the schema
      lock budget.
  • A wide all() no longer makes its workflow tasks grow with the square of the
    fan-out width (#1231, #1203). A 300-member fan-out of 10 KB activities took
    134 s to schedule and 58–85 s to finish on 2.32.0, so Laravel's default
    60-second queue job timeout killed it on every retry. Per-member cost is now
    roughly constant:

    • A workflow task publishes the tasks it committed in bounded batches and
      refreshes each affected run summary once, instead of rebuilding the run's
      whole summary, in its own transaction, for every member it published.
    • Replay, child-call, parallel-group, lineage and activity lookups index the
      loaded history by sequence once, instead of rescanning the whole history
      for every member. A child closure no longer rescans the parent's history
      for every sibling.
    • Activity starts refresh only their own timeline points, like outcomes, and
      projections skip decoding payloads that cannot name the activity or a
      failure.

    Recorded history and every projection row are unchanged. Each member's own
    activity or child task still rebuilds its run summary once.

  • Workflow definition and await() condition fingerprints are versioned, and
    a new opt-in version 2 makes comment-only and whitespace-only edits replay-safe
    (#1227). The prefix names the version:

    • Version 1, sha256:, hashes raw source lines, as before. Editing a comment
      in a workflow class, its traits or parent workflow classes, or an await()
      condition closure changes it: a missing getVersion() or patched()
      marker then takes DEFAULT_VERSION, and a waiting condition fails replay.
    • Version 2, sha256-tokens:, hashes the PHP code tokens without comments
      and whitespace, so those edits no longer change replay.
    • This release compares both versions, each run by the version it recorded,
      and new runs still record version 1 by default. Set
      DW_DEFINITION_FINGERPRINT_VERSION=v2 (workflows.definition_fingerprint_version)
      to record version 2, only after every worker that can claim these runs
      is on this release or later
      . Any other value stops the application or
      worker at boot; recording never fails a run over this setting. An older worker compares a version 2 run
      by version 1, sees a changed definition, and takes the legacy default for
      a missing marker; a newer worker would then take the current branch for
      the same run. Switching back to v1 is safe: existing runs keep the
      version they recorded. Rolling a worker back below this release requires
      draining the runs that recorded version 2 first. A later release will
      make version 2 the default.
    • A run keeps its version for every condition wait it opens, and failed-run
      redrive keeps the source run's version. Class pinning
      (resolveClassForRun()), run detail drift
      (workflow_definition_current_fingerprint is computed with the recorded
      version, version 1 when none was recorded) and determinism diagnostics
      compare by the recorded version.
    • Compensation root and child reservation descriptors and recovery-run
      admission receipts stay version 1 under either setting, so a comment edit
      to a workflow they bind still invalidates them, as before.
    • CompiledWorkflowDefinition uses the recording version for
      source.workflow_definition_fingerprint and the default
      definition_version. Under v2 both become sha256-tokens: values, so the
      same code compiles to a new version string once, and comment-only edits no
      longer produce a new one.
  • Upgrade 2.32.0 hosts to 2.33.0. On 2.32.0, a run that waits for a signal
    after it consumed a child's result receives a no-op workflow task on every
    watchdog pass, for as long as it waits (#1219). The business state-machine
    examples hit this: a booked Order waits for finish after its payment and
    booking children complete, so a queue worker run with --stop-when-empty
    never stops. 2.33.0 fixes it. Existing rows self-heal: the watchdog
    re-projects the run before it would create a task, so the run then reads
    waiting_for_signal. Recorded history is unchanged.

  • CI now installs published 2.33.0 into a new Laravel application and checks
    the state-machine examples across an upgrade (#1069). Provider-backed and
    configured Orders are left mid-flight on queue workers with MySQL or
    PostgreSQL and Redis. One has a cancellation waiting on a processing provider
    refund. After the upgrade, every recorded run replays, and the Orders finish
    or recover without repeating a provider effect. The job also checks that
    schema rollback is refused while their scopes are retained. It checks a
    package downgrade that keeps that state, followed by an upgrade that recovers
    it. It runs on pull requests that change the examples, state-machine,
    compensation or migration code, and on stable release tags against the
    published package. docs/business-state-machines.md describes what it
    checks. The compensation-scope and state-machine journeys now share
    scripts/ci/upgrade-journey-lib.sh.

  • A v1 activity whose job failed no longer runs a second time when the
    workflow replays before the failure is recorded (#1241). The failure is
    recorded by a separately queued Workflow\Exception job after the activity's
    unique lock is released, so a wake in between (a signal, timer or sibling
    result) dispatched the activity again and the copy executed it, adding an
    exception row and repeating its side effects. The failed job now marks the
    activity in the cache before its lock is released. A copy that finds the mark
    completes without executing, recording a result or firing activity events, and
    the Exception job removes the mark once it has recorded the failure or let it
    go. Recorded history, job payloads and replay are unchanged.

    • The mark expires after workflows.activity_failure_mark_seconds
      (DW_V1_ACTIVITY_FAILURE_MARK_SECONDS, default 3600). If the Exception job
      is lost (a flushed queue, an undecryptable payload), a later wake then runs
      the activity again, as before this release, instead of the workflow waiting
      forever. Keep it well above the time an Exception job can wait behind
      earlier pending work.
    • A job that times out, or exhausts its attempts after a worker crash, fails
      without running the activity's catch block, so it writes no mark and the
      redispatch race stays open on those paths, as before.
  • In the carrier-loss example (examples/provider-state-machines), a refund
    still processing after its last bounded wake no longer fails the Order run
    (#1220). The wait makes one last check of the same refund. If the provider has
    confirmed, the remedy is refunded; otherwise it is owed with resolution
    refund-unresolved, and the Order completes unsettled. A later provider
    confirmation pays that same refund exactly once, and
    IncidentStore::refund($key) shows its status. The wake bound is read from
    the incident's recorded initialization (Authority(..., transitWakes:),
    default and maximum 32); histories recorded without it replay unchanged. A
    cancellation while a full-parcel Shipment is in transit is now documented and
    tested end to end (#1217). Examples only.

One new migration (2026_11_18_000100_add_lost_lease_tracking); run php artisan migrate when upgrading from 2.33.x or earlier. See CHANGELOG.md.