Cloudflare Infrastructure

This document covers our Cloudflare integration for the Heatwave project.

Overview

We use Cloudflare for:

• Edge Caching - CDN and cache purging
• Workers - Edge compute for locale redirects, R2 asset serving, and asset versioning
• Security - WAF, rate limiting, bot protection
• Tunnels - Secure connection between origin and Cloudflare (see README_CLOUDFLARED.md)
• DNS - Domain management
• Stream - Video hosting and delivery
• Access - Zero Trust access control (staging)

Zones

Environment	Domain	Zone ID	Plan
Production	warmlyyours.com	cd991c21281a518afa7a0822dca3d434	Business
Staging	warmlyyours.ws	d39acaed475782c4901d4a8e5908c1cb	Pro
Development	warmlyyours.me	4a387e118ce5ea4917eb8dc724f3e3a9	Free

API Configuration

Account ID

79b7f58cf035093b5ad11747df30369a

API Tokens

Tokens are stored in 1Password under "Cloudflare Account API Token - Heatwave - All Zones":

Field	Purpose
credential	Main API token for rules sync and zone management
stream_token	Cloudflare Stream and Images API
legacy_token	Legacy operations (deprecated)

Token Management: https://dash.cloudflare.com/79b7f58cf035093b5ad11747df30369a/api-tokens

Required Token Permissions

For full rules sync functionality, the API token needs:

Zone Permissions:

• Zone.Zone (Read)
• Zone.Zone Settings (Read/Edit)
• Zone.Firewall Services (Read/Edit)
• Zone.Zone Rulesets (Read/Edit)
• Zone.Rate Limiting (Read/Edit)
• Zone.Cache Rules (Edit)
• Zone.Transform Rules (Edit)
• Zone.Single Redirect (Edit)

Account Permissions:

• Account Rulesets (Edit)

Services

Edge Cache Utility

Location: app/services/cache/edge_cache_utility.rb

Provides cache purging functionality:

# Purge specific URLs
Cache::EdgeCacheUtility.instance.purge_url("https://www.warmlyyours.com/page")

# Purge by cache tags
Cache::EdgeCacheUtility.instance.purge_by_tags("post", "product-123")

# Purge everything (use sparingly!)
Cache::EdgeCacheUtility.instance.purge_everything(:production)

Rake Task:

mise exec -- rake edge_cache:purge_everything

Zone rulesets are managed in Terraform (HCP Terraform)

Source of truth: infra/terraform/cloudflare-zone-production/ (warmlyyours.com)
and infra/terraform/cloudflare-zone-staging/ (warmlyyours.ws) — one
cloudflare_ruleset resource per zone-owned phase: cache settings, WAF managed
overrides, custom firewall rules, rate limits, config settings, header
transforms, single redirects. Rule order and enabled state are part of the
code, so changes are PR-reviewed (HCP Terraform posts a speculative plan as a
PR check) and dashboard drift is detected on every plan.

Workflow: edit HCL → PR → review the speculative plan → merge → confirm apply in
the TFC UI (workspaces heatwave-cloudflare-zone-{production,staging},
auto-apply off). Treat the dashboard as read-only for these phases. See
infra/terraform/README.md for the workspace table and import bootstrap.

Cloudflare Rules Service (DEPRECATED for rulesets)

Location: app/services/cloudflare_rules_service.rb

The rake-based export/compare/sync (mise exec -- rake cloudflare:rules:...,
YAML exports under data/cloudflare_rules/) is superseded by the Terraform
modules above for everything rulesets-based. It remains only for the legacy
firewall_rules API (deprecated by Cloudflare itself) and ad-hoc page-rules
export until it is removed — do not use it to mutate rulesets anymore; a sync
would fight Terraform state. The bulk-redirect CSVs in data/cloudflare_rules/
are unrelated (owned by the cloudflare-redirects skill) and stay.

Cloudflare Stream API

Location: app/services/cloudflare_stream_api.rb

Manages video hosting on Cloudflare Stream:

api = CloudflareStreamApi.instance
api.get_video(cloudflare_uid)
api.enable_mp4_downloads(cloudflare_uid)

