Edge Caching & Purge-by-Tag
Relevant source files
The following files were used as context for generating this wiki page:
Edge Caching & Purge-by-Tag is a core performance and reliability feature of StatusBeam that utilizes Cloudflare Workers Cache to serve status pages and API responses with near-zero latency. By offloading requests to Cloudflare's tiered edge cache, the system ensures that visitor traffic does not hammer the underlying D1 database or KV store, allowing the status page to remain resilient even during high-traffic events or infrastructure outages.
The mechanism employs a "Purge-on-Change" strategy. While pages are cached with a standard Time-to-Live (TTL), any detected status change in the monitoring Worker triggers an immediate, targeted invalidation of specific cache tags. This ensures that updates are near-instant and not strictly bound by the Cache-Control TTL, fixing a common lag issue found in previous-generation status generators.
Sources: ARCHITECTURE.md:10-15, README.md:105-115
Architecture and Data Flow
The edge caching system relies on a shared contract between the Display Layer (Astro web app) and the Check Layer (Cron Worker). The Display Layer tags outgoing responses with specific metadata, while the Check Layer acts as the orchestrator for invalidation when service states transition.
Cache Tag Synchronization
To prevent architectural drift, StatusBeam uses shared cache tag definitions. Both the emission side (Web headers) and the purge side (Worker) import these constants to ensure they are targeting the same cache keys.
The diagram shows the decoupled nature of the cache lifecycle, where the Worker invalidates what the Web layer has previously tagged.
Sources: ARCHITECTURE.md:120-135, README.md:65-85
Implementation Details
Cache-Tag Emission
The Astro site (apps/web) renders pages at the edge and attaches a Cache-Tag header to every response. These tags are granular:
- Global Tag: A general tag like
status-pagefor the entire dashboard. - Per-Site Tags: Specific tags like
status-site-<slug>for individual component pages or API endpoints.
This granularity allows the system to purge only the affected service's badges or API routes rather than the entire global cache if unnecessary.
Sources: ARCHITECTURE.md:200-205, README.md:315-325
The Purge Loop
When the Cron Worker detects a status difference between the current run and the previous snapshot, it executes purgeStatusCache. This function performs a REST call to the Cloudflare API's purge_cache endpoint using the Cache-Tag associated with the changed service slugs.
| Component | Responsibility | Relevant Files |
|---|---|---|
| Check Worker | Detects change, POSTs to Cloudflare API | apps/worker/src/index.ts |
| Web App | Emits Cache-Control and Cache-Tag | apps/web/src/lib/page.ts, apps/web/src/lib/api.ts |
| Cloudflare Edge | Stores response, handles tag-based invalidation | N/A (Infrastructure) |
Sources: ARCHITECTURE.md:130-135, DEPLOYMENT.md:125-135
Configuration and Secrets
The purge mechanism is optional but highly recommended for "instant" updates. If the required secrets are missing, the system gracefully falls back to TTL-based expiration (defaulting to 60 seconds).
Required Secrets for Check Worker
To enable Purge-by-Tag, the following secrets must be set via wrangler secret:
CF_API_TOKEN: An API token with the Cache Purge permission.CF_ZONE_ID: The Cloudflare Zone ID serving the status page.
bunx wrangler secret put CF_API_TOKEN --config wrangler.worker.jsonc
bunx wrangler secret put CF_ZONE_ID --config wrangler.worker.jsonc
Sources: DEPLOYMENT.md:125-135, README.md:320-330
Performance Benefits
By utilizing Workers Cache with Purge-by-Tag, StatusBeam achieves:
- Request Collapsing: Concurrent requests for the same status page are collapsed into a single fetch to the backend (D1/KV).
- Stale-While-Revalidate: The edge can serve slightly stale content while fetching an update in the background, ensuring zero-latency for the end user.
- Resilience: Because the page is rendered at the edge and cached, it can survive outages of the primary infrastructure it is monitoring.
- No Rate Limits: Unlike systems that call external APIs (like GitHub) from the browser, StatusBeam's edge caching ensures the browser only ever communicates with the Cloudflare-native store.
Sources: README.md:25-35, ARCHITECTURE.md:155-165
Summary
Edge Caching & Purge-by-Tag transforms StatusBeam from a simple generator into a high-performance monitoring platform. By leveraging Cloudflare's tiered cache and specific tag invalidation, the system provides a real-time feel for status updates while maintaining the efficiency of static-first delivery. This architecture ensures the status page remains functional and fast precisely when it is needed most—during service instability.