@fjall/components-infrastructure 0.86.1 → 0.87.3

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

@@ -1,13 +1,20 @@
-import { type RepositoryImage } from "aws-cdk-lib/aws-ecs";
+import { type RepositoryImage, type ICluster, type IBaseService } from "aws-cdk-lib/aws-ecs";
 import { Repository } from "aws-cdk-lib/aws-ecr";
-import { type Connections, type IConnectable, type IVpc, type UserData, type IMachineImage } from "aws-cdk-lib/aws-ec2";
-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 { type Connections, type IVpc, type UserData, type IMachineImage, type ISecurityGroup } from "aws-cdk-lib/aws-ec2";
+import { Code, Runtime, type Architecture, type FunctionUrlAuthType, type FunctionUrlCorsOptions, type IFunction, type InvokeMode } from "aws-cdk-lib/aws-lambda";
+import { type PolicyStatement, type PolicyDocument, type IManagedPolicy, type IGrantable, Grant } from "aws-cdk-lib/aws-iam";
+import { type IApplicationLoadBalancer, type ApplicationListener } from "aws-cdk-lib/aws-elasticloadbalancingv2";
+import { type IAutoScalingGroup } from "aws-cdk-lib/aws-autoscaling";
 import { Construct } from "constructs";
+import { type IEcsCompute, type ILambdaCompute, type IEc2Compute, type AnyCompute, isCompute, isEcsCompute, isLambdaCompute, isEc2Compute } from "./interfaces/compute.js";
+import { type ConnectionSpec } from "./interfaces/connector.js";
 import type App from "../../app";
-import { ScalingType, type DomainConfig, type EcsCapacityProvider, type Ec2CapacityConfig } from "../../resources/aws/compute/ecs";
+import EcsCluster, { type EcsClusterProps, ScalingType, type DomainConfig, type EcsCapacityProvider, type Ec2CapacityConfig } from "../../resources/aws/compute/ecs";
+import { Ec2Instance } from "../../resources/aws/compute/ec2";
+import { LambdaFunction } from "../../resources/aws/compute/lambda";
 import { type SecretImport } from "../../resources/aws/secrets";
 export type ComputeType = "ecs" | "ec2" | "lambda";
+export { ScalingType };
 export type { EcsCapacityProvider, Ec2CapacityConfig };
 /**
  * Configuration defaults for each compute type.
@@ -36,9 +43,30 @@ export interface EcsCapacityProviderConfig {
     usesEc2Instances: boolean;
 }
 export declare const ECS_CAPACITY_PROVIDER_CONFIG: Record<EcsCapacityProvider, EcsCapacityProviderConfig>;
+/**
+ * Default values for compute resource configuration.
+ * Centralised constants to ensure consistency across the codebase.
+ */
+export declare const COMPUTE_DEFAULTS: {
+    readonly EC2: {
+        readonly INSTANCE_TYPE: "t3.micro";
+        readonly MIN_CAPACITY: 1;
+        readonly MAX_CAPACITY: 1;
+    };
+    readonly ECS: {
+        /** AWS sample image used when no ECR repository is provided */
+        readonly FALLBACK_IMAGE: "amazon/amazon-ecs-sample";
+        /** Default tag for ECR images */
+        readonly IMAGE_TAG: "latest";
+    };
+    readonly LAMBDA: {
+        readonly HANDLER: "index.handler";
+        readonly RUNTIME: Runtime;
+    };
+};
 export declare function getComputeTypeConfig(type: ComputeType): ComputeTypeConfig;
 export declare function getEcsCapacityProviderConfig(provider: EcsCapacityProvider): EcsCapacityProviderConfig;
-export { HttpMethod, type FunctionUrlCorsOptions } from "aws-cdk-lib/aws-lambda";
+export { Architecture, HttpMethod, InvokeMode, type FunctionUrlCorsOptions } from "aws-cdk-lib/aws-lambda";
 /**
  * Configuration for a container in an ECS task.
  *
@@ -75,8 +103,6 @@ export interface EcsContainerConfig {
     port?: number;
     /** Environment variables */
     environment?: Record<string, string>;
-    /** Secrets imported from other resources (AWS Secrets Manager) */
-    secretsImport?: Record<string, SecretImport>;
     /**
      * Secrets from AWS SSM Parameter Store.
      * Array of secret names that will be fetched from the service's SSM namespace.
@@ -84,9 +110,11 @@ export interface EcsContainerConfig {
      *
      * @example
      * // Secrets at /myapp/api-cluster/users/API_KEY and /myapp/api-cluster/users/DB_PASSWORD
-     * ssmSecrets: ["API_KEY", "DB_PASSWORD"]
+     * secrets: ["API_KEY", "DB_PASSWORD"]
      */