Workers

Cloudflare Workers run custom JavaScript at the edge, before requests hit the origin or cache.

Location: cloudflare-worker/

Active Workers

Worker	Config	Purpose
www-edge	wrangler-www-edge.toml	Locale redirects + R2 webpack assets + Asset versioning + Turbo debug headers

WWW Edge Worker

A combined worker that handles locale redirects, R2-backed webpack asset serving, asset versioning, and Turbo debug headers. Cache isolation for Turbo and query-variant pages is owned by zone cache rules, not the worker.

Feature 1: Turbo request handling (zone rules own the isolation)

Problem: Cloudflare uses URL as the cache key by default. But the same URL can return different content:

• Regular HTML (normal page loads)
• Turbo Stream (Accept: text/vnd.turbo-stream.html)
• Turbo Frame (with Turbo-Frame header)

Without isolation, a Turbo response could be cached and served for a regular
HTML request, breaking pages.

How it's actually handled (2026-06-12):

• Turbo Stream requests are kept out of the edge cache entirely by the
  zone cache rule "Bypass Cache Turbo Stream Request" (matches on the
  Accept: text/vnd.turbo-stream.html header). They can neither poison a
  page's entry nor be served from one.
• Turbo Frame requests intentionally share the page's cache entry: Rails
  renders the full page for frame requests (Turbo extracts the frame
  client-side), and the app's lazy frames (lead-form modals, infinite scroll)
  point at uncacheable endpoints anyway — so a frame response cached under
  the page key is byte-equivalent to the regular page.
• The worker only stamps X-Turbo-Cache-Key / Vary: Accept debug
  headers on turbo-handled responses.

An earlier worker revision set fetch cf.cacheKey to a __turbo-suffixed
URL to give Turbo responses separate cache entries. request.cf cache
settings only take precedence over zone Cache Rules
when the request_cf_overrides_cache_rules compatibility flag is active
(default-on 2025-04-02); the worker pins
compatibility_date = 2024-04-29, so that key was silently ignored. The
inert override was removed on 2026-06-12 (same incident as Feature 2 below).

Feature 2 (RETIRED): Query-sensitive HTML cache key (/reviews, /towel-warmer)

Problem: the zone cache rule "Cache Localized pages on www non paginated"
caches localized www HTML while excluding all query parameters from the
edge cache key (except page= / q[-style cases, which other rules handle).
URLs like /en-US/towel-warmer?sort=effective_price asc collapsed onto the
unsorted page's cache entry — sorting/filter-sorting appeared dead, and a
sorted/filtered origin response could even get stored under the base page's
cache key, serving sorted content to everyone for the TTL.

Old (broken) solution: the worker set fetch cf.cacheKey to the full
URL for these paths. That was silently ignored: request.cf cache settings
only override zone Cache Rules
when the request_cf_overrides_cache_rules compatibility flag is active
(default-on 2025-04-02), and the worker pins
compatibility_date = 2024-04-29 — so the "Cache Localized pages" rule kept
winning. In that flag-off state the override was also observed interacting
with the rules to store a sorted/filtered response under the base page's
stripped cache key — the poisoning above. Removed from the worker on
2026-06-12. There is no reason to reintroduce it — the cache rules below
deliver per-variant caching without it. If a worker-side cache key is ever
genuinely needed, it requires deliberately enabling that compatibility flag
(do NOT just bump the compatibility date — that activates a year of other
flags) and verifying the rule/worker precedence on staging (.ws) first.

Current solution (zone cache rules, no worker involvement): the same
pattern the page= rules already use. The "Cache Localized pages on www non
paginated" rule's expression carves out reviews/towel-warmer requests
whose query carries content-affecting params (sort/after/min_rating on
/reviews; sort on /towel-warmer), and the paired rule "Cache www
reviews/towel-warmer sort/cursor variants per full URL" caches them with
the default cache key — which includes the full query string — so each
sort variant gets its own edge entry (these are heavy pages; per-variant
caching keeps them fast). Verified live: each variant MISSes once then HITs
its own entry; the query-less base page entry is unaffected.

Maintenance invariants:

• Keep the carve-out condition in the "Cache Localized…" expression and the
  variants rule's expression identical — if they drift, drifted URLs
  either collapse onto stripped keys again (bug) or merely go uncached (safe
  but slow).
• The variants rule must stay before the "Bypass Cache Turbo Stream
  Request" / "Bypass cache for search/filter requests" rules — later cache
  rules override earlier ones, and turbo/q[ requests must keep bypassing.
• Keep the param list aligned with Www::ReviewsController and
  Www::TowelWarmersController#ALLOWED_SORTS.
• A custom include-all-query cache key on the variants rule would be cleaner
  (no carve-out needed), but the API rejects it on this plan: "not entitled
  to use the custom cache key override" (the existing exclude-all keys
  predate the entitlement change).

Paginated sorted pages (?page=2&sort=…) are cached by the "Cache Paginated
WWW pages including query string" rule under their full URL (default
cache key), so each sort variant of a page is cached separately and correctly.

