alchemy 0.69.0 → 0.69.1

package/src/cloudflare/bucket.ts

@@ -1,3 +1,4 @@
+import type { R2PutOptions } from "@cloudflare/workers-types/experimental/index.ts";
 import * as mf from "miniflare";
 import { isDeepStrictEqual } from "node:util";
 import type { Context } from "../context.ts";
@@ -253,6 +254,7 @@ export type R2ObjectMetadata = {
   etag: string;
   uploaded: Date;
   size: number;
+  httpMetadata?: R2HTTPMetadata;
 };
 
 export type R2ObjectContent = R2ObjectMetadata & {
@@ -272,7 +274,7 @@ export type PutR2ObjectResponse = {
 };
 
 export type R2Objects = {
-  objects: R2ObjectMetadata[];
+  objects: Omit<R2ObjectMetadata, "httpMetadata">[];
 } & (
   | {
       truncated: true;
@@ -296,6 +298,7 @@ export type R2Bucket = _R2Bucket & {
       | string
       | null
       | Blob,
+    options?: Pick<R2PutOptions, "httpMetadata">,
   ): Promise<PutR2ObjectResponse>;
   delete(key: string): Promise<Response>;
   list(options?: R2ListOptions): Promise<R2Objects>;
@@ -449,7 +452,17 @@ export async function R2Bucket(
     ...bucket,
     head: async (key: string) => {
       if (isLocal) {
-        return (await localBucket()).head(key);
+        const result = await (await localBucket()).head(key);
+        if (result) {
+          return {
+            key: result.key,
+            etag: result.etag,
+            uploaded: result.uploaded,
+            size: result.size,
+            httpMetadata: result.httpMetadata,
+          } as R2ObjectMetadata;
+        }
+        return null;
       }
       return headObject(api, {
         bucketName: bucket.name,
@@ -489,9 +502,9 @@ export async function R2Bucket(
     put: async (
       key: string,
       value: PutObjectObject,
+      options?: Pick<R2PutOptions, "httpMetadata">,
     ): Promise<PutR2ObjectResponse> => {
       if (isLocal) {
-        // @ts-expect-error - node built-ins vs cloudflare built-ins
         return await (await localBucket()).put(
           key,
           typeof value === "string"
@@ -505,12 +518,14 @@ export async function R2Bucket(
                 : value instanceof ReadableStream
                   ? new Uint8Array(await streamToBuffer(value))
                   : value,
+          options,
         );
       }
       const response = await putObject(api, {
         bucketName: bucket.name,
         key: key,
         object: value,
+        options: options,
       });
       const body = (await response.json()) as {
         result: {
@@ -546,6 +561,7 @@ const parseR2Object = (key: string, response: Response): R2ObjectContent => ({
   uploaded: parseDate(response.headers),
   key,
   size: Number(response.headers.get("Content-Length")),
+  httpMetadata: mapHeadersToHttpMetadata(response.headers),
   arrayBuffer: () => response.arrayBuffer(),
   bytes: () => response.bytes(),
   text: () => response.text(),
@@ -1155,6 +1171,7 @@ export async function headObject(
     etag: response.headers.get("ETag")?.replace(/"/g, "")!,
     uploaded: parseDate(response.headers),
     size: Number(response.headers.get("Content-Length")),
+    httpMetadata: mapHeadersToHttpMetadata(response.headers),
   };
 }
 
@@ -1192,27 +1209,76 @@ export type PutObjectObject =
   | Buffer
   | Blob;
 
+function mapHttpMetadataToHeaders(
+  httpMetadata: R2PutOptions["httpMetadata"],
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+
+  if (httpMetadata instanceof Headers) {
+    httpMetadata.forEach((value, key) => {
+      headers[key] = value;
+    });
+  } else {
+    const {
+      contentType,
+      contentLanguage,
+      contentDisposition,
+      contentEncoding,
+      cacheControl,
+      cacheExpiry,
+    } = httpMetadata as R2HTTPMetadata;
+    if (contentType) headers["Content-Type"] = contentType;
+    if (contentLanguage) headers["Content-Language"] = contentLanguage;
+    if (contentDisposition) headers["Content-Disposition"] = contentDisposition;
+    if (contentEncoding) headers["Content-Encoding"] = contentEncoding;
+    if (cacheControl) headers["Cache-Control"] = cacheControl;
+    if (cacheExpiry) headers.Expires = cacheExpiry.toUTCString();
+  }
+
+  return headers;
+}
+
+function mapHeadersToHttpMetadata(headers: Headers): R2HTTPMetadata {
+  return {
+    contentType: headers.get("Content-Type") ?? undefined,
+    contentLanguage: headers.get("Content-Language") ?? undefined,
+    contentDisposition: headers.get("Content-Disposition") ?? undefined,
+    contentEncoding: headers.get("Content-Encoding") ?? undefined,
+    cacheControl: headers.get("Cache-Control") ?? undefined,
+    cacheExpiry: headers.get("Expires")
+      ? new Date(headers.get("Expires")!)
+      : undefined,
+  };
+}
+
 export async function putObject(
   api: CloudflareApi,
   {
     bucketName,
     key,
     object,
+    options,
   }: {
     bucketName: string;
     key: string;
     object: PutObjectObject;
+    options?: Pick<R2PutOptions, "httpMetadata">;
   },
 ): Promise<Response> {
   // Using withExponentialBackoff for reliability
   return await withRetries(async () => {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/octet-stream",
+      ...(options?.httpMetadata
+        ? mapHttpMetadataToHeaders(options?.httpMetadata)
+        : {}),
+    };
+
     const response = await api.put(
       `/accounts/${api.accountId}/r2/buckets/${bucketName}/objects/${key}`,
       object,
       {
-        headers: {
-          "Content-Type": "application/octet-stream",
-        },
+        headers,
       },
     );
     if (!response.ok) {

package/src/cloudflare/container.ts

@@ -1044,13 +1044,13 @@ export async function createContainerApplicationRollout(
   );
   const result = (await response.json()) as {
     result: CreateRolloutApplicationResponse;
-    errors: { message: string }[];
+    errors: { message: string; code: number }[];
   };
   if (response.ok) {
     return result.result;
   }
   throw Error(
-    `Failed to create container application rollout: ${result.errors.map((e: { message: string }) => e.message).join(", ")}`,
+    `Failed to create container application rollout: ${result.errors.map((e) => `[${e.code}] ${e.message}`).join(", ")}`,
   );
 }
 

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

@@ -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,
       },
     });
   }

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 };
   }
@@ -485,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
    */

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

package/src/docker/container.ts

@@ -59,6 +59,62 @@ export interface NetworkMapping {
   aliases?: string[];
 }
 
+/**
+ * Duration value supporting both number (seconds) and string format (value + unit)
+ * Units: ms (milliseconds), s (seconds), m (minutes), h (hours)
+ * Examples: 30, "30s", "1m", "500ms", "2h"
+ */
+export type Duration = number | `${number}${"ms" | "s" | "m" | "h"}`;
+
+/**
+ * Healthcheck configuration
+ */
+export interface HealthcheckConfig {
+  /**
+   * Command to run to check health.
+   * Can be an array of command arguments or a shell command string.
+   * Examples:
+   * - ["curl", "-f", "http://localhost/"]
+   * - "curl -f http://localhost/ || exit 1"
+   */
+  cmd: string[] | string;
+
+  /**
+   * Time between running the check
+   * Can be a number (in seconds) or string with unit (e.g., "30s", "1m")
+   * @default 0
+   */
+  interval?: Duration;
+
+  /**
+   * Maximum time to allow one check to run
+   * Can be a number (in seconds) or string with unit (e.g., "10s", "500ms")
+   * @default 0
+   */
+  timeout?: Duration;
+
+  /**
+   * Consecutive failures needed to report unhealthy
+   */
+  retries?: number;
+
+  /**
+   * Start period for the container to initialize before starting
+   * health-retries countdown
+   * Can be a number (in seconds) or string with unit (e.g., "40s", "1m")
+   * @default 0
+   */
+  startPeriod?: Duration;
+
+  /**
+   * Time between running the check during the start period
+   * Can be a number (in seconds) or string with unit (e.g., "5s", "500ms")
+   * Requires Docker API 1.44+
+   * @default 0
+   */
+  startInterval?: Duration;
+}
+
 /**
  * Properties for creating a Docker container
  */
@@ -115,6 +171,11 @@ export interface ContainerProps {
    * Start the container after creation
    */
   start?: boolean;
+
+  /**
+   * Healthcheck configuration
+   */
+  healthcheck?: HealthcheckConfig;
 }
 
 /**
@@ -172,6 +233,41 @@ export interface Container extends ContainerProps {
  *   restart: "always",
  *   start: true
  * });
+ *
+ * @example
+ * // Create a container with healthcheck using numeric values (seconds)
+ * const healthyContainer = await Container("api", {
+ *   image: "my-api:latest",
+ *   ports: [
+ *     { external: 3000, internal: 3000 }
+ *   ],
+ *   healthcheck: {
+ *     cmd: ["curl", "-f", "http://localhost:3000/health"],
+ *     interval: 30,
+ *     timeout: 10,
+ *     retries: 3,
+ *     startPeriod: 40
+ *   },
+ *   start: true
+ * });
+ *
+ * @example
+ * // Create a container with healthcheck using string duration format
+ * const healthyContainer2 = await Container("api2", {
+ *   image: "my-api:latest",
+ *   ports: [
+ *     { external: 3001, internal: 3000 }
+ *   ],
+ *   healthcheck: {
+ *     cmd: ["curl", "-f", "http://localhost:3000/health"],
+ *     interval: "30s",
+ *     timeout: "10s",
+ *     retries: 3,
+ *     startPeriod: "1m",
+ *     startInterval: "500ms"
+ *   },
+ *   start: true
+ * });
  */
 export const Container = Resource(
   "docker::Container",
@@ -245,6 +341,7 @@ export const Container = Resource(
         env: props.environment,
         volumes: volumeMappings,
         cmd: props.command,
+        healthcheck: props.healthcheck,
       });
 
       // Connect to networks if specified