alchemy 0.39.0 → 0.40.0

package/src/cloudflare/worker/miniflare.ts

@@ -0,0 +1,198 @@
+import type {
+  Miniflare,
+  MiniflareOptions,
+  RemoteProxyConnectionString,
+  WorkerOptions,
+} from "miniflare";
+import path from "node:path";
+import { logger } from "../../util/logger.ts";
+import { HTTPServer } from "./http-server.ts";
+import {
+  buildMiniflareWorkerOptions,
+  buildRemoteBindings,
+  type MiniflareWorkerOptions,
+} from "./miniflare-worker-options.ts";
+import { createMixedModeProxy, type MixedModeProxy } from "./mixed-mode.ts";
+
+class MiniflareServer {
+  miniflare?: Miniflare;
+  workers = new Map<string, WorkerOptions>();
+  servers = new Map<string, HTTPServer>();
+  mixedModeProxies = new Map<string, MixedModeProxy>();
+
+  stream = new WritableStream<{
+    worker: MiniflareWorkerOptions;
+    promise: PromiseWithResolvers<HTTPServer>;
+  }>({
+    write: async ({ worker, promise }) => {
+      try {
+        const server = await this.set(worker);
+        promise.resolve(server);
+      } catch (error) {
+        promise.reject(error);
+      }
+    },
+    close: async () => {
+      await this.dispose();
+    },
+  });
+  writer = this.stream.getWriter();
+
+  async push(worker: MiniflareWorkerOptions) {
+    const promise = Promise.withResolvers<HTTPServer>();
+    const [, server] = await Promise.all([
+      this.writer.write({ worker, promise }),
+      promise.promise,
+    ]);
+    return server;
+  }
+
+  async close() {
+    await this.writer.close();
+  }
+
+  private async set(worker: MiniflareWorkerOptions) {
+    this.workers.set(
+      worker.name as string,
+      buildMiniflareWorkerOptions({
+        ...worker,
+        remoteProxyConnectionString:
+          await this.maybeCreateMixedModeProxy(worker),
+      }),
+    );
+    if (this.miniflare) {
+      await this.miniflare.setOptions(await this.miniflareOptions());
+    } else {
+      const { Miniflare } = await import("miniflare").catch(() => {
+        throw new Error(
+          "Miniflare is not installed, but is required in local mode for Workers. Please run `npm install miniflare`.",
+        );
+      });
+
+      // Miniflare intercepts SIGINT and exits with 130, which is not a failure.
+      // No one likes to see a non-zero exit code when they Ctrl+C, so here's our workaround.
+      process.on("exit", (code) => {
+        if (code === 130) {
+          process.exit(0);
+        }
+      });
+
+      this.miniflare = new Miniflare(await this.miniflareOptions());
+      await this.miniflare.ready;
+    }
+    const existing = this.servers.get(worker.name);
+    if (existing) {
+      return existing;
+    }
+    const server = new HTTPServer({
+      port: worker.port,
+      fetch: this.createRequestHandler(worker.name as string),
+    });
+    this.servers.set(worker.name, server);
+    await server.ready;
+    return server;
+  }
+
+  private async dispose() {
+    await Promise.all([
+      this.miniflare?.dispose(),
+      ...Array.from(this.servers.values()).map((server) => server.stop()),
+      ...Array.from(this.mixedModeProxies.values()).map((proxy) =>
+        proxy.server.stop(),
+      ),
+    ]);
+    this.miniflare = undefined;
+    this.workers.clear();
+    this.servers.clear();
+  }
+
+  private async maybeCreateMixedModeProxy(
+    worker: MiniflareWorkerOptions,
+  ): Promise<RemoteProxyConnectionString | undefined> {
+    const bindings = buildRemoteBindings(worker);
+    if (bindings.length === 0) {
+      return undefined;
+    }
+    const existing = this.mixedModeProxies.get(worker.name);
+    if (
+      existing?.bindings.every((b) =>
+        bindings.find((b2) => b2.name === b.name && b2.type === b.type),
+      )
+    ) {
+      return existing.connectionString;
+    }
+    const proxy = await createMixedModeProxy({
+      name: `mixed-mode-proxy-${crypto.randomUUID()}`,
+      bindings,
+    });
+    this.mixedModeProxies.set(worker.name, proxy);
+    return proxy.connectionString;
+  }
+
+  private createRequestHandler(name: string) {
+    return async (req: Request) => {
+      try {
+        if (!this.miniflare) {
+          return new Response(
+            "[Alchemy] Miniflare is not initialized. Please try again.",
+            {
+              status: 503,
+            },
+          );
+        }
+        const miniflare = await this.miniflare?.getWorker(name);
+        if (!miniflare) {
+          return new Response(
+            `[Alchemy] Cannot find worker "${name}". Please try again.`,
+            {
+              status: 503,
+            },
+          );
+        }
+        const res = await miniflare.fetch(req.url, {
+          method: req.method,
+          headers: req.headers as any,
+          body: req.body as any,
+          redirect: "manual",
+        });
+        return res as unknown as Response;
+      } catch (error) {
+        logger.error(error);
+        return new Response(
+          `[Alchemy] Internal server error: ${String(error)}`,
+          {
+            status: 500,
+          },
+        );
+      }
+    };
+  }
+
+  private async miniflareOptions(): Promise<MiniflareOptions> {
+    const { getDefaultDevRegistryPath } = await import("miniflare");
+    return {
+      workers: Array.from(this.workers.values()),
+      defaultPersistRoot: path.join(process.cwd(), ".alchemy/miniflare"),
+      unsafeDevRegistryPath: getDefaultDevRegistryPath(),
+      analyticsEngineDatasetsPersist: true,
+      cachePersist: true,
+      d1Persist: true,
+      durableObjectsPersist: true,
+      kvPersist: true,
+      r2Persist: true,
+      secretsStorePersist: true,
+      workflowsPersist: true,
+    };
+  }
+}
+
+declare global {
+  var _ALCHEMY_MINIFLARE_SERVER: MiniflareServer | undefined;
+}
+
+export const miniflareServer = new Proxy({} as MiniflareServer, {
+  get: (_, prop: keyof MiniflareServer) => {
+    globalThis._ALCHEMY_MINIFLARE_SERVER ??= new MiniflareServer();
+    return globalThis._ALCHEMY_MINIFLARE_SERVER[prop];
+  },
+});

