@fjall/components-infrastructure 4.0.0 → 4.2.0

package/dist/lib/patterns/aws/computeEcs.js

@@ -25,7 +25,7 @@ import { FjallLogger } from "../../utils/validationLogger.js";
 import { VALIDATION_PATTERNS } from "@fjall/generator";
 import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab, buildParameterPath } from "@fjall/util";
-import { validateEcsDomainConfig, validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
+import { validateEc2ServiceSizing, validateEcsDomainConfig, validateSecretName } from "../../resources/aws/compute/ecsValidation.js";
 import { COMPUTE_DEFAULTS, collectImportedSecretNames } from "./compute.js";
 import { isHookMigrations } from "./computeEcsTypes.js";
 export { ScalingType } from "./computeEcsTypes.js";
@@ -150,6 +150,7 @@ export function validateEcsProps(props) {
             FjallLogger.warn(`Service '${service.name}' has ec2Config but capacityProvider is not 'EC2'. ` +
                 "The ec2Config will be ignored unless capacityProvider is set to 'EC2'.");
         }
+        validateEc2ServiceSizing(service);
         if (service.deployment !== undefined) {
             const min = service.deployment.minHealthyPercent;
             const max = service.deployment.maxHealthyPercent;

package/dist/lib/patterns/aws/devSubstrate.d.ts

@@ -38,6 +38,18 @@ export interface IDevSubstrateProps {
      * account where the repo was provisioned out-of-band.
      */
     readonly adoptSlotEcr?: boolean;
+    /**
+     * When `true`, adopt an already-existing slot build-cache ECR repository
+     * (`fjall-dev-<appKebab>-slots-cache`) by reference instead of creating one.
+     * Independent of {@link adoptSlotEcr} on purpose: an app whose slots repo
+     * predates the build-cache feature runs the substrate in slot-adopt mode, yet
+     * its cache repo does NOT exist and MUST be created on the next redeploy —
+     * coupling the two would import a non-existent cache repo and the slot builds
+     * would stay permanently uncached. The producer probes each repo's existence
+     * separately (webapp `shouldAdoptSlotEcr` / `shouldAdoptCacheEcr`). Defaults to
+     * `false`: create the cache repo with the untagged-image lifecycle rule.
+     */
+    readonly adoptCacheEcr?: boolean;
     /**
      * Deploy phase for the R2 two-step cert-hang guard. `"zone"` synthesises the
      * `devDomain` zone + cross-account NS delegation only; `"full"` additionally

package/dist/lib/patterns/aws/devSubstrate.js

@@ -251,12 +251,13 @@ export class DevSubstrate extends Construct {
                 tagMutability: TagMutability.MUTABLE
             });
         // Buildx registry cache for slot builds, named by the same helper as the app
-        // path's `<repo>-cache` so `fjall dev up` derives this URI from the slot
-        // repo's without a second wire field. Adopts on the same flag: both repos are
-        // RETAIN, so a rolled-back create leaves BOTH behind, and a create-only cache
-        // repo would fail the very retry `adoptSlotEcr` exists to rescue.
+        // path's `<repo>-cache` so `fjall dev up` derives this URI from the slot repo's
+        // without a second wire field. Adopt is gated on its OWN `adoptCacheEcr` flag,
+        // NOT `adoptSlotEcr`: an app whose slots repo predates the cache feature
+        // redeploys in slot-adopt mode with no cache repo yet — coupling the two would
+        // import a non-existent repo and slot builds would stay permanently uncached.
         const slotCacheRepositoryName = buildCacheRepositoryName(slotEcrRepositoryName);
-        if (props.adoptSlotEcr === true) {
+        if (props.adoptCacheEcr === true) {
             Repository.fromRepositoryName(this, `${slotEcrId}Cache`, slotCacheRepositoryName);
         }
         else {

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

@@ -214,6 +214,9 @@ export function addContainersToTask(ctx, serviceName, serviceProps, taskDefiniti
             stopTimeout: containerConfig.stopTimeout !== undefined
                 ? Duration.seconds(containerConfig.stopTimeout)
                 : undefined,
+            // EC2 container memory is ec2Config-only by design — do NOT add a
+            // `?? serviceProps.memoryLimitMiB` fallback (that is the silent-ignore
+            // footgun `validateEc2ServiceSizing` exists to reject).
             ...(isServiceEc2(serviceProps) && {
                 memoryLimitMiB: serviceProps.ec2Config?.memoryLimitMiB ??
                     DEFAULT_EC2_CONTAINER_MEMORY_MIB

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

@@ -102,7 +102,12 @@ export interface Ec2CapacityConfig {
     minCapacity?: number;
     /** Maximum number of instances. Default: 3 */
     maxCapacity?: number;
-    /** Memory limit in MiB for the container. Default: 1024 */
+    /**
+     * Memory limit in MiB for the container. Default: 1024. This is the ONLY
+     * memory knob for an EC2 service — the service-level `memoryLimitMiB` on
+     * `EcsServiceProps` is Fargate-only and is rejected at synth for EC2 capacity
+     * (see `validateEc2ServiceSizing`).
+     */
     memoryLimitMiB?: number;
     /** Warm pool keeps stopped instances for faster start (10-15s vs 60-90s).
      *  Mirrors generator WarmPool type (generator/src/schemas/computeSchemas.ts). */
@@ -442,9 +447,19 @@ export interface EcsServiceProps {
      * The first container with a port is the **primary container** (receives ALB traffic).
      */
     containers: EcsClusterContainerConfig[];
-    /** CPU units for this service's tasks (256-4096) */
+    /**
+     * CPU units for this service's tasks (256-4096). Fargate only — EC2 task
+     * definitions carry no task-level CPU reservation (CPU is bounded by the
+     * instance type), so a value here is rejected at synth when `capacityProvider`
+     * is 'EC2' (see `validateEc2ServiceSizing`).
+     */
     cpu?: number;
-    /** Memory in MiB for this service's tasks (512-30720) */
+    /**
+     * Memory in MiB for this service's tasks (512-30720). Fargate only — for EC2
+     * capacity the container memory comes from `ec2Config.memoryLimitMiB`; a
+     * service-level value here is rejected at synth unless it exactly mirrors
+     * that field (see `validateEc2ServiceSizing`).
+     */
     memoryLimitMiB?: number;
     /** Desired number of tasks. Default: 2 */
     desiredCount?: number;

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

@@ -1,4 +1,4 @@
-import type { DomainConfig, EcsClusterProps } from "./ecsTypes.js";
+import type { DomainConfig, EcsCapacityProvider, EcsClusterProps } from "./ecsTypes.js";
 /**
  * Validates ECS cluster props before construction.
  * Pure function — does not depend on class state.
@@ -23,6 +23,60 @@ import type { DomainConfig, EcsClusterProps } from "./ecsTypes.js";
  * @throws Error if validation fails
  */
 export declare function validateEcsClusterProps(props: EcsClusterProps): void;
+/**
+ * Minimal structural input for {@link validateEc2ServiceSizing} — exactly the
+ * fields the guard reads. Both the resources-layer `EcsServiceProps` and the
+ * patterns-layer `EcsServiceConfig` structurally satisfy it, so one guard serves
+ * both validation layers without coupling to either full service type
+ * (typescript-standards § "Helpers consume resolved state, not the dispatch enum":
+ * the parameter type is the fields the body actually reads, nothing wider).
+ */
+interface Ec2ServiceSizingInput {
+    name: string;
+    capacityProvider?: EcsCapacityProvider;
+    cpu?: number;
+    memoryLimitMiB?: number;
+    ec2Config?: {
+        memoryLimitMiB?: number;
+    };
+}
+/**
+ * Rejects service-level task sizing that is silently ignored for EC2 capacity.
+ *
+ * For an EC2-capacity ECS service the container's hard memory limit is derived
+ * from `ec2Config.memoryLimitMiB` (default {@link DEFAULT_EC2_CONTAINER_MEMORY_MIB}),
+ * NOT from the service-level `memoryLimitMiB` — that field only feeds the
+ * Fargate task definition (`createTaskDefinition` in `ecsTaskDefinition.ts`: the
+ * EC2 branch passes neither `cpu` nor `memoryLimitMiB`; the container's memory
+ * comes solely from the `ec2Config.memoryLimitMiB ?? default` spread). A
+ * service-level `cpu` has no EC2 analogue at all — EC2 task definitions carry no
+ * task-level CPU reservation and `Ec2CapacityConfig` has no `cpu` field — so it
+ * is always dead on an EC2 service. Both fields read as "size the task to N"
+ * while the deployed container ignores the value.
+ *
+ * Fail loud at synth rather than silently honour the value: silently honouring
+ * memory would rewrite deployed container memory in BOTH directions — raise it
+ * past the EC2 instance's capacity (failure-to-place mid-rollout) or lower it
+ * into the service-level [512,1023] band below the 1024 EC2 default (fresh OOM).
+ * Rejecting changes nothing deployed; it converts two silent misconfigs into a
+ * synth error with a named cure.
+ *
+ * `both-set-and-equal` is allowed for memory — a config that mirrors
+ * `ec2Config.memoryLimitMiB` into the service-level field is self-consistent and
+ * the derived container memory is unchanged. `cpu` has no such carve-out (there
+ * is no `ec2Config.cpu` to agree with); it always throws on EC2.
+ *
+ * Called from BOTH validation layers — resources `validateEcsClusterProps` and
+ * patterns `validateEcsProps` — so the guard cannot drift between them
+ * (code-quality § "Coupled values: shared source at 2 occurrences"; mirrors the
+ * `validateEcsDomainConfig` shared-helper precedent below).
+ *
+ * @param service - The service props to validate (no-op unless EC2 capacity)
+ * @throws Error if an EC2 service carries an ignored service-level `cpu`, or a
+ *   service-level `memoryLimitMiB` that is absent from / conflicts with
+ *   `ec2Config.memoryLimitMiB`
+ */
+export declare function validateEc2ServiceSizing(service: Ec2ServiceSizingInput): void;
 /**
  * Domain-config constraints shared by the resources-layer hook
  * (`validateEcsClusterProps`) and the patterns-layer mirror
@@ -52,3 +106,4 @@ export declare function validateSsmPathComponent(component: string, fieldName: s
  * reference the fjall secrets tooling can never write.
  */
 export declare function validateSecretName(name: string, context: string): void;
+export {};

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

@@ -2,6 +2,7 @@ import { NetworkMode } from "aws-cdk-lib/aws-ecs";
 import { evaluateBakeGuard } from "@fjall/util/docker";
 import { toKebab, SSM_COMPONENT_PATTERN, SSM_COMPONENT_ERROR, SECRET_NAME_PATTERN, SECRET_NAME_ERROR } from "@fjall/util";
 import { ScalingType } from "./ecsTypes.js";
+import { DEFAULT_EC2_CONTAINER_MEMORY_MIB } from "./ecsConstants.js";
 /**
  * Validates ECS cluster props before construction.
  * Pure function — does not depend on class state.
@@ -121,6 +122,7 @@ export function validateEcsClusterProps(props) {
             throw new Error(`Service '${service.name}' uses EC2 capacity provider but no ec2Config is defined. ` +
                 "Provide ec2Config on the service.");
         }
+        validateEc2ServiceSizing(service);
         if (service.deployment !== undefined) {
             const min = service.deployment.minHealthyPercent;
             const max = service.deployment.maxHealthyPercent;
@@ -188,6 +190,70 @@ export function validateEcsClusterProps(props) {
         }
     }
 }
+/**
+ * Rejects service-level task sizing that is silently ignored for EC2 capacity.
+ *
+ * For an EC2-capacity ECS service the container's hard memory limit is derived
+ * from `ec2Config.memoryLimitMiB` (default {@link DEFAULT_EC2_CONTAINER_MEMORY_MIB}),
+ * NOT from the service-level `memoryLimitMiB` — that field only feeds the
+ * Fargate task definition (`createTaskDefinition` in `ecsTaskDefinition.ts`: the
+ * EC2 branch passes neither `cpu` nor `memoryLimitMiB`; the container's memory
+ * comes solely from the `ec2Config.memoryLimitMiB ?? default` spread). A
+ * service-level `cpu` has no EC2 analogue at all — EC2 task definitions carry no
+ * task-level CPU reservation and `Ec2CapacityConfig` has no `cpu` field — so it
+ * is always dead on an EC2 service. Both fields read as "size the task to N"
+ * while the deployed container ignores the value.
+ *
+ * Fail loud at synth rather than silently honour the value: silently honouring
+ * memory would rewrite deployed container memory in BOTH directions — raise it
+ * past the EC2 instance's capacity (failure-to-place mid-rollout) or lower it
+ * into the service-level [512,1023] band below the 1024 EC2 default (fresh OOM).
+ * Rejecting changes nothing deployed; it converts two silent misconfigs into a
+ * synth error with a named cure.
+ *
+ * `both-set-and-equal` is allowed for memory — a config that mirrors
+ * `ec2Config.memoryLimitMiB` into the service-level field is self-consistent and
+ * the derived container memory is unchanged. `cpu` has no such carve-out (there
+ * is no `ec2Config.cpu` to agree with); it always throws on EC2.
+ *
+ * Called from BOTH validation layers — resources `validateEcsClusterProps` and
+ * patterns `validateEcsProps` — so the guard cannot drift between them
+ * (code-quality § "Coupled values: shared source at 2 occurrences"; mirrors the
+ * `validateEcsDomainConfig` shared-helper precedent below).
+ *
+ * @param service - The service props to validate (no-op unless EC2 capacity)
+ * @throws Error if an EC2 service carries an ignored service-level `cpu`, or a
+ *   service-level `memoryLimitMiB` that is absent from / conflicts with
+ *   `ec2Config.memoryLimitMiB`
+ */
+export function validateEc2ServiceSizing(service) {
+    if (service.capacityProvider !== "EC2")
+        return;
+    if (service.memoryLimitMiB !== undefined) {
+        const ec2Memory = service.ec2Config?.memoryLimitMiB;
+        if (ec2Memory === undefined) {
+            throw new Error(`Service '${service.name}': service-level memoryLimitMiB (${service.memoryLimitMiB}) is ignored ` +
+                "for EC2 capacity — the container's hard memory limit comes from ec2Config.memoryLimitMiB " +
+                `(default ${DEFAULT_EC2_CONTAINER_MEMORY_MIB} MiB), not the service-level field. Set ` +
+                `ec2Config.memoryLimitMiB: ${service.memoryLimitMiB} to size the container, or remove the ` +
+                "service-level memoryLimitMiB. (Service-level memoryLimitMiB only applies to Fargate services.)");
+        }
+        if (ec2Memory !== service.memoryLimitMiB) {
+            throw new Error(`Service '${service.name}': conflicting memory limits — service-level memoryLimitMiB ` +
+                `(${service.memoryLimitMiB}) disagrees with ec2Config.memoryLimitMiB (${ec2Memory}). For EC2 ` +
+                "capacity only ec2Config.memoryLimitMiB sizes the container; the service-level value is ignored. " +
+                "Set both to the same value or remove the service-level memoryLimitMiB.");
+        }
+        // both-set-and-equal falls through untouched (allowed): the config is
+        // self-consistent and the derived container memory is unchanged.
+    }
+    if (service.cpu !== undefined) {
+        throw new Error(`Service '${service.name}': service-level cpu (${service.cpu}) is ignored for EC2 capacity — ` +
+            "EC2 task definitions carry no task-level CPU reservation (CPU is bounded by the instance type) " +
+            "and there is no ec2Config.cpu field. Remove the service-level cpu. " +
+            "(Service-level cpu only applies to Fargate services.)");
+    }
+}
 /**
  * Domain-config constraints shared by the resources-layer hook
  * (`validateEcsClusterProps`) and the patterns-layer mirror

package/dist/lib/resources/aws/compute/lifecycleHookLambda.source.cjs

@@ -4,9 +4,17 @@
  *
  * Re-invocation safety: ECS hook responses do NOT carry state between
  * IN_PROGRESS invocations. On every invocation we reconstruct the
- * deterministic startedBy tag from the event's targetServiceRevisionArn and
- * use ListTasks to find an existing running migration. RunTask fires only on
- * the first invocation.
+ * deterministic startedBy tag from the event's
+ * executionDetails.targetServiceRevisionArn and use ListTasks to find an
+ * existing running migration. RunTask fires only on the first invocation.
+ *
+ * Event contract: the target revision ARN is nested under `executionDetails`
+ * and the `executionId` is top-level — see AWS "Lambda hooks for Amazon ECS
+ * service deployments" (developerguide/lambda-lifecycle-hooks.html). Reading
+ * the revision ARN from the wrong level collapses the startedBy tag to a
+ * shared constant across every deploy, so ListTasks can adopt another
+ * deployment's task (cross-deploy race). A missing revision ARN therefore
+ * FAILS the hook loudly rather than proceeding with a shared tag.
  *
  * CommonJS rather than ESM because Code.fromInline lands the source as
  * `index.js`, which Lambda treats as CommonJS by default.
@@ -37,6 +45,26 @@ function startedByTag(targetServiceRevisionArn) {
   return `fjall-migrate-${suffix}`.slice(0, 36);
 }
 
+// The revision ARN is nested under executionDetails in the ECS lifecycle-hook
+// event; the top-level fallback tolerates a future/legacy shape without
+// reopening the shared-tag race (nested is read first).
+function extractTargetServiceRevisionArn(event) {
+  const nested =
+    event &&
+    event.executionDetails &&
+    event.executionDetails.targetServiceRevisionArn;
+  const topLevel = event && event.targetServiceRevisionArn;
+  return nested || topLevel || undefined;
+}
+
+// executionId is top-level in the AWS contract; nested fallback is defensive.
+function extractExecutionId(event) {
+  const topLevel = event && event.executionId;
+  const nested =
+    event && event.executionDetails && event.executionDetails.executionId;
+  return topLevel || nested || undefined;
+}
+
 function buildContainerOverrides(
   name,
   command,
@@ -97,12 +125,20 @@ async function pollTaskUntilStopped(client, clusterArn, taskArn, sleep) {
 }
 
 async function runHandler(event, deps) {
+  const targetServiceRevisionArn = extractTargetServiceRevisionArn(event);
+  if (!targetServiceRevisionArn) {
+    return {
+      hookStatus: "FAILED",
+      reason:
+        "Lifecycle event missing executionDetails.targetServiceRevisionArn"
+    };
+  }
   const client = (deps && deps.client) || getDefaultClient();
   const sleep = deps && deps.sleep;
   const config = JSON.parse(
     (deps && deps.migrateConfig) || process.env.MIGRATE_CONFIG
   );
-  const startedBy = startedByTag(event && event.targetServiceRevisionArn);
+  const startedBy = startedByTag(targetServiceRevisionArn);
 
   const existingTaskArn = await findExistingTaskArn(
     client,
@@ -158,12 +194,8 @@ exports.handler = async (event) => {
     JSON.stringify({
       msg: "lifecycle-hook-invoked",
       targetServiceRevisionArn:
-        (event && event.targetServiceRevisionArn) || "(missing)",
-      executionId:
-        (event &&
-          event.executionDetails &&
-          event.executionDetails.executionId) ||
-        "(missing)"
+        extractTargetServiceRevisionArn(event) || "(missing)",
+      executionId: extractExecutionId(event) || "(missing)"
     })
   );
   try {
@@ -182,6 +214,8 @@ exports.handler = async (event) => {
 
 exports._internals = {
   startedByTag,
+  extractTargetServiceRevisionArn,
+  extractExecutionId,
   buildContainerOverrides,
   findExistingTaskArn,
   pollTaskUntilStopped,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "bin": {
@@ -67,8 +67,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1038.0",
-    "@fjall/generator": "^4.0.0",
-    "@fjall/util": "^4.0.0",
+    "@fjall/generator": "^4.2.0",
+    "@fjall/util": "^4.2.0",
     "constructs": "^10.6.0"
   },
   "overrides": {
@@ -82,5 +82,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "gitHead": "14031063ccd2685e390b70f6a3f4efe2bac7ced9"
+  "gitHead": "c06f7ad6b4b63a99cc8e2fcf4f216ff1c14748c6"
 }