HTTP contract

JSON API, UTF-8. Authenticated sessions use an HttpOnly SameSite=Strict cookie. Mutating authenticated requests require X-CSRF-Token from login or session response. Browser requests must be same-origin. No secrets returned in snapshots. Application-handled failures return { "error": "human readable explanation" } with non-2xx status. Framework routing errors (for example 405) may have a plain-text body; clients must tolerate this. A snapshot is the source of truth; a 2xx response confirms completion. After admission under the serialized operation lock, topology mutations run independently of the HTTP connection through commit/rollback and cleanup. A lost response does not imply an uncommitted change: refresh the snapshot before retrying. Requests cancelled while waiting for admission make no change. Shutdown rejects new admissions and waits for admitted work within the documented process deadline.

Routes

GET / — embedded UI shell (login shown until session validated).
GET /licenses.txt — licenses and attribution for the bundled Bootstrap/Font Awesome assets.
GET /healthz — process readiness {status:"ok"} (not upstream checker health).
POST /api/login JSON {password:string} → {authenticated:true,csrf:string}, Set-Cookie. 401 invalid, 429 limited.
GET /api/session → {authenticated:true,csrf:string}, 401 expired/missing.
POST /api/logout → {ok:true}, clears cookie.
GET /api/snapshot → full snapshot below.
GET /api/events — SSE, event name snapshot, full snapshot every second, heartbeat 15s. Session expiry closes stream. EventSource reconnects automatically; recheck session after errors.
PUT /api/services/{id} — full ServiceConfig JSON; id must match path. Atomically save and hot-apply. → {ok:true}. Validation/bind error: 400; persistence failure: 400 with explanation, runtime rollback attempted. Stopped listener drains established sessions. Changing primary, replicas, policy or auto mode does not restart a running listener. Existing sessions keep their previous route.
DELETE /api/services/{id} — requires enabled:false first; drains/removes then → {ok:true}.
PUT /api/teams/{id} — full Team JSON; new team or rename. Addresses of existing ids are immutable; add another id instead. → {ok:true}.

ServiceConfig:

{"id":"notes","name":"Notes","listen":"0.0.0.0:18080","upstream_port":8080,"primary":"a","replicas":["b"],"enabled":false,"auto_switch":false,"replica_policy":"isolate"}

Team:

{"id":"a","name":"Team A","address":"192.0.2.10"}

Backward-compatible optional fields: ServiceConfig has custom:false and custom_ip:null; Team has hidden:false. The legacy add dialog sends custom:true, equal listen/upstream ports and an optional custom_ip. A non-null IP resolves/reuses its team, sets primary, and atomically saves team plus service. New anonymous IP targets have hidden:true; the UI shows them only in services that reference them. No separate operator team-creation step is required. Clearing custom_ip leaves the submitted primary/replicas authoritative. Manual quick promotion retains the previous primary as replica; automatic promotion does the same and clears the direct-IP override.

Configured/saved topology containing a non-null custom_ip must also contain its matching primary team. The PUT adapter creates that pair; raw TOML/state files are validated rather than silently repaired.

Snapshot

{
 "now_ms": 1792700000000,
 "main_team_ip": "192.0.2.10",
 "health_max_age_ms": 12000,
 "teams": [{"id":"a","name":"Team A","address":"192.0.2.10"}],
 "services": [{
   "id":"notes","name":"Notes","listen":"0.0.0.0:18080","upstream_port":8080,
   "primary":"a","replicas":[],"enabled":true,"auto_switch":false,"replica_policy":"isolate",
   "engine":{"running":true,"last_error":null,"stats":{"accepted":5,"active":1,"completed":4,"connect_errors":0,"io_errors":0,"rejected":0,"accept_errors":0,"bytes_up":1234,"bytes_down":5678,"replica_disconnects":0,"replica_errors":0,"replica_bytes":0}},
   "health":{"a":{"reachable":true,"healthy":true,"consecutive_failures":0,"consecutive_successes":2,"checked_at_ms":1792700000000,"latency_ms":2}},
   "scoreboard":{"a":{"status":101,"stolen":3,"lost":0}}
 }],
 "scoreboard":{"enabled":true,"connected":true,"kind":"forcad","round":5,"updated_at_ms":1792700000000,"stale":false,"last_error":null,"teams":[],"tasks":[],"entries":{}},
 "events":[{"at_ms":1792700000000,"service":"notes","message":"Настройки сохранены"}]
}

Compute displayed bandwidth from positive byte-counter deltas / now_ms deltas, reset baseline when counters decrease. Show unknown health until checked. Scoreboard badges must indicate stale data; never imply stale checker state is current. Replica counters mean explicit disconnections/errors, not dropped arbitrary packets. replica_policy: strict uses backpressure, isolate disconnects a lagging replica per session.

The restored panel retains the legacy four connection counters; byte totals and replica counters are available in their tooltip and the snapshot API. TCP freshness uses health_max_age_ms; the UI additionally marks the whole snapshot stale and disables mutations after five seconds without updates. The top service strip shows the configured main_team_ip checker status, independently of the selected upstream, as in the legacy panel. Unset main IP gives an uncolored strip. Checker names and lost-flag chips retain the original color/sort behavior.

UI follow-up: the Teams dialog exposes existing team PUT (create/rename, preserving hidden status; existing address read-only). Configuration help displays existing scoreboard snapshot fields without adding endpoints. Invalid custom-IP drafts stay local across snapshots; Enter retries save and Escape restores the saved address. Changing a direct IP preserves other replicas; the backend removes any new-primary overlap. Add-proxy drafts persist across dialog cancel/reopen, until successful save or page reload. Process configuration remains TOML-only and requires a restart.

6.0 KiB Raw Blame History

HTTP contract

Routes

Snapshot

6.0 KiB

Raw Blame History