Feature 3: Asset Versioning (ETag/304)

Ensures browsers re-fetch HTML when webpack assets change — without ever
touching per-user pages.

The origin owns the caching decision. Asset versioning is applied only
to HTML the origin marked cacheable: its Cache-Control must be present and
must not contain no-store, no-cache, or private. Anything else — the
cart, checkout, account, search, every per-user page — is returned
byte-for-byte untouched. The worker does not override the origin.

How it works (origin-cacheable HTML only):

1. Worker fetch()es the response, then computes a hash of
   assets-manifest.json (cached 60s at edge).
2. Checks the response's Cache-Control — if not cacheable, returns it
   untouched and stops here.
3. Otherwise attaches ETag: "manifest-<hash>" and Cache-Control: no-cache.
4. On revisit, if the browser's If-None-Match matches the current manifest
   hash, returns 304 Not Modified.
5. On deploy (manifest changes), the hash changes → browser gets fresh HTML →
   loads the new bundles.

Why this works:

• Webpack bundles carry a content hash in the filename (e.g.
  runtime.a2bed5cc.js) — they're immutable; their URLs change with content.
• HTML references those bundles via <script> tags.
• When the manifest changes the ETag changes, so the browser fetches fresh
  HTML with the new bundle URLs.
• Old bundles accumulate in the heatwave-frontend-assets-* R2 bucket (served
  same-origin by this worker), so stale HTML still works during a rollout.

Why the origin-cacheability gate matters: an earlier version stamped the
manifest ETag onto every HTML response, including /my_cart. The manifest
hash is content-independent, so the worker answered the browser's
revalidation of the cart with a 304 keyed only on the asset version —
serving a stale, pre-mutation cart even though the line item had saved at the
origin. The gate — plus removing a header-blind pre-fetch() 304 fast-path
— fixed it: the worker now always fetches the response and inspects the
origin's Cache-Control before deciding.

Route Configuration

Current Production Route:

routes = [
  { pattern = "www.warmlyyours.com/*", zone_id = "cd991c21281a518afa7a0822dca3d434" }
]

The worker catches all requests but only modifies HTML responses. Non-HTML responses (JS, CSS, images) pass through unchanged.

Note: The worker only adds the asset-version ETag to text/html responses the origin marked cacheable (see Feature 3). Non-HTML responses, and per-user HTML the origin marked no-store/no-cache/private, pass through unmodified. Static assets with content-hash filenames (e.g., runtime.a2bed5cc.js) don't need asset versioning since their URLs change when content changes.

Observability

Logging is enabled for debugging:

[observability.logs]
enabled = true
head_sampling_rate = 1
persist = true
invocation_logs = true

View logs via MCP:

# Use cloudflare-observability MCP server to query logs
# Filter by: $metadata.service = "www-edge-production"

View logs via CLI:

cd cloudflare-worker
npx wrangler tail -c wrangler-www-edge.toml --env production --format json

Worker Deployment

Prerequisites:

# Wrangler is available via npx (no global install needed)
cd cloudflare-worker

# Authenticate (first time only)
npx wrangler login

Deploy:

