@fjall/components-infrastructure 2.31.1 → 2.32.0

package/dist/lib/app.d.ts

@@ -16,6 +16,7 @@ import { type RemovalPolicyString } from "./resources/aws/messaging/utils.js";
 import { type ServiceRegistrationProps } from "./resources/aws/networking/serviceDiscovery.js";
 import { type IPrivateDnsNamespace, type IService } from "aws-cdk-lib/aws-servicediscovery";
 import { type AnyCompute } from "./patterns/aws/compute.js";
+import { DevSubstrate, type IDevSubstrateProps } from "./patterns/aws/devSubstrate.js";
 import { type Storage, type StorageFactoryFn } from "./patterns/aws/storage.js";
 import { type AnyPattern, type PatternFactoryFn } from "./patterns/aws/pattern.js";
 import { type BackupTier } from "./utils/backupTierMapping.js";
@@ -242,6 +243,23 @@ export declare class App extends CdkApp {
      */
     addCompute<T extends AnyCompute & Construct>(fn: (app: App, scope: Construct) => T): T;
     addComputeResource(resource: Construct): void;
+    /**
+     * Instantiate the internal `DevSubstrate` construct on the default compute
+     * stack (fast dev-envs Phase 3).
+     *
+     * Deliberately NOT routed through `PATTERN_TYPE_VALUES` / the pattern registry
+     * / `PatternFactory` / the `IPatternProps` union — the substrate is
+     * Fjall-managed dev infrastructure, never offered on the customer
+     * create/scaffold surface (design R5).
+     *
+     * Placement is load-bearing at DEPLOY time, not just synth: deploy-core selects
+     * stacks by a fixed six-category enum and derives deploy-order flags from
+     * post-synth stack-name suffixes (`endsWith("Compute")`), so scoping the
+     * substrate under `${stackPrefix}Compute` via `getDefaultComputeStack()` is
+     * what makes it actually deploy (design VF2). A dedicated `…DevSubstrate` stack
+     * would synth and hash but never deploy.
+     */
+    addDevSubstrate(props: IDevSubstrateProps): DevSubstrate;
     /**
      * Add a database resource to the default database stack using the factory pattern.
      * Returns the appropriate database type based on the factory used.
@@ -341,8 +359,16 @@ export declare class App extends CdkApp {
      *   visibilityTimeout: 300,
      *   contentBasedDeduplication: true
      * }));
+     *
+     * Pass `stackPlacement: "compute"` to co-locate the queue in the compute stack
+     * (mirrors `addStorage`/`addSchedule`). Required when a bucket's notification
+     * targets the queue within one app: an S3 notification and its auto-generated
+     * SQS queue policy reference each other's ARN, so splitting the two across the
+     * Storage and Messaging stacks synthesises a fatal cross-stack dependency cycle.
      */
-    addMessaging<T extends AnyMessaging & Construct>(fn: (app: App, scope: Construct) => T): T;
+    addMessaging<T extends AnyMessaging & Construct>(fn: (app: App, scope: Construct) => T, opts?: {
+        stackPlacement?: "messaging" | "compute";
+    }): T;
     /**
      * Register an EventBridge schedule against a Fjall wrapper target.
      *

package/dist/lib/app.js

@@ -9,6 +9,7 @@ import { NetworkFactory } from "./patterns/aws/network.js";
 import { MessagingFactory } from "./patterns/aws/messaging.js";
 import { Schedule } from "./resources/aws/messaging/schedule.js";
 import { ServiceDiscoveryNamespace } from "./resources/aws/networking/serviceDiscovery.js";
+import { DevSubstrate } from "./patterns/aws/devSubstrate.js";
 import { StandardTagsAspect } from "./utils/standardTagsAspect.js";
 import { BACKUP_TIER_TAG_KEY, BACKUP_TIER_TAG_MAP } from "./utils/backupTierMapping.js";
 import { randomBytes } from "crypto";
@@ -413,6 +414,28 @@ export class App extends CdkApp {
         const computeStack = this.getDefaultComputeStack();
         computeStack.addConstruct(resource);
     }
+    /**
+     * Instantiate the internal `DevSubstrate` construct on the default compute
+     * stack (fast dev-envs Phase 3).
+     *
+     * Deliberately NOT routed through `PATTERN_TYPE_VALUES` / the pattern registry
+     * / `PatternFactory` / the `IPatternProps` union — the substrate is
+     * Fjall-managed dev infrastructure, never offered on the customer
+     * create/scaffold surface (design R5).
+     *
+     * Placement is load-bearing at DEPLOY time, not just synth: deploy-core selects
+     * stacks by a fixed six-category enum and derives deploy-order flags from
+     * post-synth stack-name suffixes (`endsWith("Compute")`), so scoping the
+     * substrate under `${stackPrefix}Compute` via `getDefaultComputeStack()` is
+     * what makes it actually deploy (design VF2). A dedicated `…DevSubstrate` stack
+     * would synth and hash but never deploy.
+     */
+    addDevSubstrate(props) {
+        const computeStack = this.getDefaultComputeStack();
+        const substrate = new DevSubstrate(computeStack.getStack(), "DevSubstrate", this, props);
+        computeStack.addConstruct(substrate);
+        return substrate;
+    }
     /**
      * Add a database resource to the default database stack using the factory pattern.
      * Returns the appropriate database type based on the factory used.
@@ -556,11 +579,19 @@ export class App extends CdkApp {
      *   visibilityTimeout: 300,
      *   contentBasedDeduplication: true
      * }));
+     *
+     * Pass `stackPlacement: "compute"` to co-locate the queue in the compute stack
+     * (mirrors `addStorage`/`addSchedule`). Required when a bucket's notification
+     * targets the queue within one app: an S3 notification and its auto-generated
+     * SQS queue policy reference each other's ARN, so splitting the two across the
+     * Storage and Messaging stacks synthesises a fatal cross-stack dependency cycle.
      */
-    addMessaging(fn) {
-        const messagingStack = this.getDefaultMessagingStack();
-        const messaging = fn(this, messagingStack.getStack());
-        messagingStack.addConstruct(messaging);
+    addMessaging(fn, opts = {}) {
+        const stack = opts.stackPlacement === "compute"
+            ? this.getDefaultComputeStack()
+            : this.getDefaultMessagingStack();
+        const messaging = fn(this, stack.getStack());
+        stack.addConstruct(messaging);
         return messaging;
     }
     /**

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

@@ -28,7 +28,7 @@ export declare const DATABASE_ENGINE_CONFIG: Record<DatabaseEngine, {
     defaultUsername: string;
     sslParameters: Record<string, string>;
 }>;
-export declare function getAuroraClusterEngine(engine: DatabaseEngine): IClusterEngine;
+export declare function getAuroraClusterEngine(engine: DatabaseEngine, engineVersion?: string): IClusterEngine;
 export declare function getInstanceEngine(engine: DatabaseEngine): IInstanceEngine;
 export declare function getEngineConfig(engine: DatabaseEngine): EngineConfig;
 /**
@@ -59,6 +59,24 @@ export interface AuroraDatabaseProps extends BaseDatabaseProps {
     databaseEngine?: DatabaseEngine;
     /** Overrides databaseEngine if provided */
     engine?: IClusterEngine;
+    /**
+     * Aurora PostgreSQL version to build the engine at, e.g. `"16.6"`. Overrides
+     * the `databaseEngine` default version; ignored when `engine` is supplied.
+     * Required `>= 16.3` when `serverlessV2MinCapacity` is 0 (auto-pause floor).
+     */
+    engineVersion?: string;
+    /** Physical cluster identifier. Lower-cased; falls back to a derived name. */
+    clusterIdentifier?: string;
+    /** Physical name of the generated master-credentials secret. */
+    credentialsSecretName?: string;
+    /** Serverless-v2 floor in ACU. 0 enables scale-to-zero (auto-pause). */
+    serverlessV2MinCapacity?: number;
+    /** Serverless-v2 ceiling in ACU. */
+    serverlessV2MaxCapacity?: number;
+    /** Idle duration before an idle serverless-v2 cluster auto-pauses to 0 ACU. */
+    serverlessV2AutoPauseDuration?: Duration;
+    /** Enables the RDS Data API (HTTP endpoint) on the cluster. */
+    enableDataApi?: boolean;
     writer?: AuroraWriterConfig;
     readers?: AuroraReadersConfig | false;
     proxy?: ProxyConfig | false;

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

@@ -57,8 +57,19 @@ const INSTANCE_ENGINE_FACTORIES = {
         });
     }
 };
