Probe protocol (v1)

Probes are outbound-only agents: they dial the API over WebSocket, pull check jobs, and stream results back. No inbound ports, so a probe can run anywhere — our cloud regions or a customer’s private network behind NAT.

probe ──wss──▶ GET /probe/v1/connect      Authorization: Bearer <token>

The token identifies the probe (only its SHA-256 is stored). Messages are JSON envelopes {"t": "<type>", "d": {...}}.

Handshake

direction type body
probe → api hello proto_version, probe_version, capabilities (check types)
api → probe hello_ack probe_id, region, server_time

Steady state

direction type body
probe → api heartbeat {} every 20s (server closes after 60s silence)
api → probe job job_id, monitor_id, spec (type, target, port, timeout_ms, config, credentials?)
probe → api result job_id, monitor_id, checked_at, status, latency_ms, code, detail
api → probe result_ack job_id
probe → api job_reject job_id, reason (unknown check type — version skew)
api → probe cancel job_id (monitor deleted mid-flight, best effort)

Delivery semantics

At-least-once with idempotent ingestion:

  • The probe buffers every result until acked (ring buffer, cap 1000) and re-sends unacked results after reconnecting.
  • The API dedupes on job_id (unique index) — duplicates are dropped before they can double-count toward alert thresholds.
  • The scheduler leases each job for timeout + 15s; an expired lease is a missed sample, not a missed alert cycle — the monitor simply runs at its next tick.

Failure behavior

  • Reconnect: exponential backoff with jitter, 1s → 60s cap.
  • A reconnecting probe atomically replaces its old connection server-side.
  • If no probe is connected for a monitor’s region, dispatch is skipped and the monitor transitions to unknown after ~3 missed cycles. Unknown is not down: it never fires customer-facing alerts.

Credentials

sip_register credentials are decrypted server-side at dispatch time and sent only inside the job message over WSS. Probes keep them in memory for the duration of the check and never write them to disk.