@maestro-js/aws-cdk-recipes 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,391 @@
+## Overview
+
+`@maestro-js/aws-cdk-recipes` provides opinionated AWS CDK constructs that simplify deploying cloud infrastructure. Each construct wraps multiple CDK resources behind a concise props interface with sensible defaults, and exposes a `transform` escape hatch for full customization of underlying CDK props.
+
+## Quick Setup
+
+```ts
+import {
+  Vpc,
+  Cluster,
+  Bucket,
+  MySqlDatabase,
+  AuroraDatabase,
+  LambdaFunction,
+  EcsFargateService,
+  StaticSite,
+  ReactRouterSsrSiteLambda,
+  ReactRouterSsrSiteEcsFargateService,
+  ReactRouterEcrImage
+} from '@maestro-js/aws-cdk-recipes'
+```
+
+Package dependencies:
+- `constructs` (dependency)
+- `aws-cdk-lib` (peer dependency, ^2.178.0)
+
+## Available Constructs
+
+### Vpc
+Multi-AZ VPC with public and private subnets, configurable NAT strategy (none, single, onePerAz, ec2), optional WireGuard VPN, and VPC Flow Logs.
+
+```ts
+const network = new Vpc(this, 'Network', {
+  natGateways: 'single',
+  wireguard: true
+})
+```
+
+Key props: `cidr`, `maxAzs`, `natGateways`, `subnetConfiguration`, `wireguard`, `flowLogs`.
+
+Exposes: `vpc`, `publicSubnets`, `privateSubnets`, `securityGroup`, `wireguard`, `wireguardPublicKeyParam`.
+
+### Cluster
+ECS cluster inside a VPC with optional Fargate capacity providers for Spot pricing.
+
+```ts
+const cluster = new Cluster(this, 'Cluster', {
+  vpc: network.vpc,
+  enableFargateCapacityProviders: true
+})
+```
+
+Key props: `vpc`, `enableFargateCapacityProviders`, `transform`.
+
+Exposes: `cluster`.
+
+### Bucket
+S3 bucket with HTTPS enforcement, configurable CORS, lifecycle rules, and custom bucket policies.
+
+```ts
+const uploads = new Bucket(this, 'Uploads', {
+  versioning: true,
+  lifecycle: [{ prefix: 'tmp/', expiresIn: '7 days' }]
+})
+```
+
+Key props: `access` (`'public' | 'private'`), `cors`, `versioning`, `enforceHttps`, `lifecycle`, `policy`, `transform`.
+
+Exposes: `bucket`.
+
+### MySqlDatabase
+RDS MySQL instance in private subnets with encrypted storage, automated backups, and optional RDS Proxy.
+
+```ts
+const db = new MySqlDatabase(this, 'Database', {
+  vpc: network.vpc,
+  database: 'ecommerce',
+  multiAz: true,
+  proxy: true
+})
+```
+
+Key props: `vpc`, `database`, `username`, `version`, `instance`, `storage`, `multiAz`, `proxy`, `performanceInsights`, `backupRetentionDays`, `deletionProtection`, `transform`.
+
+Exposes: `instance`, `securityGroup`, `secret`, `connections`, `rdsProxy`, `host`, `port`, `proxyEndpoint`.
+
+### AuroraDatabase
+Aurora Serverless v2 cluster (MySQL or PostgreSQL) with auto-scaling, optional auto-pause, read replicas, and RDS Proxy.
+
+```ts
+const db = new AuroraDatabase(this, 'Database', {
+  vpc: network.vpc,
+  engine: 'postgres',
+  version: rds.AuroraPostgresEngineVersion.VER_17_4,
+  database: 'myapp',
+  scaling: { min: 0, max: 4, pauseAfter: '10 minutes' }
+})
+```
+
+Key props: `vpc`, `engine` (`'postgres' | 'mysql'`), `version`, `database`, `scaling` (`min`, `max`, `pauseAfter`), `readers`, `proxy`, `dataApi`, `performanceInsights`, `backupRetentionDays`, `deletionProtection`, `transform`.
+
+Exposes: `cluster`, `securityGroup`, `secret`, `connections`, `rdsProxy`, `host`, `port`, `readerHost`, `proxyEndpoint`.
+
+### LambdaFunction
+Lambda function with esbuild bundling, VPC placement, function URLs, streaming responses, concurrency controls, and IAM permissions.
+
+```ts
+const api = new LambdaFunction(this, 'Api', {
+  handler: 'src/api.handler',
+  memory: 512,
+  url: true
+})
+```
+
+Supports three modes:
+- **Bundling mode** (default): esbuild bundles from SST-style handler path (`path/to/file.exportName`)
+- **Pre-built code**: pass `code` (a `lambda.Code` asset)
+- **Pre-built directory**: pass `bundle` (path string packaged via `Code.fromAsset`)
+
+Key props: `handler`, `code`, `bundle`, `runtime`, `architecture`, `memory`, `timeout`, `storage`, `environment`, `permissions`, `policies`, `vpc`, `concurrency`, `retries`, `streaming`, `versioning`, `url`, `logging`, `tags`, `nodejs` (esbuild options), `hook`, `transform`.
+
+Exposes: `function`, `logGroup`, `url`, `version`, `alias`.
+
+### EcsFargateService
+Fargate service with task definition, containers, optional ALB, auto-scaling, Spot capacity, and IAM permissions. Supports multi-container sidecars and conditional ALB routing rules.
+
+```ts
+new EcsFargateService(this, 'Api', {
+  cluster: cluster.cluster,
+  cpu: 512,
+  memoryLimitMiB: 1024,
+  containers: [{ port: 3000, environment: { NODE_ENV: 'production' } }],
+  loadBalancer: {
+    domain: { name: 'api.example.com', certificateArn: '...' }
+  },
+  scaling: { min: 2, max: 10, cpuTarget: 70 }
+})
+```
+
+Key props: `cluster`, `architecture`, `cpu`, `memoryLimitMiB`, `containers` (array with `name`, `image`, `port`, `environment`, `ssm`, `secrets`, `health`, `logging`), `loadBalancer` (with `domain`, `health`, `rules`), `scaling`, `capacity` (`'spot'` or mixed), `permissions`, `transform`.
+
+Exposes: `service`, `taskDefinition`, `containers`, `logGroups`, `securityGroup`, `alb`, `listener`, `targetGroups`.
+
+### StaticSite
+Static site (SPA or static HTML) deployed to S3 with CloudFront distribution, custom domain, and configurable cache control.
+
+```ts
+new StaticSite(this, 'Website', {
+  path: 'dist',
+  domain: {
+    name: 'example.com',
+    aliases: ['www.example.com'],
+    certificateArn: 'arn:aws:acm:us-east-1:123456789:certificate/abc-123'
+  }
+})
+```
+
+Key props: `path`, `indexPage`, `errorPage`, `domain`, `assets.fileOptions`, `edge`, `invalidation`, `transform`.
+
+Exposes: `bucket`, `distribution`.
+
+### ReactRouterSsrSiteLambda
+Full-stack React Router SSR application on Lambda with CloudFront and S3 static assets. Auto-generates a Lambda handler that bridges React Router's `createRequestHandler` to Lambda function URL events, with streaming and buffered response support.
+
+Run `react-router build` before deploying.
+
+```ts
+new ReactRouterSsrSiteLambda(this, 'App', {
+  domain: {
+    name: 'app.example.com',
+    certificateArn: 'arn:aws:acm:us-east-1:123456789:certificate/abc-123'
+  },
+  environment: { DATABASE_URL: 'mysql://...' }
+})
+```
+
+Key props: `path`, `buildDirectory`, `environment`, `vpc`, `permissions`, `server` (`mode`, `runtime`, `memory`, `timeout`, `architecture`, `layers`, `install`, `external`), `assets`, `domain`, `edge`, `invalidation`, `transform`.
+
+Exposes: `lambda`, `functionUrl`, `bucket`, `distribution`.
+
+### ReactRouterSsrSiteEcsFargateService
+Full-stack React Router SSR application on ECS Fargate with ALB, CloudFront, and S3 static assets. Auto-generates a Dockerfile when none is provided.
+
+Run `react-router build` before deploying.
+
+```ts
+new ReactRouterSsrSiteEcsFargateService(this, 'App', {
+  cluster: cluster.cluster,
+  cpu: 512,
+  memoryLimitMiB: 1024,
+  domain: {
+    name: 'app.example.com',
+    certificateArn: 'arn:aws:acm:us-east-1:123456789:certificate/abc-123'
+  }
+})
+```
+
+Key props: `cluster`, `path`, `buildDirectory`, `image`, `port`, `environment`, `ssm`, `secrets`, `architecture`, `cpu`, `memoryLimitMiB`, `capacity`, `healthCheck`, `scaling`, `permissions`, `assets`, `domain`, `edge`, `invalidation`, `transform`.
+
+Exposes: `bucket`, `distribution`, `ecsService`.
+
+### ReactRouterEcrImage
+Builds a Docker image for a React Router app and pushes it to ECR. Auto-generates a Dockerfile when none is provided. Use to pre-build an image shared across multiple ECS services.
+
+Run `react-router build` before deploying.
+
+```ts
+const image = new ReactRouterEcrImage(this, 'AppImage', {
+  path: './packages/web',
+  architecture: 'ARM64'
+})
+```
+
+Key props: `path`, `buildDirectory`, `port`, `image`, `architecture`, `platform`.
+
+Exposes: `asset` (DockerImageAsset).
+
+## API Reference
+
+### Exports (from `src/index.ts`)
+
+```ts
+export { Bucket } from './bucket.ts'
+export { Vpc } from './vpc.ts'
+export { Cluster } from './cluster.ts'
+export { StaticSite } from './static-site.ts'
+export { ReactRouterSsrSiteLambda } from './react-router-ssr-site-lambda.ts'
+export { ReactRouterSsrSiteEcsFargateService } from './react-router-ssr-site-ecs-fargate-service.ts'
+export { ReactRouterEcrImage } from './react-router-ecr-image.ts'
+export { MySqlDatabase } from './mysql-database.ts'
+export { AuroraDatabase } from './aurora-database.ts'
+export { LambdaFunction } from './lambda-function.ts'
+export { EcsFargateService } from './ecs-fargate-service.ts'
+```
+
+### Construct Signatures
+
+| Construct | Constructor |
+|-----------|------------|
+| `Vpc` | `new Vpc(scope, id, props?: Vpc.Props)` |
+| `Cluster` | `new Cluster(scope, id, props: Cluster.Props)` |
+| `Bucket` | `new Bucket(scope, id, props?: Bucket.Props)` |
+| `MySqlDatabase` | `new MySqlDatabase(scope, id, props: MySqlDatabase.Props)` |
+| `AuroraDatabase` | `new AuroraDatabase(scope, id, props: AuroraDatabase.Props)` |
+| `LambdaFunction` | `new LambdaFunction(scope, id, props: LambdaFunction.Props)` |
+| `EcsFargateService` | `new EcsFargateService(scope, id, props: EcsFargateService.Props)` |
+| `StaticSite` | `new StaticSite(scope, id, props: StaticSite.Props)` |
+| `ReactRouterSsrSiteLambda` | `new ReactRouterSsrSiteLambda(scope, id, props: ReactRouterSsrSiteLambda.Props)` |
+| `ReactRouterSsrSiteEcsFargateService` | `new ReactRouterSsrSiteEcsFargateService(scope, id, props: ReactRouterSsrSiteEcsFargateService.Props)` |
+| `ReactRouterEcrImage` | `new ReactRouterEcrImage(scope, id, props?: ReactRouterEcrImage.Props)` |
+
+## Common Patterns
+
+### Full-stack application with VPC, database, and API
+
+```ts
+const network = new Vpc(this, 'Network', { natGateways: 'single' })
+
+const cluster = new Cluster(this, 'Cluster', {
+  vpc: network.vpc,
+  enableFargateCapacityProviders: true
+})
+
+const db = new AuroraDatabase(this, 'Database', {
+  vpc: network.vpc,
+  engine: 'postgres',
+  version: rds.AuroraPostgresEngineVersion.VER_17_4,
+  database: 'myapp',
+  scaling: { min: 0, max: 4, pauseAfter: '10 minutes' }
+})
+
+new EcsFargateService(this, 'Api', {
+  cluster: cluster.cluster,
+  containers: [{
+    port: 3000,
+    environment: { DATABASE_HOST: db.host }
+  }],
+  loadBalancer: {
+    domain: { name: 'api.example.com', certificateArn: '...' }
+  },
+  scaling: { min: 2, max: 10 }
+})
+```
+
+### React Router SSR on Lambda with custom domain
+
+```ts
+new ReactRouterSsrSiteLambda(this, 'App', {
+  path: './packages/web',
+  server: { mode: 'streaming', memory: 1024 },
+  domain: {
+    name: 'app.example.com',
+    certificateArn: 'arn:aws:acm:us-east-1:123456789:certificate/abc-123'
+  },
+  environment: { DATABASE_URL: 'mysql://...' }
+})
+```
+
+### React Router SSR on ECS Fargate with Spot pricing
+
+```ts
+new ReactRouterSsrSiteEcsFargateService(this, 'App', {
+  cluster: cluster.cluster,
+  cpu: 512,
+  memoryLimitMiB: 1024,
+  capacity: 'spot',
+  domain: {
+    name: 'app.example.com',
+    certificateArn: 'arn:aws:acm:us-east-1:123456789:certificate/abc-123'
+  }
+})
+```
+
+### Transform escape hatch for customizing underlying CDK props
+
+Every construct supports a `transform` prop that receives default CDK props and returns modified versions:
+
+```ts
+new MySqlDatabase(this, 'Database', {
+  vpc: network.vpc,
+  database: 'app',
+  transform: {
+    instance: (props) => ({ ...props, publiclyAccessible: false })
+  }
+})
+
+new AuroraDatabase(this, 'Database', {
+  vpc: network.vpc,
+  engine: 'postgres',
+  version: rds.AuroraPostgresEngineVersion.VER_17_4,
+  database: 'myapp',
+  transform: {
+    cluster: (props) => ({ ...props, storageType: rds.DBClusterStorageType.AURORA_IOPT1 })
+  }
+})
+```
+
+### SSM secrets and environment injection in ECS
+
+```ts
+new EcsFargateService(this, 'Api', {
+  cluster: cluster.cluster,
+  containers: [{
+    port: 3000,
+    environment: { NODE_ENV: 'production' },
+    ssm: {
+      DATABASE_URL: 'arn:aws:secretsmanager:us-east-1:123456789:secret:db-url',
+      API_KEY: '/my-app/api-key'
+    }
+  }]
+})
+```
+
+Values starting with `arn:aws:secretsmanager:` are resolved as Secrets Manager secrets; all others are resolved as SSM SecureString parameters.
+
+### Cost-effective VPC with EC2 NAT
+
+```ts
+const network = new Vpc(this, 'Network', {
+  natGateways: 'ec2',
+  maxAzs: 2,
+  wireguard: true,
+  flowLogs: { retention: RetentionDays.ONE_WEEK }
+})
+```
+
+The `'ec2'` NAT option uses a `t4g.nano` instance running the fck-nat AMI (~$3/month vs ~$33/month for managed NAT Gateway).
+
+## Cross-Package Integration
+
+`@maestro-js/aws-cdk-recipes` is a standalone infrastructure package. It has no dependencies on other Maestro packages. Use it in CDK apps to deploy infrastructure for Maestro-based applications. The React Router constructs auto-generate Dockerfiles and Lambda handlers that work with both monorepo (`pnpm deploy`) and standalone project layouts.
+
+## Key Source Files
+
+- `packages/aws-cdk-recipes/src/index.ts` - Package exports
+- `packages/aws-cdk-recipes/src/vpc.ts` - Vpc construct
+- `packages/aws-cdk-recipes/src/cluster.ts` - Cluster construct
+- `packages/aws-cdk-recipes/src/bucket.ts` - Bucket construct
+- `packages/aws-cdk-recipes/src/mysql-database.ts` - MySqlDatabase construct
+- `packages/aws-cdk-recipes/src/aurora-database.ts` - AuroraDatabase construct
+- `packages/aws-cdk-recipes/src/lambda-function.ts` - LambdaFunction construct
+- `packages/aws-cdk-recipes/src/ecs-fargate-service.ts` - EcsFargateService construct
+- `packages/aws-cdk-recipes/src/static-site.ts` - StaticSite construct
+- `packages/aws-cdk-recipes/src/react-router-ssr-site-lambda.ts` - ReactRouterSsrSiteLambda construct
+- `packages/aws-cdk-recipes/src/react-router-ssr-site-ecs-fargate-service.ts` - ReactRouterSsrSiteEcsFargateService construct
+- `packages/aws-cdk-recipes/src/react-router-ecr-image.ts` - ReactRouterEcrImage construct
+- `packages/aws-cdk-recipes/src/helpers/cloudfront.ts` - Shared CloudFront/S3 deployment helpers
+- `packages/aws-cdk-recipes/src/helpers/ecs.ts` - Shared ECS helpers (log retention, secrets)
+- `packages/aws-cdk-recipes/src/helpers/docker.ts` - React Router Dockerfile generation
+- `packages/aws-cdk-recipes/src/helpers/ssr-site-lambda.ts` - SSR site Lambda orchestration
+- `packages/aws-cdk-recipes/src/helpers/ssr-site-ecs-service.ts` - SSR site ECS orchestration