# How CodexBar's Status Polling System Detects Provider Incidents

> Learn how CodexBar's status polling system detects provider incidents using a hierarchical fallback strategy across Incident.io Statuspage.io and Google Workspace to display the most severe outage.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: internals
- Published: 2026-07-08

---

**CodexBar detects provider incidents by polling multiple status page formats—Incident.io, Statuspage.io, and Google Workspace—using a hierarchical fallback strategy that ranks severity indicators to surface the worst outage in the macOS menu bar.**

The CodexBar macOS menu bar application (available at steipete/CodexBar) continuously monitors the health of AI providers through a robust status polling system. This system aggregates incident data from disparate status page formats to provide real-time visibility into service disruptions. The implementation centers on the `UsageStore` class in `UsageStore+Status.swift`, which orchestrates URL construction, HTTP fetching, and payload parsing.

## Architecture of the Status Polling System

The polling system operates through a three-phase pipeline implemented in `UsageStore.fetchStatus` and `UsageStore.fetchStatusSummary`.

### Step 1: Building the Status URL

Each provider declares a base URL (such as `https://status.openai.com`). The system appends format-specific paths including [`/api/v2/status.json`](https://github.com/steipete/CodexBar/blob/main//api/v2/status.json), [`/api/v2/summary.json`](https://github.com/steipete/CodexBar/blob/main//api/v2/summary.json), `/proxy/<host>` for Incident.io feeds, or Google Workspace's [`incidents.json`](https://github.com/steipete/CodexBar/blob/main/incidents.json). This URL construction logic resides in `UsageStore.fetchStatus` and `UsageStore.fetchStatusSummary` at lines 48-55 of `UsageStore+Status.swift`.

### Step 2: HTTP Fetch with Timeout

A shared `ProviderHTTPClient.shared` instance performs GET requests on background tasks with a **10-second timeout**. This transport layer is injected via the parameter `transport: any ProviderHTTPTransport = ProviderHTTPClient.shared` to ensure consistent networking behavior across all status checks.

### Step 3: Parsing Multiple Payload Formats

The response decoder branches based on the provider type, handling three distinct JSON schemas. All parsing runs **off the main actor** using `@concurrent nonisolated` functions to maintain UI responsiveness.

## Supported Status Page Formats

### Incident.io Grouped Feeds

For Incident.io endpoints accessed via `https://<host>/proxy/<host>`, the `parseIncidentIOSummary` function (lines 40-64 in `UsageStore+Status.swift`) extracts a hierarchy of components. It computes the worst-case indicator per group using `indicatorRank` to determine the overall `ProviderStatus`.

### Classic Statuspage.io

Standard Statuspage.io implementations expose [`summary.json`](https://github.com/steipete/CodexBar/blob/main/summary.json) and optional [`components.json`](https://github.com/steipete/CodexBar/blob/main/components.json). The `parseStatuspageStatus` function (lines 65-92) reads the top-level indicator and description, while `parseStatuspageComponents` (lines 93-146) builds the component list from the detailed endpoint.

### Google Workspace Incident Tracking

For Google Workspace-based providers (Google Docs, Slides, etc.), `fetchWorkspaceStatus(productID:)` (lines 53-60) retrieves a large JSON array. The `parseGoogleWorkspaceStatus` function (lines 70-99) filters incidents by product ID, selects the most severe active incident, and maps the `status`/`severity` fields to a `ProviderStatusIndicator`.

## Severity Ranking and UI Integration

The system uses **indicator ranking** (`indicatorRank`) to ensure critical outages dominate the UI banner. When `fetchStatusSummary` executes, it attempts the Incident.io proxy first (lines 100-119), then falls back to classic Statuspage.io endpoints (lines 122-138) if the initial request fails.

The resulting `ProviderStatus` is stored in `UsageStore` and rendered by `StatusItemController+Menu.swift`, which updates the menu bar indicator and tooltip. The date formatter is shared and lock-protected through `StatusISO8601FormatterBox` to avoid repeated allocations during high-frequency polling cycles.

## Implementation Examples

### Fetching a Provider's Status

```swift
import CodexBar

let baseURL = URL(string: "https://status.openai.com")!
Task {
    do {
        // Returns (overall status, optional component array)
        let (status, components) = try await UsageStore.fetchStatusSummary(from: baseURL)
        print("🟢 Indicator:", status.indicator)          // e.g. .operational / .majorOutage
        print("ℹ️ Description:", status.description ?? "–")
        if let comps = components {
            comps.forEach { print("\($0.name): \($0.indicator)") }
        }
    } catch {
        print("Failed to fetch status:", error)
    }
}

```

This example uses `fetchStatusSummary` which attempts the Incident.io proxy first, then falls back to the classic statuspage.io endpoints.

### Polling Google Workspace Incidents

```swift
import CodexBar

Task {
    do {
        let status = try await UsageStore.fetchWorkspaceStatus(
            productID: "docs",               // product IDs: docs, sheets, slides …
            beforeDecoding: { print("Got payload") })
        print("📶 Workspace status:", status.indicator)
        print("📝 Summary:", status.description ?? "none")
    } catch {
        print("Workspace status error:", error)
    }
}

```

This targets Google Workspace feeds using `fetchWorkspaceStatus` which internally calls `parseGoogleWorkspaceStatus`.

### Integrating Status into the Menu Bar

```swift
// Inside StatusItemController (simplified)
func updateProviderStatus() async {
    let base = URL(string: provider.baseStatusURL)!
    let (status, _) = try? await UsageStore.fetchStatusSummary(from: base)
    await MainActor.run {
        self.statusIndicator = status?.indicator ?? .unknown
        self.statusTooltip = status?.description
    }
}

```

The status-item controller consumes `ProviderStatus` from `UsageStore` and bridges it to the UI on the main actor.

## Summary

- CodexBar polls three distinct status page formats (Incident.io, Statuspage.io, and Google Workspace) using a hierarchical fallback strategy implemented in `UsageStore+Status.swift`
- The `ProviderHTTPClient.shared` transport executes all requests with a **10-second timeout** on background tasks to preserve UI responsiveness
- Severity ranking via `indicatorRank` ensures the worst active incident dominates the menu bar indicator
- **Concurrent execution** using `@concurrent nonisolated` parsing functions and shared lock-protected date formatters optimizes performance during menu bar refreshes

## Frequently Asked Questions

### How does CodexBar handle different status page formats?

According to the source code in `UsageStore+Status.swift`, CodexBar implements specialized parsers for each format: `parseIncidentIOSummary` for Incident.io feeds, `parseStatuspageStatus` and `parseStatuspageComponents` for Statuspage.io, and `parseGoogleWorkspaceStatus` for Google Workspace. The `fetchStatusSummary` method attempts Incident.io first, then falls back to Statuspage.io if the initial request fails.

### What timeout does the status polling system use?

The system uses a **10-second timeout** for all HTTP requests. This is configured in the shared `ProviderHTTPClient.shared` instance, which is injected as the default transport parameter in `fetchStatusSummary` and related methods.

### How does CodexBar determine the severity of an incident?

The system uses an `indicatorRank` mechanism to compare status indicators across components or incidents. When parsing grouped feeds or component lists, the parser selects the worst-case indicator (such as `majorOutage` over `operational`) to represent the overall provider status, ensuring critical issues are surfaced in the menu bar.

### What happens if the status page is unreachable?

If the Incident.io proxy request fails, the system automatically falls back to classic Statuspage.io endpoints ([`summary.json`](https://github.com/steipete/CodexBar/blob/main/summary.json) and [`components.json`](https://github.com/steipete/CodexBar/blob/main/components.json)) as implemented in lines 122-138 of `UsageStore+Status.swift`. Network errors are caught and propagated to the caller, allowing the UI to display an unknown status indicator rather than crashing.