@fjall/components-infrastructure 0.89.5 → 0.94.0

package/dist/lib/resources/aws/compute/ecsTypes.d.ts

@@ -0,0 +1,337 @@
+import { type ContainerDefinition, type RepositoryImage } from "aws-cdk-lib/aws-ecs";
+import { type IVpc } from "aws-cdk-lib/aws-ec2";
+import { type IManagedPolicy, type PolicyDocument } from "aws-cdk-lib/aws-iam";
+import { type TargetTrackingScalingPolicy } from "aws-cdk-lib/aws-applicationautoscaling";
+import { type GeoLocation } from "aws-cdk-lib/aws-route53";
+import { type Repository } from "aws-cdk-lib/aws-ecr";
+import { type FargateService, type Ec2Service, type FargateTaskDefinition, type Ec2TaskDefinition } from "aws-cdk-lib/aws-ecs";
+import { type IApplicationTargetGroup } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type Role } from "aws-cdk-lib/aws-iam";
+import { type HostedZone as FjallHostedZone } from "../networking/hostedZone.js";
+import { type Certificate } from "aws-cdk-lib/aws-certificatemanager";
+import { type ConnectionSpec } from "../../../utils/connector.js";
+import { type SecretImport } from "../secrets/index.js";
+import type { ManagedDomainExports } from "../../../utils/domainTypes.js";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import type { EcsServiceAlarmThresholds } from "../monitoring/index.js";
+export declare enum Protocol {
+    HTTP = 0,
+    HTTPS = 1
+}
+export declare enum ScalingType {
+    CPU = "ECSServiceAverageCPUUtilization",
+    MEMORY = "ECSServiceAverageMemoryUtilization"
+}
+export type EcsCapacityProvider = "FARGATE" | "FARGATE_SPOT" | "EC2";
+/**
+ * EC2 capacity configuration for ECS EC2-backed clusters.
+ * Only used when capacityProvider is "EC2".
+ */
+export interface Ec2CapacityConfig {
+    /** EC2 instance type. Default: "t4g.micro" */
+    instanceType?: string;
+    /** AMI hardware type. Default: "ARM" (Graviton - better cost/performance) */
+    amiHardwareType?: "ARM" | "STANDARD";
+    /** Minimum number of instances. Default: 2 */
+    minCapacity?: number;
+    /** Maximum number of instances. Default: 3 */
+    maxCapacity?: number;
+    /** Memory limit in MiB for the container. Default: 1024 */
+    memoryLimitMiB?: number;
+    /** Warm pool keeps stopped instances for faster start (10-15s vs 60-90s).
+     *  Mirrors generator WarmPool type (generator/src/schemas/computeSchemas.ts). */
+    warmPool?: {
+        /** Minimum instances to keep in the warm pool. Default: 1 */
+        minSize?: number;
+        /** Return instances to the pool on scale-in instead of terminating. Default: true */
+        reuseOnScaleIn?: boolean;
+    };
+}
+/**
+ * Domain configuration for HTTPS and DNS.
+ */
+export interface DomainBaseConfig {
+    domainName: string;
+    hostedZone?: FjallHostedZone;
+    certificate?: Certificate;
+    setIdentifier?: string;
+    /** Import zone and cert from a managed domain stack via Fn.importValue() */
+    managedDomain?: ManagedDomainExports;
+}
+export interface LatencyDomainConfig extends DomainBaseConfig {
+    region: string;
+}
+export interface WeightedDomainConfig extends DomainBaseConfig {
+    weight: number;
+}
+export interface GeoLocationDomainConfig extends DomainBaseConfig {
+    geoLocation: GeoLocation;
+}
+export type DomainConfig = DomainBaseConfig | LatencyDomainConfig | WeightedDomainConfig | GeoLocationDomainConfig;
+/**
+ * Internal configuration for a container in a multi-container ECS task.
+ *
+ * In multi-container tasks, the first container with a `port` is the **primary container**
+ * that receives load balancer traffic. All other containers are **sidecars** that provide
+ * supporting functionality (logging, monitoring, proxies, etc.).
+ *
+ * @example
+ * // Primary container (has port) + sidecar (no port)
+ * containers: [
+ *   { name: "app", port: 3000 },           // Primary - receives ALB traffic
+ *   { name: "datadog", image: "datadog/agent" }  // Sidecar - monitoring
+ * ]
+ *
+ * @internal
+ */
+export interface EcsClusterContainerConfig {
+    /** Unique container name */
+    name: string;
+    /**
+     * Container image. Options:
+     * - Omit: Uses default ECR repository (primary container only)
+     * - string: ECR repository name or public image URL
+     * - Repository: CDK ECR Repository construct
+     */
+    image?: string | Repository;
+    /**
+     * Port the container listens on.
+     * The first container with a port becomes the **primary container**
+     * and is registered with the load balancer.
+     */
+    port?: number;
+    /** Environment variables */
+    environment?: Record<string, string>;
+    /**
+     * Secrets from AWS SSM Parameter Store.
+     * Array of secret names that will be fetched from the service's SSM namespace.
+     *
+     * @example
+     * secrets: ["API_KEY", "DB_PASSWORD"]
+     */
+    secrets?: string[];
+    /** Secrets imported from other CDK resources (AWS Secrets Manager) */
+    secretsImport?: {
+        [key: string]: SecretImport;
+    };
+    /** Command to run in the container */
+    command?: string[];
+    /** Entry point for the container */
+    entryPoint?: string[];
+    /**
+     * Whether this container is essential.
+     * If an essential container stops, all containers in the task stop.
+     * Default: true for primary container, true for sidecars
+     */
+    essential?: boolean;
+    /**
+     * Health check configuration.
+     * Default: For primary container with port, uses curl health check.
+     */
+    healthCheck?: {
+        command: string[];
+        interval?: number;
+        timeout?: number;
+        retries?: number;
+        startPeriod?: number;
+    };
+}
+/**
+ * Cluster-level configuration.
+ * Controls the shared ALB for all services in this cluster.
+ */
+export interface EcsClusterClusterConfig {
+    /**
+     * Domain for HTTPS access.
+     * - Omit: ALB created with default DNS (*.elb.amazonaws.com)
+     * - Specified: Creates ACM certificate + Route53 DNS A record
+     */
+    domain?: string;
+    /**
+     * Load balancer configuration.
+     * - false: No ALB (for workers/internal services)
+     * - "public": Internet-facing ALB (default)
+     * - "internal": VPC-only ALB
+     */
+    loadBalancer?: false | "public" | "internal";
+    /**
+     * Enable direct EC2 access without ALB.
+     * Opens container ports on security group for direct access via EC2 public IP.
+     * Uses host network mode for predictable port mapping (container:3000 → host:3000).
+     * Only valid with EC2 capacity provider.
+     */
+    directAccess?: boolean;
+    /**
+     * Domain configuration for advanced routing policies (latency, weighted, geo).
+     * Only used when domain is specified.
+     */
+    domainConfig?: DomainConfig;
+}
+/**
+ * Routing configuration for path/host-based routing on the ALB.
+ */
+export interface EcsRoutingConfig {
+    /** Path pattern for routing (e.g., "/api/*", "/users/*") */
+    path?: string;
+    /** Host header for routing (e.g., "api.example.com") */
+    host?: string;
+    /** Priority for this routing rule (1-50000). Lower = higher priority. */
+    priority?: number;
+    /** Health check path for this service's target group. Default: "/" */
+    healthCheckPath?: string;
+}
+/**
+ * Configuration for a service in an ECS cluster.
+ * Each service gets its own task definition, scaling, and target group.
+ */
+export interface EcsServiceProps {
+    /** Service name (unique within cluster) */
+    name: string;
+    /**
+     * Container image for this service.
+     * - Omit: Uses cluster's default ECR repository
+     * - string: ECR repository name or public image URL
+     * - Repository: CDK ECR Repository construct
+     */
+    image?: string | Repository;
+    /**
+     * Container configurations for this service.
+     * 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?: number;
+    /** Memory in MiB for this service's tasks (512-30720) */
+    memoryLimitMiB?: number;
+    /** Desired number of tasks. Default: 2 */
+    desiredCount?: number;
+    /** Scaling type (CPU or MEMORY). Omit to disable auto-scaling. */
+    scalingType?: ScalingType;
+    /** Minimum number of tasks for auto-scaling. Default: 2 */
+    minCapacity?: number;
+    /** Maximum number of tasks for auto-scaling. Default: 10 */
+    maxCapacity?: number;
+    /**
+     * Routing rules for this service on the cluster's ALB.
+     * Required when cluster has multiple services with ports.
+     * Can be a single rule or an array of rules pointing to the same target group.
+     */
+    routing?: EcsRoutingConfig | EcsRoutingConfig[];
+    /**
+     * Additional inline policies for this service's task role.
+     * Added on top of the default ECS Exec permissions.
+     */
+    taskRoleInlinePolicies?: {
+        [name: string]: PolicyDocument;
+    };
+    /**
+     * Additional managed policies for this service's task role.
+     * Added on top of the default ECS Exec permissions.
+     */
+    taskRoleManagedPolicies?: IManagedPolicy[];
+    /**
+     * Resources this service needs to connect to (e.g., databases, S3 buckets, SQS queues).
+     * Creates security group rules for IConnectable resources and IAM grants for IAM resources.
+     *
+     * Supports:
+     * - IConnectable: Security group resources (RDS, ECS, etc.)
+     * - IStorageConnector: S3 buckets (IAM grants)
+     * - IDynamoDBConnector: DynamoDB tables (IAM grants)
+     * - IQueueConnector: SQS queues (IAM grants)
+     * - ConnectionConfig: Explicit access level configuration
+     *
+     * @example
+     * connections: [
+     *   database,                              // Security group (RDS)
+     *   { resource: cache, access: "read" },   // Read-only DynamoDB
+     *   { resource: bucket, access: "write" }, // Write-only S3
+     *   { resource: queue, access: "consume" } // Consume-only SQS
+     * ]
+     */
+    connections?: ConnectionSpec[];
+    /**
+     * Capacity provider for this service. REQUIRED.
+     * Each service specifies its own capacity provider.
+     */
+    capacityProvider: EcsCapacityProvider;
+    /**
+     * EC2 capacity configuration for this service.
+     * Only used when service capacityProvider is "EC2".
+     * Services with matching ec2Config share an ASG for efficiency.
+     */
+    ec2Config?: Ec2CapacityConfig;
+    /**
+     * SSM Parameter Store path for secrets.
+     * If containers have secrets defined, this path is used as the base path.
+     * Format: /<app>/<cluster>/<service>
+     *
+     * @example
+     * ssmSecretsPath: "/myapp/api-cluster/users"
+     */
+    ssmSecretsPath?: string;
+    /**
+     * Docker build target stage for multi-stage Dockerfiles.
+     * When specified, appends `-<target>` to the image tag.
+     *
+     * @example
+     * // With dockerTarget: "api", image tag becomes: myservice-api-latest
+     * dockerTarget: "api"
+     */
+    dockerTarget?: string;
+    /**
+     * Per-service alarm configuration.
+     * - undefined: use defaults (CPU, memory, running tasks, 5xx if ALB)
+     * - false: disable alarms for this service
+     * - object: override specific thresholds
+     */
+    alarms?: EcsServiceAlarmThresholds | false;
+}
+/**
+ * Props for creating an ECS cluster with multiple services.
+ */
+export interface EcsClusterProps {
+    /** Cluster name */
+    clusterName: string;
+    /**
+     * Application name for SSM secrets namespace.
+     * Required when any container uses secrets without explicit ssmSecretsPath.
+     * Used to build the path: /<appName>/<clusterName>/<serviceName>
+     */
+    appName?: string;
+    /** VPC to deploy into */
+    vpc?: IVpc;
+    /** Default ECR repository or container image */
+    ecrRepository: Repository | RepositoryImage | string;
+    /**
+     * Cluster configuration.
+     * Controls the shared ALB for all services.
+     */
+    cluster?: EcsClusterClusterConfig;
+    /**
+     * Services in this cluster.
+     * Each service gets its own task definition, scaling, and target group.
+     * Each service MUST specify its own capacityProvider.
+     * All services share the cluster's ALB (unless disabled).
+     * Task role policies are configured per-service for least-privilege.
+     */
+    services: EcsServiceProps[];
+    /** SNS topic for alarm notifications. Required for alarm creation. */
+    alertsTopic?: ITopic;
+    /** Application ID for alarm tagging (used by webhook to map alarms to applications). */
+    applicationId?: string;
+}
+/**
+ * Data tracked for each service in the cluster.
+ */
+export interface ServiceData {
+    service: FargateService | Ec2Service;
+    taskDefinition: FargateTaskDefinition | Ec2TaskDefinition;
+    /** Role for ECS agent (pull images, write logs, inject secrets) */
+    executionRole: Role;
+    /** Role for application code (user policies, ECS Exec) */
+    taskRole: Role;
+    containers: ContainerDefinition[];
+    primaryContainer?: ContainerDefinition;
+    targetGroup?: IApplicationTargetGroup;
+    scalingPolicy?: TargetTrackingScalingPolicy;
+}