package/src/cloudflare/worker/mixed-mode.ts

@@ -0,0 +1,220 @@
+import type { RemoteProxyConnectionString } from "miniflare";
+import { createCloudflareApi, type CloudflareApi } from "../api.ts";
+import type { WorkerBindingSpec } from "../bindings.ts";
+import type { CloudflareApiResponse } from "../types.ts";
+import type { WorkerMetadata } from "../worker-metadata.ts";
+import { getWorkerTemplate } from "./get-worker-template.ts";
+import { HTTPServer } from "./http-server.ts";
+import { getAccountSubdomain } from "./subdomain.ts";
+
+type WranglerSessionConfig =
+  | {
+      workers_dev: boolean;
+      minimal_mode: boolean;
+    }
+  | {
+      routes: string[];
+      minimal_mode: boolean;
+    };
+
+interface WorkersPreviewSession {
+  inspector_websocket: string;
+  prewarm: string;
+  token: string;
+}
+
+export async function createMixedModeProxy(input: {
+  name: string;
+  bindings: WorkerBindingSpec[];
+}) {
+  const api = await createCloudflareApi();
+  const script = await getWorkerTemplate("mixed-mode-proxy-worker");
+  const [token, subdomain] = await Promise.all([
+    createWorkersPreviewToken(api, {
+      name: input.name,
+      metadata: {
+        main_module: script.name,
+        compatibility_date: "2025-06-16",
+        bindings: input.bindings,
+        observability: {
+          enabled: false,
+        },
+      },
+      files: [script],
+      session: {
+        workers_dev: true,
+        minimal_mode: true,
+      },
+    }),
+    getAccountSubdomain(api),
+  ]);
+  return new MixedModeProxy(
+    `https://${input.name}.${subdomain}.workers.dev`,
+    token,
+    input.bindings,
+  );
+}
+
+const DEBUG: boolean = false;
+
+export class MixedModeProxy {
+  server: HTTPServer;
+
+  constructor(
+    readonly url: string,
+    readonly token: string,
+    readonly bindings: WorkerBindingSpec[],
+  ) {
+    this.server = new HTTPServer({
+      fetch: this.fetch.bind(this),
+    });
+  }
+
+  get connectionString() {
+    const hostname =
+      this.server.hostname === "::" ? "localhost" : this.server.hostname;
+    return new URL(
+      `http://${hostname}:${this.server.port}`,
+    ) as RemoteProxyConnectionString;
+  }
+
+  async fetch(req: Request) {
+    const origin = new URL(req.url);
+    const url = new URL(origin.pathname, this.url);
+    url.search = origin.search;
+    url.hash = origin.hash;
+
+    const headers = new Headers(req.headers);
+    headers.set("cf-workers-preview-token", this.token);
+    headers.set("host", new URL(this.url).hostname);
+    headers.delete("cf-connecting-ip");
+
+    const res = await fetch(url, {
+      method: req.method,
+      headers,
+      body: req.body,
+      redirect: "manual",
+    });
+
+    // Remove headers that are not supported by miniflare
+    const responseHeaders = new Headers(res.headers);
+    responseHeaders.delete("transfer-encoding");
+    responseHeaders.delete("content-encoding");
+
+    if (DEBUG) {
+      const clone = res.clone();
+      console.log({
+        request: {
+          url: url.toString(),
+          method: req.method,
+          headers,
+          body: req.body,
+        },
+        response: {
+          status: res.status,
+          headers: res.headers,
+          body: await res.text(),
+        },
+      });
+      return new Response(clone.body, {
+        status: clone.status,
+        headers: responseHeaders,
+      });
+    }
+
+    return new Response(res.body, {
+      status: res.status,
+      headers: responseHeaders,
+    });
+  }
+}
+
+async function createWorkersPreviewToken(
+  api: CloudflareApi,
+  input: {
+    name: string;
+    metadata: WorkerMetadata;
+    files: File[];
+    session: WranglerSessionConfig;
+  },
+) {
+  const session = await createWorkersPreviewSession(api);
+  const formData = new FormData();
+  formData.append("metadata", JSON.stringify(input.metadata));
+  for (const file of input.files) {
+    formData.append(file.name, file);
+  }
+  formData.append("wrangler-session-config", JSON.stringify(input.session));
+  const res = await api
+    .post(
+      `/accounts/${api.accountId}/workers/scripts/${input.name}/edge-preview`,
+      formData,
+      {
+        headers: {
+          "cf-preview-upload-config-token": session.token,
+        },
+      },
+    )
+    .then((res) =>
+      parseCloudflareResponse<{ preview_token: string }>(
+        res,
+        "Failed to create workers preview token",
+      ),
+    );
+  // Fire and forget prewarm call
+  // (see https://github.com/cloudflare/workers-sdk/blob/6c6afbd6072b96e78e67d3a863ed849c6aa49472/packages/wrangler/src/dev/create-worker-preview.ts#L338)
+  void prewarm(session.prewarm, res.preview_token);
+  return res.preview_token;
+}
+
+async function prewarm(url: string, previewToken: string) {
+  const res = await fetch(url, {
+    headers: {
+      "cf-workers-preview-token": previewToken,
+    },
+  });
+  if (!res.ok) {
+    console.error(`Failed to prewarm worker: ${res.status} ${res.statusText}`);
+  }
+}
+
+async function createWorkersPreviewSession(api: CloudflareApi) {
+  const { exchange_url } = await api
+    .get(`/accounts/${api.accountId}/workers/subdomain/edge-preview`)
+    .then((res) =>
+      parseCloudflareResponse<{
+        exchange_url: string;
+        token: string;
+      }>(res, "Failed to create workers preview session"),
+    );
+  return await fetch(exchange_url).then((res) =>
+    parseResponse<WorkersPreviewSession>(
+      res,
+      "Failed to create workers preview session",
+    ),
+  );
+}
+
+async function parseResponse<T>(res: Response, message: string): Promise<T> {
+  if (!res.ok) {
+    throw new Error(`${message} (${res.status} ${res.statusText})`);
+  }
+  const json: T = await res.json();
+  return json;
+}
+
+async function parseCloudflareResponse<T>(
+  res: Response,
+  message: string,
+): Promise<T> {
+  const json: CloudflareApiResponse<T> = await res.json();
+  if (!json.success) {
+    throw new Error(
+      `${message} (${res.status} ${res.statusText} - ${json.errors.map((e) => `${e.code}: ${e.message}`).join(", ")})`,
+    );
+  }
+  if (!json.result) {
+    throw new Error(`${message} (${res.status} ${res.statusText})`);
+  }
+  return json.result;
+}

