Skip to content

feat(cloudflare/workers): worker versions and gradual deployments - #948

Merged
sam-goodwin merged 3 commits into
mainfrom
claude/cloudflare-worker-versions-198f37
Jul 28, 2026
Merged

sam-goodwin merged 3 commits into
mainfrom
claude/cloudflare-worker-versions-198f37

Conversation

@sam-goodwin

@sam-goodwin sam-goodwin commented Jul 26, 2026 •

Copy link
Copy Markdown
Member

Adds a version prop to Cloudflare.Worker mapping Cloudflare's versions & gradual deployments onto alchemy stages.

// PR preview: upload this stage's code as a zero-traffic version of
// staging's script; worker.url is the version preview URL
const parent = yield* Cloudflare.Worker.ref("Api", { stage: "staging" });
yield* Cloudflare.Worker("Api", {
  main: "./src/api.ts",
  version: { parent, message: `PR #${process.env.PR_NUMBER}` },
});

// canary: 10% of the parent's traffic
version: { parent, traffic: 10 }

// gradual rollout of a Worker's own deploy (new version 25%, live version 75%)
version: { traffic: 25 }
  • parent accepts a Worker ref (yield* Worker.ref(id, { stage, stack })), a locally-declared Worker, or a literal script name as an escape hatch. Changing parent (or mode) replaces the resource.
  • A version worker's url is its aliased preview URL (<alias>-<name>.<subdomain>.workers.dev): the alias is auto-derived per (stack, stage, id) — override with version.alias — so the link is stable across deploys and re-points at each newly uploaded version. The per-version URL rides in domains. Because the aliased URL is known before upload, Worker.URL works on version workers and resolves to it (typed error when previews are disabled or no alias fits the 63-char DNS label).
  • Version workers own a version, not a script: read verifies the version exists on the parent (never adopts the parent's script), delete restores 100% of traffic to the surviving version and leaves the parent untouched, precreate skips the placeholder script.
  • Script-level settings (routes, domain, crons, tags, observability, logpush, placement, limits, subdomain, assets, name, namespace) are rejected on version workers with a typed WorkerVersionConfigError, as are locally-hosted Durable Object / Workflow classes (their migrations would mutate the parent).
  • Self-rollouts deploy through createScriptVersion + createScriptDeployment instead of the full-cutover putScript; the first deploy of a script always goes to 100%. Assets and pending DO migrations can't ride a rollout (typed error).
  • New attrs: versionOf, versionId, deploymentId. The metadata hash reduces version.parent to the parent's script name so parent redeploys don't spuriously re-version children.

Includes alchemy-run/distilled#389 (typed binding-validation errors on createScriptVersion) — already merged upstream; the distilled submodule points at distilled main, which contains it.

Live-tested in test/Cloudflare/Workers/WorkerVersion.test.ts: preview URL serves the version's code while the parent's deployment is untouched, aliased URL stable across the preview→canary redeploy, canary split asserted at 25/75 out-of-band via listScriptDeployments, canary removal restores 100%, string-name parent, rollout 100 → 50/50 → 100, Worker.URL on a version echoing its own aliased URL, and the validation error. Worker.test.ts passes unchanged.

Docs: Versions & Gradual Deployments JSDoc section on the Worker resource plus a new section in the Workers guide.

🤖 Generated with Claude Code

Adds a version prop to Cloudflare.Worker mapping Cloudflare's versions
and gradual deployments onto alchemy stages:

- version.parent uploads this Worker as an immutable version of another
  Worker's script (PR previews via preview URL, canaries via traffic)
- version.traffic on a self-owned Worker deploys gradually, splitting
  traffic between the new and previously-live version

Includes distilled patch typing createScriptVersion's binding-validation
errors (alchemy-run/distilled#389).

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

alchemy-version-bot Bot commented Jul 26, 2026 •

Copy link
Copy Markdown
Contributor

Install the packages built from this commit:

alchemy

bun add alchemy@https://pkg.ing/alchemy/440777c

@alchemy.run/better-auth

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

@alchemy.run/pr-package

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

sam-goodwin and others added 2 commits July 28, 2026 13:50
Resolves Worker.ts / WorkerProvider.ts conflicts (Worker.URL #964 landed
alongside the version prop) and rejects Worker.URL bindings on version
workers — a version's URL is its preview URL, which only exists after
upload. Distilled submodule resolves to main's pointer, which already
contains distilled#389.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…n workers

A version's per-version preview URL derives from the server-assigned
version id, so it can never be baked into the version's own bindings.
Aliased preview URLs break the cycle: the alias is deterministic before
upload, so the URL is knowable ahead of time and stable across deploys.

- Auto-derive a stable alias per (stack, stage, id) for version workers;
  override with version.alias. url = aliased preview URL; the
  per-version URL rides in domains.
- Worker.URL (self_url) now lowers into the aliased URL on version
  workers instead of being rejected; typed error remains when previews
  are disabled or no alias fits the 63-char DNS label.
- New versionAlias attribute; alias annotation (workers/alias) sent on
  version uploads, pass-through on self-rollouts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin
sam-goodwin merged commit 48b20c4 into main Jul 28, 2026
9 checks passed
@sam-goodwin
sam-goodwin deleted the claude/cloudflare-worker-versions-198f37 branch July 28, 2026 21:49
sam-goodwin added a commit that referenced this pull request Jul 28, 2026
- resolveWorkerDomain accepts the pre-redesign domain: string[] prop
  shape from persisted olds (first hostname = name, rest = aliases,
  [] = detach-all) instead of degrading to a bogus 'undefined' hostname
- unit coverage for resolveWorkerDomain (shorthand, punycode/dedupe,
  legacy array, null, role-overlap error) and stateWorkerDomain (all
  state generations)
- live test: props-identical redeploy migrates a #948-era version
  worker record (preview URLs in domains, no urls) as a one-time update
  that keeps the aliased preview URL byte-stable and settles to noop

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