alchemy 2.0.0-beta.4 → 2.0.0-beta.40

package/src/Cloudflare/Email/SendEmailBinding.ts

@@ -0,0 +1,124 @@
+import type * as runtime from "@cloudflare/workers-types";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Binding from "../../Binding.ts";
+import type { ResourceLike } from "../../Resource.ts";
+import { isWorker, WorkerEnvironment } from "../Workers/Worker.ts";
+import type { SendEmail } from "./SendEmail.ts";
+
+/**
+ * Email body shape for the builder-form `send` call. Either `text`, `html`,
+ * or both must be provided.
+ */
+export interface SendEmailMessage {
+  from: string | runtime.EmailAddress;
+  to: string | string[];
+  subject: string;
+  replyTo?: string | runtime.EmailAddress;
+  cc?: string | string[];
+  bcc?: string | string[];
+  headers?: Record<string, string>;
+  text?: string;
+  html?: string;
+  attachments?: runtime.EmailAttachment[];
+}
+
+export class SendEmailError extends Data.TaggedError("SendEmailError")<{
+  message: string;
+  cause?: unknown;
+}> {}
+
+export interface SendEmailClient {
+  /**
+   * The raw runtime `SendEmail` binding. Use this when you need direct
+   * access to the Cloudflare object (e.g. to send a pre-built
+   * `EmailMessage` from `cloudflare:email`).
+   */
+  raw: Effect.Effect<runtime.SendEmail, never, WorkerEnvironment>;
+  /**
+   * Send an email using the builder form. Equivalent to calling
+   * `env.<name>.send({ from, to, subject, text, html, ... })`.
+   */
+  send(
+    message: SendEmailMessage,
+  ): Effect.Effect<runtime.EmailSendResult, SendEmailError, WorkerEnvironment>;
+  /**
+   * Send a raw `EmailMessage` (constructed via `cloudflare:email`).
+   */
+  sendRaw(
+    message: runtime.EmailMessage,
+  ): Effect.Effect<runtime.EmailSendResult, SendEmailError, WorkerEnvironment>;
+}
+
+/**
+ * A typed runtime accessor for a Cloudflare `send_email` Worker binding.
+ *
+ * @binding
+ */
+export class SendEmailBinding extends Binding.Service<
+  SendEmailBinding,
+  (sender: SendEmail) => Effect.Effect<SendEmailClient>
+>()("Cloudflare.SendEmail.Binding") {}
+
+export const SendEmailBindingLive = Layer.effect(
+  SendEmailBinding,
+  Effect.gen(function* () {
+    const bind = yield* SendEmailBindingPolicy;
+
+    return Effect.fnUntraced(function* (sender: SendEmail) {
+      yield* bind(sender);
+
+      const raw = WorkerEnvironment.useSync(
+        (env) => (env as Record<string, runtime.SendEmail>)[sender.name]!,
+      );
+
+      const tryPromise = <T>(
+        fn: () => Promise<T>,
+      ): Effect.Effect<T, SendEmailError> =>
+        Effect.tryPromise({
+          try: fn,
+          catch: (error: any) =>
+            new SendEmailError({
+              message: error?.message ?? "Unknown send_email error",
+              cause: error,
+            }),
+        });
+
+      return {
+        raw,
+        send: (message: SendEmailMessage) =>
+          raw.pipe(Effect.flatMap((s) => tryPromise(() => s.send(message)))),
+        sendRaw: (message: runtime.EmailMessage) =>
+          raw.pipe(Effect.flatMap((s) => tryPromise(() => s.send(message)))),
+      } satisfies SendEmailClient;
+    });
+  }),
+);
+
+export class SendEmailBindingPolicy extends Binding.Policy<
+  SendEmailBindingPolicy,
+  (sender: SendEmail) => Effect.Effect<void>
+>()("Cloudflare.SendEmail.Binding") {}
+
+export const SendEmailBindingPolicyLive = SendEmailBindingPolicy.layer.succeed(
+  Effect.fnUntraced(function* (host: ResourceLike, sender: SendEmail) {
+    if (isWorker(host)) {
+      yield* host.bind(sender.name, {
+        bindings: [
+          {
+            type: "send_email",
+            name: sender.name,
+            destinationAddress: sender.destinationAddress,
+            allowedDestinationAddresses: sender.allowedDestinationAddresses,
+            allowedSenderAddresses: sender.allowedSenderAddresses,
+          },
+        ],
+      });
+    } else {
+      return yield* Effect.die(
+        new Error(`SendEmailBinding does not support runtime '${host.Type}'`),
+      );
+    }
+  }),
+);

