alchemy 2.0.0-beta.77 → 2.0.0-beta.78

package/lib/Cloudflare/Workers/WorkerProvider.js

@@ -23,6 +23,7 @@ import {} from "../../Resource.js";
 import { Stack } from "../../Stack.js";
 import { cachedFunction } from "../../Util/cached-function.js";
 import { initialCwd } from "../../Util/Node.js";
+import { isRedactedMarker } from "../../RuntimeContext.js";
 import { sha256Object } from "../../Util/sha256.js";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.js";
 import { localRuntimeServices } from "../LocalRuntime.js";
@@ -157,6 +158,50 @@ export const resolveVersionParentName = (version) => {
     const workerName = parent.workerName;
     return typeof workerName === "string" ? workerName : undefined;
 };
+/**
+ * A Worker's `preview` configuration is invalid — combined with
+ * `version.parent`, missing `preview.of`, a bad Preview name, or a
+ * script-level setting that belongs to the parent.
+ */
+export class WorkerPreviewConfigError extends Data.TaggedError("WorkerPreviewConfigError") {
+}
+/**
+ * Resolve the parent script *name* from a resolved `preview.of` prop.
+ *
+ * @internal
+ */
+export const resolvePreviewParentName = (preview) => {
+    const parent = preview?.of;
+    if (parent == null)
+        return undefined;
+    if (typeof parent === "string")
+        return parent;
+    const workerName = parent.workerName;
+    return typeof workerName === "string" ? workerName : undefined;
+};
+const toPreviewWireKey = (key) => key.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+const toPreviewWire = (value) => {
+    if (Array.isArray(value))
+        return value.map(toPreviewWire);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [
+            toPreviewWireKey(k),
+            toPreviewWire(v),
+        ]));
+    }
+    return value;
+};
+/** Convert Alchemy's binding array into wrangler's Preview `env` map. */
+const bindingsToPreviewEnv = (bindings) => {
+    const env = {};
+    for (const binding of bindings) {
+        const { name, ...rest } = binding;
+        if (typeof name !== "string")
+            continue;
+        env[name] = toPreviewWire(rest);
+    }
+    return env;
+};
 /**
  * The traffic percentage a *self-owned* Worker's new version should receive,
  * or `undefined` for the default full cutover. Only a `version` prop without
@@ -405,9 +450,14 @@ domain) => Effect.gen(function* () {
         }));
     }
     const zone = resolveWorkerDomainZone(config);
-    return zone === undefined
-        ? { name, aliases, redirects }
-        : { name, aliases, redirects, zone };
+    const previews = "previews" in config && config.previews === true ? true : undefined;
+    return {
+        name,
+        aliases,
+        redirects,
+        ...(zone === undefined ? {} : { zone }),
+        ...(previews === undefined ? {} : { previews }),
+    };
 });
 const isWorkersDevHostname = (hostname) => hostname.endsWith(".workers.dev");
 // Hostnames that only appear in local-dev state (the dev server's
@@ -449,6 +499,7 @@ export const stateWorkerDomain = (output) => {
             aliases: (domain.aliases ?? []).filter((h) => typeof h === "string"),
             redirects: (domain.redirects ?? []).filter((h) => typeof h === "string"),
             ...(zone === undefined ? {} : { zone }),
+            ...(domain.previews === true ? { previews: true } : {}),
         };
     }
     const legacy = stateCustomDomains(state?.domains);
@@ -670,7 +721,7 @@ export const shouldObserveWorkerCrons = (olds, output) => olds?.crons !== undefi
  * (`<subdomain>` in `https://<script>.<subdomain>.workers.dev`). When set,
  * Worker URL construction skips `GET /accounts/{id}/workers/subdomain`.
  */
