Skip to content

feat(cloudflare/workers)!: workersDev + domain props; url/urls/domain outputs - #977

Merged
sam-goodwin merged 20 commits into
mainfrom
claude/worker-url-domain-redesign-v2
Jul 29, 2026
Merged

sam-goodwin merged 20 commits into
mainfrom
claude/worker-url-domain-redesign-v2

Conversation

@sam-goodwin

Copy link
Copy Markdown
Member

Redesigns how Worker URLs and workers.dev are configured and reported, for Cloudflare.Worker and Cloudflare.Website.*.

const worker = yield* Cloudflare.Worker("Api", {
  main: "./src/api.ts",
  workersDev: false, // boolean | { enabled?, previewsEnabled? }, default true
  domain: {
    name: "example.com",
    aliases: ["www.example.com"],     // also serve the Worker
    redirects: ["old.example.com"],   // 301 → https://example.com
  },
});

worker.url;    // "https://example.com" — always urls[0]
worker.urls;   // every URL that serves the Worker, most significant first
worker.domain; // { name, aliases, redirects } | undefined

The ranking rules

urls is ordered most significant first and url = urls[0]:

  1. https://<domain.name> — the canonical custom domain
  2. aliases, in declared order
  3. the stable workers.dev URL (workersDev.enabled)
  4. version preview URLs — for a version worker (version.parent) these are its only URLs, so the stable aliased preview URL is url; for a gradual rollout the uploaded version's preview URL trails; in previews-only mode ({ enabled: false, previewsEnabled: true }) the current version's preview URL is the only workers.dev surface
  5. under alchemy dev, urls is the dev server's actual surface instead: [localhost, ...LAN] (Vite's Local/Network URLs) — a configured domain is not served by the dev session, so url is the local URL

Redirect hostnames never appear in urls — they serve no content. worker.urls is the CORS-allow-list answer.

Replaced props

