specweave 0.21.2 → 0.22.0

package/plugins/specweave/iac-templates/aws-lambda/README.md.hbs

@@ -0,0 +1,280 @@
+# {{projectName}} - AWS Lambda Infrastructure
+
+🚀 Generated by **SpecWeave Serverless Intelligence**
+
+## Overview
+
+This Terraform configuration deploys a serverless application on AWS Lambda with the following components:
+
+- **Lambda Function**: `{{functionName}}` ({{runtime}}){{#if apiName}}
+- **API Gateway**: HTTP API with CORS support{{/if}}{{#if databaseName}}
+- **DynamoDB Table**: NoSQL database for data persistence{{/if}}
+- **IAM Roles**: Least-privilege security policies
+- **CloudWatch Logs**: Centralized logging and monitoring
+
+## Architecture
+
+```
+{{#if apiName}}
+Internet → API Gateway → Lambda Function{{#if databaseName}} → DynamoDB{{/if}}
+{{else}}
+Lambda Function{{#if databaseName}} → DynamoDB{{/if}}
+{{/if}}
+```
+
+## Prerequisites
+
+1. **AWS Account** with appropriate permissions
+2. **AWS CLI** configured with credentials
+3. **Terraform** >= 1.0 installed
+4. **Lambda deployment package**: `{{functionName}}.zip` with your function code
+
+## Quick Start
+
+### 1. Configure AWS Credentials
+
+```bash
+aws configure
+```
+
+### 2. Initialize Terraform
+
+```bash
+terraform init
+```
+
+### 3. Review Plan
+
+```bash
+terraform plan
+```
+
+### 4. Deploy
+
+```bash
+terraform apply
+```
+
+### 5. Test Deployment
+
+{{#if apiName}}
+```bash
+# Get API endpoint
+API_ENDPOINT=$(terraform output -raw api_endpoint)
+
+# Test API
+curl $API_ENDPOINT
+```
+{{else}}
+```bash
+# Invoke Lambda directly
+aws lambda invoke \
+  --function-name {{functionName}}-{{environment}} \
+  --payload '{"test": "data"}' \
+  response.json
+
+cat response.json
+```
+{{/if}}
+
+## Configuration
+
+### Variables
+
+Edit `terraform.tfvars` to customize:
+
+```hcl
+project_name  = "{{projectName}}"
+environment   = "{{environment}}"
+function_name = "{{functionName}}"
+runtime       = "{{runtime}}"
+memory_size   = {{#if memorySize}}{{memorySize}}{{else}}256{{/if}}
+timeout       = {{#if timeout}}{{timeout}}{{else}}30{{/if}}
+aws_region    = "{{#if region}}{{region}}{{else}}us-east-1{{/if}}"
+```
+
+### Environment Variables
+
+The Lambda function has these environment variables:
+
+- `ENVIRONMENT`: `{{environment}}`{{#if databaseName}}
+- `DYNAMODB_TABLE`: DynamoDB table name{{/if}}{{#if apiName}}
+- `API_ENDPOINT`: API Gateway endpoint{{/if}}
+
+## Outputs
+
+After deployment, Terraform provides these outputs:
+
+- `lambda_function_arn`: Lambda function ARN
+- `lambda_function_name`: Lambda function name{{#if apiName}}
+- `api_endpoint`: API Gateway URL{{/if}}{{#if databaseName}}
+- `dynamodb_table_name`: DynamoDB table name{{/if}}
+
+## Resource Details
+
+### Lambda Function
+
+- **Runtime**: {{runtime}}
+- **Memory**: {{#if memorySize}}{{memorySize}}{{else}}256{{/if}} MB
+- **Timeout**: {{#if timeout}}{{timeout}}{{else}}30{{/if}} seconds
+- **Handler**: {{#if handler}}{{handler}}{{else}}index.handler{{/if}}
+- **Execution Role**: Least-privilege IAM role with CloudWatch Logs{{#if databaseName}} and DynamoDB access{{/if}}
+
+{{#if apiName}}
+### API Gateway
+
+- **Type**: HTTP API (lower cost than REST API)
+- **CORS**: {{#if (eq environment "prod")}}Restricted to production domain{{else}}Allow all origins (dev/staging){{/if}}
+- **Logging**: CloudWatch access logs enabled
+- **Authentication**: None (add authentication in future iteration)
+
+### API Routes
+
+- `ANY /{proxy+}`: Proxies all requests to Lambda
+{{/if}}
+
+{{#if databaseName}}
+### DynamoDB Table
+
+- **Name**: `{{databaseName}}-{{environment}}`
+- **Billing Mode**: PAY_PER_REQUEST (on-demand)
+- **Primary Key**: `id` (String)
+- **Point-in-Time Recovery**: {{#if (eq environment "prod")}}Enabled (production){{else}}Disabled (dev/staging){{/if}}
+
+**Cost Optimization**: On-demand billing is cost-effective for variable workloads (no upfront capacity planning required).
+{{/if}}
+
+## Security Best Practices
+
+✅ **Implemented**:
+- Least-privilege IAM roles
+- CloudWatch Logs encryption at rest
+- Environment-specific configurations{{#if (eq environment "prod")}}
+- Point-in-time recovery for DynamoDB (production){{/if}}
+
+⚠️ **TODO**:
+- Add API Gateway authentication (Cognito, IAM, or Lambda authorizer)
+- Enable VPC integration for private subnets
+- Add secrets management (AWS Secrets Manager)
+- Implement WAF rules for API Gateway
+- Enable X-Ray tracing for debugging
+
+## Cost Estimation
+
+### Free Tier (First 12 Months)
+
+- **Lambda**: 1M requests/month, 400K GB-seconds/month
+- **API Gateway**: 1M requests/month
+- **DynamoDB**: 25 GB storage, 25 read/write capacity units{{#if databaseName}}
+- **CloudWatch Logs**: 5 GB ingestion/month{{/if}}
+
+### Estimated Monthly Cost (After Free Tier)
+
+**Low Traffic** (10K requests/month):
+- Lambda: ~$0.20
+- API Gateway: ~$0.01{{#if databaseName}}
+- DynamoDB: ~$0.25{{/if}}
+- **Total**: ~$0.50/month
+
+**Medium Traffic** (1M requests/month):
+- Lambda: ~$1.50
+- API Gateway: ~$1.00{{#if databaseName}}
+- DynamoDB: ~$1.25{{/if}}
+- **Total**: ~$4.00/month
+
+**High Traffic** (10M requests/month):
+- Lambda: ~$18.00
+- API Gateway: ~$10.00{{#if databaseName}}
+- DynamoDB: ~$12.50{{/if}}
+- **Total**: ~$40.00/month
+
+💡 **Tip**: Monitor costs in AWS Cost Explorer and set up billing alerts.
+
+## Monitoring
+
+### CloudWatch Metrics
+
+- **Lambda Invocations**: Request count
+- **Lambda Duration**: Execution time (p50, p95, p99)
+- **Lambda Errors**: Error rate and types
+- **Lambda Throttles**: Concurrent execution limit hits{{#if apiName}}
+- **API Gateway 4XX/5XX**: Client and server errors{{/if}}{{#if databaseName}}
+- **DynamoDB Consumed RCUs/WCUs**: Read/write capacity{{/if}}
+
+### CloudWatch Logs
+
+- Lambda logs: `/aws/lambda/{{functionName}}-{{environment}}`{{#if apiName}}
+- API Gateway logs: `/aws/apigateway/{{apiName}}-{{environment}}`{{/if}}
+
+### Alarms (Recommended)
+
+```hcl
+# Add to your Terraform:
+resource "aws_cloudwatch_metric_alarm" "lambda_errors" {
+  alarm_name          = "{{functionName}}-errors"
+  comparison_operator = "GreaterThanThreshold"
+  evaluation_periods  = "2"
+  metric_name         = "Errors"
+  namespace           = "AWS/Lambda"
+  period              = "60"
+  statistic           = "Sum"
+  threshold           = "5"
+  alarm_description   = "Lambda function error rate too high"
+  alarm_actions       = [aws_sns_topic.alerts.arn]
+}
+```
+
+## Deployment Workflow
+
+### Development
+
+```bash
+terraform workspace new dev
+terraform workspace select dev
+terraform apply -var="environment=dev"
+```
+
+### Staging
+
+```bash
+terraform workspace new staging
+terraform workspace select staging
+terraform apply -var="environment=staging"
+```
+
+### Production
+
+```bash
+terraform workspace new prod
+terraform workspace select prod
+terraform apply -var="environment=prod"
+```
+
+## Cleanup
+
+To destroy all resources:
+
+```bash
+terraform destroy
+```
+
+⚠️ **Warning**: This will permanently delete all data in DynamoDB!
+
+## Next Steps
+
+1. **Add Authentication**: Implement Cognito or API Key authentication
+2. **Enable Monitoring**: Set up CloudWatch alarms for errors and latency
+3. **Implement CI/CD**: Automate deployments with GitHub Actions or AWS CodePipeline
+4. **Add Testing**: Create integration tests for API endpoints
+5. **Optimize Costs**: Review CloudWatch logs retention and DynamoDB capacity
+
+## Resources
+
+- [AWS Lambda Documentation](https://docs.aws.amazon.com/lambda/)
+- [API Gateway Documentation](https://docs.aws.amazon.com/apigateway/){{#if databaseName}}
+- [DynamoDB Documentation](https://docs.aws.amazon.com/dynamodb/){{/if}}
+- [Terraform AWS Provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs)
+
+---
+
+**Generated by SpecWeave** | [Learn More](https://spec-weave.com)

package/plugins/specweave/iac-templates/aws-lambda/defaults.json

@@ -0,0 +1,118 @@
+{
+  "platform": "aws-lambda",
+  "region": "us-east-1",
+  "secondaryRegion": "us-west-2",
+  "runtime": "nodejs18.x",
+  "handler": "index.handler",
+  "lambda": {
+    "memorySize": {
+      "dev": 128,
+      "staging": 256,
+      "prod": 512
+    },
+    "timeout": {
+      "dev": 3,
+      "staging": 10,
+      "prod": 30
+    },
+    "reservedConcurrentExecutions": {
+      "dev": null,
+      "staging": 10,
+      "prod": 100
+    },
+    "provisionedConcurrency": {
+      "dev": 0,
+      "staging": 0,
+      "prod": 5
+    }
+  },
+  "dynamodb": {
+    "billingMode": {
+      "dev": "PAY_PER_REQUEST",
+      "staging": "PAY_PER_REQUEST",
+      "prod": "PROVISIONED"
+    },
+    "readCapacity": {
+      "dev": null,
+      "staging": null,
+      "prod": 5
+    },
+    "writeCapacity": {
+      "dev": null,
+      "staging": null,
+      "prod": 5
+    },
+    "pointInTimeRecovery": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    },
+    "streamEnabled": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    },
+    "ttlEnabled": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    }
+  },
+  "cloudwatch": {
+    "retentionDays": {
+      "dev": 7,
+      "staging": 14,
+      "prod": 30
+    },
+    "metricsEnabled": {
+      "dev": false,
+      "staging": true,
+      "prod": true
+    }
+  },
+  "apiGateway": {
+    "throttling": {
+      "dev": {
+        "rateLimit": 10,
+        "burstLimit": 20
+      },
+      "staging": {
+        "rateLimit": 100,
+        "burstLimit": 200
+      },
+      "prod": {
+        "rateLimit": 1000,
+        "burstLimit": 2000
+      }
+    },
+    "cors": {
+      "dev": ["*"],
+      "staging": ["https://staging.example.com"],
+      "prod": ["https://example.com"]
+    }
+  },
+  "monitoring": {
+    "xrayEnabled": {
+      "dev": false,
+      "staging": true,
+      "prod": true
+    },
+    "alarms": {
+      "dev": false,
+      "staging": true,
+      "prod": true
+    }
+  },
+  "security": {
+    "kmsEncryption": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    },
+    "vpcEnabled": {
+      "dev": false,
+      "staging": false,
+      "prod": true
+    }
+  }
+}

package/plugins/specweave/iac-templates/aws-lambda/environments/dev.defaults.json

@@ -0,0 +1,46 @@
+{
+  "environment": "dev",
+  "region": "us-east-1",
+  "lambda": {
+    "memorySize": 128,
+    "timeout": 3,
+    "reservedConcurrentExecutions": null,
+    "provisionedConcurrency": 0
+  },
+  "dynamodb": {
+    "billingMode": "PAY_PER_REQUEST",
+    "pointInTimeRecovery": false,
+    "streamEnabled": false,
+    "ttlEnabled": false
+  },
+  "cloudwatch": {
+    "retentionDays": 7,
+    "metricsEnabled": false
+  },
+  "apiGateway": {
+    "throttling": {
+      "rateLimit": 10,
+      "burstLimit": 20
+    },
+    "cors": ["*"]
+  },
+  "monitoring": {
+    "xrayEnabled": false,
+    "alarms": false
+  },
+  "security": {
+    "kmsEncryption": false,
+    "vpcEnabled": false
+  },
+  "costOptimization": {
+    "description": "Free tier optimized - On-demand billing, minimal resources",
+    "estimatedMonthlyCost": "$0-5",
+    "freeTierEligible": true,
+    "notes": [
+      "Uses AWS Lambda free tier (1M requests/month, 400K GB-seconds)",
+      "DynamoDB on-demand pricing (25GB storage, 25 RCU/WCU free)",
+      "CloudWatch Logs 5GB free per month",
+      "API Gateway 1M requests free per month (first 12 months)"
+    ]
+  }
+}

package/plugins/specweave/iac-templates/aws-lambda/environments/prod.defaults.json

@@ -0,0 +1,67 @@
+{
+  "environment": "prod",
+  "region": "us-east-1",
+  "secondaryRegion": "us-west-2",
+  "lambda": {
+    "memorySize": 512,
+    "timeout": 30,
+    "reservedConcurrentExecutions": 100,
+    "provisionedConcurrency": 5
+  },
+  "dynamodb": {
+    "billingMode": "PROVISIONED",
+    "readCapacity": 5,
+    "writeCapacity": 5,
+    "pointInTimeRecovery": true,
+    "streamEnabled": true,
+    "ttlEnabled": true,
+    "globalTables": true
+  },
+  "cloudwatch": {
+    "retentionDays": 30,
+    "metricsEnabled": true
+  },
+  "apiGateway": {
+    "throttling": {
+      "rateLimit": 1000,
+      "burstLimit": 2000
+    },
+    "cors": ["https://example.com"],
+    "caching": {
+      "enabled": true,
+      "ttlSeconds": 300
+    }
+  },
+  "monitoring": {
+    "xrayEnabled": true,
+    "alarms": true,
+    "dashboards": true
+  },
+  "security": {
+    "kmsEncryption": true,
+    "vpcEnabled": true,
+    "waf": true,
+    "secretsManager": true
+  },
+  "backup": {
+    "enabled": true,
+    "retentionDays": 35,
+    "crossRegionCopy": true
+  },
+  "costOptimization": {
+    "description": "Production-ready - High availability, provisioned capacity, global tables",
+    "estimatedMonthlyCost": "$150-250",
+    "freeTierEligible": false,
+    "notes": [
+      "512MB memory for optimal performance",
+      "Provisioned concurrency (5 instances) eliminates cold starts",
+      "DynamoDB provisioned capacity for predictable performance",
+      "Point-in-time recovery and global tables for disaster recovery",
+      "KMS encryption at rest for compliance (SOC 2, HIPAA)",
+      "VPC integration for private resource access",
+      "WAF protection against common web exploits",
+      "30-day log retention for auditing",
+      "Cross-region backups for business continuity"
+    ]
+  }
+}

package/plugins/specweave/iac-templates/aws-lambda/environments/staging.defaults.json

@@ -0,0 +1,47 @@
+{
+  "environment": "staging",
+  "region": "us-east-1",
+  "lambda": {
+    "memorySize": 256,
+    "timeout": 10,
+    "reservedConcurrentExecutions": 10,
+    "provisionedConcurrency": 0
+  },
+  "dynamodb": {
+    "billingMode": "PAY_PER_REQUEST",
+    "pointInTimeRecovery": false,
+    "streamEnabled": false,
+    "ttlEnabled": false
+  },
+  "cloudwatch": {
+    "retentionDays": 14,
+    "metricsEnabled": true
+  },
+  "apiGateway": {
+    "throttling": {
+      "rateLimit": 100,
+      "burstLimit": 200
+    },
+    "cors": ["https://staging.example.com"]
+  },
+  "monitoring": {
+    "xrayEnabled": true,
+    "alarms": true
+  },
+  "security": {
+    "kmsEncryption": false,
+    "vpcEnabled": false
+  },
+  "costOptimization": {
+    "description": "Testing environment - Moderate resources, on-demand billing",
+    "estimatedMonthlyCost": "$20-40",
+    "freeTierEligible": false,
+    "notes": [
+      "256MB memory for realistic performance testing",
+      "10 concurrent executions limit to prevent runaway costs",
+      "X-Ray tracing enabled for debugging",
+      "CloudWatch alarms for error monitoring",
+      "14-day log retention for troubleshooting"
+    ]
+  }
+}