alchemy 2.0.0-beta.64 → 2.0.0-beta.66

package/src/Cloudflare/Workers/WorkerAsyncBindings.ts

@@ -1,5 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
+import type { Json } from "effect/Schema";
 import type { InputProps } from "../../Input.ts";
 import * as Output from "../../Output.ts";
 import type { ResourceBinding } from "../../Resource.ts";
@@ -9,6 +10,8 @@ import { isSearchInstance } from "../AI/SearchInstance.ts";
 import { isSearchNamespace } from "../AI/SearchNamespace.ts";
 import { isDataset } from "../AnalyticsEngine/Dataset.ts";
 import { isNamespace } from "../Artifacts/Namespace.ts";
+import type { Container } from "../Containers/Container.ts";
+import type { ContainerApplication } from "../Containers/ContainerApplication.ts";
 import { isDatabase } from "../D1/Database.ts";
 import { isSendEmail } from "../Email/SendEmail.ts";
 import { isApp } from "../Flagship/App.ts";
@@ -17,6 +20,7 @@ import { isHyperdriveConnection } from "../Hyperdrive/Connection.ts";
 import { isImages } from "../Images/Images.ts";
 import { isNamespace as isKVNamespace } from "../KV/Namespace.ts";
 import { isQueue } from "../Queues/Queue.ts";
+import { maybeQueueShim } from "../Queues/QueueShim.ts";
 import { isBucket } from "../R2/Bucket.ts";
 import { isSecret } from "../SecretsStore/Secret.ts";
 import { isIndex } from "../Vectorize/VectorizeIndex.ts";
@@ -33,7 +37,12 @@ import {
 import { isRateLimit } from "./RateLimit.ts";
 import { isVersionMetadata } from "./VersionMetadata.ts";
 import type { WorkerBindingProps } from "./Worker.ts";
-import { isWorker, type Worker, type WorkerProps } from "./Worker.ts";
+import {
+  isSelfUrl,
+  isWorker,
+  type Worker,
+  type WorkerProps,
+} from "./Worker.ts";
 import type { WorkerBinding, WorkerBindingResource } from "./WorkerBinding.ts";
 import { isWorkerLoader } from "./WorkerLoader.ts";
 
@@ -47,6 +56,15 @@ export const bindWorkerAsyncBindings = Effect.fn(function* (
       const bindingEff = props.env?.[bindingName] as
         | WorkerBindingResource
         | Effect.Effect<WorkerBindingResource>;
+      // A Container bound directly in `env` declares a container-backed
+      // Durable Object class: the Container IS the DO namespace binding plus
+      // its ContainerApplication. Handled before the generic Effect
+      // resolution below — yielding the Container class would resolve its
+      // *started instance* tag, which only exists inside a Durable Object.
+      if (isContainerDecl(bindingEff)) {
+        yield* bindContainerClass(resource, bindingName, bindingEff);
+        continue;
+      }
       // Bindings can be passed as a plain resource value, an Effect that
       // yields a resource, or an effect-class (e.g. a `Cloudflare.Worker`
       // class). Resolve the yieldable forms before deriving binding metadata.
@@ -58,10 +76,51 @@ export const bindWorkerAsyncBindings = Effect.fn(function* (
           : bindingEff
       ) as WorkerBindingResource;
 
-      let bindingMeta: InputProps<WorkerBinding> | undefined = toBinding(
-        bindingName,
-        binding,
-      );
+      // Queue producer bindings may need the dev-mode remote-producer shim
+      // (a LOCAL worker binding a LIVE queue): `maybeQueueShim` registers
+      // the shim worker + token resources at eval time — the same idiom as
+      // the WorkflowResource registration below — and contributes their
+      // outputs to the binding data.
+      if (isQueue(binding)) {
+        const shim = yield* maybeQueueShim(binding, resource);
+        yield* resource.bind`${bindingName}`({
+          bindings: [
+            {
+              type: "queue",
+              name: bindingName,
+              queueName: binding.queueName,
+              // Alchemy-only mode discriminator for dev (stripped before
+              // upload).
+              queueId: binding.queueId,
+              ...(shim ? { shim } : {}),
+            },
+          ],
+        });
+        continue;
+      }
+
+      const bindingMeta:
+        | BindingSpec
+        | Output.Output<WorkerBinding>
+        | undefined = toBinding(bindingName, binding);
+
+      if (Output.isOutput(bindingMeta)) {
+        // A whole-resource Output resolves to the resource's raw attributes;
+        // uploading those as a plaintext json env var is never intended.
+        // This cannot be rejected at compile time (`Input<T>` admits any
+        // Output whose A is structurally Json), so this guard is the
+        // enforcement point.
+        if (Output.isResourceExpr(binding) || Output.isRefExpr(binding)) {
+          return yield* Effect.die(
+            `Cannot bind whole-resource Output "${bindingName}": pass the resource (or a typed ref) directly, or bind one of its attribute Outputs`,
+          );
+        }
+        // Deferred classification (see `toBinding`'s Output arm): the engine
+        // resolves the Output inside the binding data before the Worker
+        // provider reads it.
+        yield* resource.bind`${bindingName}`({ bindings: [bindingMeta] });
+        continue;
+      }
 
       if (bindingMeta) {
         let resolvedBindingMeta: InputProps<WorkerBinding> = bindingMeta;
@@ -95,39 +154,151 @@ export const bindWorkerAsyncBindings = Effect.fn(function* (
             : undefined,
         });
       } else {
+        // Defensive catch-all: `toBinding` currently always classifies
+        // (its final arm is the `json` fallback), but keep the branch so a
+        // future gap fails loudly instead of silently skipping the binding.
         return yield* Effect.die(`Unknown binding type: ${bindingName}`);
       }
     }
   }
 });
 
