import type * as EC2 from "@distilled.cloud/aws/ec2";
import * as ec2 from "@distilled.cloud/aws/ec2";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import type { ScopedPlanStatusSession } from "alchemy/Report";
import { Resource } from "alchemy/Resource";
import { createInternalTags, createTagsList, diffTags, hasAlchemyTags } from "alchemy/Tags";
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 { AccountID } from "../Environment.ts";
import { AWSEnvironment } from "../Environment.ts";
import { tagListRecord } from "../internal/Observe.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
import type { VpcId } from "./Vpc.ts";
export class RouteTableNotReady extends Data.TaggedError("RouteTableNotReady")<{
readonly message: string;
readonly cause?: unknown;
}> {}
export type RouteTableId<ID extends string = string> = `rtb-${ID}`;
export const RouteTableId = <ID extends string>(id: ID): ID & RouteTableId<ID> =>
`rtb-${id}` as ID & RouteTableId<ID>;
export interface RouteTableProps {
/**
* The VPC to create the route table in.
* Required.
*/
vpcId: VpcId;
/**
* Tags to assign to the route table.
* These will be merged with alchemy auto-tags (alchemy::stack, alchemy::stage, alchemy::id).
*/
tags?: Record<string, string>;
}
export interface RouteTable extends Resource<
"AWS.EC2.RouteTable",
RouteTableProps,
{
/**
* The ID of the VPC the route table is in.
*/
vpcId: VpcId;
/**
* The ID of the route table.
*/
routeTableId: RouteTableId;
/**
* The Amazon Resource Name (ARN) of the route table.
*/
routeTableArn: `arn:aws:ec2:${RegionID}:${AccountID}:route-table/${string}`;
/**
* The ID of the AWS account that owns the route table.
*/
ownerId?: string;
/**
* The associations between the route table and subnets or gateways.
*/
associations?: Array<{
/**
* Whether this is the main route table for the VPC.
*/
main: boolean;
/**
* The ID of the association.
*/
routeTableAssociationId?: string;
/**
* The ID of the route table.
*/
routeTableId?: string;
/**
* The ID of the subnet (if the association is with a subnet).
*/
subnetId?: string;
/**
* The ID of the gateway (if the association is with a gateway).
*/
gatewayId?: string;
/**
* The state of the association.
*/
associationState?: {
state: EC2.RouteTableAssociationStateCode;
statusMessage?: string;
};
}>;
/**
* The routes in the route table.
*/
routes?: Array<{
/**
* The IPv4 CIDR block used for the destination match.
*/
destinationCidrBlock?: string;
/**
* The IPv6 CIDR block used for the destination match.
*/
destinationIpv6CidrBlock?: string;
/**
* The prefix of the AWS service.
*/
destinationPrefixListId?: string;
/**
* The ID of the egress-only internet gateway.
*/
egressOnlyInternetGatewayId?: string;
/**
* The ID of the gateway (internet gateway or virtual private gateway).
*/
gatewayId?: string;
/**
* The ID of the NAT instance.
*/
instanceId?: string;
/**
* The ID of AWS account that owns the NAT instance.
*/
instanceOwnerId?: string;
/**
* The ID of the NAT gateway.
*/
natGatewayId?: string;
/**
* The ID of the transit gateway.
*/
transitGatewayId?: string;
/**
* The ID of the local gateway.
*/
localGatewayId?: string;
/**
* The ID of the carrier gateway.
*/
carrierGatewayId?: string;
/**
* The ID of the network interface.
*/
networkInterfaceId?: string;
/**
* Describes how the route was created.
*/
origin: EC2.RouteOrigin;
/**
* The state of the route.
*/
state: EC2.RouteState;
/**
* The ID of the VPC peering connection.
*/
vpcPeeringConnectionId?: string;
/**
* The Amazon Resource Name (ARN) of the core network.
*/
coreNetworkArn?: string;
}>;
/**
* Any virtual private gateway (VGW) propagating routes.
*/
propagatingVgws?: Array<{
gatewayId: string;
}>;
/**
* Tags on the route table, as observed. Lets `alchemy drift` detect
* out-of-band changes.
*/
tags?: Record<string, string>;
},
never,
Providers
> {}
/**
* A VPC route table holds a set of routes that determine where network
* traffic from associated subnets (or gateways) is directed. Create one
* route table per routing domain — typically a "public" table whose default
* route points at an {@link InternetGateway}, and one or more "private" tables
* whose default route points at a NAT gateway.
*
* A route table is little more than a container: it owns a `vpcId` and tags,
* while the actual routing behaviour is supplied by separate {@link Route}
* resources and applied to subnets by {@link RouteTableAssociation} resources.
*
* ### Creating a Route Table
* The only required input is the `vpcId` the table belongs to. Changing
* `vpcId` later replaces the route table, since a table cannot move between
* VPCs.
*
* **Example:** Basic Route Table
* ```typescript
* const routeTable = yield* AWS.EC2.RouteTable("PublicRouteTable", {
* vpcId: myVpc.vpcId,
* });
* ```
* Creates an empty route table in the given VPC. It starts with only the
* implicit `local` route (managed by AWS) until you add your own
* {@link Route} resources.
*
* **Example:** Route Table with Tags
* ```typescript
* const routeTable = yield* AWS.EC2.RouteTable("PrivateRouteTable", {
* vpcId: myVpc.vpcId,
* tags: { Name: "private-rt", Tier: "private" },
* });
* ```
* The `tags` map is merged with the alchemy auto-tags (`alchemy::stack`,
* `alchemy::stage`, `alchemy::id`) and can be updated in place without
* replacing the table. Use the `Name` tag to label the table in the AWS
* console.
*
* ### Building a Public Routing Domain
* A route table only directs traffic once you attach routes to it and
* associate it with subnets. The pattern below wires a public subnet to the
* internet: an {@link InternetGateway}, a default {@link Route} pointing at it,
* and a {@link RouteTableAssociation} binding the subnet to the table.
*
* **Example:** Route Table, Internet Route, and Subnet Association
* ```typescript
* const internetGateway = yield* AWS.EC2.InternetGateway("InternetGateway", {
* vpcId: myVpc.vpcId,
* });
*
* const publicRouteTable = yield* AWS.EC2.RouteTable("PublicRouteTable", {
* vpcId: myVpc.vpcId,
* });
*
* const internetRoute = yield* AWS.EC2.Route("InternetRoute", {
* routeTableId: publicRouteTable.routeTableId,
* destinationCidrBlock: "0.0.0.0/0",
* gatewayId: internetGateway.internetGatewayId,
* });
*
* const association = yield* AWS.EC2.RouteTableAssociation("PublicSubnetAssociation", {
* routeTableId: publicRouteTable.routeTableId,
* subnetId: publicSubnet.subnetId,
* });
* ```
* Any subnet associated with this table now reaches the public internet via
* the `0.0.0.0/0` route. Multiple subnets can share the same route table by
* declaring additional associations — a common way to give every public
* subnet in a VPC identical routing.
*
* @resource
*/
export const RouteTable = Resource<RouteTable>("AWS.EC2.RouteTable");
export const RouteTableProvider = () =>
Provider.effect(
RouteTable,
Effect.gen(function* () {
return {
stables: ["routeTableId", "ownerId", "routeTableArn", "vpcId"],
list: () =>
Effect.gen(function* () {
const { accountId, region } = yield* AWSEnvironment.current;
return yield* ec2.describeRouteTables.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) =>
Array.from(chunk).flatMap((page) =>
(page.RouteTables ?? [])
.filter(
(rt): rt is ec2.RouteTable & { RouteTableId: string } =>
rt.RouteTableId != null &&
// Every VPC has an implicit main route table. AWS does
// not allow deleting it directly; deleting the VPC
// removes it automatically.
!rt.Associations?.some((assoc) => assoc.Main === true),
)
.map((rt) => {
const routeTableId = rt.RouteTableId as RouteTableId;
return {
routeTableId,
routeTableArn:
`arn:aws:ec2:${region}:${accountId}:route-table/${routeTableId}` as `arn:aws:ec2:${RegionID}:${AccountID}:route-table/${string}`,
vpcId: rt.VpcId as VpcId,
ownerId: rt.OwnerId,
associations: rt.Associations?.map((assoc) => ({
main: assoc.Main ?? false,
routeTableAssociationId: assoc.RouteTableAssociationId,
routeTableId: assoc.RouteTableId,
subnetId: assoc.SubnetId,
gatewayId: assoc.GatewayId,
associationState: assoc.AssociationState
? {
state: assoc.AssociationState.State!,
statusMessage: assoc.AssociationState.StatusMessage,
}
: undefined,
})),
routes: rt.Routes?.map((route) => ({
destinationCidrBlock: route.DestinationCidrBlock,
destinationIpv6CidrBlock: route.DestinationIpv6CidrBlock,
destinationPrefixListId: route.DestinationPrefixListId,
egressOnlyInternetGatewayId: route.EgressOnlyInternetGatewayId,
gatewayId: route.GatewayId,
instanceId: route.InstanceId,
instanceOwnerId: route.InstanceOwnerId,
natGatewayId: route.NatGatewayId,
transitGatewayId: route.TransitGatewayId,
localGatewayId: route.LocalGatewayId,
carrierGatewayId: route.CarrierGatewayId,
networkInterfaceId: route.NetworkInterfaceId,
origin: route.Origin!,
state: route.State!,
vpcPeeringConnectionId: route.VpcPeeringConnectionId,
coreNetworkArn: route.CoreNetworkArn,
})),
propagatingVgws: rt.PropagatingVgws?.map((vgw) => ({
gatewayId: vgw.GatewayId!,
})),
};
}),
),
),
);
}),
diff: Effect.fn(function* ({ news, olds }) {
if (!isResolved(news)) return;
// VpcId change requires replacement
if (olds.vpcId !== news.vpcId) {
return { action: "replace" };
}
// Tags can be updated in-place
}),
// The table owns only its existence and tags. Its routes and
// associations are managed by `Route` and `RouteTableAssociation`
// (which observe them), so the persisted snapshot is carried forward
// instead of reporting their changes as this table's drift.
read: Effect.fn(function* ({ id, output }) {
if (!output?.routeTableId) return undefined;
const routeTable = (yield* ec2
.describeRouteTables({ RouteTableIds: [output.routeTableId] })
.pipe(
Effect.catchTag("InvalidRouteTableID.NotFound", () =>
Effect.succeed({ RouteTables: [] }),
),
)).RouteTables?.[0];
if (!routeTable?.RouteTableId) return undefined;
const tags = tagListRecord(routeTable.Tags);
const attrs = { ...output, ownerId: routeTable.OwnerId, tags };
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const { accountId, region } = yield* AWSEnvironment.current;
const alchemyTags = yield* createInternalTags(id);
const desiredTags = { ...alchemyTags, ...news.tags };
// Observe — find the route table via cached id, else fall through
// to create.
let routeTable: ec2.RouteTable | undefined;
if (output?.routeTableId) {
const lookup = yield* ec2
.describeRouteTables({ RouteTableIds: [output.routeTableId] })
.pipe(
Effect.catchTag("InvalidRouteTableID.NotFound", () =>
Effect.succeed({ RouteTables: [] }),
),
);
routeTable = lookup.RouteTables?.[0];
}
// Ensure — create the route table when missing.
if (routeTable === undefined) {
const createResult = yield* ec2
.createRouteTable({
VpcId: news.vpcId,
TagSpecifications: [
{
ResourceType: "route-table",
Tags: createTagsList(desiredTags),
},
],
DryRun: false,
})
.pipe(
Effect.retry({
while: (e) => e._tag === "InvalidVpcID.NotFound",
schedule: Schedule.max([Schedule.fixed(500), Schedule.recurs(10)]),
}),
);
const newId = createResult.RouteTable!.RouteTableId! as RouteTableId;
yield* session.note(`Route table created: ${newId}`);
routeTable = yield* describeRouteTable(newId, session);
}
const routeTableId = routeTable.RouteTableId! as RouteTableId;
// Sync tags — observed cloud tags vs desired.
const currentTags = Object.fromEntries(
(routeTable.Tags ?? []).map((t) => [t.Key!, t.Value!]),
) as Record<string, string>;
const { removed, upsert } = diffTags(currentTags, desiredTags);
if (removed.length > 0) {
yield* ec2.deleteTags({
Resources: [routeTableId],
Tags: removed.map((key) => ({ Key: key })),
});
}
if (upsert.length > 0) {
yield* ec2.createTags({
Resources: [routeTableId],
Tags: upsert,
});
}
// Re-read final state.
const final = yield* describeRouteTable(routeTableId, session);
return {
routeTableId,
routeTableArn:
`arn:aws:ec2:${region}:${accountId}:route-table/${routeTableId}` as `arn:aws:ec2:${RegionID}:${AccountID}:route-table/${string}`,
vpcId: news.vpcId as VpcId,
ownerId: final.OwnerId,
associations: final.Associations?.map((assoc) => ({
main: assoc.Main ?? false,
routeTableAssociationId: assoc.RouteTableAssociationId,
routeTableId: assoc.RouteTableId,
subnetId: assoc.SubnetId,
gatewayId: assoc.GatewayId,
associationState: assoc.AssociationState
? {
state: assoc.AssociationState.State!,
statusMessage: assoc.AssociationState.StatusMessage,
}
: undefined,
})),
routes: final.Routes?.map((route) => ({
destinationCidrBlock: route.DestinationCidrBlock,
destinationIpv6CidrBlock: route.DestinationIpv6CidrBlock,
destinationPrefixListId: route.DestinationPrefixListId,
egressOnlyInternetGatewayId: route.EgressOnlyInternetGatewayId,
gatewayId: route.GatewayId,
instanceId: route.InstanceId,
instanceOwnerId: route.InstanceOwnerId,
natGatewayId: route.NatGatewayId,
transitGatewayId: route.TransitGatewayId,
localGatewayId: route.LocalGatewayId,
carrierGatewayId: route.CarrierGatewayId,
networkInterfaceId: route.NetworkInterfaceId,
origin: route.Origin!,
state: route.State!,
vpcPeeringConnectionId: route.VpcPeeringConnectionId,
coreNetworkArn: route.CoreNetworkArn,
})),
propagatingVgws: final.PropagatingVgws?.map((vgw) => ({
gatewayId: vgw.GatewayId!,
})),
tags: tagListRecord(final.Tags),
};
}),
delete: Effect.fn(function* ({ output, session }) {
const routeTableId = output.routeTableId;
yield* session.note(`Deleting route table: ${routeTableId}`);
// 1. Attempt to delete route table
yield* ec2
.deleteRouteTable({
RouteTableId: routeTableId,
DryRun: false,
})
.pipe(
Effect.tapError(Effect.logDebug),
Effect.catchTag("InvalidRouteTableID.NotFound", () => Effect.void),
// Retry on dependency violations (associations still being deleted)
Effect.retry({
// DependencyViolation means there are still dependent resources
while: (e) => e._tag === "DependencyViolation",
schedule: Schedule.max([Schedule.fixed(3000), Schedule.recurs(10)]).pipe(
Schedule.tap(({ attempt }) =>
session.note(`Waiting for dependencies to clear... (attempt ${attempt})`),
),
),
}),
);
// 2. Wait for route table to be fully deleted
yield* waitForRouteTableDeleted(routeTableId, session);
yield* session.note(`Route table ${routeTableId} deleted successfully`);
}),
};
}),
);
/**
* Describe a route table by ID
*/
const describeRouteTable = (routeTableId: string, _session?: ScopedPlanStatusSession) =>
Effect.gen(function* () {
const result = yield* ec2
.describeRouteTables({ RouteTableIds: [routeTableId] })
.pipe(
Effect.catchTag("InvalidRouteTableID.NotFound", () => Effect.succeed({ RouteTables: [] })),
);
const routeTable = result.RouteTables?.[0];
if (!routeTable) {
// createRouteTable can return before the new ID is visible to
// describeRouteTables. Keep the ID in this reconcile and retry the
// observation instead of failing after create and losing the only
// handle the engine has for cleanup.
return yield* new RouteTableNotVisible({ routeTableId });
}
return routeTable;
}).pipe(
Effect.retry({
while: (error) => error instanceof RouteTableNotVisible,
schedule: Schedule.max([Schedule.fixed(500), Schedule.recurs(10)]),
}),
);
class RouteTableNotVisible extends Data.TaggedError("RouteTableNotVisible")<{
routeTableId: string;
}> {}
/**
* Wait for route table to be deleted
*/
const waitForRouteTableDeleted = (routeTableId: string, session: ScopedPlanStatusSession) =>
Effect.retry(
Effect.gen(function* () {
const result = yield* ec2.describeRouteTables({ RouteTableIds: [routeTableId] }).pipe(
Effect.tapError(Effect.logDebug),
Effect.catchTag("InvalidRouteTableID.NotFound", () => Effect.succeed({ RouteTables: [] })),
);
if (!result.RouteTables || result.RouteTables.length === 0) {
return; // Successfully deleted
}
// Still exists, fail to trigger retry
return yield* new RouteTableNotReady({ message: "Route table still exists" });
}),
{
schedule: Schedule.max([Schedule.fixed(2000), Schedule.recurs(10)]).pipe(
Schedule.tap(({ attempt }) =>
session.note(`Waiting for route table deletion... (${attempt * 2}s)`),
),
),
},
);