package/dist/lib/resources/aws/compute/ecsTypes.js

@@ -0,0 +1,10 @@
+export var Protocol;
+(function (Protocol) {
+    Protocol[Protocol["HTTP"] = 0] = "HTTP";
+    Protocol[Protocol["HTTPS"] = 1] = "HTTPS";
+})(Protocol || (Protocol = {}));
+export var ScalingType;
+(function (ScalingType) {
+    ScalingType["CPU"] = "ECSServiceAverageCPUUtilization";
+    ScalingType["MEMORY"] = "ECSServiceAverageMemoryUtilization";
+})(ScalingType || (ScalingType = {}));

package/dist/lib/resources/aws/compute/ecsValidation.d.ts

@@ -0,0 +1,18 @@
+import type { EcsClusterProps } from "./ecsTypes.js";
+/**
+ * Validates ECS cluster props before construction.
+ * Pure function — does not depend on class state.
+ *
+ * @param props - The cluster props to validate
+ * @throws Error if validation fails
+ */
+export declare function validateEcsClusterProps(props: EcsClusterProps): void;
+/**
+ * Validates an SSM path component for correctness.
+ * SSM parameter paths have specific constraints that must be enforced.
+ *
+ * @param component - The path component to validate
+ * @param fieldName - Name of the field for error messages
+ * @throws Error if the component is invalid
+ */
+export declare function validateSsmPathComponent(component: string, fieldName: string): void;

