@fjall/components-infrastructure 2.30.3 → 2.32.0

package/dist/lib/resources/aws/compute/ecsNetworking.js

@@ -1,5 +1,5 @@
-import { ApplicationLoadBalancer, ApplicationProtocol, ListenerAction, ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
-import { Port, SubnetType } from "aws-cdk-lib/aws-ec2";
+import { ApplicationProtocol, ListenerAction } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { Port } from "aws-cdk-lib/aws-ec2";
 import { CfnOutput, Duration, Fn } from "aws-cdk-lib";
 import { Certificate, CertificateValidation } from "aws-cdk-lib/aws-certificatemanager";
 import { ARecord, HostedZone as AWSHostedZone, RecordTarget } from "aws-cdk-lib/aws-route53";
@@ -7,25 +7,9 @@ import { LoadBalancerTarget } from "aws-cdk-lib/aws-route53-targets";
 import { HostedZone as FjallHostedZone } from "../networking/hostedZone.js";
 import { SecurityGroup } from "../networking/securityGroup.js";
 import { isServiceEc2 } from "./ecsTaskDefinition.js";
-/** Returns the next unused auto-incremented ALB priority, skipping any manually assigned values. */
-export function getNextPriority(state) {
-    while (state.usedPriorities.has(state.nextPriority)) {
-        state.nextPriority++;
-    }
-    const priority = state.nextPriority++;
-    state.usedPriorities.add(priority);
-    return priority;
-}
-export function buildRoutingConditions(rule) {
-    const conditions = [];
-    if (rule?.path) {
-        conditions.push(ListenerCondition.pathPatterns([rule.path]));
-    }
-    if (rule?.host) {
-        conditions.push(ListenerCondition.hostHeaders([rule.host]));
-    }
-    return conditions;
-}
+import { createApplicationLoadBalancer } from "./applicationLoadBalancer.js";
+import { addRoutingListener } from "./listenerRouting.js";
+import { buildRoutingConditions, getNextPriority } from "./hostHeaderListenerRule.js";
 export function addLoadBalancer(ctx, anyServiceUsesEc2, asgSecurityGroup) {
     const props = ctx.props;
     const defaultLoadBalancerName = `${props.clusterName}LoadBalancer`;
@@ -48,18 +32,13 @@ export function addLoadBalancer(ctx, anyServiceUsesEc2, asgSecurityGroup) {
             asgSecurityGroup.connections.allowFrom(loadBalancerSecurityGroup, Port.tcpRange(49152, 65535));
         }
     }
-    const loadBalancer = new ApplicationLoadBalancer(ctx.scope, `${props.clusterName}LoadBalancer`, {
+    const loadBalancer = createApplicationLoadBalancer(ctx.scope, `${props.clusterName}LoadBalancer`, {
         vpc: ctx.cluster.vpc,
         internetFacing: !isInternal,
+        loadBalancerName: truncatedLoadBalancerName,
         ...(loadBalancerSecurityGroup && {
             securityGroup: loadBalancerSecurityGroup
-        }),
-        loadBalancerName: truncatedLoadBalancerName,
-        vpcSubnets: {
-            subnetType: isInternal
-                ? SubnetType.PRIVATE_WITH_EGRESS
-                : SubnetType.PUBLIC
-        }
+        })
     });
     new CfnOutput(ctx.scope, `${ctx.outputName}LoadBalancerDnsName`, {
         key: `${ctx.outputName}LoadBalancerDnsName`,
@@ -112,25 +91,11 @@ export function addLoadBalancerListener(ctx, loadBalancer, certificate) {
         });
     // CDK rejects listeners with neither a default action nor target groups.
     const noServicePorts = servicesWithPorts.length === 0;
-    const defaultAction = willHaveMultipleRoutes || noServicePorts
-        ? ListenerAction.fixedResponse(404, {
-            contentType: "text/plain",
-            messageBody: "Not Found"
-        })
-        : undefined;
-    if (certificate) {
-        return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
-            port,
-            certificates: [certificate],
-            ...(defaultAction !== undefined && { defaultAction })
-        });
-    }
-    else {
-        return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
-            port,
-            ...(defaultAction !== undefined && { defaultAction })
-        });
-    }
+    return addRoutingListener(loadBalancer, `${ctx.props.clusterName}Listener`, {
+        port,
+        ...(certificate && { certificate }),
+        default404: willHaveMultipleRoutes || noServicePorts
+    });
 }
 export function addHostedZone(ctx, loadBalancer) {
     const props = ctx.props;

package/dist/lib/resources/aws/compute/ecsRoles.d.ts

@@ -1,10 +1,35 @@
 import { Role } from "aws-cdk-lib/aws-iam";
+import type { Construct } from "constructs";
 import type { EcsConstructContext } from "./ecsContext.js";
 import type { EcsServiceProps } from "./ecsTypes.js";
+/**
+ * Builds the base ECS task-execution role shared by every task the platform
+ * runs: the ECR-pull quartet (account-level, so `resources: ["*"]`) and a
+ * ViaService-conditioned `kms:Decrypt` for SSM SecureString / Secrets-Manager
+ * CMK env injection. Pass `ssmSecretsPath` (already derived — no partition/
+ * region/account prefix) to add the path-scoped `ssm:GetParameters` grant.
+ * Trust principal is `ecs-tasks.amazonaws.com`.
+ *
+ * Deliberately omits `logs:*` and `secretsmanager:GetSecretValue`: on the
+ * ECS-pattern path `AwsLogDriver.bind()` and `addContainer({ secrets })`
+ * auto-grant those on the exact LogGroup / secret ARNs. A caller that builds a
+ * SHARED or IMPORTED role those auto-grants cannot reach — e.g. the dev
+ * substrate's slot exec role, referenced by slot task-defs via ARN — MUST add
+ * the explicit `logs` / `secretsmanager` statements itself.
+ */
+export declare function createBaseExecutionRole(scope: Construct, id: string, opts?: {
+    ssmSecretsPath?: string;
+}): Role;
 /**
  * Creates the execution role for ECS infrastructure operations.
  * Used by the ECS agent to pull images, write logs, and inject secrets.
  * NOT used by application code — that's the task role.
+ *
+ * Delegates the ECR/kms/ssm shape to `createBaseExecutionRole`. Logs +
+ * secretsmanager are auto-granted downstream on this path (AwsLogDriver.bind()
+ * on the real LogGroup, addContainer({ secrets }) on the exact secret ARN), so a
+ * hand-rolled `/ecs/{cluster}*` logs or bare `-*` secrets statement here would be
+ * dead (the 2026-06-04 outage shape).
  */
 export declare function createExecutionRole(ctx: EcsConstructContext, serviceName: string): Role;
 /**

package/dist/lib/resources/aws/compute/ecsRoles.js

@@ -2,12 +2,22 @@ import { Stack } from "aws-cdk-lib";
 import { Effect, Policy, PolicyStatement, Role, ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { deriveSsmSecretsPath } from "./ecsTaskDefinition.js";
 /**
- * Creates the execution role for ECS infrastructure operations.
- * Used by the ECS agent to pull images, write logs, and inject secrets.
- * NOT used by application code — that's the task role.
+ * Builds the base ECS task-execution role shared by every task the platform
+ * runs: the ECR-pull quartet (account-level, so `resources: ["*"]`) and a
+ * ViaService-conditioned `kms:Decrypt` for SSM SecureString / Secrets-Manager
+ * CMK env injection. Pass `ssmSecretsPath` (already derived — no partition/
+ * region/account prefix) to add the path-scoped `ssm:GetParameters` grant.
+ * Trust principal is `ecs-tasks.amazonaws.com`.
+ *
+ * Deliberately omits `logs:*` and `secretsmanager:GetSecretValue`: on the
+ * ECS-pattern path `AwsLogDriver.bind()` and `addContainer({ secrets })`
+ * auto-grant those on the exact LogGroup / secret ARNs. A caller that builds a
+ * SHARED or IMPORTED role those auto-grants cannot reach — e.g. the dev
+ * substrate's slot exec role, referenced by slot task-defs via ARN — MUST add
+ * the explicit `logs` / `secretsmanager` statements itself.
  */
-export function createExecutionRole(ctx, serviceName) {
-    const executionRole = new Role(ctx.scope, `${serviceName}ExecutionRole`, {
+export function createBaseExecutionRole(scope, id, opts = {}) {
+    const executionRole = new Role(scope, id, {
         assumedBy: new ServicePrincipal("ecs-tasks.amazonaws.com")
     });
     // GetAuthorizationToken is an account-level API that requires resources: ["*"].
@@ -23,25 +33,13 @@ export function createExecutionRole(ctx, serviceName) {
         ],
         resources: ["*"]
     }));
-    const { partition, region, account } = Stack.of(ctx.scope);
-    // Gotcha: no manual logs grant here. The task definition's AwsLogDriver
-    // binds an explicit LogGroup construct (CFN auto-named — there is NO
-    // `/ecs/{cluster}/...` group; that shape is only the stream prefix), and
-    // `AwsLogDriver.bind()` auto-grants CreateLogStream/PutLogEvents on the
-    // real group's ARN. A hand-rolled `/ecs/{cluster}*` statement grants
-    // access to log groups that do not exist.
-    // Gotcha: do NOT add a manual `secretsImport` grant here. `addContainer({ secrets })`
-    // auto-grants `secret.grantRead(executionRole)` on the resolved complete ARN (exact, no
-    // wildcard). A manual bare/`-*` statement is the 2026-06-04 outage shape and is dead.
-    const serviceProps = ctx.props.services.find((s) => s.name === serviceName);
-    const hasSsmSecrets = serviceProps?.containers.some((container) => container.secrets && container.secrets.length > 0) ?? false;
-    if (hasSsmSecrets && serviceProps) {
-        const ssmPath = deriveSsmSecretsPath(ctx.props, serviceName, serviceProps.ssmSecretsPath);
+    const { partition, region, account } = Stack.of(scope);
+    if (opts.ssmSecretsPath !== undefined) {
         executionRole.addToPolicy(new PolicyStatement({
             effect: Effect.ALLOW,
             actions: ["ssm:GetParameters", "ssm:GetParameter"],
             resources: [
-                `arn:${partition}:ssm:${region}:${account}:parameter${ssmPath}/*`
+                `arn:${partition}:ssm:${region}:${account}:parameter${opts.ssmSecretsPath}/*`
             ]
         }));
     }
@@ -61,6 +59,27 @@ export function createExecutionRole(ctx, serviceName) {
     }));
     return executionRole;
 }
