alchemy 2.0.0-beta.65 → 2.0.0-beta.67

package/src/Cloudflare/Auth/OAuthClient.ts

@@ -6,6 +6,7 @@ import { AUTH_ERROR_URL, AUTH_SUCCESS_URL } from "../../Auth/AuthProvider.ts";
 import {
   OAUTH_CLIENT_ID,
   OAUTH_ENDPOINTS,
+  OAUTH_LOCAL_CALLBACK_URI,
   OAUTH_REDIRECT_URI,
 } from "./AuthProvider.ts";
 
@@ -187,6 +188,46 @@ export const revoke = (
     });
   });
 
+/**
+ * Exchange a code copied from the hosted relay page, or extract the code from
+ * either the hosted or loopback callback URL.
+ */
+export const exchangeCallbackInput = (
+  input: string,
+  authorization: Authorization,
+): Effect.Effect<OAuthCredentials, OAuthError> =>
+  Effect.gen(function* () {
+    const value = input.trim();
+    let code = value;
+    let state: string | null = null;
+
+    try {
+      const url = new URL(value);
+      code = url.searchParams.get("code") ?? "";
+      state = url.searchParams.get("state");
+    } catch {
+      const separator = value.lastIndexOf("#");
+      if (separator >= 0) {
+        code = value.slice(0, separator);
+        state = value.slice(separator + 1);
+      }
+    }
+
+    if (!code) {
+      return yield* new OAuthError({
+        error: "invalid_request",
+        errorDescription: "The authorization code is missing.",
+      });
+    }
+    if (state !== null && state !== authorization.state) {
+      return yield* new OAuthError({
+        error: "invalid_request",
+        errorDescription: "The authorization state does not match.",
+      });
+    }
+    return yield* exchange(code, authorization.verifier);
+  });
+
 /**
  * Start a local HTTP server to listen for the OAuth callback, exchange
  * the authorization code, and return the credentials.
@@ -197,7 +238,7 @@ export const callback = (
   authorization: Authorization,
 ): Effect.Effect<OAuthCredentials, OAuthError> =>
   Effect.tryPromise({
-    try: () => callbackPromise(authorization),
+    try: (signal) => callbackPromise(authorization, signal),
     catch: (err) => {
       if (err instanceof OAuthError) return err;
       return new OAuthError({
@@ -209,13 +250,25 @@ export const callback = (
 
 function callbackPromise(
   authorization: Authorization,
+  signal: AbortSignal,
 ): Promise<OAuthCredentials> {
-  const { pathname, port } = new URL(OAUTH_REDIRECT_URI);
+  const { pathname, port } = new URL(OAUTH_LOCAL_CALLBACK_URI);
 
   return new Promise<OAuthCredentials>((resolve, reject) => {
     const server = http.createServer(async (req, res) => {
       const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
 
+      if (url.pathname === "/auth/ping") {
+        res.writeHead(req.method === "OPTIONS" ? 204 : 200, {
+          "Access-Control-Allow-Origin": new URL(OAUTH_REDIRECT_URI).origin,
+          "Access-Control-Allow-Methods": "GET, OPTIONS",
+          "Access-Control-Allow-Private-Network": "true",
+          "Cache-Control": "no-store",
+        });
+        res.end();
+        return;
+      }
+
       if (url.pathname !== pathname) {
         res.statusCode = 404;
         res.end("Not Found");
@@ -296,9 +349,12 @@ function callbackPromise(
 
     function cleanup() {
       clearTimeout(timeout);
+      signal.removeEventListener("abort", cleanup);
       server.close();
     }
 
+    signal.addEventListener("abort", cleanup, { once: true });
+
     server.on("error", (err) => {
       cleanup();
       reject(

package/src/Cloudflare/Containers/Container.ts

@@ -189,6 +189,66 @@ export type Container<Id extends string = string> = Named<Id> & {
  * );
  * ```
  *
+ * @section Async Workers
+ * An async Worker can host a container-backed Durable Object class that
+ * ships as plain JavaScript — `@cloudflare/sandbox`'s `Sandbox`, or your
+ * own class extending `@cloudflare/containers`' `Container`. The class
+ * lives in the worker script; `Container` (the npm one) handles the
+ * lifecycle and forwards `fetch` to the port inside the container.
+ *
+ * @example The worker script exports the container-backed class
+ * ```typescript
+ * // src/worker.ts
+ * import { Container } from "@cloudflare/containers";
+ *
+ * export class Sandbox extends Container {
+ *   defaultPort = 8080;
+ * }
+ * ```
+ *
+ * Declare it in the stack by binding a `Cloudflare.Container` in the
+ * Worker's `env` — the Container **is** the Durable Object binding and its
+ * ContainerApplication together. Alchemy emits the
+ * `durable_object_namespace` binding, marks the class as container-backed
+ * in the script metadata, provisions the ContainerApplication, and attaches
+ * it to the class's namespace. The Durable Object class name defaults to
+ * the binding name (the `env` key); set `className` when the exported class
+ * is named differently.
+ *
+ * @example Binding the container-backed class in the stack
+ * ```typescript
+ * // alchemy.run.ts
+ * import type { Sandbox } from "./src/worker.ts";
+ *
+ * export const Worker = Cloudflare.Worker("Worker", {
+ *   main: "./src/worker.ts",
+ *   env: {
+ *     Sandbox: Cloudflare.Container<Sandbox>("Sandbox", {
+ *       image: "docker.io/cloudflare/sandbox:0.1.3",
+ *     }),
+ *   },
+ * });
+ * ```
+ *
+ * The type parameter (`Container<Sandbox>`) is the class from `worker.ts` —
+ * it types `env.Sandbox` as `DurableObjectNamespace<Sandbox>` via
+ * `Cloudflare.InferEnv`, so the handler reaches the container with full
+ * types.
+ *
+ * @example Reaching the container from the async handler
+ * ```typescript
+ * // src/worker.ts
+ * import { getContainer } from "@cloudflare/containers";
+ * import type * as Cloudflare from "alchemy/Cloudflare";
+ * import type { Worker } from "../alchemy.run.ts";
+ *
+ * export default {
+ *   async fetch(request: Request, env: Cloudflare.InferEnv<typeof Worker>) {
+ *     return getContainer(env.Sandbox, "default").fetch(request);
+ *   },
+ * };
+ * ```
+ *
  * @section Image Sources
  * A container's image comes from one of three sources, picked by which
  * prop you set:
@@ -370,12 +430,12 @@ export type Container<Id extends string = string> = Named<Id> & {
  * ```
  */
 export const Container: ResourceClassLike<ContainerApplication> & {
-  <const Id extends string>(
+  <DOShape = unknown, const Id extends string = string>(
     id: Id,
     props:
       | InputProps<ExternalContainerProps>
       | InputProps<RemoteContainerProps>,
-  ): Container.Decl<Container<Id>, {}, Id>;
+  ): Container.Decl<Container<Id>, {}, Id, never, DOShape>;
   <Self>(): {
     <
       const Id extends string,
@@ -404,6 +464,11 @@ export const Container: ResourceClassLike<ContainerApplication> & {
           // registers the DO + Worker bindings and produces the runtime
           // handle) is stashed so `startContainer` can run it from inside that
           // layer — see ContainerPlatform.bind / StartContainer.ts.
+          // NOTE: no `~alchemy/Container/ClassName` marker here — an
+          // effectful (`main`) container is not bindable on an async
+          // Worker's `env` (its application is created by the `.make()`
+          // Layer inside an Effect-native Durable Object host), so it must
+          // not be picked up by bindWorkerAsyncBindings' container branch.
           return Object.assign(effectClass(ContainerTag(id)), {
             "~alchemy/Id": id,
             "~alchemy/Container/Binding": ContainerPlatform.bind(tag),
@@ -422,6 +487,11 @@ export const Container: ResourceClassLike<ContainerApplication> & {
       return Object.assign(effectClass(ContainerTag(id)), {
         "~alchemy/Id": id,
         "~alchemy/Container/Binding": ContainerPlatform.bind(resource),
+        // The Durable Object class name this container backs when bound on
+        // an async Worker's `env` (see bindWorkerAsyncBindings). Defaults to
+        // the binding name at bind time when no explicit `className` is set.
+        "~alchemy/Container/ClassName": (props as { className?: string })
+          ?.className,
         // yield* MyContainer.Application to get the ContainerApplication Resource Outputs
         Application: resource,
         of: (shape: any) => shape,
@@ -439,9 +509,28 @@ export declare namespace Container {
     Shape = any,
     Id extends string = string,
     Req = never,
+    DOShape = unknown,
   >
     extends Effect.Effect<Self, never, Providers | Req>, Rpc<Shape>, Named<Id> {
     new (): Container<Id> & Shape;
+    /**
+     * @internal phantom — the Durable Object class type backing this
+     * container when it is bound on an async Worker's `env`. Drives
+     * `InferEnv` (`env.NAME` becomes `DurableObjectNamespace<DOShape>`).
+     */
+    readonly "~alchemy/Container/Shape": DOShape;
+    /**
+     * @internal — the explicit `className` from props (`undefined` defaults
+     * to the binding name at bind time). Doubles as the runtime marker that
+     * identifies an async-bindable Container declaration in a Worker's `env`
+     * (see `bindWorkerAsyncBindings`).
+     */
+    readonly "~alchemy/Container/ClassName": string | undefined;
+    /**
+     * The underlying {@link ContainerApplication} resource declaration —
+     * `yield*` it to get the application's Output attributes.
+     */
+    Application: Effect.Effect<ContainerApplication<Self>, never, Providers>;
     make: <InitReq = never, WorkerReq = never, PropsReq = never>(
       props:
         | InputProps<EffectfulContainerProps>
@@ -459,7 +548,7 @@ export declare namespace Container {
     of(shape: Shape & WorkerShape): Shape;
   }
   export namespace Decl {
-    export type Any = Decl<any, any, string, any>;
+    export type Any = Decl<any, any, string, any, any>;
   }
 
   export interface Application<Self> {

package/src/Cloudflare/Containers/ContainerApplication.ts

@@ -78,6 +78,13 @@ export interface ContainerApplicationPropsBase extends PlatformProps {
    * physical name from the stack, stage, and logical ID.
    */
   name?: string;
+  /**
+   * Name of the exported Durable Object class this container backs when the
+   * Container is bound on an **async** Worker's `env`. Defaults to the
+   * binding name (the `env` key). Ignored by the Effect-native path, where
+   * the class name comes from the hosting Durable Object.
+   */
+  className?: string;
   /**
    * Initial number of instances to maintain. Matches wrangler, which forces
    * this to 0 whenever {@link maxInstances} is set (pure scale-from-zero).
@@ -286,6 +293,12 @@ export interface RemoteContainerProps extends ContainerApplicationPropsBase {
    * The pre-built image to pull and re-push.
    *
    * E.g. `ghcr.io/alpine/alpine:latest`
+   *
+   * When the reference already points at the target registry (the
+   * {@link ContainerApplicationPropsBase.registryId | registryId} host,
+   * `registry.cloudflare.com` by default) — e.g. a digest reference pushed
+   * by CI like `registry.cloudflare.com/<accountId>/app@sha256:...` — it is
+   * deployed as-is and the docker pull/push round-trip is skipped entirely.
    */
   image: string;
 }
@@ -600,7 +613,15 @@ export type ContainerShape = Main<ContainerServices>;
  *
  * A `rolling` strategy with `stepPercentage: 25` replaces instances in 25%
  * increments so the application stays available during the update; the default
- * `immediate` strategy swaps everything at once.
+ * `immediate` strategy swaps everything at once. Steps advance automatically
+ * as new instances become healthy; each replaced instance receives `SIGTERM`
+ * and has 15 minutes to shut down cleanly before `SIGKILL`.
+ *
+ * Rollouts replace instances — they do not split requests between two image
+ * versions (request-level traffic splitting exists one layer up, on the
+ * Worker, via `version.traffic`). The fronting Worker and Durable Object cut
+ * over immediately while instances roll, so keep the Worker-to-container
+ * protocol compatible across both image versions until a rollout completes.
  */
 export interface ContainerApplication<Shape = unknown> extends Resource<
   ContainerTypeId,
@@ -715,7 +736,12 @@ export declare namespace DevContainerImage {
 }
 
 export const ContainerProvider = () =>
-  ProviderLayer.select({
-    live: () => LiveContainerProvider(),
-    local: () => LocalContainerProvider(),
-  });
+  // `{ Type }` instead of `ContainerPlatform` — importing the platform here
+  // would create a module cycle (ContainerPlatform.ts imports this file).
+  ProviderLayer.dual(
+    { Type: ContainerTypeId },
+    {
+      live: () => LiveContainerProvider(),
+      local: () => LocalContainerProvider(),
+    },
+  );

package/src/Cloudflare/Containers/ContainerBundle.ts

@@ -338,6 +338,7 @@ const HttpServer = NodeHttpServer;
 }
 import { Stack } from "alchemy/Stack";
 import { makeEntrypointLayer, reifyBoundConfigProvider } from "alchemy/Runtime";
+import { provideProcessTelemetry } from "alchemy/Telemetry";
 import { CloudflareEnvironment } from "alchemy/Cloudflare";
 import * as ConfigProvider from "effect/ConfigProvider";
 import * as Effect from "effect/Effect";
@@ -367,8 +368,15 @@ const stack = Layer.succeed(Stack, {
 });
 
 const serverEffect = tag.pipe(
-  Effect.flatMap(func => func.RuntimeContext.exports),
-  Effect.flatMap(exports => exports.default),
+  // Process-lifetime telemetry: built once into the root scope; exporters
+  // batch on their intervals and flush when the scope closes on graceful
+  // shutdown.
+  Effect.flatMap((func) =>
+    func.RuntimeContext.exports.pipe(
+      Effect.flatMap((exports) => exports.default),
+      provideProcessTelemetry(func.RuntimeContext),
+    ),
+  ),
   Effect.provide(
     layer.pipe(
       Layer.provideMerge(stack),

package/src/Cloudflare/Containers/ContainerProvider.ts

@@ -40,6 +40,8 @@ import { ContainerPlatform } from "./ContainerPlatform.ts";
  * - `effectful` — bundle an Effect-native `main` and build a generated image.
  * - `external` — build a user-supplied Dockerfile against a context directory.
  * - `remote` — pull a pre-built remote image and re-push it to Cloudflare.
+ * - `prepushed` — the image already lives in the target registry; use the
+ *   reference as-is with no docker pull/build/push at all.
  */
 type ImageBuild =
   | {
@@ -54,8 +56,40 @@ type ImageBuild =
   | {
       readonly kind: "remote";
       readonly image: string;
+    }
+  | {
+      readonly kind: "prepushed";
+      readonly image: string;
     };
 
+/**
+ * Whether an image reference already points at the target registry host —
+ * e.g. `registry.cloudflare.com/<accountId>/repo@sha256:...` pushed by CI.
+ * Such references are deployed as-is; there is nothing to pull or push.
+ */
+const isTargetRegistryRef = (image: string, registryId: string) =>
+  image.startsWith(`${registryId}/`);
+
+/**
+ * Insert the account namespace into a Cloudflare-registry reference that
+ * omits it (`registry.cloudflare.com/app:tag` →
+ * `registry.cloudflare.com/<accountId>/app:tag`), mirroring wrangler's
+ * `resolveImageName`. Custom registries are left untouched — the account
+ * namespace rule is specific to Cloudflare's managed registry.
+ */
+const normalizePrepushedRef = (
+  image: string,
+  registryId: string,
+  accountId: string,
+) => {
+  if (registryId !== "registry.cloudflare.com") return image;
+  const rest = image.slice(registryId.length + 1);
+  const first = rest.split("/")[0];
+  return first !== undefined && /^[a-f0-9]{32}$/.test(first)
+    ? image
+    : `${registryId}/${accountId}/${rest}`;
+};
+
 export const LiveContainerProvider = () =>
   Provider.effect(
     ContainerPlatform,
@@ -233,6 +267,25 @@ export const LiveContainerProvider = () =>
           const imageHash = (yield* sha256Object({
             image: props.image,
           })).slice(0, 16);
+          // Already in the target registry (e.g. pushed by CI as a digest
+          // reference) — deploy the reference as-is and skip the docker
+          // pull/tag/push round-trip entirely.
+          if (isTargetRegistryRef(props.image, registryId)) {
+            const prepushedRef = normalizePrepushedRef(
+              props.image,
+              registryId,
+              accountId,
+            );
+            return {
+              build: { kind: "prepushed" as const, image: prepushedRef },
+              imageRef: prepushedRef,
+              imageHash,
+              // The local runtime pulls this image directly (no build
+              // context); pulling from the Cloudflare registry requires a
+              // local `docker login`.
+              dev: { imageUri: prepushedRef, env },
+            };
+          }
           return {
             build: { kind: "remote" as const, image: props.image },
             imageRef: makeRef(imageHash),
@@ -311,6 +364,15 @@ export const LiveContainerProvider = () =>
         const { accountId } = yield* yield* CloudflareEnvironment;
         const platform = "linux/amd64";
 
+        if (build.kind === "prepushed") {
+          // The reference already lives in the target registry — nothing to
+          // pull, build, or push.
+          yield* Effect.logInfo(
+            `Cloudflare Container image: using pre-pushed ${imageRef}`,
+          );
+          return;
+        }
+
         if (build.kind === "remote") {
           // Pull the pre-built image and re-tag it to the Cloudflare registry
           // reference; nothing is built locally.

package/src/Cloudflare/Credentials.ts

@@ -3,6 +3,7 @@ import {
   apiTokenCredentials,
   Credentials,
   oauthCredentials,
+  type ResolvedCredentials,
 } from "@distilled.cloud/cloudflare/Credentials";
 import { ConfigError } from "@distilled.cloud/core/errors";
 import * as Config from "effect/Config";
@@ -10,6 +11,7 @@ import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Match from "effect/Match";
 import * as Redacted from "effect/Redacted";
+import * as Semaphore from "effect/Semaphore";
 import { getAuthProvider } from "../Auth/AuthProvider.ts";
 import { ALCHEMY_PROFILE, AlchemyProfile } from "../Auth/Profile.ts";
 import {
@@ -26,6 +28,66 @@ declare module "@distilled.cloud/cloudflare/Credentials" {
   }
 }
 
+/**
+ * Refresh OAuth credentials this long before they actually expire so that
+ * in-flight requests never race the expiry deadline.
+ */
+const CREDENTIAL_REFRESH_WINDOW_MS = 5 * 60 * 1000;
+
+const getRefreshAt = (
+  credentials: ResolvedCredentials,
+  now: number,
+): number => {
+  if (credentials.type !== "oauth" || credentials.expiresAt === undefined) {
+    return Number.POSITIVE_INFINITY;
+  }
+  return credentials.expiresAt <= now + CREDENTIAL_REFRESH_WINDOW_MS
+    ? credentials.expiresAt
+    : credentials.expiresAt - CREDENTIAL_REFRESH_WINDOW_MS;
+};
+
+/**
+ * Memoize a credentials-resolution effect until shortly before the resolved
+ * credentials expire.
+ *
+ * The distilled HTTP client resolves the `Credentials` service's effect on
+ * *every* request (`yield* config.credentials`), which is what allows OAuth
+ * tokens to rotate mid-process — a dev session can outlive the ~1h access
+ * token, so caching the first resolution forever leaves the process making
+ * API calls with a dead token until restart. At the same time, resolution
+ * acquires a cross-process file lock (`auth.read`), so resolving fresh on
+ * every request would stampede that lock under high concurrency (e.g.
+ * `unsafe nuke`).
+ *
+ * This cache serves both needs: callers get the cached credentials while
+ * they are still valid, the resolver re-runs (refreshing + persisting the
+ * token) once the refresh window is reached, and a mutex makes resolution
+ * single-flight so concurrent callers share one lock acquisition.
+ */
+export const cacheUntilExpiry = <E>(
+  resolve: Effect.Effect<ResolvedCredentials, E>,
+  now: () => number = () => Date.now(),
+): Effect.Effect<ResolvedCredentials, E> => {
+  const mutex = Semaphore.makeUnsafe(1);
+  let cached:
+    | { credentials: ResolvedCredentials; refreshAt: number }
+    | undefined;
+  return Semaphore.withPermits(
+    mutex,
+    1,
+  )(
+    Effect.suspend(() => {
+      if (cached && now() < cached.refreshAt) {
+        return Effect.succeed(cached.credentials);
+      }
+      return Effect.map(resolve, (credentials) => {
+        cached = { credentials, refreshAt: getRefreshAt(credentials, now()) };
+        return credentials;
+      });
+    }),
+  );
+};
+
 /**
  * Build a `Credentials` layer that resolves Cloudflare credentials via the
  * Alchemy AuthProvider using the configured profile (defaults to "default",
@@ -43,14 +105,7 @@ export const fromAuthProvider = () =>
       const profileName = yield* ALCHEMY_PROFILE;
       const ci = yield* Config.boolean("CI").pipe(Config.withDefault(false));
 
-      // The distilled HTTP client resolves this service's effect on *every*
-      // request (`yield* config.credentials`). `auth.read` is wrapped in a
-      // cross-process file lock, so without memoization a high-concurrency
-      // run (e.g. `unsafe nuke`) stampedes a single lock and the tail waiters
-      // blow the retry budget with "Lock file is already being held". Cache
-      // the resolution so the lock is acquired once per process, mirroring
-      // `CloudflareEnvironment.fromProfile`.
-      return yield* profile.loadOrConfigure(auth, profileName, { ci }).pipe(
+      const resolve = profile.loadOrConfigure(auth, profileName, { ci }).pipe(
         Effect.flatMap((config) =>
           auth.read(profileName, config as CloudflareAuthConfig),
         ),
@@ -82,7 +137,12 @@ export const fromAuthProvider = () =>
               message: `Failed to resolve Cloudflare credentials for profile '${profileName}': ${(e as { message?: string }).message ?? String(e)}`,
             }),
         ),
-        Effect.cached,
       );
+
+      // `auth.read` refreshes and persists expired OAuth tokens when it is
+      // re-run, so expiry-aware caching (instead of caching the first
+      // resolution forever) is what keeps long-lived dev sessions
+      // authenticated across the ~1h access-token lifetime.
+      return cacheUntilExpiry(resolve);
     }),
   );