Skip to main content
Ask your AI
Server Source code Package

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.

Where this fits

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
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,
);

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​

PropertyTypeDescriptionMore
corsboolean | objectCORS configuration: false = disabled, true = allow all origins, object = custom configuration
maxBatchSizeintegerMaximum number of events accepted in a single batch request
enablePixelTrackingbooleanServe a tracking pixel for GET requests
timeoutintegerRequest 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.

Event
{
  "method": "POST",
  "body": {
    "name": "page view",
    "data": {
      "title": "Home"
    },
    "source": {
      "release": {
        "web": "r1"
      }
    }
  },
  "headers": {
    "content-type": "application/json"
  }
}
Out
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.

Event
{
  "method": "POST",
  "body": {
    "name": "order complete",
    "data": {
      "id": "ORD-700",
      "value": 99.99,
      "currency": "EUR"
    }
  },
  "headers": {
    "content-type": "application/json"
  }
}
Out
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.

Event
{
  "method": "POST",
  "body": {
    "name": "page view",
    "data": {
      "title": "Home",
      "url": "https://example.com/"
    }
  },
  "headers": {
    "content-type": "application/json"
  }
}
Out
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​

StatusMeaning
200Event processed, or failed for a reason a resend cannot fix (see below)
400Rejected 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
405A method other than POST, GET (pixel) and OPTIONS, or GET with enablePixelTracking: false
500The 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​

PathDescription
ipThe 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.)
methodHTTP method
pathPathname, no query string
query.*Query parameter, repeated keys joined with ,
urlAbsolute request URL, or '' when there is no host header
bodyRequest 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
rawThe 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.

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)