@fjall/components-infrastructure 0.95.0 → 0.99.1

package/dist/lib/app.d.ts

@@ -8,7 +8,13 @@ import { type Ecr } from "./resources/aws/storage/ecr.js";
 import { type AnyDatabase } from "./patterns/aws/database.js";
 import { type INetworkProps, type Network } from "./patterns/aws/network.js";
 import { type Cdn } from "./patterns/aws/cdn.js";
-import { type AnyMessaging } from "./patterns/aws/messaging.js";
+import { type VpcPeer } from "./patterns/aws/vpcPeer.js";
+import { type VpcPeerAccepter } from "./patterns/aws/vpcPeerAccepter.js";
+import { type AnyMessaging, type EventBusMessaging } from "./patterns/aws/messaging.js";
+import { Schedule, type ScheduleProps } from "./resources/aws/messaging/schedule.js";
+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 { type Storage, type StorageFactoryFn } from "./patterns/aws/storage.js";
 import { type AnyPattern } from "./patterns/aws/pattern.js";
@@ -61,6 +67,20 @@ export interface IAppOptions {
     tunnel?: {
         instanceType?: string;
     } | boolean;
+    /**
+     * EventBridge default-bus override (T7a, D2 + D17).
+     *
+     * - `name?` overrides the AWS `EventBus.Name` (defaults to the app name).
+     * - `removalPolicy?` overrides the env-resolved default. Default resolves
+     *   via `env({ default: "DESTROY", production: "RETAIN" })` per D17 — NOT
+     *   `process.env.NODE_ENV` (which is not set during CDK synth in Fjall's
+     *   deployment paths). The shape is the normalised string union per
+     *   D18(d), NOT the raw CDK `RemovalPolicy` enum.
+     */
+    eventBus?: {
+        name?: string;
+        removalPolicy?: RemovalPolicyString;
+    };
 }
 /**
  * The basic corner-stone of all Fjall-hosted applications.
@@ -76,6 +96,9 @@ export declare class App extends CdkApp {
     private vpc?;
     private additionalVpcs;
     private defaultEcr;
+    private defaultEventBus?;
+    private eventBusOverride?;
+    private defaultNamespace?;
     private defaultAuditRole;
     private auditRoleExternalId?;
     private bastion?;
@@ -85,63 +108,19 @@ export declare class App extends CdkApp {
     private resourceInventory?;
     private manifestCollector;
     private constructor();
-    /**
-     * Apply backup tier tag to all resources in the app.
-     * Maps tier names to AWS Backup plan tag values.
-     */
     private applyBackupTag;
-    /**
-     * Initialise the tunnel bastion in the network stack.
-     * Creates a minimal EC2 instance for SSM port forwarding to databases.
-     */
     private initialiseTunnel;
-    /**
-     * Initialise the network (VPC) for this application.
-     */
     private initialiseNetwork;
-    /**
-     * Get the application name.
-     * @returns {string} The application name
-     */
     getName(): string;
-    /**
-     * Get/Create a basic Fjall Application with standard tags applied.
-     *
-     * @param name Application name
-     * @param options Configuration options including network settings
-     * @returns {App}
-     *
-     * @example
-     * // Create app with new VPC
-     * const app = App.getApp(appName, {
-     *   network: { maxAzs: 2, natGateways: false }
-     * });
-     *
-     * @example
-     * // Create app using existing VPC
-     * const app = App.getApp(appName, {
-     *   network: { useExisting: "vpc-12345678" }
-     * });
-     *
-     * @example
-     * // Create app without network (S3-only apps)
-     * const app = App.getApp(appName, { network: false });
-     */
     static getApp(name?: string, options?: IAppOptions): App;
-    /**
-     * Get/Create the singleton instance of the App
-     * @param name Application name
-     * @param options Configuration options including network settings
-     * @returns {App}
-     */
     static getInstance(name?: string, options?: IAppOptions): App;
