alchemy 0.66.0 → 0.68.0

package/src/cloudflare/hyperdrive.ts

@@ -190,46 +190,45 @@ export interface HyperdriveProps extends CloudflareApiOptions {
  * Output returned after Cloudflare Hyperdrive creation/update.
  * IMPORTANT: The interface name MUST match the exported resource name.
  */
-export type Hyperdrive = Resource<"cloudflare::Hyperdrive"> &
-  Omit<HyperdriveProps, "origin" | "dev"> & {
-    /**
-     * The ID of the resource
-     */
-    id: string;
-
-    /**
-     * Name of the Hyperdrive configuration
-     */
-    name: string;
+export type Hyperdrive = Omit<HyperdriveProps, "origin" | "dev"> & {
+  /**
+   * The ID of the resource
+   */
+  id: string;
 
-    /**
-     * The Cloudflare-generated UUID of the hyperdrive
-     */
-    hyperdriveId: string;
+  /**
+   * Name of the Hyperdrive configuration
+   */
+  name: string;
 
-    /**
-     * Database connection origin configuration
-     */
-    origin: HyperdrivePublicOrigin | HyperdriveOriginWithAccess;
+  /**
+   * The Cloudflare-generated UUID of the hyperdrive
+   */
+  hyperdriveId: string;
 
-    /**
-     * Local development configuration
-     * @internal
-     */
-    dev: {
-      /**
-       * The connection string to use for local development
-       */
-      origin: Secret;
-    };
+  /**
+   * Database connection origin configuration
+   */
+  origin: HyperdrivePublicOrigin | HyperdriveOriginWithAccess;
 
+  /**
+   * Local development configuration
+   * @internal
+   */
+  dev: {
     /**
-     * Resource type identifier for binding.
-     * @internal
+     * The connection string to use for local development
      */
-    type: "hyperdrive";
+    origin: Secret;
   };
 
+  /**
+   * Resource type identifier for binding.
+   * @internal
+   */
+  type: "hyperdrive";
+};
+
 /**
  * Represents a Cloudflare Hyperdrive configuration.
  *
@@ -356,7 +355,7 @@ const _Hyperdrive = Resource(
       props.name ?? this.output?.name ?? this.scope.createPhysicalName(id);
 
     if (this.scope.local) {
-      return this({
+      return {
         id,
         hyperdriveId: hyperdriveId || "",
         name,
@@ -365,7 +364,7 @@ const _Hyperdrive = Resource(
         mtls: props.mtls,
         dev: props.dev,
         type: "hyperdrive",
-      });
+      };
     }
     const api = await createCloudflareApi(props);
 
@@ -445,7 +444,7 @@ const _Hyperdrive = Resource(
     }
 
     // Construct the output object from API response and props
-    return this({
+    return {
       id,
       hyperdriveId: result.id, // Store the Cloudflare-assigned UUID
       name: result.name,
@@ -454,7 +453,7 @@ const _Hyperdrive = Resource(
       mtls: result.mtls,
       dev: props.dev,
       type: "hyperdrive",
-    });
+    };
   },
 );
 

package/src/cloudflare/index.ts

@@ -30,6 +30,7 @@ export * from "./email-address.ts";
 export * from "./email-catch-all.ts";
 export * from "./email-routing.ts";
 export * from "./email-rule.ts";
+export * from "./hyperdrive-ref.ts";
 export * from "./hyperdrive.ts";
 export * from "./images.ts";
 export * from "./kv-namespace.ts";
@@ -49,6 +50,7 @@ export * from "./route.ts";
 export * from "./rule.ts";
 export * from "./ruleset.ts";
 export * from "./secret-key.ts";
+export * from "./secret-ref.ts";
 export * from "./secret.ts";
 export * from "./secrets-store.ts";
 export * from "./state.ts";

package/src/cloudflare/kv-namespace.ts

@@ -95,47 +95,46 @@ export interface KVPair {
   metadata?: any;
 }
 
-export function isKVNamespace(resource: Resource): resource is KVNamespace {
-  return resource[ResourceKind] === "cloudflare::KVNamespace";
+export function isKVNamespace(resource: any): resource is KVNamespace {
+  return resource?.[ResourceKind] === "cloudflare::KVNamespace";
 }
 
 /**
  * Output returned after KV Namespace creation/update
  */
-export type KVNamespace = Resource<"cloudflare::KVNamespace"> &
-  Omit<KVNamespaceProps, "delete" | "dev"> & {
-    type: "kv_namespace";
-    /**
-     * The ID of the namespace
-     */
-    namespaceId: string;
+export type KVNamespace = Omit<KVNamespaceProps, "delete" | "dev"> & {
+  type: "kv_namespace";
+  /**
+   * The ID of the namespace
+   */
+  namespaceId: string;
 
-    /**
-     * Time at which the namespace was created
-     */
-    createdAt: number;
+  /**
+   * Time at which the namespace was created
+   */
+  createdAt: number;
+
+  /**
+   * Time at which the namespace was last modified
+   */
+  modifiedAt: number;
 
+  /**
+   * Development mode properties
+   * @internal
+   */
+  dev: {
     /**
-     * Time at which the namespace was last modified
+     * The ID of the KV namespace in development mode
      */
-    modifiedAt: number;
+    id: string;
 
     /**
-     * Development mode properties
-     * @internal
+     * Whether the KV namespace is running remotely
      */
-    dev: {
-      /**
-       * The ID of the KV namespace in development mode
-       */
-      id: string;
-
-      /**
-       * Whether the KV namespace is running remotely
-       */
-      remote: boolean;
-    };
+    remote: boolean;
   };
+};
 
 /**
  * A Cloudflare KV Namespace is a key-value store that can be used to store data for your application.
@@ -221,7 +220,7 @@ const _KVNamespace = Resource(
     };
 
     if (local) {
-      return this({
+      return {
         type: "kv_namespace",
         namespaceId: this.output?.namespaceId ?? "",
         title,
@@ -229,7 +228,7 @@ const _KVNamespace = Resource(
         dev,
         createdAt: this.output?.createdAt ?? Date.now(),
         modifiedAt: Date.now(),
-      });
+      };
     }
 
     const api = await createCloudflareApi(props);
@@ -260,7 +259,7 @@ const _KVNamespace = Resource(
 
     await insertKVRecords(api, result.namespaceId, props);
 
-    return this({
+    return {
       type: "kv_namespace",
       namespaceId: result.namespaceId,
       title,
@@ -268,7 +267,7 @@ const _KVNamespace = Resource(
       dev,
       createdAt: result.createdAt,
       modifiedAt: Date.now(),
-    });
+    };
   },
 );
 

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

@@ -113,7 +113,7 @@ async function cleanMiniflareDirectory(dotAlchemy: string) {
 
 const removeDirectory = async (path: string, options?: RmDirOptions) => {
   try {
-    await fs.rmdir(path, options);
+    await fs.rm(path, options);
   } catch (error) {
     if (!isENOENT(error)) {
       throw error;

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,103 @@
 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";
+import { coupleWebSocket } from "../../util/http.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);
+      coupleWebSocket(wss, req, socket, head, server);
+    } 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 +112,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 +137,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,
+    });
+  }
+}