ac-lambda-deployment 0.0.1

package/README.md

@@ -0,0 +1,334 @@
+# ac-lambda-deployment
+
+Simple AWS Lambda deployment tool using AWS SDK v3. Deploys code, manages layers, and configures SQS triggers without the complexity of full infrastructure-as-code tools.
+
+## Features
+
+- **Code-focused deployment** - Updates Lambda function code quickly
+- **Layer management** - Attach and update Lambda layers
+- **SQS trigger configuration** - Manage event source mappings
+- **Multi-environment support** - Different configs for dev/prod
+- **Automatic retry logic** - Handles concurrent update conflicts
+- **Include-based packaging** - Only package specified files
+- **AWS profile support** - Use different AWS profiles per environment
+
+## Installation
+
+```bash
+npm install ac-lambda-deployment --save-dev
+# or
+yarn add ac-lambda-deployment --dev
+```
+
+## Quick Start
+
+**1. Create a configuration file:**
+
+```javascript
+// lambda.config.js
+module.exports = {
+    functionName: 'my-lambda-function',
+    roleArn: 'arn:aws:iam::123456789012:role/lambda-execution-role',
+    handler: 'lambda.handler',
+    includes: ['lambda.js'],
+    layers: [
+        'arn:aws:lambda:eu-central-1:123456789012:layer:my-utils:1'
+    ]
+}
+```
+
+**2. Add to package.json scripts:**
+
+```json
+{
+    "scripts": {
+        "deploy": "lambda-deploy",
+        "deploy:prod": "NODE_ENV=production lambda-deploy --profile=prod"
+    }
+}
+```
+
+**3. Deploy:**
+
+```bash
+npm run deploy
+```
+
+## Configuration
+
+### Basic Configuration
+
+Create `lambda.config.js` in your project root:
+
+```javascript
+module.exports = {
+    functionName: 'my-function',
+    roleArn: 'arn:aws:iam::123456789012:role/lambda-role',
+    handler: 'lambda.handler',
+    runtime: 'nodejs18.x',
+    timeout: 30,
+    memorySize: 128,
+    includes: ['lambda.js', 'config.json'],
+    environment: {
+        NODE_ENV: 'production',
+        API_KEY: 'your-api-key'
+    }
+}
+```
+
+### Multi-Environment Configuration
+
+```javascript
+// lambda.config.js
+const env = process.env.NODE_ENV || 'dev'
+
+const environments = {
+    dev: {
+        functionName: 'my-function-dev',
+        roleArn: 'arn:aws:iam::123456789012:role/lambda-dev-role',
+        profile: 'default',
+        layers: [
+            'arn:aws:lambda:eu-central-1:123456789012:layer:dev-utils:1'
+        ]
+    },
+    production: {
+        functionName: 'my-function-prod',
+        roleArn: 'arn:aws:iam::123456789012:role/lambda-prod-role', 
+        profile: 'production',
+        layers: [
+            'arn:aws:lambda:eu-central-1:123456789012:layer:prod-utils:2'
+        ]
+    }
+}
+
+module.exports = {
+    handler: 'lambda.handler',
+    runtime: 'nodejs18.x',
+    includes: ['lambda.js'],
+    ...environments[env]
+}
+```
+
+### SQS Triggers
+
+```javascript
+module.exports = {
+    functionName: 'my-sqs-processor',
+    roleArn: 'arn:aws:iam::123456789012:role/lambda-sqs-role',
+    sqsTriggers: [
+        {
+            queueArn: 'arn:aws:sqs:eu-central-1:123456789012:my-queue',
+            batchSize: 10,
+            maxBatchingWindow: 5,
+            enabled: true
+        }
+    ]
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `functionName` | string | **required** | Lambda function name |
+| `roleArn` | string | **required** | IAM role ARN for the function |
+| `handler` | string | `lambda.handler` | Function entry point |
+| `runtime` | string | `nodejs18.x` | Lambda runtime |
+| `timeout` | number | `30` | Function timeout in seconds |
+| `memorySize` | number | `128` | Memory allocation in MB |
+| `includes` | array | `['lambda.js']` | Files to include in deployment package |
+| `layers` | array | `[]` | Lambda layer ARNs |
+| `environment` | object | `{}` | Environment variables |
+| `profile` | string | default | AWS profile to use |
+| `region` | string | `eu-central-1` | AWS region |
+| `sqsTriggers` | array | `[]` | SQS event source mappings |
+
+## Usage
+
+### Command Line
+
+```bash
+# Deploy with default configuration
+npx lambda-deploy
+
+# Deploy with specific AWS profile
+npx lambda-deploy --profile=production
+
+# Deploy with different region
+npx lambda-deploy --region=us-east-1
+
+# Deploy with custom config file
+npx lambda-deploy --config=prod.config.js
+
+# Multi-environment
+NODE_ENV=production npx lambda-deploy --profile=prod
+```
+
+### Programmatic Usage
+
+```javascript
+const LambdaDeployer = require('ac-lambda-deployment')
+
+async function deploy() {
+    const deployer = new LambdaDeployer({
+        region: 'eu-central-1',
+        profile: 'production'
+    })
+    
+    await deployer.deploy()
+}
+
+deploy().catch(console.error)
+```
+
+## Package Structure
+
+The tool uses an **include-based** approach - only specified files are packaged:
+
+```
+project/
+├── lambda.js              # Your Lambda function (included)
+├── lambda.config.js       # Configuration (not included)
+├── package.json           # Dependencies info (not included) 
+├── node_modules/          # Always included in package
+└── other-files.js         # Only if specified in includes
+```
+
+**Default includes:** `['lambda.js']`
+**Always included:** `node_modules/` (production dependencies)
+
+## AWS Permissions
+
+Your Lambda execution role needs these permissions for SQS triggers:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Action": [
+                "sqs:ReceiveMessage",
+                "sqs:DeleteMessage", 
+                "sqs:GetQueueAttributes"
+            ],
+            "Resource": "arn:aws:sqs:*:*:*"
+        }
+    ]
+}
+```
+
+## Alternative Configuration
+
+You can also configure in `package.json`:
+
+```json
+{
+    "name": "my-project",
+    "lambda": {
+        "functionName": "my-function",
+        "roleArn": "arn:aws:iam::123456789012:role/lambda-role",
+        "includes": ["lambda.js", "utils.js"]
+    }
+}
+```
+
+## Security
+
+**Important:** Never commit `lambda.config.js` to version control if it contains sensitive data.
+
+```bash
+# .gitignore
+lambda.config.js
+lambda.*.config.js
+```
+
+Create a template instead:
+
+```javascript
+// lambda.config.example.js
+module.exports = {
+    functionName: 'your-function-name',
+    roleArn: 'arn:aws:iam::YOUR-ACCOUNT:role/YOUR-ROLE',
+    environment: {
+        API_KEY: 'your-api-key'
+    }
+}
+```
+
+## Comparison with Other Tools
+
+| Tool | Code Deploy | Infrastructure | Complexity |
+|------|-------------|----------------|------------|
+| **ac-lambda-deployment** | ✅ Fast | Layers, SQS only | Low |
+| Serverless Framework | ✅ | ✅ Full | High |
+| AWS SAM | ✅ | ✅ Full | Medium |
+| Terraform | ❌ | ✅ Full | High |
+| ClaudiaJS | ✅ Fast | Basic | Low (deprecated) |
+
+**Use ac-lambda-deployment when:**
+- You want fast code deployments
+- Infrastructure is managed separately (Terraform/CDK)
+- You need simple layer and SQS trigger management
+- You want ClaudiaJS-like simplicity with modern AWS SDK
+
+## Examples
+
+### Simple API Function
+
+```javascript
+// lambda.config.js
+module.exports = {
+    functionName: 'api-handler',
+    roleArn: 'arn:aws:iam::123456789012:role/api-lambda-role',
+    handler: 'lambda.handler',
+    timeout: 10,
+    memorySize: 256,
+    environment: {
+        DATABASE_URL: process.env.DATABASE_URL
+    }
+}
+```
+
+### SQS Message Processor
+
+```javascript
+// lambda.config.js  
+module.exports = {
+    functionName: 'queue-processor',
+    roleArn: 'arn:aws:iam::123456789012:role/sqs-lambda-role',
+    sqsTriggers: [
+        {
+            queueArn: 'arn:aws:sqs:eu-central-1:123456789012:process-queue',
+            batchSize: 5,
+            maxBatchingWindow: 10
+        }
+    ],
+    layers: [
+        'arn:aws:lambda:eu-central-1:123456789012:layer:shared-utils:1'
+    ]
+}
+```
+
+## Troubleshooting
+
+### Permission Denied
+```bash
+chmod +x ./node_modules/ac-lambda-deployment/index.js
+```
+
+### Concurrent Update Error
+The tool automatically retries when Lambda is being updated. Wait 30-60 seconds between deployments.
+
+### Function Not Found
+Make sure the function exists or provide `roleArn` to create it automatically.
+
+## License
+
+MIT © 2025 AdmiralCloud AG, Mark Poepping
+
+## Support
+
+- Check AWS credentials: `aws sts get-caller-identity`
+- Verify function exists: `aws lambda get-function --function-name your-function`
+- Enable debug logging: `AWS_SDK_LOAD_CONFIG=1 DEBUG=* npx lambda-deploy`

