Cloudflare Proxy Worker

The Cloudflare Proxy Worker is an open source reference implementation of the MonetizationOS proxy built on the Cloudflare Workers runtime.

View on GitHub

Environment variables

All variables are set as Cloudflare Worker bindings in wrangler.jsonc, or in a .dev.vars.local file for local development.

Variable	Required	Description
`MONETIZATION_OS_SECRET_KEY`	Yes	Your MonetizationOS secret key. Used to authenticate Surface Decision API requests and to derive the environment prefix for custom endpoint routing.
`ORIGIN_URL`	Yes	The base URL of your origin server. All non-endpoint requests are proxied here.
`SURFACE_SLUG`	Yes	The MonetizationOS surface to evaluate for every HTML request.
`AUTHENTICATED_USER_JWT_COOKIE_NAME`	Yes	Cookie name containing the authenticated user's JWT.
`ANONYMOUS_SESSION_COOKIE_NAME`	Yes	Cookie name for anonymous session identifiers.
`MONETIZATION_OS_HOST`	No	Override the MonetizationOS API host. Defaults to `https://api.monetizationos.com`.
`MONETIZATION_OS_ENDPOINTS_PREFIX`	No	URL prefix for custom MOS endpoint routing. Defaults to `/mos-endpoints/`.
`INJECT_SCRIPT_URL`	No	If set, a `<script>` tag pointing to this URL is appended to `<head>` on every HTML response after component transforms.

Requests whose path begins with the MONETIZATION_OS_ENDPOINTS_PREFIX (default /mos-endpoints/) are forwarded directly to the MonetizationOS API as Endpoint Workflow requests. The remaining pipeline stages are skipped.

The environment prefix is extracted from MONETIZATION_OS_SECRET_KEY to target the correct environment:

/mos-endpoints/my-route → https://api.monetizationos.com/api/v1/envs/{env}/endpoints/my-route

Cloudflare request context

When calling the Surface Decision API, the worker passes request.cf — Cloudflare's incoming request properties — alongside the identity and path. This gives Surface Workflows access to request geolocation, device, network, and bot information for advanced targeting and personalization.

HTML transformation with HTMLRewriter

Component behaviors use Cloudflare's streaming HTMLRewriter API to apply CSS-selector-targeted mutations without buffering the full response body in memory.

Each component behavior from the Surface Decision response is registered as a selector handler before the stream is transformed:

htmlRewriter.on(cssSelector, new ContentElementHandler(componentBehavior.content));

CSS selector limitations

Selectors using :last-child are not supported by HTMLRewriter and are silently skipped.
All other standard CSS selectors supported by HTMLRewriter work as expected.

Script injection

If INJECT_SCRIPT_URL is set, the worker appends the following to <head> after all component transforms:

<script src="{INJECT_SCRIPT_URL}" async defer></script>

Caching behavior

The worker sets Cache-Control: no-store on all HTML responses during the link-rewriting stage. This prevents CDN or browser caching of personalized, per-user responses. Non-HTML responses passed through unmodified retain whatever cache headers the origin returned.

Error handling

All processing after the initial origin fetch is wrapped in a try/catch. On any unhandled error, the worker logs to console.error and returns the original origin response unmodified. This ensures your site stays available if the MonetizationOS API is unreachable or a workflow errors.