Skip to content

feat: support arbitrary delays beyond Cloudflare's 12-hour limit via hop-based relay#1

Open
ossycodes wants to merge 4 commits into
mainfrom
feature/long-delay-hop-support
Open

feat: support arbitrary delays beyond Cloudflare's 12-hour limit via hop-based relay#1
ossycodes wants to merge 4 commits into
mainfrom
feature/long-delay-hop-support

Conversation

@ossycodes

Copy link
Copy Markdown
Owner

Current Issue:

Cloudflare Queues hard-caps delay_seconds at 43,200 seconds (12 hours). Any job dispatched with a longer delay — e.g. ->delay(now()->addHours(20)) or ->delay(now()->addDays(3)) — silently breaks: Cloudflare
either rejects the request or caps the delay at 12 hours, meaning the job fires too early.


The Fix:

When delay > 43,200s, pushRaw() wraps the original payload in an envelope containing the absolute target timestamp:

{
"__cf_delay_wrapper": true,
"__cf_execute_at": 1234567890,
"__cf_payload": "{...original job payload...}"
}

The wrapper is sent with a 12-hour delay (Cloudflare's max). When the worker pulls it, pop() inspects it and takes one of three paths:

  • Remaining > 12h → re-wrap with the same execute_at, re-queue with 12h delay, ACK current message
  • Remaining ≤ 12h → send the original payload directly with the remaining delay (no wrapper), ACK current
  • Remaining ≤ 0 → unwrap and process the original job immediately

The worker never sees the wrapper — it's a transparent internal relay.

Example — 30-hour delay becomes 3 hops:
T=0h dispatch with delay=30h → wrapper sent with delay=12h
T=12h worker pulls wrapper, 18h remaining → re-queue wrapper with 12h delay
T=24h worker pulls wrapper, 6h remaining → send original payload with 6h delay
T=30h worker pulls original job → handle() runs ✅

Changes:

  • src/CloudflareQueue.php — pushRaw() wraps long delays; pop() + resolveDelayWrapper() handles unwrapping/re-queuing
  • tests/Unit/CloudflareQueueTest.php — 7 new test cases covering all hop paths
  • README.md — updated Delayed Jobs section from limitation to supported feature
  • docs/05-configuration-reference.md — full explanation of the hop mechanism with examples

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant