import type * as EC2 from "@distilled.cloud/aws/ec2";
import * as ec2 from "@distilled.cloud/aws/ec2";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import type { ScopedPlanStatusSession } from "alchemy/Report";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import type { RouteTableId } from "./RouteTable.ts";
import type { SubnetId } from "./Subnet.ts";
export class RouteTableAssociationUnexpectedResponse extends Data.TaggedError(
"RouteTableAssociationUnexpectedResponse",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class RouteTableAssociationOperationFailed extends Data.TaggedError(
"RouteTableAssociationOperationFailed",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export class RouteTableAssociationNotReady extends Data.TaggedError(
"RouteTableAssociationNotReady",
)<{
readonly message: string;
readonly cause?: unknown;
}> {}
export type RouteTableAssociationId<ID extends string = string> = `rtbassoc-${ID}`;
export const RouteTableAssociationId = <ID extends string>(
id: ID,
): ID & RouteTableAssociationId<ID> => `rtbassoc-${id}` as ID & RouteTableAssociationId<ID>;
export interface RouteTableAssociationProps {
/**
* The ID of the route table.
* Required.
*/
routeTableId: RouteTableId;
/**
* The ID of the subnet to associate with the route table.
* Either subnetId or gatewayId is required, but not both.
*/
subnetId?: SubnetId;
/**
* The ID of the gateway (internet gateway or virtual private gateway) to associate with the route table.
* Either subnetId or gatewayId is required, but not both.
*/
gatewayId?: string;
}
export interface RouteTableAssociation extends Resource<
"AWS.EC2.RouteTableAssociation",
RouteTableAssociationProps,
{
/**
* The ID of the association.
*/
associationId: RouteTableAssociationId;
/**
* The ID of the route table.
*/
routeTableId: RouteTableId;
/**
* The ID of the subnet (if the association is with a subnet).
*/
subnetId?: SubnetId | undefined;
/**
* The ID of the gateway (if the association is with a gateway).
*/
gatewayId?: string | undefined;
/**
* The state of the association.
*/
associationState: {
state: EC2.RouteTableAssociationStateCode;
statusMessage?: string;
};
},
never,
Providers
> {}
/**
* Associates a {@link RouteTable} with a subnet (or a gateway), making that
* route table govern traffic for the associated resource. A subnet can be
* associated with exactly one route table at a time; multiple subnets may share
* the same route table.
*
* Provide exactly one of `subnetId` or `gatewayId`. Changing the subnet or
* gateway replaces the association, whereas pointing an existing association at
* a different route table is applied in place via
* `ReplaceRouteTableAssociation`.
*
* ### Associating Subnets
* Associating a subnet overrides the VPC's main route table for that subnet.
* This is how you make a subnet "public" (associate it with a table that has an
* internet-gateway route) or "private" (associate it with a NAT-gateway table).
*
* **Example:** Associate a Subnet with a Route Table
* ```typescript
* const association = yield* AWS.EC2.RouteTableAssociation("PublicSubnetAssociation", {
* routeTableId: publicRouteTable.routeTableId,
* subnetId: publicSubnet.subnetId,
* });
* ```
* Binds a single subnet to the route table so its instances follow that
* table's routes. The returned `associationId` (prefixed `rtbassoc-`) can be
* used to track or replace the association.
*
* **Example:** Share One Route Table Across Multiple Subnets
* ```typescript
* const subnet1Association = yield* AWS.EC2.RouteTableAssociation("PublicSubnet1Association", {
* routeTableId: publicRouteTable.routeTableId,
* subnetId: publicSubnet1.subnetId,
* });
*
* const subnet2Association = yield* AWS.EC2.RouteTableAssociation("PublicSubnet2Association", {
* routeTableId: publicRouteTable.routeTableId,
* subnetId: publicSubnet2.subnetId,
* });
* ```
* Declaring multiple associations against the same `routeTableId` gives every
* listed subnet identical routing — a concise way to apply one public (or
* private) routing policy across all subnets in a tier.
*
* ### Associating Gateways (Edge Routing)
* Instead of a subnet, an association can target an internet gateway or
* virtual private gateway via `gatewayId`. This "gateway route table
* association" enables edge routing, where inbound traffic is inspected or
* redirected (e.g. to a firewall appliance) as it enters the VPC.
*
* **Example:** Associate a Route Table with an Internet Gateway
* ```typescript
* const edgeAssociation = yield* AWS.EC2.RouteTableAssociation("EdgeAssociation", {
* routeTableId: ingressRouteTable.routeTableId,
* gatewayId: internetGateway.internetGatewayId,
* });
* ```
* Attaches the route table at the gateway rather than at a subnet, so traffic
* arriving from the internet is steered by this table — typically toward an
* inspection appliance before reaching its destination subnet.
*
* @resource
*/
export const RouteTableAssociation = Resource<RouteTableAssociation>(
"AWS.EC2.RouteTableAssociation",
);
export const RouteTableAssociationProvider = () =>
Provider.effect(
RouteTableAssociation,
Effect.gen(function* () {
return {
stables: ["associationId", "subnetId", "gatewayId"],
// Associations are embedded in describeRouteTables — each RouteTable
// carries an Associations[] of {subnet/gateway, routeTable,
// associationId}. Flatten every page's associations across the region.
// The implicit "main" association (the VPC default route-table binding)
// is skipped: it isn't a standalone resource we create or manage.
list: () =>
ec2.describeRouteTables.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.RouteTables ?? []).flatMap((rt) =>
(rt.Associations ?? [])
.filter(
(
a,
): a is EC2.RouteTableAssociation & {
RouteTableAssociationId: string;
RouteTableId: string;
} =>
a.Main !== true &&
a.RouteTableAssociationId != null &&
a.RouteTableId != null,
)
.map((a) => ({
associationId: a.RouteTableAssociationId as RouteTableAssociationId,
routeTableId: a.RouteTableId as RouteTableId,
subnetId: a.SubnetId as SubnetId | undefined,
gatewayId: a.GatewayId,
associationState: {
state: a.AssociationState?.State ?? "associated",
statusMessage: a.AssociationState?.StatusMessage,
},
})),
),
),
),
),
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return;
// Subnet/Gateway change requires replacement (use ReplaceRouteTableAssociation internally)
if (olds.subnetId !== news.subnetId) {
return { action: "replace" };
}
if (olds.gatewayId !== news.gatewayId) {
return { action: "replace" };
}
// Route table change can be done via ReplaceRouteTableAssociation
}),
// A subnet (or gateway) has at most one route table association, so
// look it up by the subnet/gateway rather than the association id: a
// route table swapped out of band gets a new association id, which
// drift then reports as a changed route table (and repair swaps
// back) instead of a missing association.
read: Effect.fn(function* ({ olds, output }) {
const subnetId = output?.subnetId ?? olds?.subnetId;
const gatewayId = output?.gatewayId ?? olds?.gatewayId;
if (subnetId === undefined && gatewayId === undefined) return undefined;
const lookup = yield* ec2.describeRouteTables({
Filters: [
subnetId !== undefined
? { Name: "association.subnet-id", Values: [subnetId] }
: { Name: "association.gateway-id", Values: [gatewayId!] },
],
});
const assoc = (lookup.RouteTables ?? [])
.flatMap((rt) => rt.Associations ?? [])
.find(
(a) =>
a.Main !== true &&
(subnetId !== undefined ? a.SubnetId === subnetId : a.GatewayId === gatewayId) &&
a.AssociationState?.State !== "disassociated" &&
a.AssociationState?.State !== "disassociating",
);
if (!assoc?.RouteTableAssociationId || !assoc.RouteTableId) return undefined;
return {
associationId: assoc.RouteTableAssociationId as RouteTableAssociationId,
routeTableId: assoc.RouteTableId as RouteTableId,
subnetId: assoc.SubnetId as SubnetId | undefined,
gatewayId: assoc.GatewayId,
associationState: {
state: assoc.AssociationState?.State ?? "associated",
statusMessage: assoc.AssociationState?.StatusMessage,
},
};
}),
reconcile: Effect.fn(function* ({ news, output, session }) {
// Observe — try the cached associationId first; if the association
// was disassociated out-of-band, fall through to AssociateRouteTable.
let observed:
| {
associationId: string;
routeTableId: string;
subnetId?: string;
gatewayId?: string;
state?: EC2.RouteTableAssociationStateCode;
statusMessage?: string;
}
| undefined;
if (output?.associationId) {
const lookup = yield* ec2
.describeRouteTables({
Filters: [
{
Name: "association.route-table-association-id",
Values: [output.associationId],
},
],
})
.pipe(
Effect.catchTag("InvalidRouteTableID.NotFound", () =>
Effect.succeed({ RouteTables: [] }),
),
);
for (const rt of lookup.RouteTables ?? []) {
const assoc = rt.Associations?.find(
(a) => a.RouteTableAssociationId === output.associationId,
);
if (assoc) {
observed = {
associationId: assoc.RouteTableAssociationId!,
routeTableId: assoc.RouteTableId!,
subnetId: assoc.SubnetId,
gatewayId: assoc.GatewayId,
state: assoc.AssociationState?.State,
statusMessage: assoc.AssociationState?.StatusMessage,
};
break;
}
}
}
// Ensure — no existing association ⇒ AssociateRouteTable.
if (observed === undefined) {
const result = yield* ec2
.associateRouteTable({
RouteTableId: news.routeTableId,
SubnetId: news.subnetId,
GatewayId: news.gatewayId,
DryRun: false,
})
.pipe(
Effect.retry({
while: (e) =>
e._tag === "InvalidRouteTableID.NotFound" ||
e._tag === "InvalidSubnetID.NotFound",
schedule: Schedule.exponential(100),
}),
);
const associationId = result.AssociationId! as RouteTableAssociationId;
yield* session.note(`Route table association created: ${associationId}`);
yield* waitForAssociationState(news.routeTableId, associationId, "associated", session);
return {
associationId,
routeTableId: news.routeTableId as RouteTableId,
subnetId: news.subnetId as SubnetId | undefined,
gatewayId: news.gatewayId as string | undefined,
// Waited for above; matches what `read` observes.
associationState: { state: "associated" as const },
};
}
// Sync — drift in routeTableId is patched in place by
// ReplaceRouteTableAssociation. Subnet/gateway changes are
// intercepted upstream by `diff` as a replacement.
if (observed.routeTableId !== (news.routeTableId as string)) {
const result = yield* ec2.replaceRouteTableAssociation({
AssociationId: observed.associationId,
RouteTableId: news.routeTableId,
DryRun: false,
});
const newAssociationId = result.NewAssociationId! as RouteTableAssociationId;
yield* session.note(`Route table association replaced: ${newAssociationId}`);
yield* waitForAssociationState(
news.routeTableId,
newAssociationId,
"associated",
session,
);
return {
associationId: newAssociationId,
routeTableId: news.routeTableId as RouteTableId,
subnetId: news.subnetId as SubnetId | undefined,
gatewayId: news.gatewayId as string | undefined,
// Waited for above; matches what `read` observes.
associationState: { state: "associated" as const },
};
}
// Already in the desired state — just report it.
return {
associationId: observed.associationId as RouteTableAssociationId,
routeTableId: observed.routeTableId as RouteTableId,
subnetId: observed.subnetId as SubnetId | undefined,
gatewayId: observed.gatewayId,
associationState: {
state: observed.state ?? "associated",
statusMessage: observed.statusMessage,
},
};
}),
delete: Effect.fn(function* ({ output, session }) {
yield* session.note(`Deleting route table association: ${output.associationId}`);
// Disassociate the route table
yield* ec2
.disassociateRouteTable({
AssociationId: output.associationId,
DryRun: false,
})
.pipe(
Effect.tapError(Effect.log),
Effect.catchTag("InvalidAssociationID.NotFound", () => Effect.void),
);
yield* session.note(
`Route table association ${output.associationId} deleted successfully`,
);
}),
};
}),
);
/**
* Wait for association to reach a specific state
*/
const waitForAssociationState = (
routeTableId: string,
associationId: string,
targetState: "associating" | "associated" | "disassociating" | "disassociated",
session?: ScopedPlanStatusSession,
) =>
Effect.retry(
Effect.gen(function* () {
const result = yield* ec2.describeRouteTables({ RouteTableIds: [routeTableId] }).pipe(
Effect.catchTag("InvalidRouteTableID.NotFound", () =>
Effect.succeed({
RouteTables: [],
} as ec2.DescribeRouteTablesResult),
),
);
const routeTable = result.RouteTables?.[0];
if (!routeTable) {
return yield* new RouteTableAssociationUnexpectedResponse({
message: "Route table not found",
});
}
const association = routeTable.Associations?.find(
(a) => a.RouteTableAssociationId === associationId,
);
if (!association) {
// Association might not exist yet, retry
return yield* new RouteTableAssociationUnexpectedResponse({
message: "Association not found",
});
}
if (association.AssociationState?.State === targetState) {
return;
}
if (association.AssociationState?.State === "failed") {
return yield* new RouteTableAssociationOperationFailed({
message: `Association failed: ${association.AssociationState.StatusMessage}`,
});
}
// Still in progress, fail to trigger retry
return yield* new RouteTableAssociationNotReady({
message: `Association state: ${association.AssociationState?.State}`,
});
}),
{
schedule: Schedule.max([Schedule.fixed(1000), Schedule.recurs(30)]).pipe(
Schedule.tap(({ attempt }) =>
session
? session.note(`Waiting for association to be ${targetState}... (${attempt}s)`)
: Effect.void,
),
),
},
);