Migrate backend from Serverless Framework to AWS SAM (#94)

- Replace Serverless Framework v3 with AWS SAM
- Upgrade Node.js runtime from 20.x to 22.x
- Use esbuild (built into SAM) instead of webpack/babel
- Add esbuild-jest for test transformation
- Update GitHub Actions workflow for SAM CLI
- Update documentation (README, CLAUDE.md)

This migration was necessary because Serverless v3 doesn't support
Node.js > 20, and Serverless v4 has an incompatible license.

Author: smessmer

.github/workflows/backend.yml

@@ -3,7 +3,6 @@ name: Backend
 on:
   push:
   pull_request:
-
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
@@ -25,6 +24,8 @@ jobs:
           node-version-file: 'backend/package.json'
           cache: npm
           cache-dependency-path: backend/package.json
+      - name: Setup AWS SAM
+        uses: aws-actions/setup-sam@v2
       - name: Install Dependencies
         working-directory: backend
         run: npm install
@@ -33,12 +34,13 @@ jobs:
         run: npm test
       - name: Build
         working-directory: backend
-        run: ./serverless package --package /tmp/artifacts --stage prod
+        run: npm run build
       - name: Store artifacts
         uses: actions/upload-artifact@master
         with:
-          name: serverless-package
-          path: /tmp/artifacts
+          name: sam-build
+          path: backend/.aws-sam
+
   deploy:
     needs: build
     if: success() && github.event_name == 'push' && github.ref == 'refs/heads/master'
@@ -51,20 +53,13 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-      - name: Use Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version-file: 'backend/package.json'
-          cache: npm
-          cache-dependency-path: backend/package.json
-      - name: Install Dependencies
-        working-directory: backend
-        run: npm install
+      - name: Setup AWS SAM
+        uses: aws-actions/setup-sam@v2
       - name: Load artifacts
         uses: actions/download-artifact@master
         with:
-          name: serverless-package
-          path: /tmp/artifacts
+          name: sam-build
+          path: backend/.aws-sam
       - name: Deploy
         working-directory: backend
-        run: ./serverless deploy --package /tmp/artifacts --stage prod --conceal --verbose --debug=*
+        run: sam deploy --no-confirm-changeset

.gitignore

@@ -4,8 +4,7 @@ node_modules
 *.log
 out
 jspm_packages
-.serverless
-.webpack
+.aws-sam
 backend/artifacts
 backend/coverage
 frontend/coverage

CLAUDE.md

@@ -32,7 +32,9 @@ npm run build    # Production build
 cd backend
 npm install
 npm test         # Unit tests
-./serverless deploy --stage prod  # Deploy (requires AWS credentials)
+npm run build    # Build with SAM
+npm run local    # Local API server (requires Docker)
+npm run deploy   # Deploy to AWS (requires credentials)
 ```
 
 ## Deployment

backend/CLAUDE.md

@@ -1,15 +1,21 @@
 # Backend
 
-AWS Lambda serverless functions for the CryFS website.
+AWS Lambda serverless functions for the CryFS website, deployed with AWS SAM.
 
 ## Tech Stack
 
-- **Runtime**: AWS Lambda with Serverless Framework
+- **Runtime**: AWS Lambda with AWS SAM (Serverless Application Model)
 - **Language**: JavaScript (ES6+, no TypeScript)
-- **Bundler**: Webpack + Babel
+- **Bundler**: esbuild (built into SAM)
 - **External Services**: SendGrid (email), Mailchimp (newsletter)
 - **Secrets**: AWS SSM Parameter Store
 
+## Prerequisites
+
+Install the AWS SAM CLI:
+- macOS: `brew install aws-sam-cli`
+- Other: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html
+
 ## API Endpoints
 
 | Method | Path | Description |
@@ -23,14 +29,57 @@ Both endpoints use simple token-based spam protection (not authentication).
 
 ```
 backend/
-├── *.js            # Source modules (handlers and utilities)
-├── *.test.js       # Jest tests (colocated)
-├── __mocks__/      # Jest mocks for external services
-├── iam/            # IAM policy documentation
-├── serverless.yml  # Serverless Framework config
-└── webpack.config.js
+├── *.js              # Source modules (handlers and utilities)
+├── *.test.js         # Jest tests (colocated)
+├── __mocks__/        # Jest mocks for external services
+├── iam/              # IAM policy documentation
+├── template.yaml     # SAM template (infrastructure as code)
+└── samconfig.toml    # SAM deployment configuration
+```
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Run unit tests
+npm test
+npm run test:watch     # Watch mode
+npm run test:coverage  # Coverage report
+
+# Build Lambda functions
+npm run build          # or: sam build
+
+# Local development
+npm run local          # Start local API at http://localhost:3000
+sam local invoke NewsletterRegisterFunction --event events/test.json
+
+# Deploy to AWS (requires AWS credentials)
+npm run deploy         # or: sam deploy --no-confirm-changeset
 ```
 
+## Local Testing with SAM
+
+1. Build the functions:
+   ```bash
+   sam build
+   ```
+
+2. Start local API Gateway:
+   ```bash
+   sam local start-api
+   ```
+
+3. Test endpoints (in another terminal):
+   ```bash
+   curl -X POST http://localhost:3000/newsletter/register \
+     -H "Content-Type: application/json" \
+     -d '{"token": "fd0kAn1zns", "email": "test@example.com"}'
+   ```
+
+Note: Local testing requires Docker. SSM secrets won't work locally unless you mock them or set environment variables.
+
 ## Code Conventions
 
 ### Lambda Handler Pattern
@@ -39,9 +88,9 @@ All handlers use the `LambdaFunction()` higher-order function wrapper:
 ```javascript
 import { LambdaFunction } from './lambda_function'
 
-export const myHandler = LambdaFunction(async (event) => {
+export const myHandler = LambdaFunction(async (body) => {
     // Implementation
-    return { success: true }
+    return { statusCode: 200, body: JSON.stringify({ success: true }) }
 })
 ```
 
@@ -80,18 +129,14 @@ jest.mock('mailchimp-api-v3')
 Mailchimp.__mockPost.mockResolvedValue({ status: 'subscribed' })
 ```
 
-## Commands
-
-```bash
-npm test              # Run tests
-npm run test:watch    # Tests in watch mode
-npm run test:coverage # Coverage report
-./serverless package  # Package for deployment
-./serverless deploy --stage prod  # Deploy to AWS
-```
-
 ## AWS Configuration
 
 Deployment requires:
 - AWS credentials with appropriate permissions (see `iam/` directory)
 - SSM parameters configured for secrets
+
+## Version Management
+
+IMPORTANT: Node.js version must be kept in sync in two places:
+- `package.json` → `engines.node`
+- `template.yaml` → `Globals.Function.Runtime`

backend/README.md

@@ -1,26 +1,45 @@
-Installation
--------------
-Run "npm install" to install dependencies
+# Backend
 
+AWS Lambda backend for CryFS website, deployed with AWS SAM.
 
-AWS Setup
--------------
-See `iam` folder for required IAM permissions
+## Installation
 
+```bash
+npm install
+```
 
-Serverless commands
--------------
-First set AWS environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_KEY.
+### SAM CLI
 
-Deploy all: $ ./serverless deploy [--stage prod]
-Deploy one function: $ ./serverless deploy function -f [functionName] [--stage prod]
-Invoke a remote function: $ ./serverless invoke -f [functionName] -l [--stage prod]
-Display remote logs: $ ./serverless logs -f [functionName] -t [--stage prod]
-Delete remote function: $ ./serverless remove
+Install the AWS SAM CLI for local development and deployment:
 
+```bash
+# Using pip
+pipx install aws-sam-cli
 
-Testing
--------------
-Run tests: $ npm test
-Run tests in watch mode: $ npm run test:watch
-Run tests with coverage: $ npm run test:coverage
+# Or using Homebrew (macOS/Linux)
+brew install aws-sam-cli
+```
+
+## AWS Setup
+
+See `iam` folder for required IAM permissions.
+
+## SAM Commands
+
+First set AWS environment variables `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
+
+```bash
+sam build                           # Build Lambda functions
+sam deploy --no-confirm-changeset   # Deploy to AWS
+sam local start-api                 # Start local API server
+sam logs -n NewsletterRegisterFunction --tail  # View logs
+sam delete                          # Delete stack
+```
+
+## Testing
+
+```bash
+npm test              # Run tests
+npm run test:watch    # Watch mode
+npm run test:coverage # Coverage report
+```

backend/babel.config.js

@@ -2,10 +2,12 @@ module.exports = {
   testEnvironment: 'node',
   testMatch: ['**/*.test.js'],
   testPathIgnorePatterns: ['/node_modules/'],
+  transform: {
+    '^.+\\.js$': 'esbuild-jest',
+  },
   collectCoverageFrom: [
     '*.js',
     '!jest.config.js',
-    '!webpack.config.js',
   ],
   clearMocks: true,
   resetModules: true,