@fjall/components-infrastructure 35.0.0 → 37.0.0

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

@@ -5,6 +5,7 @@ import { RdsAuroraGlobal } from "../../resources/aws/database/rdsAuroraGlobal.js
 import { DynamoDBTable } from "../../resources/aws/database/dynamodb.js";
 import { ClickHouseDatabase } from "./clickhouseDatabase.js";
 import { FjallLogger, warnIfPropertiesIgnored } from "../../utils/validationLogger.js";
+import { DATABASE_WARN_GROUPS } from "./databasePropApplicability.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
 import { ResourceNaming } from "../../utils/resourceNaming.js";
 import { resolveAlertsTopic as resolveAlertsTopicShared } from "../../utils/resolveAlertsTopic.js";
@@ -127,12 +128,9 @@ function validateRelationalDatabaseProps(props) {
         throw new Error("GlobalAurora database requires 'primaryRegion'. " +
             "Specify the AWS region where the primary cluster will be created.");
     }
-    // Instance-only options on Aurora/GlobalAurora
-    warnIfPropertiesIgnored(props, ["readReplica", "multiAz", "allocatedStorage", "iamAuthentication"], "Instance", "Instance database");
-    // Aurora-only options on Instance
-    warnIfPropertiesIgnored(props, ["readers", "writer"], ["Aurora", "GlobalAurora"], "Aurora database");
-    // GlobalAurora-only options on non-global databases
-    warnIfPropertiesIgnored(props, ["primaryRegion", "secondaryRegions", "enableGlobalWriteForwarding"], "GlobalAurora", "GlobalAurora database");
+    for (const group of DATABASE_WARN_GROUPS) {
+        warnIfPropertiesIgnored(props, group.properties, group.applicableTypes, group.typeName);
+    }
 }
 /**
  * Validates database props and logs warnings for ignored or misconfigured options.

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

@@ -0,0 +1,15 @@
+import type { AuroraDatabaseProps, GlobalAuroraDatabaseProps, InstanceDatabaseProps } from "./database.js";
+import { type RelationalDatabaseType } from "./interfaces/database.js";
+type AllDatabasePropKeys = keyof AuroraDatabaseProps | keyof InstanceDatabaseProps | keyof GlobalAuroraDatabaseProps;
+export interface DatabaseWarnGroup {
+    properties: string[];
+    applicableTypes: RelationalDatabaseType[];
+    typeName: string;
+}
+export declare const DATABASE_WARN_GROUPS: readonly DatabaseWarnGroup[];
+/**
+ * Runtime key set for tests — derived from the compiled guard, never
+ * re-listed (typescript-standards § compile-time guards).
+ */
+export declare const ALL_DATABASE_PROP_KEYS: AllDatabasePropKeys[];
+export {};

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

