@fjall/components-infrastructure 0.77.4 → 0.78.5

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

@@ -1,79 +1,511 @@
 import { type RepositoryImage } from "aws-cdk-lib/aws-ecs";
 import { Repository } from "aws-cdk-lib/aws-ecr";
 import { Connections, type IConnectable, type IVpc, type UserData, type IMachineImage } from "aws-cdk-lib/aws-ec2";
-import { Code, Runtime, type FunctionUrlAuthType } from "aws-cdk-lib/aws-lambda";
-import { type Duration } from "aws-cdk-lib";
-import { type PolicyStatement } from "aws-cdk-lib/aws-iam";
+import { Code, Runtime, type FunctionUrlAuthType, type FunctionUrlCorsOptions } from "aws-cdk-lib/aws-lambda";
+import { type PolicyStatement, type PolicyDocument, type IManagedPolicy } from "aws-cdk-lib/aws-iam";
 import { Construct } from "constructs";
 import type App from "../../app";
-import { type DomainConfig } from "../../resources/aws/compute/ecs";
+import { ScalingType } from "../../resources/aws/compute/ecs";
 import { type SecretImport } from "../../resources/aws/secrets";
-export type HttpMethodString = "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS" | "PATCH";
-export interface SimplifiedCorsOptions {
-    allowedOrigins?: string[];
-    allowedMethods?: HttpMethodString[];
-    allowedHeaders?: string[];
-    maxAge?: Duration;
-    allowCredentials?: boolean;
-    exposeHeaders?: string[];
-}
-interface IComputeProps {
-    vpc?: IVpc;
-    ecrRepository?: Repository | RepositoryImage;
-    type?: "ecs" | "ec2" | "lambda";
-    ecsType?: "fargate" | "freetier" | "spot";
-    parentDomain?: string;
-    domainConfig?: DomainConfig;
+export type ComputeType = "ecs" | "ec2" | "lambda";
+export type EcsCapacityProvider = "FARGATE" | "FARGATE_SPOT" | "EC2";
+/**
+ * Configuration defaults for each compute type.
+ */
+export interface ComputeTypeConfig {
+    /** Default port for the compute type. ECS: 80, EC2: 22, Lambda: 0 (no port) */
+    defaultPort: number;
+    /** Default scaling limits */
+    defaultScaling: {
+        minCapacity: number;
+        maxCapacity: number;
+    };
+    /** Whether this compute type supports security group connections */
+    supportsConnections: boolean;
+    /** Whether this compute type requires a VPC */
+    requiresVpc: boolean;
+}
+export declare const COMPUTE_TYPE_CONFIG: Record<ComputeType, ComputeTypeConfig>;
+/**
+ * Configuration for ECS capacity providers.
+ */
+export interface EcsCapacityProviderConfig {
+    /** Whether this uses Spot pricing */
+    usesSpot: boolean;
+    /** Whether this runs on EC2 instances (vs serverless Fargate) */
+    usesEc2Instances: boolean;
+}
+export declare const ECS_CAPACITY_PROVIDER_CONFIG: Record<EcsCapacityProvider, EcsCapacityProviderConfig>;
+export declare function getComputeTypeConfig(type: ComputeType): ComputeTypeConfig;
+export declare function getEcsCapacityProviderConfig(provider: EcsCapacityProvider): EcsCapacityProviderConfig;
+export { HttpMethod, type FunctionUrlCorsOptions } from "aws-cdk-lib/aws-lambda";
+/**
+ * Configuration for a container in an ECS task.
+ *
+ * For single-container services, `name` is optional and defaults to `${serviceName}Container`.
+ * For multi-container tasks, the first container with a `port` is the **primary container**
+ * that receives load balancer traffic.
+ *
+ * @example
+ * // Single container (name auto-generated)
+ * containers: [{ port: 3000 }]
+ *
+ * @example
+ * // Multi-container with sidecars
+ * containers: [
+ *   { name: "app", port: 3000 },                    // Primary - receives ALB traffic
+ *   { name: "datadog", image: "datadog/agent" }     // Sidecar - monitoring
+ * ]
+ */
+export interface EcsContainerConfig {
+    /** Container name. Optional for single-container services. */
+    name?: string;
     /**
-     * Path to Dockerfile for building custom image.
-     * Note: This is metadata for the CLI build process,
-     * not used during CDK synthesis
+     * Container image. Options:
+     * - Omit: Uses app's default ECR repository (primary container only)
+     * - string: ECR repository name or public image URL
+     * - Repository: CDK ECR Repository construct
      */
-    dockerfilePath?: string;
+    image?: string | Repository;
     /**
-     * Port the container listens on (default: 80)
+     * Port the container listens on.
+     * The first container with a port becomes the **primary container**
+     * and is registered with the load balancer.
      */
-    containerPort?: number;
+    port?: number;
+    /** Environment variables */
+    environment?: Record<string, string>;
+    /** Secrets imported from other resources */
+    secretsImport?: Record<string, SecretImport>;
+    /** Command to run in the container */
+    command?: string[];
+    /** Entry point for the container */
+    entryPoint?: string[];
     /**
-     * CPU units for Fargate tasks (256, 512, 1024, 2048, 4096)
+     * Whether this container is essential.
+     * If an essential container stops, all containers in the task stop.
+     * Default: true
      */
-    cpu?: number;
+    essential?: boolean;
     /**
-     * Memory in MiB for Fargate tasks (512-30720)
+     * Health check configuration.
+     * Default: For primary container with port, uses curl health check.
      */
+    healthCheck?: {
+        command: string[];
+        interval?: number;
+        timeout?: number;
+        retries?: number;
+        startPeriod?: number;
+    };
+}
+/**
+ * ECS scaling configuration.
+ * - Omit: enabled with defaults
+ * - `{}`: enabled with defaults
+ * - `{ minCapacity: 2, maxCapacity: 10 }`: custom scaling
+ * - `false`: explicitly disabled
+ */
+export interface EcsScalingConfig {
+    minCapacity?: number;
+    maxCapacity?: number;
+    scalingType?: ScalingType;
+}
+/**
+ * EC2 capacity configuration for ECS EC2-backed clusters.
+ * Only used when capacityProvider is "EC2".
+ */
+export interface Ec2CapacityConfig {
+    /** EC2 instance type. Default: "t3.micro" */
+    instanceType?: string;
+    /** AMI hardware type. Default: "ARM" (Graviton - better cost/performance) */
+    amiHardwareType?: "ARM" | "STANDARD";
+    /** Minimum number of instances. Default: 1 */
+    minCapacity?: number;
+    /** Maximum number of instances. Default: 3 */
+    maxCapacity?: number;
+    /** Desired number of EC2 instances. Default: 2 (for availability) */
+    desiredCount?: number;
+    /** Memory limit in MiB for the container. Default: 1024 */
     memoryLimitMiB?: number;
+}
+/**
+ * Cluster-level configuration.
+ * Controls the shared ALB for all services in this cluster.
+ */
+export interface EcsClusterConfig {
     /**
-     * Environmnet variables to pass to the container
+     * Domain for HTTPS access.
+     * - Omit: ALB created with default DNS (*.elb.amazonaws.com)
+     * - Specified: Creates ACM certificate + Route53 DNS A record
      */
-    containerEnvironment?: {
-        [key: string]: string;
-    };
+    domain?: string;
     /**
-     * Safely import secrets from another resource,
-     *  object key is used as name when passing to container
+     * Load balancer configuration.
+     * - Omit or "public": Internet-facing ALB (default)
+     * - "internal": VPC-only ALB
+     * - false: No ALB (for workers/background processors)
      */
-    containerSecretsImport?: {
-        [key: string]: SecretImport;
-    };
+    loadBalancer?: false | "public" | "internal";
+    /**
+     * Enable direct EC2 access without ALB.
+     * Uses host network mode for predictable ports.
+     * Access via EC2 public IP at container port.
+     */
+    directAccess?: boolean;
+}
+/**
+ * Routing configuration for path/host-based routing on the ALB.
+ * Required when cluster has multiple services with ports.
+ * Optional for single service (gets all traffic automatically).
+ */
+export interface EcsRoutingConfig {
+    /**
+     * Path pattern for routing (e.g., "/api/*", "/users/*").
+     * Uses ALB path-based routing.
+     */
+    path?: string;
+    /**
+     * Host header for routing (e.g., "api.example.com").
+     * Uses ALB host-based routing.
+     */
+    host?: string;
+    /**
+     * Priority for this routing rule (1-50000).
+     * Lower number = higher priority.
+     * Auto-assigned if omitted.
+     */
+    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 config, and target group.
+ *
+ * @example
+ * // Simple service
+ * { name: "api", containers: [{ port: 3000 }] }
+ *
+ * @example
+ * // Service with routing (for multi-service clusters)
+ * { name: "users", containers: [{ port: 3000 }], routing: { path: "/users/*", priority: 100 } }
+ *
+ * @example
+ * // Service with sidecars
+ * {
+ *   name: "api",
+ *   containers: [
+ *     { name: "app", port: 3000 },
+ *     { name: "datadog", image: "datadog/agent" }
+ *   ]
+ * }
+ */
+export interface EcsServiceConfig {
+    /** Service name (unique within cluster) */
+    name: string;
+    /**
+     * Container image for this service (applies to first container without explicit image).
+     * - Omit: Uses app's default ECR repository
+     * - string: ECR repository name or public image URL
+     * - Repository: CDK ECR Repository construct
+     */
+    image?: string | Repository;
+    /**
+     * Container configuration(s) for this service.
+     * For single-container services, container name is optional and auto-generated.
+     * For multi-container services, the first container with a port is the primary container.
+     */
+    containers?: EcsContainerConfig[];
+    /**
+     * Routing rules for this service on the cluster's ALB.
+     * Required when cluster has multiple services with ports.
+     * Optional for single service (gets /* automatically).
+     */
+    routing?: EcsRoutingConfig;
+    /** 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 configuration.
+     * - Omit: enabled with defaults
+     * - false: disabled
+     */
+    scaling?: EcsScalingConfig | false;
+    /**
+     * Path to Dockerfile for building this service's image.
+     * Metadata for CLI build process, not used during CDK synthesis.
+     */
+    dockerfilePath?: string;
+    /**
+     * Additional inline policies for this service's task role.
+     * Added on top of the default ECS Exec permissions.
+     * Use for service-specific AWS permissions (S3, DynamoDB, SQS, etc.).
+     */
+    taskRoleInlinePolicies?: Record<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).
+     * Creates security group rules to allow traffic from this service.
+     * Follows least-privilege - only this service gets access, not all services in the cluster.
+     *
+     * @example
+     * // Only backend service connects to database
+     * services: [
+     *   { name: "frontend" },
+     *   { name: "backend", connections: [appDatabase] }
+     * ]
+     */
+    connections?: IConnectable[];
+}
+/**
+ * SSH access configuration for EC2 instances.
+ * - Omit: disabled (default)
+ * - `{}`: enabled with auto-generated key
+ * - `{ keyName: "my-key" }`: enabled with existing key
+ * - `false`: explicitly disabled
+ */
+export interface SshConfig {
+    /** SSH key pair name */
+    keyName?: string;
+    /** Allowed CIDR blocks for SSH access */
+    allowedCidrs?: string[];
+}
+/**
+ * Lambda function URL configuration.
+ * - Omit: disabled (default)
+ * - `{}`: enabled with IAM auth
+ * - `{ authType: "NONE", cors: {...} }`: public with CORS
+ * - `false`: explicitly disabled
+ */
+export interface FunctionUrlConfig {
+    /** Authentication type. Default: AWS_IAM */
+    authType?: FunctionUrlAuthType;
+    /** CORS configuration */
+    cors?: FunctionUrlCorsOptions;
+}
+interface BaseComputeProps {
+    vpc?: IVpc;
+}
+/**
+ * ECS compute configuration.
+ * Creates an ECS cluster with one or more services sharing a load balancer.
+ *
+ * @example
+ * // Single service
+ * app.addCompute(ComputeFactory.build("WebApp", {
+ *   type: "ecs",
+ *   cluster: { domain: "app.example.com" },
+ *   services: [{ name: "web", containers: [{ port: 3000 }] }]
+ * }));
+ *
+ * @example
+ * // Multi-service cluster with routing
+ * app.addCompute(ComputeFactory.build("ApiCluster", {
+ *   type: "ecs",
+ *   cluster: { domain: "api.example.com" },
+ *   services: [
+ *     { name: "users", containers: [{ port: 3000 }], routing: { path: "/users/*" } },
+ *     { name: "orders", containers: [{ port: 3001 }], routing: { path: "/orders/*" } }
+ *   ]
+ * }));
+ *
+ * @example
+ * // Internal workers (no ALB)
+ * app.addCompute(ComputeFactory.build("Workers", {
+ *   type: "ecs",
+ *   cluster: { loadBalancer: false },
+ *   services: [{ name: "processor" }, { name: "emailer" }]
+ * }));
+ */
+export interface EcsComputeProps extends BaseComputeProps {
+    type: "ecs";
+    /**
+     * Cluster configuration.
+     * Controls the shared ALB for all services in this cluster.
+     * - Omit: ALB created with default settings
+     * - `{ domain: "..." }`: ALB with HTTPS + DNS
+     * - `{ loadBalancer: false }`: No ALB (internal workers)
+     */
+    cluster?: EcsClusterConfig;
+    /**
+     * Services in this cluster.
+     * Each service gets its own task definition, scaling, and target group.
+     * All services share the cluster's ALB (unless disabled).
+     */
+    services: EcsServiceConfig[];
+    /**
+     * Capacity provider determines infrastructure type.
+     * - "FARGATE": Serverless containers (default)
+     * - "FARGATE_SPOT": Serverless with Spot pricing
+     * - "EC2": EC2-backed containers
+     */
+    capacityProvider?: EcsCapacityProvider;
+    /**
+     * EC2 capacity configuration.
+     * Only used when capacityProvider is "EC2".
+     */
+    ec2Config?: Ec2CapacityConfig;
+    /**
+     * ECR repository for all services (default image).
+     * Individual services can override with their own `image` property.
+     */
+    ecrRepository?: Repository | RepositoryImage;
+    /**
+     * Path to Dockerfile for building custom image.
+     * Note: This is metadata for the CLI build process,
+     * not used during CDK synthesis.
+     */
+    dockerfilePath?: string;
+}
+export interface Ec2ComputeProps extends BaseComputeProps {
+    type: "ec2";
+    /** EC2 instance type. Default: "t3.micro" */
     instanceType?: string;
-    enableSSH?: boolean;
+    /**
+     * SSH access configuration.
+     * - Omit: disabled (default)
+     * - `{}`: enabled with defaults
+     * - `false`: explicitly disabled
+     */
+    ssh?: SshConfig | false;
+    /** User data script */
     userData?: UserData;
+    /** Machine image (AMI) */
     machineImage?: IMachineImage;
+    /** Minimum number of instances. Default: 1 */
     minCapacity?: number;
+    /** Maximum number of instances. Default: 1 */
     maxCapacity?: number;
-    runtime?: Runtime;
-    handler?: string;
-    code?: Code;
+}
+/**
+ * Base Lambda configuration shared by both container and code deployments.
+ */
+interface BaseLambdaProps extends BaseComputeProps {
+    type: "lambda";
+    /** Timeout in seconds. Default: 3 */
     timeout?: number;
+    /** Memory size in MB. Default: 128 */
     memorySize?: number;
-    lambdaDescription?: string;
+    /** Lambda function description */
+    description?: string;
+    /** IAM role description */
     roleDescription?: string;
+    /** Inline IAM policy statements */
     inlinePolicy?: PolicyStatement[];
-    enableFunctionUrl?: boolean;
-    functionUrlAuthType?: FunctionUrlAuthType;
-    functionUrlCors?: SimplifiedCorsOptions;
-    connections?: IConnectable[];
+    /**
+     * Function URL configuration.
+     * - Omit: disabled (default)
+     * - `{}`: enabled with IAM auth
+     * - `{ authType: "NONE" }`: public access
+     * - `false`: explicitly disabled
+     */
+    functionUrl?: FunctionUrlConfig | false;
+    /** Environment variables */
+    environment?: Record<string, string>;
+}
+/**
+ * Container-based Lambda using ECR image.
+ *
+ * Uses Docker image from ECR repository. Handler and runtime are
+ * automatically set to FROM_IMAGE.
+ *
+ * @example
+ * app.addCompute(ComputeFactory.build("ImageLambda", {
+ *   type: "lambda",
+ *   deployment: "container",
+ *   ecrRepository: app.getDefaultContainerRegistry()
+ * }));
+ */
+export interface ContainerLambdaProps extends BaseLambdaProps {
+    /** Container-based deployment using ECR image */
+    deployment: "container";
+    /** ECR repository containing the Lambda container image */
+    ecrRepository: Repository | RepositoryImage;
+}
+/**
+ * Code-based Lambda using inline code or S3.
+ *
+ * Uses traditional Lambda deployment with code, handler, and runtime.
+ *
+ * @example
+ * app.addCompute(ComputeFactory.build("CodeLambda", {
+ *   type: "lambda",
+ *   deployment: "code",
+ *   code: Code.fromAsset("./lambda"),
+ *   handler: "index.handler",
+ *   runtime: Runtime.NODEJS_20_X
+ * }));
+ */
+export interface CodeLambdaProps extends BaseLambdaProps {
+    /** Code-based deployment */
+    deployment: "code";
+    /** Lambda code (from asset, S3, or inline) */
+    code: Code;
+    /** Handler function. Default: "index.handler" */
+    handler?: string;
+    /** Lambda runtime. Default: NODEJS_18_X */
+    runtime?: Runtime;
 }
+/**
+ * Lambda compute configuration.
+ *
+ * Discriminated union ensuring type-safe Lambda configuration:
+ * - `deployment: "container"` requires `ecrRepository`
+ * - `deployment: "code"` requires `code` and allows `handler`/`runtime`
+ *
+ * @example
+ * // Container-based Lambda
+ * { type: "lambda", deployment: "container", ecrRepository: ecr }
+ *
+ * @example
+ * // Code-based Lambda
+ * { type: "lambda", deployment: "code", code: Code.fromAsset("./lambda") }
+ */
+export type LambdaComputeProps = ContainerLambdaProps | CodeLambdaProps;
+export type IComputeProps = EcsComputeProps | Ec2ComputeProps | LambdaComputeProps;
+/**
+ * Factory for creating compute resources.
+ *
+ * @example
+ * // Single service cluster
+ * app.addCompute(ComputeFactory.build("WebApp", {
+ *   type: "ecs",
+ *   cluster: { domain: "app.example.com" },
+ *   services: [{ name: "web", containers: [{ port: 3000 }] }]
+ * }));
+ *
+ * @example
+ * // Multi-service cluster with routing
+ * app.addCompute(ComputeFactory.build("ApiCluster", {
+ *   type: "ecs",
+ *   cluster: { domain: "api.example.com" },
+ *   services: [
+ *     { name: "users", containers: [{ port: 3000 }], routing: { path: "/users/*" } },
+ *     { name: "orders", containers: [{ port: 3001 }], routing: { path: "/orders/*" } }
+ *   ]
+ * }));
+ *
+ * @example
+ * // Worker cluster (no ALB)
+ * app.addCompute(ComputeFactory.build("Workers", {
+ *   type: "ecs",
+ *   cluster: { loadBalancer: false },
+ *   services: [
+ *     { name: "processor", containers: [{ command: ["node", "worker.js"] }] }
+ *   ]
+ * }));
+ */
 export declare class ComputeFactory {
     static build(id: string, props: IComputeProps): (app: App, scope: Construct) => Compute;
 }
@@ -89,4 +521,3 @@ export declare class Compute extends Construct implements IConnectable {
     private addEcsCompute;
     private addLambdaCompute;
 }
-export {};