package/src/Cloudflare/Email/index.ts

@@ -0,0 +1,5 @@
+export * from "./EmailAddress.ts";
+export * from "./EmailRouting.ts";
+export * from "./EmailRule.ts";
+export * from "./SendEmail.ts";
+export * from "./SendEmailBinding.ts";

package/src/Cloudflare/Fetcher.ts

@@ -233,6 +233,19 @@ export const fromCloudflareSocket = (cfSocket: cf.Socket): Socket.Socket => {
       opts,
     );
 
+  const decoder = new TextDecoder();
+  const runString = <_, E, R>(
+    handler: (_: string) => Effect.Effect<_, E, R> | void,
+    opts?: { readonly onOpen?: Effect.Effect<void> | undefined },
+  ): Effect.Effect<void, Socket.SocketError | E, R> =>
+    runRaw(
+      (data) =>
+        typeof data === "string"
+          ? handler(data)
+          : handler(decoder.decode(data)),
+      opts,
+    );
+
   const write = (
     chunk: Uint8Array | string | Socket.CloseEvent,
   ): Effect.Effect<void, Socket.SocketError> =>
@@ -275,6 +288,7 @@ export const fromCloudflareSocket = (cfSocket: cf.Socket): Socket.Socket => {
     [Socket.TypeId]: Socket.TypeId,
     run,
     runRaw,
+    runString,
     writer,
   });
 };

package/src/Cloudflare/Hyperdrive/Hyperdrive.ts