+/**
+ * Structural check for a `Cloudflare.Container` class declaration. Keyed on
+ * the `~alchemy/Container/ClassName` marker (rather than importing from
+ * `Containers/Container.ts`) to avoid a value-level import cycle through
+ * `ContainerPlatform` → `Worker.ts` → this module.
+ *
+ * A Container declaration is Effect-shaped (yielding it resolves the
+ * *started instance* tag, which only exists inside a Durable Object), so
+ * every env-resolution site must check this before `Effect.isEffect`.
+ */
+export const isContainerDecl = (value: unknown): value is Container.Decl.Any =>
+  (typeof value === "function" || typeof value === "object") &&
+  value !== null &&
+  "~alchemy/Container/ClassName" in value;
+
+/**
+ * Structural check for a yielded {@link ContainerApplication} resource
+ * instance (same import-cycle note as above).
+ */
+const isContainerApplicationResource = (
+  value: unknown,
+): value is ContainerApplication =>
+  typeof value === "object" &&
+  value !== null &&
+  (value as { Type?: unknown }).Type === "Cloudflare.Container";
+
+/**
+ * Wire a Container bound directly on an async Worker's `env`
+ * (`env: { Sandbox: Cloudflare.Container("Sandbox", { image }) }`). Mirrors
+ * v1 alchemy, where a Container binding is a Durable Object namespace plus
+ * its ContainerApplication in one declaration:
+ *
+ * 1. emit the `durable_object_namespace` binding for the class,
+ * 2. attach the class's namespace id to the ContainerApplication, and
+ * 3. contribute `containers: [{ className }]` binding data so the Worker's
+ *    script metadata marks the class as container-backed.
+ *
+ * The namespace id only exists once the Worker uploads, while the Worker's
+ * metadata needs the container class — the same circularity as the
+ * Effect-native path (`ContainerPlatform.bind`), resolved through bindings +
+ * precreate.
+ */
+const bindContainerClass = Effect.fn(function* (
+  resource: Worker,
+  bindingName: string,
+  decl: Container.Decl.Any,
+) {
+  const className = decl["~alchemy/Container/ClassName"] ?? bindingName;
+  // Resolve the ContainerApplication resource declaration carried on the
+  // class. An effectful (`main`) container has no application declaration of
+  // its own here (it is created by its `.make()` Layer inside a Durable
+  // Object host), so it cannot back an async class.
+  const declaration = (decl as { Application?: unknown }).Application;
+  const application =
+    isYieldableEffectLike(declaration) && !Output.isOutput(declaration)
+      ? yield* declaration as Effect.Effect<unknown>
+      : undefined;
+  if (!isContainerApplicationResource(application)) {
+    return yield* Effect.die(
+      `Worker binding '${bindingName}' is a Container without a deployable image. Declare the container with props (image, or context/dockerfile) to bind it on an async Worker — effectful (main) containers require an Effect-native Durable Object host.`,
+    );
+  }
+  yield* resource.bind`${bindingName}`({
+    bindings: [
+      {
+        type: "durable_object_namespace",
+        name: bindingName,
+        className,
+      },
+    ],
+  });
+  yield* application.bind`${bindingName}`({
+    durableObjects: {
+      namespaceId: resource.durableObjectNamespaces.pipe(
+        Output.map((namespaces) => namespaces?.[className]),
+      ),
+    },
+  });
+  yield* resource.bind`${application.LogicalId}`({
+    containers: [{ className, dev: application.dev }],
+  });
+});
+
 type BindingSpec = InputProps<WorkerBinding>;
 
