@fjall/components-infrastructure 4.1.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "4.1.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.1.0",
-    "@fjall/util": "^4.1.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": "09dee795753839b82aedbb7d0cef1c5ef283df55"
+  "gitHead": "c06f7ad6b4b63a99cc8e2fcf4f216ff1c14748c6"
 }