Cron Check Scheduler

Relevant source files

The following files were used as context for generating this wiki page:

• apps/worker/src/index.ts
• apps/worker/wrangler.jsonc
• ARCHITECTURE.md
• README.md
• packages/core/src/check.ts
• packages/core/src/config.ts

The Cron Check Scheduler is the primary data production engine of StatusBeam. Implemented as a Cloudflare Worker triggered by a Cron Trigger, it is responsible for probing configured services, analyzing their health, and persisting the results to durable storage. Unlike legacy systems that rely on best-effort GitHub Actions, this scheduler utilizes Cloudflare's native infrastructure to ensure high availability and reliable execution intervals, typically every 5 minutes.

The scheduler acts as the "Check Layer," deriving service states (Operational, Degraded, or Down) based on HTTP status codes and response times. It bridges the gap between raw external service data and the aggregated snapshots displayed on the status page. On detecting a status change, it initiates downstream actions, including fanning out notifications to channels like Slack and purging the edge cache to ensure visitors receive near-instant updates.

Sources: README.md:46-55, ARCHITECTURE.md:16-25, ARCHITECTURE.md:78-85

Core Architecture and Data Flow

The Cron Check Scheduler follows a unidirectional data flow starting from the Cloudflare Cron Trigger and ending in persistent storage and notification dispatch.

Execution Lifecycle

1. Trigger: The Cloudflare Cron Trigger fires the scheduled() handler in apps/worker/src/index.ts.
2. Configuration Loading: The worker reads the system configuration (a YAML file) stored in the config key of the KV (Key-Value) store. This configuration is validated using Zod schemas defined in the Domain Layer.
3. Probing: The worker iterates through the list of sites and services defined in the configuration, executing specific probe logic (HTTP, Statuspage, or Sentry) for each.
4. Persistence:
   • Individual check results are batch-inserted into D1 (SQLite) for long-term time-series history.
   • Aggregated summaries (SiteSummary objects) are calculated and written to a summary key in KV for fast retrieval by the display layer.
5. Side Effects: If a service's status differs from the previous snapshot, the worker asynchronously dispatches notifications and purges the Cloudflare edge cache by tag.

Sources: ARCHITECTURE.md:78-95, README.md:46-63, apps/worker/src/index.ts

Check Types and Logic

The scheduler supports multiple adapter types to determine the health of a target service. The logic for these checks resides primarily in the framework-free Domain Layer.

Check Type	Logic Description	Target Use Case
http	Fetches the URL and checks the response code and latency.	Standard web services and APIs.
statuspage	Mirrors an Atlassian Statuspage indicator or specific component.	Monitoring third-party vendors.
incidentio	Reads Statuspage-compatible JSON from incident.io pages.	Modern incident management pages.
sentry	Ingests verdicts from Sentry Uptime monitors via webhooks or API polling.	Internal services already monitored by Sentry.

Sources: README.md:144-160, packages/core/src/check.ts

Status Derivation Logic

For standard http checks, the status is derived based on the expectedStatusCodes (defaulting to 200) and the maxResponseTime (threshold for "degraded" status).

// packages/core/src/check.ts:16-25
export function deriveStatus(code: number, time: number, site: Site): CheckStatus {
  if (!site.expectedStatusCodes.includes(code)) return 'down'
  if (time > site.maxResponseTime) return 'degraded'
  return 'up'
}

Sources: packages/core/src/check.ts:16-25, README.md:135-142

Infrastructure Configuration

The scheduler's behavior is defined in apps/worker/wrangler.jsonc. This configuration binds the Worker to the necessary Cloudflare primitives.

Bindings and Schedule

The Worker requires access to D1 for history and KV for snapshots. It also includes an upgrade path for Cloudflare Queues to handle reliable notification delivery.

// apps/worker/wrangler.jsonc
{
  "name": "statusbeam-worker",
  "triggers": {
    "crons": [ "*/5 * * * *" ]
  },
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "statusbeam",
      "database_id": "REPLACE_WITH_D1_DATABASE_ID"
    }
  ],
  "kv_namespaces": [
    {
      "binding": "STATUS_KV",
      "id": "REPLACE_WITH_KV_NAMESPACE_ID"
    }
  ]
}

Sources: apps/worker/wrangler.jsonc, ARCHITECTURE.md:37-43

Summary of Significant Components

Component	Responsibility	Source Reference
scheduled()	The entry point for Cron Triggers.	apps/worker/src/index.ts
checkSite()	Executes the probe and returns a CheckResult.	packages/core/src/check.ts
writeSummary()	Aggregates D1 data into a KV snapshot.	apps/worker/src/index.ts
dispatchNotifications()	Handles Slack and Webhook alerts.	apps/worker/src/notify.ts

The Cron Check Scheduler ensures that StatusBeam remains configuration-independent at build time; it reads all site definitions from KV at runtime, allowing the same worker code to be used across different deployments.

Sources: ARCHITECTURE.md:80-90, ARCHITECTURE.md:112-117