+    static resetForTesting(): void;
     /**
      * Retrieve a stack by key. If the stack does not exist, it will be created.
      *  Dependencies are only applied the first time a stack is created.
      *
      * @param key - The key of the stack
      * @param dependencies - The stack(s) that this stack depends on
-     * @returns {AwsStack}
      */
     getStack(key: string, dependencies?: AwsStack | AwsStack[]): AwsStack;
     /**
@@ -149,23 +128,18 @@ export declare class App extends CdkApp {
      *
      * Only depends on Network. Database dependency is added automatically
      * by CDK when compute resources reference database resources.
-     *
-     * @returns {AwsStack}
      */
     getDefaultComputeStack(): AwsStack;
     /**
      * Retrieve default network stack - named as `${this.name}Network`
-     * @returns {AwsStack}
      */
     getDefaultNetworkStack(): AwsStack;
     /**
      * Retrieve default database stack - named as `${this.name}Database`
-     * @returns {AwsStack}
      */
     getDefaultDatabaseStack(): AwsStack;
     /**
      * Retrieve default storage stack - named as `${this.name}Storage`
-     * @returns {AwsStack}
      */
     getDefaultStorageStack(): AwsStack;
     /**
@@ -173,8 +147,6 @@ export declare class App extends CdkApp {
      *
      * Depends on Network. Compute/Storage dependencies are added automatically
      * by CDK when CDN resources reference ALB or S3 bucket resources.
-     *
-     * @returns {AwsStack}
      */
     getDefaultCdnStack(): AwsStack;
     /**
@@ -183,8 +155,6 @@ export declare class App extends CdkApp {
      * Used for SQS queues, SNS topics, and EventBridge event buses.
      * Depends on Network only. These are regional services that don't
      * require VPC, but we maintain consistent stack dependency patterns.
-     *
-     * @returns {AwsStack}
      */
     getDefaultMessagingStack(): AwsStack;
     /**
@@ -194,21 +164,42 @@ export declare class App extends CdkApp {
      * Network must be configured via App.getApp() options or app.addNetwork().
      *
      * @param name - Optional name of the VPC to retrieve. If not provided, returns the default VPC.
-     * @returns {IVpc} The configured VPC
      * @throws {Error} If network is disabled, not configured, or named VPC not found
      */
     getVpc(name?: string): IVpc;
+    getVpcNames(): string[];
+    getDefaultContainerRegistry(): Ecr;
     /**
-     * Get the names of all available VPCs.
+     * Lazy getter for the per-app default custom EventBridge bus (D2).
      *
-     * @returns {string[]} Array of VPC names. Includes "default" if the default VPC is configured.
+     * Buses are recreatable in non-prod; the env-resolved default keeps prod
+     * history. The override (`App.getApp({ eventBus: { name?, removalPolicy? } })`)
+     * is consulted first; absent override falls back to the app name and the
+     * `env({ default: "DESTROY", production: "RETAIN" })` resolution per D17.
+     * NODE_ENV is not consulted — it is not set during CDK synth in Fjall's
+     * deployment paths.
      */
-    getVpcNames(): string[];
+    getEventBus(): EventBusMessaging;
     /**
-     * Retrieve the default application container registry. If the registry does not exist
-     *  it will be created.
+     * Lazy getter for the per-app Cloud Map private DNS namespace (D7 + D29 of
+     * the ClickHouse Database Factory promotion design).
+     *
+     * The namespace is constructed in the network stack on first call and
+     * reused thereafter — `app.getNamespace() === app.getNamespace()`. Default
+     * name is `${toKebab(appName)}.local` per the implementation-defined
+     * derivation rule; v1 has no override config option (D29). Returns the
+     * `IPrivateDnsNamespace` interface per D18(a), never the concrete class.
      */
-    getDefaultContainerRegistry(): Ecr;
+    getNamespace(): IPrivateDnsNamespace;
+    /**
+     * Register a Cloud Map service against the per-app namespace. Lazily creates
+     * the namespace on first call (same construct as `getNamespace()`) and
+     * delegates to the `ServiceDiscoveryNamespace` wrapper's `registerService`
+     * — keeping both halves of Cloud Map (namespace + services) routed through
+     * the wrapper layer per § Wrapper Routing Discipline.
+     */
+    registerService(props: ServiceRegistrationProps): IService;
+    private ensureNamespace;
     /**
      * Create a cross-account audit role in the Network stack that allows
      * the Fjall platform to use CloudQuery for comprehensive AWS resource auditing.
@@ -218,18 +209,9 @@ export declare class App extends CdkApp {
      *
      * @param webappAccountId - Optional AWS account ID of the Fjall webapp. Defaults to configured platform account.
      * @param externalId - Optional external ID for additional security. If not provided, a unique ID will be generated.
-     * @returns {Role} The created audit role
      */
     createAuditRole(webappAccountId?: string, externalId?: string): Role;
-    /**
-     * Get the external ID used for the audit role
-     * @returns {string | undefined} The external ID if audit role has been created
-     */
     getAuditRoleExternalId(): string | undefined;
-    /**
-     * Generate a unique external ID for audit role
-     * Format: fjall-audit-{appName}-{timestamp}
-     */
     private generateAuditExternalId;
     /**
      * Add a compute resource to the default compute stack using the factory pattern.
@@ -255,10 +237,7 @@ export declare class App extends CdkApp {
      * }));
      * worker.getFunction("process"); // Available on LambdaCompute
      */
-    addCompute<T extends AnyCompute>(fn: (app: App, scope: Construct) => T): T;
-    /**
-     * Manually add a resource to the default compute stack.
-     */
+    addCompute<T extends AnyCompute & Construct>(fn: (app: App, scope: Construct) => T): T;
     addComputeResource(resource: Construct): void;
     /**
      * Add a database resource to the default database stack using the factory pattern.
@@ -280,10 +259,7 @@ export declare class App extends CdkApp {
      * }));
      * cache.getTableName(); // Available
      */
