Server Source code Package

AWS Lambda

AWS Lambda source for walkerOS. Works across API Gateway REST (v1), API Gateway HTTP (v2), Lambda Function URLs, and direct invocation. Auto-detects the API Gateway version, supports optional pixel tracking with a 1x1 GIF response, and exposes 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.

Where this fits

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

import { sourceLambda } from '@walkeros/server-source-aws';
import { startFlow } from '@walkeros/collector';

let handler: any;

async function init() {
  if (handler) return handler;

  const { sources } = await startFlow({
    sources: {
      lambda: {
        code: sourceLambda,
        config: {
          settings: { cors: true, healthPath: '/health' },
        },
      },
    },
    destinations: {
      // Your destinations
    },
  });

  handler = sources.lambda.push;
  return handler;
}

export const main = async (event: any, context: any) => {
  const h = await init();
  return h(event, context);
};

export { main as handler };

Bundled

Add to your flow.json sources:

"sources": {
  "lambda": {
    "package": "@walkeros/server-source-aws",
    "config": {
      "settings": {
        "cors": true,
        "healthPath": "/health"
      }
    }
  }
}

Server sources require platform-specific handlers. For containerized deployments, see Docker.

See bundled mode setup | CLI reference

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.

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
}

Out

elb({
  "name": "page view",
  "data": {
    "title": "Home"
  }
})

Lambda GET

An API Gateway v2 HTTP GET with query parameters is parsed into an elb event payload.

Event

{
  "version": "2.0",
  "requestContext": {
    "http": {
      "method": "GET",
      "path": "/collect"
    },
    "requestId": "req-456"
  },
  "rawQueryString": "e=page+view&d=%7B%22title%22%3A%22Home%22%7D",
  "isBase64Encoded": false
}

Out

elb({
  "e": "page view",
  "d": "{\"title\":\"Home\"}"
})

Lambda POST

An API Gateway v2 HTTP POST with a JSON body is converted into a walker elb event.

Event

{
  "version": "2.0",
  "requestContext": {
    "http": {
      "method": "POST",
      "path": "/collect"
    },
    "requestId": "req-123"
  },
  "body": "{\"name\":\"page view\",\"data\":{\"title\":\"Home\"}}",
  "isBase64Encoded": false
}

Out

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.

Event

{
  "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
}

Out

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
400	Rejected client input: the pipeline declared the event invalid. The body echoes the validation message, for example Event name is required
500	The pipeline failed to process a valid event, or an unexpected server fault

Invalid input is counted on collector.status.sources.<id>.rejected rather than inflating status.failed, and is logged at warn with the reason instead of as an error with a stack trace.

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' } is silently inert: without the map operator the source passes the whole scope through 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 { sources } = await startFlow({
  sources: {
    lambda: {
      code: sourceLambda,
      config: {
        settings: { cors: true },
        ingest: {
          map: {
            ip: { key: 'ip' },
            ua: { 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 genuinely 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	Supported