@fjall/components-infrastructure 0.95.0 → 0.99.1

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

@@ -1,4 +1,4 @@
-import { Cluster as CdkCluster, type FargateService, type Ec2Service } from "aws-cdk-lib/aws-ecs";
+import { Cluster as CdkCluster, type FargateService, type Ec2Service, type TaskDefinition } from "aws-cdk-lib/aws-ecs";
 import { Connections, type IConnectable } from "aws-cdk-lib/aws-ec2";
 import { Construct } from "constructs";
 import type { StackBuilder } from "../base/awsStack.js";
@@ -56,6 +56,7 @@ export default class EcsCluster extends Construct implements IConnectable {
     private certificate?;
     private asgState;
     private services;
+    private scheduledTaskDefinitions;
     private scope;
     private props;
     private outputName;
@@ -72,8 +73,33 @@ export default class EcsCluster extends Construct implements IConnectable {
     getService(name: string): FargateService | Ec2Service | undefined;
     /** Get all services in this cluster. */
     getServices(): Map<string, FargateService | Ec2Service>;
+    /**
+     * Get the task definition for a service or a registered scheduled task.
+     * Used by Schedule / Subscription targets to construct the EcsTask adapter
+     * for EventBridge invocation. Returns undefined for unknown names — callers
+     * MUST validate before passing to `resolveTarget(...)`.
+     */
+    getTaskDefinition(serviceName: string): TaskDefinition | undefined;
+    /**
+     * Register a `Ec2TaskDefinition` under a synthetic name so it can be
+     * resolved by `app.addSchedule(...)` against the existing
+     * `EcsScheduleTarget` shape (AC34). Throws if `name` collides with any
+     * steady-state service name OR a previously-registered scheduled task.
+     */
+    registerScheduledTaskDefinition(name: string, taskDefinition: TaskDefinition): void;
     /** Get the ECS cluster construct. */
     getCluster(): CdkCluster;
+    /**
+     * Get the EC2 instance role for the cluster's ASG (D10). Returns undefined
+     * for Fargate-only clusters. Pulled from the shared ASG capacity state.
+     */
+    getInstanceRole(): import("aws-cdk-lib/aws-iam").IRole | undefined;
+    /**
+     * Get the underlying ASG's `autoScalingGroupName` token (string-only,
+     * not the ASG construct itself — D10 forbids ASG-typed accessors).
+     * Used by alarm helpers that need CloudWatch dimension keys.
+     */
+    getAutoScalingGroupName(): string | undefined;
     /** Get the ALB URL (http:// or https://). */
     getUrl(): string | undefined;
     /**

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

@@ -69,8 +69,8 @@ export default class EcsCluster extends Construct {
         autoScalingGroup: undefined,
         asgSecurityGroup: undefined
     };
-    // Per-service tracking
     services = new Map();
+    scheduledTaskDefinitions = new Map();
     // Configuration
     scope;
     props;
@@ -147,10 +147,50 @@ export default class EcsCluster extends Construct {
         }
         return result;
     }
+    /**
+     * Get the task definition for a service or a registered scheduled task.
+     * Used by Schedule / Subscription targets to construct the EcsTask adapter
+     * for EventBridge invocation. Returns undefined for unknown names — callers
+     * MUST validate before passing to `resolveTarget(...)`.
+     */
+    getTaskDefinition(serviceName) {
+        return (this.services.get(serviceName)?.taskDefinition ??
+            this.scheduledTaskDefinitions.get(serviceName));
+    }
+    /**
+     * Register a `Ec2TaskDefinition` under a synthetic name so it can be
+     * resolved by `app.addSchedule(...)` against the existing
+     * `EcsScheduleTarget` shape (AC34). Throws if `name` collides with any
+     * steady-state service name OR a previously-registered scheduled task.
+     */
+    registerScheduledTaskDefinition(name, taskDefinition) {
+        if (this.services.has(name)) {
+            throw new Error(`Scheduled task name '${name}' collides with a steady-state service in cluster '${this.props.clusterName}'.`);
+        }
+        if (this.scheduledTaskDefinitions.has(name)) {
+            throw new Error(`Scheduled task name '${name}' is already registered in cluster '${this.props.clusterName}'.`);
+        }
+        this.scheduledTaskDefinitions.set(name, taskDefinition);
+    }
     /** Get the ECS cluster construct. */
     getCluster() {
         return this.cluster;
     }
+    /**
+     * Get the EC2 instance role for the cluster's ASG (D10). Returns undefined
+     * for Fargate-only clusters. Pulled from the shared ASG capacity state.
+     */
+    getInstanceRole() {
+        return this.asgState.autoScalingGroup?.role;
+    }
+    /**
+     * Get the underlying ASG's `autoScalingGroupName` token (string-only,
+     * not the ASG construct itself — D10 forbids ASG-typed accessors).
+     * Used by alarm helpers that need CloudWatch dimension keys.
+     */
+    getAutoScalingGroupName() {
+        return this.asgState.autoScalingGroup?.autoScalingGroupName;
+    }
     /** Get the ALB URL (http:// or https://). */
     getUrl() {
         if (!this.loadBalancer)
@@ -199,7 +239,7 @@ export default class EcsCluster extends Construct {
                 );
             }
             catch (error) {
-                throw new Error(`Failed to process connections for ECS service '${serviceName}': ${error instanceof Error ? error.message : String(error)}`);
+                throw new Error(`Failed to process connections for ECS service '${serviceName}': ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
         }
         // Per-service alarm wiring (shared topic on cluster, thresholds per service)

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

@@ -3,6 +3,15 @@ export declare const DEFAULT_EC2_INSTANCE_TYPE = "t4g.micro";
 export declare const DEFAULT_WARM_POOL_MIN_SIZE = 1;
 export declare const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = true;
 export declare const DEFAULT_LOG_RETENTION_DAYS = 14;
+export declare const DEFAULT_FARGATE_CPU = 256;
+export declare const DEFAULT_FARGATE_MEMORY_MIB = 512;
+export declare const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
+export declare const DEFAULT_ECS_FALLBACK_IMAGE = "amazon/amazon-ecs-sample";
+export declare const DEFAULT_CUSTOM_RESOURCE_TIMEOUT_SECONDS = 300;
+export declare const DEFAULT_HEALTH_CHECK_GRACE_SECONDS = 120;
+export declare const DEFAULT_MIN_HEALTHY_PERCENT = 100;
+export declare const DEFAULT_MAX_HEALTHY_PERCENT = 200;
+export declare const DEFAULT_DESIRED_COUNT = 2;
 /**
  * Instance type prefixes that use ARM64 architecture (Graviton processors).
  * All other prefixes are assumed to be x86-64 (STANDARD).

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

@@ -5,6 +5,22 @@ export const DEFAULT_WARM_POOL_MIN_SIZE = 1;
 export const DEFAULT_WARM_POOL_REUSE_ON_SCALE_IN = true;
 // 14 days balances cost against retaining enough history for post-mortem debugging
 export const DEFAULT_LOG_RETENTION_DAYS = 14;
+// Smallest valid (cpu, memory) pair on the Fargate matrix — must move together.
+export const DEFAULT_FARGATE_CPU = 256;
+export const DEFAULT_FARGATE_MEMORY_MIB = 512;
+export const DEFAULT_EC2_CONTAINER_MEMORY_MIB = 1024;
+// AWS sample image used when no ECR repository is provided. Consumed by both
+// the resources/ image resolver and the patterns/ defaults block — keep them
+// in lockstep via this single export.
+export const DEFAULT_ECS_FALLBACK_IMAGE = "amazon/amazon-ecs-sample";
+// 5 minutes matches the Lambda service default; CDK uses it for sync providers.
+export const DEFAULT_CUSTOM_RESOURCE_TIMEOUT_SECONDS = 300;
+// 100/200 must move together — the rolling-deploy window relies on the gap.
+export const DEFAULT_HEALTH_CHECK_GRACE_SECONDS = 120;
+export const DEFAULT_MIN_HEALTHY_PERCENT = 100;
+export const DEFAULT_MAX_HEALTHY_PERCENT = 200;
+// Read at two sites (createService initial count + addServiceScaling derive-base) that must agree.
+export const DEFAULT_DESIRED_COUNT = 2;
 /**
  * Instance type prefixes that use ARM64 architecture (Graviton processors).
  * All other prefixes are assumed to be x86-64 (STANDARD).

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

@@ -1,35 +1,47 @@
+import { CfnParameter, Stack } from "aws-cdk-lib";
 import { ContainerImage } from "aws-cdk-lib/aws-ecs";
 import { Repository } from "aws-cdk-lib/aws-ecr";
+import { DEFAULT_ECS_FALLBACK_IMAGE } from "./ecsConstants.js";
+import { toPascalCase } from "../../../utils/capitaliseString.js";
+function buildImageTagDescription(serviceName) {
+    return `Image tag for ECS service ${serviceName}. Set by fjall deploy to the content-hash tag.`;
+}
+function getOrCreateImageTagParameter(ctx, serviceName) {
+    const stack = Stack.of(ctx.scope);
+    const paramLogicalId = `${toPascalCase(serviceName)}ImageTag`;
+    const description = buildImageTagDescription(serviceName);
+    const existing = stack.node.tryFindChild(paramLogicalId);
+    if (existing instanceof CfnParameter) {
+        if (existing.description !== description) {
+            throw new Error(`CfnParameter logical-ID collision: "${paramLogicalId}" is already registered for a different service. ` +
+                `Distinct service names cannot share a PascalCase identifier — rename one of the conflicting services.`);
+        }
+        return existing;
+    }
+    return new CfnParameter(stack, paramLogicalId, {
+        type: "String",
+        default: "latest",
+        description
+    });
+}
 export function getContainerImage(ctx, serviceName, containerConfig, serviceProps) {
     const imageSource = containerConfig.image || serviceProps.image || ctx.props.ecrRepository;
     if (!imageSource) {
-        return ContainerImage.fromRegistry("amazon/amazon-ecs-sample");
+        return ContainerImage.fromRegistry(DEFAULT_ECS_FALLBACK_IMAGE);
     }
-    // Build image tag with optional dockerTarget suffix
-    // Format: <service>-[<target>-]<version>
-    // imageVersion comes from CDK context (git SHA) to ensure CloudFormation
-    // detects template changes when new code is deployed. Falls back to 'latest'
-    // for apps without Dockerfiles (welcome image) or local dev.
-    const rawVersion = ctx.scope.node.tryGetContext("imageVersion");
-    const imageVersion = (typeof rawVersion === "string" ? rawVersion : undefined) || "latest";
-    const targetSuffix = serviceProps.dockerTarget
-        ? `-${serviceProps.dockerTarget.toLowerCase()}`
-        : "";
-    const imageTag = `${serviceName.toLowerCase()}${targetSuffix}-${imageVersion}`;
     if (typeof imageSource === "string") {
-        // Detect full registry URLs vs bare ECR repository names.
-        // Bare names (with or without namespace slashes) are treated as ECR repos.
-        // Docker Hub requires an explicit registry prefix (docker.io/).
-        const isFullRegistryUrl = /^(docker\.io|registry\.hub\.docker\.com|ghcr\.io)\//i.test(imageSource) || // Docker Hub / GHCR URLs
-            imageSource.startsWith("public.ecr.aws/") || // Public ECR: public.ecr.aws/fjall/welcome
-            imageSource.includes(".dkr.ecr."); // Private ECR full URL: 123456789012.dkr.ecr.us-east-2.amazonaws.com/repo:tag
+        const isFullRegistryUrl = /^(docker\.io|registry\.hub\.docker\.com|ghcr\.io)\//i.test(imageSource) ||
+            imageSource.startsWith("public.ecr.aws/") ||
+            imageSource.includes(".dkr.ecr.");
         if (isFullRegistryUrl) {
             return ContainerImage.fromRegistry(imageSource);
         }
-        return ContainerImage.fromEcrRepository(Repository.fromRepositoryName(ctx.scope, `${serviceName}${containerConfig.name}EcrRepo`, imageSource), imageTag);
+        const param = getOrCreateImageTagParameter(ctx, serviceName);
+        return ContainerImage.fromEcrRepository(Repository.fromRepositoryName(ctx.scope, `${serviceName}${containerConfig.name}EcrRepo`, imageSource), param.valueAsString);
     }
     if (imageSource instanceof Repository) {
-        return ContainerImage.fromEcrRepository(imageSource, imageTag);
+        const param = getOrCreateImageTagParameter(ctx, serviceName);
+        return ContainerImage.fromEcrRepository(imageSource, param.valueAsString);
     }
     return imageSource;
 }

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

@@ -0,0 +1,96 @@
+import { type BaseService, DeploymentLifecycleStage } from "aws-cdk-lib/aws-ecs";
+import { Construct } from "constructs";
+import { LambdaFunction } from "./lambda.js";
+/**
+ * Awsvpc network configuration consumed by the runner's `RunTask` call.
+ */
+export interface LifecycleHookNetworkConfiguration {
+    subnetIds: string[];
+    securityGroupIds: string[];
+    assignPublicIp: boolean;
+}
+/**
+ * Optional nested block describing a separate migration task definition.
+ *
+ * Three lockstep fields enforced by the type system — present-as-a-group or
+ * absent-as-a-group. This shape is the resources-layer mirror of
+ * `EcsLifecycleHookMigrationsSeparateTaskDef` at the patterns layer.
+ */
+export interface MigrationTaskDef {
+    /** ARN of the migration task definition (different from the service task def). */
+    definitionArn: string;
+    /** Family of the migration task definition — used to scope `ecs:RunTask`. */
+    family: string;
+    /** Task role ARN for the migration task. */
+    taskRoleArn: string;
+    /** Execution role ARN for the migration task. */
+    executionRoleArn: string;
+}
+export interface EcsLifecycleHookMigrationProps {
+    /**
+     * The ECS service this hook fires for.
+     */
+    service: BaseService;
+    /** Cluster ARN — used for both `ecs:RunTask`'s cluster condition and ListTasks scoping. */
+    clusterArn: string;
+    /** ARN of the task definition the migrate task launches from. */
+    taskDefinitionArn: string;
+    /** Family of the task definition — used in the `ecs:RunTask` resource ARN. */
+    taskDefinitionFamily: string;
+    /** Task execution role ARN (the role pulling the image, writing logs). */
+    taskExecutionRoleArn: string;
+    /** Task role ARN (the role the running container assumes). */
+    taskRoleArn: string;
+    /** Migration command, passed through to the runner. */
+    command: string[];
+    /** Synthetic container name used in `RunTask` overrides. */
+    containerName: string;
+    /** Optional image override (else the task definition's image is used). */
+    image?: string;
+    /**
+     * Optional container entrypoint override (else inherited from the image).
+     * Lets the patterns layer carry `["/usr/bin/tini", "--"]` shapes through to
+     * the runner's `ContainerOverrides` block.
+     */
+    entryPoint?: string[];
+    /** Optional environment override. */
+    environment?: Record<string, string>;
+    /**
+     * Lambda timeout in seconds. Defaults to 300, capped at 900 (Lambda max).
+     * Should comfortably exceed the migration command's expected runtime
+     * including a few re-invocation cycles.
+     */
+    timeoutSeconds?: number;
+    /** Awsvpc network configuration for the migrate task. */
+    networkConfiguration: LifecycleHookNetworkConfiguration;
+    /**
+     * Optional separate migration task definition. When present, `RunTask`
+     * targets THIS task def instead of the service's, and the Lambda's IAM
+     * policy expands to cover both task-def families + both role pairs.
+     *
+     * When absent, behaviour is unchanged — the migration runs in the service
+     * task def via `ContainerOverrides`.
+     */
+    migrationTaskDef?: MigrationTaskDef;
+    /**
+     * Which deployment lifecycle stage to fire at. Defaults to
+     * `PRE_SCALE_UP` (migration runs BEFORE the new revision scales up;
+     * service rollout blocks until the hook returns SUCCEEDED).
+     *
+     * Set to `POST_SCALE_UP` for post-deploy work (backfills, smoke tests)
+     * that should run AFTER new tasks are healthy; a FAILED return triggers
+     * deployment circuit-breaker rollback.
+     */
+    lifecycleStage?: DeploymentLifecycleStage;
+}
+/**
+ * ECS deployment lifecycle hook (PRE_SCALE_UP) that runs migrations as a
+ * one-off `RunTask` before the new revision scales up. Self-wires:
+ * synthesises the Lambda + IAM + LogGroup, then attaches the hook to the
+ * service via the typed CDK API. CDK auto-generates the hook-invocation
+ * role.
+ */
+export declare class EcsLifecycleHookMigration extends Construct {
+    readonly lambda: LambdaFunction;
+    constructor(scope: Construct, id: string, props: EcsLifecycleHookMigrationProps);
+}

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

@@ -0,0 +1,113 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Stack } from "aws-cdk-lib";
+import { Code, Runtime } from "aws-cdk-lib/aws-lambda";
+import { PolicyStatement, Effect } from "aws-cdk-lib/aws-iam";
+import { RetentionDays } from "aws-cdk-lib/aws-logs";
+import { DeploymentLifecycleLambdaTarget, DeploymentLifecycleStage } from "aws-cdk-lib/aws-ecs";
+import { Construct } from "constructs";
+import { LambdaFunction } from "./lambda.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const LAMBDA_SOURCE_FILE = "lifecycleHookLambda.source.cjs";
+const LAMBDA_TIMEOUT_DEFAULT_SECONDS = 300;
+const LAMBDA_TIMEOUT_MAX_SECONDS = 900;
+/**
+ * ECS deployment lifecycle hook (PRE_SCALE_UP) that runs migrations as a
+ * one-off `RunTask` before the new revision scales up. Self-wires:
+ * synthesises the Lambda + IAM + LogGroup, then attaches the hook to the
+ * service via the typed CDK API. CDK auto-generates the hook-invocation
+ * role.
+ */
+export class EcsLifecycleHookMigration extends Construct {
+    lambda;
+    constructor(scope, id, props) {
+        super(scope, id);
+        const stack = Stack.of(scope);
+        const timeoutSeconds = Math.min(props.timeoutSeconds ?? LAMBDA_TIMEOUT_DEFAULT_SECONDS, LAMBDA_TIMEOUT_MAX_SECONDS);
+        const sourcePath = path.resolve(__dirname, LAMBDA_SOURCE_FILE);
+        const source = readFileSync(sourcePath, "utf-8");
+        const migrationTaskDef = props.migrationTaskDef;
+        const targetTaskDefinitionArn = migrationTaskDef?.definitionArn ?? props.taskDefinitionArn;
+        const runTaskResources = [
+            `arn:aws:ecs:${stack.region}:${stack.account}:task-definition/${props.taskDefinitionFamily}:*`
+        ];
+        if (migrationTaskDef !== undefined) {
+            runTaskResources.push(`arn:aws:ecs:${stack.region}:${stack.account}:task-definition/${migrationTaskDef.family}:*`);
+        }
+        const passRoleResources = [props.taskExecutionRoleArn, props.taskRoleArn];
+        if (migrationTaskDef !== undefined) {
+            passRoleResources.push(migrationTaskDef.taskRoleArn, migrationTaskDef.executionRoleArn);
+        }
+        // ECS RunTask awsvpcConfiguration uses subnets/securityGroups and
+        // assignPublicIp as "ENABLED"/"DISABLED" string, not boolean.
+        const awsvpcConfiguration = {
+            subnets: props.networkConfiguration.subnetIds,
+            securityGroups: props.networkConfiguration.securityGroupIds,
+            assignPublicIp: props.networkConfiguration.assignPublicIp
+                ? "ENABLED"
+                : "DISABLED"
+        };
+        this.lambda = new LambdaFunction(this, `${id}Fn`, {
+            runtime: Runtime.NODEJS_22_X,
+            handler: "index.handler",
+            code: Code.fromInline(source),
+            lambdaDescription: `${id} ECS deployment lifecycle hook for migration`,
+            roleDescription: `Execution role for ${id} migration lifecycle-hook runner`,
+            timeout: timeoutSeconds,
+            memorySize: 256,
+            logGroupRetention: RetentionDays.ONE_MONTH,
+            environment: {
+                MIGRATE_CONFIG: JSON.stringify({
+                    clusterArn: props.clusterArn,
+                    taskDefinitionArn: targetTaskDefinitionArn,
+                    name: props.containerName,
+                    command: props.command,
+                    ...(props.image !== undefined ? { image: props.image } : {}),
+                    ...(props.entryPoint !== undefined
+                        ? { entryPoint: props.entryPoint }
+                        : {}),
+                    ...(props.environment !== undefined
+                        ? { environment: props.environment }
+                        : {}),
+                    networkConfiguration: awsvpcConfiguration,
+                    ...(migrationTaskDef !== undefined
+                        ? { hasSeparateMigrationTaskDef: true }
+                        : {})
+                })
+            },
+            inlinePolicy: [
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["ecs:RunTask"],
+                    resources: runTaskResources,
+                    conditions: {
+                        ArnEquals: { "ecs:cluster": props.clusterArn }
+                    }
+                }),
+                // ListTasks/DescribeTasks do not support resource-level ARN scoping;
+                // restrict via the `ecs:cluster` condition key instead.
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["ecs:ListTasks", "ecs:DescribeTasks"],
+                    resources: ["*"],
+                    conditions: {
+                        ArnEquals: { "ecs:cluster": props.clusterArn }
+                    }
+                }),
+                new PolicyStatement({
+                    effect: Effect.ALLOW,
+                    actions: ["iam:PassRole"],
+                    resources: passRoleResources,
+                    conditions: {
+                        StringEquals: { "iam:PassedToService": "ecs-tasks.amazonaws.com" }
+                    }
+                })
+            ]
+        });
+        const lifecycleStage = props.lifecycleStage ?? DeploymentLifecycleStage.PRE_SCALE_UP;
+        props.service.addLifecycleHook(new DeploymentLifecycleLambdaTarget(this.lambda, id, {
+            lifecycleStages: [lifecycleStage]
+        }));
+    }
+}

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

@@ -1,4 +1,5 @@
 import { type ApplicationListener, ApplicationLoadBalancer, type IApplicationTargetGroup, ListenerCondition } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 import { type ICertificate } from "aws-cdk-lib/aws-certificatemanager";
 import { ARecord, type IHostedZone } from "aws-cdk-lib/aws-route53";
 import type { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
@@ -14,7 +15,7 @@ export interface PriorityState {
 /** 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[];
-export declare function addLoadBalancer(ctx: EcsConstructContext, anyServiceUsesEc2: boolean, asgSecurityGroup?: SecurityGroup): {
+export declare function addLoadBalancer(ctx: EcsConstructContext, anyServiceUsesEc2: boolean, asgSecurityGroup?: ISecurityGroup): {
     loadBalancer: ApplicationLoadBalancer;
     loadBalancerSecurityGroup?: SecurityGroup;
 };

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

@@ -100,21 +100,33 @@ export function addLoadBalancer(ctx, anyServiceUsesEc2, asgSecurityGroup) {
 }
 export function addLoadBalancerListener(ctx, loadBalancer, certificate) {
     const port = certificate ? 443 : 80;
-    const defaultAction = ListenerAction.fixedResponse(404, {
-        contentType: "text/plain",
-        messageBody: "Not Found"
-    });
+    const servicesWithPorts = ctx.props.services.filter((s) => s.containers.some((c) => c.port !== undefined));
+    const willHaveMultipleRoutes = servicesWithPorts.length > 1 ||
+        servicesWithPorts.some((s) => {
+            const rules = Array.isArray(s.routing)
+                ? s.routing
+                : s.routing
+                    ? [s.routing]
+                    : [];
+            return rules.length > 1;
+        });
+    const defaultAction = willHaveMultipleRoutes
+        ? ListenerAction.fixedResponse(404, {
+            contentType: "text/plain",
+            messageBody: "Not Found"
+        })
+        : undefined;
     if (certificate) {
         return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
             port,
             certificates: [certificate],
-            defaultAction
+            ...(defaultAction !== undefined && { defaultAction })
         });
     }
     else {
         return loadBalancer.addListener(`${ctx.props.clusterName}Listener`, {
             port,
-            defaultAction
+            ...(defaultAction !== undefined && { defaultAction })
         });
     }
 }

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

@@ -0,0 +1,38 @@
+/**
+ * Synth-time resolver for ECS `remoteConnections` — turns each declared
+ * cross-app resource into a pair of `${PREFIX}_HOST` / `${PREFIX}_PORT` env
+ * vars resolved from SSM (`StringParameter.valueForStringParameter`) and
+ * indexed by service name for downstream merge into container environments.
+ *
+ * SSM path layout (matches the accepter side's publishing layout in
+ * `vpcPeerAccepter.ts`):
+ *   /fjall/{orgId ?? "default"}/{peer.peerAppName}/resources/{resource}/endpoint
+ *   /fjall/{orgId ?? "default"}/{peer.peerAppName}/resources/{resource}/port
+ *
+ * Default env-var prefix: `${toScreamingSnake(peer.peerAppName)}_${toScreamingSnake(resource)}`.
+ * Override via `RemoteConnectionSpec.envPrefix`.
+ */
+import { type Construct } from "constructs";
+import { type IVpcPeer } from "../../../utils/vpcPeerInterface.js";
+export interface RemoteConnectionSpec {
+    peer: IVpcPeer;
+    resource: string;
+    envPrefix?: string;
+}
+interface ServiceWithRemoteConnections {
+    name: string;
+    remoteConnections?: RemoteConnectionSpec[];
+}
+/**
+ * Resolve `remoteConnections` for every service into a per-service env-var
+ * bag. Returns `Record<serviceName, Record<envVarName, value>>`.
+ *
+ * Validates each `RemoteConnectionSpec` at synth time:
+ * - `resource` matches `RESOURCE_NAME_PATTERN` (PascalCase).
+ * - `envPrefix` (when supplied) matches `ENV_PREFIX_PATTERN`.
+ * - `peer.peerAppName` is defined and is not a CFN token — token-derived app
+ *   names produce `${Token[…]}` literals in env-var names, breaking ECS task
+ *   definitions silently.
+ */
+export declare function resolveRemoteConnections(services: ServiceWithRemoteConnections[], scope: Construct, orgId: string | undefined): Record<string, Record<string, string>>;
+export {};

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

@@ -0,0 +1,80 @@
+/**
+ * Synth-time resolver for ECS `remoteConnections` — turns each declared
+ * cross-app resource into a pair of `${PREFIX}_HOST` / `${PREFIX}_PORT` env
+ * vars resolved from SSM (`StringParameter.valueForStringParameter`) and
+ * indexed by service name for downstream merge into container environments.
+ *
+ * SSM path layout (matches the accepter side's publishing layout in
+ * `vpcPeerAccepter.ts`):
+ *   /fjall/{orgId ?? "default"}/{peer.peerAppName}/resources/{resource}/endpoint
+ *   /fjall/{orgId ?? "default"}/{peer.peerAppName}/resources/{resource}/port
+ *
+ * Default env-var prefix: `${toScreamingSnake(peer.peerAppName)}_${toScreamingSnake(resource)}`.
+ * Override via `RemoteConnectionSpec.envPrefix`.
+ */
+import { Token } from "aws-cdk-lib";
+import { StringParameter } from "aws-cdk-lib/aws-ssm";
+import { VALIDATION_PATTERNS } from "@fjall/generator";
+import { buildSsmPrefix, DEFAULT_ORG_ID } from "../../../utils/cdkContext.js";
+import { toScreamingSnake } from "../../../utils/capitaliseString.js";
+const RESOURCE_NAME_PATTERN = VALIDATION_PATTERNS.RESOURCE_NAME;
+/** SCREAMING_SNAKE_CASE env-var prefix (digits allowed, must start with letter). */
+const ENV_PREFIX_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+/**
+ * Resolve `remoteConnections` for every service into a per-service env-var
+ * bag. Returns `Record<serviceName, Record<envVarName, value>>`.
+ *
+ * Validates each `RemoteConnectionSpec` at synth time:
+ * - `resource` matches `RESOURCE_NAME_PATTERN` (PascalCase).
+ * - `envPrefix` (when supplied) matches `ENV_PREFIX_PATTERN`.
+ * - `peer.peerAppName` is defined and is not a CFN token — token-derived app
+ *   names produce `${Token[…]}` literals in env-var names, breaking ECS task
+ *   definitions silently.
+ */
+export function resolveRemoteConnections(services, scope, orgId) {
+    const byService = {};
+    for (const service of services) {
+        const specs = service.remoteConnections ?? [];
+        if (specs.length === 0)
+            continue;
+        const envVars = {};
+        const seenPrefixes = new Set();
+        for (const spec of specs) {
+            const peerAppName = validateSpec(service.name, spec);
+            const peerOrgId = spec.peer.peerOrgId ?? orgId ?? DEFAULT_ORG_ID;
+            const ssmPrefix = `${buildSsmPrefix(peerOrgId, peerAppName)}/resources/${spec.resource}`;
+            const endpoint = StringParameter.valueForStringParameter(scope, `${ssmPrefix}/endpoint`);
+            const port = StringParameter.valueForStringParameter(scope, `${ssmPrefix}/port`);
+            const prefix = spec.envPrefix ??
+                `${toScreamingSnake(peerAppName)}_${toScreamingSnake(spec.resource)}`;
+            if (seenPrefixes.has(prefix)) {
+                throw new Error(`remoteConnections on service '${service.name}': duplicate env-var prefix '${prefix}' — set distinct envPrefix on each spec to avoid silently clobbering ${prefix}_HOST and ${prefix}_PORT.`);
+            }
+            seenPrefixes.add(prefix);
+            envVars[`${prefix}_HOST`] = endpoint;
+            envVars[`${prefix}_PORT`] = port;
+        }
+        byService[service.name] = envVars;
+    }
+    return byService;
+}
+function validateSpec(serviceName, spec) {
+    if (!RESOURCE_NAME_PATTERN.test(spec.resource)) {
+        throw new Error(`remoteConnections on service '${serviceName}': resource '${spec.resource}' is not a valid PascalCase resource name (must match ${RESOURCE_NAME_PATTERN.source}).`);
+    }
+    if (spec.envPrefix !== undefined &&
+        !ENV_PREFIX_PATTERN.test(spec.envPrefix)) {
+        throw new Error(`remoteConnections on service '${serviceName}': envPrefix '${spec.envPrefix}' is not SCREAMING_SNAKE_CASE (must match ${ENV_PREFIX_PATTERN.source}).`);
+    }
+    const peerAppName = spec.peer.peerAppName;
+    if (peerAppName === undefined) {
+        throw new Error(`remoteConnections on service '${serviceName}': peer.peerAppName is undefined — pass a peer built via VpcPeerFactory.build() so the SSM path can be resolved at synth.`);
+    }
+    if (typeof peerAppName === "string" && peerAppName.length === 0) {
+        throw new Error(`remoteConnections on service '${serviceName}': peer.peerAppName is an empty string, which would produce malformed env-var names and an invalid SSM path. Pass a literal app name (typically the Fjall app's name string).`);
+    }
+    if (Token.isUnresolved(peerAppName)) {
+        throw new Error(`remoteConnections on service '${serviceName}': peer.peerAppName is a CFN token, which would corrupt env-var names. Pass a literal app name (typically the Fjall app's name string).`);
+    }
+    return peerAppName;
+}

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

@@ -1,15 +1,24 @@
-import { FargateService, Ec2Service, AsgCapacityProvider } from "aws-cdk-lib/aws-ecs";
+import { FargateService, Ec2Service, AsgCapacityProvider, type DeploymentCircuitBreaker } from "aws-cdk-lib/aws-ecs";
 import type { FargateTaskDefinition, Ec2TaskDefinition } from "aws-cdk-lib/aws-ecs";
+import { type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 import { TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
-import { AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
-import { SecurityGroup } from "../networking/securityGroup.js";
+import { type AutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import { type EcsServiceProps, type Ec2CapacityConfig } from "./ecsTypes.js";
 import type { EcsConstructContext } from "./ecsContext.js";
+/**
+ * Resolves the user's `circuitBreaker` config to the CDK
+ * `DeploymentCircuitBreaker` shape. `undefined` resolves to the safe default
+ * `{ enable: true, rollback: true }`; `false` resolves to `undefined` (CDK
+ * omits the breaker block from CFN output entirely).
+ */
+export declare function resolveCircuitBreaker(config: false | {
+    rollback?: boolean;
+} | undefined): DeploymentCircuitBreaker | undefined;
 /** Mutable state for ASG capacity provider deduplication. */
 export interface AsgCapacityState {
     providers: Map<string, AsgCapacityProvider>;
     autoScalingGroup?: AutoScalingGroup;
-    asgSecurityGroup?: SecurityGroup;
+    asgSecurityGroup?: ISecurityGroup;
 }
 /**
  * Generates a unique key for EC2 config so services with matching