alchemy 2.0.0-beta.65 → 2.0.0-beta.67

package/src/Cloudflare/Workers/Worker.ts

@@ -11,6 +11,7 @@ import { type MemoOptions } from "../../Command/Memo.ts";
 import type { Dependencies } from "../../Dependencies.ts";
 import type { InputProps } from "../../Input.ts";
 import type { Named, Tag } from "../../Named.ts";
+import type * as Output from "../../Output.ts";
 import {
   Platform,
   type Main,
@@ -278,6 +279,13 @@ export type WorkerBindingProps = {
     | Effect.Effect<WorkerBindingResource, any, any>;
 };
 
+type Unwrap<T> = T extends Output.Output<infer A, infer _Req> ? A : T;
+
+// NOTE: `Worker<NormalizedBindings<...>>` must provably satisfy the
+// `WorkerBindings` constraint for *generic* `Bindings`, which restricts the
+// shapes usable here: conditional checks on the naked parameter `T` and an
+// outermost `Extract<..., WorkerBindingResource>` are provable; e.g.
+// `Unwrap<T> extends ...` as a check type is not.
 export type NormalizedBindings<
   Bindings extends WorkerBindingProps = {},
   AssetsConfig extends WorkerAssetsConfig | undefined = undefined,
@@ -287,14 +295,71 @@ export type NormalizedBindings<
     any,
     any
   >
-    ? T extends Redacted.Redacted<infer T> | Config.Config<infer T>
-      ? T
-      : T
-    : Extract<Bindings[B], WorkerBindingResource>;
+    ? T extends Redacted.Redacted<infer V> | Config.Config<infer V>
+      ? V
+      : Unwrap<T>
+    : Extract<Unwrap<Bindings[B]>, WorkerBindingResource>;
 } & (undefined extends AssetsConfig ? {} : { ASSETS: Assets });
 
 export type WorkerAssetsConfig = string | AssetsProps | AssetsWithHash;
 