-    addDatabase<T extends AnyDatabase>(fn: (app: App, scope: Construct) => T): T;
-    /**
-     * Type guard for IConnectable — checks if a construct has a connections property.
-     */
+    addDatabase<T extends AnyDatabase & Construct>(fn: (app: App, scope: Construct) => T): T;
     private isConnectable;
     /**
      * Add a storage resource (S3) to the default storage stack using the factory pattern.
@@ -322,6 +298,22 @@ export declare class App extends CdkApp {
      * }));
      */
     addCdn(fn: (app: App, scope: Construct) => Cdn): Cdn;
+    /**
+     * Peer this app's VPC with a remote app's VPC.
+     *
+     * Creates the peering connection plus routes on both sides. The remote app
+     * must have deployed a `VpcPeerAccepter` first. Note: `app.getVpc(peerAppName)`
+     * does NOT return the peer's VPC — callers wanting the remote handle must use
+     * the returned `VpcPeer` instance.
+     */
+    addVpcPeer(fn: (app: App, scope: Construct) => VpcPeer): VpcPeer;
+    /**
+     * Accept VPC peering requests from remote apps.
+     *
+     * Creates an IAM role for cross-account peering acceptance and return-route
+     * management, and publishes VPC metadata to SSM for discovery.
+     */
+    addVpcPeerAccepter(fn: (app: App, scope: Construct) => VpcPeerAccepter): VpcPeerAccepter;
     /**
      * Add a messaging resource to the default queue stack using the factory pattern.
      *
@@ -347,7 +339,22 @@ export declare class App extends CdkApp {
      *   contentBasedDeduplication: true
      * }));
      */
-    addMessaging<T extends AnyMessaging>(fn: (app: App, scope: Construct) => T): T;
+    addMessaging<T extends AnyMessaging & Construct>(fn: (app: App, scope: Construct) => T): T;
+    /**
+     * Register an EventBridge schedule against a Fjall wrapper target.
+     *
+     * Defaults to the messaging stack; set `props.stackPlacement = "compute"`
+     * when the schedule's target lives in the compute stack and cross-stack
+     * output churn is undesired. `applicationId` is threaded automatically
+     * from `app.getName()` for alarm webhook routing per D13.
+     *
+     * @example
+     * app.addSchedule("MetricsCollection", {
+     *   schedule: "rate(5 minutes)",
+     *   target: notificationsQueue
+     * });
+     */
+    addSchedule(id: string, props: Omit<ScheduleProps, "applicationId">): Schedule;
     /**
      * Add a high-level infrastructure pattern to the application.
      *
@@ -375,7 +382,7 @@ export declare class App extends CdkApp {
      * payload.getServer().getLambdaFunction().addEnvironment("CUSTOM", "value");
      * payload.getCdn().getDistribution().addBehavior("/custom/*", customOrigin);
      */
-    addPattern<T extends AnyPattern>(fn: (app: App, scope: Construct) => T): T;
+    addPattern<T extends AnyPattern & Construct>(fn: (app: App, scope: Construct) => T): T;
     /**
      * Add an additional network (VPC) to the application.
      *
@@ -383,7 +390,6 @@ export declare class App extends CdkApp {
      * Additional VPCs can be retrieved by name using app.getVpc(name).
      *
      * @param fn - Factory function that creates the Network construct
-     * @returns {Network} The created Network construct
      *
      * @example
      * const isolatedVpc = app.addNetwork(
@@ -391,21 +397,9 @@ export declare class App extends CdkApp {
      * );
      */
     addNetwork(fn: (app: App, scope: Construct) => Network): Network;
-    /**
-     * Manually add a resource to the default database stack.
-     */
     addDatabaseResource(resource: Construct): void;
-    /**
-     * Manually add a resource to the default storage stack.
-     */
     addStorageResource(resource: Construct): void;
-    /**
-     * Initialise standard tags
-     */
     private initialiseStandardTags;
-    /**
-     * Apply all tags using CDK's native Tags.of().add() API
-     */
     private applyTagsAspect;
     /**
      * Add custom tags to all resources in the app.
@@ -414,27 +408,16 @@ export declare class App extends CdkApp {
      * @example
      * app.addTags({
      *   "fjall:costAllocation:owner": "platform-team",
-     *   "fjall:costAllocation:cost-center": "CC-123",
+     *   "fjall:costAllocation:cost-centre": "CC-123",
      *   "team:slack-channel": "#platform-alerts"
      * });
      */
     addTags(tags: {
         [key: string]: string;
     }): App;
-    /**
-     * Export resource inventory collected during synthesis
-     * Call this after app.synth() to get complete resource inventory
-     * @returns {ResourceInventory} Complete inventory of all resources in the app
-     */
+    /** Call after app.synth() — inventory is not available before synthesis. */
     exportResourceInventory(): ResourceInventory;
-    /**
-     * Get the manifest collector for registering services and patterns.
-     * Used by ComputeFactory and PatternFactory to register their configurations.
-     */
     getManifestCollector(): ManifestCollector;
-    /**
-     * Override synth to automatically export resource inventory and manifest
-     */
     synth(options?: StageSynthesisOptions): CloudAssembly;
 }
 export default App;