alchemy 2.0.0-beta.2 → 2.0.0-beta.4

package/src/Cloudflare/Auth/OAuthClient.ts

@@ -0,0 +1,315 @@
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import crypto from "node:crypto";
+import http from "node:http";
+import {
+  OAUTH_CLIENT_ID,
+  OAUTH_ENDPOINTS,
+  OAUTH_REDIRECT_URI,
+} from "./AuthProvider.ts";
+
+export class OAuthError extends Data.TaggedError("OAuthError")<{
+  error: string;
+  errorDescription: string;
+}> {}
+
+export interface OAuthCredentials {
+  type: "oauth";
+  access: string;
+  refresh: string;
+  expires: number;
+  scopes: string[];
+}
+
+export interface Authorization {
+  url: string;
+  state: string;
+  verifier: string;
+}
+
+function generateState(length = 32): string {
+  return crypto.randomBytes(length).toString("base64url");
+}
+
+function generatePKCE(length = 96): {
+  verifier: string;
+  challenge: string;
+} {
+  const verifier = crypto.randomBytes(length).toString("base64url");
+  const challenge = crypto
+    .createHash("sha256")
+    .update(verifier)
+    .digest("base64url");
+  return { verifier, challenge };
+}
+
+function extractCredentials(json: {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  scope: string;
+}): OAuthCredentials {
+  return {
+    type: "oauth",
+    access: json.access_token,
+    refresh: json.refresh_token,
+    expires: Date.now() + json.expires_in * 1000,
+    scopes: json.scope.split(" "),
+  };
+}
+
+const tokenRequest = (
+  body: Record<string, string>,
+): Effect.Effect<OAuthCredentials, OAuthError> =>
+  Effect.gen(function* () {
+    const res = yield* Effect.tryPromise({
+      try: () =>
+        fetch(OAUTH_ENDPOINTS.token, {
+          method: "POST",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+          },
+          body: new URLSearchParams(body).toString(),
+        }),
+      catch: (err) =>
+        new OAuthError({
+          error: "network_error",
+          errorDescription: `Token request failed: ${err}`,
+        }),
+    });
+
+    if (!res.ok) {
+      const json = yield* Effect.tryPromise({
+        try: () =>
+          res.json() as Promise<{ error: string; error_description: string }>,
+        catch: () =>
+          new OAuthError({
+            error: "parse_error",
+            errorDescription: `Token endpoint returned ${res.status}`,
+          }),
+      });
+      return yield* new OAuthError({
+        error: json.error,
+        errorDescription: json.error_description,
+      });
+    }
+
+    const json = yield* Effect.tryPromise({
+      try: () =>
+        res.json() as Promise<{
+          access_token: string;
+          refresh_token: string;
+          expires_in: number;
+          scope: string;
+        }>,
+      catch: () =>
+        new OAuthError({
+          error: "parse_error",
+          errorDescription: "Failed to parse token response",
+        }),
+    });
+    return extractCredentials(json);
+  });
+
+/**
+ * Generate an authorization URL with PKCE for the given scopes.
+ */
+export function authorize(scopes: string[]): Authorization {
+  const state = generateState();
+  const pkce = generatePKCE();
+  const url = new URL(OAUTH_ENDPOINTS.authorize);
+  url.searchParams.set("client_id", OAUTH_CLIENT_ID);
+  url.searchParams.set("redirect_uri", OAUTH_REDIRECT_URI);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", scopes.join(" "));
+  url.searchParams.set("state", state);
+  url.searchParams.set("code_challenge", pkce.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  return { url: url.toString(), state, verifier: pkce.verifier };
+}
+
+/**
+ * Exchange an authorization code for OAuth credentials.
+ */
+export const exchange = (
+  code: string,
+  verifier: string,
+): Effect.Effect<OAuthCredentials, OAuthError> =>
+  tokenRequest({
+    grant_type: "authorization_code",
+    code,
+    code_verifier: verifier,
+    client_id: OAUTH_CLIENT_ID,
+    redirect_uri: OAUTH_REDIRECT_URI,
+  });
+
+/**
+ * Refresh expired OAuth credentials.
+ */
+export const refresh = (
+  credentials: OAuthCredentials,
+): Effect.Effect<OAuthCredentials, OAuthError> =>
+  tokenRequest({
+    grant_type: "refresh_token",
+    refresh_token: credentials.refresh,
+    client_id: OAUTH_CLIENT_ID,
+    redirect_uri: OAUTH_REDIRECT_URI,
+  });
+
+/**
+ * Revoke OAuth credentials.
+ */
+export const revoke = (
+  credentials: OAuthCredentials,
+): Effect.Effect<void, OAuthError> =>
+  Effect.gen(function* () {
+    yield* Effect.tryPromise({
+      try: () =>
+        fetch(OAUTH_ENDPOINTS.revoke, {
+          method: "POST",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/x-www-form-urlencoded",
+          },
+          body: new URLSearchParams({
+            refresh_token: credentials.refresh,
+            client_id: OAUTH_CLIENT_ID,
+            redirect_uri: OAUTH_REDIRECT_URI,
+          }).toString(),
+        }),
+      catch: (err) =>
+        new OAuthError({
+          error: "network_error",
+          errorDescription: `Revoke request failed: ${err}`,
+        }),
+    });
+  });
+
+/**
+ * Start a local HTTP server to listen for the OAuth callback, exchange
+ * the authorization code, and return the credentials.
+ *
+ * Times out after 5 minutes.
+ */
+export const callback = (
+  authorization: Authorization,
+): Effect.Effect<OAuthCredentials, OAuthError> =>
+  Effect.tryPromise({
+    try: () => callbackPromise(authorization),
+    catch: (err) => {
+      if (err instanceof OAuthError) return err;
+      return new OAuthError({
+        error: "callback_error",
+        errorDescription: `OAuth callback failed: ${err}`,
+      });
+    },
+  });
+
+function callbackPromise(
+  authorization: Authorization,
+): Promise<OAuthCredentials> {
+  const { pathname, port } = new URL(OAUTH_REDIRECT_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 !== pathname) {
+        res.statusCode = 404;
+        res.end("Not Found");
+        return;
+      }
+
+      const error = url.searchParams.get("error");
+      const errorDescription = url.searchParams.get("error_description");
+      if (error) {
+        res.writeHead(302, { Location: "https://alchemy.run/auth/error" });
+        res.end();
+        cleanup();
+        reject(
+          new OAuthError({
+            error,
+            errorDescription: errorDescription ?? "An unknown error occurred.",
+          }),
+        );
+        return;
+      }
+
+      const code = url.searchParams.get("code");
+      const state = url.searchParams.get("state");
+      if (!code || !state) {
+        res.writeHead(302, { Location: "https://alchemy.run/auth/error" });
+        res.end();
+        cleanup();
+        reject(
+          new OAuthError({
+            error: "invalid_request",
+            errorDescription: "Missing code or state",
+          }),
+        );
+        return;
+      }
+
+      if (state !== authorization.state) {
+        res.writeHead(302, { Location: "https://alchemy.run/auth/error" });
+        res.end();
+        cleanup();
+        reject(
+          new OAuthError({
+            error: "invalid_request",
+            errorDescription: "Invalid state",
+          }),
+        );
+        return;
+      }
+
+      try {
+        const credentials = await Effect.runPromise(
+          exchange(code, authorization.verifier),
+        );
+        res.writeHead(302, {
+          Location: "https://alchemy.run/auth/success",
+        });
+        res.end();
+        cleanup();
+        resolve(credentials);
+      } catch (err) {
+        res.writeHead(302, { Location: "https://alchemy.run/auth/error" });
+        res.end();
+        cleanup();
+        reject(err);
+      }
+    });
+
+    const timeout = setTimeout(
+      () => {
+        cleanup();
+        reject(
+          new OAuthError({
+            error: "timeout",
+            errorDescription: "The authorization process timed out.",
+          }),
+        );
+      },
+      5 * 60 * 1000,
+    );
+
+    function cleanup() {
+      clearTimeout(timeout);
+      server.close();
+    }
+
+    server.on("error", (err) => {
+      cleanup();
+      reject(
+        new OAuthError({
+          error: "server_error",
+          errorDescription: `Failed to start callback server: ${err.message}`,
+        }),
+      );
+    });
+
+    server.listen(Number(port));
+  });
+}