-export function getAuroraClusterEngine(engine) {
-    return AURORA_ENGINE_FACTORIES[engine]();
+export function getAuroraClusterEngine(engine, engineVersion) {
+    if (engineVersion === undefined) {
+        return AURORA_ENGINE_FACTORIES[engine]();
+    }
+    // The auto-pause version floor is enforced in RdsAurora, alongside the
+    // min-capacity knob that requires it — not here.
+    if (engine !== "postgresql") {
+        throw new Error(`engineVersion override is only supported for postgresql Aurora clusters (received "${engine}")`);
+    }
+    const majorVersion = engineVersion.split(".")[0] ?? "16";
+    return DatabaseClusterEngine.auroraPostgres({
+        version: AuroraPostgresEngineVersion.of(engineVersion, majorVersion)
+    });
 }
 export function getInstanceEngine(engine) {
     return INSTANCE_ENGINE_FACTORIES[engine]();
@@ -346,7 +357,8 @@ export class RelationalDatabase extends Construct {
     }
     addAurora(props) {
         const resolvedDatabaseEngine = props.databaseEngine ?? "postgresql";
-        const resolvedEngine = props.engine ?? getAuroraClusterEngine(resolvedDatabaseEngine);
+        const resolvedEngine = props.engine ??
+            getAuroraClusterEngine(resolvedDatabaseEngine, props.engineVersion);
         const engineConfig = getEngineConfig(resolvedDatabaseEngine);
         if (props.publiclyAccessible) {
             FjallLogger.warn(`Aurora database '${props.databaseName}' is configured with public accessibility. ` +
@@ -356,7 +368,14 @@ export class RelationalDatabase extends Construct {
             vpc: props.vpc,
             databaseName: props.databaseName,
             engine: resolvedEngine,
+            engineVersion: props.engineVersion,
             engineConfig,
+            clusterIdentifier: props.clusterIdentifier,
+            credentialsSecretName: props.credentialsSecretName,
+            serverlessV2MinCapacity: props.serverlessV2MinCapacity,
+            serverlessV2MaxCapacity: props.serverlessV2MaxCapacity,
+            serverlessV2AutoPauseDuration: props.serverlessV2AutoPauseDuration,
+            enableDataApi: props.enableDataApi,
             writer: props.writer,
             readers: props.readers,
             proxy: props.proxy,

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

@@ -0,0 +1,85 @@
+import { Construct } from "constructs";
+import type App from "../../app.js";
+/**
+ * Props for the internal `DevSubstrate` construct.
+ *
+ * Deliberately standalone — NOT a member of the `IPatternProps` union and NOT
+ * registered in `PATTERN_TYPE_VALUES` / the pattern registry / `PatternFactory`.
+ * The substrate is Fjall-managed dev infrastructure, never offered on the
+ * customer create/scaffold surface (design R5). Increments A2–A7 extend this
+ * interface (S3→SQS, compute/network, domain, delegation, `phase`) as each lands.
+ */
+export interface IDevSubstrateProps {
+    /**
+     * Real customer application identifier, surfaced as the `fjall:app` reaper
+     * tag. Distinct from the `fjall-dev-<app>` App identity that drives the
+     * substrate's stack names.
+     */
+    readonly appId: string;
+    /**
+     * Kebab-cased customer app name used to pin the substrate's physical resource
+     * names inside the `fjall-dev-*` fence (cluster identifier, master secret) so
+     * the dev-tier IAM grants match. Single-sourced with the `fjall-dev-<app>` App
+     * identity (design VERDICT-3).
+     */
+    readonly appKebab: string;
+    /**
+     * Aurora PostgreSQL engine version override (default `DEV_AURORA_DEFAULTS`).
+     * Must be `>= 16.3` — the shared cluster runs `serverlessV2MinCapacity` 0,
+     * which needs an auto-pause-capable engine (RdsAurora rejects lower at synth).
+     */
+    readonly engineVersion?: string;
+    /**
+     * When `true`, adopt an already-existing slot image ECR repository
+     * (`fjall-dev-<appKebab>-slots`) by reference instead of creating one — an
+     * import only, emitting no CloudFormation resource (and therefore untaggable).
+     * Defaults to `false`: create and fence-tag the repo. Set on a redeploy into an
+     * account where the repo was provisioned out-of-band.
+     */
+    readonly adoptSlotEcr?: boolean;
+    /**
+     * Deploy phase for the R2 two-step cert-hang guard. `"zone"` synthesises the
+     * `dev.<appDomain>` child zone + cross-account NS delegation only; `"full"`
+     * additionally builds the wildcard cert + :443 listener (A6) — deploy that
+     * only after the delegated NS has propagated, else ACM DNS-validation hangs.
+     * Defaults to `"full"`. Inert unless `domain` is set.
+     */
+    readonly phase?: "zone" | "full";
+    /**
+     * Public domain the substrate hangs a `dev.<appDomain>` child zone under. When
+     * omitted, the substrate stands up no zone/cert (early milestone — G2 reaches
+     * slots via `curl --resolve`).
+     *
+     * `parentDelegationRoleArn`, when present, wires the same-org **Case-1** in-stack
+     * NS delegation (design VD2-a): the child stack's `CrossAccountZoneDelegationRecord`
+     * assumes the parent account's `DelegationRole` by LITERAL ARN and UPSERTs the
+     * child NS into the parent zone. Omit it for a plain externally-owned parent
+     * (Case 3 — manual one-off delegation) or a connected different-org parent
+     * (Case 2 — worker UPSERT, B3b, deferred): the substrate then emits only the
+     * zone + its NS export for out-of-band delegation.
+     */
+    readonly domain?: {
+        readonly appDomain: string;
+        readonly parentDelegationRoleArn?: string;
+    };
+}
+/**
+ * Shared per-app substrate for ephemeral dev/preview slots (fast dev-envs
+ * Phase 3). Stands up the long-lived infrastructure a customer dev team's slots
+ * share — Aurora (A1), an S3→SQS drop (A2), an ECS cluster + slot SG (A2.5), an
+ * ALB with host-header routing (A3) fronted by a Lambda waker (A4), a delegated
+ * child zone (A5) and a wildcard cert (A6) — fenced to the development account.
+ *
+ * Instantiated ONLY via the internal `App.addDevSubstrate(props)`, which scopes
+ * it under the default compute stack so it actually deploys (design VF2). Every
+ * resource it creates carries `fjall:dev = "true"` (the IAM fence tag) and
+ * `fjall:app = <appId>` (the reaper tag) — including resources created through
+ * the app factories in sibling stacks, which are tagged explicitly since the
+ * `Tags.of(this)` aspect only reaches this construct's own scope subtree.
+ */
+export declare class DevSubstrate extends Construct {
+    #private;
+    private readonly app;
+    private readonly appId;
+    constructor(scope: Construct, id: string, app: App, props: IDevSubstrateProps);
+}