package/dist/lib/resources/aws/compute/ecsValidation.js

@@ -0,0 +1,72 @@
+/**
+ * Validates ECS cluster props before construction.
+ * Pure function — does not depend on class state.
+ *
+ * @param props - The cluster props to validate
+ * @throws Error if validation fails
+ */
+export function validateEcsClusterProps(props) {
+    const loadBalancerDisabled = props.cluster?.loadBalancer === false ||
+        props.cluster?.directAccess === true;
+    // Validate services array
+    if (!props.services || props.services.length === 0) {
+        throw new Error("At least one service must be specified.");
+    }
+    // Check for duplicate service names
+    const serviceNames = props.services.map((s) => s.name);
+    const duplicateServices = serviceNames.filter((name, index) => serviceNames.indexOf(name) !== index);
+    if (duplicateServices.length > 0) {
+        throw new Error(`Duplicate service names: ${[...new Set(duplicateServices)].join(", ")}`);
+    }
+    // Validate routing when multiple services have ports
+    const servicesWithPorts = props.services.filter((s) => s.containers.some((c) => c.port !== undefined));
+    if (servicesWithPorts.length > 1 && !loadBalancerDisabled) {
+        const missingRouting = servicesWithPorts.filter((s) => {
+            const rules = Array.isArray(s.routing)
+                ? s.routing
+                : s.routing
+                    ? [s.routing]
+                    : [];
+            return !rules.some((r) => r.path || r.host);
+        });
+        if (missingRouting.length > 0) {
+            throw new Error(`Services with ports require routing config when cluster has multiple services: ` +
+                `${missingRouting.map((s) => s.name).join(", ")}. ` +
+                "Add routing: { path: '/...' } to each service.");
+        }
+    }
+    // Validate each service's containers
+    for (const service of props.services) {
+        if (!service.containers || service.containers.length === 0) {
+            throw new Error(`Service '${service.name}': At least one container must be specified.`);
+        }
+        // Check for duplicate container names within service
+        const containerNames = service.containers.map((c) => c.name);
+        const duplicateContainers = containerNames.filter((name, index) => containerNames.indexOf(name) !== index);
+        if (duplicateContainers.length > 0) {
+            throw new Error(`Service '${service.name}': Duplicate container names: ` +
+                `${[...new Set(duplicateContainers)].join(", ")}`);
+        }
+    }
+}
+/**
+ * Validates an SSM path component for correctness.
+ * SSM parameter paths have specific constraints that must be enforced.
+ *
+ * @param component - The path component to validate
+ * @param fieldName - Name of the field for error messages
+ * @throws Error if the component is invalid
+ */
+export function validateSsmPathComponent(component, fieldName) {
+    if (!component || component.trim() === "") {
+        throw new Error(`${fieldName} cannot be empty for SSM path derivation`);
+    }
+    if (component.includes("/")) {
+        throw new Error(`${fieldName} cannot contain forward slashes (/). Invalid value: "${component}".`);
+    }
+    // SSM parameter name hierarchy labels have a max length of 2048, but we use a more
+    // reasonable limit since each component is just one part of the path
+    if (component.length > 128) {
+        throw new Error(`${fieldName} exceeds maximum length (128 characters).`);
+    }
+}

