alchemy 0.55.2 → 0.56.0

package/src/cloudflare/miniflare/remote-binding-proxy.ts

@@ -32,7 +32,7 @@ export interface RemoteBindingProxy {
 export async function createRemoteProxyWorker(input: {
   name: string;
   bindings: WorkerBindingSpec[];
-}) {
+}): Promise<RemoteBindingProxy> {
   const api = await createCloudflareApi();
   const script = await getInternalWorkerBundle("remote-binding-proxy");
   const [token, subdomain] = await Promise.all([
@@ -42,9 +42,7 @@ export async function createRemoteProxyWorker(input: {
         main_module: script.bundle.entrypoint,
         compatibility_date: "2025-06-16",
         bindings: input.bindings,
-        observability: {
-          enabled: false,
-        },
+        observability: { enabled: false },
       },
       bundle: script.bundle,
       session: {
@@ -55,27 +53,24 @@ export async function createRemoteProxyWorker(input: {
     import("../worker-subdomain.ts").then((m) => m.getAccountSubdomain(api)),
   ]);
 
-  const proxyURL = new URL(`https://${input.name}.${subdomain}.workers.dev`);
+  const proxyURL = `https://${input.name}.${subdomain}.workers.dev`;
   const server = new HTTPServer({
     fetch: async (req) => {
-      const origin = new URL(req.url);
-      const url = new URL(origin.pathname, proxyURL.toString());
-      url.search = origin.search;
-      url.hash = origin.hash;
+      const url = new URL(req.url);
+      const targetUrl = new URL(url.pathname + url.search, proxyURL);
 
-      const requestHeaders = new Headers(req.headers);
-      requestHeaders.set("cf-workers-preview-token", token);
-      requestHeaders.set("host", proxyURL.hostname);
-      requestHeaders.delete("cf-connecting-ip");
+      const headers = new Headers(req.headers);
+      headers.set("cf-workers-preview-token", token);
+      headers.set("host", new URL(proxyURL).hostname);
+      headers.delete("cf-connecting-ip");
 
-      const res = await fetch(url, {
+      const res = await fetch(targetUrl, {
         method: req.method,
-        headers: requestHeaders,
+        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");
@@ -86,6 +81,7 @@ export async function createRemoteProxyWorker(input: {
       });
     },
   });
+
   await server.listen();
   return {
     server,
@@ -126,13 +122,12 @@ async function createWorkersPreviewToken(
 }
 
 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}`);
+  try {
+    await fetch(url, {
+      headers: { "cf-workers-preview-token": previewToken },
+    });
+  } catch {
+    // Ignore prewarm errors
   }
 }
 

package/src/cloudflare/website.ts

@@ -206,11 +206,11 @@ export default {
       } as WorkerProps<any> & { name: string };
 
       if (wrangler) {
-        const wranglerPath = path.relative(cwd, wranglerJsonPath);
-        const wranglerDir = path.dirname(wranglerPath);
+        const wranglerAbsPath = path.resolve(cwd, wranglerJsonPath);
+        const wranglerAbsDir = path.dirname(wranglerAbsPath);
 
         await WranglerJson("wrangler.jsonc", {
-          path: wranglerPath,
+          path: path.relative(cwd, wranglerJsonPath),
           worker: workerProps,
           // @ts-expect-error - props.wrangler can be string | object, this is fine
           main: props.wrangler?.main ?? props.main,
@@ -218,7 +218,7 @@ export default {
           assets: {
             binding: "ASSETS",
             // path must be relative to the wrangler.jsonc file
-            directory: path.relative(wranglerDir, assetsDirPath),
+            directory: path.relative(wranglerAbsDir, assetsDirPath),
           },
           transform: props.transform,
         });

package/src/cloudflare/worker-bundle.ts

@@ -1,8 +1,10 @@
 import esbuild from "esbuild";
 import { err, ok, type Result } from "neverthrow";
 import fs from "node:fs/promises";
-import path from "node:path";
+import path from "pathe";
+import { logger } from "../util/logger.ts";
 import { external, external_als } from "./bundle/externals.ts";
+import { esbuildPluginAlias } from "./bundle/plugin-alias.ts";
 import { esbuildPluginCompatWarning } from "./bundle/plugin-compat-warning.ts";
 import { createHotReloadPlugin } from "./bundle/plugin-hot-reload.ts";
 import { esbuildPluginHybridNodeCompat } from "./bundle/plugin-hybrid-node-compat.ts";
@@ -16,6 +18,7 @@ export interface WorkerBundle {
 }
 
 export function normalizeWorkerBundle(props: {
+  id: string;
   script: string | undefined;
   entrypoint: string | undefined;
   noBundle: boolean | undefined;
@@ -65,6 +68,7 @@ export function normalizeWorkerBundle(props: {
             sourcemaps: props.sourceMap !== false,
           })
         : new WorkerBundleSource.ESBuild({
+            id: props.id,
             entrypoint: props.entrypoint,
             format: props.format ?? "esm",
             nodeCompat,
@@ -237,6 +241,7 @@ export namespace WorkerBundleSource {
         esbuild.BuildOptions,
         "entryPoints" | "format" | "absWorkingDir" | "outdir"
       > {
+    id: string;
     entrypoint: string;
     cwd: string;
     outdir: string;
@@ -273,7 +278,20 @@ export namespace WorkerBundleSource {
 
     async *watch(signal: AbortSignal): AsyncIterable<WorkerBundle> {
       const wasm = createWasmPlugin();
-      const hotReload = createHotReloadPlugin();
+      let count = 0;
+      const hotReload = createHotReloadPlugin({
+        onBuildStart: () => {
+          if (count > 0) {
+            logger.task(this.props.id, {
+              message: "Rebuilding",
+              status: "pending",
+              resource: this.props.id,
+              prefix: "dev",
+              prefixColor: "cyanBright",
+            });
+          }
+        },
+      });
       const options = this.buildOptions([wasm.plugin, hotReload.plugin]);
 
       const context = await esbuild.context(options);
@@ -281,6 +299,7 @@ export namespace WorkerBundleSource {
       await context.watch();
 
       for await (const result of hotReload.iterator) {
+        count++;
         const { entrypoint, root, modules } = this.resolveBuildOutput(
           result.metafile!,
         );
@@ -300,7 +319,14 @@ export namespace WorkerBundleSource {
     }
 
     private buildOptions(additionalPlugins: esbuild.Plugin[]) {
-      const { entrypoint, nodeCompat, cwd, format, ...props } = this.props;
+      const {
+        id: _,
+        entrypoint,
+        nodeCompat,
+        cwd,
+        format,
+        ...props
+      } = this.props;
       return {
         entryPoints: [entrypoint],
         absWorkingDir: cwd,
@@ -319,13 +345,13 @@ export namespace WorkerBundleSource {
           ...props.loader,
         },
         plugins: [
+          esbuildPluginAlias(props.alias ?? {}, this.props.cwd),
           nodeCompat === "v2"
             ? esbuildPluginHybridNodeCompat()
             : esbuildPluginCompatWarning(nodeCompat ?? null),
           ...(props.plugins ?? []),
           ...additionalPlugins,
         ],
-        alias: props.alias,
         external: [
           ...(nodeCompat === "als" ? external_als : external),
           ...(props.external ?? []),

package/src/cloudflare/worker.ts

@@ -1,4 +1,3 @@
-import kleur from "kleur";
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import { isDeepStrictEqual } from "node:util";
@@ -9,6 +8,7 @@ import { Resource, ResourceKind } from "../resource.ts";
 import { isSecret } from "../secret.ts";
 import type { type } from "../type.ts";
 import { DeferredPromise } from "../util/deferred-promise.ts";
+import { exists } from "../util/exists.ts";
 import { logger } from "../util/logger.ts";
 import { withExponentialBackoff } from "../util/retry.ts";
 import { CloudflareApiError, handleApiError } from "./api-error.ts";
@@ -38,8 +38,6 @@ import {
   isDurableObjectNamespace,
 } from "./durable-object-namespace.ts";
 import { type EventSource, isQueueEventSource } from "./event-source.ts";
-import type { MiniflareWorkerOptions } from "./miniflare/miniflare-worker-options.ts";
-import { miniflareServer } from "./miniflare/miniflare.ts";
 import {
   QueueConsumer,
   deleteQueueConsumer,
@@ -48,11 +46,7 @@ import {
 import { isQueue } from "./queue.ts";
 import { Route } from "./route.ts";
 import { uploadAssets } from "./worker-assets.ts";
-import {
-  WorkerBundle,
-  type WorkerBundleSource,
-  normalizeWorkerBundle,
-} from "./worker-bundle.ts";
+import { WorkerBundle, normalizeWorkerBundle } from "./worker-bundle.ts";
 import {
   type WorkerScriptMetadata,
   bumpMigrationTagVersion,
@@ -65,7 +59,6 @@ import { Workflow, isWorkflow, upsertWorkflow } from "./workflow.ts";
 // Previous versions of `Worker` used the `Bundle` resource.
 // This import is here to avoid errors when destroying the `Bundle` resource.
 import "../esbuild/bundle.ts";
-import { exists } from "../util/exists.ts";
 
 /**
  * Configuration options for static assets
@@ -736,6 +729,7 @@ const _Worker = Resource(
         : props.namespace?.namespaceName;
 
     const bundleSourceResult = normalizeWorkerBundle({
+      id,
       entrypoint: props.entrypoint,
       script: props.script,
       format: props.format,
@@ -762,7 +756,7 @@ const _Worker = Resource(
       }
 
       if (props.dev?.command) {
-        const { url: commandUrl } = await createDevCommand({
+        const result = await createDevCommand({
           id,
           command: props.dev.command,
           cwd: props.dev.cwd || props.cwd || process.cwd(),
@@ -780,18 +774,25 @@ const _Worker = Resource(
             ),
           },
         });
-        url = commandUrl;
+        url = result.url;
+        this.onCleanup(() => result.cleanup());
       } else {
-        url = await createMiniflare({
+        const { MiniflareController } = await import(
+          "./miniflare/miniflare-controller.ts"
+        );
+        const controller = MiniflareController.singleton;
+        url = await controller.add({
           id,
-          workerName,
+          name: workerName,
           compatibilityDate,
           compatibilityFlags,
           bindings: props.bindings,
+          eventSources: props.eventSources,
+          assets: props.assets,
           bundle: bundleSourceResult.value,
           port: props.dev?.port,
-          assets: props.assets,
         });
+        this.onCleanup(() => controller.dispose());
       }
 
       return this({
@@ -926,7 +927,6 @@ const _Worker = Resource(
     let putWorkerResult: PutWorkerResult;
     if (watch) {
       const controller = new AbortController();
-      cleanups.push(() => controller.abort());
       const promise = new DeferredPromise<PutWorkerResult>();
       const runWatch = async () => {
         for await (const bundle of bundleSource.watch(controller.signal)) {
@@ -973,14 +973,12 @@ const _Worker = Resource(
         }
       };
       void runWatch(); // this is not awaited because it's an ongoing process
+      this.onCleanup(() => controller.abort());
       putWorkerResult = await promise.value;
-      await createTail(api, id, workerName)
-        .then((tail) => {
-          cleanups.push(() => tail.close());
-        })
-        .catch((error) => {
-          logger.error(`Failed to create tail for ${workerName}`, error);
-        });
+      const tail = await createTail(api, id, workerName).catch((error) => {
+        logger.error(`Failed to create tail for ${workerName}`, error);
+      });
+      this.onCleanup(() => tail?.close());
     } else {
       const scriptBundle = await bundleSource.create();
       putWorkerResult = await putWorkerWithAssets(props, scriptBundle);
@@ -1102,22 +1100,6 @@ const _Worker = Resource(
   },
 );
 
-const cleanups: (() => any)[] = [];
-let exiting = false;
-
-process.on("SIGINT", async () => {
-  if (cleanups.length > 0) {
-    if (!exiting) {
-      exiting = true;
-      logger.log(`\n${kleur.gray("Exiting...")}`);
-    }
-    // TODO: for some reason this runs twice...
-    // and this whole thing feels hacky anyway
-    await Promise.allSettled(cleanups.map((cleanup) => cleanup()));
-  }
-  process.exit(0);
-});
-
 const assertUnique = <T, Key extends keyof T>(
   inputs: T[],
   key: Key,
@@ -1337,56 +1319,12 @@ async function provisionSubdomain(
   }
 }
 
-async function createMiniflare(props: {
-  id: string;
-  workerName: string;
-  compatibilityDate: string;
-  compatibilityFlags: string[];
-  bindings: Bindings | undefined;
-  port: number | undefined;
-  bundle: WorkerBundleSource;
-  assets: AssetsConfig | undefined;
-}) {
-  const sharedOptions: Omit<MiniflareWorkerOptions, "bundle"> = {
-    name: props.workerName,
-    compatibilityDate: props.compatibilityDate,
-    compatibilityFlags: props.compatibilityFlags,
-    bindings: props.bindings,
-    port: props.port,
-    assets: props.assets,
-  };
-
-  const startPromise = new DeferredPromise<string>();
-  const controller = new AbortController();
-  cleanups.push(() => controller.abort());
-  const run = async () => {
-    for await (const bundle of props.bundle.watch(controller.signal)) {
-      const server = await miniflareServer.push({
-        ...sharedOptions,
-        bundle,
-      });
-      if (startPromise.status === "pending") {
-        startPromise.resolve(server.url);
-      }
-      logger.task("", {
-        message: `ready at ${server.url}`,
-        status: "success",
-        resource: props.id,
-        prefix: "miniflare",
-        prefixColor: "greenBright",
-      });
-    }
-  };
-  void run();
-  return await startPromise.value;
-}
-
 async function createDevCommand(props: {
   id: string;
   command: string;
   cwd: string;
   env: Record<string, string | undefined>;
-}): Promise<{ url: string }> {
+}) {
   const persistFile = path.join(process.cwd(), ".alchemy", `${props.id}.pid`);
   if (await exists(persistFile)) {
     const pid = Number.parseInt(await fs.readFile(persistFile, "utf8"));
@@ -1404,7 +1342,9 @@ async function createDevCommand(props: {
   }
   const command = props.command.split(" ");
   const [cmd, ...args] = command;
-  const proc = spawn(cmd, args, {
+
+  const promise = new DeferredPromise<string>();
+  const childProcess = spawn(cmd, args, {
     cwd: props.cwd,
     shell: true,
     env: {
@@ -1420,56 +1360,81 @@ async function createDevCommand(props: {
     },
     stdio: ["inherit", "pipe", "pipe"],
   });
-  const { url } = await new Promise<{ url: string }>((resolve, reject) => {
-    let urlFound = false;
-    let stdout = "";
-    let stderr = "";
-    const urlRegex =
-      /http:\/\/(?:(?:localhost|0\.0\.0\.0|127\.0\.0\.1)|(?:\d{1,3}\.){3}\d{1,3}):\d+(?:\/)?/;
-
-    const parseOutput = (data: string) => {
-      if (!urlFound) {
-        const match = data.match(urlRegex);
-        if (match) {
-          urlFound = true;
-          resolve({ url: match[0] });
-        }
-      }
-    };
 
-    // Handle stdout - parse for URL and write through with colors preserved
-    proc.stdout?.on("data", (data) => {
-      parseOutput(
-        (stdout += data.toString().replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")),
-      );
-      process.stdout.write(data);
-    });
+  // Clean up the pid file when the process exits
+  childProcess.once("exit", async () => {
+    try {
+      await fs.unlink(persistFile);
+    } catch {
+      // ignore
+    }
+  });
 
-    proc.stderr?.on("data", (data) => {
-      parseOutput(
-        (stderr += data.toString().replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")),
-      );
-      process.stderr.write(data);
-    });
+  let urlFound = false;
+  let stdout = "";
+  let stderr = "";
+  const urlRegex =
+    /http:\/\/(?:(?:localhost|0\.0\.0\.0|127\.0\.0\.1)|(?:\d{1,3}\.){3}\d{1,3}):\d+(?:\/)?/;
+
+  const parseOutput = (data: string) => {
+    if (!urlFound) {
+      const match = data.match(urlRegex);
+      if (match) {
+        urlFound = true;
+        promise.resolve(match[0]);
+      }
+    }
+  };
 
-    proc.on("error", (error) => {
-      reject(error);
-    });
+  // Handle stdout - parse for URL and write through with colors preserved
+  childProcess.stdout?.on("data", (data) => {
+    parseOutput(
+      (stdout += data.toString().replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")),
+    );
+    process.stdout.write(data);
+  });
 
-    cleanups.push(async () => {
+  childProcess.stderr?.on("data", (data) => {
+    parseOutput(
+      (stderr += data.toString().replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "")),
+    );
+    process.stderr.write(data);
+  });
+
+  childProcess.on("error", (error) => {
+    promise.reject(error);
+  });
+  if (childProcess.pid) {
+    await fs.mkdir(path.dirname(persistFile), { recursive: true });
+    await fs.writeFile(persistFile, childProcess.pid.toString());
+  }
+  return {
+    url: await promise.value,
+    cleanup: async () => {
       try {
         await fs.unlink(persistFile);
       } catch {
         // ignore
       }
-      proc.kill();
-    });
-  });
-  if (proc.pid) {
-    await fs.mkdir(path.dirname(persistFile), { recursive: true });
-    await fs.writeFile(persistFile, proc.pid.toString());
-  }
-  return { url };
+      if (!childProcess.killed) {
+        childProcess.kill("SIGTERM");
+        // Give it time to exit gracefully
+        await new Promise<void>((resolve) => {
+          const timeout = setTimeout(() => {
+            if (!childProcess.killed) {
+              childProcess.kill("SIGKILL");
+            }
+            resolve();
+          }, 5000);
+
+          childProcess.once("exit", () => {
+            clearTimeout(timeout);
+            resolve();
+          });
+        });
+      }
+    },
+  };
 }
 
 type PutWorkerOptions = Omit<WorkerProps, "entrypoint"> & {

package/src/context.ts

@@ -67,6 +67,17 @@ export interface BaseContext<Out extends Resource> {
    * "return undefined" so that `await MyResource()` always returns a value.
    */
   destroy(): never;
+  /**
+   * Register a cleanup function that will be called when the process exits.
+   *
+   * @example
+   * const proc = spawn('my-command', ['arg1', 'arg2']);
+   * this.onCleanup(async () => {
+   *   proc.kill();
+   *   await waitForExit(proc);
+   * });
+   */
+  onCleanup(fn: () => void | Promise<void>): void;
   /**
    * Create the Resource envelope (with Alchemy + User properties)
    */
@@ -153,6 +164,14 @@ export function context<
     destroy: () => {
       throw new DestroyedSignal();
     },
+    onCleanup: (fn: () => void | Promise<void>) => {
+      // make the function idempotent so repeated calls don't cause the process to hang
+      let promise: Promise<void> | undefined;
+      scope.root.onCleanup(async () => {
+        promise ??= Promise.resolve(fn());
+        await promise;
+      });
+    },
     create,
   }) as unknown as Context<Out>;
 }

package/src/scope.ts

@@ -1,3 +1,4 @@
+import kleur from "kleur";
 import { AsyncLocalStorage } from "node:async_hooks";
 import util from "node:util";
 import type { Phase } from "./alchemy.ts";
@@ -99,6 +100,8 @@ export class Scope {
     new AsyncLocalStorage<Scope>());
   public static globals: Scope[] = (globalThis.__ALCHEMY_GLOBALS__ ??= []);
 
+  private static exitHandlerInstalled = false;
+
   public static getScope(): Scope | undefined {
     const scope = Scope.storage.getStore();
     if (!scope) {
@@ -144,6 +147,7 @@ export class Scope {
   private finalized = false;
   private startedAt = performance.now();
   private deferred: (() => Promise<any>)[] = [];
+  private cleanups: (() => Promise<void>)[] = [];
 
   public get appName(): string {
     if (this.parent) {
@@ -466,6 +470,7 @@ export class Scope {
     });
 
     if (!this.parent && process.env.ALCHEMY_TEST_KILL_ON_FINALIZE) {
+      await this.cleanup();
       process.exit(0);
     }
   }
@@ -537,6 +542,28 @@ export class Scope {
     return promise;
   }
 
+  /**
+   * Run all cleanup functions registered with `onCleanup`.
+   * This should only be called on the root scope.
+   */
+  public async cleanup() {
+    if (this.parent) return;
+    this.logger.log(kleur.gray("Exiting..."));
+    await Promise.allSettled(this.cleanups.map((cleanup) => cleanup()));
+  }
+
+  /**
+   * Register a cleanup function that will be called when the process exits.
+   * This should only be called on the root scope.
+   */
+  public onCleanup(fn: () => Promise<void>) {
+    if (this.parent) {
+      this.root.onCleanup(fn);
+      return;
+    }
+    this.cleanups.push(fn);
+  }
+
   /**
    * Returns a string representation of the scope.
    */