alchemy 0.65.1 → 0.67.0

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/paths.ts

@@ -1,5 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { existsSync, readlinkSync, statSync } from "node:fs";
+import path from "node:path";
+import { ALCHEMY_ROOT } from "../../util/root-dir.ts";
 
 const dynamicImportContext = new AsyncLocalStorage<boolean>();
 
@@ -10,13 +12,15 @@ export const withSkipPathValidation = <T>(callback: () => T) => {
   return dynamicImportContext.run(true, callback);
 };
 
-export const DEFAULT_CONFIG_PATH = ".alchemy/local/wrangler.jsonc";
-export const DEFAULT_PERSIST_PATH = ".alchemy/miniflare/v3";
+export const getDefaultConfigPath = (rootDir: string = process.cwd()) => {
+  return path.join(rootDir, ".alchemy", "local", "wrangler.jsonc");
+};
 
-export const validateConfigPath = (
-  path = DEFAULT_CONFIG_PATH,
-  throws = true,
-) => {
+export const getDefaultPersistPath = (rootDir: string = ALCHEMY_ROOT) => {
+  return path.join(rootDir, ".alchemy", "miniflare", "v3");
+};
+
+export const validateConfigPath = (path: string, throws = true) => {
   if (!existsSync(path)) {
     warnOrThrow(
       `The Wrangler config path, "${path}", could not be found. Please run \`alchemy dev\` or \`alchemy deploy\` to create it.`,
@@ -31,7 +35,7 @@ const DEFAULT_VALIDATE_PERSIST =
   !process.argv.some((arg) => ["build", "prepare", "typegen"].includes(arg));
 
 export const validatePersistPath = (
-  path = DEFAULT_PERSIST_PATH,
+  path: string,
   throws = DEFAULT_VALIDATE_PERSIST,
 ) => {
   try {

package/src/cloudflare/miniflare/symlink-miniflare-state.ts

@@ -0,0 +1,19 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getDefaultPersistPath } from "./paths.ts";
+
+export async function writeMiniflareSymlink(rootDir: string, cwd: string) {
+  const target = path.resolve(getDefaultPersistPath(cwd));
+  await fs.mkdir(target, { recursive: true });
+  if (cwd === process.cwd()) {
+    return;
+  }
+  const persistPath = path.resolve(cwd, getDefaultPersistPath(rootDir));
+  console.log("link", target, persistPath);
+  await fs.mkdir(path.dirname(persistPath), { recursive: true });
+  await fs.symlink(target, persistPath).catch((e) => {
+    if (e.code !== "EEXIST") {
+      throw e;
+    }
+  });
+}

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/nuxt/plugin.ts

@@ -1,5 +1,10 @@
 import type { CloudflareOptions } from "nitropack/presets/cloudflare/types";
-import { validateConfigPath, validatePersistPath } from "../miniflare/paths.ts";
+import {
+  getDefaultConfigPath,
+  getDefaultPersistPath,
+  validateConfigPath,
+  validatePersistPath,
+} from "../miniflare/paths.ts";
 
 const alchemy = (
   options: Partial<CloudflareOptions> = {},
@@ -7,8 +12,12 @@ const alchemy = (
   return {
     nodeCompat: true,
     dev: {
-      configPath: validateConfigPath(options.dev?.configPath),
-      persistDir: validatePersistPath(options.dev?.persistDir),
+      configPath: validateConfigPath(
+        options.dev?.configPath ?? getDefaultConfigPath(),
+      ),
+      persistDir: validatePersistPath(
+        options.dev?.persistDir ?? getDefaultPersistPath(),
+      ),
       ...options.dev,
     },
     ...options,

package/src/cloudflare/redwood/plugin.ts

@@ -1,10 +1,10 @@
 import { redwood, type RedwoodPluginOptions } from "rwsdk/vite";
 import type { PluginOption } from "vite";
-import { DEFAULT_CONFIG_PATH } from "../miniflare/paths.ts";
+import { getDefaultConfigPath } from "../miniflare/paths.ts";
 import alchemyVite from "../vite/plugin.ts";
 
 const alchemyRedwood = (options?: RedwoodPluginOptions): PluginOption => {
-  const configPath = options?.configPath ?? DEFAULT_CONFIG_PATH;
+  const configPath = options?.configPath ?? getDefaultConfigPath();
   return [
     redwood({
       ...options,

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/vite/plugin.ts

@@ -2,7 +2,8 @@ import { cloudflare, type PluginConfig } from "@cloudflare/vite-plugin";
 import path from "node:path";
 import type { PluginOption } from "vite";
 import {
-  DEFAULT_PERSIST_PATH,
+  getDefaultConfigPath,
+  getDefaultPersistPath,
   validateConfigPath,
   validatePersistPath,
 } from "../miniflare/paths.ts";
@@ -12,7 +13,8 @@ const alchemy = (config?: PluginConfig): PluginOption => {
     path: validatePersistPath(
       typeof config?.persistState === "object"
         ? config.persistState.path
-        : DEFAULT_PERSIST_PATH,
+        : // persist path should default to the /.alchemy/miniflare/v3
+          getDefaultPersistPath(),
     ),
   };
   if (typeof persistState === "object" && persistState.path.endsWith("v3")) {
@@ -20,7 +22,10 @@ const alchemy = (config?: PluginConfig): PluginOption => {
   }
   return cloudflare({
     ...config,
-    configPath: validateConfigPath(config?.configPath),
+    configPath: validateConfigPath(
+      // config path doesn't need to be in the root, it can be in the app dir
+      config?.configPath ?? getDefaultConfigPath(),
+    ),
     persistState,
     experimental: config?.experimental ?? {
       remoteBindings: true,

package/src/cloudflare/website.ts

@@ -10,7 +10,7 @@ import { Assets } from "./assets.ts";
 import type { Bindings } from "./bindings.ts";
 import { DEFAULT_COMPATIBILITY_DATE } from "./compatibility-date.gen.ts";
 import { unionCompatibilityFlags } from "./compatibility-presets.ts";
-import { DEFAULT_PERSIST_PATH } from "./miniflare/paths.ts";
+import { writeMiniflareSymlink } from "./miniflare/symlink-miniflare-state.ts";
 import { type AssetsConfig, Worker, type WorkerProps } from "./worker.ts";
 import { WranglerJson, type WranglerJsonSpec } from "./wrangler.json.ts";
 
@@ -267,7 +267,9 @@ export async function Website<B extends Bindings>(
     await fs.writeFile(paths.entrypoint, content);
   }
 
-  await writeMiniflareSymlink(paths.cwd);
+  if (Scope.current.local) {
+    await writeMiniflareSymlink(Scope.current.rootDir, paths.cwd);
+  }
 
   await WranglerJson({
     path: path.relative(paths.cwd, paths.wrangler.path),
@@ -293,6 +295,7 @@ export async function Website<B extends Bindings>(
         ...env,
         ...(typeof build === "object" ? build.env : {}),
         NODE_ENV: "production",
+        ALCHEMY_ROOT: Scope.current.rootDir,
       },
       memoize: typeof build === "object" ? build.memoize : undefined,
     });
@@ -350,20 +353,3 @@ export async function Website<B extends Bindings>(
     dev: url ? { url } : undefined,
   })) as Website<B>;
 }
-
-async function writeMiniflareSymlink(cwd: string) {
-  const target = path.resolve(DEFAULT_PERSIST_PATH);
-  await fs.mkdir(target, { recursive: true });
-
-  if (cwd === process.cwd()) {
-    return;
-  }
-
-  const persistPath = path.resolve(cwd, DEFAULT_PERSIST_PATH);
-  await fs.mkdir(path.dirname(persistPath), { recursive: true });
-  await fs.symlink(target, persistPath).catch((e) => {
-    if (e.code !== "EEXIST") {
-      throw e;
-    }
-  });
-}