@@ -0,0 +1,371 @@
+import * as hyperdrive from "@distilled.cloud/cloudflare/hyperdrive";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+
+import { AlchemyContext } from "../../AlchemyContext.ts";
+import { isResolved } from "../../Diff.ts";
+import { createPhysicalName } from "../../PhysicalName.ts";
+import * as Provider from "../../Provider.ts";
+import { Resource } from "../../Resource.ts";
+import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
+import type { Providers } from "../Providers.ts";
+import { HyperdriveBinding } from "./HyperdriveBinding.ts";
+
+export type HyperdriveScheme = "postgres" | "postgresql" | "mysql";
+
+/**
+ * Origin configuration for a public PostgreSQL or MySQL database.
+ */
+export type HyperdrivePublicOrigin = {
+  scheme: HyperdriveScheme;
+  host: string;
+  port?: number;
+  database: string;
+  user: string;
+  /**
+   * Database password.
+   */
+  password: Redacted.Redacted<string>;
+};
+
+/**
+ * Origin configuration for a database fronted by Cloudflare Access.
+ */
+export type HyperdriveAccessOrigin = {
+  scheme: HyperdriveScheme;
+  host: string;
+  database: string;
+  user: string;
+  password: Redacted.Redacted<string>;
+  accessClientId: Redacted.Redacted<string>;
+  accessClientSecret: Redacted.Redacted<string>;
+};
+
+export type HyperdriveOrigin = HyperdrivePublicOrigin | HyperdriveAccessOrigin;
+
+export type HyperdriveCaching = {
+  /**
+   * Whether caching is disabled.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Maximum duration items should persist in the cache, in seconds.
+   * @default 60
+   */
+  maxAge?: number;
+  /**
+   * Number of seconds the cache may serve a stale response while revalidating.
+   * @default 15
+   */
+  staleWhileRevalidate?: number;
+};
+
+export type HyperdriveMtls = {
+  caCertificateId?: string;
+  mtlsCertificateId?: string;
+  /**
+   * @default "require"
+   */
+  sslmode?: "require" | "verify-ca" | "verify-full";
+};
+
+export type HyperdriveDevOrigin = HyperdrivePublicOrigin & {
+  /**
+   * @default "prefer"
+   */
+  sslmode?: "disable" | "prefer" | "require" | "verify-ca" | "verify-full";
+};
+
+export type HyperdriveProps = {
+  /**
+   * Name of the Hyperdrive configuration. If omitted, a unique name will be
+   * generated.
+   * @default ${app}-${stage}-${id}
+   */
+  name?: string;
+  /**
+   * Database connection origin. Hyperdrive supports public Postgres/MySQL
+   * databases and databases fronted by Cloudflare Access.
+   */
+  origin: HyperdriveOrigin;
+  /**
+   * Caching configuration.
+   */
+  caching?: HyperdriveCaching;
+  /**
+   * mTLS configuration.
+   */
+  mtls?: HyperdriveMtls;
+  /**
+   * The (soft) maximum number of connections Hyperdrive is allowed to make to
+   * the origin database.
+   */
+  originConnectionLimit?: number;
+  /**
+   * Local development overrides. When the stack runs in dev mode
+   * connect to a locally running database
+   */
+  dev?: HyperdriveDevOrigin;
+};
+
+export type Hyperdrive = Resource<
+  "Cloudflare.Hyperdrive",
+  HyperdriveProps,
+  {
+    hyperdriveId: string;
+    name: string;
+    accountId: string;
+    origin: HyperdriveOrigin;
+    mtls: HyperdriveMtls;
+    dev: HyperdriveDevOrigin | undefined;
+  },
+  never,
+  Providers
+>;
+
+/**
+ * A Cloudflare Hyperdrive configuration.
+ *
+ * Hyperdrive accelerates and pools connections to existing PostgreSQL or
+ * MySQL databases, exposing them to Workers via a binding. Create a config
+ * as a resource, then bind it to a Worker to obtain a connection string.
+ *
+ * @section Creating a Hyperdrive
+ * @example Public Postgres origin
+ * ```typescript
+ * const hd = yield* Cloudflare.Hyperdrive("my-pg", {
+ *   origin: {
+ *     scheme: "postgres",
+ *     host: "db.example.com",
+ *     port: 5432,
+ *     database: "app",
+ *     user: "app",
+ *     password: alchemy.secret.env.DB_PASSWORD,
+ *   },
+ * });
+ * ```
+ *
+ * @section Binding to a Worker
+ * @example Using Hyperdrive inside a Worker
+ * ```typescript
+ * const hd = yield* Cloudflare.Hyperdrive.bind(MyDB);
+ * const url = yield* hd.connectionString;
+ * ```
+ */
+export const Hyperdrive = Resource<Hyperdrive>("Cloudflare.Hyperdrive")({
+  bind: HyperdriveBinding.bind,
+});
+
+export const HyperdriveProvider = () =>
+  Provider.effect(
+    Hyperdrive,
+    Effect.gen(function* () {
+      const { accountId } = yield* CloudflareEnvironment;
+      const createConfig = yield* hyperdrive.createConfig;
+      const getConfig = yield* hyperdrive.getConfig;
+      const updateConfig = yield* hyperdrive.updateConfig;
+      const deleteConfig = yield* hyperdrive.deleteConfig;
+      const listConfigs = yield* hyperdrive.listConfigs;
+
+      const createConfigName = (id: string, name: string | undefined) =>
+        Effect.gen(function* () {
+          if (name) return name;
+          return yield* createPhysicalName({ id, lowercase: true });
+        });
+
+      const findByName = (name: string) =>
+        Effect.gen(function* () {
+          const list = yield* listConfigs({ accountId });
+          return list.result.find((c) => c.name === name);
+        });
+
+      return {
+        // The `hyperdriveId` is not marked as stable because if you start in dev mode, the ID will change on first deploy.
+        stables: ["accountId"],
+        diff: Effect.fn(function* ({ id, olds, news, output }) {
+          const ctx = yield* AlchemyContext;
+          if (ctx.dev) return undefined;
+
+          if (!isResolved(news)) return undefined;
+          if ((output?.accountId ?? accountId) !== accountId) {
+            return { action: "replace" } as const;
+          }
+          const name = yield* createConfigName(id, news.name);
+          const oldName = output?.name
+            ? output.name
+            : yield* createConfigName(id, olds.name);
+          if (oldName !== name) {
+            return { action: "replace" } as const;
+          }
+          if (!isHyperdriveId(output?.hyperdriveId)) {
+            return { action: "update" };
+          }
+        }),
+        read: Effect.fn(function* ({ id, output, olds }) {
+          const ctx = yield* AlchemyContext;
+          if (ctx.dev) {
+            return output;
+          }
+
+          if (isHyperdriveId(output?.hyperdriveId)) {
+            return yield* getConfig({
+              accountId: output.accountId,
+              hyperdriveId: output.hyperdriveId,
+            }).pipe(
+              Effect.map((c) => ({
+                hyperdriveId: c.id,
+                name: c.name,
+                accountId: output.accountId,
+                origin: {
+                  ...c.origin,
+                  password: olds?.origin?.password,
+                } as HyperdriveOrigin,
+                mtls: {
+                  caCertificateId: c.mtls?.caCertificateId ?? undefined,
+                  mtlsCertificateId: c.mtls?.mtlsCertificateId ?? undefined,
+                  sslmode: c.mtls?.sslmode ?? undefined,
+                } as HyperdriveMtls,
+                dev: output?.dev,
+              })),
+              Effect.catchTag("HyperdriveConfigNotFound", () =>
+                Effect.succeed(undefined),
+              ),
+            );
+          }
+          const name = yield* createConfigName(id, olds?.name);
+          const match = yield* findByName(name);
+          if (match) {
+            return {
+              hyperdriveId: match.id,
+              name: match.name,
+              accountId,
+              origin: {
+                ...match.origin,
+                password: olds?.origin?.password,
+              } as HyperdriveOrigin,
+              mtls: {
+                caCertificateId: match.mtls?.caCertificateId ?? undefined,
+                mtlsCertificateId: match.mtls?.mtlsCertificateId ?? undefined,
+                sslmode: match.mtls?.sslmode ?? undefined,
+              } as HyperdriveMtls,
+              dev: output?.dev,
+            };
+          }
+          return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output }) {
+          const name = output?.name ?? (yield* createConfigName(id, news.name));
+
+          const ctx = yield* AlchemyContext;
+          if (ctx.dev) {
+            return {
+              hyperdriveId:
+                output?.hyperdriveId ?? `dev:${crypto.randomUUID()}`,
+              name,
+              accountId: output?.accountId ?? accountId,
+              origin: news.origin,
+              mtls: news.mtls ?? {},
+              dev: news.dev,
+            };
+          }
+
+          const requestBody = {
+            origin: toRequestOrigin(news.origin),
+            caching: news.caching,
+            mtls: news.mtls,
+            originConnectionLimit: news.originConnectionLimit,
+          };
+
+          // Observe + ensure. When we know the hyperdriveId we go straight
+          // to update; otherwise we createConfig and fall back to "find by
+          // name then update" if Cloudflare reports the name is already in
+          // use (race or a cold-start adoption).
+          const synced = isHyperdriveId(output?.hyperdriveId)
+            ? yield* updateConfig({
+                accountId: output.accountId,
+                hyperdriveId: output.hyperdriveId,
+                name: output.name,
+                ...requestBody,
+              })
+            : yield* createConfig({ accountId, name, ...requestBody }).pipe(
+                Effect.catchTag("InvalidHyperdriveConfig", (originalError) =>
+                  Effect.gen(function* () {
+                    const match = yield* findByName(name);
+                    if (!match) {
+                      return yield* Effect.fail(originalError);
+                    }
+                    return yield* updateConfig({
+                      accountId,
+                      hyperdriveId: match.id,
+                      name,
+                      ...requestBody,
+                    });
+                  }),
+                ),
+              );
+
+          return {
+            hyperdriveId: synced.id,
+            name: synced.name,
+            accountId: output?.accountId ?? accountId,
+            origin: news.origin,
+            mtls: news.mtls ?? {},
+            dev: news.dev,
+          };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          if (!isHyperdriveId(output.hyperdriveId)) return;
+
+          yield* deleteConfig({
+            accountId: output.accountId,
+            hyperdriveId: output.hyperdriveId,
+          }).pipe(
+            Effect.catchIf(
+              (e) =>
+                e._tag === "HyperdriveConfigNotFound" ||
+                (e._tag === "CloudflareHttpError" && e.status === 404),
+              () => Effect.void,
+            ),
+          );
+        }),
+      };
+    }),
+  );
+
+export const defaultPort = (scheme: HyperdriveScheme): number =>
+  scheme === "mysql" ? 3306 : 5432;
+
+const unwrap = (v: string | Redacted.Redacted<string>): string =>
+  Redacted.isRedacted(v) ? Redacted.value(v) : v;
+
+const isHyperdriveId = (maybeId: string | undefined): maybeId is string =>
+  typeof maybeId === "string" && !maybeId.startsWith("dev:");
+
+/**
+ * Build the request body shape that the distilled `createConfig`/`updateConfig`
+ * methods accept. Secrets are unwrapped here because the distilled TS types
+ * declare `password`/`access_client_secret` as plain strings even though the
+ * runtime schema also accepts `Redacted<string>`.
+ */
+const toRequestOrigin = (origin: HyperdriveOrigin) => {
+  if ("accessClientId" in origin) {
+    return {
+      accessClientId: unwrap(origin.accessClientId),
+      accessClientSecret: unwrap(origin.accessClientSecret),
+      database: origin.database,
+      host: origin.host,
+      password: unwrap(origin.password),
+      scheme: origin.scheme,
+      user: origin.user,
+    };
+  }
+  return {
+    database: origin.database,
+    host: origin.host,
+    password: unwrap(origin.password),
+    port: origin.port ?? defaultPort(origin.scheme),
+    scheme: origin.scheme,
+    user: origin.user,
+  };
+};