package/index.js

@@ -0,0 +1,346 @@
+#!/usr/bin/env node
+
+const { LambdaClient, UpdateFunctionCodeCommand, CreateFunctionCommand, GetFunctionCommand, UpdateFunctionConfigurationCommand, CreateEventSourceMappingCommand, ListEventSourceMappingsCommand, UpdateEventSourceMappingCommand, DeleteEventSourceMappingCommand } = require('@aws-sdk/client-lambda')
+const { fromIni } = require('@aws-sdk/credential-provider-ini')
+const fs = require('fs')
+const path = require('path')
+const archiver = require('archiver')
+const { execSync } = require('child_process')
+
+class LambdaDeployer {
+    constructor(options = {}) {
+        const { region = 'eu-central-1', profile } = options
+        
+        const clientConfig = { region }
+        if (profile) {
+            clientConfig.credentials = fromIni({ profile })
+        }
+        
+        this.lambda = new LambdaClient(clientConfig)
+    }
+
+    // Load configuration from lambda.config.js or package.json
+    loadConfig(configPath) {
+        const cwd = process.cwd()
+        
+        // Try lambda.config.js first
+        const configFile = path.join(cwd, configPath || 'lambda.config.js')
+        if (fs.existsSync(configFile)) {
+            delete require.cache[require.resolve(configFile)]
+            return require(configFile)
+        }
+        
+        // Try package.json lambda section
+        const packageFile = path.join(cwd, 'package.json')
+        if (fs.existsSync(packageFile)) {
+            const pkg = JSON.parse(fs.readFileSync(packageFile, 'utf8'))
+            if (pkg.lambda) {
+                return pkg.lambda
+            }
+        }
+        
+        throw new Error('No configuration found. Create lambda.config.js or add "lambda" section to package.json')
+    }
+
+    // Create ZIP archive with code and dependencies
+    createZip(sourceDir, outputPath, includes = ['lambda.js']) {
+        return new Promise((resolve, reject) => {
+            const output = fs.createWriteStream(outputPath)
+            const archive = archiver('zip', { zlib: { level: 9 } })
+
+            output.on('close', () => resolve(outputPath))
+            archive.on('error', reject)
+
+            archive.pipe(output)
+            
+            // Add specified files only
+            includes.forEach(pattern => {
+                const fullPath = path.join(sourceDir, pattern)
+                if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+                    archive.file(fullPath, { name: pattern })
+                }
+                else {
+                    // Handle glob patterns
+                    archive.glob(pattern, { cwd: sourceDir })
+                }
+            })
+
+            // Install and add production dependencies
+            console.log('Installing production dependencies...')
+            try {
+                // Detect package manager
+                const hasYarnLock = fs.existsSync(path.join(sourceDir, 'yarn.lock'))
+                const hasPnpmLock = fs.existsSync(path.join(sourceDir, 'pnpm-lock.yaml'))
+                
+                let installCmd
+                if (hasYarnLock) {
+                    installCmd = 'yarn install --production --silent'
+                }
+                else if (hasPnpmLock) {
+                    installCmd = 'pnpm install --production'
+                }
+                else {
+                    installCmd = 'npm install --production --silent'
+                }
+                
+                execSync(installCmd, { cwd: sourceDir })
+                archive.directory(path.join(sourceDir, 'node_modules'), 'node_modules')
+            }
+            catch {
+                console.warn('Warning: dependency installation failed, continuing without dependencies')
+            }
+
+            archive.finalize()
+        })
+    }
+
+    // Check if function exists
+    async functionExists(functionName) {
+        try {
+            await this.lambda.send(new GetFunctionCommand({ FunctionName: functionName }))
+            return true
+        }
+        catch (err) {
+            if (err.name === 'ResourceNotFoundException') {
+                return false
+            }
+            throw err
+        }
+    }
+
+    // Create new Lambda function
+    createFunction(config) {
+        const zipBuffer = fs.readFileSync(config.zipPath)
+        
+        const params = {
+            FunctionName: config.functionName,
+            Runtime: config.runtime || 'nodejs18.x',
+            Role: config.roleArn,
+            Handler: config.handler || 'lambda.handler',
+            Code: { ZipFile: zipBuffer },
+            Description: config.description || 'Deployed with lambda-deployer',
+            Timeout: config.timeout || 30,
+            MemorySize: config.memorySize || 128,
+            Environment: config.environment ? { Variables: config.environment } : undefined,
+            Layers: config.layers || []
+        }
+
+        const command = new CreateFunctionCommand(params)
+        return this.lambda.send(command)
+    }
+
+    // Update existing Lambda function code with retry
+    async updateFunction(functionName, zipPath) {
+        const zipBuffer = fs.readFileSync(zipPath)
+        
+        const params = {
+            FunctionName: functionName,
+            ZipFile: zipBuffer
+        }
+
+        const command = new UpdateFunctionCodeCommand(params)
+        
+        // Retry logic for concurrent updates
+        for (let i = 0; i < 3; i++) {
+            try {
+                return this.lambda.send(command)
+            }
+            catch (err) {
+                if (err.name === 'ResourceConflictException' && i < 2) {
+                    console.log(`Function is being updated, waiting 30 seconds... (attempt ${i + 1}/3)`)
+                    await new Promise(resolve => setTimeout(resolve, 30000))
+                    continue
+                }
+                throw err
+            }
+        }
+    }
+
+    // Update function configuration (layers, environment, etc.) with retry
+    async updateFunctionConfig(config) {
+        const params = {
+            FunctionName: config.functionName,
+            Runtime: config.runtime,
+            Handler: config.handler,
+            Description: config.description,
+            Timeout: config.timeout,
+            MemorySize: config.memorySize,
+            Environment: config.environment ? { Variables: config.environment } : undefined,
+            Layers: config.layers || []
+        }
+
+        const command = new UpdateFunctionConfigurationCommand(params)
+        
+        // Retry logic for concurrent updates
+        for (let i = 0; i < 3; i++) {
+            try {
+                return this.lambda.send(command)
+            }
+            catch (err) {
+                if (err.name === 'ResourceConflictException' && i < 2) {
+                    console.log(`Function config is being updated, waiting 20 seconds... (attempt ${i + 1}/3)`)
+                    await new Promise(resolve => setTimeout(resolve, 20000))
+                    continue
+                }
+                throw err
+            }
+        }
+    }
+
+    // Manage SQS event source mappings
+    async updateEventSourceMappings(functionName, sqsTriggers = []) {
+        if (sqsTriggers.length === 0) return
+
+        // Get existing mappings
+        const listCommand = new ListEventSourceMappingsCommand({
+            FunctionName: functionName
+        })
+        const existing = await this.lambda.send(listCommand)
+        
+        // Process each SQS trigger
+        for (const trigger of sqsTriggers) {
+            const existingMapping = existing.EventSourceMappings?.find(
+                m => m.EventSourceArn === trigger.queueArn
+            )
+
+            if (existingMapping) {
+                // Update existing mapping
+                console.log(`Updating SQS trigger: ${trigger.queueArn}`)
+                const updateCommand = new UpdateEventSourceMappingCommand({
+                    UUID: existingMapping.UUID,
+                    BatchSize: trigger.batchSize || 10,
+                    MaximumBatchingWindowInSeconds: trigger.maxBatchingWindow || 0,
+                    Enabled: trigger.enabled !== false
+                })
+                await this.lambda.send(updateCommand)
+            }
+            else {
+                // Create new mapping
+                console.log(`Creating SQS trigger: ${trigger.queueArn}`)
+                const createCommand = new CreateEventSourceMappingCommand({
+                    EventSourceArn: trigger.queueArn,
+                    FunctionName: functionName,
+                    BatchSize: trigger.batchSize || 10,
+                    MaximumBatchingWindowInSeconds: trigger.maxBatchingWindow || 0,
+                    Enabled: trigger.enabled !== false
+                })
+                await this.lambda.send(createCommand)
+            }
+        }
+
+        // Remove mappings not in config
+        const configuredArns = sqsTriggers.map(t => t.queueArn)
+        for (const mapping of existing.EventSourceMappings || []) {
+            if (!configuredArns.includes(mapping.EventSourceArn)) {
+                console.log(`Removing SQS trigger: ${mapping.EventSourceArn}`)
+                const deleteCommand = new DeleteEventSourceMappingCommand({
+                    UUID: mapping.UUID
+                })
+                await this.lambda.send(deleteCommand)
+            }
+        }
+    }
+
+    // Main deployment function
+    async deploy(configPath) {
+        const config = this.loadConfig(configPath)
+        
+        const {
+            functionName,
+            sourceDir = '.',
+            roleArn,
+            includes = ['lambda.js'],
+            region,
+            profile
+        } = config
+
+        // Override AWS config if specified in config file
+        if (region || profile) {
+            const clientConfig = { region: region || 'eu-central-1' }
+            if (profile) {
+                clientConfig.credentials = fromIni({ profile })
+            }
+            this.lambda = new LambdaClient(clientConfig)
+        }
+
+        if (!functionName) {
+            throw new Error('functionName is required in configuration')
+        }
+
+        console.log(`Deploying Lambda function: ${functionName}`)
+        
+        // Create ZIP
+        const zipPath = path.join(sourceDir, `${functionName}.zip`)
+        console.log('Creating deployment package...')
+        await this.createZip(sourceDir, zipPath, includes)
+        
+        try {
+            const exists = await this.functionExists(functionName)
+            
+            if (exists) {
+                console.log('Updating existing function...')
+                await this.updateFunction(functionName, zipPath)
+                
+                // Update function configuration (layers, environment, etc.)
+                if (config.layers || config.environment || config.timeout || config.memorySize) {
+                    console.log('Updating function configuration...')
+                    await this.updateFunctionConfig(config)
+                }
+                
+                // Update SQS triggers
+                if (config.sqsTriggers) {
+                    console.log('Updating SQS triggers...')
+                    await this.updateEventSourceMappings(functionName, config.sqsTriggers)
+                }
+                
+                console.log('Function updated successfully!')
+            }
+            else {
+                if (!roleArn) {
+                    throw new Error('roleArn is required for creating new functions')
+                }
+                console.log('Creating new function...')
+                await this.createFunction({ ...config, zipPath })
+                
+                // Add SQS triggers after function creation
+                if (config.sqsTriggers) {
+                    console.log('Creating SQS triggers...')
+                    await this.updateEventSourceMappings(functionName, config.sqsTriggers)
+                }
+                
+                console.log('Function created successfully!')
+            }
+        }
+        finally {
+            // Cleanup ZIP file
+            if (fs.existsSync(zipPath)) {
+                fs.unlinkSync(zipPath)
+            }
+        }
+    }
+}
+
+// CLI interface
+async function cli() {
+    const args = process.argv.slice(2)
+    const profile = args.find(arg => arg.startsWith('--profile='))?.split('=')[1]
+    const region = args.find(arg => arg.startsWith('--region='))?.split('=')[1]
+    const config = args.find(arg => arg.startsWith('--config='))?.split('=')[1]
+    
+    const deployer = new LambdaDeployer({ region, profile })
+    
+    try {
+        await deployer.deploy(config)
+    }
+    catch (err) {
+        console.error('Deployment failed:', err.message)
+        process.exit(1)
+    }
+}
+
+// Run CLI if called directly
+if (require.main === module) {
+    cli()
+}
+
+module.exports = LambdaDeployer

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "ac-lambda-deployment",
+  "version": "0.0.1",
+  "description": "Simple AWS Lambda deployment tool using AWS SDK v3",
+  "main": "index.js",
+  "bin": {
+    "lambda-deploy": "./index.js"
+  },
+  "author": "Mark Poepping (https://www.admiralcloud.com)",
+  "license": "MIT",
+  "packageManager": "yarn@1.22.22",
+  "keywords": [
+    "aws",
+    "lambda",
+    "deployment",
+    "serverless",
+    "aws-sdk-v3"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/admiralcloud/ac-lambda-deployment"
+  },
+  "bugs": {
+    "url": "https://github.com/admiralcloud/ac-lambda-deployment/issues"
+  },
+  "homepage": "https://github.com/admiralcloud/ac-lambda-deployment#readme",
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "lint": "eslint index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "dependencies": {
+    "@aws-sdk/client-lambda": "^3.848.0",
+    "@aws-sdk/credential-provider-ini": "^3.848.0",
+    "archiver": "^7.0.1"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.31.0"
+  }
+}