-const toBinding = (
+/**
+ * Classify a plain env value (string / Redacted / Json) into its wire
+ * binding. Called by {@link toBinding} both eagerly (literal values) and
+ * deferred (the resolved value of an Output env entry).
+ */
+const toValueBinding = (
   bindingName: string,
-  binding: WorkerBindingResource,
-): BindingSpec => {
-  if (typeof binding === "string") {
+  value: Json | Redacted.Redacted<Json>,
+): WorkerBinding => {
+  if (typeof value === "string") {
     return {
       type: "plain_text",
       name: bindingName,
-      text: binding,
+      text: value,
     };
-  } else if (Redacted.isRedacted(binding)) {
-    const val = Redacted.value(binding);
-    if (typeof val === "string") {
-      return {
-        type: "secret_text",
-        name: bindingName,
-        text: val,
-      };
-    } else {
-      return {
-        type: "secret_text",
-        name: bindingName,
-        text: JSON.stringify(val),
-      };
-    }
+  }
+  if (Redacted.isRedacted(value)) {
+    const val = Redacted.value(value);
+    return {
+      type: "secret_text",
+      name: bindingName,
+      text: typeof val === "string" ? val : JSON.stringify(val),
+    };
+  }
+  return {
+    type: "json",
+    name: bindingName,
+    json: value,
+  };
+};
+
+/**
+ * Classify a binding into its wire shape.
+ *
+ * An Output that no native classifier recognized resolves to a plain env
+ * value, unknown until the engine resolves it, so its classification
+ * (plain_text vs secret_text vs json) is deferred to resolution time via
+ * {@link toValueBinding} — classifying eagerly would fall through to the
+ * `json` fallback and deploy e.g. a resolved `Redacted` secret as an
+ * unencrypted json binding. Resource refs never land in the Output arm:
+ * they surface their target's `Type` statically, so a native classifier
+ * (kv_namespace, r2_bucket, ...) already matched above. Whole-resource
+ * Outputs also land here (lazily, nothing is resolved); the caller rejects
+ * them before the returned Output is ever bound.
+ */
+const toBinding = (
+  bindingName: string,
+  binding: WorkerBindingResource,
+): BindingSpec | Output.Output<WorkerBinding, unknown> => {
+  if (typeof binding === "string" || Redacted.isRedacted(binding)) {
+    return toValueBinding(bindingName, binding);
   } else if (isAssets(binding)) {
     return {
       type: "assets",
@@ -220,6 +391,8 @@ const toBinding = (
       type: "queue",
       name: bindingName,
       queueName: binding.queueName,
+      // Alchemy-only mode discriminator for dev (stripped before upload).
+      queueId: binding.queueId,
     };
   } else if (isDispatchNamespace(binding)) {
     return {
@@ -285,11 +458,22 @@ const toBinding = (
       type: "version_metadata",
       name: bindingName,
     };
+  } else if (isSelfUrl(binding)) {
+    // The Worker's own URL. The provider lowers this sentinel into a
+    // `plain_text` binding holding the resolved URL just before upload.
+    return {
+      type: "self_url",
+      name: bindingName,
+    };
   } else if (isWorkerLoader(binding)) {
     return {
       type: "worker_loader",
       name: bindingName,
     };
+  } else if (Output.isOutput(binding)) {
+    return Output.map(binding, (value: Json | Redacted.Redacted<Json>) =>
+      toValueBinding(bindingName, value),
+    );
   } else {
     return {
       type: "json",

package/src/Cloudflare/Workers/WorkerBinding.ts

@@ -3,6 +3,7 @@ import * as Config from "effect/Config";
 import * as Effect from "effect/Effect";
 import * as Redacted from "effect/Redacted";
 import type { Json } from "effect/Schema";
+import type * as Output from "../../Output.ts";
 import type { Rpc } from "../../Rpc.ts";
 import { isYieldableEffectLike } from "../../Util/effect.ts";
 import type { Gateway as AiGateway } from "../AI/Gateway.ts";
@@ -10,6 +11,7 @@ import type { SearchInstance } from "../AI/SearchInstance.ts";
 import type { SearchNamespace } from "../AI/SearchNamespace.ts";
 import { Dataset } from "../AnalyticsEngine/Dataset.ts";
 import type { Namespace as ArtifactsNamespace } from "../Artifacts/Namespace.ts";
+import type { Container } from "../Containers/Container.ts";
 import type { Database as D1Database } from "../D1/Database.ts";
 import { SendEmail } from "../Email/SendEmail.ts";
 import type { App as FlagshipApp } from "../Flagship/App.ts";
@@ -24,6 +26,7 @@ import type { DispatchNamespace } from "../WorkersForPlatforms/DispatchNamespace
 import type { WorkflowLike } from "../Workflows/Workflow.ts";
 import type { AIBinding } from "./AIBinding.ts";
 import type { Assets } from "./Assets.ts";
+import type { URLEffect } from "./Worker.ts";
 import type { BrowserBinding } from "./BrowserBinding.ts";
 import type { DurableObjectLike } from "./DurableObject.ts";
 import type { RateLimitBinding } from "./RateLimitBinding.ts";
@@ -52,9 +55,57 @@ export type DurableObjectNamespaceWorkerBinding = Extract<
   transferredFrom?: string | string[];
 };
 
+/**
+ * Alchemy-only binding: the host Worker's own public URL (`Worker.URL`). The
+ * provider resolves the URL the Worker will be served at (first custom domain,
+ * else its `workers.dev` URL) and lowers this into a `plain_text` binding
+ * before the script upload — Cloudflare never sees this type.
+ */
+export interface SelfUrlWorkerBinding {
+  type: "self_url";
+  name: string;
+}
+
+/**
+ * The `queue` metadata binding extended with the alchemy-only `queueId`.
+ * The local worker provider uses it to discriminate a locally-emulated
+ * queue (`dev:` id → local broker) from an `Alchemy.remote()` queue in dev
+ * (real id → remote-proxied producer). Stripped from the binding before
+ * the script upload — Cloudflare never sees it.
+ */
+export type QueueWorkerBinding = Extract<
+  DistilledWorkerBinding,
+  { type: "queue" }
+> & {
+  queueId?: string;
+  /**
+   * Alchemy-only (stripped before upload): dev-mode remote-producer shim
+   * for an `Alchemy.remote()` queue. Cloudflare preview sessions reject
+   * queue bindings, so a local worker produces to the live queue through
+   * this deployed shim worker instead (see `Queues/QueueShim.ts`).
+   */
+  shim?: {
+    /** The shim worker's workers.dev URL. */
+    url: string | undefined;
+    /** Bearer token the shim requires. */
+    token: Redacted.Redacted<string> | string;
+  };
+};
+
+/**
+ * The wire-shape binding union the Cloudflare API accepts — {@link WorkerBinding}
+ * minus the alchemy-only members that must be lowered before upload.
+ */
+export type WireWorkerBinding = Exclude<WorkerBinding, SelfUrlWorkerBinding>;
+
 export type WorkerBinding =
-  | Exclude<DistilledWorkerBinding, { type: "durable_object_namespace" }>
-  | DurableObjectNamespaceWorkerBinding;
+  | Exclude<
+      DistilledWorkerBinding,
+      { type: "durable_object_namespace" } | { type: "queue" }
+    >
+  | DurableObjectNamespaceWorkerBinding
+  | QueueWorkerBinding
+  | SelfUrlWorkerBinding;
 
 export type WorkerSettingsBinding = Exclude<
   workers.GetScriptScriptAndVersionSettingResponse["bindings"],
@@ -66,6 +117,14 @@ export type WorkerBindingResource =
   | Json
   | Redacted.Redacted<Json>
   | Config.Config<Json>
+  // Outputs that resolve to a plain env value (e.g. `Alchemy.makeRandom`,
+  // `Output.literal`), classified by their resolved value at deploy time.
+  // Whole-resource Outputs (`Output.of(bucket)`) cannot be excluded here:
+  // `Input<T>` wraps this whole union in `Output<T>`, so any Output whose
+  // A is structurally Json (most resource attribute shapes) is admitted
+  // upstream regardless of this arm. `bindWorkerAsyncBindings` rejects
+  // them at deploy time instead.
+  | Output.Output<Json | Redacted.Redacted<Json>, unknown>
   // CF resources
   | Assets
   | Bucket
@@ -89,9 +148,14 @@ export type WorkerBindingResource =
   | Worker
   | WorkerLoader
   | VersionMetadataBinding
+  // The Worker's own URL (`Worker.URL`).
+  | URLEffect
   | DispatchNamespace
   | DurableObjectLike<any>
-  | WorkflowLike<any>;
+  | WorkflowLike<any>
+  // A Container bound directly in `env` declares a container-backed Durable
+  // Object class (DO namespace binding + ContainerApplication in one).
+  | Container.Decl.Any;
 
 export type WorkerBindings = {
   [bindingName in string]: WorkerBindingResource;

package/src/Cloudflare/Workers/WorkerBridge.ts

@@ -19,6 +19,7 @@ import {
 } from "../../Runtime.ts";
 import { Self } from "../../Self.ts";
 import { Stack } from "../../Stack.ts";
+import { buildEventTelemetry } from "../../Telemetry.ts";
 import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
 import cloudflare_workers from "./cloudflare_workers.ts";
 import { isScopeEjected } from "./HttpServer.ts";
@@ -41,13 +42,16 @@ import type { WorkerRuntimeContext } from "./WorkerRuntimeContext.ts";
 
 /**
  * The isolate-lifetime artifacts produced by a single layer build: the built
- * service Context, the resolved export for this entrypoint, and the user's
- * RPC shape (a thunk — the shape is only populated once `serve` has run).
+ * service Context, the resolved export for this entrypoint, the user's
+ * RPC shape (a thunk — the shape is only populated once `serve` has run),
+ * and the telemetry Layer override registered during init (a thunk for the
+ * same reason).
  */
 export interface WorkerBuild<Export = any> {
   readonly context: Context.Context<any>;
   readonly export: Export;
   readonly shape: () => Record<string, any>;
+  readonly telemetry: () => Layer.Layer<never, any, any> | undefined;
 }
 
 /**
@@ -102,6 +106,16 @@ export const makeWorkerBridge = (
                   fromExecutionContext(ctx),
                 ),
                 Layer.succeed(Scope.Scope, scope),
+                // The configured telemetry exporters. Constructed as part
+                // of this per-event layer, but `buildEventTelemetry`
+                // attaches their batching fibers and flush finalizers to
+                // the request `scope` (not this build's transient scope),
+                // so buffered telemetry flushes when the scope closes into
+                // `ctx.waitUntil` below — never on workerd's ephemeral
+                // isolate scope.
+                Layer.effectContext(
+                  buildEventTelemetry(built.context, scope, built.telemetry()),
+                ),
               ).pipe(
                 Layer.provideMerge(Layer.succeedContext(services)),
                 Layer.provideMerge(Layer.succeedContext(built.context)),
@@ -118,8 +132,15 @@ export const makeWorkerBridge = (
       .finally(() =>
         isScopeEjected(scope)
           ? undefined
-          : Scope.close(scope, Exit.void).pipe(Effect.runPromise, (promise) =>
-              ctx.waitUntil(promise),
+          : ctx.waitUntil(
+              // The HttpMiddleware tracer ends the request's root span in a
+              // dispatcher task scheduled after the handler effect resolves.
+              // Yield one macrotask before closing the scope so that span
+              // reaches the telemetry exporter's buffer before the scope's
+              // flush finalizer runs.
+              new Promise((resolve) => setTimeout(resolve, 0)).then(() =>
+                Effect.runPromise(Scope.close(scope, Exit.void)),
+              ),
             ),
       );
   };
@@ -398,6 +419,7 @@ export const getWorkerExport = <Export = any>({
                 context,
                 export: exp,
                 shape: rc.shape,
+                telemetry: () => rc.telemetry,
               }),
             ),
             Effect.provideContext(context),

package/src/Cloudflare/Workers/WorkerBundle.ts

@@ -1,4 +1,3 @@
-import cloudflareRolldown from "@distilled.cloud/cloudflare-rolldown-plugin";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import { flow } from "effect/Function";
@@ -20,6 +19,25 @@ import {
   type DurableObjectExport,
 } from "./DurableObject.ts";
 
+/**
+ * Bundler options for a Worker: the generic {@link Bundle.BundleExtraOptions}
+ * plus rolldown output overrides merged over Alchemy's defaults.
+ */
+export interface WorkerBuildOptions extends Bundle.BundleExtraOptions {
+  /**
+   * Rolldown output options merged over Alchemy's defaults. Use this to
+   * control chunking (`codeSplitting`), minification, etc.
+   */
+  output?: rolldown.OutputOptions;
+  /**
+   * Forwarded to rolldown's `preserveEntrySignatures` input option. Some
+   * `output.codeSplitting` configurations require relaxing it (e.g.
+   * `includeDependenciesRecursively: false` needs `"allow-extension"`).
+   * Workers must keep their entry exports, so never pass `false`.
+   */
+  preserveEntrySignatures?: rolldown.InputOptions["preserveEntrySignatures"];
+}
+
 export interface WorkerBundleOptions {
   id: string;
   main: string;
@@ -36,7 +54,7 @@ export interface WorkerBundleOptions {
         exports: Record<string, DurableObjectExport | WorkflowExport>;
       };
   stack: { name: string; stage: string };
-  extraOptions: Bundle.BundleExtraOptions | undefined;
+  extraOptions: WorkerBuildOptions | undefined;
 }
 
 export const WorkerBundle = Effect.gen(function* () {
@@ -45,9 +63,16 @@ export const WorkerBundle = Effect.gen(function* () {
   const virtualEntryPlugin = yield* Bundle.virtualEntryPlugin;
 
   const makeOptions = Effect.fn(function* (options: WorkerBundleOptions) {
+    // Loaded lazily so importing the Cloudflare provider (or the CLI, whose
+    // command tree reaches this module) never loads rolldown's native
+    // binding — only actually bundling a Worker does (#562).
+    const { default: cloudflareRolldown } = yield* Effect.promise(
+      () => import("@distilled.cloud/cloudflare-rolldown-plugin"),
+    );
     const realMain = yield* sanitizeMain(options.main);
     const inputOptions: rolldown.InputOptions = {
       input: realMain,
+      preserveEntrySignatures: options.extraOptions?.preserveEntrySignatures,
       // Forever-devtool native modules that vite/chokidar reference behind
       // runtime guards. Rolldown resolves before tree-shaking, so the dead
       // `require('../pkg')` (lightningcss < 1.32) and `require('fsevents')`
@@ -89,7 +114,17 @@ export const WorkerBundle = Effect.gen(function* () {
       sourcemap: "hidden",
       minify: true,
       keepNames: true,
+      // Rolldown's default chunking can split top-level initializer modules
+      // (e.g. Drizzle `pgTable` schemas) away from the classes they read,
+      // and workerd then evaluates a reader before its imported binding is
+      // initialized — the script fails Cloudflare startup validation with
+      // `ScriptStartupError: Cannot access '<minified>' before
+      // initialization` (#749). `strictExecutionOrder` wraps cross-chunk
+      // modules so evaluation follows ESM semantics regardless of how the
+      // graph was chunked. See DrizzleSchemaChunks.test.ts.
+      strictExecutionOrder: true,
       dir: `.alchemy/bundles/${options.id}`,
+      ...options.extraOptions?.output,
     };
     return { inputOptions, outputOptions, extraOptions: options.extraOptions };
   });