+/**
+ * Creates the execution role for ECS infrastructure operations.
+ * Used by the ECS agent to pull images, write logs, and inject secrets.
+ * NOT used by application code — that's the task role.
+ *
+ * Delegates the ECR/kms/ssm shape to `createBaseExecutionRole`. Logs +
+ * secretsmanager are auto-granted downstream on this path (AwsLogDriver.bind()
+ * on the real LogGroup, addContainer({ secrets }) on the exact secret ARN), so a
+ * hand-rolled `/ecs/{cluster}*` logs or bare `-*` secrets statement here would be
+ * dead (the 2026-06-04 outage shape).
+ */
+export function createExecutionRole(ctx, serviceName) {
+    const serviceProps = ctx.props.services.find((s) => s.name === serviceName);
+    const hasSsmSecrets = serviceProps?.containers.some((container) => container.secrets && container.secrets.length > 0) ?? false;
+    const ssmSecretsPath = hasSsmSecrets && serviceProps
+        ? deriveSsmSecretsPath(ctx.props, serviceName, serviceProps.ssmSecretsPath)
+        : undefined;
+    return createBaseExecutionRole(ctx.scope, `${serviceName}ExecutionRole`, {
+        ssmSecretsPath
+    });
+}
 /**
  * Creates the task role for application code running in the container.
  * This role is assumed by the application, not the ECS agent.

package/dist/lib/resources/aws/compute/hostHeaderListenerRule.d.ts

@@ -0,0 +1,23 @@
+import { ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import type { EcsRoutingConfig } from "./ecsTypes.js";
+/**
+ * Mutable ALB rule-priority state shared across every rule on one listener. The
+ * ECS cluster path and the dev substrate both thread a single instance so
+ * auto-incremented and host-hashed priorities never collide on the same listener.
+ */
+export interface PriorityState {
+    nextPriority: number;
+    usedPriorities: Set<number>;
+}
+/** Returns the next unused auto-incremented ALB priority, skipping any manually assigned values. */
+export declare function getNextPriority(state: PriorityState): number;
+export declare function buildRoutingConditions(rule: EcsRoutingConfig | undefined): ListenerCondition[];
+/**
+ * A deterministic, in-band ALB rule priority for a host-routed slot rule. Same
+ * host → same priority across synths. Collisions (two hosts hashing equal, a
+ * host re-registering, or a manually-claimed priority) are resolved by
+ * open-addressing linear probe with wraparound within the band, claimed against
+ * the shared `usedPriorities`. Throws only if the (40 000-slot) band is exhausted
+ * — unreachable in practice given AWS's per-listener rule ceiling.
+ */
+export declare function deterministicHostPriority(host: string, state: PriorityState): number;