+/**
+ * Fine-grained control over the Worker's `workers.dev` surface. The two
+ * toggles are independent on the Cloudflare API.
+ */
+export interface WorkersDevConfig {
+  /**
+   * Serve the Worker at its stable `workers.dev` URL
+   * (`https://<worker-name>.<account-subdomain>.workers.dev`).
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Enable version preview URLs — a distinct
+   * `https://<version-prefix>-<worker-name>.<account-subdomain>.workers.dev`
+   * URL per uploaded version, plus stable aliased preview URLs
+   * (`https://<alias>-...`) for versions uploaded with an alias.
+   *
+   * When previews are enabled but {@link enabled} is `false`, the current
+   * version's preview URL becomes the Worker's primary `url` output.
+   * @default true
+   */
+  previewsEnabled?: boolean;
+}
+
+/**
+ * The Worker's custom-domain configuration: one canonical hostname, plus
+ * optional aliases that also serve the Worker and redirect hostnames that
+ * 301 to the canonical name.
+ */
+export interface WorkerDomainConfig {
+  /**
+   * The canonical hostname (e.g. `"example.com"`). Attached to the Worker
+   * as a Cloudflare custom domain — DNS record and edge certificate are
+   * managed automatically. The Cloudflare zone is inferred from the
+   * hostname and must already exist in the account.
+   *
+   * When set, `https://<name>` is the Worker's primary `url` output.
+   */
+  name: string;
+  /**
+   * Additional hostnames that serve the Worker (e.g. `"www.example.com"`,
+   * `"api.example.com"`). Each is attached as its own custom domain.
+   * Order matters: aliases follow `name` in the `urls` output.
+   */
+  aliases?: string[];
+  /**
+   * Hostnames that permanently redirect (HTTP 301, path and query
+   * preserved) to {@link name} — e.g. `"old.example.com"`. Each is
+   * attached as a custom domain (for DNS + TLS) with a redirect rule in
+   * the zone's `http_request_dynamic_redirect` phase, which runs before
+   * the Worker — redirected requests never invoke it. Redirect hostnames
+   * serve no content, so they appear in the `domain` output but never in
+   * `urls`.
+   */
+  redirects?: string[];
+}
+
 export interface WorkerRouteConfig {
   /**
    * URL pattern to match incoming requests against, e.g.
@@ -317,6 +382,187 @@ export interface WorkerRouteConfig {
   zone?: ZoneReference;
 }
 
+/**
+ * Version-affinity configuration — keeps each user on one version for the
+ * duration of a gradual rollout.
+ *
+ * Percentages route each request independently, so one user can bounce
+ * between versions mid-rollout. Cloudflare pins a request to a version
+ * deterministically when it carries a `Cloudflare-Workers-Version-Key`
+ * header: the key is hashed and assigned a version from the current
+ * percentages, so equal keys always land on the same version, and pinned
+ * users only move forward as percentages rise.
+ *
+ * Setting `affinity` provisions that header as infrastructure: a `rewrite`
+ * Transform Rule in the `http_request_late_transform` phase of every zone
+ * the Worker serves on (custom domains and zone routes), scoped to the
+ * Worker's hostnames, filling the header from the configured source. The
+ * rule is updated in place as the config changes and removed when
+ * `affinity` is removed or the Worker is destroyed; other rules in the
+ * zone's shared entrypoint are left untouched.
+ *
+ * Exactly one of {@link cookie}, {@link header}, or {@link key} may be
+ * set; {@link ip} combines with `cookie`/`header` as a fallback or stands
+ * alone as the sole source.
+ *
+ * Transform Rules only see **zone traffic** — the Worker must have a
+ * `domain` or `routes` (or, with `version.parent`, the parent must).
+ * A workers.dev-only Worker fails the deploy with
+ * `WorkerVersionConfigError`; on the bare workers.dev URL clients must
+ * send the header themselves.
+ */
+export interface WorkerVersionAffinity {
+  /**
+   * Pin by the value of this request cookie (e.g. a session id). Requests
+   * without the cookie fall back to {@link ip} when set, otherwise they
+   * route independently by percentage.
+   */
+  cookie?: string;
+  /**
+   * Pin by the value of this request header (e.g. a tenant or user id
+   * your edge already stamps, or a stable auth claim forwarded as a
+   * header). Requests without the header fall back to {@link ip} when
+   * set, otherwise they route independently by percentage.
+   */
+  header?: string;
+  /**
+   * Pin by client IP. On its own (`{ ip: true }`) every request is keyed
+   * by `ip.src`; combined with {@link cookie} or {@link header} it is the
+   * fallback for requests missing the primary source (e.g. sticky by
+   * session cookie, falling back to sticky IP before the cookie is set).
+   */
+  ip?: boolean;
+  /**
+   * Escape hatch: a raw [Rules-language](https://developers.cloudflare.com/ruleset-engine/rules-language/)
+   * expression that computes the version key — e.g. a JWT claim via API
+   * Shield's `http.request.jwt.claims`, or any composite of request
+   * fields. Applied to every request on the Worker's hostnames; cannot be
+   * combined with the other sources.
+   */
+  key?: string;
+}
+
+/**
+ * Versioning configuration for a Worker deploy — controls Worker
+ * [versions and gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/).
+ *
+ * Two modes, selected by {@link parent}:
+ *
+ * - **Version worker** (`parent` set): instead of creating its own script,
+ *   this Worker uploads an immutable *version* to the referenced parent
+ *   Worker's script. With `traffic: 0` (the default) the parent's live
+ *   deployment is untouched and the version is reachable only at its
+ *   preview URL (`<version-prefix>-<name>.<subdomain>.workers.dev`) —
+ *   the PR-preview use case. With `traffic > 0` the version becomes a
+ *   canary taking that percentage of the parent's traffic.
+ * - **Gradual rollout** (`parent` omitted): when this Worker deploys
+ *   itself, the newly uploaded version receives {@link traffic} percent
+ *   and the currently-live version keeps the remainder, instead of the
+ *   default 100% cutover.
+ *
+ * A gradual rollout carries only what a version can: code, bindings,
+ * compatibility settings, and cache configuration. Workers with static
+ * assets cannot roll out gradually (the versions API cannot carry assets),
+ * a deploy that changes Durable Object class migrations must go out at
+ * 100% (migrations cannot ride a rollout), and script-level settings
+ * (tags, observability, limits, placement, logpush) keep their live
+ * values until the next full deploy.
+ */
+export interface WorkerVersionOptions {
+  /**
+   * The Worker that owns the script this version is uploaded to. Accepts a
+   * Worker reference — typically `yield* Cloudflare.Worker.ref(id, { stage,
+   * stack })` for a Worker deployed in another stage/stack, or a
+   * locally-declared Worker — or a literal script name as an escape hatch.
+   *
+   * When set, this resource does not create a script of its own: it
+   * uploads a version (code + bindings + compatibility settings) to the
+   * parent's script. Script-level settings apply immediately to *all*
+   * versions of the parent, so they cannot be set on a version worker —
+   * `name`, `assets`, `namespace`, `crons`, `domain`, `routes`, `tags`,
+   * `logpush`, `observability`, `placement`, `limits`, and `subdomain` are
+   * rejected, as are locally-hosted Durable Object or Workflow classes
+   * (their migrations would mutate the parent).
+   *
+   * Changing the parent replaces the resource (a version belongs to
+   * exactly one script).
+   */
+  parent?: string | Worker;
+  /**
+   * Percentage of traffic (0–100) the newly uploaded version receives; the
+   * currently-live version keeps the remainder. Cloudflare deployments
+   * split between at most two versions, so one canary can be active per
+   * script at a time.
+   *
+   * With {@link parent} set, defaults to `0`: the version is
+   * preview-URL-only and the parent's live deployment is untouched.
+   * Without `parent`, defaults to `100` (today's full cutover); `0` means
+   * "upload the version without deploying it" (the equivalent of
+   * `wrangler versions upload`).
+   *
+   * Percentages replace the previous deployment, they never add. Each
+   * versioned deploy splits its new version against the *stable* version —
+   * the majority holder of the current deployment — so deploying at 10 and
+   * then at 20 yields the second version at 20% against the stable version
+   * at 80%, with the earlier 10% version dropped from routing entirely
+   * (still uploaded, but unreachable even via a version-override header).
+   * With unchanged code that replacement is exactly a ramp; with changed
+   * code it swaps canaries. The first deploy of a script always goes to
+   * 100%, since there is no previous version to split with.
+   *
+   * Note that a subsequent full deploy of the parent (or of this Worker
+   * itself, at the default 100) resets traffic to 100% of its own new
+   * version.
+   */
+  traffic?: number;
+  /**
+   * Preview-URL alias for the uploaded version. Aliased preview URLs
+   * (`<alias>-<name>.<subdomain>.workers.dev`) are stable — each upload
+   * with the same alias re-points the URL at the new version — which is
+   * what makes them useful as shareable PR-preview links and lets
+   * `Worker.URL` resolve before the version exists.
+   *
+   * For a version worker ({@link parent} set) an alias is derived
+   * automatically from the stack, stage, and logical id, so every version
+   * worker gets a stable preview URL out of the box; set this to override
+   * it. Must start with a lowercase letter, contain only lowercase
+   * letters, digits, and dashes, and `<alias>-<worker-name>` must fit in
+   * 63 characters (a DNS label).
+   */
+  alias?: string;
+  /**
+   * Keep each user on one version for the duration of the rollout by
+   * pinning them to a stable request property — a session cookie, a
+   * header, the client IP, or a raw Rules-language expression:
+   *
+   * ```typescript
+   * version: {
+   *   traffic: 10,
+   *   // sticky by session cookie, falling back to sticky IP
+   *   affinity: { cookie: "session_id", ip: true },
+   * }
+   * ```
+   *
+   * Provisions a Transform Rule that fills the
+   * `Cloudflare-Workers-Version-Key` header on the zones the Worker
+   * serves on — the Worker (or, with {@link parent}, the parent) must
+   * have a `domain` or `routes`. With `parent` set, the rule lands on the
+   * parent's zones, pinning users across the canary split. See
+   * {@link WorkerVersionAffinity}.
+   */
+  affinity?: WorkerVersionAffinity;
+  /**
+   * Human-readable annotation attached to the uploaded version, shown in
+   * the Cloudflare dashboard and `wrangler versions list`.
+   */
+  message?: string;
+  /**
+   * Machine-readable tag annotation attached to the uploaded version
+   * (e.g. a git commit SHA or PR number).
+   */
+  tag?: string;
+}
+
 export interface WorkerProps<
   Bindings extends WorkerBindingProps = any,
   Assets extends WorkerAssetsConfig | undefined =
@@ -350,21 +596,38 @@ export interface WorkerProps<
    */
   namespace?: string | DispatchNamespace;
   /**
-   * Whether to enable a workers.dev URL for this worker
+   * Worker versions & gradual deployments. Set `version.parent` to upload
+   * this Worker as a preview/canary *version* of another Worker's script
+   * instead of creating its own; set `version.traffic` below 100 to
+   * gradually roll out a deploy of this Worker's own script. See
+   * {@link WorkerVersionOptions}.
+   */
+  version?: WorkerVersionOptions;
+  /**
+   * Controls the Worker's `workers.dev` surface.
+   *
+   * - `true` (the default) — serve the Worker at its stable `workers.dev`
+   *   URL and enable version preview URLs.
+   * - `false` — no `workers.dev` URLs at all.
+   * - An object — toggle the stable URL and version previews independently,
+   *   e.g. `{ enabled: false, previewsEnabled: true }` keeps the stable URL
+   *   off while each deployed version stays reachable at its preview URL.
+   *
    * @default true
    */
-  url?: boolean;
+  workersDev?: boolean | WorkersDevConfig;
   /**
    * Static assets to serve. Can be:
    * - A string path to the assets directory
    * - An AssetsProps object with directory and config
    * - An object with path and hash (e.g., from a Build resource)
+   *
+   * When neither {@link main} nor {@link script} is provided, the Worker is
+   * deployed **assets-only**: no script is uploaded at all and Cloudflare's
+   * asset layer serves every request, applying `htmlHandling` /
+   * `notFoundHandling` (including single-page-application fallback) itself.
    */
   assets?: Assets;
-  subdomain?: {
-    enabled?: boolean;
-    previewsEnabled?: boolean;
-  };
   /** @internal used by Cloudflare.Website.Vite resource */
   vite?: ViteOptions;
   logpush?: boolean;
@@ -401,7 +664,8 @@ export interface WorkerProps<
   tags?: string[];
   /**
    * Path to the Worker's entry module. Bundled with rolldown before
-   * upload. Mutually exclusive with {@link script} — provide exactly one.
+   * upload. Mutually exclusive with {@link script} — provide at most one.
+   * Omit both (with {@link assets} set) to deploy an assets-only Worker.
    *
    * A `.py` entry deploys a Python Worker instead: no bundling runs — the
    * entry plus every sibling `.py` file upload as Python modules, the
@@ -444,6 +708,11 @@ export interface WorkerProps<
    *   [Secrets & env](/cloudflare/security/secrets-env).
    * - Literal values — routed by shape: `Redacted<string>` →
    *   `secret_text`, `string` → `plain_text`, anything else → `json`.
+   * - `Output` values that resolve to a plain env value (e.g.
+   *   `Alchemy.makeRandom`) — classified at deploy time by their
+   *   resolved value using the literal rules above. Whole-resource
+   *   Outputs (`Output.of(bucket)`) are rejected at deploy time; bind
+   *   the resource itself instead.
    *
    * In Effect-native Workers you can alternatively `yield*` a
    * `Config` in the Init phase to register the binding implicitly;
@@ -464,11 +733,20 @@ export interface WorkerProps<
    */
   crons?: string[];
   /**
-   * One or more custom hostnames (e.g. `"app.example.com"`) to bind to this
-   * Worker. The Cloudflare Zone is inferred from the hostname — the zone must
-   * already exist in the account.
+   * The Worker's custom domain: one canonical hostname, plus optional
+   * `aliases` that also serve the Worker and `redirects` that 301 to the
+   * canonical name. A bare string is shorthand for `{ name }`. The
+   * Cloudflare zone is inferred from each hostname — the zone must already
+   * exist in the account.
+   *
+   * When set, `https://<name>` becomes the Worker's primary `url` output,
+   * ranking above the `workers.dev` URL. See {@link WorkerDomainConfig}.
+   *
+   * Omitting the prop leaves custom domains unmanaged — attachments made
+   * outside Alchemy are preserved. Pass `null` to explicitly detach every
+   * custom domain (and remove their redirect rules).
    */
-  domain?: string | string[];
+  domain?: string | WorkerDomainConfig | null;
   /**
    * Zone routes that map URL patterns to this Worker. Equivalent to Wrangler's
    * `routes` array — provide `zoneName` or `zoneId` (or `zone`) alongside each
@@ -549,6 +827,22 @@ export interface WorkerProps<
          * @default false
          */
         strictPort?: boolean;
+        /**
+         * Whether the local runtime's Cache API simulator
+         * (`caches.default` / `caches.open()`) stores responses. Set
+         * `false` to make every cache operation a no-op — matching
+         * production behaviour on `workers.dev` subdomains, where the
+         * Cache API silently does nothing.
+         * @default true
+         */
+        cache?: boolean;
+        /**
+         * Override the `request.cf` blob served to this Worker locally.
+         * Defaults to a static placeholder (Miniflare's Austin/DFW blob);
+         * pass e.g. `{ colo: "LHR", country: "GB" }` to simulate a
+         * different edge location.
+         */
+        cf?: Record<string, unknown>;
       }
     | {
         /**
@@ -646,13 +940,75 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<
      */
     namespace: string | undefined;
     logpush: boolean | undefined;
+    /**
+     * The most significant URL the Worker is reachable at — always
+     * `urls[0]`, or `undefined` when the Worker is not reachable at any
+     * URL (e.g. a dispatch-namespace user worker). Ranking: the canonical
+     * custom domain, then aliases, then the stable `workers.dev` URL; a
+     * version worker's `url` is its aliased preview URL; under
+     * `alchemy dev` it is the local dev server's URL.
+     */
     url: string | undefined;
+    /**
+     * Every URL that serves this Worker, most significant first —
+     * `[https://<domain.name>?, ...aliases, <workers.dev URL>?,
+     * <version preview URLs>?]`, or the local dev server's
+     * `[localhost, ...LAN]` URLs under `alchemy dev`. Redirect hostnames
+     * never appear (they don't serve the Worker). Useful wholesale, e.g.
+     * as a CORS allow-list.
+     */
+    urls: string[];
+    /**
+     * The Worker's resolved custom-domain configuration — canonical
+     * `name`, `aliases`, and `redirects` as deployed — or `undefined`
+     * when no custom domain is configured.
+     */
+    domain:
+      | { name: string; aliases: string[]; redirects: string[] }
+      | undefined;
     tags: string[] | undefined;
     durableObjectNamespaces: Record<string, string>;
     accountId: string;
-    domains: string[];
     routes: { id: string; pattern: string; zoneId: string }[];
     crons: string[];
+    /**
+     * The parent script name this Worker uploads versions to, when this
+     * resource is a version worker (`version.parent` set). `undefined` for
+     * a Worker that owns its own script — including one deploying with a
+     * gradual rollout. This is the discriminator `read`/`delete` use to
+     * avoid treating the parent's script as this resource's own.
+     */
+    versionOf?: string | undefined;
+    /**
+     * The id of the version uploaded by the most recent deploy. Only set
+     * when versioning is in play: always for a version worker
+     * (`version.parent`), and for a self-owned Worker when a gradual
+     * rollout (`version.traffic` < 100) deployed via the versions API.
+     */
+    versionId?: string | undefined;
+    /**
+     * The preview-URL alias attached to the uploaded version — the
+     * user-provided `version.alias`, or the auto-derived stable alias for
+     * a version worker. The aliased preview URL
+     * (`<alias>-<name>.<subdomain>.workers.dev`) is stable across
+     * deploys and is the version worker's primary `url`.
+     */
+    versionAlias?: string | undefined;
+    /**
+     * The id of the deployment created by the most recent deploy, when the
+     * deploy created one through the deployments API (a version with
+     * `traffic > 0`). Preview-only versions (`traffic: 0`) have no
+     * deployment.
+     */
+    deploymentId?: string | undefined;
+    /**
+     * The zone ids currently holding this resource's version-affinity
+     * Transform Rules (`version.affinity`) — the cleanup list consulted
+     * when affinity is removed or the resource is deleted. For a version
+     * worker these are the *parent's* zones. `undefined` when no affinity
+     * rules are deployed.
+     */
+    affinityZoneIds?: string[] | undefined;
     hash?: {
       assets: string | undefined;
       bundle: string | undefined;
@@ -677,10 +1033,91 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<
     containers?: { className: string; dev: DevContainerImage | undefined }[];
     crons?: string[];
     hyperdrives?: Record<string, Required<DevOrigin>>;
+    dev?: { remote?: boolean };
   },
   Providers
 >;
 
+/** The env key the resolved URL is injected under when `yield*`-ed. */
+const SELF_URL_BINDING_NAME = "WORKER_URL";
+
+/**
+ * Effect-native accessor for the Worker's own URL. The value is injected as an
+ * env binding that only exists at the *exec* phase on the deployed Worker, so
+ * reading it is deferred behind an Effect that requires {@link RuntimeContext}.
+ * Yield it inside a handler to obtain the URL string.
+ */
+export type URLAccessor = Effect.Effect<string, never, RuntimeContext>;
+
+/**
+ * The type of {@link URL} (`Worker.URL`).
+ *
+ * It is a real `Effect` — `yield* Worker.URL` inside a Worker init attaches
+ * the binding and resolves the deferred {@link URLAccessor} — but it also
+ * carries the `~alchemy/Kind` marker statically, so when it is declared on a
+ * Worker's `env` the binding machinery recognises it as a `self_url` binding
+ * (`isSelfUrl`) instead of running it.
+ *
+ * Defined in this module (not its own file): the effect closes over the
+ * `Worker` tag and `WorkerEnvironment`, and a separate module would form a
+ * value cycle with Worker.ts that the deploy bundler's scope hoisting turns
+ * into a startup crash.
+ */
+export interface URLEffect extends Effect.Effect<
+  URLAccessor,
+  never,
+  WorkerEnvironment | Worker
+> {
+  "~alchemy/Kind": "Cloudflare.Workers.URL";
+}
+
+/**
+ * A Worker's own public URL, injected as a binding on that same Worker. At
+ * deploy time Alchemy resolves the URL the Worker will be served at (its first
+ * custom domain if any, otherwise its `workers.dev` URL) and injects it as a
+ * plain-text env binding, so the running Worker knows its own public address.
+ *
+ * Declare it on a Worker's `env` (it flows through `InferEnv` → `string`) or
+ * `yield*` it inside an Effect-native Worker to attach the binding and obtain
+ * a deferred {@link URLAccessor}. It is also exposed as
+ * `Cloudflare.Worker.URL`.
+ *
+ * Because the URL is resolved *before* the bundle is built, a `VITE_`-prefixed
+ * env key holding `Worker.URL` is inlined into the client bundle as
+ * `import.meta.env.VITE_*` — the canonical way to give a Vite frontend its own
+ * public URL.
+ */
+export const URL: URLEffect = Object.assign(
+  Effect.gen(function* () {
+    // Deploy-time only: register the binding on the host Worker. The provider
+    // lowers the `self_url` sentinel into a plain-text binding holding the
+    // resolved URL just before upload.
+    if (!globalThis.__ALCHEMY_RUNTIME__) {
+      yield* (yield* Worker).bind`${SELF_URL_BINDING_NAME}`({
+        bindings: [{ type: "self_url", name: SELF_URL_BINDING_NAME }],
+      });
+    }
+    // Captured at init; the deferred read only runs at exec phase (the
+    // accessor is colored with RuntimeContext), where env is populated.
+    const env = yield* WorkerEnvironment;
+    return Effect.sync(
+      () => (env as Record<string, string>)[SELF_URL_BINDING_NAME]!,
+    ) as URLAccessor;
+  }),
+  { "~alchemy/Kind": "Cloudflare.Workers.URL" as const },
+);
+
+/**
+ * Returns true when the value is the `Worker.URL` binding (keyed on the
+ * static `~alchemy/Kind` marker — the value is a real Effect, so every
+ * env-resolution site must check this before `Effect.isEffect`).
+ */
+export const isSelfUrl = (value: unknown): value is URLEffect =>
+  typeof value === "object" &&
+  value !== null &&
+  "~alchemy/Kind" in value &&
+  (value as URLEffect)["~alchemy/Kind"] === "Cloudflare.Workers.URL";
+
 /**
  * A Cloudflare Worker host with deploy-time binding support and runtime export
  * collection.
@@ -921,6 +1358,22 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<
  * }
  * ```
  *
+ * @example Assets-only Worker (static site)
+ * Omit `main` and `script` entirely to deploy a static site: no Worker
+ * code is uploaded — Cloudflare's asset layer serves every request and
+ * applies `htmlHandling` / `notFoundHandling` (including SPA fallback)
+ * itself, exactly like an assets-only `wrangler deploy`.
+ * ```typescript
+ * const site = yield* Cloudflare.Worker("Site", {
+ *   assets: {
+ *     directory: "./public",
+ *     htmlHandling: "drop-trailing-slash",
+ *     notFoundHandling: "404-page",
+ *   },
+ *   domain: "static.example.com",
+ * });
+ * ```
+ *
  * @example Zone routes
  * ```typescript
  * {
@@ -947,6 +1400,170 @@ export type Worker<Bindings extends WorkerBindings = any> = Resource<
  * }
  * ```
  *
+ * @section URLs & Domains
+ * Every URL that serves the Worker is collected in `worker.urls`, most
+ * significant first, and `worker.url` is always `urls[0]`. The ranking:
+ * the canonical custom domain (`domain.name`), then aliases in declared
+ * order, then the stable `workers.dev` URL, then version preview URLs.
+ * Under `alchemy dev`, `urls` is the local dev server's
+ * `[localhost, ...LAN]` addresses instead. Redirect hostnames never
+ * appear in `urls` — they serve no content.
+ *
+ * The `workersDev` prop controls the `workers.dev` surface (`true` by
+ * default = stable URL + version previews; `false` = neither; object form
+ * toggles independently), and the `domain` prop attaches custom domains —
+ * DNS records and edge certificates are managed automatically.
+ *
+ * @example Custom domain with aliases and redirects
+ * ```typescript
+ * const worker = yield* Cloudflare.Worker("Api", {
+ *   main: "./src/api.ts",
+ *   domain: {
+ *     name: "example.com",
+ *     aliases: ["www.example.com"],
+ *     redirects: ["old.example.com"], // 301 → https://example.com
+ *   },
+ * });
+ * // worker.url  === "https://example.com"
+ * // worker.urls === ["https://example.com", "https://www.example.com",
+ * //                  "https://<name>.<account>.workers.dev"]
+ * ```
+ *
+ * @example workers.dev toggles
+ * ```typescript
+ * // No workers.dev URLs at all:
+ * { main: "./src/api.ts", workersDev: false, domain: "api.example.com" }
+ *
+ * // Previews only — each deploy's version preview URL becomes worker.url:
+ * { main: "./src/api.ts", workersDev: { enabled: false, previewsEnabled: true } }
+ * ```
+ *
+ * @example All URLs as a CORS allow-list
+ * ```typescript
+ * const site = yield* Cloudflare.Worker("Site", {
+ *   main: "./src/site.ts",
+ *   domain: { name: "example.com", aliases: ["www.example.com"] },
+ * });
+ * const api = yield* Cloudflare.Worker("Api", {
+ *   main: "./src/api.ts",
+ *   env: { ALLOWED_ORIGINS: site.urls },
+ * });
+ * ```
+ *
+ * @section Versions & Gradual Deployments
+ * The `version` prop maps Cloudflare's
+ * [versions and gradual deployments](https://developers.cloudflare.com/workers/configuration/versions-and-deployments/)
+ * onto Alchemy stages. A Worker with `version.parent` set uploads an
+ * immutable *version* to the parent Worker's script instead of creating its
+ * own — by default with no traffic, reachable only at its preview URL
+ * (`worker.url`), which is the PR-preview workflow. Give it `traffic` to
+ * run it as a canary, or use `version.traffic` on a normal Worker to roll
+ * out its own deploys gradually.
+ *
+ * A version worker's `url` is its *aliased* preview URL
+ * (`<alias>-<name>.<subdomain>.workers.dev`) — the alias is derived from
+ * the stack, stage, and logical id (override with `version.alias`), so the
+ * URL is stable across deploys and always points at the latest uploaded
+ * version. The per-version URL (`<version-prefix>-...`) is also returned
+ * in `domains`. Because the aliased URL is known before the version
+ * exists, `Worker.URL` works on version workers and resolves to it.
+ *
+ * A version carries code, bindings, and compatibility settings. Script-level
+ * settings (routes, domains, crons, tags, observability, …) belong to the
+ * parent and are rejected on version workers, as are locally-hosted Durable
+ * Object or Workflow classes. Preview URLs require the parent's workers.dev
+ * subdomain to be enabled (the default).
+ *
+ * @example PR preview: a version of another stage's Worker
+ * ```typescript
+ * // The staging stage deploys the real Worker; a PR stage uploads its
+ * // code as a zero-traffic version of staging's script and gets back a
+ * // stable preview URL.
+ * const parent = yield* Cloudflare.Worker.ref("MyWorker", {
+ *   stage: "staging",
+ * });
+ * const preview = yield* Cloudflare.Worker("MyWorker", {
+ *   main: "./src/worker.ts",
+ *   version: { parent, message: `PR #${process.env.PR_NUMBER}` },
+ * });
+ * // preview.url -> https://<alias>-<name>.<subdomain>.workers.dev
+ * // (stable across deploys; re-points at each newly uploaded version)
+ * ```
+ *
+ * @example Canary: send 10% of the parent's traffic to a version
+ * ```typescript
+ * const parent = yield* Cloudflare.Worker.ref("MyWorker", { stage: "prod" });
+ * yield* Cloudflare.Worker("MyWorker", {
+ *   main: "./src/worker.ts",
+ *   version: { parent, traffic: 10 },
+ * });
+ * ```
+ *
+ * @example Gradual rollout of a Worker's own deploy
+ * ```typescript
+ * // The new version takes 25% of traffic; the previously-live version
+ * // keeps 75%. Bump traffic (or remove the prop) and re-deploy to promote.
+ * yield* Cloudflare.Worker("MyWorker", {
+ *   main: "./src/worker.ts",
+ *   version: { traffic: 25 },
+ * });
+ * ```
+ *
+ * @example Keep users on one version during the rollout
+ * ```typescript
+ * // Percentages route each request independently; affinity pins users by
+ * // filling the Cloudflare-Workers-Version-Key header on zone traffic —
+ * // here from the session cookie, falling back to the client IP. Requires
+ * // a `domain` or `routes` (with `parent`, the parent's).
+ * yield* Cloudflare.Worker("MyWorker", {
+ *   main: "./src/worker.ts",
+ *   domain: "api.example.com",
+ *   version: {
+ *     traffic: 25,
+ *     affinity: { cookie: "session_id", ip: true },
+ *   },
+ * });
+ * ```
+ *
+ * @section The Worker's own URL
+ * `Worker.URL` injects the URL a Worker is served at as a binding on that
+ * same Worker — the first custom `domain` if one is configured, otherwise
+ * its `workers.dev` URL, always equal to the resource's `url` attribute.
+ * Under `alchemy dev` it resolves to the local dev server's URL.
+ *
+ * @example Read the Worker's own URL inside a handler
+ * ```typescript
+ * Cloudflare.Worker(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     // Attaches the binding and returns a deferred accessor.
+ *     const url = yield* Cloudflare.Worker.URL;
+ *
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const publicUrl = yield* url;
+ *         return Response.json({ url: publicUrl });
+ *       }),
+ *     };
+ *   }).pipe(Effect.provide(Cloudflare.Workers.URLBinding)),
+ * );
+ * ```
+ *
+ * @example Inject the URL into an async Worker's env
+ * `InferEnv` types the entry as `string`. A `VITE_`-prefixed key on a
+ * vite-built Worker is additionally inlined into the client bundle as
+ * `import.meta.env.VITE_PUBLIC_URL` at build time.
+ * ```typescript
+ * export const Worker = Cloudflare.Worker("Worker", {
+ *   main: "./src/worker.ts",
+ *   env: { PUBLIC_URL: Cloudflare.Worker.URL },
+ * });
+ *
+ * export type WorkerEnv = Cloudflare.InferEnv<typeof Worker>;
+ * //   { PUBLIC_URL: string }
+ * ```
+ *
  * @section Observability
  * Cloudflare Workers Observability is on by default — `logs.enabled` and
  * `logs.invocationLogs` are turned on if you don't pass an `observability`
@@ -1282,6 +1899,26 @@ export const Worker: ResourceClassLike<Worker> &
         Named<Id> & {
           new (): MakeShape<Shape, WorkerShape> & Named<Id> & Tag;
         };
+      /**
+       * Class form without an implementation — an external Worker (a plain
+       * bundled `main`, a raw `script`, or an assets-only Worker with no
+       * script at all):
+       *
+       * ```typescript
+       * export class Site extends Cloudflare.Worker<Site>()("Site", {
+       *   assets: { directory: "./public" },
+       * }) {}
+       * ```
+       */
+      <const Id extends string, Req = never>(
+        id: Id,
+        props:
+          | InputProps<WorkerProps>
+          | Effect.Effect<InputProps<WorkerProps>, ConfigError, Req>,
+      ): Effect.Effect<Worker & Rpc<{}>, never, Req | Providers> &
+        Named<Id> & {
+          new (): Named<Id> & Tag;
+        };
     };
     <
       const Bindings extends WorkerBindingProps = {},
