Shields.io Badges
Relevant source files
The following files were used as context for generating this wiki page:
StatusBeam provides a dedicated API surface for generating dynamic status badges compatible with the Shields.io endpoint protocol. Instead of generating images directly at the edge, StatusBeam emits a standardized JSON contract that Shields.io consumes to render SVG badges. This ensures high performance, minimal resource usage on the Cloudflare platform, and instant updates via edge cache invalidation.
These badges allow users to embed real-time system status, uptime percentages, and response times directly into external documentation, GitHub READMEs, or third-party dashboards. The badges are served from the same edge-cached KV snapshot as the main status page, ensuring they never lag behind the reported status.
Sources: README.md:213-221, ARCHITECTURE.md:144-147, packages/core/src/badge.ts:4-9
Architecture and Data Flow
The badge system is implemented within the packages/core domain layer and exposed via the apps/web interface layer. The architecture follows a "Worker-Writes, Web-Reads" pattern where the check engine aggregates data into a KV store, and the badge API retrieves this data to generate the Shields.io JSON response.
Data Request Lifecycle
The following sequence diagram illustrates how a badge request is processed from a visitor's browser through Shields.io to the StatusBeam edge deployment.
The system leverages Cloudflare Workers Cache to collapse concurrent requests and provide near-instant updates through tag-based purging when a service status changes.
Sources: ARCHITECTURE.md:105-115, README.md:214-216, DEPLOYMENT.md:113-118
Badge Types and Endpoints
StatusBeam supports several badge types, covering overall system health and granular per-site metrics.
| Badge Type | Endpoint | Description |
|---|---|---|
| Overall Status | /api/badge.json | Rolled-up status of all monitored services. |
| Site Status | /api/badge/<slug>.json | Current status of a specific site (up, degraded, or down). |
| Site Uptime | /api/badge/<slug>/uptime.json | Uptime ratio for a period (day, week, month). |
| Response Time | /api/badge/<slug>/response-time.json | Current response time in milliseconds. |
Sources: README.md:223-231, packages/core/src/badge.ts:140-199
Uptime Period Configuration
The uptime badge supports a period query parameter (defaulting to month). The logic maps the requested period to specific fields within the SiteSummary data structure stored in KV.
export type UptimePeriod = 'day' | 'week' | 'month'
function uptimeDisplay(site: SiteSummary, period: UptimePeriod): string {
switch (period) {
case 'day':
return site.uptimeDay ?? 'n/a'
case 'week':
return site.uptimeWeek ?? 'n/a'
case 'month':
return site.uptimeMonth ?? 'n/a'
}
}
Sources: packages/core/src/badge.ts:25-25, packages/core/src/badge.ts:117-128
Visual Mapping Logic
StatusBeam maps internal severity levels and metrics to specific Shields.io colors and messages.
Severity and Status Mapping
The severityColor function translates the service status into standard health indicators.
| Status | Severity | Badge Color |
|---|---|---|
up | Operational | brightgreen |
degraded | Degraded | yellow |
down | Major Outage | red |
| N/A | Maintenance | blue |
Sources: packages/core/src/badge.ts:32-47, packages/core/src/badge.test.ts:28-34
Uptime Color Logic
Uptime percentages are parsed from display strings back to ratios (0..1) to determine the appropriate badge color.
Response Time Color Logic
Response time color thresholds use an inverted scale where lower values result in "healthier" colors. Values under 200ms are marked brightgreen, while values exceeding 4000ms transition to red. If a site is down, the response time badge message is forced to "down" with a red color, rather than reporting 0ms.
Sources: packages/core/src/badge.ts:81-98, packages/core/src/badge.ts:188-198
Data Structures
The core contract for all badge responses is the ShieldsEndpoint interface.
export interface ShieldsEndpoint {
schemaVersion: 1
label: string
message: string
color: string
}
Sources: packages/core/src/badge.ts:11-18
Key Functions Reference
| Function | Purpose |
|---|---|
statusBadge(site) | Generates a badge for a specific site status. |
overallBadge(summary) | Aggregates all site statuses and returns the worst-case status. |
uptimeBadge(site, period) | Returns the uptime percentage for a given window. |
responseBadge(site) | Returns the response time formatted as <n>ms. |
parseUptimePercent(display) | Utility to convert strings like "99.98%" to 0.9998. |
Sources: packages/core/src/badge.ts:131-199, packages/core/src/badge.test.ts:84-142
Summary
Shields.io Badges in StatusBeam provide a standardized, high-performance way to export status data to external platforms. By utilizing a JSON-based contract rather than server-side image generation, the system remains lightweight and perfectly suited for Cloudflare's edge environment. The tight integration with the KV snapshot and the edge cache tagging system ensures that these badges provide accurate, real-time information with minimal latency.
Sources: ARCHITECTURE.md:144-147, README.md:213-221