alchemy 0.66.0 → 0.67.0

package/src/cloudflare/miniflare/build-worker-options.ts

@@ -2,12 +2,11 @@ import * as miniflare from "miniflare";
 import { assertNever } from "../../util/assert-never.ts";
 import type { HTTPServer } from "../../util/http.ts";
 import type { CloudflareApi } from "../api.ts";
-import {
-  Self,
-  type Binding,
-  type Bindings,
-  type WorkerBindingService,
-  type WorkerBindingSpec,
+import type {
+  Binding,
+  Bindings,
+  WorkerBindingService,
+  WorkerBindingSpec,
 } from "../bindings.ts";
 import { isQueueEventSource, type EventSource } from "../event-source.ts";
 import type { WorkerBundle, WorkerBundleSource } from "../worker-bundle.ts";
@@ -25,11 +24,11 @@ export interface MiniflareWorkerInput {
   assets: AssetsConfig | undefined;
   bundle: WorkerBundleSource;
   port: number | undefined;
+  tunnel: boolean | undefined;
 }
 
 type RemoteOnlyBindingType =
   | "ai"
-  | "ai_gateway"
   | "browser"
   | "dispatch_namespace"
   | "mtls_certificate"
@@ -92,13 +91,18 @@ export const buildWorkerOptions = async (
       (options.bindings ??= {})[key] = binding;
       continue;
     }
-    if (binding === Self) {
+    if (binding.type === "cloudflare::Worker::Self") {
       (options.serviceBindings ??= {})[key] = miniflare.kCurrentWorker;
       continue;
     }
     switch (binding.type) {
-      case "ai":
-      case "ai_gateway": {
+      case "ai": {
+        const existing = remoteBindings.find((b) => b.type === "ai");
+        if (existing) {
+          throw new Error(
+            `Workers cannot have multiple AI bindings. Binding "${key}" conflicts with "${existing.name}".`,
+          );
+        }
         remoteBindings.push({
           type: "ai",
           name: key,
@@ -180,7 +184,9 @@ export const buildWorkerOptions = async (
         break;
       }
       case "hyperdrive": {
-        (options.hyperdrives ??= {})[key] = binding.dev.origin.unencrypted;
+        if (binding.dev) {
+          (options.hyperdrives ??= {})[key] = binding.dev.origin.unencrypted;
+        }
         break;
       }
       case "images": {
@@ -459,7 +465,10 @@ const normalizeBundle = (bundle: WorkerBundle) => {
 };
 
 const isRemoteBinding = (binding: Binding) => {
-  if (typeof binding === "string" || binding === Self) {
+  if (
+    typeof binding === "string" ||
+    binding.type === "cloudflare::Worker::Self"
+  ) {
     return false;
   }
   return (

package/src/cloudflare/miniflare/miniflare-controller.ts

@@ -10,8 +10,12 @@ import {
   buildWorkerOptions,
   type MiniflareWorkerInput,
 } from "./build-worker-options.ts";
-import { MiniflareWorkerProxy } from "./miniflare-worker-proxy.ts";
+import {
+  createMiniflareWorkerProxy,
+  type MiniflareWorkerProxy,
+} from "./miniflare-worker-proxy.ts";
 import { getDefaultPersistPath } from "./paths.ts";
+import { createTunnel, type Tunnel } from "./tunnel.ts";
 
 declare global {
   var ALCHEMY_MINIFLARE_CONTROLLER: MiniflareController | undefined;
@@ -21,6 +25,7 @@ export class MiniflareController {
   abort = new AbortController();
   miniflare: miniflare.Miniflare | undefined;
   options = new Map<string, miniflare.WorkerOptions>();
+  tunnel: Tunnel | undefined;
   localProxies = new Map<string, MiniflareWorkerProxy>();
   remoteProxies = new Map<string, HTTPServer>();
   mutex = new AsyncMutex();
@@ -40,21 +45,32 @@ export class MiniflareController {
     assert(first.value, "First value is undefined");
     this.options.set(input.name, first.value);
     const miniflare = await this.update();
-    const proxy = new MiniflareWorkerProxy({
-      name: input.name,
-      port: input.port ?? (await findOpenPort()),
-      miniflare,
-    });
-    this.localProxies.set(input.name, proxy);
+    let url: URL;
+    if (input.tunnel) {
+      this.tunnel ??= await createTunnel(miniflare);
+      url = await this.tunnel.configureWorker({
+        api: input.api,
+        name: input.name,
+      });
+    } else {
+      const proxy = await createMiniflareWorkerProxy({
+        port: input.port ?? (await findOpenPort()),
+        getWorkerName: () => input.name,
+        miniflare,
+        mode: "local",
+      });
+      this.localProxies.set(input.name, proxy);
+      url = proxy.url;
+    }
     void this.watch(input.id, watcher);
     logger.task(input.id, {
-      message: `Ready at ${proxy.url}`,
+      message: `Ready at ${url}`,
       status: "success",
       resource: input.id,
       prefix: "dev",
       prefixColor: "cyanBright",
     });
-    return proxy.url;
+    return url.toString();
   }
 
   private async watch(
@@ -76,9 +92,7 @@ export class MiniflareController {
 
   private async update() {
     return await this.mutex.lock(async () => {
-      const options: miniflare.MiniflareOptions & {
-        workers: miniflare.WorkerOptions[];
-      } = {
+      const options: miniflare.MiniflareOptions = {
         workers: [],
         defaultPersistRoot: path.resolve(
           getDefaultPersistPath(Scope.current.rootDir),
@@ -147,6 +161,7 @@ export class MiniflareController {
     this.abort.abort();
     await Promise.all([
       this.miniflare?.dispose(),
+      this.tunnel?.close(),
       ...this.localProxies.values().map((proxy) => proxy.close()),
       ...this.remoteProxies.values().map((proxy) => proxy.close()),
     ]);

package/src/cloudflare/miniflare/miniflare-worker-proxy.ts

@@ -1,126 +1,108 @@
 import * as miniflare from "miniflare";
 import { once } from "node:events";
 import http from "node:http";
-import type Stream from "node:stream";
 import { Readable } from "node:stream";
 import { WebSocket, WebSocketServer } from "ws";
-import { logger } from "../../util/logger.ts";
 
-interface MiniflareWorkerProxyOptions {
-  name: string;
-  port: number;
-  miniflare: miniflare.Miniflare;
+export interface MiniflareWorkerProxy {
+  url: URL;
+  close: () => Promise<void>;
 }
 
-export class MiniflareWorkerProxy {
-  private server = http.createServer();
-  private wss = new WebSocketServer({ noServer: true });
-
-  constructor(private readonly options: MiniflareWorkerProxyOptions) {
-    this.server.on("upgrade", async (req, socket, head) => {
-      await this.handleUpgrade(req, socket, head);
-    });
-    this.server.on("request", async (req, res) => {
-      await this.handleRequest(req, res);
-    });
-    this.server.listen(this.options.port);
-  }
-
-  get ready() {
-    if (!this.server.listening) {
-      return once(this.server, "listening");
-    }
-    return Promise.resolve();
-  }
-
-  get url() {
-    return `http://localhost:${this.options.port}`;
-  }
-
-  async close() {
-    await Promise.all([
-      new Promise((resolve) => this.wss.close(resolve)),
-      new Promise((resolve) => this.server.close(resolve)),
-    ]);
-  }
+export async function createMiniflareWorkerProxy(options: {
+  port: number;
+  transformRequest?: (request: RequestInfo) => void;
+  getWorkerName: (request: miniflare.Request) => string;
+  miniflare: miniflare.Miniflare;
+  mode: "local" | "remote";
+}) {
+  const server = http.createServer();
+  const wss = new WebSocketServer({ noServer: true });
 
-  private async handleUpgrade(
-    req: http.IncomingMessage,
-    socket: Stream.Duplex,
-    head: Buffer,
-  ) {
-    const server = await this.createServerWebSocket(req);
-    if (!server) {
+  server.on("upgrade", async (req, socket, head) => {
+    try {
+      const server = await createServerWebSocket(req);
+      wss.handleUpgrade(req, socket, head, (client) => {
+        client.on("message", (event, binary) => server.send(event, { binary }));
+        client.on("close", (code, reason) => server.close(code, reason));
+        server.on("message", (event, binary) => client.send(event, { binary }));
+        server.on("close", (code, reason) => client.close(code, reason));
+        wss.emit("connection", client, req);
+      });
+    } catch (error) {
+      console.error(error);
       socket.destroy();
-      return;
     }
-    this.wss.handleUpgrade(req, socket, head, (client) => {
-      client.on("message", (event, binary) => server.send(event, { binary }));
-      client.on("close", (code, reason) => server.close(code, reason));
-      server.on("message", (event, binary) => client.send(event, { binary }));
-      server.on("close", (code, reason) => client.close(code, reason));
-      this.wss.emit("connection", client, req);
-    });
-  }
-
-  private async createServerWebSocket(req: http.IncomingMessage) {
-    const target = await this.options.miniflare.unsafeGetDirectURL(
-      this.options.name,
-    );
-    if (!target) {
-      logger.error(
-        `[Alchemy] Websocket connection failed: The worker "${this.options.name}" is not running.`,
+  });
+  server.on("request", async (req, res) => {
+    try {
+      const request = toMiniflareRequest(req);
+      const name = options.getWorkerName(request);
+      const worker = await options.miniflare.getWorker(name);
+      const response = await worker.fetch(request);
+      writeMiniflareResponseToNode(response, res);
+    } catch (error) {
+      console.error(error);
+      const response = MiniflareWorkerProxyError.fromUnknown(error).toResponse(
+        options.mode,
       );
-      return null;
+      writeMiniflareResponseToNode(response, res);
     }
+  });
+
+  const toMiniflareRequest = (req: http.IncomingMessage): miniflare.Request => {
+    const info = parseIncomingMessage(req);
+    options.transformRequest?.(info);
+    return new miniflare.Request(info.url, {
+      method: info.method,
+      headers: info.headers,
+      body: info.body,
+      redirect: info.redirect,
+      duplex: info.duplex,
+    });
+  };
+
+  const createServerWebSocket = async (req: http.IncomingMessage) => {
+    const name = options.getWorkerName(toMiniflareRequest(req));
+    const target = await options.miniflare.unsafeGetDirectURL(name);
     const url = new URL(req.url ?? "/", target);
     url.protocol = url.protocol.replace("http", "ws");
     const protocols = req.headers["sec-websocket-protocol"]
       ?.split(",")
       .map((p) => p.trim());
     const server = new WebSocket(url, protocols);
-    const controller = new AbortController();
-    return await Promise.race([
-      once(server, "open", { signal: controller.signal }).then(() => server),
-      once(server, "close", { signal: controller.signal }).then((args) => {
-        const [code, reason] = args as [number, string];
-        logger.error(
-          `[Alchemy] Websocket connection failed for worker "${this.options.name}": ${code} ${reason}`,
-        );
-        return null;
-      }),
-    ]).finally(() => controller.abort());
-  }
+    await once(server, "open");
+    return server;
+  };
 
-  private async handleRequest(
-    req: http.IncomingMessage,
-    res: http.ServerResponse,
-  ) {
-    const worker = await this.options.miniflare.getWorker(this.options.name);
-    if (!worker) {
-      res.statusCode = 503;
-      res.end(`[Alchemy] The worker "${this.options.name}" is not running.`);
-      return;
-    }
-    try {
-      const response = await worker.fetch(toMiniflareRequest(req));
-      writeMiniflareResponseToNode(response, res);
-    } catch (rawError) {
-      const message =
-        rawError instanceof Error
-          ? (rawError.stack ?? rawError.message)
-          : String(rawError);
-      res.statusCode = 500;
-      res.end(
-        `[Alchemy] The worker "${this.options.name}" threw an error:\n\n${message}`,
-      );
-    }
-  }
+  server.listen(options.port);
+  await once(server, "listening");
+  const url = new URL(`http://localhost:${options.port}`);
+
+  return {
+    url,
+    close: async () => {
+      await Promise.all([
+        new Promise((resolve) => server.close(resolve)),
+        new Promise((resolve) => wss.close(resolve)),
+      ]);
+    },
+  };
+}
+
+interface RequestInfo {
+  method: string;
+  url: URL;
+  headers: miniflare.Headers;
+  body: miniflare.BodyInit | undefined;
+  redirect: "manual";
+  duplex: "half" | undefined;
 }
 
-const toMiniflareRequest = (req: http.IncomingMessage) => {
+const parseIncomingMessage = (req: http.IncomingMessage): RequestInfo => {
   const method = req.method ?? "GET";
-  const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+  const protocol = req.headers["x-forwarded-proto"] ?? "http";
+  const url = new URL(req.url ?? "/", `${protocol}://${req.headers.host}`);
   const headers = new miniflare.Headers();
   for (const [key, value] of Object.entries(req.headers)) {
     if (Array.isArray(value)) {
@@ -135,13 +117,14 @@ const toMiniflareRequest = (req: http.IncomingMessage) => {
     ["GET", "HEAD", "OPTIONS"].includes(method) || !req.readable
       ? undefined
       : Readable.toWeb(req);
-  return new miniflare.Request(url, {
+  return {
     method,
+    url,
     headers,
     body,
     redirect: "manual",
     duplex: body ? "half" : undefined,
-  });
+  };
 };
 
 const writeMiniflareResponseToNode = (
@@ -159,3 +142,40 @@ const writeMiniflareResponseToNode = (
     out.end();
   }
 };
+
+export class MiniflareWorkerProxyError extends Error {
+  constructor(
+    message: string,
+    readonly status: number,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+  }
+
+  toResponse(mode: "local" | "remote"): miniflare.Response {
+    let text = `[Alchemy] ${this.message}`;
+    if (mode === "local" && this.cause) {
+      const cause =
+        this.cause instanceof Error
+          ? (this.cause.stack ?? this.cause.message)
+          : String(this.cause);
+      text += `\n\n${cause}`;
+    }
+    return new miniflare.Response(text, {
+      status: this.status,
+      headers: {
+        "Content-Type": "text/plain",
+        "Alchemy-Error": this.message,
+      },
+    });
+  }
+
+  static fromUnknown(error: unknown): MiniflareWorkerProxyError {
+    if (error instanceof MiniflareWorkerProxyError) {
+      return error;
+    }
+    return new MiniflareWorkerProxyError("An unknown error occurred.", 500, {
+      cause: error,
+    });
+  }
+}

package/src/cloudflare/miniflare/tunnel.ts

@@ -0,0 +1,116 @@
+import type * as miniflare from "miniflare";
+import { Scope } from "../../scope.ts";
+import { findOpenPort } from "../../util/find-open-port.ts";
+import type { CloudflareApi } from "../api.ts";
+import { getInternalWorkerBundle } from "../bundle/internal-worker-bundle.ts";
+import {
+  enableWorkerSubdomain,
+  getAccountSubdomain,
+  getWorkerSubdomain,
+} from "../worker-subdomain.ts";
+import { putWorker } from "../worker.ts";
+import {
+  createMiniflareWorkerProxy,
+  MiniflareWorkerProxyError,
+} from "./miniflare-worker-proxy.ts";
+
+export interface Tunnel {
+  /**
+   * Enables tunneling for a local worker.
+   * Returns a `workers.dev` URL that can be used to access the worker.
+   */
+  configureWorker: (input: {
+    api: CloudflareApi;
+    name: string;
+  }) => Promise<URL>;
+  /**
+   * Closes the tunnel.
+   */
+  close: () => Promise<void>;
+}
+
+export async function createTunnel(
+  miniflare: miniflare.Miniflare,
+): Promise<Tunnel> {
+  const workers = new Set<string>(); // used to avoid exposing workers that are not running with tunneling enabled
+  const proxy = await createMiniflareWorkerProxy({
+    port: await findOpenPort(9977), // alchemy auth uses 9976, so one above that
+    miniflare,
+    mode: "remote",
+    transformRequest: (request) => {
+      if (request.url.origin === remote.origin) {
+        request.url.protocol = proxy.url.protocol;
+        request.url.host = proxy.url.host;
+        request.url.port = proxy.url.port;
+        request.headers.set("host", proxy.url.host);
+      }
+    },
+    getWorkerName: (request) => {
+      const name = request.headers.get("alchemy-worker-name");
+      if (!name) {
+        throw new MiniflareWorkerProxyError(
+          "Worker name is missing from request headers. This indicates a bug in Alchemy.",
+          530,
+        );
+      }
+      if (!workers.has(name)) {
+        throw new MiniflareWorkerProxyError(
+          `The worker "${name}" is not running with tunneling enabled.`,
+          530,
+        );
+      }
+      return name;
+    },
+  });
+  const remoteUrlString = await Scope.current.spawn("tunnel", {
+    processName: `cloudflared-${proxy.url.port}`,
+    cmd: `cloudflared tunnel --url ${proxy.url.toString()}`,
+    quiet: !process.env.DEBUG,
+    extract: (line) => {
+      const match = line.match(/https:\/\/([^\s]+)\.trycloudflare\.com/);
+      if (match) {
+        return `https://${match[1]}.trycloudflare.com`;
+      }
+    },
+  });
+  const remote = new URL(remoteUrlString);
+  return {
+    configureWorker: async (input) => {
+      workers.add(input.name);
+      return await createTunnelProxyWorker({
+        api: input.api,
+        name: input.name,
+        host: remote.host,
+      });
+    },
+    close: async () => {
+      await proxy.close();
+    },
+  };
+}
+
+async function createTunnelProxyWorker(input: {
+  api: CloudflareApi;
+  name: string;
+  host: string;
+}) {
+  const script = await getInternalWorkerBundle("tunnel-proxy");
+  const [accountSubdomain, workerSubdomainStatus] = await Promise.all([
+    getAccountSubdomain(input.api),
+    getWorkerSubdomain(input.api, input.name),
+    putWorker(input.api, {
+      workerName: input.name,
+      scriptBundle: script.bundle,
+      compatibilityDate: "2025-09-01",
+      compatibilityFlags: [],
+      bindings: {
+        WORKER_NAME: input.name,
+        TUNNEL_HOST: input.host,
+      },
+    }),
+  ]);
+  if (!workerSubdomainStatus.enabled) {
+    await enableWorkerSubdomain(input.api, input.name);
+  }
+  return new URL(`https://${input.name}.${accountSubdomain}.workers.dev`);
+}

package/src/cloudflare/next.ts

@@ -33,6 +33,9 @@ export async function Nextjs<const B extends Bindings>(
     );
   }
   return await Website(id, {
+    bundle: {
+      minify: true,
+    },
     ...props,
     entrypoint: props.entrypoint ?? ".open-next/worker.js",
     wrangler: {

package/src/cloudflare/secret-ref.ts

@@ -0,0 +1,56 @@
+import { createCloudflareApi, type CloudflareApiOptions } from "./api.ts";
+import { findSecretsStoreByName, SecretsStore } from "./secrets-store.ts";
+
+/**
+ * Properties for referencing an existing Secret in a Secrets Store (without managing its value)
+ */
+export interface SecretRefProps extends CloudflareApiOptions {
+  name: string;
+  store?: SecretsStore;
+}
+
+export type SecretRef = {
+  type: "secrets_store_secret";
+  name: string;
+  storeId: string;
+};
+
+/**
+ * SecretRef references an existing secret by name in a Secrets Store.
+ *
+ * It does not create or update the secret value – use {@link Secret} for that.
+ *
+ * Behavior:
+ * - Resolves the target secrets store ID (defaults to Cloudflare's `default_secrets_store`, creating/adopting if needed)
+ * - Exposes a binding of type `secrets_store_secret` usable in Worker bindings
+ * - Update with a different name will trigger resource replacement
+ * - Delete is a no-op in Cloudflare (resource removed from state only)
+ *
+ * @example
+ * // Reference an existing secret in the default store and bind to a Worker
+ * const apiKeyRef = await SecretRef("api-key-ref", { name: "API_KEY" });
+ * const worker = await Worker("my-worker", {
+ *   entrypoint: "./src/worker.ts",
+ *   url: true,
+ *   bindings: {
+ *     API_KEY: apiKeyRef,
+ *   },
+ * });
+ */
+export async function SecretRef(props: SecretRefProps): Promise<SecretRef> {
+  const api = await createCloudflareApi(props);
+
+  const storeId =
+    props.store?.id ??
+    (await findSecretsStoreByName(api, SecretsStore.Default))?.id;
+
+  if (!storeId) {
+    throw new Error(`Secrets store ${SecretsStore.Default} not found`);
+  }
+
+  return {
+    type: "secrets_store_secret",
+    name: props.name,
+    storeId,
+  };
+}

package/src/cloudflare/worker-metadata.ts

@@ -3,11 +3,10 @@ import { logger } from "../util/logger.ts";
 import { memoize } from "../util/memoize.ts";
 import { extractCloudflareResult } from "./api-response.ts";
 import type { CloudflareApi } from "./api.ts";
-import {
-  Self,
-  type Bindings,
-  type WorkerBindingDurableObjectNamespace,
-  type WorkerBindingSpec,
+import type {
+  Bindings,
+  WorkerBindingDurableObjectNamespace,
+  WorkerBindingSpec,
 } from "./bindings.ts";
 import { isContainer, type Container } from "./container.ts";
 import {
@@ -392,11 +391,12 @@ export async function prepareWorkerMetadata(
         name: bindingName,
         text: binding,
       });
-    } else if (binding === Self) {
+    } else if (binding.type === "cloudflare::Worker::Self") {
       meta.bindings.push({
         type: "service",
         name: bindingName,
         service: props.workerName,
+        entrypoint: binding.__entrypoint__,
       });
     } else if (binding.type === "d1") {
       meta.bindings.push({
@@ -416,6 +416,8 @@ export async function prepareWorkerMetadata(
         type: "service",
         name: bindingName,
         service: "service" in binding ? binding.service : binding.name,
+        entrypoint:
+          "__entrypoint__" in binding ? binding.__entrypoint__ : undefined,
       });
     } else if (binding.type === "durable_object_namespace") {
       meta.bindings.push({
@@ -491,12 +493,6 @@ export async function prepareWorkerMetadata(
         name: bindingName,
         index_name: binding.name,
       });
-    } else if (binding.type === "ai_gateway") {
-      // AI Gateway binding - just needs the name property
-      meta.bindings.push({
-        type: "ai",
-        name: bindingName,
-      });
     } else if (binding.type === "hyperdrive") {
       // Hyperdrive binding
       meta.bindings.push({
@@ -510,6 +506,12 @@ export async function prepareWorkerMetadata(
         name: bindingName,
       });
     } else if (binding.type === "ai") {
+      const existing = meta.bindings.find((b) => b.type === "ai");
+      if (existing) {
+        throw new Error(
+          `Workers cannot have multiple AI bindings. Binding "${bindingName}" conflicts with "${existing.name}".`,
+        );
+      }
       meta.bindings.push({
         type: "ai",
         name: bindingName,