Skip to content

ARCHITECTURE-PUBLIC-LIVE.md

Latest commit

 

History

History
101 lines (78 loc) · 4.9 KB

ARCHITECTURE-PUBLIC-LIVE.md

File metadata and controls

101 lines (78 loc) · 4.9 KB
Raw

Architecture — Public Live View

Updated: 2026-04-25 (single-mode refactor) Original decision date: 2026-04-23 — Option B chosen (same server, /live route + live.html).

Overview

There is one server, one database (audit.db), and one operating mode. The admin decides whether live audit progress is visible to the public by toggling broadcastLive.

admin.html  ──POST /api/broadcast──►  state.broadcastLive = true/false
                                              │
                          ┌───────────────────┘
                          ▼
              /api/public/events  (SSE fan-out)
                  │
       broadcastLive=false         broadcastLive=true
       ────────────────────        ──────────────────
       Public SSE is silent.       Live progress events forwarded.
       public.html + /live show    /live upgrades from snapshot
       last-completed snapshot.    view to live progress view.

Constraints (unchanged from original)

  1. Zero user-facing action buttons on any public surface.
  2. Public can watch live testing progress only when the admin has enabled broadcast.
  3. Public can search nodes (moniker, address, country, city).
  4. Admin controls start/stop and broadcast. Public never does.
  5. Share-friendly URL (/live).

Pages

Page Role
admin.html Full control panel. Start/stop audit. Toggle Broadcast Live. View all results.
public.html Static node directory + search + filters + sort. No action buttons. Shows last-completed run snapshot.
live.html Public live view. SSE-driven via /api/public/events. Shows live progress when broadcastLive=true; falls back to last-completed snapshot when broadcastLive=false. No action buttons.

Broadcast Live Toggle

  • POST /api/broadcast (adminOnly) — flips state.broadcastLive. No request body required. Returns { broadcastLive: boolean }.
  • GET /api/broadcast — returns current value. Open (no auth).
  • When broadcastLive is set to true:
    1. Admin clicks "Broadcast Live" in admin.html.
    2. state.broadcastLive flips to true on the server.
    3. /api/public/events SSE begins forwarding live batch:* and loop:* events to all connected public clients.
    4. live.html receives the events and switches from snapshot view to live progress view (same cbCard widget used in admin).
  • When broadcastLive is set back to false:
    1. SSE fan-out goes silent.
    2. live.html returns to showing the last-completed run snapshot.

Database

One database: audit.db. All runs — live and dry — write to it.

  • Normal audit run: mode='live' (or absent/null for legacy rows).
  • Test-run (?testRun=1 on /api/start): mode='test'. Every node row gets actualMbps: null, errorCode: 'TEST_RUN_SKIP'. Visually distinguishable in the admin table but stored in the same file.
  • audit-dry.db no longer exists.

TEST RUN (Test Run)

TEST RUN is not a mode — it is an optional parameter on the normal start endpoint.

  • POST /api/start with testRun: true in body, or POST /api/start?testRun=1.
  • Pipeline skips: plan membership check, online scan, chain operations, payments.
  • Every node row: actualMbps: null, errorCode: 'TEST_RUN_SKIP'.
  • Run row: mode='test' in audit.db.
  • Useful for verifying the pipeline plumbing and UI without spending DVPN.

SSE Event Contract

/api/public/events forwards events only when state.broadcastLive=true.

Event Payload
batch:start { batchId, snapshotSize, iteration }
batch:node { addr, moniker, countryCode, type, actualMbps, errorCode, ... }
batch:end { batchId, passed, failed, durationMs }
batch:gap { gapMs }
loop:started { iteration: 0 }
loop:stopped { iterations, reason }
loop:error { error, iteration }

No wallet, plan ID, or fee-grant internals are forwarded on the public SSE stream.

Security Surface

  • /live is publicly accessible (uses attachAdminFlag but does NOT gate access).
  • All data consumed by /live comes from /api/public/* endpoints — already sanitized.
  • POST /api/broadcast requires adminOnly middleware (signed cookie or Bearer token).
  • No ALLOW_PUBLIC_TEST env flag needed — admin triggers broadcast, public only views.

What Was Removed (2026-04-25)

  • Mode cookie (server_mode) and requireMode() middleware.
  • _currentMode, _applyModeUI, selectMode, switchMode client-side helpers.
  • Mode overlay UI in admin.html.
  • POST /api/admin/public-test/start, POST /api/admin/public-test/stop, GET /api/admin/public-test/status.
  • POST /api/public/test/start, POST /api/public/test/stop, GET /api/public/test/status.
  • audit-dry.db — superseded by the mode='test' column in audit.db.
  • Economy mode (deprecated earlier in the same session).