package/src/Cloudflare/Container/Container.ts

@@ -48,6 +48,128 @@ export type Container = {
   interceptAllOutboundHttp(binding: Fetcher): Effect.Effect<void>;
 };
 
+/**
+ * A Cloudflare Container that runs a long-lived process alongside a
+ * Durable Object.
+ *
+ * Containers always use the **Container Layer** pattern — the class
+ * and `.make()` must live in separate files. A Container must be
+ * bound to a Durable Object, and the DO imports the class to get a
+ * typed handle. If the class and `.make()` lived in the same file,
+ * the DO's bundle would pull in all of the container's runtime
+ * dependencies (process spawners, Node APIs, SDKs, etc.), which
+ * would bloat the bundle and likely break the Cloudflare Workers
+ * runtime. Keeping them separate ensures the bundler only includes
+ * the tiny class in the DO's output.
+ *
+ * See the {@link https://alchemy.run/concepts/platform | Platform
+ * concept} page for how this fits into the async / effect / layer
+ * progression.
+ *
+ * @section Container Layer
+ * Define the class and `.make()` in separate files. The class
+ * declares the container's identity, configuration, and typed
+ * shape. `.make()` provides the runtime implementation as a
+ * default export. Use `Container.of` to construct the typed
+ * shape — it ensures your implementation matches the methods
+ * declared on the class.
+ *
+ * @example Container class
+ * ```typescript
+ * // src/Sandbox.ts
+ * export class Sandbox extends Cloudflare.Container<
+ *   Sandbox,
+ *   {
+ *     exec: (cmd: string) => Effect.Effect<{
+ *       exitCode: number;
+ *       stdout: string;
+ *       stderr: string;
+ *     }>;
+ *   }
+ * >()(
+ *   "Sandbox",
+ *   { main: import.meta.filename },
+ * ) {}
+ * ```
+ *
+ * @example Container .make()
+ * ```typescript
+ * // src/Sandbox.runtime.ts
+ * export default Sandbox.make(
+ *   Effect.gen(function* () {
+ *     const cp = yield* ChildProcessSpawner;
+ *
+ *     return Sandbox.of({
+ *       exec: (cmd) =>
+ *         cp.spawn(ChildProcess.make(cmd, { shell: true })).pipe(
+ *           Effect.map(({ exitCode, stdout, stderr }) => ({
+ *             exitCode, stdout, stderr,
+ *           })),
+ *           Effect.scoped,
+ *         ),
+ *       fetch: Effect.succeed(
+ *         HttpServerResponse.text("Hello from container!"),
+ *       ),
+ *     });
+ *   }),
+ * );
+ * ```
+ *
+ * @section Configuration
+ * The props object accepts `main` (entrypoint file), `instanceType`
+ * (compute size), `runtime` (`"bun"` or `"node"`), and
+ * `observability` settings. Use `Stack.useSync` to vary config by
+ * stage.
+ *
+ * @example Stage-dependent configuration
+ * ```typescript
+ * export class Sandbox extends Cloudflare.Container<Sandbox>()(
+ *   "Sandbox",
+ *   Stack.useSync((stack) => ({
+ *     main: import.meta.filename,
+ *     instanceType: stack.stage === "prod" ? "standard-1" : "dev",
+ *     observability: { logs: { enabled: true } },
+ *   })),
+ * ) {}
+ * ```
+ *
+ * @section Starting from a Durable Object
+ * Use `Cloudflare.Container.bind` in the outer init phase to bind
+ * the container class, then `Cloudflare.start` in the inner
+ * per-instance phase to start it. Because the DO only imports the
+ * class, the runtime implementation is completely excluded from the
+ * DO's bundle.
+ *
+ * @example Binding and starting a container
+ * ```typescript
+ * // init (outer Effect) — only imports the class
+ * const sandbox = yield* Cloudflare.Container.bind(Sandbox);
+ *
+ * // per-instance (inner Effect)
+ * return Effect.gen(function* () {
+ *   const container = yield* Cloudflare.start(sandbox);
+ *
+ *   return {
+ *     exec: (cmd: string) => container.exec(cmd),
+ *   };
+ * });
+ * ```
+ *
+ * @section HTTP Requests to Container Ports
+ * Use `getTcpPort` to get a `fetch` handle for a specific port on
+ * the running container. This lets you make HTTP requests to
+ * servers running inside the container process.
+ *
+ * @example Fetching from a container port
+ * ```typescript
+ * const container = yield* Cloudflare.start(sandbox);
+ * const { fetch } = yield* container.getTcpPort(3000);
+ *
+ * const response = yield* fetch(
+ *   HttpClientRequest.get("http://container/health"),
+ * );
+ * ```
+ */
 export const Container: Platform<
   ContainerApplication,
   ContainerServices,

