alchemy 0.68.0 → 0.69.1

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

@@ -31,10 +31,7 @@ export async function createMiniflareWorkerProxy(options: {
   });
   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);
+      const response = await handleFetch(req);
       writeMiniflareResponseToNode(response, res);
     } catch (error) {
       console.error(error);
@@ -45,20 +42,67 @@ export async function createMiniflareWorkerProxy(options: {
     }
   });
 
-  const toMiniflareRequest = (req: http.IncomingMessage): miniflare.Request => {
+  const handleFetch = async (
+    req: http.IncomingMessage,
+  ): Promise<miniflare.Response> => {
+    const { request, url } = toMiniflareRequest(req);
+    const name = options.getWorkerName(request);
+    const worker = await options.miniflare.getWorker(name);
+
+    // Handle scheduled events
+    // https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/#background
+    // https://github.com/cloudflare/workers-sdk/blob/7d53b9ab6b370944b7934ad51ebef43160c3c775/packages/wrangler/templates/middleware/middleware-scheduled.ts#L6
+    if (url.pathname === "/__scheduled") {
+      await worker.scheduled({
+        scheduledTime: new Date(),
+        cron: url.searchParams.get("cron") ?? undefined,
+      });
+      return new miniflare.Response("Ran scheduled function");
+    }
+
+    const result = await worker
+      .fetch(request)
+      .then((response) => ({ success: true, response }) as const)
+      .catch((error) => ({ success: false, error }) as const);
+
+    // If you open the `/__scheduled` page in a browser, the browser will automatically make a request to `/favicon.ico`.
+    // For scheduled Workers _without_ a fetch handler, this will result in an unhelpful error that we don't need to log.
+    // To avoid this, inject a 404 response to favicon.ico loads on the `/__scheduled` page
+    if (
+      request.headers.get("referer")?.endsWith("/__scheduled") &&
+      url.pathname === "/favicon.ico" &&
+      !result.success
+    ) {
+      return new miniflare.Response(null, { status: 404 });
+    }
+
+    if (!result.success) {
+      throw result.error;
+    }
+
+    return result.response;
+  };
+
+  const toMiniflareRequest = (
+    req: http.IncomingMessage,
+  ): { request: miniflare.Request; url: URL } => {
     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,
-    });
+    return {
+      request: new miniflare.Request(info.url, {
+        method: info.method,
+        headers: info.headers,
+        body: info.body,
+        redirect: info.redirect,
+        duplex: info.duplex,
+      }),
+      url: info.url,
+    };
   };
 
   const createServerWebSocket = async (req: http.IncomingMessage) => {
-    const name = options.getWorkerName(toMiniflareRequest(req));
+    const { request } = toMiniflareRequest(req);
+    const name = options.getWorkerName(request);
     const target = await options.miniflare.unsafeGetDirectURL(name);
     const url = new URL(req.url ?? "/", target);
     url.protocol = url.protocol.replace("http", "ws");

package/src/cloudflare/next.ts

@@ -113,7 +113,7 @@ const normalizeCommand = (
     command: string;
     env: Record<string, string>;
   },
-): WebsiteProps<any>["build"] => {
+) => {
   return {
     command:
       typeof input === "string" ? input : (input?.command ?? defaults.command),
@@ -122,5 +122,5 @@ const normalizeCommand = (
       ...(typeof input === "object" ? (input?.env ?? {}) : {}),
     },
     memoize: typeof input === "object" ? input?.memoize : undefined,
-  };
+  } satisfies WebsiteProps<any>["build"];
 };

package/src/cloudflare/nuxt/nuxt.ts

@@ -2,7 +2,12 @@ import path from "node:path";
 import { getPackageManagerRunner } from "../../util/detect-package-manager.ts";
 import type { Assets } from "../assets.ts";
 import type { Bindings } from "../bindings.ts";