package/dist/lib/resources/aws/compute/hostHeaderListenerRule.js

@@ -0,0 +1,59 @@
+import { ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+/** Returns the next unused auto-incremented ALB priority, skipping any manually assigned values. */
+export function getNextPriority(state) {
+    while (state.usedPriorities.has(state.nextPriority)) {
+        state.nextPriority++;
+    }
+    const priority = state.nextPriority++;
+    state.usedPriorities.add(priority);
+    return priority;
+}
+export function buildRoutingConditions(rule) {
+    const conditions = [];
+    if (rule?.path) {
+        conditions.push(ListenerCondition.pathPatterns([rule.path]));
+    }
+    if (rule?.host) {
+        conditions.push(ListenerCondition.hostHeaders([rule.host]));
+    }
+    return conditions;
+}
+// ALB rule priorities are 1..50000 and unique per listener. Host-hashed slot
+// rules occupy a band DISJOINT from the auto-increment counter (which starts at
+// 100 and climbs — realistically a few hundred at most), so a deterministic slot
+// priority can never collide with an ECS-service rule that shares the same
+// PriorityState. Band [10000, 49999] sits above the counter and below the 50000 max.
+const HOST_PRIORITY_BAND_START = 10_000;
+const HOST_PRIORITY_BAND_SIZE = 40_000;
+/**
+ * FNV-1a 32-bit string hash. Deterministic across processes and machines (no
+ * Math.random / Date), so the same host maps to the same base priority on every
+ * synth — stable rule ordering, no spurious CloudFormation diffs.
+ */
+function fnv1a32(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x0100_0193);
+    }
+    return hash >>> 0;
+}
+/**
+ * A deterministic, in-band ALB rule priority for a host-routed slot rule. Same
+ * host → same priority across synths. Collisions (two hosts hashing equal, a
+ * host re-registering, or a manually-claimed priority) are resolved by
+ * open-addressing linear probe with wraparound within the band, claimed against
+ * the shared `usedPriorities`. Throws only if the (40 000-slot) band is exhausted
+ * — unreachable in practice given AWS's per-listener rule ceiling.
+ */
+export function deterministicHostPriority(host, state) {
+    const base = fnv1a32(host) % HOST_PRIORITY_BAND_SIZE;
+    for (let probe = 0; probe < HOST_PRIORITY_BAND_SIZE; probe++) {
+        const priority = HOST_PRIORITY_BAND_START + ((base + probe) % HOST_PRIORITY_BAND_SIZE);
+        if (!state.usedPriorities.has(priority)) {
+            state.usedPriorities.add(priority);
+            return priority;
+        }
+    }
+    throw new Error(`Exhausted the host-priority band resolving a priority for "${host}"`);
+}