package/dist/lib/resources/aws/compute/index.d.ts

@@ -1,3 +1,3 @@
-export * from "./ec2";
-export * from "./ecs";
-export * from "./lambda";
+export * from "./ec2.js";
+export * from "./ecs.js";
+export * from "./lambda.js";

package/dist/lib/resources/aws/compute/index.js

@@ -1,20 +1,3 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __exportStar = (this && this.__exportStar) || function(m, exports) {
-    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./ec2"), exports);
-__exportStar(require("./ecs"), exports);
-__exportStar(require("./lambda"), exports);
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi8uLi8uLi9saWIvcmVzb3VyY2VzL2F3cy9jb21wdXRlL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7Ozs7Ozs7Ozs7Ozs7Ozs7QUFBQSx3Q0FBc0I7QUFDdEIsd0NBQXNCO0FBQ3RCLDJDQUF5QiIsInNvdXJjZXNDb250ZW50IjpbImV4cG9ydCAqIGZyb20gXCIuL2VjMlwiO1xuZXhwb3J0ICogZnJvbSBcIi4vZWNzXCI7XG5leHBvcnQgKiBmcm9tIFwiLi9sYW1iZGFcIjtcbiJdfQ==
+export * from "./ec2.js";
+export * from "./ecs.js";
+export * from "./lambda.js";

package/dist/lib/resources/aws/compute/lambda.d.ts

@@ -6,8 +6,10 @@ import { Rule, type EventPattern } from "aws-cdk-lib/aws-events";
 import { type IQueue } from "aws-cdk-lib/aws-sqs";
 import { type ITable } from "aws-cdk-lib/aws-dynamodb";
 import { type Construct } from "constructs";
-import { type KeyValue } from "../../../types";
-import { type SecretImport } from "../secrets";
+import { type KeyValue } from "../../../types.js";
+import { type SecretImport } from "../secrets/index.js";
+import type { ITopic } from "aws-cdk-lib/aws-sns";
+import { type LambdaAlarmThresholds } from "../monitoring/index.js";
 export interface LambdaFunctionProps {
     code: Code;
     handler: string;
@@ -35,6 +37,12 @@ export interface LambdaFunctionProps {
     secretsImport?: Record<string, SecretImport>;
     appName?: string;
     functionName?: string;
+    /** SNS topic for alarm notifications. Required for alarm creation. */
+    alertsTopic?: ITopic;
+    /** Alarm thresholds. false to disable, undefined for defaults, object to override. */
+    alarms?: LambdaAlarmThresholds | false;
+    /** Application ID for alarm tagging. */
+    applicationId?: string;
 }
 export interface SingletonFunctionProps extends LambdaFunctionProps {
     uuid?: string;