@@ -0,0 +1,98 @@
+import { RELATIONAL_DATABASE_TYPES } from "./interfaces/database.js";
+/**
+ * Compile-time lockstep guard for `validateRelationalDatabaseProps`'s
+ * ignored-prop warnings — the database twin of `COMPUTE_PROP_APPLICABILITY`.
+ * The Record over the full top-level key union rejects BOTH a missing key (a
+ * new prop added to any relational props interface fails TS2741 here until
+ * classified) and a stale extra key (a removed/renamed prop fails TS2353).
+ * `"all"` means the prop is declared on every relational variant and never
+ * warns; a list names the variants that declare it, and a prop declared on
+ * two of the three variants is first-class here — the shape no
+ * single-variant hand list (or Exclude-difference bucket) can express.
+ *
+ * Applicability is DECLARATION, not type identity: `engine` and `encryption`
+ * map `"all"` although their TYPES differ per variant (`IClusterEngine` vs
+ * `IInstanceEngine`, `AuroraEncryptionConfig` vs `EncryptionConfig`) — every
+ * variant reads them, so they are never ignored and must never warn.
+ */
+const DATABASE_PROP_APPLICABILITY = {
+    type: "all",
+    vpc: "all",
+    databaseName: "all",
+    instanceType: "all",
+    deletionProtection: "all",
+    appBackupTier: "all",
+    alertsTopic: "all",
+    alarms: "all",
+    applicationId: "all",
+    migrations: "all",
+    databaseEngine: "all",
+    engine: "all",
+    port: "all",
+    proxy: "all",
+    credentials: "all",
+    encryption: "all",
+    backupRetention: "all",
+    databaseInsights: "all",
+    snapshotIdentifier: "all",
+    snapshotUsername: "all",
+    writer: ["Aurora", "GlobalAurora"],
+    readers: ["Aurora", "GlobalAurora"],
+    monitoringInterval: ["Aurora", "GlobalAurora"],
+    preferredMaintenanceWindow: ["Aurora", "GlobalAurora"],
+    removalPolicy: ["Aurora"],
+    engineVersion: ["Aurora"],
+    clusterIdentifier: ["Aurora"],
+    credentialsSecretName: ["Aurora"],
+    credentialsKmsAliasName: ["Aurora"],
+    serverlessV2MinCapacity: ["Aurora"],
+    serverlessV2MaxCapacity: ["Aurora"],
+    serverlessV2AutoPauseDuration: ["Aurora"],
+    enableDataApi: ["Aurora"],
+    allowVpcAccess: ["Aurora"],
+    allowedIpCidr: ["Aurora"],
+    publiclyAccessible: ["Aurora", "Instance"],
+    primaryRegion: ["GlobalAurora"],
+    secondaryRegions: ["GlobalAurora"],
+    globalClusterIdentifier: ["GlobalAurora"],
+    enableGlobalWriteForwarding: ["GlobalAurora"],
+    allocatedStorage: ["Instance"],
+    multiAz: ["Instance"],
+    readReplica: ["Instance"],
+    iamAuthentication: ["Instance"]
+};
+/**
+ * The variant literals are already the user-facing vocabulary (the
+ * `type: "Aurora"` a user writes), so the warning names exactly that —
+ * no label table to keep in step. Groups are keyed on the variants in
+ * `RELATIONAL_DATABASE_TYPES` order, so two entries declaring the same
+ * variants in a different order land in one group with one label.
+ */
+const orderedVariants = (variants) => [...variants].sort((a, b) => RELATIONAL_DATABASE_TYPES.indexOf(a) -
+    RELATIONAL_DATABASE_TYPES.indexOf(b));
+export const DATABASE_WARN_GROUPS = (() => {
+    const groups = new Map();
+    for (const [prop, applicability] of Object.entries(DATABASE_PROP_APPLICABILITY)) {
+        if (applicability === "all")
+            continue;
+        const applicableTypes = orderedVariants(applicability);
+        const key = applicableTypes.join("+");
+        const existing = groups.get(key);
+        if (existing !== undefined) {
+            existing.properties.push(prop);
+        }
+        else {
+            groups.set(key, {
+                properties: [prop],
+                applicableTypes,
+                typeName: applicableTypes.join(" or ") + " database"
+            });
+        }
+    }
+    return [...groups.values()];
+})();
+/**
+ * Runtime key set for tests — derived from the compiled guard, never
+ * re-listed (typescript-standards § compile-time guards).
+ */
+export const ALL_DATABASE_PROP_KEYS = Object.keys(DATABASE_PROP_APPLICABILITY);

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

@@ -92,32 +92,60 @@ async function findExistingTaskArn(client, clusterArn, startedBy) {
   return result.taskArns[0];
 }
 