package/src/Cloudflare/Hyperdrive/HyperdriveBinding.ts

@@ -0,0 +1,163 @@
+import type * as runtime from "@cloudflare/workers-types";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Redacted from "effect/Redacted";
+import { AlchemyContext } from "../../AlchemyContext.ts";
+import * as Binding from "../../Binding.ts";
+import * as Output from "../../Output.ts";
+import type { ResourceLike } from "../../Resource.ts";
+import { isWorker, WorkerEnvironment } from "../Workers/Worker.ts";
+import type { Hyperdrive } from "./Hyperdrive.ts";
+import { defaultPort, type HyperdriveDevOrigin } from "./Hyperdrive.ts";
+
+export interface HyperdriveBindingClient {
+  /**
+   * The raw runtime `Hyperdrive` binding. Use this when integrating with a
+   * driver that wants direct access to the Cloudflare object.
+   */
+  raw: Effect.Effect<runtime.Hyperdrive>;
+  /**
+   * A valid DB connection string for use with a driver/ORM.
+   */
+  connectionString: Effect.Effect<Redacted.Redacted<string>>;
+  /**
+   * Hostname valid only within the current Worker invocation.
+   */
+  host: Effect.Effect<string>;
+  /**
+   * Port to pair with `host`.
+   */
+  port: Effect.Effect<number>;
+  /**
+   * Database user.
+   */
+  user: Effect.Effect<string>;
+  /**
+   * Randomly generated password valid only within the current Worker
+   * invocation.
+   */
+  password: Effect.Effect<Redacted.Redacted<string>>;
+  /**
+   * Database name.
+   */
+  database: Effect.Effect<string>;
+}
+
+/**
+ * A typed accessor for a Cloudflare Hyperdrive runtime binding inside a
+ * Worker. Provides the same shape as the raw `Hyperdrive` runtime object
+ * (connection string, host, port, user, password, database) plus a `raw`
+ * escape hatch for libraries that want direct access.
+ *
+ * @example Bind Hyperdrive in a Worker
+ * ```typescript
+ * const hd = yield* Cloudflare.Hyperdrive.bind(MyHyperdrive);
+ * const url = yield* hd.connectionString;
+ * ```
+ *
+ * @binding
+ */
+export class HyperdriveBinding extends Binding.Service<
+  HyperdriveBinding,
+  (hyperdrive: Hyperdrive) => Effect.Effect<HyperdriveBindingClient>
+>()("Cloudflare.Hyperdrive.Binding") {}
+
+export const HyperdriveBindingLive = Layer.effect(
+  HyperdriveBinding,
+  Effect.gen(function* () {
+    const Policy = yield* HyperdriveBindingPolicy;
+
+    return Effect.fn(function* (hyperdrive: Hyperdrive) {
+      yield* Policy(hyperdrive);
+      const hd = yield* Effect.serviceOption(WorkerEnvironment).pipe(
+        Effect.map(Option.getOrUndefined),
+        Effect.map((env) => env?.[hyperdrive.LogicalId]! as runtime.Hyperdrive),
+        Effect.cached,
+      );
+
+      return {
+        raw: hd,
+        connectionString: hd.pipe(
+          Effect.map((hd) => Redacted.make(hd.connectionString)),
+        ),
+        host: hd.pipe(Effect.map((hd) => hd.host)),
+        port: hd.pipe(Effect.map((hd) => hd.port)),
+        user: hd.pipe(Effect.map((hd) => hd.user)),
+        password: hd.pipe(Effect.map((hd) => Redacted.make(hd.password))),
+        database: hd.pipe(Effect.map((hd) => hd.database)),
+      } satisfies HyperdriveBindingClient;
+    });
+  }),
+);
+
+export class HyperdriveBindingPolicy extends Binding.Policy<
+  HyperdriveBindingPolicy,
+  (hyperdrive: Hyperdrive) => Effect.Effect<void>
+>()("Cloudflare.Hyperdrive.Binding") {}
+
+export const HyperdriveBindingPolicyLive = HyperdriveBindingPolicy.layer.effect(
+  Effect.gen(function* () {
+    const ctx = yield* AlchemyContext;
+
+    return Effect.fn(function* (host: ResourceLike, hyperdrive: Hyperdrive) {
+      if (!isWorker(host)) {
+        return yield* Effect.die(
+          new Error(
+            `HyperdriveBinding does not support runtime '${host.Type}'`,
+          ),
+        );
+      }
+
+      const origin = Output.map(
+        Output.all(hyperdrive.dev, hyperdrive.origin, hyperdrive.mtls),
+        ([dev, origin, mtls]): Required<HyperdriveDevOrigin> => {
+          if (dev) {
+            return {
+              scheme: dev.scheme,
+              host: dev.host,
+              port: dev.port ?? defaultPort(dev.scheme),
+              user: dev.user,
+              database: dev.database,
+              password: dev.password,
+              sslmode: dev.sslmode ?? "prefer",
+            };
+          }
+          if ("accessClientId" in origin) {
+            throw new Error(
+              `Hyperdrive instance ${hyperdrive.LogicalId} has an origin that requires Cloudflare Access. This is not supported in development mode. ` +
+                "Select a different origin or set the `dev` property to an origin that does not require Cloudflare Access.",
+            );
+          }
+          return {
+            scheme: origin.scheme,
+            host: origin.host,
+            port: origin.port ?? defaultPort(origin.scheme),
+            user: origin.user,
+            database: origin.database,
+            password: origin.password,
+            sslmode: mtls?.sslmode ?? "require",
+          };
+        },
+      );
+
+      yield* host.bind`${hyperdrive}`({
+        bindings: [
+          {
+            type: "hyperdrive",
+            name: hyperdrive.LogicalId,
+            id: hyperdrive.hyperdriveId as unknown as string,
+          },
+        ],
+        hyperdrives: ctx.dev
+          ? (Output.map(
+              Output.all(hyperdrive.hyperdriveId, Output.asOutput(origin)),
+              ([id, origin]) => ({
+                [id]: origin,
+              }),
+            ) as unknown as Record<string, Required<HyperdriveDevOrigin>>)
+          : undefined,
+      });
+    });
+  }),
+);

package/src/Cloudflare/Hyperdrive/index.ts

@@ -0,0 +1,2 @@
+export * from "./Hyperdrive.ts";
+export * from "./HyperdriveBinding.ts";