Issue Review: cloudflare/workers-sdk#10286

Summary

Request to remove delivery_delay parameter from queue producer binding configuration as a breaking change, since workers should not affect queue-level settings.

Findings

• Created: 2025-08-08
• Updated: 2025-08-11
• Version: wrangler 4.28.1 -> 4.60.0 (current)
• Component: wrangler (queues)
• Labels: bug, breaking change
• Comments: 0

Key Evidence

• PR #10288 merged on 2025-08-11 - "fix(wrangler) remove putQueue call when deploying a worker with queue producer binding"

  • This PR removed the updateQueueProducers function that was calling putQueue API
  • Fixes the behavioral issue: workers no longer affect queue-level settings during deployment
  • Released in wrangler 4.29.0

• Partial fix only - The delivery_delay parameter is still present in the schema:

  • File: packages/workers-utils/src/config/environment.ts
  • The parameter is now a no-op but still accepted without warning
  • PR #10288 notes: "(optionally start deprecating 'delivery_delay' as now, setting it will not do anything)"

• Issue title explicitly requests breaking change - "[Breaking] Remove delivery_delay parameter from queue producer binding"

  • The behavioral bug is fixed but the schema cleanup (the breaking change) was not done

Recommendation

Status: KEEP OPEN

Reasoning: The underlying behavioral issue was fixed in PR #10288 (wrangler 4.29.0), but the delivery_delay parameter still exists in the queue producer schema. The issue specifically requests a breaking change to remove this parameter entirely. Currently, users can still set delivery_delay in their config without any warning, but it silently does nothing - this is confusing UX.

Action: The issue should remain open to track the breaking change work to:

1. Remove delivery_delay from the queue producer binding schema
2. Add a deprecation warning or validation error when the parameter is used
3. Update documentation to reflect that queue-level settings should be configured via wrangler queues commands, not producer bindings

---

Root Cause Analysis

The issue stems from the original design decision to allow queue producer settings to be configured in the wrangler.toml file under [[queues.producers]]. This was problematic because:

1. Queue settings are queue-level, not worker-level: The delivery_delay setting affects the entire queue, not just the producer binding
2. Multiple producer conflict: When multiple workers have producer bindings to the same queue with different delivery_delay values, the last deployed worker's setting wins, leading to unpredictable behavior
3. Separation of concerns violation: Workers should only define their bindings to queues, not configure queue-level settings

Code References

Schema definition (still contains delivery_delay):

• packages/workers-utils/src/config/environment.ts - Queue producer schema includes delivery_delay?: number

Fixed deploy behavior:

• packages/wrangler/src/deploy/deploy.ts - updateQueueProducers function was removed by PR #10288
• packages/wrangler/src/triggers/deploy.ts - No longer calls queue update API during deployment

Proposed Solution

Option 1: Deprecation Warning (Soft Break)

Add a deprecation warning when delivery_delay is set on a producer, then remove in a future major version.

// In packages/wrangler/src/config/validation.ts or similar
function validateQueueProducers(producers: QueueProducer[]) {
  for (const producer of producers) {
    if (producer.delivery_delay !== undefined) {
      logger.warn(
        `The 'delivery_delay' setting in [[queues.producers]] is deprecated and has no effect. ` +
        `Queue-level settings should be configured using 'wrangler queues update' instead. ` +
        `This setting will be removed in a future version.`
      );
    }
  }
}

Option 2: Hard Removal (Breaking Change)

Remove the parameter from the schema entirely, causing validation errors for existing configs.

// In packages/workers-utils/src/config/environment.ts
// Remove this line from the producers schema:
// delivery_delay?: number;

Recommended approach: Option 1 first, then Option 2 in the next major version.

Implementation Difficulty

Difficulty: EASY

Justification:

• The behavioral fix is already done (PR #10288)
• Only schema/validation changes remain
• Clear scope: remove one field from one schema
• No complex logic or API changes required
• Existing tests already updated to not expect the putQueue call

Files to Modify

1. packages/workers-utils/src/config/environment.ts

   • Remove delivery_delay?: number from queue producer schema (or mark as deprecated)

2. packages/workers-utils/src/config/validation.ts (if exists) or create validation

   • Add deprecation warning if delivery_delay is set

3. packages/wrangler/src/__tests__/deploy.test.ts

   • Update tests that use delivery_delay in producer config

4. packages/wrangler/src/__tests__/init.test.ts

   • May need updates if it tests producer schema

5. Documentation/CHANGELOG

   • Document the breaking change or deprecation

Testing Recommendations

1. Unit tests:

   • Test that delivery_delay in producer config triggers deprecation warning (if soft break)
   • Test that delivery_delay in producer config causes validation error (if hard break)

2. Integration tests:

   • Verify wrangler deploy with delivery_delay in config still works (soft break) or fails with helpful error (hard break)

3. Migration testing:

   • Test upgrade path from wrangler < 4.29.0 configs that have delivery_delay

Suggested Comment

This issue was partially addressed by #10288, which removed the putQueue call during deployment so that workers no longer affect queue-level settings. However, the delivery_delay parameter is still accepted in the queue producer configuration schema - it just silently does nothing now.

The issue specifically requests a breaking change to remove this parameter entirely. Should this be:

1. A deprecation warning now, with removal in a future major version?
2. An immediate removal in the next major version?

This would help avoid confusion where users set delivery_delay expecting it to work, but it has no effect.