+function describeFailureReason(desc) {
+  const failure = desc && desc.failures && desc.failures[0];
+  return failure && failure.reason ? failure.reason : "no failure reported";
+}
+
+// DescribeTasks is eventually consistent with RunTask: for a few seconds
+// after a launch it answers `tasks: []` with a MISSING failure for the very
+// ARN RunTask just returned. Until the task has been seen once, a miss is
+// "not visible yet" and the poll continues; once it has been seen, a miss is
+// the task vanishing, which is loud. A task never seen inside one
+// invocation's poll budget is loud too — that is a hundred seconds, not
+// consistency lag.
 async function pollTaskUntilStopped(client, clusterArn, taskArn, sleep) {
   const sleepFn =
     sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let seen = false;
+  let lastMissReason = "no failure reported";
   for (let i = 0; i < MAX_POLLS_PER_INVOCATION; i++) {
     const desc = await client.send(
       new DescribeTasksCommand({ cluster: clusterArn, tasks: [taskArn] })
     );
     const task = desc.tasks && desc.tasks[0];
-    if (!task) {
-      return { hookStatus: "FAILED", reason: "DescribeTasks returned no task" };
-    }
-    if (task.lastStatus === "STOPPED") {
-      const exitCode =
-        task.containers && task.containers[0]
-          ? task.containers[0].exitCode
-          : undefined;
-      if (exitCode === 0) return { hookStatus: "SUCCEEDED" };
-      return {
-        hookStatus: "FAILED",
-        reason: `Task exited ${exitCode}: ${task.stoppedReason || "no reason"}`
-      };
+    if (task) {
+      seen = true;
+      if (task.lastStatus === "STOPPED") {
+        const exitCode =
+          task.containers && task.containers[0]
+            ? task.containers[0].exitCode
+            : undefined;
+        if (exitCode === 0) return { hookStatus: "SUCCEEDED" };
+        return {
+          hookStatus: "FAILED",
+          reason: `Task exited ${exitCode}: ${task.stoppedReason || "no reason"}`
+        };
+      }
+    } else {
+      lastMissReason = describeFailureReason(desc);
+      if (seen) {
+        return {
+          hookStatus: "FAILED",
+          reason: `DescribeTasks returned no task after it had been seen (${lastMissReason})`
+        };
+      }
     }
     if (i < MAX_POLLS_PER_INVOCATION - 1) {
       await sleepFn(POLL_INTERVAL_MS);
     }
   }
+  if (!seen) {
+    return {
+      hookStatus: "FAILED",
+      reason: `DescribeTasks returned no task in ${MAX_POLLS_PER_INVOCATION} polls (${lastMissReason})`
+    };
+  }
   return {
     hookStatus: "IN_PROGRESS",
     callBackDelay: HOOK_CALLBACK_DELAY_SECONDS

package/dist/lib/resources/aws/secrets/kms.d.ts

@@ -10,6 +10,14 @@ export type KeyProtectionScope = (typeof KEY_PROTECTION_SCOPES)[number];
  * forgotten (tier-aware alert policy design §8 K4, `KMS_KEY_ORPHAN`).
  */
 export { KMS_RETENTION_TAG_KEY } from "@fjall/util/aws";
+/**
+ * Stamped beside the retention marker, valued with the alias name as `kms
+ * list-aliases` reports it. The alias resource goes with the stack and
+ * CloudFormation tags nothing on a KMS key, so after a stack delete this tag
+ * is the only thing that still says which stack's key a retained key was —
+ * the deploy-test teardown releases retained stack keys by it.
+ */
+export { KMS_ALIAS_TAG_KEY } from "@fjall/util/aws";
 interface CustomerManagedKeyProps {
     description?: string;
     aliasName?: string;

package/dist/lib/resources/aws/secrets/kms.js

@@ -1,4 +1,4 @@
-import { KMS_RETENTION_TAG_KEY } from "@fjall/util/aws";
+import { KMS_ALIAS_TAG_KEY, KMS_RETENTION_TAG_KEY } from "@fjall/util/aws";
 import { CfnOutput, Duration, RemovalPolicy, Tags } from "aws-cdk-lib";
 import { Alias, Key } from "aws-cdk-lib/aws-kms";
 import { Construct } from "constructs";
@@ -17,6 +17,14 @@ export const KEY_PROTECTION_SCOPES = [
  * forgotten (tier-aware alert policy design §8 K4, `KMS_KEY_ORPHAN`).
  */
 export { KMS_RETENTION_TAG_KEY } from "@fjall/util/aws";
+/**
+ * Stamped beside the retention marker, valued with the alias name as `kms
+ * list-aliases` reports it. The alias resource goes with the stack and
+ * CloudFormation tags nothing on a KMS key, so after a stack delete this tag
+ * is the only thing that still says which stack's key a retained key was —
+ * the deploy-test teardown releases retained stack keys by it.
+ */
+export { KMS_ALIAS_TAG_KEY } from "@fjall/util/aws";
 /**
  * How long a scheduled-for-deletion key stays recoverable.
  *
@@ -52,8 +60,10 @@ export class CustomerManagedKey extends Construct {
                 ? PENDING_DELETION_WINDOW
                 : undefined
         });
+        const aliasName = props.aliasName || ResourceNaming.defaultKeyAlias(id);
         if (removalPolicy === RemovalPolicy.RETAIN) {
             Tags.of(this.key).add(KMS_RETENTION_TAG_KEY, props.protects);
+            Tags.of(this.key).add(KMS_ALIAS_TAG_KEY, ResourceNaming.qualifiedKeyAlias(aliasName));
         }
         new CfnOutput(this, `${outputName}KeyArn`, {
             key: `${outputName}Arn`,
@@ -61,7 +71,7 @@ export class CustomerManagedKey extends Construct {
             exportName: stackScopedExportName(this, `${outputName}KeyArn`)
         });
         this.alias = new Alias(this, `${id}KeyAlias`, {
-            aliasName: props.aliasName || ResourceNaming.defaultKeyAlias(id),
+            aliasName,
             targetKey: this.key
         });
         new CfnOutput(this, `${outputName}KeyAliasArn`, {

package/dist/lib/resources/aws/secrets/stackEncryptionKey.js

@@ -1,8 +1,9 @@
 import { Stack } from "aws-cdk-lib";
 import { PolicyStatement, ServicePrincipal } from "aws-cdk-lib/aws-iam";
 import { tierDefault } from "../../../utils/backupTierMapping.js";
+import { ResourceNaming } from "../../../utils/resourceNaming.js";
 import { CustomerManagedKey } from "./kms.js";
-const STACK_ENCRYPTION_KEY_ID = "FjallStackEncryptionKey";
+const STACK_ENCRYPTION_KEY_ID = ResourceNaming.stackEncryptionKeyConstructId();
 /**
  * AWS services that publish to an application's SNS topics on the app's
  * behalf and therefore encrypt messages through the topic's key: EventBridge
@@ -48,9 +49,10 @@ export class StackEncryptionKey extends CustomerManagedKey {
     constructor(stack) {
         super(stack, STACK_ENCRYPTION_KEY_ID, {
             description: `Encrypts the enterprise-tier resources of ${stack.stackName} (DynamoDB tables, SNS topics, Lambda environment, ECS Exec sessions, log groups)`,
-            // KMS alias names are unique per account-region, so the stack name is
-            // the namespace — every stack in the account carries its own key.
-            aliasName: `cmk/${stack.stackName}/${STACK_ENCRYPTION_KEY_ID}`,
+            // Derived through ResourceNaming so the deploy-test teardown, which
+            // finds the retained key by this alias after the stack is gone, cannot
+            // spell it differently.
+            aliasName: ResourceNaming.stackEncryptionKeyAlias(stack.stackName),
             protects: "outlives-stack"
         });
     }

package/dist/lib/utils/backupTierMapping.d.ts

@@ -1,22 +1,17 @@
-import { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, type BackupTier, type BackupTierDefaults, tierDefault } from "@fjall/util";
-/** Tag key used by AWS Backup plan selection rules */
-export declare const BACKUP_TIER_TAG_KEY = "fjall:disasterRecovery:tier";
+import { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP, type BackupTier, type BackupTierDefaults, tierDefault } from "@fjall/util";
 /**
- * The application backup tier vocabulary and its defaults table are owned by
- * `@fjall/util` (`BACKUP_TIERS`, `BACKUP_TIER_DEFAULTS`, `tierDefault`) and
- * shared with the generator (`BACKUP_VAULT_TIERS`) and the CLI's synth
- * expectations, so every system derives from one declaration. Re-exported
- * here so construct code keeps one import path for tier concerns.
+ * The application backup tier vocabulary, its defaults table, the DR tag key
+ * and the tier → tag-value map are owned by `@fjall/util` (`BACKUP_TIERS`,
+ * `BACKUP_TIER_DEFAULTS`, `tierDefault`, `BACKUP_TIER_TAG_KEY`,
+ * `BACKUP_TIER_TAG_MAP`) and shared with the generator (`BACKUP_VAULT_TIERS`),
+ * the CLI's synth expectations and the webapp's posture rules (which read the
+ * tag back from discovered resources), so every system derives from one
+ * declaration. Re-exported here so construct code keeps one import path for
+ * tier concerns: `App.applyBackupTier()` (app-level tag), `StandardTagsAspect`
+ * (per-resource tag) and `BackupPlan` (selection key) all read the same pair.
  */
 export type { BackupTier, BackupTierDefaults };
-export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, tierDefault };
-/**
- * Shared mapping from application backup tier names to AWS Backup plan tag values.
- *
- * Used by both App.applyBackupTier() (app-level tag) and StandardTagsAspect
- * (per-resource tag) to ensure consistent tier → tag translation.
- */
-export declare const BACKUP_TIER_TAG_MAP: Readonly<Record<BackupTier, string>>;
+export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP, tierDefault };
 /**
  * The tier a resource actually runs under: its own override, else the
  * app-level tier `App.getApp({ backup: { tier } })` declared. The single

package/dist/lib/utils/backupTierMapping.js

@@ -1,18 +1,5 @@
-import { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, tierDefault } from "@fjall/util";
-/** Tag key used by AWS Backup plan selection rules */
-export const BACKUP_TIER_TAG_KEY = "fjall:disasterRecovery:tier";
-export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, tierDefault };
-/**
- * Shared mapping from application backup tier names to AWS Backup plan tag values.
- *
- * Used by both App.applyBackupTier() (app-level tag) and StandardTagsAspect
- * (per-resource tag) to ensure consistent tier → tag translation.
- */
-export const BACKUP_TIER_TAG_MAP = Object.freeze({
-    standard: "default",
-    resilient: "resilient",
-    enterprise: "enterprise"
-});
+import { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP, tierDefault } from "@fjall/util";
+export { BACKUP_TIERS, BACKUP_TIER_DEFAULTS, BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP, tierDefault };
 /**
  * The tier a resource actually runs under: its own override, else the
  * app-level tier `App.getApp({ backup: { tier } })` declared. The single

package/dist/lib/utils/resourceNaming.d.ts

@@ -77,6 +77,28 @@ export declare class ResourceNaming {
      * reports.
      */
     static defaultKeyAlias(constructId: string): string;
+    /**
+     * Construct id of the one `StackEncryptionKey` an enterprise-tier stack
+     * mints (lib/resources/aws/secrets/stackEncryptionKey.ts). It is also the
+     * alias suffix, so the two are spelled once.
+     */
+    static stackEncryptionKeyConstructId(): string;
+    /**
+     * Alias the stack encryption key is created under. KMS alias names are
+     * unique per account-region, so the stack name is the namespace. Unprefixed
+     * like the other alias helpers; the deploy tests that find the retained key
+     * after its stack is gone derive the reported form through
+     * [[qualifiedKeyAlias]], the same way the construct's alias tag does.
+     */
+    static stackEncryptionKeyAlias(stackName: string): string;
+    /**
+     * An alias name as KMS reports it. The CDK `Alias` prepends `alias/` to a
+     * resolved name that lacks it, and to a token only when the token's
+     * leading literal fragment lacks it — every Fjall alias starts with the
+     * literal `cmk/`, so the two rules agree. An already-qualified name is
+     * returned as it is.
+     */
+    static qualifiedKeyAlias(aliasName: string): string;
     /**
      * S3 bucket holding a VPC's flow logs. `id` is the Network construct id —
      * the network name for an additional VPC, `${stackPrefix}Vpc` for the

package/dist/lib/utils/resourceNaming.js

@@ -1,6 +1,8 @@
 import { toKebab } from "./capitaliseString.js";
 /** ELBv2's hard limit on an Application Load Balancer's name. */
 const LOAD_BALANCER_NAME_MAX_LENGTH = 32;
+/** What `kms list-aliases` prepends to every alias name. */
+const KMS_ALIAS_PREFIX = "alias/";
 /**
  * Centralised resource naming for infrastructure.
  * Ensures consistent, predictable names across constructs and tests.
@@ -127,6 +129,36 @@ export class ResourceNaming {
     static defaultKeyAlias(constructId) {
         return `cmk/${constructId}`;
     }
+    /**
+     * Construct id of the one `StackEncryptionKey` an enterprise-tier stack
+     * mints (lib/resources/aws/secrets/stackEncryptionKey.ts). It is also the
+     * alias suffix, so the two are spelled once.
+     */
+    static stackEncryptionKeyConstructId() {
+        return "FjallStackEncryptionKey";
+    }
+    /**
+     * Alias the stack encryption key is created under. KMS alias names are
+     * unique per account-region, so the stack name is the namespace. Unprefixed
+     * like the other alias helpers; the deploy tests that find the retained key
+     * after its stack is gone derive the reported form through
+     * [[qualifiedKeyAlias]], the same way the construct's alias tag does.
+     */
+    static stackEncryptionKeyAlias(stackName) {
+        return `cmk/${stackName}/${ResourceNaming.stackEncryptionKeyConstructId()}`;
+    }
+    /**
+     * An alias name as KMS reports it. The CDK `Alias` prepends `alias/` to a
+     * resolved name that lacks it, and to a token only when the token's
+     * leading literal fragment lacks it — every Fjall alias starts with the
+     * literal `cmk/`, so the two rules agree. An already-qualified name is
+     * returned as it is.
+     */
+    static qualifiedKeyAlias(aliasName) {
+        return aliasName.startsWith(KMS_ALIAS_PREFIX)
+            ? aliasName
+            : `${KMS_ALIAS_PREFIX}${aliasName}`;
+    }
     /**
      * S3 bucket holding a VPC's flow logs. `id` is the Network construct id —
      * the network name for an additional VPC, `${stackPrefix}Vpc` for the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "35.0.0",
+  "version": "37.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -80,8 +80,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^35.0.0",
-    "@fjall/util": "^35.0.0",
+    "@fjall/generator": "^37.0.0",
+    "@fjall/util": "^37.0.0",
     "constructs": "^10.7.2",
     "zod": "^4.4.3"
   },