Project overview

NIE-SLA is a self-hostable open-source probe and SLA platform. The server side runs on Cloudflare; a Rust agent on each VPS collects system metrics. The platform provides reachability checks, system telemetry, multi-region latency, long-term SLA statistics, alerting, and a public status page.

Cloudflare active checks, Agent online state, host-side TCP pings, and external latency are different data sources. NIE-SLA records and displays them separately so a single "online" flag cannot hide a broken link.

System architecture

Monitored VPS                       External nodes
Rust Agent                          Latency Agent
  | metrics / TCP ping               | cross-network TCP latency
  +----------- scoped token ---------+
                                      v
                     Cloudflare Worker + Static Assets
                     routing / auth / aggregation / alerts / public API
                          |             |             |
                          v             v             v
                         D1            R2      Durable Objects
                  config & index  history & archive  regional coordination

The Worker is the single entry point, serving the public status page, admin UI, and API from one origin:

• D1: configuration, indexes, current state, fixed-bucket SLA data.
• R2: high-frequency telemetry, snapshots, archives, theme files.
• Durable Objects: regional probe coordination and per-agent hourly telemetry buffering.
• Cron (every minute): probing, aggregation, cleanup, notifications.
• Worker Static Assets: public page and admin UI.

Raw per-second metrics are never all written to D1. History endpoints cap time ranges and sample counts and can downsample dense data. When an optional source fails, the API returns warnings[] instead of pretending the data is empty.

Observation sources

Source	Where it runs	What it answers
Cloudflare checks	Cloudflare edge / regional executors	current reachability and connection latency
Rust Agent online state	monitored VPS	latest system metric reporting
Agent TCP ping	monitored VPS	network quality from the host to a target
External Latency Agent	independent region/provider node	connection latency to public targets

A reachable port does not mean the Agent is reporting, and a reporting Agent does not mean every region can reach the target. The public page and API keep source and time fields; integrations must handle each state separately.

Differences from common setups

The table compares common implementation approaches.

Aspect	Common approach	NIE-SLA
State	central probes or a single heartbeat	separate active checks, Agent state, host pings, external latency
Server	self-hosted app, database, separate frontend	Worker + Static Assets + D1 + R2 + Durable Objects
High-frequency history	raw samples into a relational DB	D1 for current state and aggregation, R2 for history
Agent offline	in-memory retry or drop	local persistent queue, delete after server ACK
Third-party integration	internal frontend endpoints	/api/v1 manifest and stable read-only endpoints
Page customization	edit the frontend or run privileged extensions	CSS themes and sandboxed Canvas themes
Agent release	online CI	local builds of five static Linux architectures with verification and rollback

Key implementation

Agent offline queue

The Rust agent writes unsent samples to a local persistent queue: unique temp file, create_new, Unix 0600, fsync on file and parent directory, then atomic rename. If persistence fails the queue stays dirty and keeps retrying. Samples are deleted only after the Worker confirms receipt, reducing gaps from brief outages or restarts.

Public API

GET /api/v1 returns the endpoints and capabilities of the deployment. The public API is credential-free and read-only; browser CORS is limited to an explicit allowlist. History queries have fixed caps, status uses caching, and clients must handle HTTP status, JSON ok, and warnings[] together. Third-party frontends use only the public API; they never proxy admin sessions or hold Agent tokens.

Credentials

Admin auth uses short-lived sessions with optional TOTP. Agents and latency nodes use per-node scoped tokens; disabling a node revokes its write access. Passwords and GitHub OAuth tickets are used only at login endpoints, never as general API tokens.

Versioning and update chain

The application, Worker, documentation, and Agent share one numeric version. App source tags use app-vX.Y.Z; Agent binary tags/releases use vX.Y.Z. The Worker's update check prefers the official manifest and falls back to a success cache or the bundled manifest on 429, 5xx, timeout, or invalid responses. That only changes where version info comes from; tests and dry-runs in the deployment repository still run.

Agent install and update verify installer, setup, SHA256SUMS, architecture binary, and version in sequence. The chain catches transport corruption and mismatched artifacts, but the hashes come from the same release trust domain and are not an independent offline signature. See Development for source work.

The Linux telemetry service runs unprivileged. Since 1.0.44 removed ICMP, neither the systemd unit nor the Agent binary needs CAP_NET_RAW; the Manager clears leftover file capabilities on startup.