@fjall/components-infrastructure 39.0.5 → 39.0.6

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

@@ -2,7 +2,7 @@ import { type ICluster, type IBaseService, type TaskDefinition, type FargateTask
 import { type Connections, type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
 import { type Grant, type IGrantable, type IRole } from "aws-cdk-lib/aws-iam";
 import { type IApplicationLoadBalancer, type ApplicationListener } from "aws-cdk-lib/aws-elasticloadbalancingv2";
-import { Construct } from "constructs";
+import { Construct, type IDependable } from "constructs";
 import { type IEcsCompute } from "./interfaces/compute.js";
 import { type SecretImport } from "../../resources/aws/secrets/index.js";
 import EcsCluster, { type EcsClusterProps, type EcsIngressProfile } from "../../resources/aws/compute/ecs.js";
@@ -100,6 +100,10 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
     private readonly clusterId;
     private readonly appName;
     private readonly migrationTaskDefinitions;
+    /** The cluster's physical name, as a literal. */
+    private readonly clusterName;
+    /** Service name → its rollout barrier, made on first use. */
+    private readonly rolloutBarriers;
     /**
      * Service name → exact `@fjall/schema-gate` semver, for every service that
      * materialised the gate container with the DEFAULT image this synth.
@@ -151,11 +155,6 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
      * - `migrations.mode: "post-deploy"` — expected is deliberately ahead of
      *   the DB during scale-up, so a materialised gate would refuse every task
      *   (synth warning)
-     * - `migrations.mode: "lifecycle-hook"` WITHOUT `separateTaskDef` — the
-     *   hook's migration RunTask reuses the service task definition, so a
-     *   materialised gate would refuse the migration task itself while the DB
-     *   still holds the pre-migration schema (synth warning; adding
-     *   `separateTaskDef` restores full gating)
      * - No eligible half survives the v1 scope filters: the relational half
      *   requires `tool: "prisma"` and a postgres-family connection scheme
      *   (per-half synth warnings; env injection into app containers stays on)
@@ -195,30 +194,45 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
      * Without `awaitMigrationsFrom` the sibling rolls out in parallel with the
      * owner, so its gate-refused task churn can trip the deployment circuit
      * breaker before the migration lands. The gate refusing is by design (new
-     * code must not serve the old schema); the missing DependsOn is the
-     * author-fixable part — warn, don't disable.
+     * code must not serve the old schema); the missing ordering on the owner's
+     * rollout barrier is the author-fixable part — warn, don't disable.
      */
     private warnUngatedSiblingsOfHookOwners;
     /**
      * For each service whose `migrations.mode` is a lambda-hook variant
      * (`"lifecycle-hook"` for PRE_SCALE_UP, `"post-deploy"` for POST_SCALE_UP),
-     * synthesise the Lambda + IAM role + log group that backs the deployment
-     * lifecycle hook. The init-container path is unaffected — services without
-     * `mode` (or with `mode: "init-container"`) still get the synthetic
-     * migrate container injected by `expandMigrationsSugar`.
+     * synthesise the migration's own task definition and the Lambda + IAM role
+     * + log group that backs the deployment lifecycle hook. Every hook
+     * migration runs from a task definition of its own, which the service's
+     * task definition names in its `fjall:migration-task-definition` tag and
+     * its primary container's docker label: the hook reads the tag from the
+     * revision each deployment targets, and the label where a copy carries no
+     * tag. The
+     * init-container path is unaffected — services without `mode` (or with
+     * `mode: "init-container"`) still get the synthetic migrate container
+     * injected by `expandMigrationsSugar`.
      */
     private wireLifecycleHookMigrations;
     /**
-     * Wire a native CloudFormation `DependsOn` from each service that declares
-     * `awaitMigrationsFrom` to the named migrate-owning service, so CFN does not
-     * roll out the dependent service until the target's ECS deployment — including
-     * its PRE_SCALE_UP migrate hook — has completed. Prevents the RDS-IAM auth /
-     * schema-mismatch race when a DB-connecting worker starts before the app's
-     * migrations have applied, and enables a single-pass greenfield deploy.
-     * Shape (target exists, declares hook migrations, no self / cycle) is already
-     * guaranteed by `validateEcsProps`; the undefined guards are synth invariants.
+     * Orders each service that declares `awaitMigrationsFrom` after the named
+     * migrate-owning service's rollout, so a DB-connecting worker never starts
+     * before the owner's migrations have applied. Each owner gets one rollout
+     * barrier (`EcsRolloutBarrier`): a custom resource that completes only once
+     * ECS reports the owner's deployment of its task definition finished, its
+     * lifecycle-hook migration included, and fails once ECS rolled that
+     * deployment back. Every dependant's `DependsOn` names the barrier.
+     *
+     * A `DependsOn` on the owner service itself no longer orders this: since
+     * 2026-10-01 CloudFormation starts the dependants of an updating ECS
+     * service at its eventual-consistency check, 20-31 s into the update, while
+     * a custom resource's dependants wait for its response (FJL-901).
+     *
+     * Shape (target exists, declares hook migrations, no self / cycle) is
+     * already guaranteed by `validateEcsProps`.
      */
     private wireServiceMigrationDependencies;
+    /** The service's one rollout barrier, made on first use. */
+    private rolloutBarrierOf;
     /**
      * Synthesise a dedicated migration task definition for a lifecycle-hook
      * migration when `separateTaskDef` is set. Creates the migration's own
@@ -227,6 +241,19 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
      * with the migration container baked in.
      */
     private synthesiseMigrationTaskDef;
+    /**
+     * The migration task definition of a lifecycle-hook migration without
+     * `separateTaskDef`. It runs what the hook's `RunTask` of the service's
+     * own task definition, its command and environment overridden, ran until
+     * FJL-901: as the service's own roles, at the service's size, in the
+     * service's log group, from the service's image, with the primary
+     * container's environment, entry point and secrets beneath the
+     * migration's own. A connected database's contributed secrets and role
+     * policies, such as its schema administrator's, reach only a
+     * `separateTaskDef` migration, whose roles are its own, so they never
+     * widen the service's.
+     */
+    private synthesiseInheritedMigrationTaskDef;
     private resolveMigrationSecrets;
     /** Get the ECS cluster. */
     getCluster(): ICluster;
@@ -249,9 +276,26 @@ export declare class EcsCompute extends Construct implements IEcsCompute {
      * Get the migration task definition for a service. Returns `undefined` when
      * the service has no `migrations: { mode: "lifecycle-hook", separateTaskDef }`
      * configured — escape hatch for callers that need to attach grants (e.g.
-     * `bucket.grantReadWrite(td.taskRole)`) to the migration task role.
+     * `bucket.grantReadWrite(td.taskRole)`) to the migration task role. Without
+     * `separateTaskDef` the migration runs in a task definition of its own that
+     * this does not return: its task role is the service's, so a grant to it
+     * would widen the service.
      */
     getMigrationTaskDefinition(serviceName: string): FargateTaskDefinition | undefined;
+    /**
+     * The rollout barrier of a service: a custom resource that completes only
+     * once ECS reports the service's deployment of its task definition
+     * finished, and fails once ECS rolled that deployment back. A construct
+     * that depends on it is created or updated only after the service has
+     * rolled out, for orderings `awaitMigrationsFrom` cannot express:
+     * `compute.getService("worker")?.node.addDependency(compute.getRolloutBarrier("app"))`.
+     * A `DependsOn` on the service itself does not order this: CloudFormation
+     * may start a service's dependants at its eventual-consistency check, long
+     * before its deployment finishes (FJL-901). A service has one barrier,
+     * shared with `awaitMigrationsFrom`; one the cluster does not run is
+     * refused.
+     */
+    getRolloutBarrier(serviceName: string): IDependable;
     /** Get the security group for the cluster. */
     getSecurityGroup(): ISecurityGroup;
     /**