cd cloudflare-worker

# Deploy to staging first
npx wrangler deploy -c wrangler-www-edge.toml --env staging

# Then production
npx wrangler deploy -c wrangler-www-edge.toml --env production

Check Worker Status:

# List deployments
npx wrangler deployments list -c wrangler-www-edge.toml

# View live logs
npx wrangler tail -c wrangler-www-edge.toml --env production

Worker Removal / Rollback

Disable via Dashboard:

1. Go to Cloudflare Dashboard
2. Navigate to: Workers & Pages → www-edge-production → Settings → Routes
3. Delete or disable the routes

Rollback to Previous Version:

npx wrangler rollback -c wrangler-www-edge.toml --env production

Delete Worker Entirely:

npx wrangler delete -c wrangler-www-edge.toml --env production

Testing Workers

Test Asset Versioning (GET/HEAD):

# Check ETag and X-Asset-Version headers on HTML
curl -skI https://www.warmlyyours.com/en-US/floor-heating | grep -iE "ETag|X-Asset|X-Cache|content-type"
# Expected: etag: "manifest-HASH", x-asset-version: HASH, x-cache-status: MISS

# Test 304 response with cached ETag
curl -skI -H "If-None-Match: \"manifest-2126c2d7285e\"" https://www.warmlyyours.com/en-US
# Expected: HTTP/2 304, x-cache-status: REVALIDATED

Test Turbo Cache Key:

# Regular HTML request (no X-Turbo-Cache-Key header)
curl -skI https://www.warmlyyours.com/en-US/products/code/TRT120-01 | grep -iE "X-Turbo|X-Asset"
# Expected: x-asset-version header, NO x-turbo-cache-key

# Turbo Stream request (should have X-Turbo-Cache-Key: stream)
curl -skI -H "Accept: text/vnd.turbo-stream.html" https://www.warmlyyours.com/en-US/products/code/TRT120-01 | grep -iE "X-Turbo"
# Expected: x-turbo-cache-key: stream

# Turbo Frame request (should have X-Turbo-Cache-Key: frame-{id})
curl -skI -H "Turbo-Frame: product-section" https://www.warmlyyours.com/en-US/products/code/TRT120-01 | grep -iE "X-Turbo"
# Expected: x-turbo-cache-key: frame-product-section

Verify Non-HTML Pass-Through:

# JSON/API requests should NOT have worker-added headers
curl -skI https://www.warmlyyours.com/en-US/globals.json | grep -iE "X-Asset|X-Turbo"
# Expected: No X-Asset-Version or X-Turbo-Cache-Key headers

Dashboard Location

• Workers Overview: https://dash.cloudflare.com/79b7f58cf035093b5ad11747df30369a/workers
• Worker Analytics: Workers & Pages → www-edge-production → Analytics
• Worker Routes: warmlyyours.com zone → Workers Routes
• Observability Logs: Workers & Pages → www-edge-production → Logs

Worker Files Reference

File	Purpose
cloudflare-worker/www-edge-worker.js	Combined worker: Turbo cache key + Asset versioning
cloudflare-worker/wrangler-www-edge.toml	Worker configuration with route optimization

---

Rule Types

Rulesets (Modern)

The modern rules engine includes:

Phase	Purpose
http_request_cache_settings	Cache rules
http_request_firewall_custom	Custom WAF rules
http_request_dynamic_redirect	Redirect rules
http_response_headers_transform	Response header modifications
http_config_settings	Configuration overrides
http_ratelimit	Rate limiting

Firewall Rules (Legacy)

Classic firewall rules using expressions. Being phased out in favor of WAF Custom Rules.

Rules Sync: Production → Staging (RETIRED for rulesets)

⚠️ Do NOT run mise exec -- rake cloudflare:rules:sync* against rulesets anymore. Both
zones' rulesets are Terraform-managed (see Zone rulesets are managed in
Terraform above); a rake sync would mutate them behind Terraform's back and
show up as drift that the next apply reverts. To propagate a rule from
production to staging, port it between
infra/terraform/cloudflare-zone-production/ and …-staging/ in a PR —
adapting hostnames (warmlyyours.com → warmlyyours.ws) and plan
differences (matches regex operator requires Business — production only;
rate-limit parameters differ by plan) by hand, which the old auto-sync
half-handled anyway.

