RSS and Atom Feeds

Relevant source files

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

• packages/core/src/feed.ts
• apps/web/src/lib/feed.ts
• packages/core/src/feed.test.ts
• ARCHITECTURE.md
• README.md
• apps/web/CHANGELOG.md

StatusBeam provides automated incident-history feeds in both RSS 2.0 and Atom 1.0 formats. These feeds allow users to subscribe to status updates and incident reports using standard news aggregators. The system generates these feeds dynamically at the edge, utilizing the same Cloudflare KV data store as the main status page to ensure consistency and high performance.

The feed system is integrated into the "Display Layer" of the architecture, acting as a read-only consumer of the snapshot data produced by the check Worker. It supports instant cache invalidation via Cache-Tag headers, ensuring that feed subscribers receive updates the moment a service status flips or an incident update is recorded.

Sources: ARCHITECTURE.md:27-37, README.md:195-200, apps/web/src/lib/feed.ts:13-20

Architecture and Data Flow

The feed generation logic is partitioned into a framework-free domain layer within packages/core and a delivery layer within apps/web. The core package handles the XML construction and incident sorting, while the web application handles the HTTP response and edge caching.

Key Components and Logic

Feed Metadata and Configuration

The generation process requires a FeedMeta object, which contains essential site information derived from the incoming request origin and configuration stored in KV.

Field	Description	Source
name	The display name of the status page (e.g., "statusbeam Demo").	packages/core/src/feed.ts:12
siteUrl	Absolute origin of the status page without a trailing slash.	packages/core/src/feed.ts:14
feedUrl	Absolute URL of the feed document itself for self-referencing.	packages/core/src/feed.ts:16
now	Build time in milliseconds; used for deterministic testing.	packages/core/src/feed.ts:21

Sources: packages/core/src/feed.ts:11-22

Incident Sorting and Formatting

Feeds are ordered by the most recent activity first. The incidentUpdatedAt function determines the sort key by checking for the latest update, falling back to resolvedAt, and finally startedAt.

Content Generation

Incident updates are rendered as an HTML blob within the feed. The incidentContentHtml function formats updates in reverse chronological order, matching the layout used by industry standards like Statuspage.io.

• State Labels: Updates include human-readable labels: Investigating, Identified, Monitoring, and Resolved.
• Time Formatting: Timestamps are formatted as Mon DD, YYYY - HH:MM UTC using stable UTC getters.
• XML Escaping: The system applies double-escaping to the HTML content to ensure well-formed XML while preserving literal characters like < or & in the rendered output.

Sources: packages/core/src/feed.ts:27-60, packages/core/src/feed.ts:96-108, packages/core/src/feed.test.ts:78-90

API Endpoints and Caching

The feeds are served through a shared handler that manages response headers and content types.

Endpoint	Content-Type	Purpose
/feed.atom	application/atom+xml	Primary Atom 1.0 feed.
/feed.rss	application/rss+xml	Primary RSS 2.0 feed.
/history.atom	application/atom+xml	Alias for Atom feed.
/history.rss	application/rss+xml	Alias for RSS feed.

Edge Caching and Invalidation

Feeds are cached at the edge using Cloudflare Workers Cache with a s-maxage of 60 seconds and a stale-while-revalidate window of 600 seconds.

The handler emits a Cache-Tag header containing the standard status-page tag and unique tags for every site mentioned in the incidents. This allows the Worker to perform a targeted purge-by-tag whenever a status change occurs, providing near-instant updates to feed readers.

Sources: apps/web/src/lib/feed.ts:6-46, README.md:275-285, ARCHITECTURE.md:109-117

Robustness and Security

The feed system implements several guards to prevent crashes or malformed output from invalid data in the KV store:

• Nullish Handling: The escapeXml function converts null or undefined values to empty strings instead of throwing TypeErrors.
• Date Fallbacks: Unparseable timestamps fall back to the Unix epoch (1970-01-01), ensuring stable sorting even with corrupt data.
• Tag URI Stability: Unique identifiers use a stable tag: URI scheme (e.g., tag:demo.statusbeam.dev,2005:Incident/2) to prevent duplicate entries in RSS readers when URLs change.

Sources: packages/core/src/feed.ts:41-55, packages/core/src/feed.ts:118-128, packages/core/src/feed.test.ts:127-145

Summary: StatusBeam's RSS and Atom feeds provide a reliable, edge-cached history of service incidents. By centralizing logic in the core package and leveraging Cloudflare's tag-based cache purging, the system delivers timely updates to subscribers while maintaining high resilience and performance.