GCP Cloud Functions
The GCP Cloud Functions source is a runtime adapter for walkerOS whose push you assign directly as a Cloud Functions handler. It supports the shared event envelope including batches, a GET tracking pixel, and configurable CORS. The @walkeros/server-source-gcp package also ships sourcePubSubPull and sourcePubSubPush for ingesting from Pub/Sub topics; this page covers the Cloud Functions handler only.
The GCP Cloud Functions 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-gcp @google-cloud/functions-framework- Integrated
- Bundled
import { Source } from '@walkeros/core';
import {
sourceCloudFunction,
type SourceCloudFunction,
} from '@walkeros/server-source-gcp';
import { startFlow } from '@walkeros/collector';
import { http } from '@google-cloud/functions-framework';
const { collector } = await startFlow({
sources: {
gcp: {
code: sourceCloudFunction,
config: {
settings: { cors: true },
},
},
},
destinations: {
// Your destinations
},
});
// Plug-and-play: source.push IS the Cloud Function handler
http(
'walkerHandler',
Source.getSource<SourceCloudFunction.Types>(collector, 'gcp').push,
);Add to your flow.json sources:
"sources": {
"gcp": {
"package": "@walkeros/server-source-gcp",
"import": "sourceCloudFunction",
"config": {
"settings": {
"cors": true
}
}
}
}This bundle is for deploying to Cloud Functions. 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 | |
maxBatchSize | integer | Maximum number of events accepted in a single batch request | |
enablePixelTracking | boolean | Serve a tracking pixel for GET requests | |
timeout | integer | Request timeout in milliseconds (max: 540000 for GCP) |
Mapping
This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
Examples
POST with provenance
A POST body carrying a source map is forwarded in full, so release and trace provenance survive the crossing.
{
"method": "POST",
"body": {
"name": "page view",
"data": {
"title": "Home"
},
"source": {
"release": {
"web": "r1"
}
}
},
"headers": {
"content-type": "application/json"
}
}elb({
"name": "page view",
"data": {
"title": "Home"
},
"source": {
"release": {
"web": "r1"
}
}
})Order POST
A Cloud Function HTTP POST carrying an order payload becomes a walker order complete event.
{
"method": "POST",
"body": {
"name": "order complete",
"data": {
"id": "ORD-700",
"value": 99.99,
"currency": "EUR"
}
},
"headers": {
"content-type": "application/json"
}
}elb({
"name": "order complete",
"data": {
"id": "ORD-700",
"value": 99.99,
"currency": "EUR"
}
})POST event
A GCP Cloud Function HTTP POST with a JSON body becomes a single walker elb event.
{
"method": "POST",
"body": {
"name": "page view",
"data": {
"title": "Home",
"url": "https://example.com/"
}
},
"headers": {
"content-type": "application/json"
}
}elb({
"name": "page view",
"data": {
"title": "Home",
"url": "https://example.com/"
}
})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.
Single event
{
"name": "page view",
"data": {
"title": "Home Page",
"path": "/"
}
}Batch events
Send several events in one request with the shared envelope. See
Event Envelope for the accepted forms, the
maxBatchSize cap and the 207 partial-failure response.
{
"batch": [
{ "name": "page view", "data": { "title": "Page 1" } },
{ "name": "button click", "data": { "id": "btn1" } }
]
}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), or a batch larger than maxBatchSize |
| 405 | A method other than POST, GET (pixel) and OPTIONS, 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) |
A malformed application/json body is rejected by the Functions Framework
before the source runs: 400 with an HTML body, no CORS headers, not counted.
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 batch over maxBatchSize is answered 400
and not counted.
The source sets no body size limit of its own. The Functions Framework accepts up to 1024mb and leaves the cap to the platform: 32 MB for a 2nd gen HTTP function, 10 MB for 1st gen.
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 and forward it through the pipeline.
config.ingest must use the map operator. Keys are output field names; values are direct field paths on the request scope (no req. 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.
const { collector } = await startFlow({
sources: {
gcp: {
code: sourceCloudFunction,
config: {
settings: { cors: true },
ingest: {
map: {
// only when your load balancer sets it; otherwise leave ip unmapped
ip: { key: 'headers.x-client-ip' },
userAgent: { key: 'headers.user-agent' },
origin: { key: 'headers.origin' },
},
},
},
},
},
});Available ingest paths
| Path | Description |
|---|---|
ip | The Functions Framework's req.ip. The framework trusts every proxy, so this is the leftmost X-Forwarded-For entry, which a client can set itself. For the client IP, map a header your load balancer sets, see Client IP behind a proxy |
headers.* | HTTP headers (user-agent, origin, etc.) |
method | HTTP method |
path | Pathname, no query string |
query.* | Query parameter, repeated keys joined with , |
url | Absolute request URL, or '' when there is no host header |
body | Request body: parsed JSON (also a text/plain body that is JSON), the raw string for other text/plain, the fields of an application/x-www-form-urlencoded body, or undefined for other content types |
raw | The Functions Framework request itself |
Pub/Sub
The same @walkeros/server-source-gcp package also exports sourcePubSubPull (streaming pull subscriber) and sourcePubSubPush (HTTP webhook handler) for ingesting events from a Pub/Sub topic. See the Pub/Sub source page for full settings, lifecycle, decoders, OIDC verification, and setup reference.