-const CLOUDFLARE_WORKERS_SUBDOMAIN = Config.string("CLOUDFLARE_WORKERS_SUBDOMAIN").pipe(Config.map((value) => value.trim()), Config.option);
+const CLOUDFLARE_WORKERS_SUBDOMAIN = Config.String("CLOUDFLARE_WORKERS_SUBDOMAIN").pipe(Config.map((value) => value.trim()), Config.option);
 const WORKERS_SUBDOMAIN_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
 /**
  * Max concurrent `GET /zones/{id}/workers/routes` calls when observing the
@@ -790,6 +841,14 @@ const resolveWorkerMetadataHash = ({ props, bindings, accountId, stack, selfUrl,
             tag: props.version.tag,
         }
         : undefined,
+    preview: props.preview
+        ? {
+            of: resolvePreviewParentName(props.preview),
+            name: props.preview.name,
+            message: props.preview.message,
+            tag: props.preview.tag,
+        }
+        : undefined,
 }).pipe(Effect.flatMap((metadata) => sha256Object({ metadata })));
 export const WorkerProvider = () => ProviderLayer.dual(Worker, {
     live: () => LiveWorkerProvider(),
@@ -917,7 +976,7 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
         zoneCache.set(cacheKey, zoneId);
         return zoneId;
     });
-    const reconcileDomains = (scriptName, desired, zone) => Effect.gen(function* () {
+    const reconcileDomains = (scriptName, desired, zone, previewsEnabled) => Effect.gen(function* () {
         const { accountId } = yield* yield* CloudflareEnvironment;
         // Always query the live state of domains attached to *this*
         // Worker rather than trusting `_previous` from local state.
@@ -937,6 +996,7 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                     hostname: d.hostname,
                     zoneId: d.zoneId,
                     service: d.service ?? undefined,
+                    previewsEnabled: d.previewsEnabled === true,
                 },
             ]
             : [])), Effect.catch(() => Effect.succeed([])));
@@ -962,7 +1022,8 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                 ? undefined
                 : yield* inferZoneIdForHostname(hostname, zoneCache, zone);
             if (live &&
-                !shouldRecreateWorkerDomainAttachment(live.zoneId, desiredZoneId)) {
+                !shouldRecreateWorkerDomainAttachment(live.zoneId, desiredZoneId) &&
+                live.previewsEnabled === (previewsEnabled === true)) {
                 return {
                     hostname: live.hostname,
                     id: live.id,
@@ -1003,6 +1064,11 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                 hostname,
                 service: scriptName,
                 zoneId,
+                // Private-beta field — only send it when the user opted
+                // into custom-domain Previews. Omitting it keeps the
+                // public PUT /workers/domains body unchanged for everyone
+                // else.
+                ...(previewsEnabled === true ? { previewsEnabled: true } : {}),
             })
                 .pipe(Effect.retry({
                 while: (error) => error._tag === "WorkerNotFound",
@@ -1739,6 +1805,34 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
             skip: effectiveHash === output?.hash?.assets,
         };
     };
+    /**
+     * Merge `Worker["Binding"].env` from active bindings into `news.env`.
+     * Stack-level `worker.bind({ env })` is how a later resource (webhook
+     * secret, etc.) attaches env without the Worker init depending on it.
+     */
+    const secretTextFromEnvValue = (value) => {
+        if (Redacted.isRedacted(value)) {
+            const inner = Redacted.value(value);
+            return typeof inner === "string" ? inner : undefined;
+        }
+        if (isRedactedMarker(value) && typeof value.value === "string") {
+            return value.value;
+        }
+        return undefined;
+    };
+    const newsWithBoundEnv = (news, bindings) => {
+        const bound = {};
+        for (const binding of bindings) {
+            if (binding.action === "delete")
+                continue;
+            if (binding.data?.env)
+                Object.assign(bound, binding.data.env);
+        }
+        const boundKeys = Object.keys(bound);
+        if (boundKeys.length === 0)
+            return { news, boundKeys };
+        return { news: { ...news, env: { ...news.env, ...bound } }, boundKeys };
+    };
     /**
      * Append the standard Alchemy runtime bindings plus the user's `env`
      * entries (routed by shape: `Redacted` → secret_text, string →
@@ -1774,14 +1868,12 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                     continue;
                 if (metadataBindings.some((b) => b.name === key))
                     continue;
-                if (Redacted.isRedacted(value)) {
-                    const unredacted = Redacted.value(value);
+                const secretText = secretTextFromEnvValue(value);
+                if (secretText !== undefined) {
                     metadataBindings.push({
                         type: "secret_text",
                         name: key,
-                        text: typeof unredacted === "string"
-                            ? unredacted
-                            : JSON.stringify(unredacted),
+                        text: secretText,
                     });
                 }
                 else if (typeof value === "string") {
@@ -1978,6 +2070,7 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
      * with changed content simply uploads the next immutable version.
      */
     const putWorkerVersion = Effect.fn(function* (id, fqn, news, bindings, session, output) {
+        ({ news } = newsWithBoundEnv(news, bindings));
         const { accountId } = yield* yield* CloudflareEnvironment;
         const version = news.version;
         const parentName = resolveVersionParentName(version);
@@ -2192,7 +2285,254 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
             hash,
         };
     });