package/src/cloudflare/worker/subdomain.ts

@@ -0,0 +1,16 @@
+import { memoize } from "../../util/memoize.ts";
+import type { CloudflareApi } from "../api.ts";
+
+export const getAccountSubdomain = memoize(
+  async (api: CloudflareApi) => {
+    const res = await api.get(`/accounts/${api.accountId}/workers/subdomain`);
+    if (!res.ok) {
+      throw new Error(
+        `Failed to get account subdomain: ${res.status} ${res.statusText}`,
+      );
+    }
+    const json: { result?: { subdomain: string } } = await res.json();
+    return json.result?.subdomain;
+  },
+  (api) => api.accountId,
+);

package/src/cloudflare/worker-metadata.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { assertNever } from "../util/assert-never.ts";
 import { logger } from "../util/logger.ts";
 import type { CloudflareApi } from "./api.ts";
 import {
@@ -209,7 +210,6 @@ export async function prepareWorkerMetadata(
   const oldTags: string[] | undefined =
     oldSettings?.default_environment?.script?.tags;
   const oldBindings = oldSettings?.bindings;
-
   // we use Cloudflare Worker tags to store a mapping between Alchemy's stable identifier and the binding name
   // e.g.
   // {
@@ -384,7 +384,10 @@ export async function prepareWorkerMetadata(
         type: "durable_object_namespace",
         name: bindingName,
         class_name: binding.className,
-        script_name: binding.scriptName,
+        script_name:
+          binding.scriptName === props.workerName
+            ? undefined
+            : binding.scriptName,
         environment: binding.environment,
         namespace_id: binding.namespaceId,
       });
@@ -510,8 +513,13 @@ export async function prepareWorkerMetadata(
         key_jwk: binding.key_jwk?.unencrypted,
       });
     } else {
-      // @ts-expect-error - we should never reach here
-      throw new Error(`Unsupported binding type: ${binding.type}`);
+      assertNever(
+        binding,
+        `Unsupported binding type: ${
+          // @ts-expect-error - types think it's never
+          binding.type
+        }`,
+      );
     }
   }