before after
url: boolean workersDev: boolean | { enabled?, previewsEnabled? }
subdomain: { enabled?, previewsEnabled? } (silently ignored) folded into workersDev (actually reconciled now)
domain: string | string[] domain: string | { name, aliases?, redirects? } | null
output domains: string[] (https:// URLs) outputs urls: string[] + domain object

Website.Vite / Website.StaticSite inherit the new props via WorkerProps.

Main's #942 semantics carry over: an omitted domain leaves attachments unmanaged (and skips the listDomains fan-out, #926); domain: null is the explicit detach-all (replacing domain: []).

Redirects

Each redirect hostname is attached as a Worker custom domain (managed DNS + edge certificate) plus a rule in the zone's http_request_dynamic_redirect phase entrypoint (301, path + query preserved), which runs before Workers — redirected requests never invoke the Worker. Rules are tagged alchemy:worker:<script>:redirect:<host>; reconcile and destroy only ever touch our own rules in the shared entrypoint.

State migration

Legacy domains state ({ id, hostname, zoneId } objects ≤ beta.44, https:// URL strings beta.45+) migrates on the fly: the diff reads all generations, and the first redeploy rewrites attributes to the new shape as a one-time update.

Builds on #948 (worker versions & gradual deployments, now in main) and folds in the earlier worker-url-domains-redesign branch, reshaped to this design.

Live-tested (Worker.test.ts, WorkerUrls.test.ts, WorkerVersion.test.ts, AssetsOnlyWorker.test.ts, Website/*): default/off/object workersDev permutations against live subdomain state, previews-only url, domain-vs-workers.dev ranking and alias swaps on the test zone, redirect 301 end-to-end with rule lifecycle asserted out-of-band in the zone entrypoint, version-worker and rollout urls, legacy-state migrations, and local-dev [localhost, ...LAN] URLs.

🤖 Generated with Claude Code

sam-goodwin and others added 15 commits July 8, 2026 18:06
…mains outputs

Replaces the Worker's overlapping url/subdomain/domain props with a
single workersDev toggle (boolean | { url, previews }) and a domains
list. Outputs are now self-describing: url is always allUrls[0],
allUrls collects every reachable URL most-relevant-first (preview?,
workers.dev?, localhost?, ...customDomains, ...dev network URLs), and
domains holds the matching hostnames aligned 1:1.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Redeploying over state written by beta.45-57 (https:// URL strings) or
<= beta.44 ({ id, hostname, zoneId } objects) must not crash and must
rewrite the attributes to the current hostname/allUrls shape.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- props-identical redeploy migrates via the metadata hash alone (the
  real upgrade path for a bare Worker), one-time update then noop
- downstream resource consuming worker.allUrls re-resolves through the
  migration and settles to noop
- legacy props keys (url/subdomain) in olds flow through the diff

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ains-redesign-1496aa

Co-authored-by: Cursor <cursoragent@cursor.com>
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>
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>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Takes this branch's Worker.ts/WorkerProvider.ts wholesale — the
provider-side redesign is re-ported by hand against the NEW design
(domain object with aliases/redirects, urls output) in the next
commits. The prior branch's test/fixture/doc migrations and
LocalWorkerProvider LAN-URL expansion carry over; local attrs already
adapted to url/urls/domain.

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

Replaces url/subdomain/domain with:

- workersDev?: boolean | { enabled?, previewsEnabled? } (default true)
- domain?: string | { name, aliases?, redirects? }

Outputs: url = urls[0] (most significant first: canonical domain,
aliases, workers.dev, version previews); domain = resolved config;
the domains list is gone. Redirect hostnames are attached as custom
domains (DNS + TLS) and 301 via a tagged rule in the zone's
http_request_dynamic_redirect entrypoint, which runs before the Worker;
they never appear in urls. Local dev urls = [localhost, ...LAN].
Legacy domains state (objects <= beta.44, https:// URLs beta.45+)
migrates on the fly.

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

- WorkerUrls.test.ts: role-overlap validation, redirect 301 lifecycle
  (rule create/remove/destroy, out-of-band entrypoint assertions,
  path+query preservation), domain string shorthand
- Worker.test.ts reshaped to the new ranking (domain > aliases >
  workers.dev); rollout urls assertion in WorkerVersion.test.ts
- workers.mdx URLs & domains section, custom-domains.mdx rewrite,
  Worker JSDoc URLs & Domains section

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…an-out) into url redesign

Integrates main's manage-only-when-declared domain semantics with the
new domain config: an omitted domain leaves attachments alone and skips
the listDomains fan-out; domain: null is the explicit detach-all
(replacing the old domain: []). Read keeps main's gated observation
(#926) with the new name/alias/redirect classification.

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

The unmanaged path (domain omitted) carried persisted domain state into
urls/domain attrs unverified — stale legacy entries whose attach never
happened resurfaced as the primary url. Observe listDomains (only for
workers that persist domains, preserving #926's fan-out cut) and carry
forward only hostnames still attached. Also fixes the update path
writing domain: undefined instead of the carried-forward config.

WorkerUrls test now confirms DNS over DoH before its first fetch — an
early system-resolver lookup negative-caches NXDOMAIN for the zone's
30-minute SOA minimum TTL and poisons every later fetch in the test.

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

Adopts #975's urlStable carry-forward for unmanaged domains against the
new domain-config shape, and its plan-noop regression assertion in
WorkerDomain.test.ts.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin
sam-goodwin marked this pull request as ready for review July 28, 2026 22:14
@alchemy-version-bot

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

Copy link
Copy Markdown
Contributor

Install the packages built from this commit:

alchemy

bun add alchemy@https://pkg.ing/alchemy/1990f82

@alchemy.run/better-auth

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

@alchemy.run/pr-package

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

sam-goodwin and others added 5 commits July 28, 2026 15:57
… coverage

- workers.mdx / custom-domains.mdx: replace prose blocks with short
  code snippets per concept
- WorkerUrls redirect test now deploys name + alias + redirect together
  and fetches the alias to prove it serves the Worker

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- 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>
…swarm #972) into url redesign

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The website build's diff-indent check requires +/- markers as an extra
column before the code's full indentation, and at least one flush
context line so expressive-code doesn't strip a marker column from
every line. Fixes the telemetry tutorial's one-space-short markers and
anchors the swarm doc's fragment with its enclosing call.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@sam-goodwin
sam-goodwin merged commit 3306118 into main Jul 29, 2026
9 checks passed
@sam-goodwin
sam-goodwin deleted the claude/worker-url-domain-redesign-v2 branch July 29, 2026 01:00
sam-goodwin added a commit that referenced this pull request Jul 29, 2026
…r-aggregating destroy

Ports into the LocalProvider.make structure:
- make-before-break serveWith (workerd scopes fork from rootScope, closed on
  cutover / closeWorkerd) from #863
- url/urls/domain Attributes + resolveLocalUrls wildcard-host handling from #977
  (local urls no longer carry a trailing slash; tests updated to `${url}/path`)
- ALCHEMY_WORKER_NAME env (#860), viteMain root-relative resolution (#796),
  toRuntimeBinding dev.remote param for send_email (#865)

distilled bumped to main (0.30.2).

Co-authored-by: Cursor <cursoragent@cursor.com>
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.

2 participants