Repository navigation
Make the legacy workflow overlap-lock release delay configurable #897
Description
Delivered
The reported 1.0.87 behavior is addressed in the compatible 1.1.0 release, through #904 at 6381450d13265bba86bddec6299abd0f4b1eba1b. The current Core fix is 2.11.0, through #903 at d7db4a2ea4ffb0c8dfda7cae4c846cce61ef5aec.
Set new WorkflowOptions(overlapReleaseAfter: 5) when starting a legacy workflow. The delay is a nonnegative integer in seconds. The default remains zero; old serialized options and existing runs keep their routing and stored options. Root/parent lock ownership and expiry remain unchanged. Children and continue-as-new inherit the setting unless explicit options replace it.
Laravel queue reservations still consume attempts. Choose the delay and retry budget for the expected contention duration. This setting is for Workflow\Workflow; V2 uses durable task claims and ignores the legacy delay.
Verification
- The 1.x candidate and merged source pass their complete hosted checks, including MySQL/PostgreSQL features and Laravel 9–13 dependency injection. Full source qualification includes ECS, PHPStan, 418 unit tests and 100% legacy statement coverage. 1.x acceptance evidence.
- Current Core passes the complete main source build, including all MySQL/PostgreSQL feature shards, MariaDB, supported source upgrade cells, quality, contracts, tracing and coverage. Its complete local unit coverage run passes 4,687 tests and 69,248 assertions, with 15 PHPUnit notices and seven skips; V2 statement coverage is 76.33% against the 60% unit floor.
- The normal 2.11.0 published-package verification passes package/platform verification and all 16 PHP/Laravel upgrade cells.
- Fresh public-package consumers verify immutable references, byte-identical installed source, old serialized routing options and runtime-class provenance. Installed 1.1.0 passes 15 queue/options cases plus four inheritance cases. Installed 2.11.0 passes 18 queue/options/V2 boundary cases plus four inheritance cases. The real database-queue controls prove positive-delay readmission, unchanged payload/identity, eventual completion, correct lock owners, default zero and invalid-input rejection. Current installed acceptance.
- Positive-delay V2 start, signal-with-start and child-start controls preserve arguments, routing and portable task/history shape through completion. No portable contract or migration changes are introduced. The consumer review requires no additional Server, SDK, Waterline or Sample App publication for this legacy-only option.
- Documentation PR Document legacy overlap delay and queue attempt limits durable-workflow.github.io#356 is deployed. All eight current locales and the maintained English 1.x guide return HTTP 200 with the rendered option/code, correct HTML language and retained locale route. The live install manifest selects 2.11.0. Deployment and live acceptance.
The interrupted local PostgreSQL attempt is excluded from passing totals. Its database limit and baseline deadline observations are retained in the qualification disposition; the completed hosted matrix supplies the full feature result.
Original need and product decision
An overlap lock can release a legacy workflow job immediately while parallel activities are running, rapidly consuming database-queue reservations and attempts. This was accepted as a supported configuration capability, with the zero default, serialized compatibility, root/parent ownership, inheritance and invalid-input controls preserved. The optional API ships as backward-compatible minor versions.
Original discussion: #895. Reporter follow-up for 1.0.87: #897 (comment). Reporter upgrade and configuration instructions.
Activity
jakobkollerup commentedon Oct 22, 2026
We're seeing the same issue on 1.0.87 as driver database: parallel activities make the workflow job spin on release(0) until attempts overflows and the workflow fails.
rmcdaniel commentedon Oct 22, 2026
Implementation ownership is acknowledged. Scope is the current-main option/middleware fix and real contended database-queue acceptance first, followed by a minimal #897-only 1.x backport and compatible patch publication for the reporter. Preserve the zero default and serialized option compatibility, apply root and parent-lock delays, and verify child/continue-as-new inheritance without changing lock ownership or expiry. There is no competing 1.x release work from General. Exact candidates and versions will be coordinated before tagging; the separate V2 audit #901 does not reserve these legacy files. Keep this issue open through installed-package acceptance.
rmcdaniel commentedon Oct 22, 2026
The 1.0.87 database-queue report is reproduced with two outstanding activity locks. On unmodified main, the zero-delay control passes but requesting a five-second delay still makes the released job immediately available. PR #903 adds the opt-in
WorkflowOptions(overlapReleaseAfter: 5)setting. Its regression now proves delayed readmission, the unchanged queued payload, and completion after the activity locks release.This is a product fix. Zero remains the compatibility default, and queue releases still consume Laravel attempts. A delay reduces contention churn but cannot guarantee that an arbitrarily low attempt limit is safe. The setting also covers legacy activity, signal and child-completion overlap releases so those jobs do not retain the same immediate-retry problem when the workflow opts in. Lock expiry and semaphore ownership are unchanged.
Next: finish normal qualification and all-locale guidance, qualify a minimal #897-only 1.x backport, then publish compatible packages and exercise the installed artifacts before closing this issue.
rmcdaniel commentedon Oct 22, 2026
Release coordination: use 2.11.0 for current main and 1.1.0 for the scoped legacy backport, subject to exact qualification and tag availability. The new supported optional WorkflowOptions constructor/configuration API is a backward-compatible minor addition; my earlier generic patch wording was imprecise. Scope and zero-default compatibility are unchanged. Because WorkflowMetadata is shared with V2 starts, child starts and RoutingResolver, retain a positive-delay control proving the legacy option leaves V2 arguments/routing and portable task/history shape unchanged. This verifies the stated legacy-only boundary and is not a confirmed V2 leak.
Add configurable legacy overlap release delay (#904)
rmcdaniel commentedon Oct 22, 2026
@jakobkollerup The 1.x fix is available in Workflow 1.1.0. Set a delay when starting the workflow, for example:
The delay is in seconds and is inherited by child workflows and continue-as-new unless explicit options replace it. The default remains zero, and existing runs keep their stored options, so upgrading alone does not enable the delay. Queue reservations still consume attempts; choose the delay and attempt budget for the expected lock-contention duration.
I verified the installed Packagist package against real database-queue contention, including delayed availability, the unchanged payload and completion after unlock, plus persistence/inheritance and invalid-input controls. The usage guide is included in the release.
The current 2.x fix and website guidance are still progressing; this issue remains open for that follow-through.
Configure legacy overlap-lock release delay (#903)
Document legacy overlap release delay (#356)
rmcdaniel commentedon Oct 22, 2026
@jakobkollerup The 1.x fix is fully delivered in 1.1.0. To stay on 1.x:
Start new legacy workflows with
new WorkflowOptions(connection: 'database', overlapReleaseAfter: 5)to select a five-second delay. The default remains zero, and existing runs retain their stored options. Queue reservations still consume attempts, so choose the delay and retry budget for your activity duration.The same feature is released in 2.11.0. The 1.x guide and current guide are live, including all seven current translations.
Both public packages passed fresh installed-package acceptance with real database-queue contention. The complete main build, supported published-package upgrade matrix and documentation deployment are green. Closing this issue with the release and acceptance evidence recorded above.