sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ DSQL/ Connect.ts

import type { PresignError } from "@distilled.cloud/aws/Presign";
import * as Binding from "alchemy/Binding";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import type * as Effect from "effect/Effect";
import type { SqlConnectionInfo } from "../Connection/internal.ts";
import { connectEnvPrefix as makeConnectEnvPrefix } from "../Connection/internal.ts";
import type { Cluster } from "./Cluster.ts";

export interface ConnectOptions {
  /**
   * Connect as the built-in `admin` role. Grants `dsql:DbConnectAdmin` on the
   * cluster (instead of `dsql:DbConnect`) and signs the auth token for the
   * `DbConnectAdmin` action.
   * @default false
   */
  admin?: boolean;
  /**
   * Database role to connect as when `admin` is not set. Must be a Postgres
   * role in the cluster that was granted to an IAM identity via
   * `AWS IAM GRANT`.
   */
  username?: string;
  /**
   * Database to connect to.
   * @default "postgres"
   */
  database?: string;
}

/**
 * Environment variable prefix under which {@link Connect} publishes the
 * cluster endpoint on the host Function, derived from the cluster's logical
 * ID. A cluster with logical ID `AppDb` yields `DSQL_APPDB` and the variable
 * `DSQL_APPDB_HOST`.
 */
export const connectEnvPrefix = (logicalId: string): string =>
  makeConnectEnvPrefix("DSQL", logicalId);

/**
 * Runtime binding that resolves connection settings for an Aurora DSQL
 * cluster using IAM database authentication.
 *
 * DSQL clusters expose a **public** Postgres-wire endpoint
 * (`<clusterId>.dsql.<region>.on.aws:5432`) and authenticate exclusively
 * with short-lived IAM auth tokens — there is no password secret and no VPC
 * requirement. The deploy half grants `dsql:DbConnect` (or
 * `dsql:DbConnectAdmin` with `admin: true`) on the cluster to the host
 * Function; the runtime half mints a presigned token client-side (a pure
 * SigV4 computation, no API call) and returns a {@link SqlConnectionInfo}
 * whose `url` feeds `Drizzle.Postgres` / any Postgres client directly.
 *
 * Token freshness is structural: yielding the returned connection effect
 * re-mints the token, and execution-scoped pools (`Drizzle.Postgres`)
 * rebuild per execution — a ~15-minute token can never outlive its pool.
 *
 * ### Connecting to a Cluster
 * **Example:** Resolve Connection Info inside a Function
 * ```typescript
 * const conn = yield* DSQL.Connect(cluster, { admin: true });
 * // inside a handler — each yield mints a fresh auth token:
 * const { host, port, username, password, url } = yield* conn;
 * ```
 *
 * **Example:** Drizzle over DSQL
 * ```typescript
 * const conn = yield* DSQL.Connect(cluster, { admin: true });
 * const db = yield* Drizzle.Postgres(conn.pipe(Effect.map((info) => info.url)));
 * // inside a handler:
 * const rows = yield* db.select().from(Widgets);
 * ```
 *
 * **Example:** Connect as a Custom Database Role
 * ```typescript
 * const conn = yield* DSQL.Connect(cluster, {
 *   username: "app",
 *   database: "postgres",
 * });
 * ```
 *
 * @binding
 */
export interface Connect extends Binding.Service<
  Connect,
  "AWS.DSQL.Connect",
  (
    cluster: Cluster,
    options?: ConnectOptions,
  ) => Effect.Effect<Effect.Effect<SqlConnectionInfo, PresignError, RuntimeContext>>
> {}
export const Connect = Binding.Service<Connect>("AWS.DSQL.Connect");