The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type * as Presign from "@distilled.cloud/aws/Presign"; |
| 2 | import type * as secretsmanager from "@distilled.cloud/aws/secrets-manager"; |
| 3 | import * as Binding from "alchemy/Binding"; |
| 4 | import type { Input } from "alchemy/Input"; |
| 5 | import type { RuntimeContext } from "alchemy/RuntimeContext"; |
| 6 | import type * as Effect from "effect/Effect"; |
| 7 | import type * as Redacted from "effect/Redacted"; |
| 8 | import type { SecurityGroupId } from "../EC2/SecurityGroup.ts"; |
| 9 | import type { SubnetId } from "../EC2/Subnet.ts"; |
| 10 | import type { Secret } from "../SecretsManager/Secret.ts"; |
| 11 | import type { DBCluster } from "./DBCluster.ts"; |
| 12 | import type { DBInstance } from "./DBInstance.ts"; |
| 13 | import type { DBProxy } from "./DBProxy.ts"; |
| 14 | import type { DBProxyEndpoint } from "./DBProxyEndpoint.ts"; |
| 15 | |
| 16 | export type ConnectResource = DBCluster | DBInstance | DBProxy | DBProxyEndpoint; |
| 17 | |
| 18 | export interface ConnectionInfo { |
| 19 | host: string; |
| 20 | port: number; |
| 21 | database?: string; |
| 22 | username?: string; |
| 23 | password?: string; |
| 24 | ssl: boolean; |
| 25 | /** |
| 26 | * RFC-3986 connection URL — feeds `Drizzle.Postgres` / a Hyperdrive |
| 27 | * origin directly. `Redacted` because it embeds the password. |
| 28 | */ |
| 29 | url: Redacted.Redacted<string>; |
| 30 | /** |
| 31 | * IAM auth mode only: re-mints a fresh short-lived (15 minute) IAM |
| 32 | * database authentication token. |
| 33 | * |
| 34 | * Per-execution pools (Lambda invoke, Worker event) never need it — the |
| 35 | * `Connect` runtime effect re-runs on each execution and mints a fresh |
| 36 | * token as `password`/`url`. Long-lived serverful pools (ECS Task / |
| 37 | * ServerHost) should wire this into the driver's lazy-password hook |
| 38 | * (`@effect/sql-pg` `password: Effect`, `postgres.js` `pass: () => ...`) so every |
| 39 | * new physical connection authenticates with a fresh token instead of a |
| 40 | * token minted at pool construction. |
| 41 | */ |
| 42 | refreshPassword?: Effect.Effect<Redacted.Redacted<string>, Presign.PresignError>; |
| 43 | } |
| 44 | |
| 45 | interface ConnectOptionsBase { |
| 46 | database?: string; |
| 47 | port?: number; |
| 48 | ssl?: boolean; |
| 49 | /** |
| 50 | * Subnets the host Function should be attached to so it can open a |
| 51 | * socket to the database. Wired through the host's `vpc` binding |
| 52 | * channel — equivalent to setting the Function's `vpc` prop manually. |
| 53 | */ |
| 54 | subnetIds?: Input<SubnetId[]>; |
| 55 | /** |
| 56 | * Security groups for the host Function's VPC attachment (see |
| 57 | * {@link ConnectOptionsBase.subnetIds}). The referenced groups must be |
| 58 | * allowed ingress on the database port by the database's security |
| 59 | * group. |
| 60 | */ |
| 61 | securityGroupIds?: Input<SecurityGroupId[]>; |
| 62 | } |
| 63 | |
| 64 | /** |
| 65 | * Default credential strategy: read `{ username, password }` from a |
| 66 | * Secrets Manager secret. The deploy half grants |
| 67 | * `secretsmanager:GetSecretValue` on the secret; the runtime half fetches |
| 68 | * and parses it. |
| 69 | */ |
| 70 | export interface SecretConnectOptions extends ConnectOptionsBase { |
| 71 | /** @default "secret" */ |
| 72 | auth?: "secret"; |
| 73 | /** |
| 74 | * Secret whose JSON payload carries `username` and `password`. Required |
| 75 | * for a proxy. For a `DBInstance` or `DBCluster` it defaults to the |
| 76 | * database's RDS-managed master user secret (`manageMasterUserPassword: |
| 77 | * true`); a managed secret encrypted with a customer-managed KMS key also |
| 78 | * needs `kms:Decrypt` on that key. |
| 79 | * @default the RDS-managed master user secret |
| 80 | */ |
| 81 | secret?: Secret; |
| 82 | } |
| 83 | |
| 84 | /** |
| 85 | * IAM database authentication: the deploy half grants `rds-db:connect` on |
| 86 | * `arn:aws:rds-db:{region}:{account}:dbuser:{resourceId}/{username}`; the |
| 87 | * runtime half presigns a short-lived auth token as the password. Requires |
| 88 | * `enableIAMDatabaseAuthentication: true` on the database and a database |
| 89 | * user granted the `rds_iam` role (Postgres) / `AWSAuthenticationPlugin` |
| 90 | * (MySQL). TLS is mandatory — `ssl` is forced to `true`. |
| 91 | */ |
| 92 | export interface IamConnectOptions extends ConnectOptionsBase { |
| 93 | auth: "iam"; |
| 94 | /** Database user the IAM token authenticates as. */ |
| 95 | username: string; |
| 96 | } |
| 97 | |
| 98 | export type ConnectOptions = SecretConnectOptions | IamConnectOptions; |
| 99 | |
| 100 | /** |
| 101 | * Runtime binding that resolves connection settings for an Aurora cluster, |
| 102 | * RDS instance, proxy, or proxy endpoint using a Secrets Manager secret or |
| 103 | * IAM database authentication. |
| 104 | * |
| 105 | * Binding it yields an Effect (not a callable) that resolves a |
| 106 | * `ConnectionInfo` — host, port, credentials, and a ready-to-use `url` — |
| 107 | * fresh on every execution. No socket is opened; feed the result into your |
| 108 | * database driver. Provide the implementation with |
| 109 | * `Effect.provide(AWS.RDS.ConnectHttp)`. |
| 110 | * ### Connecting to a Database |
| 111 | * **Example:** Resolve Credentials from a Secret |
| 112 | * ```typescript |
| 113 | * export default MyFunction.make( |
| 114 | * { main: import.meta.url, functionUrl: true }, |
| 115 | * Effect.gen(function* () { |
| 116 | * const db = yield* AWS.RDS.Aurora("AppDb", { |
| 117 | * subnetIds: [subnetA.subnetId, subnetB.subnetId], |
| 118 | * securityGroupIds: [dbSecurityGroup.groupId], |
| 119 | * }); |
| 120 | * // init — bind the cluster + admin secret; grants |
| 121 | * // secretsmanager:GetSecretValue and (optionally) attaches the |
| 122 | * // function to the given subnets/security groups |
| 123 | * const connect = yield* AWS.RDS.Connect(db.cluster, { |
| 124 | * secret: db.secret, |
| 125 | * database: "app", |
| 126 | * subnetIds: [subnetA.subnetId, subnetB.subnetId], |
| 127 | * securityGroupIds: [appSecurityGroup.groupId], |
| 128 | * }); |
| 129 | * |
| 130 | * return { |
| 131 | * fetch: Effect.gen(function* () { |
| 132 | * // runtime — resolve host/port/credentials, hand `info.url` |
| 133 | * // (Redacted) to SQL.Postgres / Drizzle.Postgres |
| 134 | * const info = yield* connect; |
| 135 | * return yield* HttpServerResponse.json({ |
| 136 | * host: info.host, |
| 137 | * port: info.port, |
| 138 | * database: info.database, |
| 139 | * }); |
| 140 | * }).pipe(Effect.orDie), |
| 141 | * }; |
| 142 | * }).pipe(Effect.provide(AWS.RDS.ConnectHttp)), |
| 143 | * ); |
| 144 | * ``` |
| 145 | * |
| 146 | * **Example:** Connect to an RDS Instance with its Managed Secret |
| 147 | * ```typescript |
| 148 | * const instance = yield* AWS.RDS.DBInstance("AppDb", { |
| 149 | * engine: "postgres", |
| 150 | * dbInstanceClass: "db.t4g.micro", |
| 151 | * masterUsername: "app", |
| 152 | * manageMasterUserPassword: true, |
| 153 | * dbSubnetGroupName: subnetGroup.dbSubnetGroupName, |
| 154 | * vpcSecurityGroupIds: [dbSecurityGroup.groupId], |
| 155 | * }); |
| 156 | * // no `secret` — reads the RDS-managed master user secret |
| 157 | * const connect = yield* AWS.RDS.Connect(instance, { |
| 158 | * database: "postgres", |
| 159 | * subnetIds: [subnetA.subnetId, subnetB.subnetId], |
| 160 | * securityGroupIds: [appSecurityGroup.groupId], |
| 161 | * }); |
| 162 | * ``` |
| 163 | * |
| 164 | * **Example:** IAM Database Authentication |
| 165 | * ```typescript |
| 166 | * // init — grants rds-db:connect for the `app_iam` user; the runtime half |
| 167 | * // presigns a short-lived (15 minute) auth token as the password |
| 168 | * const connect = yield* AWS.RDS.Connect(db.cluster, { |
| 169 | * auth: "iam", |
| 170 | * username: "app_iam", |
| 171 | * database: "app", |
| 172 | * }); |
| 173 | * |
| 174 | * // runtime — long-lived pools should wire info.refreshPassword into the |
| 175 | * // driver's lazy-password hook so each new connection gets a fresh token |
| 176 | * const info = yield* connect; |
| 177 | * ``` |
| 178 | * |
| 179 | * @binding |
| 180 | */ |
| 181 | export interface Connect extends Binding.Service< |
| 182 | Connect, |
| 183 | "AWS.RDS.Connect", |
| 184 | ( |
| 185 | resource: ConnectResource, |
| 186 | options: ConnectOptions, |
| 187 | ) => Effect.Effect< |
| 188 | Effect.Effect< |
| 189 | ConnectionInfo, |
| 190 | secretsmanager.GetSecretValueError | Presign.PresignError, |
| 191 | RuntimeContext |
| 192 | > |
| 193 | > |
| 194 | > {} |
| 195 | export const Connect = Binding.Service<Connect>("AWS.RDS.Connect"); |