import * as rds from "@distilled.cloud/aws/rds";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags } from "alchemy/Tags";
import { toWireSeconds } from "alchemy/Util/Duration";
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
export class DBProxyNotReady extends Data.TaggedError("DBProxyNotReady")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export interface DBProxyProps {
/**
* Proxy name. If omitted, Alchemy generates one.
*/
dbProxyName?: string;
/**
* Engine family such as `POSTGRESQL`.
*/
engineFamily: rds.EngineFamily;
/**
* Authentication config for the proxy.
*/
auth: rds.UserAuthConfig[];
/**
* IAM role ARN used by the proxy to read secrets.
*/
roleArn: string;
/**
* Subnets used by the proxy.
*/
vpcSubnetIds: string[];
/**
* Security groups attached to the proxy.
*/
vpcSecurityGroupIds?: string[];
/**
* Require TLS from clients.
*/
requireTLS?: boolean;
/**
* Idle client timeout (e.g. `"30 minutes"` or `Duration.minutes(30)`).
* Sent to the API in whole seconds.
*/
idleClientTimeout?: Duration.Input;
/**
* Enable debug logging.
*/
debugLogging?: boolean;
/**
* Endpoint network type.
*/
endpointNetworkType?: rds.EndpointNetworkType;
/**
* Target connection network type.
*/
targetConnectionNetworkType?: rds.TargetConnectionNetworkType;
/**
* User-defined tags.
*/
tags?: Record<string, string>;
}
export interface DBProxy extends Resource<
"AWS.RDS.DBProxy",
DBProxyProps,
{
/**
* Name of the proxy.
*/
dbProxyName: string;
/**
* ARN of the proxy.
*/
dbProxyArn: string;
/**
* DNS endpoint applications connect to.
*/
endpoint: string | undefined;
/**
* Status of the proxy (e.g. `available`).
*/
status: string | undefined;
/**
* Engine family the proxy fronts (`POSTGRESQL`, `MYSQL`).
*/
engineFamily: string | undefined;
/**
* IAM role the proxy uses to read credentials secrets.
*/
roleArn: string | undefined;
/**
* VPC the proxy runs in.
*/
vpcId: string | undefined;
/**
* Subnets the proxy is attached to.
*/
vpcSubnetIds: string[];
/**
* Security groups attached to the proxy.
*/
vpcSecurityGroupIds: string[];
/**
* Whether clients must use TLS.
*/
requireTLS: boolean | undefined;
/**
* Idle client timeout in seconds.
*/
idleClientTimeout: number | undefined;
/**
* Whether debug logging is enabled.
*/
debugLogging: boolean | undefined;
/**
* Tags on the proxy.
*/
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* An RDS Proxy for pooled Lambda-to-Aurora connectivity.
*
* The proxy multiplexes many short-lived function connections over a small
* pool of database connections, absorbing connection storms from Lambda
* scale-out. It authenticates against the database with credentials read
* from Secrets Manager via the provided IAM role, then registers targets
* through a `DBProxyTargetGroup`. Changing the name, engine family, or
* subnets replaces the proxy; auth, TLS, timeout, and security groups
* update in place.
*
* For the common case, `Aurora("Db", { proxy: true })` wires the role,
* proxy, target group, and secret automatically.
* ### Creating a Proxy
* **Example:** Proxy in Front of an Aurora Cluster
* ```typescript
* const proxy = yield* DBProxy("Proxy", {
* engineFamily: "POSTGRESQL",
* auth: [
* {
* AuthScheme: "SECRETS",
* SecretArn: secret.secretArn,
* IAMAuth: "DISABLED",
* },
* ],
* roleArn: proxyRole.roleArn,
* vpcSubnetIds: [privateSubnetA.subnetId, privateSubnetB.subnetId],
* vpcSecurityGroupIds: [dbSecurityGroup.groupId],
* requireTLS: true,
* });
*
* // register the cluster behind the proxy
* const targets = yield* DBProxyTargetGroup("ProxyTargets", {
* dbProxyName: proxy.dbProxyName,
* dbClusterIdentifiers: [cluster.dbClusterIdentifier],
* });
* ```
*
* @resource
*/
export const DBProxy = Resource<DBProxy>("AWS.RDS.DBProxy");
const toAttrs = ({
proxy,
tags,
}: {
proxy: rds.DBProxy;
tags: Record<string, string>;
}): DBProxy["Attributes"] => ({
dbProxyName: proxy.DBProxyName ?? "",
dbProxyArn: proxy.DBProxyArn ?? "",
endpoint: proxy.Endpoint,
status: proxy.Status,
engineFamily: proxy.EngineFamily,
roleArn: proxy.RoleArn,
vpcId: proxy.VpcId,
vpcSubnetIds: proxy.VpcSubnetIds ?? [],
vpcSecurityGroupIds: proxy.VpcSecurityGroupIds ?? [],
requireTLS: proxy.RequireTLS,
idleClientTimeout: proxy.IdleClientTimeout,
debugLogging: proxy.DebugLogging,
tags,
});
export const DBProxyProvider = () =>
Provider.effect(
DBProxy,
Effect.gen(function* () {
const toName = (id: string, props: DBProxyProps) =>
props.dbProxyName
? Effect.succeed(props.dbProxyName)
: createPhysicalName({ id, maxLength: 63 });
const readProxy = Effect.fn(function* (name: string) {
const response = yield* rds
.describeDBProxies({
DBProxyName: name,
})
.pipe(Effect.catchTag("DBProxyNotFoundFault", () => Effect.undefined));
return response?.DBProxies?.[0];
});
const waitForProxy = Effect.fn(function* (name: string) {
const readinessPolicy = Schedule.max([Schedule.fixed("2 seconds"), Schedule.recurs(30)]);
return yield* readProxy(name).pipe(
Effect.flatMap((proxy) =>
proxy?.DBProxyArn
? Effect.succeed(proxy)
: Effect.fail(new DBProxyNotReady({ message: `DB proxy '${name}' not ready` })),
),
Effect.retry({ schedule: readinessPolicy }),
);
});
return {
stables: ["dbProxyArn", "dbProxyName"],
// Enumerate every DB proxy in the account/region via the paginated
// `describeDBProxies`, then hydrate each proxy's tags via
// `listTagsForResource` (describe does not return tags inline) so each
// element matches `read`'s `Attributes` shape exactly. A proxy deleted
// between the describe and the tag fetch surfaces `DBProxyNotFoundFault`
// per item and is dropped.
list: () =>
Effect.gen(function* () {
const proxies = yield* rds.describeDBProxies.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.DBProxies ?? [])),
);
const rows = yield* Effect.forEach(
proxies,
(proxy) =>
Effect.gen(function* () {
if (!proxy.DBProxyArn) return undefined;
const tagResponse = yield* rds
.listTagsForResource({ ResourceName: proxy.DBProxyArn })
.pipe(Effect.catchTag("DBProxyNotFoundFault", () => Effect.undefined));
if (tagResponse === undefined) return undefined;
const tags = Object.fromEntries(
(tagResponse.TagList ?? [])
.filter((tag): tag is rds.Tag & { Key: string } => tag.Key != null)
.map((tag) => [tag.Key, tag.Value ?? ""] as const),
);
return toAttrs({ proxy, tags });
}),
{ concurrency: 10 },
);
return rows.filter((row): row is DBProxy["Attributes"] => row !== undefined);
}),
diff: Effect.fn(function* ({ id, olds, news }) {
if (!isResolved(news)) return undefined;
if ((yield* toName(id, olds ?? ({} as DBProxyProps))) !== (yield* toName(id, news))) {
return { action: "replace" } as const;
}
if (olds?.engineFamily !== news.engineFamily) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const name =
output?.dbProxyName ??
(yield* toName(
id,
olds ??
({
engineFamily: "POSTGRESQL",
auth: [],
roleArn: "",
vpcSubnetIds: [],
} as DBProxyProps),
));
const proxy = yield* readProxy(name);
if (!proxy?.DBProxyArn) {
return undefined;
}
return toAttrs({ proxy, tags: output?.tags ?? {} });
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const name = output?.dbProxyName ?? (yield* toName(id, news));
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...internalTags, ...news.tags };
// Duration prop → the wire unit the RDS API expects (whole seconds).
const idleClientTimeoutSeconds = toWireSeconds(news.idleClientTimeout);
// Observe — fetch live proxy state.
let observed = yield* readProxy(name);
// Ensure — create if missing. Tolerate
// `DBProxyAlreadyExistsFault` as a race with a peer reconciler.
if (!observed?.DBProxyArn) {
yield* rds
.createDBProxy({
DBProxyName: name,
EngineFamily: news.engineFamily,
Auth: news.auth,
RoleArn: news.roleArn,
VpcSubnetIds: news.vpcSubnetIds,
VpcSecurityGroupIds: news.vpcSecurityGroupIds,
RequireTLS: news.requireTLS,
IdleClientTimeout: idleClientTimeoutSeconds,
DebugLogging: news.debugLogging,
EndpointNetworkType: news.endpointNetworkType,
TargetConnectionNetworkType: news.targetConnectionNetworkType,
Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
Key,
Value,
})),
})
.pipe(Effect.catchTag("DBProxyAlreadyExistsFault", () => Effect.void));
observed = yield* waitForProxy(name);
} else {
// Sync mutable proxy config — push desired shape via
// `modifyDBProxy`. Rename via `NewDBProxyName` is a no-op when
// the desired name already matches the observed name.
yield* rds.modifyDBProxy({
DBProxyName: name,
Auth: news.auth,
RoleArn: news.roleArn,
SecurityGroups: news.vpcSecurityGroupIds,
RequireTLS: news.requireTLS,
IdleClientTimeout: idleClientTimeoutSeconds,
DebugLogging: news.debugLogging,
NewDBProxyName:
news.dbProxyName && news.dbProxyName !== name ? news.dbProxyName : undefined,
});
observed = yield* waitForProxy(news.dbProxyName ?? name);
}
const dbProxyArn = observed.DBProxyArn ?? "";
const finalName = observed.DBProxyName ?? name;
// Sync tags — diff prior recorded tags against desired (describe
// does not surface tags inline).
const observedTags = output?.tags ?? {};
const { removed, upsert } = diffTags(observedTags, desiredTags);
if (upsert.length > 0 && dbProxyArn) {
yield* rds.addTagsToResource({
ResourceName: dbProxyArn,
Tags: upsert,
});
}
if (removed.length > 0 && dbProxyArn) {
yield* rds.removeTagsFromResource({
ResourceName: dbProxyArn,
TagKeys: removed,
});
}
yield* session.note(dbProxyArn || finalName);
return toAttrs({ proxy: observed, tags: desiredTags });
}),
delete: Effect.fn(function* ({ output }) {
yield* rds
.deleteDBProxy({
DBProxyName: output.dbProxyName,
})
.pipe(Effect.catchTag("DBProxyNotFoundFault", () => Effect.void));
}),
};
}),
);