-import { Website, type WebsiteProps } from "../website.ts";
+import {
+  spreadBuildProps,
+  spreadDevProps,
+  Website,
+  type WebsiteProps,
+} from "../website.ts";
 import type { Worker } from "../worker.ts";
 
 /**
@@ -55,8 +60,8 @@ export async function Nuxt<B extends Bindings>(
   return await Website(id, {
     ...props,
     noBundle: props?.noBundle ?? true,
-    build: props?.build ?? `${runner} nuxt build`,
-    dev: props?.dev ?? `${runner} nuxt dev`,
+    build: spreadBuildProps(props, `${runner} nuxt build`),
+    dev: spreadDevProps(props, `${runner} nuxt dev`),
     compatibility: "node",
     // Default entry point for cloudflare-module preset
     entrypoint: props?.entrypoint ?? "./.output/server/index.mjs",

package/src/cloudflare/tanstack-start/plugin.ts

@@ -1,30 +1,9 @@
-import type { GetPlatformProxyOptions } from "wrangler";
-import { dedent } from "../../util/dedent.ts";
+import type { PluginConfig } from "@cloudflare/vite-plugin";
+import alchemyVite from "../vite/plugin.ts";
 
-/**
- * TanStackStart server functions and middleware run in Node.js intead of Miniflare when using `vite dev`.
- *
- * This plugin polyfills the cloudflare:workers module & includes `process.env` during the dev server phase.
- *
- * @see https://developers.cloudflare.com/workers/framework-guides/web-apps/tanstack/#using-cloudflare-bindings
- */
-export default function alchemy(options: GetPlatformProxyOptions = {}) {
-  return {
-    name: "cloudflare-workers-dev-shim",
-    apply: "serve", // dev‑only
-    enforce: "pre",
-    resolveId(id: string) {
-      if (id === "cloudflare:workers") return id; // tell Vite we handled it
-    },
-    load(id: string) {
-      if (id === "cloudflare:workers") {
-        return dedent`
-          import { getCloudflareEnvProxy } from "alchemy/cloudflare";
-          export const env = await getCloudflareEnvProxy(${JSON.stringify(
-            options,
-          )});
-        `;
-      }
-    },
-  } as const;
+export default function alchemy(options: PluginConfig = {}) {
+  return alchemyVite({
+    viteEnvironment: { name: "ssr" },
+    ...options,
+  });
 }

package/src/cloudflare/tanstack-start/tanstack-start.ts

@@ -15,10 +15,21 @@ export async function TanStackStart<B extends Bindings>(
   props?: Partial<TanStackStartProps<B>>,
 ): Promise<TanStackStart<B>> {
   return await Vite(id, {
-    ...props,
+    entrypoint: "dist/server/index.js",
+    assets: "dist/client",
+    compatibility: "node",
     noBundle: true,
-    entrypoint: props?.entrypoint ?? ".output/server/index.mjs",
-    compatibilityFlags: ["nodejs_compat", ...(props?.compatibilityFlags ?? [])],
-    assets: props?.assets ?? ".output/public",
+    spa: false,
+    ...props,
+    wrangler: {
+      ...props?.wrangler,
+      transform: async (spec) => {
+        const transformed = (await props?.wrangler?.transform?.(spec)) ?? spec;
+        if (!props?.wrangler?.main) {
+          transformed.main = "@tanstack/react-start/server-entry";
+        }
+        return transformed;
+      },
+    },
   });
 }

package/src/cloudflare/vite/vite.ts

@@ -1,7 +1,12 @@
 import { getPackageManagerRunner } from "../../util/detect-package-manager.ts";
 import type { Assets } from "../assets.ts";
 import type { Bindings } from "../bindings.ts";
-import { Website, type WebsiteProps } from "../website.ts";
+import {
+  spreadBuildProps,
+  spreadDevProps,
+  Website,
+  type WebsiteProps,
+} from "../website.ts";
 import type { Worker } from "../worker.ts";
 
 export interface ViteProps<B extends Bindings> extends WebsiteProps<B> {}
@@ -27,7 +32,7 @@ export async function Vite<B extends Bindings>(
               props.assets?.directory ??
               (props.entrypoint || props.script ? "dist/client" : "dist"),
           },
-    build: props.build ?? `${runner} vite build`,
-    dev: props.dev ?? `${runner} vite dev`,
+    build: spreadBuildProps(props, `${runner} vite build`),
+    dev: spreadDevProps(props, `${runner} vite dev`),
   });
 }

