url-proxy-function

Run a local HTTP server that forwards incoming requests to your own AWS Lambda–style handler function. It packages each request into an API Gateway HTTP API v2–like event and returns your handler's response back to the client.

Features

• Lambda-style event: Provides queryStringParameters, headers, rawQueryString, rawPath, and requestContext.http.
• UUID context: Supplies requestContext.requestId and context.awsRequestId as UUIDv4 values.
• Headers passthrough: Applies any headers returned by your handler to the HTTP response.
• .env support: Automatically loads a .env file from the current working directory if present.
• Binds to 0.0.0.0: Accessible from your local network by default.

---

Installation

# Using npx (no install)
npx url-proxy-function ./test.js

# Or install globally
npm i -g url-proxy-function
url-proxy-function ./test.js

Node.js 16+ recommended.

---

Quick start

1. Create a file with an async handler (default export name: handler).

// test.js
exports.handler = async (event, context) => {
  // Return any serializable object as body; Express will JSON-encode it
  return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json' },
    body: { ok: true, method: event.requestContext.http.method, path: event.rawPath },
  }
}

2. Start the local proxy server:

url-proxy-function ./test.js -p 10808
# started on http://0.0.0.0:10808

3. Call it from a client:

curl "http://localhost:10808/hello?foo=bar"
# {"ok":true,"method":"GET","path":"/hello"}

---

CLI

url-proxy-function [-f handlerName] [-p port] test_file

• test_file: Path to a .js file exporting your async handler.
• -f handlerName: Optional function name to invoke. Defaults to handler.
• -p port: Optional port. Defaults to 10808.

Environment:

• Loads .env from the current working directory if it exists.
• Enable verbose logs with DEBUG=url-proxy-function*.

Examples:

# Use a custom handler name and port
url-proxy-function ./my-func.js -f myHandler -p 3000

# With DEBUG logging
DEBUG=url-proxy-function* url-proxy-function ./test.js

---

Handler contract

Your handler must be an async function with the signature:

async function handler(event, context) { /* ... */ }

Return an object shaped like API Gateway responses:

return {
  statusCode: 200,              // number (required)
  headers: { 'Content-Type': 'application/json' }, // optional
  body: { any: 'serializable value' } // string or object; objects are JSON-encoded by Express
}
``;

Notes:
- If `headers` are present, they are set on the HTTP response as-is.
- If `body` is an object, Express will serialize it as JSON. For strict Lambda parity, you can `JSON.stringify` yourself (see below).

---

## Event mapping (Express → Lambda-like)

On each request, the proxy constructs an event similar to API Gateway HTTP API (v2):

```js
{
  queryStringParameters: { [key: string]: string },
  headers: { [name: string]: string },
  rawQueryString: string,   // e.g. "?foo=bar&x=1"
  rawPath: string,          // e.g. "/users/123"
  requestContext: {
    http: { method: string, path: string },
    requestId: string       // uuid v4
  }
}

Query parameters:

• Single-value params become strings.
• Multi-value params are joined with commas (e.g., ?a=1&a=2 → "a": "1,2").

context argument:

{ awsRequestId: string } // uuid v4

---

Examples

1) Convenience (object body)

// test.js
exports.handler = async (event) => {
  return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json' },
    body: { echo: event.queryStringParameters },
  }
}

2) AWS-compatible (string body)

// test.js
exports.handler = async (event) => {
  return {
    statusCode: 200,
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ echo: event.queryStringParameters }),
  }
}

---

Behavior details

• Binds to 0.0.0.0 so you can access from your LAN: http://<your-ip>:<port>
• Logs basic request lines (method and path) to stdout.
• If the specified handler function is not found or not async, the process exits with a non-zero code.

---

Development

git clone https://github.com/aj-sandbox/url-proxy-function
cd url-proxy-function
npm install

# Run with auto-reload during development
DEBUG=url-proxy-function* npx nodemon index.js -- ./test.js -f handler -p 10808

Formatting:

npm run format

---

License

ISC