package/src/Cloudflare/Container/ContainerApplication.ts

@@ -223,6 +223,9 @@ export type ContainerServices =
 
 export type ContainerShape = Main<ContainerServices>;
 
+/**
+ * @internal
+ */
 export interface ContainerApplication<Shape = unknown> extends Resource<
   ContainerTypeId,
   ContainerApplicationProps,
@@ -480,16 +483,16 @@ ${
   runtime === "bun"
     ? `
 import { BunServices } from "@effect/platform-bun";
-import { BunHttpServer } from "alchemy-effect/Http";
+import { BunHttpServer } from "alchemy/Http";
 const HttpServer = BunHttpServer;
 `
     : `
 import { NodeServices } from "@effect/platform-node";
-import { NodeHttpServer } from "alchemy-effect/Http";
+import { NodeHttpServer } from "alchemy/Http";
 const HttpServer = NodeHttpServer;
 `
 }
-import { Stack } from "alchemy-effect/Stack";
+import { Stack } from "alchemy/Stack";
 import * as Effect from "effect/Effect";
 import * as FetchHttpClient from "effect/unstable/http/FetchHttpClient";
 import * as Layer from "effect/Layer";

package/src/Cloudflare/Container/ContainerBinding.ts

@@ -5,10 +5,8 @@ import {
   toCloudflareFetcher,
   type Fetcher,
 } from "../Fetcher.ts";
