Lambda HTTP Echo

A simple HTTP echo service that returns all request and response information as JSON. Deployable to AWS Lambda as a zip file or Docker container.

Thanks to inspiration from mendhak/http-https-echo, optimized for Lambda deployment. For convenience, a pre-built Docker image is available at digitalglacier/lambda-http-echo.

Features

• Echo all HTTP request details (method, headers, query params, body, etc.)
• JSON response format
• Works as Express server or Lambda function
• Docker containerized
• Lightweight (minimal dependencies)

Local Development

Prerequisites

• Node.js 22+
• npm

Setup

npm install

Run

npm start

Server runs on http://localhost:3000

Test

curl http://localhost:3000/echo
curl -X POST http://localhost:3000/test -H "Content-Type: application/json" -d '{"test": "data"}'

Docker Development

Build (development image)

docker build -f Dockerfile.dev -t http-echo:dev .

Run

docker run -p 3000:3000 http-echo:dev

Test:

curl http://localhost:3000/test

Lambda Deployment

Option 1: ZIP file deployment

1. Prepare the zip file

   npm ci --only=production
   npm install aws-serverless-express
   zip -r lambda-http-echo.zip . -x node_modules/aws-sdk\*

2. Upload to Lambda

   • AWS Console → Lambda → Create Function
   • Choose Node.js 22.x runtime
   • Upload the zip file as deployment package
   • Set handler to lambda.handler
   • Increase timeout to 30 seconds (optional)

3. Configure for HTTP

   • Add API Gateway trigger, or
   • Use Lambda function URL for direct HTTP access

Option 2: Docker image deployment

1. Build the container image

   docker build -t http-echo:latest .

2. Push to ECR

   # Create ECR repo (if not exists)
   aws ecr create-repository --repository-name http-echo --region us-east-1
   
   # Get login token
   aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com
   
   # Tag and push
   docker tag http-echo:latest <ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com/http-echo:latest
   docker push <ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com/http-echo:latest

3. Create Lambda function from image

   • AWS Console → Lambda → Create Function
   • Choose "Container image"
   • Select the image from ECR
   • Set environment variables as needed

Response Format

The echo endpoint returns JSON with this structure:

{
  "method": "GET",
  "url": "/test?param=value",
  "path": "/test",
  "query": {
    "param": "value"
  },
  "headers": {
    "host": "example.com",
    "user-agent": "curl/7.68.0",
    "content-type": "application/json"
  },
  "body": null,
  "rawBody": "",
  "cookies": {},
  "hostname": "example.com",
  "ip": "192.168.1.1",
  "baseUrl": "",
  "protocol": "https",
  "secure": true,
  "xhr": false,
  "environment": {
    "nodeEnv": "production",
    "timestamp": "2026-04-14T10:30:00.000Z",
    "uptime": 123.456
  }
}

Environment Variables

• PORT - Server port (default: 3000)
• NODE_ENV - Environment (development/production)

Project Structure

.
├── app.js           # Express application
├── lambda.js        # Lambda handler
├── package.json     # Dependencies
├── Dockerfile       # Lambda runtime image (for ECR/Lambda)
├── Dockerfile.dev   # Development image (for local testing)
└── README.md        # This file

Testing with different HTTP methods

# GET
curl http://localhost:3000/

# POST with JSON
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

# PUT with headers
curl -X PUT http://localhost:3000/ \
  -H "X-Custom-Header: value" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

# Query parameters
curl "http://localhost:3000/?key1=value1&key2=value2"

# All together
curl -X POST "http://localhost:3000/api/test?debug=true" \
  -H "Authorization: Bearer token123" \
  -H "Content-Type: application/json" \
  -d '{"message": "hello world"}'

Troubleshooting

Lambda timeout errors: Increase Lambda timeout to 30+ seconds

Docker build fails: Ensure Docker daemon is running and you have sufficient disk space

Port already in use: Change PORT environment variable

License

MIT