package/src/cloudflare/website.ts

@@ -27,7 +27,7 @@ export interface WebsiteProps<B extends Bindings>
         /**
          * The command to run to build the site
          */
-        command: string;
+        command?: string;
         /**
          * Additional environment variables to set when running the build command
          */
@@ -287,7 +287,7 @@ export async function Website<B extends Bindings>(
 
   const scope = Scope.current;
 
-  if (build && !scope.local) {
+  if (build?.command && !scope.local) {
     await Exec(`${id}-build`, {
       cwd: path.relative(process.cwd(), paths.cwd),
       command: build.command,
@@ -334,6 +334,7 @@ export async function Website<B extends Bindings>(
         // NOTE: we must set this to ensure the user does not accidentally set `NODE_ENV=production`
         // which breaks `vite dev` (it won't, for example, re-write `process.env.TSS_APP_BASE` in the `.js` client side bundle)
         NODE_ENV: "development",
+        ALCHEMY_ROOT: Scope.current.rootDir,
       },
     });
   }
@@ -353,3 +354,29 @@ export async function Website<B extends Bindings>(
     dev: url ? { url } : undefined,
   })) as Website<B>;
 }
+
+export const spreadBuildProps = (
+  props: { build?: WebsiteProps<Bindings>["build"] } | undefined,
+  defaultCommand: string,
+): WebsiteProps<Bindings>["build"] => {
+  if (typeof props?.build === "object") {
+    return {
+      ...props.build,
+      command: props.build.command ?? defaultCommand,
+    };
+  }
+  return props?.build ?? defaultCommand;
+};
+
+export const spreadDevProps = (
+  props: { dev?: WebsiteProps<Bindings>["dev"] } | undefined,
+  defaultCommand: string,
+): WebsiteProps<Bindings>["dev"] => {
+  if (typeof props?.dev === "object") {
+    return {
+      ...props.dev,
+      command: props.dev.command ?? defaultCommand,
+    };
+  }
+  return props?.dev ?? defaultCommand;
+};

package/src/cloudflare/worker-metadata.ts

@@ -18,7 +18,7 @@ import type {
   MultiStepMigration,
   SingleStepMigration,
 } from "./worker-migration.ts";
-import type { AssetsConfig, WorkerProps } from "./worker.ts";
+import { isWorker, type AssetsConfig, type WorkerProps } from "./worker.ts";
 
 /**
  * Metadata returned by Cloudflare API for a worker script
@@ -175,6 +175,7 @@ export interface WorkerDefaultEnvironment extends WorkerEnvironment {
   script: WorkerScriptInfo;
 }
 
+//? (jacob): why is this not using BaseWorkerProps?
 export interface WorkerMetadata {
   compatibility_date: string;
   compatibility_flags?: string[];
@@ -202,6 +203,7 @@ export interface WorkerMetadata {
   limits?: {
     cpu_ms?: number;
   };
+  tail_consumers?: Array<Worker | { service: string }>;
 }
 
 export async function prepareWorkerMetadata(
@@ -316,6 +318,9 @@ export async function prepareWorkerMetadata(
   const meta: WorkerMetadata = {
     compatibility_date: props.compatibilityDate,
     compatibility_flags: props.compatibilityFlags,
+    tail_consumers: props.tailConsumers?.map((consumer) =>
+      isWorker(consumer) ? { service: consumer.name } : consumer,
+    ),
     bindings: [],
     observability: {
       enabled: props.observability?.enabled !== false,

package/src/cloudflare/worker.ts

@@ -375,6 +375,11 @@ export interface BaseWorkerProps<
      */
     cpu_ms?: number;
   };
+
+  /**
+   * Tail consumers that will receive execution logs from this worker
+   */
+  tailConsumers?: Array<Worker | { service: string }>;
 }
 
 export interface InlineWorkerProps<
@@ -1018,6 +1023,7 @@ const _Worker = Resource(
         props.crons?.map((cron) => ({ cron })) ?? [],
       );
     }