-import {
-  DurableObjectNamespace,
-  DurableObjectState,
-} from "../Workers/DurableObject.ts";
+import { DurableObjectNamespace } from "../Workers/DurableObjectNamespace.ts";
+import { DurableObjectState } from "../Workers/DurableObjectState.ts";
 import { Worker } from "../Workers/Worker.ts";
 import type { Container } from "./Container.ts";
 import type { ContainerApplication } from "./ContainerApplication.ts";

package/src/Cloudflare/Container/StartContainer.ts

@@ -6,7 +6,7 @@ import * as HttpClientResponse from "effect/unstable/http/HttpClientResponse";
 import * as HttpServerRequest from "effect/unstable/http/HttpServerRequest";
 import * as HttpServerResponse from "effect/unstable/http/HttpServerResponse";
 import { type Fetcher } from "../Fetcher.ts";
-import { DurableObjectState } from "../Workers/DurableObject.ts";
+import { DurableObjectState } from "../Workers/DurableObjectState.ts";
 import { type Container, ContainerError } from "./Container.ts";
 
 /**

package/src/Cloudflare/D1/D1Database.ts

@@ -57,18 +57,37 @@ export type D1Database = Resource<
 /**
  * A Cloudflare D1 serverless SQL database built on SQLite.
  *
+ * D1 is a serverless relational database that runs at the edge. Create a
+ * database as a resource, then bind it to a Worker to run SQL queries.
+ *
  * @section Creating a Database
- * @example Basic Database
+ * @example Basic database
  * ```typescript
- * const db = yield* Database("my-db", {});
+ * const db = yield* Cloudflare.D1Database("my-db");
  * ```
  *
- * @example Database with Location Hint
+ * @example Database with location hint
  * ```typescript
- * const db = yield* Database("my-db", {
+ * const db = yield* Cloudflare.D1Database("my-db", {
  *   primaryLocationHint: "wnam",
  * });
  * ```
+ *
+ * @section Binding to a Worker
+ * @example Using D1 inside a Worker
+ * ```typescript
+ * const db = yield* Cloudflare.D1Connection.bind(MyDB);
+ *
+ * // Run a query
+ * const results = yield* db.prepare("SELECT * FROM users WHERE id = ?")
+ *   .bind(userId)
+ *   .all();
+ *
+ * // Execute a mutation
+ * yield* db.prepare("INSERT INTO users (id, name) VALUES (?, ?)")
+ *   .bind(newId, name)
+ *   .run();
+ * ```
  */
 export const D1Database = Resource<D1Database>("Cloudflare.D1Database");
 