The export/compare halves (mise exec -- rake cloudflare:rules:export_all,
… cloudflare:rules:compare) remain harmless read-only tools but are
superseded by tofu plan drift detection; the whole service goes away with
the legacy firewall_rules API cleanup (follow-up in
doc/tasks/202606121035_CLOUDFLARE_RULES_FOLLOWUPS.md).

MCP Integration

Cloudflare's hosted MCP servers are available to any agent that reads the
project's committed .mcp.json (Claude Code, Cursor, Zed, …) — they are not
tied to a specific editor. See the
mcp-servers skill for how MCP
servers are wired up in this repo.

Setup: Run ./script/setup_mcp_servers.sh to populate the gitignored
.env.mcp secrets, then start (or restart) your agent so it picks up
.mcp.json.

Server	Purpose
cloudflare-observability	Debug logs and analytics
cloudflare-audit-logs	Query audit logs and reports
cloudflare-dns-analytics	DNS performance and debugging
cloudflare-graphql	Analytics data via GraphQL
cloudflare-docs	Up-to-date Cloudflare documentation

Authentication: OAuth via browser on first use.

Documentation: https://developers.cloudflare.com/agents/model-context-protocol/mcp-servers-for-cloudflare/

Tunnels (Cloudflared)

See README_CLOUDFLARED.md for tunnel setup instructions.

Production Tunnel: heatwave-app-production
Staging Tunnel: heatwave-app-staging

Cloudflare Access (Zero Trust)

Staging environment is protected by Cloudflare Access:

• Requires authentication to access *.warmlyyours.ws
• Configured in Cloudflare Zero Trust dashboard

Geo Location

We use Cloudflare's geo headers for visitor location:

# Headers available in requests:
# CF-IPCountry, CF-IPCity, CF-Region, CF-Postal-Code, etc.

Development Simulation: lib/middleware/cloudflare_geo_simulator.rb

# Test with different geos in development:
TRACK_VISITOR=y TRACK_VISITOR_PROFILE=CA-QC bin/dev

Turnstile (CAPTCHA)

Location: lib/turnstile.rb

Used for bot protection on forms.

Files Reference

File	Purpose
app/services/cache/edge_cache_utility.rb	Cache purging
app/services/cloudflare_rules_service.rb	Rules sync
app/services/cloudflare_stream_api.rb	Video streaming
lib/turnstile.rb	CAPTCHA verification
lib/middleware/cloudflare_geo_simulator.rb	Geo testing
config/initializers/cloudflare.rb	Stream/Image token config
config/initializers/cloudflare_geo_simulator.rb	Geo middleware setup
lib/tasks/cloudflare_rules.rake	Rules sync rake tasks
lib/tasks/edge_cache.rake	Cache purge rake tasks
data/cloudflare_rules/	Exported rules storage

Troubleshooting

Authentication Errors

# Check token validity
mise exec -- rake cloudflare:rules:check_permissions

If permissions fail:

1. Go to https://dash.cloudflare.com/79b7f58cf035093b5ad11747df30369a/api-tokens
2. Edit the token and add missing permissions
3. Update the token in 1Password and credentials

Cache Not Purging

1. Verify edge cache is enabled: Cache::EdgeCacheUtility.edge_cache_enabled?
2. Check zone ID is correct in zone_map
3. Test with a single URL purge first

Rules Sync Failures

Common issues:

• "not entitled" - Target zone on lower plan, rule uses unsupported operator
• "exceeded maximum" - Target zone has lower rule limits
• "request not authorized" - Missing API token permission

Tunnel Issues

# Check tunnel status
cloudflared tunnel list
cloudflared tunnel info <tunnel-name>

# Check service status
systemctl status cloudflared
journalctl -u cloudflared -f

Related Documentation

• Cloudflare API Docs
• Cloudflare Rulesets
• Cloudflare MCP Servers
• Account API Tokens