+
     await Promise.all(
       options.workflows.map((workflow) =>
         upsertWorkflow(api, {
@@ -1063,6 +1069,7 @@ const _Worker = Resource(
       url: subdomain?.url,
       assets: props.assets,
       crons: props.crons,
+      tailConsumers: props.tailConsumers,
       routes,
       domains,
       namespace: props.namespace,

package/src/cloudflare/wrangler.json.ts

@@ -11,7 +11,7 @@ import type { DurableObjectNamespace } from "./durable-object-namespace.ts";
 import type { EventSource } from "./event-source.ts";
 import { isQueueEventSource } from "./event-source.ts";
 import { isQueue } from "./queue.ts";
-import type { Worker, WorkerProps } from "./worker.ts";
+import { isWorker, type Worker, type WorkerProps } from "./worker.ts";
 
 type WranglerJsonRateLimit = Omit<WorkerBindingRateLimit, "type"> & {
   type: "rate_limit";
@@ -182,6 +182,15 @@ export async function WranglerJson(
     spec.vars = { ...worker.env };
   }
 
+  if (worker.tailConsumers && worker.tailConsumers.length > 0) {
+    spec.tail_consumers = worker.tailConsumers.map((consumer) => {
+      if (isWorker(consumer)) {
+        return { service: consumer.name };
+      }
+      return { service: consumer.service };
+    });
+  }
+
   if (worker.crons && worker.crons.length > 0) {
     spec.triggers = { crons: worker.crons };
   }
@@ -350,14 +359,7 @@ export interface WranglerJsonSpec {
    */
   queues?: {
     producers?: { queue: string; binding: string }[];
-    consumers?: {
-      queue: string;
-      max_batch_size?: number;
-      max_concurrency?: number;
-      max_retries?: number;
-      max_wait_time_ms?: number;
-      retry_delay?: number;
-    }[];
+    consumers?: QueueConsumerWranglerJson[];
   };
 
   /**
@@ -492,6 +494,11 @@ export interface WranglerJsonSpec {
     experimental_remote?: boolean;
   }[];
 
+  /**
+   * Tail consumers that will receive execution logs from this worker
+   */
+  tail_consumers?: Array<{ service: string }>;
+
   /**
    * Unsafe bindings section for experimental features
    */
@@ -500,6 +507,33 @@ export interface WranglerJsonSpec {
   };
 }
 
+/**
+ * Queue consumer bindings for wrangler.json
+ */
+interface QueueConsumerWranglerJson {
+  queue: string;
+  /**
+   * The maximum number of messages allowed in each batch.
+   */
+  max_batch_size?: number;
+  /**
+   * The maximum number of concurrent consumers allowed to run at once. Leaving this unset will mean that the number of invocations will scale to the currently supported maximum.
+   */
+  max_concurrency?: number;
+  /**
+   * The maximum number of retries for a message, if it fails or `retryAll()` is invoked.
+   */
+  max_retries?: number;
+  /**
+   * The maximum number of seconds to wait for messages to fill a batch before the batch is sent to the consumer Worker.
+   */
+  max_batch_timeout?: number;
+  /**
+   * The number of seconds to delay retried messages for by default, before they are re-delivered to the consumer. This can be overridden on a per-message or per-batch basis when retrying messages.
+   */
+  retry_delay?: number;
+}
+
 /**
  * Process worker bindings into wrangler.json format
  */
@@ -554,14 +588,7 @@ function processBindings(
   }[] = [];
   const queues: {
     producers: { queue: string; binding: string }[];
-    consumers: {
-      queue: string;
-      max_batch_size?: number;
-      max_concurrency?: number;
-      max_retries?: number;
-      max_wait_time_ms?: number;
-      retry_delay?: number;
-    }[];
+    consumers: QueueConsumerWranglerJson[];
   } = {
     producers: [],
     consumers: [],
@@ -604,7 +631,9 @@ function processBindings(
         max_batch_size: eventSource.settings?.batchSize,
         max_concurrency: eventSource.settings?.maxConcurrency,
         max_retries: eventSource.settings?.maxRetries,
-        max_wait_time_ms: eventSource.settings?.maxWaitTimeMs,
+        max_batch_timeout: eventSource.settings?.maxWaitTimeMs
+          ? eventSource.settings?.maxWaitTimeMs / 1000
+          : undefined,
         retry_delay: eventSource.settings?.retryDelay,
       });
     } else if (isQueue(eventSource)) {

package/src/docker/api.ts

@@ -3,6 +3,41 @@ import { Buffer } from "node:buffer";
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
+import type { Duration, HealthcheckConfig } from "./container.ts";
+
+/**
+ * Normalize a duration value to Docker CLI format
+ * Accepts either a number (seconds) or a string with unit suffix (ms|s|m|h)
+ * Returns a string in Docker CLI format
+ *
+ * The Duration type provides compile-time type safety, ensuring only valid
+ * formats are accepted: number or string matching the pattern `${number}${unit}`
+ *
+ * @param duration Duration value (number in seconds or string with unit)
+ * @returns Normalized duration string for Docker CLI
+ *
+ * @example
+ * normalizeDuration(30) // "30s"
+ * normalizeDuration("30s") // "30s"
+ * normalizeDuration("1m") // "1m"
+ * normalizeDuration("500ms") // "500ms"
+ * normalizeDuration("1.5s") // "1.5s"
+ */
+export function normalizeDuration(duration: Duration): string {
+  if (typeof duration === "number") {
+    return `${duration}s`;
+  }
+
+  // Validate string format: must be a number followed by unit (ms|s|m|h)
+  const match = duration.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)$/);
+  if (!match) {
+    throw new Error(
+      `Invalid duration format: "${duration}". Expected format: number followed by unit (ms|s|m|h), e.g., "30s", "1m", "500ms"`,
+    );
+  }
+
+  return duration;
+}
 
 /**
  * Options for Docker API requests
@@ -59,7 +94,10 @@ export class DockerApi {
    * @param args Command arguments to pass to Docker CLI
    * @returns Result of the command
    */
-  async exec(args: string[]): Promise<{ stdout: string; stderr: string }> {
+  async exec(
+    args: string[],
+    remainingAttempts = 3,
+  ): Promise<{ stdout: string; stderr: string }> {
     // If a custom config directory is provided, ensure all commands use it by
     // setting the DOCKER_CONFIG env variable for the spawned process.
     const env = this.configDir
@@ -94,8 +132,16 @@ export class DockerApi {
     try {
       await subprocess;
     } catch (error: any) {
+      const message = stderr || error.message || "Command failed";
+      if (
+        message.includes("unexpected status from HEAD request") &&
+        remainingAttempts > 0
+      ) {
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        return this.exec(args, remainingAttempts - 1);
+      }
       // Process failed, but we still have the output
-      throw new Error(stderr || error.message || "Command failed");
+      throw new Error(message);
     }
 
     return { stdout, stderr };
@@ -177,6 +223,7 @@ export class DockerApi {
       env?: Record<string, string>;
       volumes?: Record<string, string>;
       cmd?: string[];
+      healthcheck?: HealthcheckConfig;
     } = {},
   ): Promise<string> {
     const args = ["create", "--name", name];
@@ -202,6 +249,43 @@ export class DockerApi {
       }
     }
 
+    // Add healthcheck configuration
+    if (options.healthcheck) {
+      const hc = options.healthcheck;
+
+      // Format the cmd
+      const cmdStr = Array.isArray(hc.cmd) ? hc.cmd.join(" ") : hc.cmd;
+      args.push("--health-cmd", cmdStr);
+
+      // Add interval
+      if (hc.interval !== undefined) {
+        args.push("--health-interval", normalizeDuration(hc.interval));
+      }
+
+      // Add timeout
+      if (hc.timeout !== undefined) {
+        args.push("--health-timeout", normalizeDuration(hc.timeout));
+      }
+
+      // Add retries
+      if (hc.retries !== undefined) {
+        args.push("--health-retries", String(hc.retries));
+      }
+
+      // Add start period
+      if (hc.startPeriod !== undefined) {
+        args.push("--health-start-period", normalizeDuration(hc.startPeriod));
+      }
+
+      // Add start interval (API 1.44+)
+      if (hc.startInterval !== undefined) {
+        args.push(
+          "--health-start-interval",
+          normalizeDuration(hc.startInterval),
+        );
+      }
+    }
+
     args.push(image);
 
     // Add command if specified