@@ -1324,15 +1961,26 @@ export const Worker: ResourceClassLike<Worker> &
       Extract<Req, Container.Application<any>> | Providers
     > &
       Named<Id>;
-  } = Platform(WorkerTypeId, {
-  // Both hooks are wrapped in arrows so the imported references are resolved
-  // at call time rather than at module-load time. Worker.ts forms import
-  // cycles with both WorkerAsyncBindings.ts (which imports `isWorker` here)
-  // and WorkerRuntimeContext.ts (which imports `WorkerTypeId`/`WorkerEnvironment`
-  // here). Reading either binding eagerly here hits TDZ when Bun loads the
-  // package from node_modules in a different module-init order than the local
-  // workspace.
-  onCreate: (resource, props) =>
-    bindWorkerAsyncBindings(resource as Worker, props),
-  createRuntimeContext: (id) => makeWorkerRuntimeContext(id),
-});
+    /**
+     * The Worker's own public URL, injected as a binding on that same Worker.
+     * Declare it on `env` (`env: { VITE_PUBLIC_URL: Worker.URL }`) or
+     * `yield*` it inside an Effect-native Worker to obtain a deferred
+     * accessor. See {@link URLEffect}.
+     */
+    readonly URL: URLEffect;
+  } = Platform(
+  WorkerTypeId,
+  {
+    // Both hooks are wrapped in arrows so the imported references are resolved
+    // at call time rather than at module-load time. Worker.ts forms import
+    // cycles with both WorkerAsyncBindings.ts (which imports `isWorker` here)
+    // and WorkerRuntimeContext.ts (which imports `WorkerTypeId`/`WorkerEnvironment`
+    // here). Reading either binding eagerly here hits TDZ when Bun loads the
+    // package from node_modules in a different module-init order than the local
+    // workspace.
+    onCreate: (resource, props) =>
+      bindWorkerAsyncBindings(resource as Worker, props),
+    createRuntimeContext: (id) => makeWorkerRuntimeContext(id),
+  },
+  { URL },
+);