+    /**
+     * Reconcile a *Preview Worker*: create/update a first-class Preview of
+     * the parent script and upload this Worker's code + bindings as a
+     * Preview deployment. Isolated same-Worker Durable Object classes
+     * get their own namespace per Preview.
+     */
+    const putWorkerPreview = Effect.fn(function* (id, fqn, news, bindings, session, output) {
+        const { accountId } = yield* yield* CloudflareEnvironment;
+        const preview = news.preview;
+        const parentName = resolvePreviewParentName(preview);
+        if (parentName === undefined) {
+            return yield* Effect.fail(new WorkerPreviewConfigError({
+                message: `preview.of did not resolve to a Worker script name. Pass a Worker (e.g. \`yield* Cloudflare.Worker.ref(id, { stage })\`) or a literal script name.`,
+            }));
+        }
+        if (news.version !== undefined) {
+            return yield* Effect.fail(new WorkerPreviewConfigError({
+                message: `preview and version cannot be set together. Use preview.of for branch/PR Previews; use version.parent / version.traffic for canaries and gradual rollouts.`,
+            }));
+        }
+        const forbidden = [
+            ["name", news.name],
+            ["namespace", news.namespace],
+            ["crons", news.crons],
+            ["tailConsumers", news.tailConsumers],
+            ["streamingTailConsumers", news.streamingTailConsumers],
+            ["domain", news.domain],
+            ["routes", news.routes],
+            ["workersDev", news.workersDev],
+            ["access", news.access],
+        ].flatMap(([key, value]) => (value !== undefined ? [key] : []));
+        if (forbidden.length > 0) {
+            return yield* Effect.fail(new WorkerPreviewConfigError({
+                message: `preview.of creates a Preview of '${parentName}' — script-level settings belong to the parent Worker and cannot be set here: ${forbidden.join(", ")}. ` +
+                    `Remove ${forbidden.length === 1 ? "this prop" : "these props"} or configure ${forbidden.length === 1 ? "it" : "them"} on the parent.`,
+            }));
+        }
+        const cronBindings = getCronBindings(bindings);
+        if (cronBindings.length > 0) {
+            return yield* Effect.fail(new WorkerPreviewConfigError({
+                message: `Cron Triggers are script-level settings and cannot be registered from a Preview of '${parentName}'. Configure crons on the parent Worker.`,
+            }));
+        }
+        const budget = 63 - parentName.length - 1;
+        const userName = preview.name;
+        let previewName;
+        if (userName !== undefined) {
+            if (!/^[a-z][a-z0-9-]*$/.test(userName)) {
+                return yield* Effect.fail(new WorkerPreviewConfigError({
+                    message: `preview.name '${userName}' is invalid: names must start with a lowercase letter and contain only lowercase letters, digits, and dashes.`,
+                }));
+            }
+            if (userName.length > budget) {
+                return yield* Effect.fail(new WorkerPreviewConfigError({
+                    message: `preview.name '${userName}' is too long: '<name>-${parentName}' must fit in a 63-character DNS label, leaving ${Math.max(budget, 0)} characters for the name.`,
+                }));
+            }
+            previewName = userName;
+        }
+        else if (budget < 4) {
+            return yield* Effect.fail(new WorkerPreviewConfigError({
+                message: `Cannot derive a Preview name: '<name>-${parentName}' must fit in a 63-character DNS label. Set preview.name to a short value or shorten the parent's name.`,
+            }));
+        }
+        else {
+            const readable = stack.stage
+                .toLowerCase()
+                .replace(/[^a-z0-9-]+/g, "-")
+                .replace(/^-+|-+$/g, "");
+            const derived = (readable.length > 0 ? readable : `p${id}`)
+                .slice(0, budget)
+                .replace(/-+$/, "");
+            previewName = /^[a-z]/.test(derived)
+                ? derived
+                : `p${derived}`.slice(0, budget);
+        }
+        yield* Effect.logInfo(`Cloudflare Worker Preview: ${previewName} of ${parentName} (from ${id})`);
+        const existingPreview = yield* workers
+            .getPreview({
+            accountId,
+            workerId: parentName,
+            previewId: previewName,
+        })
+            .pipe(Effect.catchTag("PreviewNotFound", () => Effect.succeed(undefined)), Effect.catchTag("WorkerNotFound", () => Effect.fail(new WorkerPreviewConfigError({
+            message: `preview.of script '${parentName}' does not exist. Deploy the parent Worker first (or check the referenced stage/stack).`,
+        }))));
+        const previewResource = existingPreview ??
+            (yield* workers
+                .createPreview({
+                accountId,
+                workerId: parentName,
+                name: previewName,
+                ignoreBaseConfig: true,
+            })
+                .pipe(Effect.catchTag("WorkerNotFound", () => Effect.fail(new WorkerPreviewConfigError({
+                message: `preview.of script '${parentName}' does not exist. Deploy the parent Worker first (or check the referenced stage/stack).`,
+            })))));
+        const accountSubdomain = yield* getAccountSubdomain(accountId);
+        const parentAttrs = typeof preview.of === "object" && preview.of !== null
+            ? preview.of
+            : undefined;
+        const parentDomainName = parentAttrs?.domain?.name;
+        const parentDomainPreviews = parentAttrs?.domain?.previews === true;
+        const constructedUrls = [
+            ...(parentDomainPreviews && parentDomainName
+                ? [`https://${previewResource.slug}.${parentDomainName}`]
+                : []),
+            `https://${previewResource.slug}-${parentName}.${accountSubdomain}.workers.dev`,
+        ];
+        const stableUrl = previewResource.urls?.[0] ?? constructedUrls[0];
+        const selfUrl = hasSelfUrlBinding(bindings) ? stableUrl : undefined;
+        yield* Effect.logInfo(`Cloudflare Worker Preview: preparing bundle for ${parentName} (preview ${previewName})`);
+        const { assets, bundle, hash: preparedHash, } = yield* prepareAssetsAndBundle(id, fqn, parentName, news, {
+            skipAssetsRead: false,
+        });
+        const metadataHash = yield* resolveWorkerMetadataHash({
+            props: news,
+            bindings,
+            accountId,
+            stack: { name: stack.name, stage: stack.stage },
+            selfUrl,
+        });
+        const hash = {
+            ...preparedHash,
+            metadata: metadataHash,
+        };
+        const metadataBindings = bindings.flatMap((b) => (b.data.bindings ?? []).map((item) => item.type === "self_url"
+            ? { type: "plain_text", name: item.name, text: selfUrl }
+            : item.type === "self_service"
+                ? {
+                    type: "service",
+                    name: item.name,
+                    service: parentName,
+                }
+                : item));
+        let metadataAssets;
+        if (assets) {
+            yield* Effect.logInfo(`Cloudflare Worker Preview: uploading assets for ${parentName}`);
+            const { jwt } = yield* uploadAssets(accountId, parentName, assets, session);
+            metadataAssets = {
+                jwt,
+                config: mergeAssetsConfigFiles(assets.config, assets),
+            };
+            metadataBindings.push({ type: "assets", name: "ASSETS" });
+        }
+        appendAlchemyAndEnvBindings(metadataBindings, news, accountId, parentName);
+        const hostedClasses = getDurableObjectBindings(bindings, parentName);
+        const classNames = [...new Set(hostedClasses.map((c) => c.className))];
+        let migrations = undefined;
+        if (classNames.length > 0) {
+            const latest = yield* workers
+                .getPreviewDeployment({
+                accountId,
+                workerId: parentName,
+                previewId: previewResource.id,
+                deploymentId: "latest",
+            })
+                .pipe(Effect.catchTag(["PreviewNotFound", "PreviewDeploymentNotFound"], () => Effect.succeed(undefined)));
+            const oldTag = latest?.migrationTag ?? undefined;
+            const previous = output?.previewDoClasses ?? [];
+            if (oldTag === undefined) {
+                migrations = {
+                    new_tag: "alchemy:v1",
+                    new_sqlite_classes: classNames,
+                };
+            }
+            else {
+                const added = classNames.filter((c) => !previous.includes(c));
+                const deleted = previous.filter((c) => !classNames.includes(c));
+                if (added.length > 0 || deleted.length > 0) {
+                    migrations = {
+                        old_tag: oldTag,
+                        new_tag: bumpMigrationTagVersion(oldTag) ?? "alchemy:v1",
+                        ...(added.length > 0 ? { new_sqlite_classes: added } : {}),
+                        ...(deleted.length > 0 ? { deleted_classes: deleted } : {}),
+                    };
+                }
+            }
+        }
+        const compatibility = getCompatibility(news);
+        const annotations = preview.message !== undefined || preview.tag !== undefined
+            ? {
+                ...(preview.message !== undefined
+                    ? { "workers/message": preview.message }
+                    : {}),
+                ...(preview.tag !== undefined
+                    ? { "workers/tag": preview.tag }
+                    : {}),
+            }
+            : undefined;
+        yield* session.note(`Uploading Preview ${previewName} of ${parentName} ...`, {
+            kind: "status",
+        });
+        const deployment = yield* workers.createPreviewDeployment({
+            accountId,
+            workerId: parentName,
+            previewId: previewResource.id,
+            metadata: {
+                mainModule: bundle.main,
+                assets: metadataAssets,
+                compatibilityDate: compatibility.date,
+                compatibilityFlags: compatibility.flags,
+                cacheOptions: news.cache ?? getCacheBinding(bindings),
+                annotations,
+                migrations,
+                env: bindingsToPreviewEnv(metadataBindings),
+            },
+            files: bundle.files,
+        });
+        const refreshed = yield* workers
+            .getPreview({
+            accountId,
+            workerId: parentName,
+            previewId: previewResource.id,
+        })
+            .pipe(Effect.catchTag("PreviewNotFound", () => Effect.succeed(previewResource)));
+        const urls = [
+            ...new Set([
+                ...(refreshed.urls ?? []),
+                ...constructedUrls,
+                ...(deployment.urls ?? []),
+            ]),
+        ];
+        return {
+            workerId: cachedWorkerId(output?.workerId, parentName) ??
+                (yield* findWorkerId(accountId, parentName)),
+            workerName: parentName,
+            namespace: undefined,
+            logpush: undefined,
+            url: urls[0],
+            urls,
+            domain: undefined,
+            tags: undefined,
+            durableObjectNamespaces: {},
+            accountId,
+            routes: [],
+            crons: [],
+            previewOf: parentName,
+            previewId: previewResource.id,
+            previewName,
+            previewSlug: previewResource.slug,
+            previewDoClasses: classNames.length > 0 ? classNames : undefined,
+            deploymentId: deployment.id,
+            hash,
+        };
+    });
     const putWorker = Effect.fn(function* (id, fqn, news, bindings, olds, output, session, existingSettings) {
+        news = newsWithBoundEnv(news, bindings).news;
         const { accountId } = yield* yield* CloudflareEnvironment;
         // Prefer the deployed name: regenerating would target a different
         // script if the generator's output for this id ever drifts.
@@ -2846,7 +3186,7 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                 .pipe(Effect.map((r) => (r.result ?? []).flatMap((d) => d.hostname && d.zoneId
                 ? [[d.hostname, d.zoneId]]
                 : [])), Effect.catch(() => Effect.succeed([])));
-            const reconciled = yield* reconcileDomains(name, desiredHostnames, domainConfig?.zone);
+            const reconciled = yield* reconcileDomains(name, desiredHostnames, domainConfig?.zone, domainConfig?.previews);
             const zoneIdByHostname = new Map([
                 ...liveBeforeReconcile,
                 ...reconciled.map((d) => [d.hostname, d.zoneId]),
@@ -3028,15 +3368,20 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
             const versionParent = props.version?.parent != null
                 ? (resolveVersionParentName(props.version) ?? output.versionOf)
                 : undefined;
+            const previewParent = props.preview?.of != null
+                ? (resolvePreviewParentName(props.preview) ?? output.previewOf)
+                : undefined;
             const selfUrl = hasSelfUrlBinding(bindings)
-                ? versionParent !== undefined
-                    ? yield* Effect.gen(function* () {
-                        const alias = yield* resolveVersionAlias(id, props, versionParent);
-                        return alias !== undefined
-                            ? `https://${alias}-${versionParent}.${yield* getAccountSubdomain(accountId)}.workers.dev`
-                            : undefined;
-                    })
-                    : yield* resolveSelfUrl(output.workerName, props, accountId)
+                ? previewParent !== undefined
+                    ? output.url
+                    : versionParent !== undefined
+                        ? yield* Effect.gen(function* () {
+                            const alias = yield* resolveVersionAlias(id, props, versionParent);
+                            return alias !== undefined
+                                ? `https://${alias}-${versionParent}.${yield* getAccountSubdomain(accountId)}.workers.dev`
+                                : undefined;
+                        })
+                        : yield* resolveSelfUrl(output.workerName, props, accountId)
                 : undefined;
             const metadataHash = yield* resolveWorkerMetadataHash({
                 props,
@@ -3188,9 +3533,9 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
             if (newNamespace !== oldNamespace) {
                 return { action: "replace" };
             }
-            // A version worker (version.parent) and a script-owning Worker are
-            // distinct cloud resources, and a version belongs to exactly one
-            // parent script — switching mode or parent is a replacement.
+            // A version worker (version.parent), a Preview Worker
+            // (preview.of), and a script-owning Worker are distinct cloud
+            // resources — switching mode or parent is a replacement.
             const newIsVersion = news.version?.parent != null;
             const oldIsVersion = output?.versionOf !== undefined || olds?.version?.parent != null;
             if (newIsVersion !== oldIsVersion) {
@@ -3205,6 +3550,20 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                     return { action: "replace" };
                 }
             }
+            const newIsPreview = news.preview?.of != null;
+            const oldIsPreview = output?.previewOf !== undefined || olds?.preview?.of != null;
+            if (newIsPreview !== oldIsPreview) {
+                return { action: "replace" };
+            }
+            if (newIsPreview) {
+                const newParent = resolvePreviewParentName(news.preview);
+                const oldParent = output?.previewOf ?? resolvePreviewParentName(olds?.preview);
+                if (newParent !== undefined &&
+                    oldParent !== undefined &&
+                    newParent !== oldParent) {
+                    return { action: "replace" };
+                }
+            }
             const oldWorkerName = output?.workerName ?? (yield* createWorkerName(id, olds?.name));
             // Auto-generated names are engine-owned: the deployed name stays
             // authoritative even if the generator would name this id
@@ -3230,6 +3589,7 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                     d.aliases,
                     [...d.redirects].sort(),
                     d.zone ?? null,
+                    d.previews === true,
                 ]);
             // An omitted `domain` unmanages the surface (#942): reconcile
             // carries previously-observed custom domains forward in state, so
@@ -3373,8 +3733,8 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
             // no placeholder is needed for circular bindings either. (`news`
             // is raw here — `version.parent` may be an unresolved ref, but its
             // *presence* is statically known.)
-            if (news.version?.parent != null) {
-                yield* Effect.logInfo(`Cloudflare Worker precreate: skipping stub for version worker ${id}`);
+            if (news.version?.parent != null || news.preview?.of != null) {
+                yield* Effect.logInfo(`Cloudflare Worker precreate: skipping stub for ${news.preview?.of != null ? "Preview" : "version"} worker ${id}`);
                 return {
                     // Provisional: a version worker resolves its parent's
                     // immutable ID at reconcile — nothing observes this stub row
@@ -3545,6 +3905,19 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                 ({ durableObjectNamespaces } =
                     yield* getWorkerSettingsWithDurableObjects(name, doClasses, dispatchNamespace));
             }
+            /**
+             * Precreate publishes the stable `https://{name}.{subdomain}.workers.dev`
+             * URL when `workersDev` is enabled (the default). Cycle peers that
+             * interpolate `worker.url` (e.g. Stripe.WebhookEndpoint) need a
+             * valid HTTPS URL here — the previous `url: undefined` stub made
+             * Stripe reject `"undefined/webhooks/stripe"`. Custom domains and
+             * version/preview URLs are still unresolved; reconcile overwrites
+             * `url` with the final value. `workersDev: false` keeps `url`
+             * undefined.
+             */
+            const workersDevUrl = resolveWorkersDev(news.workersDev).enabled
+                ? `https://${name}.${yield* getAccountSubdomain(accountId)}.workers.dev`
+                : undefined;
             return {
                 // The placeholder upload's tag (or, when adopting an existing
                 // script, the listing lookup); reconcile re-records it after
@@ -3553,11 +3926,11 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                 workerName: name,
                 namespace: dispatchNamespace,
                 logpush: existingSettings?.logpush ?? undefined,
-                url: undefined,
+                url: workersDevUrl,
                 tags: existingSettings?.tags ?? tags,
                 durableObjectNamespaces,
                 accountId,
-                urls: [],
+                urls: workersDevUrl !== undefined ? [workersDevUrl] : [],
                 domain: undefined,
                 routes: [],
                 crons: [],
@@ -3586,6 +3959,18 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                 })
                     .pipe(Effect.map(() => output), Effect.catchTag(["WorkerNotFound", "VersionNotFound"], () => Effect.succeed(undefined)));
             }
+            if (output?.previewOf !== undefined || olds?.preview?.of != null) {
+                if (output?.previewOf === undefined || !output.previewId) {
+                    return undefined;
+                }
+                return yield* workers
+                    .getPreview({
+                    accountId,
+                    workerId: output.previewOf,
+                    previewId: output.previewId,
+                })
+                    .pipe(Effect.map(() => output), Effect.catchTag(["WorkerNotFound", "PreviewNotFound"], () => Effect.succeed(undefined)));
+            }
             const workerName = output?.workerName ?? (yield* createWorkerName(id, olds?.name));
             const dispatchNamespace = output?.namespace ?? resolveNamespaceName(olds?.namespace);
             yield* Effect.logInfo(`Cloudflare Worker read: checking ${workerName}`);
@@ -3774,12 +4159,20 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
         Effect.catchTag("WorkerNotFound", () => Effect.succeed(undefined)), Effect.catchTag("WorkerHasNoVersions", () => Effect.succeed(undefined)), Effect.catchTag("DispatchNamespaceScriptNotFound", () => Effect.succeed(undefined)), Effect.catchTag("DispatchNamespaceNotFound", () => Effect.succeed(undefined)))),
         reconcile: Effect.fn(function* ({ id, fqn, news, olds, bindings, output, session, }) {
             yield* assertCloudflareTelemetryCompatibility(news, bindings);
+            if (news.preview?.of != null && news.version?.parent != null) {
+                return yield* Effect.fail(new WorkerPreviewConfigError({
+                    message: `preview and version cannot be set together. Use preview.of for branch/PR Previews; use version.parent / version.traffic for canaries and gradual rollouts.`,
+                }));
+            }
             // A version worker uploads an immutable version to its parent's
             // script instead of owning a script of its own — none of the
             // script-level observation below applies.
             if (news.version?.parent != null) {
                 return yield* putWorkerVersion(id, fqn, news, bindings, session, output);
             }
+            if (news.preview?.of != null) {
+                return yield* putWorkerPreview(id, fqn, news, bindings, session, output);
+            }
             const { accountId } = yield* yield* CloudflareEnvironment;
             const name = output?.workerName ?? (yield* createWorkerName(id, news.name));
             const durableObjects = getDurableObjectBindings(bindings, name).map(({ logicalId, className }) => ({
@@ -3861,6 +4254,20 @@ export const LiveWorkerProvider = () => Provider.effect(Worker, Effect.gen(funct
                     .pipe(Effect.catchTag("WorkerNotFound", () => Effect.void));
                 return;
             }
+            if (output.previewOf !== undefined) {
+                const previewId = output.previewId ?? output.previewName;
+                if (!previewId)
+                    return;
+                yield* Effect.logInfo(`Cloudflare Worker delete: deleting Preview ${previewId} of ${output.previewOf}`);
+                yield* workers
+                    .deletePreview({
+                    accountId: output.accountId,
+                    workerId: output.previewOf,
+                    previewId,
+                })
+                    .pipe(Effect.catchTag(["PreviewNotFound", "WorkerNotFound"], () => Effect.void));
+                return;
+            }
             yield* Effect.logInfo(`Cloudflare Worker delete: deleting ${output.workerName}`);
             // Workers for Platforms user workers have no custom domains; delete
             // the script straight out of its dispatch namespace.