package/src/Cloudflare/KV/KVNamespace.ts

@@ -30,6 +30,31 @@ export type KVNamespace = Resource<
   Providers
 >;
 
+/**
+ * A Cloudflare Workers KV namespace for key-value storage at the edge.
+ *
+ * KV provides eventually-consistent, low-latency reads with global
+ * replication. Create a namespace as a resource, then bind it to a Worker
+ * to get/put values at runtime.
+ *
+ * @section Creating a Namespace
+ * @example Basic KV namespace
+ * ```typescript
+ * const kv = yield* Cloudflare.KVNamespace("MyKV");
+ * ```
+ *
+ * @section Binding to a Worker
+ * @example Using KV inside a Worker
+ * ```typescript
+ * const kv = yield* Cloudflare.KVNamespace.bind(MyKV);
+ *
+ * // Read a value
+ * const value = yield* kv.get("my-key");
+ *
+ * // Write a value
+ * yield* kv.put("my-key", "hello world");
+ * ```
+ */
 export const KVNamespace = Resource<KVNamespace>("Cloudflare.KVNamespace")({
   bind: KVNamespaceBinding.bind,
 });

package/src/Cloudflare/Providers.ts

@@ -10,7 +10,6 @@ import * as Containers from "./Container/index.ts";
 import * as D1 from "./D1/index.ts";
 import * as KV from "./KV/index.ts";
 import * as R2 from "./R2/index.ts";
-import * as Assets from "./Workers/Assets.ts";
 import * as Workers from "./Workers/index.ts";
 import * as Workflows from "./Workers/Workflow.ts";
 
@@ -60,11 +59,7 @@ export const providers = () =>
       ),
     ),
     Layer.provideMerge(
-      Layer.mergeAll(
-        Assets.AssetsProvider(),
-        Build.CommandProvider(),
-        RandomProvider(),
-      ),
+      Layer.mergeAll(Build.CommandProvider(), RandomProvider()),
     ),
     Layer.provideMerge(
       Layer.mergeAll(

package/src/Cloudflare/R2/R2Bucket.ts

@@ -6,7 +6,7 @@ import { createPhysicalName } from "../../PhysicalName.ts";
 import * as Provider from "../../Provider.ts";
 import { Resource } from "../../Resource.ts";
 import { Account } from "../Account.ts";
-import type { Providers } from "../Providers.ts";
+import type * as Cloudflare from "../Providers.ts";
 import { R2BucketBinding } from "./R2BucketBinding.ts";
 
 export type R2BucketName = string;
@@ -44,9 +44,52 @@ export type R2Bucket = Resource<
     accountId: string;
   },
   never,
-  Providers
+  Cloudflare.Providers
 >;
 
+/**
+ * A Cloudflare R2 object storage bucket with S3-compatible API.
+ *
+ * R2 provides zero-egress-fee object storage. Create a bucket as a resource,
+ * then bind it to a Worker to read and write objects at runtime.
+ *
+ * @section Creating a Bucket
+ * @example Basic R2 bucket
+ * ```typescript
+ * const bucket = yield* Cloudflare.R2Bucket("MyBucket");
+ * ```
+ *
+ * @example Bucket with location hint
+ * ```typescript
+ * const bucket = yield* Cloudflare.R2Bucket("MyBucket", {
+ *   locationHint: "wnam",
+ * });
+ * ```
+ *
+ * @section Binding to a Worker
+ * @example Reading and writing objects
+ * ```typescript
+ * const bucket = yield* Cloudflare.R2Bucket.bind(MyBucket);
+ *
+ * // Write an object
+ * yield* bucket.put("hello.txt", "Hello, World!");
+ *
+ * // Read an object
+ * const object = yield* bucket.get("hello.txt");
+ * if (object) {
+ *   const text = yield* object.text();
+ * }
+ * ```
+ *
+ * @example Streaming upload with content length
+ * ```typescript
+ * const bucket = yield* Cloudflare.R2Bucket.bind(MyBucket);
+ *
+ * yield* bucket.put("upload.bin", request.stream, {
+ *   contentLength: Number(request.headers["content-length"] ?? 0),
+ * });
+ * ```
+ */
 export const R2Bucket = Resource<R2Bucket>("Cloudflare.R2Bucket")({
   bind: R2BucketBinding.bind,
 });