AWS Lambda
The AWS Lambda source for walkerOS works across API Gateway REST (v1), API Gateway HTTP (v2) and Lambda Function URLs. It detects the API Gateway version automatically, supports optional pixel tracking with a 1x1 GIF response, and has a built-in health check endpoint. The @walkeros/server-source-aws package also ships sourceSqs for ingesting from SQS queues; this page covers the Lambda handler only.
The AWS Lambda source is a server source in the walkerOS flow:
It receives events via HTTP and forwards them to your destinations.
Installation
npm install @walkeros/server-source-aws- Integrated
- Bundled
import { Source } from '@walkeros/core';
import { startFlow } from '@walkeros/collector';
import { sourceLambda, type SourceLambda } from '@walkeros/server-source-aws';
let handler: SourceLambda.Push | undefined;
async function setup(): Promise<SourceLambda.Push> {
if (handler) return handler;
const { collector } = await startFlow({
sources: {
lambda: {
code: sourceLambda,
config: {
settings: {
cors: true,
enablePixelTracking: true,
healthPath: '/health',
},
},
},
},
destinations: {
// Your destinations
},
});
handler = Source.getSource<SourceLambda.Types>(collector, 'lambda').push;
return handler;
}
export const main: SourceLambda.Push = async (event, context) => {
const h = await setup();
return h(event, context);
};
export { main as handler };Add to your flow.json sources:
"sources": {
"lambda": {
"package": "@walkeros/server-source-aws",
"import": "sourceLambda",
"config": {
"settings": {
"cors": true,
"healthPath": "/health"
}
}
}
}This bundle is for deploying to AWS Lambda. The walkerOS runtime (runneros, the walkeros/flow image) serves only sources with an HTTP handler, such as the Express source: under it this source receives no requests, and every request answers 503.
Configuration
This source uses the standard source config wrapper (consent, data, env, id, ...). For the shared fields see source configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
cors | boolean | object | CORS configuration: false = disabled, true = allow all origins, object = custom configuration | |
timeout | integer | Request timeout in milliseconds (max: 900000 for Lambda) | |
enablePixelTracking | boolean | Enable GET requests with 1x1 transparent GIF response for pixel tracking | |
maxBatchSize | integer | Maximum number of events accepted in a single batch request | |
healthPath | string | Health check endpoint path (e.g., /health) |
Mapping
This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
Examples
API Gateway v1 POST
A REST API Gateway v1 POST request with a JSON body is converted into a walker elb event.
{
"httpMethod": "POST",
"path": "/collect",
"requestContext": {
"requestId": "req-789",
"identity": {
"sourceIp": "203.0.113.42"
}
},
"queryStringParameters": null,
"body": "{\"name\":\"page view\",\"data\":{\"title\":\"Home\"}}",
"isBase64Encoded": false
}elb({
"name": "page view",
"data": {
"title": "Home"
}
})Lambda GET
An API Gateway v2 HTTP GET with name and data[...] query parameters becomes a single walker elb event.
{
"version": "2.0",
"requestContext": {
"http": {
"method": "GET",
"path": "/collect"
},
"requestId": "req-456"
},
"rawQueryString": "name=page+view&data%5Btitle%5D=Home",
"isBase64Encoded": false
}elb({
"name": "page view",
"data": {
"title": "Home"
}
})Lambda POST
An API Gateway v2 HTTP POST with a JSON body is converted into a walker elb event.
{
"version": "2.0",
"requestContext": {
"http": {
"method": "POST",
"path": "/collect"
},
"requestId": "req-123"
},
"body": "{\"name\":\"page view\",\"data\":{\"title\":\"Home\"}}",
"isBase64Encoded": false
}elb({
"name": "page view",
"data": {
"title": "Home"
}
})Lambda POST with provenance
A POST body carrying a source map is forwarded in full, so release and trace provenance survive the crossing.
{
"version": "2.0",
"requestContext": {
"http": {
"method": "POST",
"path": "/collect"
},
"requestId": "req-321"
},
"body": "{\"name\":\"page view\",\"data\":{\"title\":\"Home\"},\"source\":{\"release\":{\"web\":\"r1\"}}}",
"isBase64Encoded": false
}elb({
"name": "page view",
"data": {
"title": "Home"
},
"source": {
"release": {
"web": "r1"
}
}
})Request format
The event name field is name. Every other field of the body is forwarded to
the collector as-is, so source (carrying release and trace provenance)
rides through instead of being dropped.
{
"name": "page view",
"data": {
"title": "Home Page",
"path": "/"
}
}Responses
| Status | Meaning |
|---|---|
| 200 | Event processed, or failed for a reason a resend cannot fix (see below) |
| 400 | Rejected client input: the pipeline declared the event invalid (the body echoes the validation message, for example Event name is required), a POST without a body (Request body is required), or a batch larger than maxBatchSize |
| 405 | Method not allowed, or GET with enablePixelTracking: false |
| 500 | The pipeline failed to process a valid event for a reason a resend could fix (the body is Event was not processed), or an unexpected server fault (Internal server error) |
| 207 | Batch request where at least one event was invalid or failed for a reason a resend could fix. The body carries per-index errors |
Every request to healthPath (default /health) answers { status: 'ok', ... }, whatever the method.
A failed event is acknowledged or retried by one rule on every server source: see Producer acknowledgement.
Invalid input is counted on collector.status.sources.<id>.rejected rather than
inflating status.failed, and is logged at error with the reason and no stack
trace, once per source and minute. A POST without a body and a batch over
maxBatchSize are answered 400 and not counted.
The source sets no body size limit of its own; Lambda caps a synchronous request payload at 6 MB.
settings.timeout has no effect today: a request whose push takes longer still
waits for it and answers as above.
Ingest metadata
Extract request metadata from Lambda events and forward it through the pipeline.
config.ingest must use the map operator. Keys are output field names; values
are paths on the shared request scope, with no prefix. A
bare object like { ip: 'ip' } has no operator: walkeros validate and the
bundle reject it, and if it still runs, the collector logs one ERROR line
(mapping value has no operator) and no field is extracted.
API Gateway v1 and v2 produce an identical scope. The version specific envelopes are normalized away, so one mapping serves both.
const { collector } = await startFlow({
sources: {
lambda: {
code: sourceLambda,
config: {
settings: { cors: true },
ingest: {
map: {
ip: { key: 'ip' },
userAgent: { key: 'headers.user-agent' },
path: { key: 'path' },
},
},
},
},
},
});Available ingest paths
| Path | Description |
|---|---|
method | Uppercase HTTP method, both gateway versions |
url | Absolute request URL, when a host header is present |
path | Pathname, no query string |
query.<name> | Query parameter, repeated keys joined with , |
headers.<name> | Header, lowercased name, repeated values joined with , |
body | Parsed body, base64 decoded when the event says so |
ip | Client IP, from either gateway version's request context |
raw | The Lambda event itself |
Anything version specific stays reachable through raw, for example
raw.requestContext.stage.
Supported platforms
| Platform | Status |
|---|---|
| API Gateway REST API (v1) | Supported |
| API Gateway HTTP API (v2) | Supported |
| Lambda Function URLs | Supported |
| Direct Lambda invocation | Only with an API Gateway v1 or v2 shaped event |