feat: add Express and Lambda adapters

.claude/settings.json

@@ -3,7 +3,7 @@
     "ask": [],
     "allow": [
       "Bash(git add:*)",
-      "Bash(node dist/server.js)",
+      "Bash(node dist/adapters/express/index.js)",
       "Bash(yarn install:*)",
       "Bash(yarn dev)",
       "Bash(yarn build)",

.github/workflows/ci.yml

@@ -37,7 +37,7 @@ jobs:
       run: yarn build
     - name: Start server in background
       run: |
-        node dist/server.js &
+        node dist/adapters/express/index.js &
         echo $! > server.pid
     - name: Wait for server to be ready
       run: |

AGENTS.md

@@ -7,7 +7,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 **Development**:
 - `yarn dev` - Start development server with hot reload using nodemon
 - `yarn build` - Compile TypeScript to JavaScript in `dist/`
-- `node dist/server.js` - Run the compiled application
+- `node dist/adapters/express/index.js` - Run the compiled application
 
 **Code Quality**:
 - `yarn lint` - Check code with ESLint

Dockerfile

@@ -27,4 +27,4 @@ COPY --from=build /app/dist ./dist
 COPY package.json yarn.lock ./
 RUN yarn install --frozen-lockfile --production && yarn cache clean
 
-CMD ["node", "dist/server.js"]
+CMD ["node", "dist/adapters/express/index.js"]

README.md

@@ -17,7 +17,7 @@ Built with **Node.js** and **Express**.
 | `ALL`  | `/base64/decode`        | Decodes a Base64 string to its original format.                                                              |
 | `ALL`  | `/basic-auth`           | Tests HTTP Basic Authentication by comparing credentials from Authorization header against query parameters. |
 | `ALL`  | `/error/timeout`        | Simulates a timeout by never sending a response.                                                             |
-| `ALL`  | `/error/network`        | Simulates a network error by closing the connection.                                                         |
+| `ALL`  | `/error/network`        | Simulates a network error by closing the connection. Returns `400` in Lambda (socket destroy is unsupported). |
 | `ALL`  | `/error/malformed-json` | Returns malformed JSON response.                                                                             |
 | `ALL`  | `/error/error`          | Throws an unhandled exception to trigger Express error handler.                                              |
 | `ALL`  | `/mirror`               | Returns the request body as a response.                                                                      |
@@ -97,7 +97,7 @@ Built with **Node.js** and **Express**.
 4. Run the application:
 
    ```bash
-   node dist/server.js
+   node dist/adapters/express/index.js
    ```
 
 ---

docs/DEVELOPMENT_GUIDE.md

@@ -6,12 +6,17 @@ This guide covers development-specific details for contributing to the HTTP Play
 
 ```
 ├── src
-│   ├── app.ts               # Main application setup
-│   ├── env.ts               # Environment variable handler
-│   ├── logger.ts            # Application logging configuration
-│   ├── middlewares          # Middlewares directory
-│   ├── routes               # API routes directory
-│   ├── server.ts            # Server startup and shutdown handling
+│   ├── adapters             # Runtime-specific entry points
+│   │   ├── express          # Express/Docker adapter
+│   │   │   ├── app.ts       # Express application setup
+│   │   │   └── index.ts     # Server startup and shutdown handling
+│   │   └── lambda           # AWS Lambda adapter
+│   │       └── index.ts     # Lambda handler (API Gateway HTTP API v2)
+│   ├── core                 # Shared business logic
+│   │   ├── env.ts           # Environment variable handler
+│   │   ├── logger.ts        # Application logging configuration
+│   │   ├── middlewares      # Middlewares directory
+│   │   └── routes           # API routes directory
 │   └── utils                # Utility functions directory
 ├── tests
 │   ├── api                  # API tests directory
@@ -59,7 +64,7 @@ Running API Tests Locally:
 1. Build and start the server:
    ```bash
    yarn build
-   node dist/server.js
+   node dist/adapters/express/index.js
    ```
 
 2. In another terminal, run the API tests:

nodemon.json

@@ -1,7 +1,7 @@
 {
   "watch": ["src"],
   "ext": "ts",
-  "exec": "tsx ./src/server.ts",
+  "exec": "tsx ./src/adapters/express/index.ts",
   "env": {
     "LOG_LEVEL": "debug",
     "KEEP_ALIVE_TIMEOUT": 5000,

package.json

@@ -2,12 +2,14 @@
   "name": "http-playground-server",
   "version": "0.0.1",
   "type": "module",
-  "main": "dist/server.js",
+  "main": "dist/adapters/express/index.js",
   "repository": "https://github.com/ryo8000/http-playground-server.git",
   "author": "Ryo Hasegawa",
   "license": "MIT",
   "scripts": {
     "build": "tsc",
+    "build:lambda:function": "yarn build && cp package.json dist/ && zip -r lambda-function.zip dist/",
+    "build:lambda:layer": "mkdir -p lambda-layer/nodejs && cp -r node_modules lambda-layer/nodejs && cd lambda-layer && zip -r ../lambda-layer.zip . && cd .. && rm -rf lambda-layer",
     "dev": "nodemon",
     "test": "jest --coverage",
     "test:api": "newman run tests/api/api-test-collection.json -e tests/api/environment.json --reporters cli",
@@ -24,6 +26,7 @@
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
+    "@types/aws-lambda": "8.10.149",
     "@types/cookie-parser": "1.4.10",
     "@types/cors": "2.8.19",
     "@types/express": "5.0.6",

src/app.ts → src/adapters/express/app.ts

@@ -1,21 +1,21 @@
 import express from 'express';
 import cookieParser from 'cookie-parser';
 import cors from 'cors';
-import { delayMiddleware } from './middlewares/delay.js';
-import { loggerMiddleware } from './middlewares/logger.js';
-import { base64Router } from './routes/base64.js';
-import { basicAuthRouter } from './routes/basic-auth.js';
-import { errorRouter } from './routes/error.js';
-import { indexRouter } from './routes/index.js';
-import { mirrorRouter } from './routes/mirror.js';
-import { redirectRouter } from './routes/redirect.js';
-import { requestRouter } from './routes/request.js';
-import { shutdownRouter } from './routes/shutdown.js';
-import { statusRouter } from './routes/status.js';
-import { uuidRouter } from './routes/uuid.js';
-import { HttpStatusCodes } from './utils/http.js';
-import { environment } from './env.js';
-import { log } from './logger.js';
+import { delayMiddleware } from '../../core/middlewares/delay.js';
+import { loggerMiddleware } from '../../core/middlewares/logger.js';
+import { base64Router } from '../../core/routes/base64.js';
+import { basicAuthRouter } from '../../core/routes/basic-auth.js';
+import { errorRouter } from '../../core/routes/error.js';
+import { indexRouter } from '../../core/routes/index.js';
+import { mirrorRouter } from '../../core/routes/mirror.js';
+import { redirectRouter } from '../../core/routes/redirect.js';
+import { requestRouter } from '../../core/routes/request.js';
+import { shutdownRouter } from '../../core/routes/shutdown.js';
+import { statusRouter } from '../../core/routes/status.js';
+import { uuidRouter } from '../../core/routes/uuid.js';
+import { HttpStatusCodes } from '../../utils/http.js';
+import { environment } from '../../core/env.js';
+import { log } from '../../core/logger.js';
 
 const app = express();
 

src/server.ts → src/adapters/express/index.ts

@@ -1,6 +1,6 @@
 import { app } from './app.js';
-import { environment } from './env.js';
-import { log } from './logger.js';
+import { environment } from '../../core/env.js';
+import { log } from '../../core/logger.js';
 
 const server = app.listen(environment.port, () => {
   log.info(`Server is running on http://localhost:${environment.port}`);

src/adapters/lambda/index.ts

@@ -0,0 +1,137 @@
+import http from 'node:http';
+import { createServer } from 'node:http';
+import type {
+  APIGatewayProxyEventV2,
+  APIGatewayProxyStructuredResultV2,
+  Handler,
+} from 'aws-lambda';
+import { app } from '../express/app.js';
+
+/** Hop-by-hop headers that must not be forwarded to the loopback request. */
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection',
+  'keep-alive',
+  'transfer-encoding',
+  'te',
+  'trailer',
+  'upgrade',
+  'proxy-authorization',
+  'proxy-authenticate',
+]);
+
+/**
+ * Starts the Express app on a random loopback port and resolves with the port number.
+ * Called once on cold start; subsequent invocations reuse the cached promise.
+ */
+const listeningPromise: Promise<number> = new Promise((resolve, reject) => {
+  const server = createServer(app);
+  server.listen(0, '127.0.0.1', () => {
+    const address = server.address();
+    if (address === null || typeof address === 'string') {
+      reject(new Error('Unexpected server address format'));
+      return;
+    }
+    resolve(address.port);
+  });
+  server.on('error', reject);
+});
+
+/**
+ * Converts an API Gateway HTTP API v2 event into a loopback HTTP request
+ * against the locally running Express server, and maps the response back
+ * to an API Gateway proxy result.
+ *
+ * @param event - The API Gateway v2 proxy event.
+ * @returns A structured API Gateway proxy result.
+ */
+export const handler: Handler<APIGatewayProxyEventV2, APIGatewayProxyStructuredResultV2> = async (
+  event,
+) => {
+  const port = await listeningPromise;
+
+  const method = event.requestContext.http.method;
+  const path = event.rawPath + (event.rawQueryString ? `?${event.rawQueryString}` : '');
+
+  const bodyBuffer: Buffer = event.body
+    ? Buffer.from(event.body, event.isBase64Encoded ? 'base64' : 'utf-8')
+    : Buffer.alloc(0);
+
+  // Build forwarded headers, skipping hop-by-hop headers and recalculating content-length.
+  const forwardHeaders: Record<string, string> = {};
+  for (const [key, value] of Object.entries(event.headers ?? {})) {
+    const lower = key.toLowerCase();
+    if (!HOP_BY_HOP_HEADERS.has(lower) && value !== undefined) {
+      forwardHeaders[lower] = value;
+    }
+  }
+  if (bodyBuffer.length > 0) {
+    forwardHeaders['content-length'] = String(bodyBuffer.length);
+  }
+
+  try {
+    const { statusCode, headers, rawBody } = await new Promise<{
+      statusCode: number;
+      headers: Record<string, string | string[]>;
+      rawBody: Buffer;
+    }>((resolve, reject) => {
+      const req = http.request(
+        {
+          hostname: '127.0.0.1',
+          port,
+          method,
+          path,
+          headers: forwardHeaders,
+        },
+        (res) => {
+          const chunks: Buffer[] = [];
+          res.on('data', (chunk: Buffer) => chunks.push(chunk));
+          res.on('end', () => {
+            const responseHeaders: Record<string, string | string[]> = {};
+            for (const [key, value] of Object.entries(res.headers)) {
+              if (value !== undefined) {
+                responseHeaders[key] = value;
+              }
+            }
+            resolve({
+              statusCode: res.statusCode ?? 200,
+              headers: responseHeaders,
+              rawBody: Buffer.concat(chunks),
+            });
+          });
+          res.on('error', reject);
+        },
+      );
+      req.on('error', reject);
+      if (bodyBuffer.length > 0) {
+        req.write(bodyBuffer);
+      }
+      req.end();
+    });
+
+    // Extract Set-Cookie headers into the cookies array (API Gateway v2 requirement).
+    const cookies: string[] = [];
+    const responseHeaders: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(headers)) {
+      if (key.toLowerCase() === 'set-cookie') {
+        const cookieValues = Array.isArray(value) ? value : [value];
+        cookies.push(...cookieValues);
+      } else {
+        responseHeaders[key] = Array.isArray(value) ? value.join(', ') : value;
+      }
+    }
+
+    return {
+      statusCode,
+      headers: responseHeaders,
+      body: rawBody.toString('utf-8'),
+      ...(cookies.length > 0 && { cookies }),
+    };
+  } catch {
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: { message: 'Internal server error' } }),
+      headers: { 'content-type': 'application/json' },
+    };
+  }
+};