package/dist/lib/resources/aws/compute/imageTagParameter.d.ts

@@ -1,5 +1,15 @@
 import { CfnParameter } from "aws-cdk-lib";
 import { type Construct } from "constructs";
+import { type DockerBuild } from "@fjall/util/manifest/schemas";
+/** Which key namespace is registering the parameter. */
+export type ImageTagEntityKind = "ecs-service" | "lambda-image";
+/** Identity of the entity requesting the parameter, for collision reporting. */
+export interface ImageTagEntity {
+    readonly kind: ImageTagEntityKind;
+    /** ECS: the service name. Lambda: the function's construct id. */
+    readonly declaredBy: string;
+    readonly docker: DockerBuild | undefined;
+}
 /**
  * Get or create the per-key image-tag CfnParameter (logical id from
  * `imageTagParameterName`). Idempotent by logical id: a second call with the
@@ -8,5 +18,12 @@ import { type Construct } from "constructs";
  * than once within a stack). Distinct keys that happen to collide on the same
  * PascalCase logical id fail closed rather than silently aliasing two
  * different things onto one parameter.
+ *
+ * Cross-entity reuse (an ECS service name and a Lambda `image` key sharing
+ * one build key) is allowed only when both declare fingerprint-identical
+ * docker configs — the deliberate shared-build case. Any divergence
+ * (including docker-vs-no-docker) throws at synth, mirroring deploy-core's
+ * `assertNoCrossEntityBuildKeyDivergence`: a shared parameter with divergent
+ * builds means a deploy of either entity silently rolls both onto one image.
  */
