UptimeFlare Documentation

Use PageConfig to customize the appearance of your public status page. You can set a global title and define a list of header links. Links can be highlighted using the highlight property.

const pageConfig: PageConfig = {
  title: "lyc8503's Status Page",
  links: [
    { link: 'https://github.com/lyc8503', label: 'GitHub' },
    { link: 'https://blog.lyc8503.net/', label: 'Blog' },
    { link: 'mailto:me@lyc8503.net', label: 'Email Me', highlight: true },
  ],
}

Use MaintenanceConfig to define scheduled downtime. During maintenance, an alert is shown on the status page and related downtime notifications are skipped.

• monitors: Array of monitor IDs affected by this maintenance.
• title: Title of the maintenance (defaults to "Scheduled Maintenance").
• body: Description shown on the status page.
• start: Start time in UNIX timestamp or ISO 8601 format.
• end: End time in UNIX timestamp or ISO 8601 format (if omitted, maintenance is ongoing).
• color: Color of the alert (e.g., blue, yellow).

const maintenances: MaintenanceConfig[] = [
  {
    monitors: ['foo_monitor', 'bar_monitor'],
    title: 'Test Maintenance',
    body: 'This is a test maintenance, server software upgrade',
    start: '2020-01-01T00:00:00+08:00',
    end: '2050-01-01T00:00:00+08:00',
    color: 'blue',
  },
]

When using CompactedMonitorStateWrapper.uncompact(), the following errors may be thrown if the underlying data structure is corrupted or inconsistent:

• Inconsistent incident data lengths, please report an issue at https://github.com/lyc8503/UptimeFlare (occurs if start, end, or error arrays in an incident have different lengths).
• Inconsistent latency data lengths, please report an issue at https://github.com/lyc8503/UptimeFlare. (occurs if the hex-encoded time, ping, or location data lengths do not match).
• Index out of bounds or monitor not found (occurs when accessing specific incidents via getIncident or setIncident).

To monitor a raw TCP port, set the method to 'TCP_PING'. The target field must be provided in a format that can be parsed as a URL (e.g., https://example.com:80) so the proxy can extract the hostname and port.

Example configuration for a TCP check:

{
  "name": "My Database Port",
  "method": "TCP_PING",
  "target": "https://127.0.0.1:5432",
  "timeout": 2000
}

The worker package provides utility functions to interact with the Cloudflare D1 database via the UPTIMEFLARE_D1 binding in the Env object. These functions use a simple key-value pattern within the uptimeflare table.

• getFromStore(env, key): Retrieves the string value associated with a specific key. Returns null if the key does not exist.
• setToStore(env, key, value): Stores a string value for a given key. If the key already exists, it performs an upsert (updates the existing value).

The getStatus function performs a direct check from the current execution environment. It supports two monitoring methods:

• TCP_PING: Attempts to establish a TCP connection to the target using cloudflare:sockets. Success is determined by the connection being opened within the timeout period.
• HTTP Endpoint: Performs a fetch request to the target. It supports GET, HEAD, and OPTIONS methods.

HTTP Validation Logic:

• Status Codes: If expectedCodes is provided in the monitor config, the response must match one of them. Otherwise, it expects a 2xx status code.
• Keywords: If responseKeyword is set, the response body must contain it. If responseForbiddenKeyword is set, the response body must NOT contain it.
• TLS: For https targets, the TLS certificate must be authorized/trusted.

The doMonitor function is the primary entrypoint for executing a monitoring check for a given MonitorTarget. It supports three types of proxy-based checks via the checkProxy field:

1. Durable Object Proxy: If checkProxy starts with worker://, it uses a Cloudflare Durable Object to perform the check at a specific location.
2. Globalping Proxy: If checkProxy starts with globalping://, it uses the Globalping API to perform geo-distributed measurements.
3. HTTP Proxy: Any other URL is treated as an external HTTP endpoint that accepts a POST request containing the MonitorTarget JSON.

If a proxy check fails and checkProxyFallback is enabled, the function will fall back to a local check using getStatus. If no proxy is provided, it performs a local check.

The getStatusWithGlobalPing function uses the Globalping API to perform remote measurements.

Requirements:

• The monitor.checkProxy must use the globalping: protocol (e.g., globalping://<token>?magic=<value>).
• The token is extracted from the hostname of the checkProxy URL.

Supported Methods:

• TCP_PING: Performs a TCP port probe.
• HTTP: Supports GET, HEAD, and OPTIONS methods. It validates status codes, keywords, and TLS authorization.

Note: Custom request bodies are not supported for HTTP checks via Globalping.

The UptimeFlare worker supports custom lifecycle callbacks that can be triggered during monitoring events. These callbacks are executed within the scheduled event handler.

Available callbacks in workerConfig:

• onStatusChange(env, monitor, isUp, startTime, currentTime, statusOrMessage): Triggered when a monitor's status changes (e.g., UP to DOWN or vice versa).
• onIncident(env, monitor, startTime, currentTime, statusOrMessage): Triggered during incident lifecycle events.

Arguments:

• env: The Env object containing Cloudflare bindings.
• monitor: The MonitorTarget being checked.
• isUp: Boolean indicating if the monitor is currently UP (true) or DOWN (false).
• startTime: The timestamp when the current incident started.
• currentTime: The current execution timestamp.
• statusOrMessage: The error message if DOWN, or 'OK' if UP.