src/middlewares/delay.ts → src/core/middlewares/delay.ts

@@ -1,5 +1,5 @@
 import { Request, Response, NextFunction } from 'express';
-import { toSafeInteger } from '../utils/number.js';
+import { toSafeInteger } from '../../utils/number.js';
 import { environment } from '../env.js';
 
 /**

src/routes/base64.ts → src/core/routes/base64.ts

@@ -1,5 +1,5 @@
 import { Router } from 'express';
-import { HttpStatusCodes } from '../utils/http.js';
+import { HttpStatusCodes } from '../../utils/http.js';
 import { log } from '../logger.js';
 
 const base64Router = Router();

src/routes/basic-auth.ts → src/core/routes/basic-auth.ts

@@ -1,5 +1,5 @@
 import { Router, Response } from 'express';
-import { HttpStatusCodes } from '../utils/http.js';
+import { HttpStatusCodes } from '../../utils/http.js';
 
 const basicAuthRouter = Router();
 

src/routes/error.ts → src/core/routes/error.ts

@@ -7,7 +7,15 @@ errorRouter.all('/timeout', () => {
   return;
 });
 
-errorRouter.all('/network', (req) => {
+errorRouter.all('/network', (req, res) => {
+  if (process.env['RUNTIME'] === 'lambda') {
+    res
+      .status(400)
+      .json({
+        error: { message: 'Network error simulation is not supported in this environment.' },
+      });
+    return;
+  }
   // Intentionally destroy the connection
   req.socket.destroy();
   return;

src/routes/index.ts → src/core/routes/index.ts

@@ -1,5 +1,5 @@
 import { Router } from 'express';
-import { HttpStatusCodes } from '../utils/http.js';
+import { HttpStatusCodes } from '../../utils/http.js';
 
 const indexRouter = Router();
 

src/routes/redirect.ts → src/core/routes/redirect.ts

@@ -1,6 +1,6 @@
 import { Router } from 'express';
-import { HttpStatusCodes, RedirectStatuses } from '../utils/http.js';
-import { toSafeInteger } from '../utils/number.js';
+import { HttpStatusCodes, RedirectStatuses } from '../../utils/http.js';
+import { toSafeInteger } from '../../utils/number.js';
 
 const redirectRouter = Router();
 

src/routes/shutdown.ts → src/core/routes/shutdown.ts

@@ -1,6 +1,6 @@
 import { Router } from 'express';
 import { environment } from '../env.js';
-import { HttpStatusCodes } from '../utils/http.js';
+import { HttpStatusCodes } from '../../utils/http.js';
 
 const shutdownRouter = Router();
 

src/routes/status.ts → src/core/routes/status.ts

@@ -1,6 +1,6 @@
 import { Router } from 'express';
-import { HttpStatusCodes } from '../utils/http.js';
-import { toSafeInteger } from '../utils/number.js';
+import { HttpStatusCodes } from '../../utils/http.js';
+import { toSafeInteger } from '../../utils/number.js';
 
 const MIN_VALID_STATUS_CODE = 200;
 const MAX_VALID_STATUS_CODE = 599;

tests/ut/app.test.ts

@@ -1,5 +1,5 @@
 import request from 'supertest';
-import { app } from '../../src/app.js';
+import { app } from '../../src/adapters/express/app.js';
 
 describe('App', () => {
   describe('GET /', () => {

tests/ut/env.test.ts

@@ -11,7 +11,7 @@ describe('Environment configuration', () => {
   });
 
   const loadEnv = async () => {
-    const envModule = await import('../../src/env.js');
+    const envModule = await import('../../src/core/env.js');
     return envModule.environment;
   };
 

tests/ut/middlewares/delay.test.ts

@@ -1,6 +1,6 @@
 import { Request, Response, NextFunction } from 'express';
-import { delayMiddleware } from '../../../src/middlewares/delay.js';
-import { environment } from '../../../src/env.js';
+import { delayMiddleware } from '../../../src/core/middlewares/delay.js';
+import { environment } from '../../../src/core/env.js';
 
 describe('delayMiddleware', () => {
   let mockRequest: Partial<Request>;