-export declare function getOrCreateImageTagParameter(scope: Construct, key: string): CfnParameter;
+export declare function getOrCreateImageTagParameter(scope: Construct, key: string, entity: ImageTagEntity): CfnParameter;

package/dist/lib/resources/aws/compute/imageTagParameter.js

@@ -1,8 +1,16 @@
 import { CfnParameter, Stack } from "aws-cdk-lib";
 import { imageTagParameterName } from "@fjall/util";
+import { dockerBuildFingerprint } from "@fjall/util/manifest/schemas";
+/** Per-parameter entity metadata; WeakMap keeps the registry per-stack and test-safe. */
+const registrations = new WeakMap();
 function buildImageTagDescription(key) {
     return `Image tag for ${key}. Set by fjall deploy to the content-hash tag.`;
 }
+function describeEntity(kind, declaredBy) {
+    return kind === "ecs-service"
+        ? `ECS service "${declaredBy}"`
+        : `Lambda function "${declaredBy}"`;
+}
 /**
  * Get or create the per-key image-tag CfnParameter (logical id from
  * `imageTagParameterName`). Idempotent by logical id: a second call with the
@@ -11,8 +19,15 @@ function buildImageTagDescription(key) {
  * than once within a stack). Distinct keys that happen to collide on the same
  * PascalCase logical id fail closed rather than silently aliasing two
  * different things onto one parameter.
+ *
+ * Cross-entity reuse (an ECS service name and a Lambda `image` key sharing
+ * one build key) is allowed only when both declare fingerprint-identical
+ * docker configs — the deliberate shared-build case. Any divergence
+ * (including docker-vs-no-docker) throws at synth, mirroring deploy-core's
+ * `assertNoCrossEntityBuildKeyDivergence`: a shared parameter with divergent
+ * builds means a deploy of either entity silently rolls both onto one image.
  */