-    ssmSecrets?: string[];
+    secrets?: string[];
+    /** Secrets imported from other CDK resources (AWS Secrets Manager) */
+    secretsImport?: Record<string, SecretImport>;
     /** Command to run in the container */
     command?: string[];
     /** Entry point for the container */
@@ -243,11 +271,13 @@ export interface EcsServiceConfig {
     dockerfilePath?: string;
     /**
      * Docker build target stage for multi-stage Dockerfiles.
-     * Metadata for CLI build process, not used during CDK synthesis.
+     * When specified, the CLI builds with `--target <dockerTarget>`.
+     * The image tag suffix is also updated: `<service>-<target>-latest`.
      *
      * @example
-     * // Build "api" stage from Dockerfile
-     * dockerTarget: "api"
+     * // Dockerfile: FROM node AS base ... FROM base AS api ... FROM base AS worker
+     * { name: "api", dockerTarget: "api" }   // builds: myapp-api-api-latest
+     * { name: "worker", dockerTarget: "worker" }  // builds: myapp-worker-worker-latest
      */
     dockerTarget?: string;
     /**
@@ -262,18 +292,31 @@ export interface EcsServiceConfig {
      */
     taskRoleManagedPolicies?: IManagedPolicy[];
     /**
-     * Resources this service needs to connect to (e.g., databases).
-     * Creates security group rules to allow traffic from this service.
+     * 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.
      * Follows least-privilege - only this service gets access, not all services in the cluster.
      *
+     * 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
-     * // Only backend service connects to database
-     * services: [
-     *   { name: "frontend" },
-     *   { name: "backend", connections: [appDatabase] }
+     * // Simple connections (default permissions)
+     * connections: [database, bucket, cache, queue]
+     *
+     * @example
+     * // Explicit access levels
+     * 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?: IConnectable[];
+    connections?: ConnectionSpec[];
     /**
      * Capacity provider for this service. REQUIRED.
      * Each service specifies its own capacity provider.
@@ -330,6 +373,8 @@ export interface FunctionUrlConfig {
     authType?: FunctionUrlAuthType;
     /** CORS configuration */
     cors?: FunctionUrlCorsOptions;
+    /** Invoke mode. Use RESPONSE_STREAM for Lambda streaming. Default: BUFFERED */
+    invokeMode?: InvokeMode;
 }
 interface BaseComputeProps {
     vpc?: IVpc;
@@ -369,7 +414,7 @@ export interface EcsComputeProps extends BaseComputeProps {
     type: "ecs";
     /**
      * Application name for SSM secrets namespace.
-     * When containers use ssmSecrets, the path is derived as: /<appName>/<clusterName>/<serviceName>
+     * When containers use secrets, the path is derived as: /<appName>/<clusterName>/<serviceName>
      * Auto-derived from App.getName() if not specified.
      */
     appName?: string;
@@ -419,6 +464,16 @@ export interface Ec2ComputeProps extends BaseComputeProps {
     minCapacity?: number;
     /** Maximum number of instances. Default: 1 */
     maxCapacity?: number;
+    /**
+     * Percentage of capacity to run on Spot instances (0-100).
+     * - Omit or 0: All On-Demand instances (default)
+     * - 100: All Spot instances
+     * - 50: Half Spot, half On-Demand
+     *
+     * Spot instances can reduce costs by up to 90% but may be interrupted.
+     * Use for fault-tolerant workloads.
+     */
+    spotCapacityPercentage?: number;
 }
 /**
  * Base Lambda configuration shared by both container and code deployments.
@@ -430,6 +485,8 @@ interface BaseLambdaProps extends BaseComputeProps {
     /** Memory size in MB. Default: 128 */
     memorySize?: number;
     ephemeralStorageSize?: number;
+    /** CPU architecture. Default: x86_64. Use Architecture.ARM_64 for Graviton2. */
+    architecture?: Architecture;
     /** Lambda function description */
     description?: string;
     /** IAM role description */
@@ -446,15 +503,64 @@ interface BaseLambdaProps extends BaseComputeProps {
     functionUrl?: FunctionUrlConfig | false;
     /** Environment variables */
     environment?: Record<string, string>;
-    /** Container secrets import (key: env var, value: SecretImport) */
-    containerSecretsImport?: {
-        [key: string]: SecretImport;
-    };
     /**
-     * Resources this Lambda needs to connect to (e.g., databases).
-     * Creates security group rules to allow traffic from this Lambda.
+     * Secrets from AWS SSM Parameter Store.
+     * Array of secret names that will be fetched from the Lambda's SSM namespace.
+     * The namespace path is auto-determined as: /<appName>/lambda/<functionName>
+     *
+     * @example
+     * secrets: ["API_KEY", "STRIPE_SECRET"]
+     */
+    secrets?: string[];
+    /**
+     * SSM Parameter Store path for secrets.
+     * If secrets are defined, this path is used as the base path.
+     * If not specified, uses: /<appName>/lambda/<functionName>
+     *
+     * @example
+     * ssmSecretsPath: "/myapp/custom/path"
+     */
+    ssmSecretsPath?: string;
+    /**
+     * Secrets imported from other CDK resources (AWS Secrets Manager).
+     * Used for CDK-managed secrets like database credentials.
+     *
+     * @example
+     * secretsImport: {
+     *   DATABASE_USERNAME: database.getCredentials().getImport("username"),
+     *   DATABASE_PASSWORD: database.getCredentials().getImport("password")
+     * }
+     */
+    secretsImport?: Record<string, SecretImport>;
+    /**
+     * Application name for SSM secrets path derivation.
+     * Auto-derived from App instance when using ComputeFactory.
+     * Only specify for advanced use cases.
+     */
+    appName?: string;
+    /**
+     * Resources this Lambda 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,
+     *   { resource: queue, access: "send" }
+     * ]
+     */
+    connections?: ConnectionSpec[];
+    /**
+     * EventBridge schedule expression for scheduled Lambda invocations.
+     * Uses cron or rate syntax: "rate(1 hour)" or "cron(0 12 * * ? *)".
      */
-    connections?: IConnectable[];
+    scheduleExpression?: string;
 }
 /**
  * Container-based Lambda using ECR image.
@@ -515,51 +621,164 @@ export interface CodeLambdaProps extends BaseLambdaProps {
  * { type: "lambda", deployment: "code", code: Code.fromAsset("./lambda") }
  */
 export type LambdaComputeProps = ContainerLambdaProps | CodeLambdaProps;
-export type IComputeProps = EcsComputeProps | Ec2ComputeProps | LambdaComputeProps;
+export type IEcsComputeProps = EcsComputeProps;
+export type ILambdaComputeProps = LambdaComputeProps;
+export type IEc2ComputeProps = Ec2ComputeProps;
+export type IComputeProps = IEcsComputeProps | ILambdaComputeProps | IEc2ComputeProps;
+/**
+ * Build container configurations for an ECS service.
+ * Converts user-facing EcsContainerConfig to internal EcsClusterProps format.
+ * @internal Exported for testing only
+ */
+export declare function buildContainerConfigs(service: EcsServiceConfig): EcsClusterProps["services"][number]["containers"];
+/**
+ * Resolved scaling configuration for an ECS service.
+ * @internal Exported for testing only
+ */
+export interface ResolvedScalingConfig {
+    scalingType: ScalingType | undefined;
+    minCapacity: number | undefined;
+    maxCapacity: number | undefined;
+}
+/**
+ * Resolve scaling configuration from service props.
+ * Handles the three cases: explicit config, disabled (false), or default (undefined).
+ * @internal Exported for testing only
+ */
+export declare function resolveScalingConfig(scaling: EcsScalingConfig | false | undefined): ResolvedScalingConfig;
 /**
- * Factory for creating compute resources.
+ * Resolved Lambda deployment configuration.
+ */
+export interface ResolvedLambdaDeployment {
+    code: Code;
+    handler: string;
+    runtime: Runtime;
+}
+/**
+ * Resolve Lambda deployment configuration from props.
+ * Handles container vs code deployment types.
+ */
+export declare function resolveLambdaDeployment(props: ILambdaComputeProps): ResolvedLambdaDeployment;
+/**
+ * Factory for creating compute resources with type-safe return types.
+ *
+ * The factory uses overloads to infer the specific compute type from props,
+ * ensuring TypeScript provides only the relevant methods for each compute type.
  *
  * @example
- * // Single service cluster
- * app.addCompute(ComputeFactory.build("WebApp", {
+ * // ECS compute - returns EcsCompute with ECS-specific methods
+ * const ecs = app.addCompute(ComputeFactory.build("WebApp", {
  *   type: "ecs",
  *   cluster: { domain: "app.example.com" },
  *   services: [{ name: "web", containers: [{ port: 3000 }] }]
  * }));
+ * ecs.getLoadBalancer(); // Available on EcsCompute
  *
  * @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/*" } }
- *   ]
+ * // Lambda compute - returns LambdaCompute with Lambda-specific methods
+ * const lambda = app.addCompute(ComputeFactory.build("Fn", {
+ *   type: "lambda",
+ *   deployment: "code",
+ *   code: Code.fromAsset("./lambda")
  * }));
+ * lambda.getFunctionUrl(); // Available on LambdaCompute
  *
  * @example
- * // Worker cluster (no ALB)
- * app.addCompute(ComputeFactory.build("Workers", {
- *   type: "ecs",
- *   cluster: { loadBalancer: false },
- *   services: [
- *     { name: "processor", containers: [{ command: ["node", "worker.js"] }] }
- *   ]
+ * // EC2 compute - returns Ec2Compute with EC2-specific methods
+ * const ec2 = app.addCompute(ComputeFactory.build("Instance", {
+ *   type: "ec2",
+ *   instanceType: "t3.micro"
  * }));
+ * ec2.getAutoScalingGroup(); // Available on Ec2Compute
  */
 export declare class ComputeFactory {
-    static build(id: string, props: IComputeProps): (app: App, scope: Construct) => Compute;
+    static build(id: string, props: IEcsComputeProps): (app: App, scope: Construct) => EcsCompute;
+    static build(id: string, props: ILambdaComputeProps): (app: App, scope: Construct) => LambdaCompute;
+    static build(id: string, props: IEc2ComputeProps): (app: App, scope: Construct) => Ec2Compute;
 }
-export declare class Compute extends Construct implements IConnectable {
-    id: string;
-    scope: Construct;
-    vpc: IVpc;
-    connections: Connections;
-    private compute;
-    constructor(scope: Construct, id: string, props: IComputeProps);
-    addCompute(props: IComputeProps): void;
-    private addEc2Compute;
-    private addEcsCompute;
-    private addLambdaCompute;
+/**
+ * ECS compute wrapper implementing IEcsCompute.
+ * Provides type-safe access to ECS-specific resources.
+ */
+export declare class EcsCompute extends Construct implements IEcsCompute {
+    readonly computeType: "ecs";
+    readonly connections: Connections;
+    private readonly ecsCluster;
+    constructor(scope: Construct, id: string, props: IEcsComputeProps);
+    /** Get the ECS cluster. */
+    getCluster(): ICluster;
+    /** Get the Application Load Balancer if one was created. */
+    getLoadBalancer(): IApplicationLoadBalancer | undefined;
+    /** Get a specific service by name. */
+    getService(name: string): IBaseService | undefined;
+    /** Get all services in the cluster. */
+    getAllServices(): IBaseService[];
+    /** Get the security group for the cluster. */
+    getSecurityGroup(): ISecurityGroup;
+    /**
+     * Get the ALB listener if this is an ECS compute with ALB.
+     */
+    getListener(): ApplicationListener | undefined;
+    /**
+     * Get the underlying ECS cluster construct.
+     */
+    getEcsCluster(): EcsCluster;
+    /**
+     * Grants ecs:ExecuteCommand permission for ECS services.
+     */
+    grantExecuteCommand(grantee: IGrantable): Grant;
+}
+/**
+ * Lambda compute wrapper implementing ILambdaCompute.
+ * Provides type-safe access to Lambda-specific resources.
+ */
+export declare class LambdaCompute extends Construct implements ILambdaCompute {
+    readonly computeType: "lambda";
+    readonly connections: Connections;
+    private readonly lambdaFunction;
+    constructor(scope: Construct, id: string, props: ILambdaComputeProps);
+    /**
+     * Get a Lambda function by name.
+     * Since we only have one function, name is ignored.
+     */
+    getFunction(_name?: string): IFunction | undefined;
+    /** Get all Lambda functions. */
+    getAllFunctions(): IFunction[];
+    /**
+     * Get the function URL for a Lambda function.
+     */
+    getFunctionUrl(_name?: string): string | undefined;
+    /**
+     * Grant invoke permissions to a grantee.
+     */
+    grantInvoke(grantee: IGrantable, _functionName?: string): Grant;
+    /**
+     * Get the security group for VPC-enabled Lambda functions.
+     * Returns undefined if the Lambda is not VPC-enabled.
+     */
+    getSecurityGroup(): ISecurityGroup | undefined;
+    /**
+     * Get the underlying Lambda function construct.
+     */
+    getLambdaFunction(): LambdaFunction;
+}
+/**
+ * EC2 compute wrapper implementing IEc2Compute.
+ * Provides type-safe access to EC2-specific resources.
+ */
+export declare class Ec2Compute extends Construct implements IEc2Compute {
+    readonly computeType: "ec2";
+    readonly connections: Connections;
+    private readonly ec2Instance;
+    constructor(scope: Construct, id: string, props: IEc2ComputeProps);
+    /** Get the Auto Scaling Group. */
+    getAutoScalingGroup(): IAutoScalingGroup;
+    /** Get the security group. */
+    getSecurityGroup(): ISecurityGroup;
+    /**
+     * Get the underlying EC2 instance construct.
+     */
+    getEc2Instance(): Ec2Instance;
 }
+export { isCompute, isEcsCompute, isLambdaCompute, isEc2Compute };
+export type { IEcsCompute, ILambdaCompute, IEc2Compute, AnyCompute };