@codedrifters/constructs 0.0.2 → 0.0.4

package/README.md

@@ -1 +1,526 @@
-# replace this
+# @codedrifters/constructs
+
+A collection of reusable AWS CDK constructs frequently used in CodeDrifters projects. This package provides pre-configured, secure, and production-ready constructs for common AWS infrastructure patterns.
+
+## Table of Contents
+
+- [What are AWS CDK Constructs?](#what-are-aws-cdk-constructs)
+- [Installation](#installation)
+- [Constructs](#constructs)
+  - [S3 Constructs](#s3-constructs)
+    - [PrivateBucket](#privatebucket)
+  - [Static Hosting Constructs](#static-hosting-constructs)
+    - [StaticHosting](#statichosting)
+    - [StaticContent](#staticcontent)
+  - [Utility Functions](#utility-functions)
+    - [Git Utilities](#git-utilities)
+    - [String Utilities](#string-utilities)
+- [Complete Example](#complete-example)
+- [API Reference](#api-reference)
+- [Further Documentation](#further-documentation)
+
+## What are AWS CDK Constructs?
+
+AWS CDK (Cloud Development Kit) constructs are reusable cloud components that encapsulate AWS resources and their configuration. Think of them as building blocks that combine multiple AWS services into higher-level abstractions.
+
+For example, instead of manually configuring an S3 bucket, CloudFront distribution, Route53 records, and SSL certificates separately, a construct can combine all of these into a single "StaticHosting" construct that you can use with just a few lines of code.
+
+**Key Benefits:**
+- **Reusability**: Write once, use everywhere
+- **Consistency**: Enforce best practices and security defaults
+- **Simplicity**: Complex infrastructure becomes simple API calls
+- **Type Safety**: Full TypeScript support with IntelliSense
+
+For more information about AWS CDK constructs, see the [AWS CDK Developer Guide](https://docs.aws.amazon.com/cdk/v2/guide/home.html).
+
+## Installation
+
+Add the package to your CDK project using Configulator/Projen configuration. This ensures consistent dependency management across your project.
+
+### In a Monorepo (Recommended)
+
+If you're using `@codedrifters/configulator` in a monorepo, add the package as a dependency in your sub-project configuration:
+
+```typescript
+import { TypeScriptProject } from '@codedrifters/configulator';
+import { MonorepoProject } from '@codedrifters/configulator';
+
+const myCdkProject = new TypeScriptProject({
+  name: 'my-cdk-project',
+  packageName: '@myorg/my-cdk-project',
+  outdir: 'packages/my-cdk-project',
+  parent: root, // Your MonorepoProject instance
+  
+  deps: [
+    '@codedrifters/constructs',
+  ],
+  
+  devDeps: [
+    'aws-cdk-lib@catalog:', // Catalog versions are pre-configured
+    'constructs@catalog:',
+  ],
+});
+```
+
+### In a Standalone CDK Project
+
+If you're using AWS CDK directly (not via Configulator), add the package to your `deps` array:
+
+```typescript
+import { awscdk } from 'projen';
+
+const project = new awscdk.AwsCdkTypeScriptApp({
+  name: 'my-cdk-app',
+  
+  deps: [
+    '@codedrifters/constructs',
+  ],
+  
+  devDeps: [
+    'aws-cdk-lib',
+    'constructs',
+  ],
+});
+```
+
+### After Adding to Configuration
+
+After updating your projenrc configuration file, run:
+
+```bash
+npx projen
+```
+
+This will update your `package.json` and install the dependencies.
+
+### Peer Dependencies
+
+This package requires the following peer dependencies:
+
+- `aws-cdk-lib` - AWS CDK construct library
+- `constructs` - Core constructs library
+
+These should be added as dev dependencies in your project configuration. If you're using `@codedrifters/configulator`, the catalog versions (`@catalog:`) are automatically configured in the root `MonorepoProject`.
+
+## Constructs
+
+### S3 Constructs
+
+#### PrivateBucket
+
+A secure S3 bucket with sensible security defaults. This construct extends AWS CDK's `Bucket` construct with security best practices applied by default.
+
+**Security Defaults:**
+- Public access is blocked (`BlockPublicAccess.BLOCK_ALL`)
+- SSL/TLS is enforced for all requests
+- Bucket owner enforced object ownership
+- Configurable removal policy (defaults to `RETAIN`)
+
+**Basic Usage:**
+
+```typescript
+import { PrivateBucket } from '@codedrifters/constructs';
+import { Stack } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+
+const stack = new Stack(app, 'MyStack');
+
+// Create a private bucket with default security settings
+const bucket = new PrivateBucket(stack, 'MyPrivateBucket');
+```
+
+**With Custom Properties:**
+
+```typescript
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { PrivateBucket } from '@codedrifters/constructs';
+
+const bucket = new PrivateBucket(stack, 'MyPrivateBucket', {
+  removalPolicy: RemovalPolicy.DESTROY,
+  autoDeleteObjects: true,
+  versioned: true,
+});
+```
+
+**Note:** The security settings (public access blocked, SSL enforced, etc.) cannot be overridden - they are always applied to ensure bucket security.
+
+### Static Hosting Constructs
+
+#### StaticHosting
+
+A complete static website hosting solution that creates and configures:
+
+- **S3 Bucket**: Private bucket for storing static files (using `PrivateBucket`)
+- **CloudFront Distribution**: Global CDN for fast content delivery
+- **SSL Certificate**: Wildcard certificate via AWS Certificate Manager
+- **Route53 Records**: DNS entries for the domain and wildcard subdomains
+- **Lambda@Edge Function**: Viewer request handler for path rewriting
+- **SSM Parameters**: Stores bucket ARN, distribution domain, and distribution ID for later use
+
+**Features:**
+- Automatic wildcard SSL certificate generation
+- Support for custom domains with automatic DNS configuration
+- Lambda@Edge function for intelligent path rewriting
+- Conservative caching policy (60s default TTL)
+- Stores configuration in SSM Parameter Store for use by `StaticContent`
+
+**Basic Usage (CloudFront Domain Only):**
+
+```typescript
+import { StaticHosting } from '@codedrifters/constructs';
+import { Stack } from 'aws-cdk-lib';
+
+const hostingStack = new Stack(app, 'HostingStack', { env });
+
+const hosting = new StaticHosting(hostingStack, 'static-hosting', {
+  description: 'My static website',
+});
+```
+
+**With Custom Domain:**
+
+```typescript
+import { StaticHosting } from '@codedrifters/constructs';
+import { Stack, RemovalPolicy } from 'aws-cdk-lib';
+
+const hostingStack = new Stack(app, 'HostingStack', { env });
+
+const hosting = new StaticHosting(hostingStack, 'static-hosting', {
+  description: 'My static website',
+  staticDomainProps: {
+    baseDomain: 'example.com',
+    hostedZoneAttributes: {
+      hostedZoneId: 'Z1234567890ABC',
+      zoneName: 'example.com',
+    },
+  },
+  privateBucketProps: {
+    removalPolicy: RemovalPolicy.DESTROY,
+    autoDeleteObjects: true,
+  },
+});
+```
+
+**Properties:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `description` | `string` | `undefined` | Short description for traceability |
+| `staticDomainProps` | `StaticDomainProps` | `undefined` | Domain configuration (optional) |
+| `bucketArnParamName` | `string` | `"/STATIC_WEBSITE/BUCKET_ARN"` | SSM parameter name for bucket ARN |
+| `distributionDomainParamName` | `string` | `"/STATIC_WEBSITE/DISTRIBUTION_DOMAIN"` | SSM parameter name for distribution domain |
+| `distributionIDParamName` | `string` | `"/STATIC_WEBSITE/DISTRIBUTION_ID"` | SSM parameter name for distribution ID |
+| `privateBucketProps` | `PrivateBucketProps` | `undefined` | Props to pass to the S3 bucket |
+
+**StaticDomainProps:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `baseDomain` | `string` | The base domain (e.g., `example.com`) |
+| `hostedZoneAttributes` | `HostedZoneAttributes` | Hosted zone ID and zone name |
+
+**Outputs:**
+
+The construct exposes:
+- `fullDomain: string` - The full domain name (custom domain if provided, otherwise CloudFront domain)
+
+**SSM Parameters Created:**
+
+The construct automatically creates SSM parameters that can be referenced by `StaticContent`:
+- Bucket ARN (default: `/STATIC_WEBSITE/BUCKET_ARN`)
+- CloudFront Distribution Domain (default: `/STATIC_WEBSITE/DISTRIBUTION_DOMAIN`)
+- CloudFront Distribution ID (default: `/STATIC_WEBSITE/DISTRIBUTION_ID`)
+
+#### StaticContent
+
+Deploys static content from a local directory to an S3 bucket. This construct is designed to work with `StaticHosting` and supports branch-based deployment paths for PR and feature branch previews.
+
+**Features:**
+- Deploys files from a local directory to S3
+- Supports branch-based path prefixes (e.g., `feature-123.example.com/`)
+- Automatically retrieves bucket ARN from SSM Parameter Store
+- Configurable destination directory within the bucket
+
+**How Branch-Based Deployment Works:**
+
+The construct uses the current git branch name to create unique deployment paths. This allows multiple branches to deploy to the same bucket without conflicts:
+
+```
+S3 Bucket Structure:
+├── example.com/              → Production/main branch
+├── feature-123.example.com/  → Feature branch
+├── pr-456.example.com/      → Pull request
+└── stage.example.com/       → Staging branch
+```
+
+**Basic Usage:**
+
+```typescript
+import { StaticContent, StaticHosting } from '@codedrifters/constructs';
+import { Stack } from 'aws-cdk-lib';
+
+// First, create the hosting infrastructure
+const hostingStack = new Stack(app, 'HostingStack', { env });
+const hosting = new StaticHosting(hostingStack, 'static-hosting', {
+  staticDomainProps: {
+    baseDomain: 'example.com',
+    hostedZoneAttributes: {
+      hostedZoneId: 'Z1234567890ABC',
+      zoneName: 'example.com',
+    },
+  },
+});
+
+// Then, deploy content in a separate stack
+const contentStack = new Stack(app, 'ContentStack', { env });
+contentStack.node.addDependency(hostingStack);
+
+new StaticContent(contentStack, 'static-content', {
+  contentSourceDirectory: 'dist', // Local directory with built files
+  contentDestinationDirectory: '/', // Deploy to root of bucket path
+  fullDomain: hosting.fullDomain, // Use domain from StaticHosting
+});
+```
+
+**With Custom Subdomain:**
+
+```typescript
+new StaticContent(contentStack, 'static-content', {
+  contentSourceDirectory: 'dist',
+  contentDestinationDirectory: '/',
+  fullDomain: hosting.fullDomain,
+  subDomain: 'staging', // Override git branch detection
+  bucketArnParamName: '/STATIC_WEBSITE/BUCKET_ARN', // Custom param name
+});
+```
+
+**Properties:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `contentSourceDirectory` | `string` | **Required** | Absolute path to directory containing files to deploy |
+| `contentDestinationDirectory` | `string` | **Required** | Directory within bucket to place content (should start with `/`) |
+| `fullDomain` | `string` | **Required** | Full domain name (from `StaticHosting.fullDomain`) |
+| `subDomain` | `string` | Git branch name | Subdomain prefix (defaults to current git branch) |
+| `bucketArnParamName` | `string` | `"/STATIC_WEBSITE/BUCKET_ARN"` | SSM parameter name for bucket ARN |
+
+**Path Construction:**
+
+The construct creates a unique path prefix using: `{subDomain}.{fullDomain}`
+
+For example:
+- Branch: `feature-123`, Domain: `example.com` → Path: `feature-123.example.com/`
+- Branch: `main`, Domain: `example.com` → Path: `main.example.com/` (or just `example.com/` if subdomain is empty)
+
+### Utility Functions
+
+#### Git Utilities
+
+Helper functions for working with Git in CDK deployments.
+
+**`findGitBranch()`**
+
+Returns the current git branch name.
+
+```typescript
+import { findGitBranch } from '@codedrifters/constructs/lib/git-utils';
+
+const branch = findGitBranch();
+// Returns: "feature/1234" or "main" etc.
+```
+
+**`findGitRepoName()`**
+
+Returns the repository name. Works in both local environments and GitHub Actions.
+
+```typescript
+import { findGitRepoName } from '@codedrifters/constructs/lib/git-utils';
+
+const repoName = findGitRepoName();
+// Returns: "codedrifters/packages" or similar
+```
+
+In GitHub Actions, this uses the `GITHUB_REPOSITORY` environment variable. Locally, it extracts the name from the git remote URL.
+
+#### String Utilities
+
+Helper functions for string manipulation.
+
+**`hashString(inString: string, trimLength?: number)`**
+
+Creates a SHA-256 hash of a string, optionally trimmed to a specific length.
+
+```typescript
+import { hashString } from '@codedrifters/constructs/lib/string-utils';
+
+const hash = hashString('my-string');
+// Returns: Full SHA-256 hash
+
+const shortHash = hashString('my-string', 8);
+// Returns: First 8 characters of hash
+```
+
+**`trimStringLength(inputString: string, maxLength: number)`**
+
+Truncates a string to a maximum length if it exceeds it.
+
+```typescript
+import { trimStringLength } from '@codedrifters/constructs/lib/string-utils';
+
+const short = trimStringLength('very long string', 10);
+// Returns: "very long " (truncated to 10 chars)
+
+const unchanged = trimStringLength('short', 10);
+// Returns: "short" (no change needed)
+```
+
+## Complete Example
+
+Here's a complete example showing how to use `StaticHosting` and `StaticContent` together:
+
+```typescript
+import { StaticContent, StaticHosting } from '@codedrifters/constructs';
+import { App, RemovalPolicy, Stack } from 'aws-cdk-lib';
+
+const app = new App();
+
+const env = {
+  account: '123456789012',
+  region: 'us-east-1',
+};
+
+const baseDomain = 'example.com';
+
+/*******************************************************************************
+ *
+ * Step 1: Create the hosting infrastructure
+ *
+ * This creates the S3 bucket, CloudFront distribution, SSL certificate,
+ * and DNS records.
+ *
+ ******************************************************************************/
+
+const hostingStack = new Stack(
+  app,
+  `static-hosting-dev-${env.account}-${env.region}`,
+  { env }
+);
+
+const hosting = new StaticHosting(hostingStack, 'static-hosting', {
+  description: 'My static website',
+  privateBucketProps: {
+    removalPolicy: RemovalPolicy.DESTROY,
+    autoDeleteObjects: true,
+  },
+  staticDomainProps: {
+    baseDomain,
+    hostedZoneAttributes: {
+      hostedZoneId: 'Z1234567890ABC',
+      zoneName: baseDomain,
+    },
+  },
+});
+
+/*******************************************************************************
+ *
+ * Step 2: Deploy static content
+ *
+ * This deploys files from a local directory to the S3 bucket created above.
+ * The content stack must depend on the hosting stack to ensure the bucket
+ * exists before deployment.
+ *
+ ******************************************************************************/
+
+const contentStack = new Stack(
+  app,
+  `static-content-dev-${env.account}-${env.region}`,
+  { env }
+);
+
+// Ensure hosting stack is created first
+contentStack.node.addDependency(hostingStack);
+
+new StaticContent(contentStack, 'static-content', {
+  contentSourceDirectory: 'src/website', // Path to your built website files
+  contentDestinationDirectory: '/', // Deploy to root
+  fullDomain: hosting.fullDomain, // Use the domain from StaticHosting
+});
+
+app.synth();
+```
+
+**Deployment Flow:**
+
+1. Deploy the hosting stack first: `cdk deploy static-hosting-dev-*`
+2. This creates the S3 bucket, CloudFront distribution, SSL certificate, and DNS records
+3. Deploy the content stack: `cdk deploy static-content-dev-*`
+4. This uploads your static files to the S3 bucket
+5. Your website is now live at your domain!
+
+**Branch-Based Deployments:**
+
+When deploying from different git branches, the `StaticContent` construct automatically uses the branch name as a subdomain prefix. This allows you to have:
+- `main` branch → `example.com`
+- `feature-123` branch → `feature-123.example.com`
+- `pr-456` branch → `pr-456.example.com`
+
+All using the same S3 bucket and CloudFront distribution!
+
+## API Reference
+
+### Exports
+
+The package exports the following:
+
+**Constructs:**
+- `PrivateBucket` - Secure S3 bucket
+- `StaticHosting` - Complete static hosting solution
+- `StaticContent` - Static content deployment
+
+**Utilities:**
+- `findGitBranch()` - Get current git branch
+- `findGitRepoName()` - Get repository name
+- `hashString()` - Hash a string
+- `trimStringLength()` - Truncate a string
+
+### Type Definitions
+
+**PrivateBucketProps**
+- Extends `BucketProps` from `aws-cdk-lib/aws-s3`
+- All standard S3 bucket properties are supported
+- Security settings are enforced and cannot be overridden
+
+**StaticHostingProps**
+- Extends `StackProps` from `aws-cdk-lib`
+- See [StaticHosting](#statichosting) section for full property list
+
+**StaticContentProps**
+- See [StaticContent](#staticcontent) section for full property list
+
+**StaticDomainProps**
+- `baseDomain: string` - Base domain name
+- `hostedZoneAttributes: HostedZoneAttributes` - Route53 hosted zone attributes
+
+## Further Documentation
+
+### AWS CDK Resources
+
+- [AWS CDK Developer Guide](https://docs.aws.amazon.com/cdk/v2/guide/home.html) - Comprehensive guide to AWS CDK
+- [AWS CDK API Reference](https://docs.aws.amazon.com/cdk/api/v2/) - Complete API documentation
+- [AWS CDK Construct Library](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-construct-library.html) - All available constructs
+
+### AWS Service Documentation
+
+- [Amazon S3 Documentation](https://docs.aws.amazon.com/s3/) - S3 service documentation
+- [Amazon CloudFront Documentation](https://docs.aws.amazon.com/cloudfront/) - CloudFront CDN documentation
+- [AWS Certificate Manager](https://docs.aws.amazon.com/acm/) - SSL/TLS certificate management
+- [Amazon Route53](https://docs.aws.amazon.com/route53/) - DNS service documentation
+
+### Package Information
+
+- [NPM Package](https://www.npmjs.com/package/@codedrifters/constructs) - View on NPM
+- [GitHub Repository](https://github.com/codedrifters/packages) - Source code
+
+---
+
+**Note:** This package is designed for use with AWS CDK v2. Make sure you're using compatible versions of `aws-cdk-lib` and `constructs`.

package/package.json

@@ -42,7 +42,7 @@
   },
   "main": "lib/index.js",
   "license": "UNLICENSED",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "types": "lib/index.d.ts",
   "//": "~~ Generated by projen. To modify, edit .projenrc.js and run \"npx projen\".",
   "scripts": {