-export function getOrCreateImageTagParameter(scope, key) {
+export function getOrCreateImageTagParameter(scope, key, entity) {
     const stack = Stack.of(scope);
     const paramLogicalId = imageTagParameterName(key);
     const description = buildImageTagDescription(key);
@@ -22,11 +37,26 @@ export function getOrCreateImageTagParameter(scope, key) {
             throw new Error(`CfnParameter logical-ID collision: "${paramLogicalId}" is already registered for a different service. ` +
                 `Distinct service/lambda names cannot share a PascalCase identifier — rename one of the conflicting entries.`);
         }
+        const prior = registrations.get(existing);
+        const fingerprint = dockerBuildFingerprint(entity.docker);
+        if (prior !== undefined && prior.fingerprint !== fingerprint) {
+            throw new Error(`Image-tag parameter collision: ${describeEntity(prior.kind, prior.declaredBy)} and ` +
+                `${describeEntity(entity.kind, entity.declaredBy)} share the build key "${key}" ` +
+                `(CfnParameter "${paramLogicalId}") but declare different docker configs — ` +
+                `a deploy of either would silently roll both onto one image. Rename one of them, ` +
+                `or make the docker configs identical to deliberately share the build.`);
+        }
         return existing;
     }
-    return new CfnParameter(stack, paramLogicalId, {
+    const param = new CfnParameter(stack, paramLogicalId, {
         type: "String",
         default: "latest",
         description
     });
+    registrations.set(param, {
+        kind: entity.kind,
+        declaredBy: entity.declaredBy,
+        fingerprint: dockerBuildFingerprint(entity.docker)
+    });
+    return param;
 }

package/dist/lib/resources/aws/compute/lambda.d.ts

@@ -2,7 +2,7 @@ import { SingletonFunction as singletonFunction, Function, Code, type Runtime, A
 import { type Bucket } from "aws-cdk-lib/aws-s3";
 import { PolicyStatement, type IRole } from "aws-cdk-lib/aws-iam";
 import { type IVpc } from "aws-cdk-lib/aws-ec2";
-import { RetentionDays } from "aws-cdk-lib/aws-logs";
+import type { RetentionDays } from "aws-cdk-lib/aws-logs";
 import { type IQueue } from "aws-cdk-lib/aws-sqs";
 import { type ITable } from "aws-cdk-lib/aws-dynamodb";
 import { type Construct } from "constructs";

package/dist/lib/resources/aws/compute/lambda.js

@@ -7,8 +7,7 @@ import { createHash } from "node:crypto";
 import { SqsEventSource, DynamoEventSource, S3EventSource } from "aws-cdk-lib/aws-lambda-event-sources";
 import { EventType } from "aws-cdk-lib/aws-s3";
 import { PolicyStatement, Effect } from "aws-cdk-lib/aws-iam";
-import { RetentionDays } from "aws-cdk-lib/aws-logs";
-import { LogGroup } from "../logging/logGroup.js";
+import { DEFAULT_FRAMEWORK_LOG_RETENTION, LogGroup } from "../logging/logGroup.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 import { buildParameterPath } from "@fjall/util";
 import { resolveImportedSecret } from "../secrets/index.js";
@@ -95,7 +94,10 @@ export class SingletonFunction extends singletonFunction {
             runtime: props.runtime,
             ephemeralStorageSize: props.ephemeralStorageSize
                 ? Size.mebibytes(props.ephemeralStorageSize)
-                : undefined
+                : undefined,
+            logGroup: new LogGroup(scope, `${id}LogGroup`, {
+                retention: props.logGroupRetention ?? DEFAULT_FRAMEWORK_LOG_RETENTION
+            })
         });
         addPoliciesToRole(this, props.inlinePolicy);
         applyRoleDescription(this, props.roleDescription);
@@ -125,7 +127,7 @@ export class LambdaFunction extends Function {
             description: props.lambdaDescription ?? `${id} Lambda`,
             environment: props.environment,
             logGroup: new LogGroup(scope, `${id}LogGroup`, {
-                retention: props.logGroupRetention ?? RetentionDays.ONE_WEEK
+                retention: props.logGroupRetention ?? DEFAULT_FRAMEWORK_LOG_RETENTION
             })
         });
         addPoliciesToRole(this, props.inlinePolicy);

package/dist/lib/resources/aws/compute/lambdaAlbTarget.d.ts

@@ -0,0 +1,17 @@
+import { type IApplicationTargetGroup } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import type { IFunction } from "aws-cdk-lib/aws-lambda";
+import type { Construct } from "constructs";
+export interface LambdaAlbTargetOptions {
+    readonly handler: IFunction;
+}
+/**
+ * Context-free Lambda-behind-ALB target group. Registering the handler as a
+ * `LambdaTarget` auto-adds the `elasticloadbalancing.amazonaws.com` invoke
+ * permission (CDK's `LambdaTarget.attachToApplicationTargetGroup` → `grantInvoke`),
+ * so no explicit `AWS::Lambda::Permission` is needed.
+ *
+ * Intentionally NOT attached to a listener here — the substrate exports the
+ * target-group ARN (A7) so slot-ops point a sleeping slot's host-header rule at
+ * it (§5.4); an unmatched host still falls through to the listener's 404.
+ */
+export declare function createLambdaTargetGroup(scope: Construct, id: string, options: LambdaAlbTargetOptions): IApplicationTargetGroup;

package/dist/lib/resources/aws/compute/lambdaAlbTarget.js

@@ -0,0 +1,18 @@
+import { ApplicationTargetGroup, TargetType } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { LambdaTarget } from "aws-cdk-lib/aws-elasticloadbalancingv2-targets";
+/**
+ * Context-free Lambda-behind-ALB target group. Registering the handler as a
+ * `LambdaTarget` auto-adds the `elasticloadbalancing.amazonaws.com` invoke
+ * permission (CDK's `LambdaTarget.attachToApplicationTargetGroup` → `grantInvoke`),
+ * so no explicit `AWS::Lambda::Permission` is needed.
+ *
+ * Intentionally NOT attached to a listener here — the substrate exports the
+ * target-group ARN (A7) so slot-ops point a sleeping slot's host-header rule at
+ * it (§5.4); an unmatched host still falls through to the listener's 404.
+ */
+export function createLambdaTargetGroup(scope, id, options) {
+    return new ApplicationTargetGroup(scope, id, {
+        targetType: TargetType.LAMBDA,
+        targets: [new LambdaTarget(options.handler)]
+    });
+}

package/dist/lib/resources/aws/compute/listenerRouting.d.ts

@@ -0,0 +1,21 @@
+import { type ApplicationListener, type ApplicationLoadBalancer } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import type { ICertificate } from "aws-cdk-lib/aws-certificatemanager";
+export interface RoutingListenerOptions {
+    readonly port: number;
+    readonly certificate?: ICertificate;
+    /**
+     * Attach a fixed 404 default action. The ECS path passes this conditionally
+     * (only when ≥2 routes exist or no service has a port — CDK rejects a listener
+     * with neither a default action nor target groups); the dev substrate passes
+     * `true` unconditionally, since its host-header rules are the only routes and
+     * an unmatched host must return 404, not fall through.
+     */
+    readonly default404: boolean;
+}
+/**
+ * Context-free ALB listener factory shared by the ECS cluster path and the dev
+ * substrate. When `default404` is set, the listener's default action is a plain
+ * `404 Not Found` fixed response; otherwise no default action is attached (the
+ * caller's target groups become the listener's default).
+ */
+export declare function addRoutingListener(loadBalancer: ApplicationLoadBalancer, id: string, options: RoutingListenerOptions): ApplicationListener;

package/dist/lib/resources/aws/compute/listenerRouting.js

@@ -0,0 +1,20 @@
+import { ListenerAction } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+/**
+ * Context-free ALB listener factory shared by the ECS cluster path and the dev
+ * substrate. When `default404` is set, the listener's default action is a plain
+ * `404 Not Found` fixed response; otherwise no default action is attached (the
+ * caller's target groups become the listener's default).
+ */
+export function addRoutingListener(loadBalancer, id, options) {
+    const defaultAction = options.default404
+        ? ListenerAction.fixedResponse(404, {
+            contentType: "text/plain",
+            messageBody: "Not Found"
+        })
+        : undefined;
+    return loadBalancer.addListener(id, {
+        port: options.port,
+        ...(options.certificate && { certificates: [options.certificate] }),
+        ...(defaultAction !== undefined && { defaultAction })
+    });
+}

package/dist/lib/resources/aws/database/rdsAurora.d.ts

@@ -10,8 +10,24 @@ interface RdsProps {
     vpc: IVpc;
     databaseName?: string;
     engine?: IClusterEngine;
+    /**
+     * Aurora PostgreSQL version string the `engine` was built at, carried purely
+     * so the auto-pause floor can be validated here (the layer that owns the
+     * min-capacity knob). `undefined` means the engine default (>= 16.3) is in use.
+     */
+    engineVersion?: string;
     engineConfig?: EngineConfig;
     clusterIdentifier?: string;
+    /** Physical name of the generated master-credentials secret. */
+    credentialsSecretName?: string;
+    /** Serverless-v2 floor in ACU. 0 enables scale-to-zero (auto-pause). */
+    serverlessV2MinCapacity?: number;
+    /** Serverless-v2 ceiling in ACU. */
+    serverlessV2MaxCapacity?: number;
+    /** Idle duration before an idle serverless-v2 cluster auto-pauses to 0 ACU. */
+    serverlessV2AutoPauseDuration?: Duration;
+    /** Enables the RDS Data API (HTTP endpoint) on the cluster. */
+    enableDataApi?: boolean;
     writer?: AuroraWriterConfig;
     readers?: AuroraReadersConfig | false;
     proxy?: ProxyConfig | false;

package/dist/lib/resources/aws/database/rdsAurora.js

@@ -8,10 +8,49 @@ import { Secret } from "../secrets/index.js";
 import { ResourceNaming } from "../../../utils/resourceNaming.js";
 import { addProxyCfnOutput } from "./rdsProxyOutput.js";
 import { getDatabaseInsightsRetention } from "./index.js";
-import { RDS_DEFAULTS } from "./rdsDefaults.js";
+import { RDS_DEFAULTS, SERVERLESS_V2_AUTO_PAUSE_MIN_SECONDS, SERVERLESS_V2_AUTO_PAUSE_MAX_SECONDS, MIN_AUTO_PAUSE_POSTGRES_VERSION } from "./rdsDefaults.js";
 import { createRdsAlarms } from "../monitoring/index.js";
 import { DEFAULT_POSTGRES_ENGINE_CONFIG, resolveDatabaseInsights, resolveStorageEncryptionKey, resolvePerformanceInsightsKey, addMultiUserSecretRotation, warnIfSnapshotUsernameAssumed } from "./rdsHelpers.js";
 import { resolveSecretRotation } from "../../../utils/databaseTypes.js";
+function parsePostgresVersion(version) {
+    const parts = version.split(".");
+    return {
+        major: parseInt(parts[0] ?? "", 10),
+        minor: parseInt(parts[1] ?? "0", 10)
+    };
+}
+function assertAutoPauseCapablePostgresVersion(engineVersion) {
+    const { major, minor } = parsePostgresVersion(engineVersion);
+    if (Number.isNaN(major) || Number.isNaN(minor)) {
+        throw new Error(`Invalid Aurora engineVersion "${engineVersion}" (expected "<major>.<minor>")`);
+    }
+    const floor = parsePostgresVersion(MIN_AUTO_PAUSE_POSTGRES_VERSION);
+    const meetsFloor = major > floor.major || (major === floor.major && minor >= floor.minor);
+    if (!meetsFloor) {
+        throw new Error(`serverlessV2MinCapacity 0 requires Aurora PostgreSQL >= ${MIN_AUTO_PAUSE_POSTGRES_VERSION} for auto-pause; received engineVersion "${engineVersion}"`);
+    }
+}
+function validateServerlessV2DevKnobs(props) {
+    const min = props.serverlessV2MinCapacity;
+    const max = props.serverlessV2MaxCapacity;
+    if (min !== undefined && max !== undefined && min > max) {
+        throw new Error(`serverlessV2MinCapacity (${min}) must be <= serverlessV2MaxCapacity (${max})`);
+    }
+    if (props.serverlessV2AutoPauseDuration !== undefined) {
+        const seconds = props.serverlessV2AutoPauseDuration.toSeconds();
+        if (seconds < SERVERLESS_V2_AUTO_PAUSE_MIN_SECONDS ||
+            seconds > SERVERLESS_V2_AUTO_PAUSE_MAX_SECONDS) {
+            throw new Error(`serverlessV2AutoPauseDuration must be between ${SERVERLESS_V2_AUTO_PAUSE_MIN_SECONDS}s and ${SERVERLESS_V2_AUTO_PAUSE_MAX_SECONDS}s; received ${seconds}s`);
+        }
+    }
+    // Floor enforced only via engineVersion (opaque `IClusterEngine` can't be
+    // introspected): a raw `engine` below the floor with min 0 and no version is
+    // the caller's own risk. No such caller exists — DevSubstrate always passes
+    // engineVersion.
+    if (min === 0 && props.engineVersion !== undefined) {
+        assertAutoPauseCapablePostgresVersion(props.engineVersion);
+    }
+}
 export class RdsAurora extends Construct {
     connections;
     constructId;
@@ -25,6 +64,7 @@ export class RdsAurora extends Construct {
     databaseNameValue;
     constructor(scope, id, props) {
         super(scope, id);
+        validateServerlessV2DevKnobs(props);
         this.constructId = id;
         this.databaseNameValue = props.databaseName ?? id;
         // PostgreSQL fallback for direct usage - ensure engine and engineConfig match
@@ -44,7 +84,8 @@ export class RdsAurora extends Construct {
         // Global secondary clusters import replicated secret instead of creating new
         if (props.isGlobalSecondary) {
             this.databaseCredentials = new Secret(this, `${this.databaseNameValue}Credentials`, {
-                secretName: ResourceNaming.credentialsSecretName(id),
+                secretName: props.credentialsSecretName ??
+                    ResourceNaming.credentialsSecretName(id),
                 importExisting: true
             });
         }
@@ -57,7 +98,8 @@ export class RdsAurora extends Construct {
                 assumedUsername: username
             });
             this.databaseCredentials = new Secret(this, `${this.databaseNameValue}Credentials`, {
-                secretName: ResourceNaming.credentialsSecretName(id),
+                secretName: props.credentialsSecretName ??
+                    ResourceNaming.credentialsSecretName(id),
                 generateSecretString: {
                     secretStringTemplate: JSON.stringify({ username }),
                     excludePunctuation: true,
@@ -140,6 +182,18 @@ export class RdsAurora extends Construct {
             removalPolicy: RemovalPolicy.SNAPSHOT,
             deletionProtection: props.deletionProtection ?? true,
             iamAuthentication: true,
+            ...(props.serverlessV2MinCapacity !== undefined && {
+                serverlessV2MinCapacity: props.serverlessV2MinCapacity
+            }),
+            ...(props.serverlessV2MaxCapacity !== undefined && {
+                serverlessV2MaxCapacity: props.serverlessV2MaxCapacity
+            }),
+            ...(props.serverlessV2AutoPauseDuration !== undefined && {
+                serverlessV2AutoPauseDuration: props.serverlessV2AutoPauseDuration
+            }),
+            ...(props.enableDataApi !== undefined && {
+                enableDataApi: props.enableDataApi
+            }),
             writer,
             readers
         };