Skip to content

feat(cloudflare): version.affinity sticky-session sugar for gradual deployments - #985

Merged
sam-goodwin merged 1 commit into
mainfrom
claude/worker-affinity-sugar-f372dc
Jul 29, 2026
Merged

sam-goodwin merged 1 commit into
mainfrom
claude/worker-affinity-sugar-f372dc

Conversation

@sam-goodwin

Copy link
Copy Markdown
Member

First-class version affinity for gradual deployments — pin each user to one version for the duration of a rollout by declaring the key source on the version prop (requested by Eric Clemmons in review of #981):

yield* Cloudflare.Worker("Api", {
  main: "./src/api.ts",
  domain: "api.example.com",
  version: {
    traffic: 10,
    // sticky by session cookie, falling back to sticky IP
    affinity: { cookie: "session_id", ip: true },
  },
});

Provisions rewrite Transform Rules in each serving zone's http_request_late_transform entrypoint that fill the Cloudflare-Workers-Version-Key header, scoped to the Worker's own hostnames (http.host eq/in/wildcard …) so other zone traffic and other Workers' rollouts are untouched. Managed like the worker redirect rules: tagged by an alchemy:worker:<script>:affinity description prefix, foreign rules pass through, removed when affinity is removed or the resource is deleted.

  • Sources: cookie, header, ip: true (standalone or as fallback for an absent cookie/header), and key — a raw Rules-language expression escape hatch (e.g. a JWT claim via API Shield).
  • Zones resolve from observed custom-domain attachments plus reconciled route zone ids; a workers.dev-only Worker fails with a typed WorkerVersionConfigError.
  • Parent-mode canaries (version.parent) are supported: the rule lands on the parent's zones under the parent's script name, and releasing the canary removes it.
  • Placed zones persist as affinityZoneIds on Attributes (the cleanup list for delete and affinity-removal); affinity participates in the metadata hash so toggling it plans an update.

One subtlety worth knowing: an absent cookie/header is a missing value in the Rules language and every comparison on missing evaluates false, so the IP-fallback guard is not (len(field) > 0) — len(field) == 0 never matches. The live test proved this end-to-end (worker echoes the rewritten header for cookie and bare requests).

Live tests in WorkerVersionAffinity.test.ts (all green, ~47s): rule convergence across sources + destroy cleanup with functional header-rewrite assertions on the standing test zone, the workers.dev-only rejection, and the parent-mode canary. Existing WorkerVersion.test.ts suite still green. The gradual-deployments guide now leads with the sugar and keeps the manual Ruleset as the escape hatch.

🤖 Generated with Claude Code

…eployments

Pin each user to one Worker version during a gradual rollout by
declaring the version-key source on the version prop:

  version: { traffic: 10, affinity: { cookie: "session_id", ip: true } }

Provisions rewrite Transform Rules (http_request_late_transform) that
fill the Cloudflare-Workers-Version-Key header on every zone the Worker
serves on, scoped to its hostnames. Sources: cookie, header, ip
(standalone or fallback), and a raw Rules-language key expression.
Rules converge in place, land on the parent's zones for parent-mode
canaries, and are removed when affinity is removed or the resource is
deleted. workers.dev-only Workers fail with a typed
WorkerVersionConfigError.

Note the absence guard is `not (len(field) > 0)` — Rules-language
comparisons on a missing cookie/header always evaluate false, so
`len(field) == 0` never matches (caught by the live IP-fallback test).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@alchemy-version-bot

Copy link
Copy Markdown
Contributor

Install the packages built from this commit:

alchemy

bun add alchemy@https://pkg.ing/alchemy/5295913

@alchemy.run/better-auth

bun add @alchemy.run/better-auth@https://pkg.ing/@alchemy.run/better-auth/5295913

@alchemy.run/pr-package

bun add @alchemy.run/pr-package@https://pkg.ing/@alchemy.run/pr-package/5295913

@sam-goodwin
sam-goodwin merged commit 77899a5 into main Jul 29, 2026
9 checks passed
@sam-goodwin
sam-goodwin deleted the claude/worker-affinity-sugar-f372dc branch July 29, 2026 08:47
john-royal added a commit that referenced this pull request Jul 30, 2026
Brings in 94 commits from main (local vs live provider modes #963,
workersDev/domain props #977, Worker.URL self-binding #964, assets-only
Workers #969, Prisma provider #416, version affinity #985, telemetry
#860) while preserving this branch's SourceProvider architecture and
Website framework integrations.

- Worker providers take main's side wholesale; the SourceProvider
  integration is re-grafted as a dispatch: `props.source` routes through
  `resolveSource`/`loadSource` (build, hash slots, and local dev in both
  server and bundle modes via the make-before-break serve path), while
  script/vite/python/prebuilt/assets-only workers keep main's paths.
- Apply.ts: both sides landed the resolved-bindings persistence fix
  (#874 / ef08f4c); merged as the union, keeping `providerMode` and
  `bindings` on replaced-state commits.
- test Utils/Http.ts: keep main's generalized retryResponse machinery
  (expectUrlRedirect/expectUrlHeader) and re-add expectDirectStatus on
  top of it.
- Website tests track main's API: `url`/`subdomain` props fold into
  `workersDev`; dev-mode R2 cleanup skips virtual `dev:` buckets.
- cloudflare-tools submodule bumped to this branch's merge of its own
  upstream main (59c3861); distilled synced to main's pointer.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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