Skip to content

docs(workers): clarify Version-Overrides header works on service-binding subrequests#30733

Closed
thomsoncf wants to merge 1 commit into
cloudflare:productionfrom
thomsoncf:docs/version-overrides-service-bindings
Closed

docs(workers): clarify Version-Overrides header works on service-binding subrequests#30733
thomsoncf wants to merge 1 commit into
cloudflare:productionfrom
thomsoncf:docs/version-overrides-service-bindings

Conversation

@thomsoncf
Copy link
Copy Markdown
Contributor

Summary

Adds a single paragraph + small JS snippet to the Version overrides section of the Gradual Deployments docs, clarifying that Cloudflare-Workers-Version-Overrides is honoured on subrequests made through a Worker-to-Worker service binding — but only when the calling Worker explicitly sets the header on the subrequest.

Why

The neighbouring Version affinity section already documents that Cloudflare-Workers-Version-Key works on service-binding subrequests:

You can set the Cloudflare-Workers-Version-Key header both when making an external request from the Internet to your Worker, as well as when making a subrequest from one Worker to another Worker using a service binding.

The same is true of Cloudflare-Workers-Version-Overrides, but the docs don't currently say so, which leads to repeat questions about whether the override header is honoured on service bindings.

There is also a subtle difference worth surfacing: the override header is not automatically propagated through a service binding — the calling Worker must explicitly include it on the subrequest. This PR makes that explicit with a short JS example using env.MY_SERVICE.fetch().

Verified empirically

Set up two Workers in one account:

  • Callee with v1 (100%) and v2 (0%) in its gradual deployment.
  • Caller with a service binding to the callee, conditionally setting the override header on env.CALLEE.fetch().
Scenario Result
No override header callee returns v1 (default)
Caller explicitly sets override → v2 on the subrequest callee returns v2
Invalid version ID in override falls back to v1 (matches existing docs)
Header set only on inbound request, caller does not forward it callee returns v1 (no auto-propagation)

Out of scope

  • RPC method calls (env.MY_SERVICE.someMethod()) — there is no API to attach headers per-call, so this PR doesn't address that case.
  • Automatic propagation through service-binding chains — separate runtime work, not a docs change.

…ing subrequests

Adds a paragraph and JS snippet to the Version overrides section
clarifying that Cloudflare-Workers-Version-Overrides is honoured on
subrequests made through a Worker-to-Worker service binding, but only
when the calling Worker explicitly sets it on the subrequest.

The neighbouring Version affinity section already documents the same
behaviour for Cloudflare-Workers-Version-Key; this brings parity.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

product:workers Related to Workers product size/s

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants