From 46c106409eeaa7405b03626439fa20d662148942 Mon Sep 17 00:00:00 2001 From: dingo Date: Tue, 27 Oct 2026 15:13:02 -0400 Subject: [PATCH] feat(admin): session windows in SQL, opened from the admin portal (schema 62) The dev session window moves from Git to SQL (ADR-0087 amendment): the admin portal opens, extends (30 min to 4 h from now) and closes it, and the cellular region re-reads it every 5 s with --session-window-source db. No push, sync or restart per window; a closed window keeps the region running instead of crash-looping. - Schema 62: append-only session_windows (4 h cap, no rewrites), load_session_window_v1 for the runtime group, admin_set_session_window_v1 and admin_session_windows_v1 for a dedicated admin group role, granted and audited each migration run when EVO_PG_ADMIN_ROLE is set (aevolution_admin in DEV). Schema 61's views are revoked from the runtime group. - RegionSessions admission switch: while closed every Hello is refused before signature work and closing closes open sessions (new sessions were still admitted after expiry before). - Admin API: GET/POST /api/regions//session-window, window state in the regions list; the portal's session-window card with history. - Git: REGION_SESSION_WINDOW and the pre-push refresh rule are removed; the policy check requires the database source and refuses a committed window. Needs the new image and the aevolution_admin role (with the portal's login in aevolution-admin-pg) before a sync. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 7 +- apps/evo-admin-api/portal/app.js | 80 +++++++++++- apps/evo-admin-api/portal/style.css | 8 +- apps/evo-server/cellular_bridge.hpp | 100 +++++++++++--- apps/evo-server/m10_bridge.hpp | 13 +- apps/evo-server/main.cpp | 5 +- deploy/kubernetes/region/base/deployment.yaml | 4 +- .../region/dev-session-route/listener.yaml | 5 +- .../kubernetes/stores/base/migrate-job.yaml | 2 + .../kubernetes/stores/dev/kustomization.yaml | 4 + docs/STATUS.md | 8 ++ docs/adr/0087-dev-session-route.md | 31 +++++ .../adr/0182-admin-portal-and-world-tuning.md | 20 ++- docs/engineering/VALIDATION.md | 37 ++++++ include/evo/server/admin/admin_api.hpp | 15 ++- include/evo/server/region_sessions.hpp | 5 + include/evo/server/session_window.hpp | 49 +++++++ migrations/0062_session_windows.sql | 97 ++++++++++++++ migrations/apply.sql | 90 ++++++++++++- src/server/admin/admin_api.cpp | 122 ++++++++++++++++-- src/server/session/region_sessions.cpp | 11 ++ tests/grant_broker_tests.cpp | 81 +++++++++++- tests/region_migration_tests.cpp | 3 +- tests/session_window_tests.cpp | 28 ++++ tools/backup/verify-backup.sh | 2 + tools/ci/deploy-policy-check.py | 26 ++-- tools/ci/deploy-policy-selftest.py | 14 +- tools/ci/history-domain-check.sh | 4 + tools/ci/postgres-check.sh | 14 +- tools/migrate-postgres.sh | 7 + tools/ops/load-drill.sh | 8 +- 31 files changed, 807 insertions(+), 93 deletions(-) create mode 100644 migrations/0062_session_windows.sql diff --git a/AGENTS.md b/AGENTS.md index 973f29e..e1175f3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,7 +25,6 @@ limits in docs/engineering/VALIDATION.md. Preserve uncommitted work by others. After each completed and validated gate segment, commit its scoped changes and push to the configured Git remote. Preserve unrelated untracked work; never stage secrets. -Immediately before each push, refresh REGION_SESSION_WINDOW in -deploy/kubernetes/region/dev-session-route/listener.yaml with a unique activation -and absolute UTC expiry four hours ahead (ADR-0087). Include it in that push; -do not deploy or claim live reachability from a Git update alone. +The dev session window lives in SQL and is opened from the admin portal (ADR-0087 +amendment of 2026-10-27); Git carries no window. Do not deploy or claim live +reachability from a Git update alone. diff --git a/apps/evo-admin-api/portal/app.js b/apps/evo-admin-api/portal/app.js index 3dec857..8555b07 100644 --- a/apps/evo-admin-api/portal/app.js +++ b/apps/evo-admin-api/portal/app.js @@ -145,11 +145,11 @@ function signOut() { class ApiError extends Error { constructor(status, code) { super(code || `HTTP ${status}`); this.status = status; this.code = code; } } -async function api(path, retry = true) { +async function api(path, retry = true, method = 'GET') { const t = await token(); if (!t) throw new ApiError(401, 'signed_out'); - const res = await fetch(path, { headers: { Authorization: `Bearer ${t}` }, cache: 'no-store' }); - if (res.status === 401 && retry) { access = null; return api(path, false); } + const res = await fetch(path, { method, headers: { Authorization: `Bearer ${t}` }, cache: 'no-store' }); + if (res.status === 401 && retry) { access = null; return api(path, false, method); } if (!res.ok) { let code = null; try { code = (await res.json()).error; } catch { /* plain text */ } @@ -285,10 +285,70 @@ async function regionsPage() { { key: 'sequence', label: 'Commits', num: true, render: (r) => fmtInt(r.sequence), sort: (r) => Number(r.sequence ?? -1) }, { key: 'committed_at', label: 'Last commit', render: (r) => fmtAgo(r.committed_at), sort: (r) => r.committed_at ?? 0 }, { key: 'build', label: 'Build', render: (r) => h('span', { class: 'mono', title: r.build || '' }, r.build ? r.build.slice(0, 12) : '—') }, + { key: 'window_open', label: 'Sessions', render: windowBadge, sort: (r) => (r.window_open ? r.window_expires : 0) }, { key: 'viewable', label: '', render: (r) => (r.viewable ? h('a', { href: `#/regions/${r.region}` }, 'Open view →') : h('span', { class: 'muted' }, 'no view')) }, ], data.regions, { sortKey: 'region' })); } +function windowBadge(r) { + return r.window_open ? h('span', { class: 'badge online', title: fmtTime(r.window_expires) }, `open · closes ${fmtAgo(r.window_expires)}`) + : h('span', { class: 'muted' }, 'closed'); +} + +// The region's session window (ADR-0087): who may connect, until when. Writes go through the +// admin API as the signed-in admin; the region applies a change within about 5 seconds. +function sessionWindowCard(region) { + const card = h('div', { class: 'card' }); + const minutes = h('select', {}, [[30, '30 minutes'], [60, '1 hour'], [120, '2 hours'], [240, '4 hours']] + .map(([m, label]) => h('option', { value: m, selected: m === 240 }, label))); + const reason = h('input', { type: 'text', maxlength: 200, placeholder: 'Reason (optional)' }); + const note = h('div', { class: 'muted small' }); + let busy = false; + const send = async (m) => { + if (busy) return; + if (m === 0 && !confirm(`Close sessions in region ${region}? Connected players are disconnected.`)) return; + busy = true; + try { + const q = new URLSearchParams({ minutes: String(m) }); + if (reason.value.trim()) q.set('reason', reason.value.trim()); + await api(`/api/regions/${region}/session-window?${q}`, true, 'POST'); + reason.value = ''; + note.textContent = 'Saved. The region applies it within about 5 seconds.'; + } catch (e) { + note.textContent = `Could not change the window: ${e.message}`; + } finally { + busy = false; + load(); + } + }; + const openButton = h('button', { class: 'primary', onclick: () => send(Number(minutes.value)) }, 'Open'); + const closeButton = h('button', { onclick: () => send(0) }, 'Close sessions'); + const status = h('div'); + const history = h('div'); + async function load() { + try { + const w = await api(`/api/regions/${region}/session-window`); + const current = w.history[0]; + openButton.textContent = w.open ? 'Extend' : 'Open'; + closeButton.disabled = !w.open; + status.replaceChildren(w.open + ? h('div', {}, h('span', { class: 'badge online' }, 'open'), ` until ${fmtTime(current.expires_at)} (closes ${fmtAgo(current.expires_at)})`) + : h('div', {}, h('span', { class: 'badge' }, 'closed'), current && current.expires_at ? ` expired ${fmtAgo(current.expires_at)}` : '')); + history.replaceChildren(w.history.length ? h('table', { class: 'compact' }, h('tbody', {}, w.history.slice(0, 8).map((x) => + h('tr', {}, h('td', {}, fmtAgo(x.created_at)), + h('td', {}, x.expires_at ? `opened until ${new Date(x.expires_at * 1000).toLocaleTimeString()}` : 'closed'), + h('td', { class: 'muted', title: x.author || '' }, (x.author || '').split(' (')[0]), + h('td', { class: 'muted' }, x.reason || ''))))) : h('p', { class: 'muted' }, 'No window has been opened yet.')); + } catch (e) { + status.textContent = `Unavailable: ${e.message}`; + } + } + card.replaceChildren(h('h2', {}, 'Session window'), status, + h('div', { class: 'window-controls' }, minutes, openButton, closeButton), reason, note, history); + load(); + return { card, load }; +} + // ---------- Region view ---------- const channelNames = ['energy', 'carbon', 'nitrogen', 'phosphorus', 'other']; const css = (name) => getComputedStyle(document.documentElement).getPropertyValue(`--${name}`).trim(); @@ -304,7 +364,8 @@ async function regionPage(region, params) { const show_ = { players: true, wildlife: true, pools: true, bubbles: true }; const toggle = (k, label) => h('label', {}, h('input', { type: 'checkbox', checked: true, onchange: (e) => { show_[k] = e.target.checked; paint(); } }), label); const live = h('input', { type: 'checkbox', checked: true }); - let view = null, selected = null, timer = null; + const sessions = sessionWindowCard(region); + let view = null, selected = null, timer = null, beats = 0; let zoom = 1, panX = 0, panY = 0, drag = null; show( @@ -314,6 +375,7 @@ async function regionPage(region, params) { h('div', { class: 'region-layout' }, h('div', { class: 'canvas-wrap' }, canvas, tip, note), h('div', { class: 'side' }, + sessions.card, detail, h('div', { class: 'card' }, h('h2', {}, 'Show'), h('div', { class: 'toggles' }, toggle('players', 'Player cells'), toggle('wildlife', 'Wildlife'), toggle('pools', 'Pools'), toggle('bubbles', 'Bubbles'))), @@ -495,7 +557,15 @@ async function regionPage(region, params) { status.className = 'error'; } } - const tick = () => { timer = setTimeout(async () => { if (live.checked && !document.hidden) await load(); tick(); }, 1000); }; + const tick = () => { + timer = setTimeout(async () => { + if (live.checked && !document.hidden) { + await load(); + if (++beats % 10 === 0) sessions.load(); + } + tick(); + }, 1000); + }; await load(); tick(); stopPage = () => { clearTimeout(timer); window.removeEventListener('resize', onResize); }; diff --git a/apps/evo-admin-api/portal/style.css b/apps/evo-admin-api/portal/style.css index 7c53eeb..96fc17e 100644 --- a/apps/evo-admin-api/portal/style.css +++ b/apps/evo-admin-api/portal/style.css @@ -58,7 +58,7 @@ button { button:hover { border-color: var(--accent); } button.primary { background: var(--accent); border-color: var(--accent); color: #fff; } button.ghost { background: transparent; } -input[type="search"] { +input[type="search"], input[type="text"], select { font: inherit; color: var(--text); background: var(--panel); @@ -182,3 +182,9 @@ dl.facts dd { margin: 0; } .toggles label { display: flex; gap: 8px; align-items: center; cursor: pointer; } .error { color: var(--bad); } .center { display: grid; place-items: center; min-height: 50vh; text-align: center; } +.window-controls { display: flex; gap: 8px; margin: 10px 0 8px; flex-wrap: wrap; } +.side input[type="text"] { width: 100%; min-width: 0; } +.small { font-size: 12px; margin-top: 6px; } +table.compact { margin-top: 10px; font-size: 12.5px; background: transparent; } +table.compact td { padding: 4px 6px; white-space: normal; } +button:disabled { opacity: 0.5; cursor: default; } diff --git a/apps/evo-server/cellular_bridge.hpp b/apps/evo-server/cellular_bridge.hpp index 839916d..6ccb489 100644 --- a/apps/evo-server/cellular_bridge.hpp +++ b/apps/evo-server/cellular_bridge.hpp @@ -42,9 +42,16 @@ class CellularBridge { if (!options.complete()) return fail("error cellular-session-config"); CellularBridge bridge; - const auto window = server::SessionWindow::open(options.session_window, wall_seconds()); - if (!window) - return fail("error cellular-session-window"); + // A fixed --session-window must be open now; a database window (ADR-0087 amendment) + // may open, close and reopen while the region runs. + if (!options.window_from_database) { + const auto window = server::SessionWindow::open(options.session_window, wall_seconds()); + if (!window) + return fail("error cellular-session-window"); + bridge.window_ = *window; + } + bridge.window_from_database_ = options.window_from_database; + bridge.key_ = key; const auto colon = options.listen.rfind(':'); std::uint16_t port{}; if (colon == std::string::npos || @@ -85,7 +92,6 @@ class CellularBridge { std::copy(issuer.begin(), issuer.end(), public_key.begin()); config.issuer_keys.push_back({1, public_key}); - bridge.window_ = *window; bridge.slot_ = std::make_unique(pg, std::chrono::seconds{2}); const auto lease = [&host] { return host.authority(); }; bridge.control_ = @@ -126,15 +132,25 @@ class CellularBridge { : "error cellular-session-config"); bridge.sessions_ = std::move(*sessions); bridge.sessions_->set_default_interest({0, 0, 0, 7}); + // A database window admits nobody until it has been read. + if (bridge.window_from_database_) + bridge.sessions_->set_admission(false); std::printf("cellular listening %u\n", static_cast(bridge.sessions_->port())); return std::optional{std::move(bridge)}; } + // Applies the session window: while it is closed every Hello is refused, and closing + // closes the open sessions. [[nodiscard]] bool accepting(std::uint64_t now_seconds) { - const bool open = window_ && window_->accepting(now_seconds); - if (!open && !shutdown_) { - sessions_->shutdown(std::chrono::steady_clock::now()); - shutdown_ = true; + if (window_from_database_) + read_window(now_seconds); + const bool open = window_from_database_ ? feed_.accepting(now_seconds) + : window_ && window_->accepting(now_seconds); + if (open != sessions_->admitting()) { + sessions_->set_admission(open); + if (!open) + sessions_->shutdown(std::chrono::steady_clock::now()); + std::printf("cellular sessions %s\n", open ? "admitted" : "closed"); } return open; } @@ -362,11 +378,13 @@ class CellularBridge { const auto before = deposit_stock_.find(patch.id); deposit.drained = before != deposit_stock_.end() && (patch.available.energy.value < before->second.energy.value || - std::ranges::any_of(std::array{0, 1, 2, 3}, [&](int c) { - const auto i = static_cast(c); - return patch.available.matter.at(i).value < - before->second.matter.at(i).value; - })); + std::ranges::any_of( + std::array{0, 1, 2, 3}, + [&](int c) { + const auto i = static_cast(c); + return patch.available.matter.at(i).value < + before->second.matter.at(i).value; + })); seen_stock_[patch.id] = patch.available; // Rules 12 (v13): a bubble's world velocity, current plus induced drift, so the // client can carry it between perceptions. @@ -614,12 +632,65 @@ class CellularBridge { std::puts(message); return std::nullopt; } + // The region's newest window record, every 5 s. A failed read keeps the current window, + // which still closes at its own deadline. + void read_window(std::uint64_t now_seconds) { + constexpr std::chrono::seconds interval{5}; + const auto now = std::chrono::steady_clock::now(); + if (now < next_window_read_) + return; + next_window_read_ = now + interval; + auto* db = slot_->get(); + if (db == nullptr) + return; + const std::array parameters{std::to_string(key_.world), + std::to_string(key_.region)}; + const auto rows = + db->query("SELECT activation_id, floor(extract(epoch FROM expires_at))::bigint FROM " + "evolution.load_session_window_v1($1::evolution.u64, $2::evolution.u64)", + parameters, std::chrono::milliseconds{1000}); + if (!rows) { + slot_->broken(); + return; + } + std::optional record; + if (!rows->empty() && rows->front().size() == 2 && rows->front()[0]) { + record = server::SessionWindowFeed::Record{*rows->front()[0], std::nullopt}; + if (const auto& expiry = rows->front()[1]) { + std::uint64_t value{}; + const auto [end, ec] = + std::from_chars(expiry->data(), expiry->data() + expiry->size(), value); + if (ec == std::errc{} && end == expiry->data() + expiry->size()) + record->expires_at = value; + } + } + switch (feed_.observe(record, now_seconds)) { + case server::SessionWindowFeed::Change::opened: + std::printf("cellular window opened activation=%s expires=%llu\n", + feed_.window()->activation_id().c_str(), + static_cast(feed_.window()->deadline_seconds())); + break; + case server::SessionWindowFeed::Change::closed: + std::puts("cellular window closed"); + break; + case server::SessionWindowFeed::Change::refused: + std::printf("cellular window refused activation=%s\n", + record ? record->activation_id.c_str() : ""); + break; + case server::SessionWindowFeed::Change::none: + break; + } + } std::unique_ptr slot_; std::unique_ptr control_; std::unique_ptr actions_; std::unique_ptr sessions_; - std::optional window_; + std::optional window_; // A fixed --session-window. + bool window_from_database_{}; + persistence::RegionKey key_{}; + server::SessionWindowFeed feed_; + std::chrono::steady_clock::time_point next_window_read_{}; std::optional replicated_tick_; struct SentOffer { server::LifeAccount account{}; @@ -632,6 +703,5 @@ class CellularBridge { // ADR-0136: deposit stocks seen at the last replicated tick, and this tick's. std::map deposit_stock_, seen_stock_; std::vector> owned_; // At last replication. - bool shutdown_{}; }; } // namespace evo::server_app diff --git a/apps/evo-server/m10_bridge.hpp b/apps/evo-server/m10_bridge.hpp index ad4e48d..4f2d4de 100644 --- a/apps/evo-server/m10_bridge.hpp +++ b/apps/evo-server/m10_bridge.hpp @@ -53,6 +53,10 @@ namespace evo::server_app { struct M10Options { std::string listen, certificate, key, issuer, environment, session_window; + // ADR-0087 amendment: `--session-window-source db` reads the window from + // evolution.load_session_window_v1 every few seconds instead of --session-window + // (cellular profile only). Exactly one of the two is given. + bool window_from_database{}; // M10.5c: dev only, 60..14400 s; 0 keeps the default (300 s, ADR-0091). std::uint64_t max_grant_lifetime{}; // M10.9 (ADR-0097, dev only): `--m10-load-governor off` keeps measuring and exposing the @@ -68,15 +72,16 @@ struct M10Options { std::vector life_routes; [[nodiscard]] bool session_any() const noexcept { return !listen.empty() || !certificate.empty() || !key.empty() || !issuer.empty() || - !environment.empty() || !session_window.empty() || max_grant_lifetime != 0 || - !area.empty() || !handoff_key.empty() || !neighbours.empty() || !load_governor; + !environment.empty() || !session_window.empty() || window_from_database || + max_grant_lifetime != 0 || !area.empty() || !handoff_key.empty() || + !neighbours.empty() || !load_governor; } [[nodiscard]] bool any() const noexcept { return session_any() || !life_routes.empty(); } [[nodiscard]] bool complete() const noexcept { return !listen.empty() && !certificate.empty() && !key.empty() && !issuer.empty() && - !environment.empty() && !session_window.empty(); + !environment.empty() && (session_window.empty() == window_from_database); } }; // Actions are handed to the host as soon as they are scheduled (at most 8 ticks ahead). @@ -117,6 +122,8 @@ template class M10Bridge { M10Bridge bridge; if (!o.any()) return bridge; + if (o.window_from_database) + return fail("error m10-window-source"); // The cellular profile only. const auto window = server::SessionWindow::open(o.session_window, wall_seconds()); if (!window) return fail(window.error() == server::SessionWindow::Error::expired diff --git a/apps/evo-server/main.cpp b/apps/evo-server/main.cpp index 656a54a..f9a5123 100644 --- a/apps/evo-server/main.cpp +++ b/apps/evo-server/main.cpp @@ -263,6 +263,8 @@ std::optional parse(int argc, char** argv) { o.m10.environment = value; else if (flag == "--session-window") o.m10.session_window = value; + else if (flag == "--session-window-source" && value == "db") + o.m10.window_from_database = true; else if (flag == "--m10-max-grant-lifetime" && n && *n >= 60 && *n <= 14400) o.m10.max_grant_lifetime = *n; else if (flag == "--m10-area") @@ -1406,7 +1408,8 @@ int main(int argc, char** argv) { "--session-cert F --session-key F --session-grant-key F " "--session-grant-ledger F --session-environment dev]] [--m10-listen " "ADDRESS:PORT --m10-cert F --m10-key F --m10-issuer F " - "--m10-environment dev|stage|world0 --session-window ACTIVATION:UTC_EXPIRY " + "--m10-environment dev|stage|world0 (--session-window ACTIVATION:UTC_EXPIRY | " + "--session-window-source db) " "[--m10-max-grant-lifetime 60..14400] [--m10-area X0,Y0,X1,Y1] " "[--m10-handoff-key F [--m10-neighbour " "REGION=X0,Y0,X1,Y1=HOST:PORT=NAME=PUBFILE]...] " diff --git a/deploy/kubernetes/region/base/deployment.yaml b/deploy/kubernetes/region/base/deployment.yaml index 10a854f..2781caa 100644 --- a/deploy/kubernetes/region/base/deployment.yaml +++ b/deploy/kubernetes/region/base/deployment.yaml @@ -63,7 +63,7 @@ spec: if [ -n "$REGION_SESSION" ]; then m10=(--m10-listen "$REGION_SESSION_LISTEN" --m10-cert /run/session/server.pem --m10-key /run/session/server.key --m10-issuer /run/session/issuer.pub - --m10-environment "$REGION_SESSION" --session-window "$REGION_SESSION_WINDOW") + --m10-environment "$REGION_SESSION" --session-window-source db) grant=(--m10-max-grant-lifetime "$REGION_M10_MAX_GRANT_LIFETIME") fi # Lineage keeps its 20 s drain. Both profiles take the overlay grant ceiling; @@ -100,8 +100,6 @@ spec: # Session listener address; the policy check allows only this loopback value # outside region/dev-session-route. - {name: REGION_SESSION_LISTEN, value: "127.0.0.1:7400"} - # Absolute UTC expiry; route overlays must provide activation-id:unix-seconds. - - {name: REGION_SESSION_WINDOW, value: ""} # DEV-only grant ceiling; overlays must keep this within the server contract. - {name: REGION_M10_MAX_GRANT_LIFETIME, value: "300"} ports: diff --git a/deploy/kubernetes/region/dev-session-route/listener.yaml b/deploy/kubernetes/region/dev-session-route/listener.yaml index 80134e0..1ab4dbf 100644 --- a/deploy/kubernetes/region/dev-session-route/listener.yaml +++ b/deploy/kubernetes/region/dev-session-route/listener.yaml @@ -1,5 +1,5 @@ -# With the route, the opt-in M10 QUIC listener binds the pod interface. The absolute -# expiry is committed so a delayed Argo sync fails closed (ADR-0087). +# With the route, the opt-in M10 QUIC listener binds the pod interface. Its session window +# is not in Git: the region reads it from SQL, set in the admin portal (ADR-0087 amendment). apiVersion: apps/v1 kind: Deployment metadata: @@ -12,7 +12,6 @@ spec: env: - {name: REGION_SESSION, value: "dev"} - {name: REGION_SESSION_LISTEN, value: "0.0.0.0:7400"} - - {name: REGION_SESSION_WINDOW, value: "dev-20261027T175219-2121894c:1793137939"} - {name: REGION_M10_MAX_GRANT_LIFETIME, value: "14400"} ports: # QUIC (ADR-0090): UDP only; nothing listens on TCP 7400. diff --git a/deploy/kubernetes/stores/base/migrate-job.yaml b/deploy/kubernetes/stores/base/migrate-job.yaml index a0dd2bf..4b81474 100644 --- a/deploy/kubernetes/stores/base/migrate-job.yaml +++ b/deploy/kubernetes/stores/base/migrate-job.yaml @@ -38,6 +38,8 @@ spec: - {name: PGSERVICEFILE, value: /run/postgres/pg_service.conf} - {name: EVO_PGPASS_SOURCE, value: /run/postgres/pgpass} - {name: EVO_PG_RUNTIME_ROLE, value: set-by-overlay} + # ADR-0182: the admin API's group role; empty grants no admin functions. + - {name: EVO_PG_ADMIN_ROLE, value: ""} resources: requests: {cpu: 100m, memory: 64Mi} limits: {memory: 128Mi} diff --git a/deploy/kubernetes/stores/dev/kustomization.yaml b/deploy/kubernetes/stores/dev/kustomization.yaml index 3e03a72..e9a1a2d 100644 --- a/deploy/kubernetes/stores/dev/kustomization.yaml +++ b/deploy/kubernetes/stores/dev/kustomization.yaml @@ -24,3 +24,7 @@ patches: - op: replace path: /spec/template/spec/containers/0/env/3/value value: aevolution_runtime + # Operator-created NOLOGIN group of the admin portal's login (ADR-0182). + - op: replace + path: /spec/template/spec/containers/0/env/4/value + value: aevolution_admin diff --git a/docs/STATUS.md b/docs/STATUS.md index 086b88a..f28fd86 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -1,5 +1,13 @@ # Project status and next steps +## Session windows from the admin portal - 2026-10-27 + +The dev session window now lives in SQL (schema 62) instead of Git: the admin portal opens, +extends (up to four hours from now) and closes it, and the region applies the change within +about five seconds without a push, sync or restart. A closed window refuses every new +session and the region keeps running. The admin API moves to its own database role. See the +[ADR-0087 amendment](adr/0087-dev-session-route.md) and [validation](engineering/VALIDATION.md). + ## Read-only admin portal - 2026-10-27 [ADR-0182](adr/0182-admin-portal-and-world-tuning.md) records the admin portal direction diff --git a/docs/adr/0087-dev-session-route.md b/docs/adr/0087-dev-session-route.md index a406163..24a4334 100644 --- a/docs/adr/0087-dev-session-route.md +++ b/docs/adr/0087-dev-session-route.md @@ -197,3 +197,34 @@ the pod-side checks (ready, listener bound) could not show this. Decision: Service UDP 7400 -> NetworkPolicy UDP 7400 -> evo-region M10 listener`, with the dev CA and issuer key read from the authorized cluster Secret without printing or persisting them. Until that is recorded in VALIDATION.md the route is not declared working. + +## Amendment 2026-10-27: Session windows in SQL, opened from the admin portal + +Maintainer decision (ADR-0182 discussion). Committing the window to Git meant a push and a +full Argo sync for every opening or extension, and an expired window made the region exit +and crash-loop until the next sync. The window moves to the database: + +- **Record.** Schema 62 adds the append-only `evolution.session_windows` (world, region, + activation id, absolute UTC expiry or none, author, reason, time written). A row with an + expiry opens or replaces the window until then; a row without one closes it. The table + refuses updates, deletes and truncation, and a window may end at most **four hours** after + it is written (the maximum is unchanged). +- **Writing.** Only the admin group role, through `admin_set_session_window_v1`, from the + admin portal (Open or Extend for 30 min to 4 h, Close). The author is the signed-in + admin's email and Keycloak subject. The runtime group may only read the newest row + (`load_session_window_v1`). +- **Reading.** The cellular region runs with `--session-window-source db` and reads the newest + row every 5 s on its session-ledger connection. A newer activation replaces the window + without disturbing open sessions; a closing, expired, over-long or missing row closes it. + Each admitted window keeps its own absolute deadline, a window once closed never reopens + (only a newer activation opens sessions again), and an unreadable database leaves the + current window to close at its deadline. +- **Closed means closed.** While no window is open, every Hello is refused with `shutdown` + before signature work, and closing closes the open sessions. Previously the cellular + bridge closed the sessions once at expiry but still admitted new ones. The region keeps + running while closed instead of exiting. +- **Git.** `REGION_SESSION_WINDOW` and the pre-push refresh are removed; the policy check + requires `--session-window-source db` and refuses a committed window. A fixed + `--session-window` remains for the lineage/primitive bridge and process tests. + +The elapsed-time guard of the 2026-10-08 clock amendment is still pending. diff --git a/docs/adr/0182-admin-portal-and-world-tuning.md b/docs/adr/0182-admin-portal-and-world-tuning.md index 087f2c8..9cdf04b 100644 --- a/docs/adr/0182-admin-portal-and-world-tuning.md +++ b/docs/adr/0182-admin-portal-and-world-tuning.md @@ -23,7 +23,7 @@ may change a running region except an event recorded at a tick. ### 1. World tuning lives in SQL -- Schema 62 adds append-only `world_tuning_revisions(world, revision, parent_revision, +- Schema 63 adds append-only `world_tuning_revisions(world, revision, parent_revision, format, canonical_text, digest, author_subject, reason, created_at)`. A revision is the complete canonical tuning text (`encode_cellular_revamp_tuning`), never a diff, so the existing parser and validator are the only interpretation. @@ -51,7 +51,7 @@ may change a running region except an event recorded at a tick. ### 3. Admin commands -- Schema 62 adds `admin_commands(world, region, command_id, kind, payload, author_subject, +- Schema 63 adds `admin_commands(world, region, command_id, kind, payload, author_subject, reason, created_at, applied_tick, outcome)`. The admin API inserts and the region host drains them at tick boundaries in id order, publishing each with that tick. This is the same pattern as the durable mutation queue (schema 59). @@ -160,14 +160,26 @@ pool holds. For the source, scale multiplies the import. (`'self'` scripts and styles, connections only to this origin and the realm), `nosniff`, `no-referrer` and `DENY` framing; every answer is `no-store`. The access token stays in page memory and the rotating refresh token in the tab's sessionStorage. -- **Not yet available** (they need the schema-62 records): time played, bans, current +- **Not yet available** (they need the schema-63 records): time played, bans, current mutations and living offspring. +### 9. Session windows and the admin role (schema 62) + +The dev session window moves from Git to SQL and is opened, extended and closed from the +portal; see the [ADR-0087 amendment](0087-dev-session-route.md). Schema 62 also moves the +admin functions to a dedicated, operator-created NOLOGIN group role (`aevolution_admin` in +DEV, `EVO_PG_ADMIN_ROLE` for the migration): every migration run grants it exactly the admin +functions and audits it like the runtime group (no table privilege, no privileged +attribute, no membership outside it, not the runtime role). Schema 61's read views are +revoked from the runtime group. The admin API logs in with its own login in that group. +Writes go through POST without a body (`?minutes=M&reason=R`); the bearer token in the +`Authorization` header, never a cookie, is the only credential. + ## Delivery order 1. Read-only portal: login, accounts (from existing data), regions, region view (schema 61, section 8). -2. Schema 62 and the new owner format: world revisions, adoption records, admin commands, +2. Schema 63 and the new owner format: world revisions, adoption records, admin commands, game source, drip settings, the score vector, session intervals and bans. One new opening on that format. 3. Admin commands and account actions in the portal. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 689fe55..5e6b5aa 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -10471,3 +10471,40 @@ Keycloak client, Ingress, Secret and a new server image are not in place yet); a lives and deaths were checked only on accounts without lives. The MSVC and sanitizer presets and the image build/smoke were not run locally. Nothing was deployed, pushed or synced; no World0, stage or live database operation occurred. + +## 2026-10-27 - Session windows in SQL and the admin role (schema 62) + +Scope: the ADR-0087 amendment and ADR-0182 section 9. Schema 62 adds the append-only +`session_windows` table, `load_session_window_v1` (runtime), `admin_set_session_window_v1` +and `admin_session_windows_v1` (admin), and moves schema 61's views to the optional +operator-created admin group role, granted and audited on every migration run. The cellular +region reads the window every 5 s with `--session-window-source db`; `RegionSessions` gains +an admission switch so a closed window refuses Hellos before signature work (previously new +sessions were still admitted after expiry). The portal opens, extends and closes windows. +Git no longer carries `REGION_SESSION_WINDOW`. No simulation, checkpoint or wire change. + +Executed (WSL Ubuntu, GCC 14.2 Release/NDEBUG, build/m97-postgres): + +- Full build of the tree with -Werror (one -Wshadow fix in the new test). +- CTest `session`: 5/5 passed, including the new SessionWindowFeed cases (no record, open, + same-record no-op, extension by a newer activation, own deadline, no reopening, closing + row, expired and over-long refusals, a vanished record). +- `tools/ci/postgres-check.sh --full` passed (637 s, every phase). The admin API tests now + log in as the new admin login: open with reason, history and author, extend, close, + regions list state, 400s for bad minutes and reasons, 403 without the role, 405 on other + POST paths, 503 for an unknown region; the runtime role reads only the current window and + can no longer call the admin views or the writer; the table refuses UPDATE, DELETE and a + window over four hours. The test cluster gained an admin group role and login; the + private verify-backup cluster ignores the admin role; the schema-50 rewind and the + future-version probe move up to 62/63. +- clang-tidy 19 (warnings as errors) on the changed sources; one unchecked-optional fix in + the window test. A pre-existing finding in region_sessions.cpp:291 under the standalone + invocation is outside this change. clang-format 19.1.5 applied; `node --check` on the + portal script. +- Deploy suite passed: the policy check now requires `--session-window-source db` and + refuses a committed `REGION_SESSION_WINDOW` (self-test cases added for both). + +Limits: no live region has read a SQL window yet, and no process test drives the database +window through a real session; the elapsed-time guard of the 2026-10-08 clock amendment is +still pending. Applying it needs the DEV `aevolution_admin` role and the admin portal's own +login first. diff --git a/include/evo/server/admin/admin_api.hpp b/include/evo/server/admin/admin_api.hpp index c1ec522..0aca1d1 100644 --- a/include/evo/server/admin/admin_api.hpp +++ b/include/evo/server/admin/admin_api.hpp @@ -26,6 +26,11 @@ // GET /api/accounts/ one account and its life requests // GET /api/regions the world's regions, leases and heads // GET /api/regions//view the region's live view (render_cellular_admin_view) +// GET /api/regions//session-window the current session window and its last changes +// POST /api/regions//session-window?minutes=M[&reason=R] +// opens or extends the window for M (1..240) minutes +// from now, or closes it (M = 0), as the signed-in admin +// (ADR-0087 amendment). No request body. namespace evo::server::admin { struct AdminAsset { std::string path; // "/index.html", ...; "/" serves "/index.html". @@ -52,11 +57,15 @@ class AdminApi { std::chrono::steady_clock::time_point now); private: - [[nodiscard]] OpsResponse api(std::string_view path, const broker::AccessTokenClaims& admin, + [[nodiscard]] OpsResponse api(std::string_view method, std::string_view path, + std::string_view query, const broker::AccessTokenClaims& admin, std::chrono::steady_clock::time_point now); [[nodiscard]] OpsResponse accounts(std::optional account); [[nodiscard]] OpsResponse regions(); [[nodiscard]] OpsResponse view(std::uint64_t region, std::chrono::steady_clock::time_point now); + [[nodiscard]] OpsResponse window(std::uint64_t region); + [[nodiscard]] OpsResponse set_window(std::uint64_t region, std::string_view query, + const broker::AccessTokenClaims& admin); [[nodiscard]] std::optional query(const std::string& sql, std::vector parameters); @@ -80,4 +89,8 @@ class AdminApi { std::size_t limit); // JSON string literal (quotes included) with control characters escaped. [[nodiscard]] std::string json_string(std::string_view text); +// The decoded value of `name` in a URL query ("a=1&b=x%20y"), or nullopt when absent or +// malformed (bad escape, a decoded control character, over `limit` bytes). +[[nodiscard]] std::optional query_value(std::string_view query, std::string_view name, + std::size_t limit = 200); } // namespace evo::server::admin diff --git a/include/evo/server/region_sessions.hpp b/include/evo/server/region_sessions.hpp index 5e2c636..32b1eea 100644 --- a/include/evo/server/region_sessions.hpp +++ b/include/evo/server/region_sessions.hpp @@ -207,6 +207,11 @@ class RegionSessions { [[nodiscard]] const network::motion::ProbeMarkers& markers() const noexcept; // Closes every connection with `shutdown` (flushed by later polls). void shutdown(std::chrono::steady_clock::time_point now); + // ADR-0087 session window: while closed, every Hello (grant or handoff ticket) is closed + // with `shutdown` before signature work. Open by default; closing does not close the + // connections already open (call shutdown for that). + void set_admission(bool open) noexcept; + [[nodiscard]] bool admitting() const noexcept; [[nodiscard]] std::vector take_events(); [[nodiscard]] std::optional holder(const network::AccountId& account) const; [[nodiscard]] std::size_t sessions() const noexcept; diff --git a/include/evo/server/session_window.hpp b/include/evo/server/session_window.hpp index 8e25c1d..942ffd9 100644 --- a/include/evo/server/session_window.hpp +++ b/include/evo/server/session_window.hpp @@ -3,6 +3,7 @@ #include #include #include +#include #include #include #include @@ -67,4 +68,52 @@ class SessionWindow { bool closed_{}; }; +// ADR-0087 amendment (2026-10-27): the window as the database records it, re-read every few +// seconds. A newer activation replaces the current window (sessions continue); a closed, +// expired, over-long or absent record closes it. Each admitted window keeps its own absolute +// deadline, and a window once closed never reopens: only a newer activation opens sessions +// again. While the database cannot be read the caller does not observe, so the current +// window keeps running to its deadline. +class SessionWindowFeed { + public: + struct Record { + std::string activation_id; + std::optional expires_at; // nullopt: the record closes the window. + }; + enum class Change : std::uint8_t { none, opened, closed, refused }; + + // `record` is the region's newest row, or nullopt when it has none. + Change observe(const std::optional& record, std::uint64_t now_seconds) { + if (!record) { + const bool had = window_.has_value(); + window_.reset(); + seen_.clear(); + return had ? Change::closed : Change::none; + } + if (record->activation_id == seen_) + return Change::none; + seen_ = record->activation_id; + const bool had = window_.has_value(); + window_.reset(); + if (!record->expires_at) + return had ? Change::closed : Change::none; + auto opened = SessionWindow::open( + record->activation_id + ":" + std::to_string(*record->expires_at), now_seconds); + if (!opened) + return Change::refused; + window_ = std::move(*opened); + return Change::opened; + } + [[nodiscard]] bool accepting(std::uint64_t now_seconds) noexcept { + return window_ && window_->accepting(now_seconds); + } + [[nodiscard]] const std::optional& window() const noexcept { + return window_; + } + + private: + std::optional window_; + std::string seen_; // The newest activation observed, admitted or not. +}; + } // namespace evo::server diff --git a/migrations/0062_session_windows.sql b/migrations/0062_session_windows.sql new file mode 100644 index 0000000..0c39602 --- /dev/null +++ b/migrations/0062_session_windows.sql @@ -0,0 +1,97 @@ +-- Session windows in SQL (ADR-0087 amendment and ADR-0182, 2026-10-27). A region's dev +-- session window is the newest row of an append-only table instead of a Git-committed +-- environment value: the admin portal opens, extends and closes it, and the region reads it +-- every few seconds. A row with an expiry opens (or replaces) the window until then, at most +-- four hours after it was written; a row without one closes it. Rows are never changed. +-- +-- The admin functions move to a dedicated group role: schema 61's read views are revoked +-- from the runtime group, and apply.sql grants every admin function to :admin_role on each +-- run when that role is configured. The runtime group may only read the current window. + +CREATE TABLE evolution.session_windows ( + world_id evolution.u64 NOT NULL, + region_id evolution.u64 NOT NULL, + sequence bigint GENERATED ALWAYS AS IDENTITY, + activation_id text NOT NULL UNIQUE CHECK (activation_id ~ '^[A-Za-z0-9._-]{1,64}$'), + expires_at timestamptz, + author_subject text NOT NULL CHECK (octet_length(author_subject) BETWEEN 1 AND 255), + reason text NOT NULL DEFAULT '' CHECK (octet_length(reason) <= 500), + created_at timestamptz NOT NULL DEFAULT clock_timestamp(), + PRIMARY KEY (world_id, region_id, sequence), + FOREIGN KEY (world_id, region_id) REFERENCES evolution.region_leases, + CHECK (expires_at IS NULL OR + (expires_at > created_at AND expires_at <= created_at + interval '4 hours')) +); +CREATE TRIGGER session_windows_immutable BEFORE UPDATE OR DELETE ON evolution.session_windows + FOR EACH ROW EXECUTE FUNCTION evolution.refuse_history_rewrite(); +CREATE TRIGGER session_windows_no_truncate BEFORE TRUNCATE ON evolution.session_windows + FOR EACH STATEMENT EXECUTE FUNCTION evolution.refuse_history_rewrite(); + +-- The region's current window: its newest row, or nothing when none was ever written. +CREATE FUNCTION evolution.load_session_window_v1(p_world evolution.u64, p_region evolution.u64) +RETURNS TABLE (activation_id text, expires_at timestamptz, author_subject text, + created_at timestamptz) +LANGUAGE sql STABLE SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ + SELECT w.activation_id, w.expires_at, w.author_subject, w.created_at + FROM evolution.session_windows w + WHERE w.world_id = p_world AND w.region_id = p_region + ORDER BY w.sequence DESC + LIMIT 1 +$$; +REVOKE ALL ON FUNCTION evolution.load_session_window_v1(evolution.u64, evolution.u64) FROM PUBLIC; +GRANT EXECUTE ON FUNCTION evolution.load_session_window_v1(evolution.u64, evolution.u64) + TO :"runtime_role"; + +-- Opens or extends (1..14400 seconds from now, a new activation) or closes (0 seconds) the +-- region's window, recording who and why. Returns the row written. +CREATE FUNCTION evolution.admin_set_session_window_v1(p_world evolution.u64, + p_region evolution.u64, p_seconds integer, p_subject text, p_reason text) +RETURNS TABLE (activation_id text, expires_at timestamptz) +LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ +#variable_conflict use_column +DECLARE + now_at timestamptz := clock_timestamp(); + id text := 'adm-' || to_char(now_at AT TIME ZONE 'UTC', 'YYYYMMDD"T"HH24MISS') || '-' + || substr(replace(gen_random_uuid()::text, '-', ''), 1, 8); +BEGIN + IF p_seconds IS NULL OR p_seconds < 0 OR p_seconds > 14400 THEN + RAISE EXCEPTION 'session window duration out of range' USING ERRCODE = '22023'; + END IF; + IF NOT EXISTS (SELECT 1 FROM evolution.region_leases l + WHERE l.world_id = p_world AND l.region_id = p_region) THEN + RAISE EXCEPTION 'unknown region' USING ERRCODE = '22023'; + END IF; + RETURN QUERY + WITH written AS ( + INSERT INTO evolution.session_windows AS w(world_id, region_id, activation_id, expires_at, + author_subject, reason, created_at) + VALUES (p_world, p_region, id, + CASE WHEN p_seconds = 0 THEN NULL ELSE now_at + make_interval(secs => p_seconds) END, + p_subject, coalesce(p_reason, ''), now_at) + RETURNING w.activation_id, w.expires_at) + SELECT written.activation_id, written.expires_at FROM written; +END $$; +REVOKE ALL ON FUNCTION evolution.admin_set_session_window_v1(evolution.u64, evolution.u64, + integer, text, text) FROM PUBLIC; + +-- The region's last 50 window changes, newest first. +CREATE FUNCTION evolution.admin_session_windows_v1(p_world evolution.u64, p_region evolution.u64) +RETURNS TABLE (sequence bigint, activation_id text, expires_at timestamptz, + author_subject text, reason text, created_at timestamptz) +LANGUAGE sql STABLE SECURITY DEFINER SET search_path = pg_catalog, pg_temp AS $$ + SELECT w.sequence, w.activation_id, w.expires_at, w.author_subject, w.reason, w.created_at + FROM evolution.session_windows w + WHERE w.world_id = p_world AND w.region_id = p_region + ORDER BY w.sequence DESC + LIMIT 50 +$$; +REVOKE ALL ON FUNCTION evolution.admin_session_windows_v1(evolution.u64, evolution.u64) + FROM PUBLIC; + +-- Schema 61's read views belong to the admin role from now on. +REVOKE EXECUTE ON FUNCTION evolution.admin_accounts_v1(evolution.u64) FROM :"runtime_role"; +REVOKE EXECUTE ON FUNCTION evolution.admin_account_lives_v1(evolution.u64, uuid) + FROM :"runtime_role"; +REVOKE EXECUTE ON FUNCTION evolution.admin_regions_v1(evolution.u64) FROM :"runtime_role"; + +INSERT INTO evolution.schema_migrations(version,sha256) VALUES(62,:'migration_sha_62'); diff --git a/migrations/apply.sql b/migrations/apply.sql index 91cfc78..e4a27e2 100644 --- a/migrations/apply.sql +++ b/migrations/apply.sql @@ -137,6 +137,7 @@ SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname='evolution') SELECT :'history_v58' || ',59:' || :'migration_sha_59' AS history_v59 \gset SELECT :'history_v59' || ',60:' || :'migration_sha_60' AS history_v60 \gset SELECT :'history_v60' || ',61:' || :'migration_sha_61' AS history_v61 \gset + SELECT :'history_v61' || ',62:' || :'migration_sha_62' AS history_v62 \gset SELECT :'history' = :'history_v22' AS at_v22, :'history' = :'history_v23' AS at_v23, :'history' = :'history_v24' AS at_v24, @@ -176,8 +177,10 @@ SELECT EXISTS (SELECT 1 FROM pg_catalog.pg_namespace WHERE nspname='evolution') :'history' = :'history_v58' AS at_v58, :'history' = :'history_v59' AS at_v59, :'history' = :'history_v60' AS at_v60, - :'history' = :'history_v61' AS at_v61 \gset - \if :at_v61 + :'history' = :'history_v61' AS at_v61, + :'history' = :'history_v62' AS at_v62 \gset + \if :at_v62 + \elif :at_v61 \elif :at_v60 \elif :at_v59 \elif :at_v58 @@ -593,7 +596,8 @@ SELECT coalesce(max(version), 0) = 24 AS at_v24, coalesce(max(version), 0) = 58 AS at_v58, coalesce(max(version), 0) = 59 AS at_v59, coalesce(max(version), 0) = 60 AS at_v60, - coalesce(max(version), 0) = 61 AS at_v61 + coalesce(max(version), 0) = 61 AS at_v61, + coalesce(max(version), 0) = 62 AS at_v62 FROM evolution.schema_migrations \gset \if :at_v24 \ir 0025_cellular_v2_bundle.sql @@ -823,6 +827,7 @@ SELECT coalesce(max(version), 0) = 24 AS at_v24, \elif :at_v59 \elif :at_v60 \elif :at_v61 +\elif :at_v62 \else \echo 'Unknown or changed migration history after v43' DO $$ BEGIN RAISE EXCEPTION 'unknown or changed migration history'; END $$; @@ -899,6 +904,10 @@ SELECT coalesce(max(version), 0) = 60 AS needs_v61 FROM evolution.schema_migrati \if :needs_v61 \ir 0061_admin_read_views.sql \endif +SELECT coalesce(max(version), 0) = 61 AS needs_v62 FROM evolution.schema_migrations \gset +\if :needs_v62 + \ir 0062_session_windows.sql +\endif -- Effective-privilege audit on every run, including no-ops (ADR-0060). Attributes -- alone are insufficient: predefined roles such as pg_write_all_data, PUBLIC -- grants or SET-able memberships would bypass the fenced functions. Checks the @@ -972,9 +981,7 @@ BEGIN ('evolution.load_cellular_mutation_publications(evolution.u64,evolution.u64,uuid,evolution.u64,uuid)'::regprocedure::oid), ('evolution.end_cellular_lives(evolution.u64,evolution.u64,uuid,evolution.u64,uuid,bytea)'::regprocedure::oid), ('evolution.issue_account_grant(evolution.u64,text,text)'::regprocedure::oid), - ('evolution.admin_accounts_v1(evolution.u64)'::regprocedure::oid), - ('evolution.admin_account_lives_v1(evolution.u64,uuid)'::regprocedure::oid), - ('evolution.admin_regions_v1(evolution.u64)'::regprocedure::oid), + ('evolution.load_session_window_v1(evolution.u64,evolution.u64)'::regprocedure::oid), ('evolution.revoke_account_grants(evolution.u64,text,text)'::regprocedure::oid), ('evolution.load_cellular_publication_actions(evolution.u64,evolution.u64,uuid,evolution.u64,uuid)'::regprocedure::oid), ('evolution.load_cellular_publication_births(evolution.u64,evolution.u64,uuid,evolution.u64,uuid)'::regprocedure::oid), @@ -1029,4 +1036,75 @@ BEGIN RAISE EXCEPTION 'runtime role audit failed: %', bad; END IF; END $$; +-- ADR-0182: the admin API's group role, when configured (EVO_PG_ADMIN_ROLE). Every run +-- grants it exactly the admin functions and audits it like the runtime group; it shares no +-- membership with the runtime group. +\if :{?admin_role} +GRANT USAGE ON SCHEMA evolution TO :"admin_role"; +GRANT EXECUTE ON FUNCTION evolution.admin_accounts_v1(evolution.u64) TO :"admin_role"; +GRANT EXECUTE ON FUNCTION evolution.admin_account_lives_v1(evolution.u64, uuid) TO :"admin_role"; +GRANT EXECUTE ON FUNCTION evolution.admin_regions_v1(evolution.u64) TO :"admin_role"; +GRANT EXECUTE ON FUNCTION evolution.load_session_window_v1(evolution.u64, evolution.u64) + TO :"admin_role"; +GRANT EXECUTE ON FUNCTION evolution.admin_session_windows_v1(evolution.u64, evolution.u64) + TO :"admin_role"; +GRANT EXECUTE ON FUNCTION evolution.admin_set_session_window_v1(evolution.u64, evolution.u64, + integer, text, text) TO :"admin_role"; +SELECT pg_catalog.set_config('evolution.admin_role', :'admin_role', true); +DO $$ +DECLARE + admin oid := (SELECT r.oid FROM pg_catalog.pg_roles r + WHERE r.rolname = pg_catalog.current_setting('evolution.admin_role')); + runtime oid := (SELECT r.oid FROM pg_catalog.pg_roles r + WHERE r.rolname = pg_catalog.current_setting('evolution.runtime_role')); + bad text; +BEGIN + IF admin IS NULL THEN + RAISE EXCEPTION 'admin role does not exist'; + END IF; + WITH RECURSIVE closure(oid) AS ( + SELECT admin + UNION + SELECT m.member FROM pg_catalog.pg_auth_members m JOIN closure c ON m.roleid = c.oid + ), fenced(oid) AS (VALUES + ('evolution.admin_accounts_v1(evolution.u64)'::regprocedure::oid), + ('evolution.admin_account_lives_v1(evolution.u64,uuid)'::regprocedure::oid), + ('evolution.admin_regions_v1(evolution.u64)'::regprocedure::oid), + ('evolution.load_session_window_v1(evolution.u64,evolution.u64)'::regprocedure::oid), + ('evolution.admin_session_windows_v1(evolution.u64,evolution.u64)'::regprocedure::oid), + ('evolution.admin_set_session_window_v1(evolution.u64,evolution.u64,integer,text,text)'::regprocedure::oid) + ), violations(reason) AS ( + SELECT 'admin role is the runtime role' WHERE admin = runtime + UNION ALL + SELECT 'privileged attribute or owner identity' FROM pg_catalog.pg_roles r + JOIN closure c ON c.oid = r.oid + WHERE r.rolsuper OR r.rolcreaterole OR r.rolcreatedb OR r.rolreplication + OR r.rolbypassrls OR r.rolname = current_user + UNION ALL + SELECT 'membership outside the admin group' FROM pg_catalog.pg_auth_members m + JOIN closure c ON c.oid = m.member + WHERE m.roleid NOT IN (SELECT oid FROM closure) + UNION ALL + SELECT 'table privilege in evolution schema' FROM closure c + CROSS JOIN pg_catalog.pg_class t + WHERE t.relnamespace = 'evolution'::regnamespace AND t.relkind IN ('r', 'p', 'v', 'm', 'S') + AND pg_catalog.has_table_privilege(c.oid, t.oid, + 'SELECT,INSERT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER,MAINTAIN') + UNION ALL + SELECT 'CREATE on schema or database' FROM closure c + WHERE pg_catalog.has_schema_privilege(c.oid, 'evolution', 'CREATE') + OR pg_catalog.has_database_privilege(c.oid, pg_catalog.current_database(), 'CREATE') + UNION ALL + SELECT 'EXECUTE outside the admin function set' FROM closure c + CROSS JOIN pg_catalog.pg_proc p + WHERE p.pronamespace = 'evolution'::regnamespace + AND p.oid NOT IN (SELECT oid FROM fenced) + AND pg_catalog.has_function_privilege(c.oid, p.oid, 'EXECUTE') + ) + SELECT pg_catalog.string_agg(DISTINCT v.reason, '; ') INTO bad FROM violations v; + IF bad IS NOT NULL THEN + RAISE EXCEPTION 'admin role audit failed: %', bad; + END IF; +END $$; +\endif COMMIT; diff --git a/src/server/admin/admin_api.cpp b/src/server/admin/admin_api.cpp index 38dd9ff..801a573 100644 --- a/src/server/admin/admin_api.cpp +++ b/src/server/admin/admin_api.cpp @@ -144,6 +144,40 @@ std::string json_string(std::string_view text) { return out + "\""; } +std::optional query_value(std::string_view query, std::string_view name, + std::size_t limit) { + while (!query.empty()) { + const auto amp = query.find('&'); + const auto pair = query.substr(0, amp); + query = amp == std::string_view::npos ? std::string_view{} : query.substr(amp + 1); + const auto equals = pair.find('='); + if (pair.substr(0, equals) != name) + continue; + const auto raw = + equals == std::string_view::npos ? std::string_view{} : pair.substr(equals + 1); + std::string out; + for (std::size_t i = 0; i < raw.size(); ++i) { + char ch = raw[i]; + if (ch == '+') { + ch = ' '; + } else if (ch == '%') { + unsigned value{}; + if (i + 2 >= raw.size() || + std::from_chars(raw.data() + i + 1, raw.data() + i + 3, value, 16).ptr != + raw.data() + i + 3) + return std::nullopt; + ch = static_cast(value); + i += 2; + } + if (static_cast(ch) < 0x20 || ch == 0x7F || out.size() >= limit) + return std::nullopt; + out.push_back(ch); + } + return out; + } + return std::nullopt; +} + std::optional http_get(std::string_view address, std::string_view path, std::chrono::milliseconds timeout, std::size_t limit) { const auto colon = address.rfind(':'); @@ -225,8 +259,14 @@ AdminApi::AdminApi(AdminConfig config, broker::TokenVerifier verifier, AdminConn OpsResponse AdminApi::handle(const ApiRequest& request, std::uint64_t now_seconds, std::chrono::steady_clock::time_point now) { - auto path = request.path.substr(0, request.path.find('?')); - if (request.method != "GET") + const auto mark = request.path.find('?'); + auto path = request.path.substr(0, mark); + const auto query = + mark == std::string_view::npos ? std::string_view{} : request.path.substr(mark + 1); + // Only the session window accepts POST; everything else is read-only. + if (request.method != "GET" && + !(request.method == "POST" && path.starts_with("/api/regions/") && + path.ends_with("/session-window"))) return {405, "method not allowed\n"}; if (path == "/healthz") return {200, "ok\n"}; @@ -255,10 +295,11 @@ OpsResponse AdminApi::handle(const ApiRequest& request, std::uint64_t now_second if (!claims) return error(claims.error() == TokenError::missing_role ? 403 : 401, token_error(claims.error())); - return api(path, *claims, now); + return api(request.method, path, query, *claims, now); } -OpsResponse AdminApi::api(std::string_view path, const broker::AccessTokenClaims& admin, +OpsResponse AdminApi::api(std::string_view method, std::string_view path, std::string_view query, + const broker::AccessTokenClaims& admin, std::chrono::steady_clock::time_point now) { if (path == "/api/me") return json(200, "{\"subject\":" + json_string(admin.subject) + @@ -280,6 +321,15 @@ OpsResponse AdminApi::api(std::string_view path, const broker::AccessTokenClaims region_prefix.size(), path.size() - region_prefix.size() - view_suffix.size())); return region ? view(*region, now) : error(404, "not_found"); } + constexpr std::string_view window_suffix = "/session-window"; + if (path.starts_with(region_prefix) && path.ends_with(window_suffix) && + path.size() > region_prefix.size() + window_suffix.size()) { + const auto region = number(path.substr( + region_prefix.size(), path.size() - region_prefix.size() - window_suffix.size())); + if (!region) + return error(404, "not_found"); + return method == "POST" ? set_window(*region, query, admin) : window(*region); + } return error(404, "not_found"); } @@ -335,11 +385,15 @@ OpsResponse AdminApi::accounts(std::optional account) { OpsResponse AdminApi::regions() { const auto world = std::to_string(config_.world); - const auto rows = query("SELECT region_id, frame_id, lease_epoch, lease_held, " - "floor(extract(epoch FROM lease_expires))::bigint, commit_sequence, " - "end_tick, floor(extract(epoch FROM committed_at))::bigint, " - "build_identity FROM evolution.admin_regions_v1($1)", - {world}); + const auto rows = + query("SELECT r.region_id, r.frame_id, r.lease_epoch, r.lease_held, " + "floor(extract(epoch FROM r.lease_expires))::bigint, r.commit_sequence, r.end_tick, " + "floor(extract(epoch FROM r.committed_at))::bigint, r.build_identity, " + "floor(extract(epoch FROM w.expires_at))::bigint, " + "coalesce(w.expires_at > clock_timestamp(), false) " + "FROM evolution.admin_regions_v1($1) r " + "LEFT JOIN LATERAL evolution.load_session_window_v1($1, r.region_id) w ON true", + {world}); if (!rows) return error(503, "unavailable"); std::string out = "{\"world\":" + world + ",\"regions\":["; @@ -355,11 +409,61 @@ OpsResponse AdminApi::regions() { ",\"sequence\":" + text_value(at(row, 5)) + ",\"tick\":" + text_value(at(row, 6)) + ",\"committed_at\":" + seconds_value(at(row, 7)) + ",\"build\":" + text_value(at(row, 8)) + + ",\"window_expires\":" + seconds_value(at(row, 9)) + + ",\"window_open\":" + (at(row, 10) == "t" ? "true" : "false") + ",\"viewable\":" + (viewable ? "true" : "false") + "}"; } return json(200, out + "]}\n"); } +OpsResponse AdminApi::window(std::uint64_t region) { + const std::vector key{std::to_string(config_.world), std::to_string(region)}; + const auto rows = query("SELECT sequence, activation_id, " + "floor(extract(epoch FROM expires_at))::bigint, author_subject, " + "reason, floor(extract(epoch FROM created_at))::bigint, " + "coalesce(expires_at > clock_timestamp(), false), " + "floor(extract(epoch FROM clock_timestamp()))::bigint " + "FROM evolution.admin_session_windows_v1($1, $2)", + key); + if (!rows) + return error(503, "unavailable"); + std::string out = "{\"region\":" + json_string(key[1]) + ",\"open\":" + + (!rows->empty() && at(rows->front(), 6) == "t" ? "true" : "false") + + ",\"history\":["; + for (std::size_t i = 0; i < rows->size(); ++i) { + const auto& row = (*rows)[i]; + out += std::string(i == 0 ? "" : ",") + "{\"sequence\":" + count_value(at(row, 0)) + + ",\"activation\":" + text_value(at(row, 1)) + + ",\"expires_at\":" + seconds_value(at(row, 2)) + + ",\"author\":" + text_value(at(row, 3)) + ",\"reason\":" + text_value(at(row, 4)) + + ",\"created_at\":" + seconds_value(at(row, 5)) + "}"; + } + return json(200, out + "]}\n"); +} + +OpsResponse AdminApi::set_window(std::uint64_t region, std::string_view query_text, + const broker::AccessTokenClaims& admin) { + const auto minutes_text = query_value(query_text, "minutes", 3); + const auto minutes = minutes_text ? number(*minutes_text) : std::nullopt; + if (!minutes || *minutes > 240) + return error(400, "bad_minutes"); + const auto reason = query_value(query_text, "reason"); + if (!reason && query_text.find("reason=") != std::string_view::npos) + return error(400, "bad_reason"); + // Who: the email for people reading the history, and the subject that identifies them. + auto author = admin.email.empty() ? admin.subject : admin.email + " (" + admin.subject + ")"; + if (author.size() > 255) + author = admin.subject; + const auto rows = query("SELECT activation_id, floor(extract(epoch FROM expires_at))::bigint " + "FROM evolution.admin_set_session_window_v1($1, $2, $3, $4, $5)", + {std::to_string(config_.world), std::to_string(region), + std::to_string(*minutes * 60), author, reason.value_or("")}); + if (!rows || rows->empty()) + return error(503, "unavailable"); + return json(200, "{\"activation\":" + text_value(at(rows->front(), 0)) + + ",\"expires_at\":" + seconds_value(at(rows->front(), 1)) + "}\n"); +} + OpsResponse AdminApi::view(std::uint64_t region, std::chrono::steady_clock::time_point now) { if (!std::ranges::contains(config_.view_regions, region)) return error(404, "not_viewable"); diff --git a/src/server/session/region_sessions.cpp b/src/server/session/region_sessions.cpp index b88c5e7..1b404d2 100644 --- a/src/server/session/region_sessions.cpp +++ b/src/server/session/region_sessions.cpp @@ -128,6 +128,7 @@ struct RegionSessions::Impl { Clock::time_point next_ghosts{}, next_overdue{}; std::optional default_interest; bool refuse_logins{}; // Load governor (ADR-0097). + bool admission_closed{}; // Session window closed (ADR-0087). std::uint64_t refused_load{}; // Grant logins refused for load. HostFacts facts; std::vector connections; @@ -264,6 +265,8 @@ struct RegionSessions::Impl { Clock::time_point now) { if (m.required_features != 0) return close(c, SessionCloseReason::protocol, now); + if (admission_closed) // No session window: before any signature work. + return close(c, SessionCloseReason::shutdown, now); if (!control.attempt(now_seconds)) // Region-wide, before signature work. return close(c, SessionCloseReason::rate_limited, now); if (network::looks_like_handoff_ticket(m.grant)) @@ -1079,6 +1082,14 @@ std::optional RegionSessions::holder(const network::AccountId& ac return impl_->control.holder(account); } +void RegionSessions::set_admission(bool open) noexcept { + impl_->admission_closed = !open; +} + +bool RegionSessions::admitting() const noexcept { + return !impl_->admission_closed; +} + void RegionSessions::set_load(bool refuse_logins, std::uint8_t shed) { impl_->refuse_logins = refuse_logins; impl_->replication.set_shed(shed); diff --git a/tests/grant_broker_tests.cpp b/tests/grant_broker_tests.cpp index 146a288..23d21ec 100644 --- a/tests/grant_broker_tests.cpp +++ b/tests/grant_broker_tests.cpp @@ -383,7 +383,7 @@ void admin_api_tests(const Realm& realm) { *TokenVerifier::from_jwks(realm.jwks("sig-1"), admin_rules), [&, online]() -> std::unique_ptr { ++connects; - return online ? connect_as(env("EVO_PG_RUNTIME_USER")) : nullptr; + return online ? connect_as(env("EVO_PG_ADMIN_USER")) : nullptr; }, [&](std::uint64_t region) -> std::optional { ++fetches; @@ -477,9 +477,86 @@ void admin_api_tests(const Realm& realm) { CHECK(offline.handle({"GET", "/api/accounts", admin}, now, t0).status == 503); CHECK(offline.handle({"GET", "/api/regions", admin}, now, t0).status == 503); - // The read views are the only way in: the runtime role still cannot read the tables. + // Session windows (schema 62): none yet, so sessions are closed. + const auto window_of = [&](std::string_view id) { + return must(JsonValue::parse( + get("/api/regions/" + std::string(id) + "/session-window", admin).body)); + }; + const auto post = [&](std::string_view target) { + return api.handle({"POST", target, admin}, now, t0); + }; + CHECK(window_of("1").member("open")->boolean() == false && + window_of("1").member("history")->array()->empty()); + for (const std::string_view bad : + {"/api/regions/1/session-window", "/api/regions/1/session-window?minutes=241", + "/api/regions/1/session-window?minutes=x", "/api/regions/1/session-window?minutes=1000", + "/api/regions/1/session-window?minutes=60&reason=%zz", + "/api/regions/1/session-window?minutes=60&reason=a%0Ab"}) + CHECK(post(bad).status == 400); + CHECK( + api.handle({"POST", "/api/regions/1/session-window?minutes=60", player}, now, t0).status == + 403); + CHECK(post("/api/accounts").status == 405 && post("/api/regions/1/view").status == 405); + CHECK(post("/api/regions/2/session-window?minutes=60").status == 503); // No such region. + + // Open for an hour, with a reason; the region list and the history show it. + const auto opened = post("/api/regions/1/session-window?minutes=60&reason=Playtest+A%21"); + CHECK(opened.status == 200); + const auto first = must(JsonValue::parse(opened.body)); + const auto first_id = std::string(must(first.member("activation")->string())); + CHECK(first_id.starts_with("adm-") && first.member("expires_at")->integer()); + const auto open_now = window_of("1"); + const auto& latest = open_now.member("history")->array()->at(0); + CHECK(open_now.member("open")->boolean() == true && + latest.member("activation")->string() == first_id && + latest.member("author")->string() == "ops@example.test (ops)" && + latest.member("reason")->string() == "Playtest A!" && + latest.member("expires_at")->integer() == first.member("expires_at")->integer()); + const auto listed_regions = must(JsonValue::parse(get("/api/regions", admin).body)); + CHECK(listed_regions.member("regions")->array()->at(0).member("window_open")->boolean() == + true); + + // Extending writes a new activation; closing writes a closing row. Rows never change. + const auto extended = + must(JsonValue::parse(post("/api/regions/1/session-window?minutes=240").body)); + CHECK(extended.member("activation")->string() != first_id); + CHECK(post("/api/regions/1/session-window?minutes=0&reason=done").status == 200); + const auto closed_now = window_of("1"); + CHECK(closed_now.member("open")->boolean() == false && + closed_now.member("history")->array()->size() == 3 && + closed_now.member("history")->array()->at(0).member("expires_at")->kind() == + JsonValue::Kind::null); + + // The region reads only the newest row; the table refuses rewrites and long windows. auto runtime = connect_as(env("EVO_PG_RUNTIME_USER")); + const auto current = runtime->query( + "SELECT activation_id, expires_at IS NULL FROM evolution.load_session_window_v1(9831, 1)", + {}, 5s); + CHECK(current && current->size() == 1 && (*current)[0][1] == "t"); + CHECK(!runtime->query( + "SELECT * FROM evolution.admin_set_session_window_v1(9831, 1, 60, 'x', '')", {}, 5s)); + runtime = connect_as(env("EVO_PG_RUNTIME_USER")); + CHECK(!runtime->query("SELECT * FROM evolution.admin_accounts_v1(9831)", {}, 5s)); + auto owner = connect_as(env("PGUSER")); + CHECK(!owner->query("UPDATE evolution.session_windows SET reason = 'x'", {}, 5s)); + owner = connect_as(env("PGUSER")); + CHECK(!owner->query("DELETE FROM evolution.session_windows", {}, 5s)); + owner = connect_as(env("PGUSER")); + CHECK(!owner->query("INSERT INTO evolution.session_windows(world_id, region_id, " + "activation_id, expires_at, author_subject) VALUES (9831, 1, 'long', " + "clock_timestamp() + interval '5 hours', 'x')", + {}, 5s)); + owner = connect_as(env("PGUSER")); + CHECK(!owner->query( + "SELECT * FROM evolution.admin_set_session_window_v1(9831, 1, 14401, 'x', '')", {}, 5s)); + + // The read views are the only way in: the runtime role still cannot read the tables. + runtime = connect_as(env("EVO_PG_RUNTIME_USER")); CHECK(!runtime->query("SELECT count(*) FROM evolution.life_reservations", {}, 5s)); + CHECK(!runtime->query("SELECT count(*) FROM evolution.session_windows", {}, 5s)); + CHECK(server::admin::query_value("a=1&reason=x%20y+z&b=2", "reason") == "x y z" && + !server::admin::query_value("a=1", "reason") && + !server::admin::query_value("reason=abc", "reason", 2)); CHECK(server::admin::json_string("a\"b\\c\n\x01") == "\"a\\\"b\\\\c\\u000a\\u0001\""); } } // namespace diff --git a/tests/region_migration_tests.cpp b/tests/region_migration_tests.cpp index a561b30..1711efe 100644 --- a/tests/region_migration_tests.cpp +++ b/tests/region_migration_tests.cpp @@ -227,6 +227,7 @@ void upgrade_across_migration_and_barrier() { " -v migration_sha_59=$(s 0059_durable_mutation_queue.sql)" " -v migration_sha_60=$(s 0060_cellular_revamp_bundle.sql)" " -v migration_sha_61=$(s 0061_admin_read_views.sql)" + " -v migration_sha_62=$(s 0062_session_windows.sql)" " -v runtime_role=evo_runtime_test -f migrations/apply.sql" " > /dev/null 2>&1") != 0); CHECK(history(*owner_db) == "1,2,3,4,5,6,7"); @@ -244,7 +245,7 @@ void upgrade_across_migration_and_barrier() { "tools/migrate-postgres.sh\" > /dev/null") == 0); CHECK(history(*owner_db) == "1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24," "25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46," - "47,48,49,50,51,52,53,54,55,56,57,58,59,60,61"); + "47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62"); CHECK(scalar(*owner_db, "SELECT (c.condeferrable AND c.condeferred AND " "c.confrelid = 'evolution.region_commits'::regclass)::text " "FROM pg_catalog.pg_constraint c WHERE c.conrelid = " diff --git a/tests/session_window_tests.cpp b/tests/session_window_tests.cpp index 0269e10..006366d 100644 --- a/tests/session_window_tests.cpp +++ b/tests/session_window_tests.cpp @@ -1,5 +1,6 @@ #include "evo/server/session_window.hpp" #include +#include #include using evo::server::SessionWindow; @@ -52,5 +53,32 @@ int main() { CHECK(close.has_value()); close->close(); CHECK(!close->accepting(1'001)); + + // ADR-0087 amendment: the database feed. No record keeps sessions closed. + using Feed = evo::server::SessionWindowFeed; + using Change = Feed::Change; + Feed feed; + CHECK(feed.observe(std::nullopt, now) == Change::none && !feed.accepting(now)); + CHECK(feed.observe(Feed::Record{"adm-1", 1'200}, now) == Change::opened); + const auto& admitted = feed.window(); + CHECK(feed.accepting(1'100) && admitted && admitted->deadline_seconds() == 1'200); + // Re-reading the same record changes nothing; a newer activation extends. + CHECK(feed.observe(Feed::Record{"adm-1", 1'200}, 1'150) == Change::none); + CHECK(feed.observe(Feed::Record{"adm-2", 5'000}, 1'150) == Change::opened); + CHECK(feed.accepting(1'250) && admitted && admitted->activation_id() == "adm-2"); + // Its own deadline still closes it, and the same record cannot reopen it. + CHECK(!feed.accepting(5'000)); + CHECK(feed.observe(Feed::Record{"adm-2", 5'000}, 4'000) == Change::none); + CHECK(!feed.accepting(4'001)); + // A closing record closes; an expired or over-long newer one is refused and stays closed. + CHECK(feed.observe(Feed::Record{"adm-3", 9'000}, 6'000) == Change::opened); + CHECK(feed.observe(Feed::Record{"adm-4", std::nullopt}, 6'001) == Change::closed); + CHECK(!feed.accepting(6'002)); + CHECK(feed.observe(Feed::Record{"adm-5", 6'000}, 6'010) == Change::refused); + CHECK(feed.observe(Feed::Record{"adm-6", 6'010 + 14'401}, 6'010) == Change::refused); + CHECK(!feed.accepting(6'011)); + // A record that disappears (a restored database) closes the window. + CHECK(feed.observe(Feed::Record{"adm-7", 7'000}, 6'100) == Change::opened); + CHECK(feed.observe(std::nullopt, 6'101) == Change::closed && !feed.accepting(6'102)); return 0; } diff --git a/tools/backup/verify-backup.sh b/tools/backup/verify-backup.sh index 1ced4bc..d27ba38 100644 --- a/tools/backup/verify-backup.sh +++ b/tools/backup/verify-backup.sh @@ -17,6 +17,8 @@ # The cluster and its files are removed on exit unless --keep. Binaries come from # EVO_WORLD_CLONE_BIN / EVO_SERVER_BIN or PATH. Port: EVO_VERIFY_PORT (55499). set -euo pipefail +# The private cluster has only its own roles: no admin role grants (ADR-0182) apply here. +unset EVO_PG_ADMIN_ROLE usage() { echo "usage: $0 BUNDLE [--isolate WORLD [--source-world W]] [--keep]" >&2; exit 2; } [ $# -ge 1 ] || usage bundle="$(realpath -- "$1")"; shift diff --git a/tools/ci/deploy-policy-check.py b/tools/ci/deploy-policy-check.py index 88c9b56..1ac0db7 100644 --- a/tools/ci/deploy-policy-check.py +++ b/tools/ci/deploy-policy-check.py @@ -44,8 +44,9 @@ import re # restart after expiry, delayed application, extend/close races, clock movement, # synthetic inputs stopping while commits drain). The runtime contract and focused # expiry tests are now implemented in the M10 QUIC -# bridge. The route remains constrained to the dev overlay and a committed absolute -# window; delayed application fails closed in the server. +# bridge. The route remains constrained to the dev overlay. Since the ADR-0087 amendment of +# 2026-10-27 the window lives in SQL (evolution.session_windows, set from the admin portal) +# and the region re-reads it; Git carries no window. ROUTE_ENABLING_PERMITTED = True # Addresses the route may use: RFC 1918 plus internal ranges the maintainer has # explicitly approved in ADR-0087 (none yet; the cluster LAN 172.10.0.0/16 is not @@ -703,22 +704,11 @@ for overlay, docs in renders.items(): check(env.get('REGION_SESSION_LISTEN') == listen, f'{where}: REGION_SESSION_LISTEN must be {listen} (route {"on" if route_active else "off"})') check(text.count('--m10-listen') == 1 and '--m10-listen "$REGION_SESSION_LISTEN"' in text - and '--session-window "$REGION_SESSION_WINDOW"' in text, - f'{where}: one M10 listener and absolute session window, addressed only by GitOps env') - # The server refuses a window ending more than 4 h after it starts - # (SessionWindow::max_duration_seconds) and exits in a loop. The id carries - # its UTC activation (dev-YYYYMMDDTHHMMSS-...); the expiry must fall within - # 4 h of it. Checked here because the server sees it only at startup. - window = env.get('REGION_SESSION_WINDOW') or '' - if route_active and window: - import calendar, re, time - m = re.fullmatch(r'[0-9A-Za-z._-]*?(\d{8}T\d{6})Z?[0-9A-Za-z._-]*:(\d+)', window) - ok = False - if m: - start = calendar.timegm(time.strptime(m.group(1), '%Y%m%dT%H%M%S')) - ok = start < int(m.group(2)) <= start + 4 * 60 * 60 - check(ok, f'{where}: REGION_SESSION_WINDOW must name its UTC activation and end ' - 'within 4 h of it (the server maximum)') + and '--session-window-source db' in text and '--session-window ' not in text, + f'{where}: one M10 listener whose session window is read from SQL (ADR-0087)') + # The window lives in SQL; a Git-committed one would never be read. + check('REGION_SESSION_WINDOW' not in env, + f'{where}: the session window lives in SQL, not in REGION_SESSION_WINDOW') else: check('--m10-listen' not in text and '--synthetic-inputs' not in text, f'{where}: only evo-server may listen for sessions') diff --git a/tools/ci/deploy-policy-selftest.py b/tools/ci/deploy-policy-selftest.py index e1c6da0..44e77ec 100644 --- a/tools/ci/deploy-policy-selftest.py +++ b/tools/ci/deploy-policy-selftest.py @@ -132,14 +132,14 @@ CASES = [ ('non-RFC 1918 VIP without approval', lambda t: edit(t, ROUTE + 'service.yaml', '172.10.1.202', '172.11.1.210'), 'internal address'), # Review M9.8f P1: inline/JSON patches and namespace changes, seen only when rendered. - ('session window longer than the server maximum', lambda t: inline_patch( + ('session window committed to Git again', lambda t: inline_patch( t, 'deploy/kubernetes/dev/kustomization.yaml', env_patch('REGION_SESSION_WINDOW', 'dev-20261008T111342-32432:1791477222')), - 'end within 4 h of it'), - ('session window without an activation time', lambda t: inline_patch( - t, 'deploy/kubernetes/dev/kustomization.yaml', - env_patch('REGION_SESSION_WINDOW', 'dev-manual:1791477222')), - 'end within 4 h of it'), + 'the session window lives in SQL'), + ('fixed session window argument', lambda t: edit( + t, 'deploy/kubernetes/region/base/deployment.yaml', '--session-window-source db', + '--session-window "$REGION_SESSION_LISTEN"'), + 'session window is read from SQL'), ('inline patch: synthetic inputs on', lambda t: inline_patch( t, 'deploy/kubernetes/dev/kustomization.yaml', env_patch('REGION_INPUTS', 'development-v1')), 'sessions must be dev only with the route'), @@ -155,7 +155,7 @@ CASES = [ {'kind': 'Deployment', 'name': 'evo-region'}), 'container ports must be'), ('JSON patch: second listener argument', lambda t: inline_patch( t, DEV, '- op: add\n path: /spec/template/spec/containers/0/args/-\n value: --m10-listen 0.0.0.0:7401\n', - {'kind': 'Deployment', 'name': 'evo-region'}), 'one M10 listener and absolute session window'), + {'kind': 'Deployment', 'name': 'evo-region'}), 'one M10 listener whose session window is read from SQL'), ('namespace transformation', lambda t: edit(t, DEV, 'namespace: evolution-dev', 'namespace: evolution-stage'), 'expected evolution-dev'), ('inline quota patch in stage', lambda t: inline_patch( diff --git a/tools/ci/history-domain-check.sh b/tools/ci/history-domain-check.sh index 8f33789..3fbcc1d 100644 --- a/tools/ci/history-domain-check.sh +++ b/tools/ci/history-domain-check.sh @@ -75,6 +75,10 @@ awk '/^CREATE FUNCTION evolution\.(publish_cellular_checkpoint|publish_cellular_ awk '/^CREATE OR REPLACE FUNCTION evolution\.valid_cellular_action_input\(/ {capture=1} capture {print} capture && /^END \$\$;/ {capture=0}' \ "$root/migrations/0036_cellular_v5_budding_bundle.sql" | sql > /dev/null sql -v runtime_role="$EVO_PG_RUNTIME_ROLE" > /dev/null <<'SQL' +DROP FUNCTION evolution.admin_session_windows_v1(evolution.u64,evolution.u64); +DROP FUNCTION evolution.admin_set_session_window_v1(evolution.u64,evolution.u64,integer,text,text); +DROP FUNCTION evolution.load_session_window_v1(evolution.u64,evolution.u64); +DROP TABLE evolution.session_windows; DROP FUNCTION evolution.admin_regions_v1(evolution.u64); DROP FUNCTION evolution.admin_account_lives_v1(evolution.u64,uuid); DROP FUNCTION evolution.admin_accounts_v1(evolution.u64); diff --git a/tools/ci/postgres-check.sh b/tools/ci/postgres-check.sh index 035e34e..6e826be 100644 --- a/tools/ci/postgres-check.sh +++ b/tools/ci/postgres-check.sh @@ -71,6 +71,10 @@ fi psql -X -v ON_ERROR_STOP=1 -c 'CREATE ROLE evo_runtime_test NOLOGIN' \ -c 'CREATE ROLE evo_runtime_login LOGIN IN ROLE evo_runtime_test' export EVO_PG_RUNTIME_ROLE=evo_runtime_test EVO_PG_RUNTIME_USER=evo_runtime_login +# ADR-0182: the admin API's own group role and login, outside the runtime group. +psql -X -v ON_ERROR_STOP=1 -c 'CREATE ROLE evo_admin_test NOLOGIN' \ + -c 'CREATE ROLE evo_admin_login LOGIN IN ROLE evo_admin_test' +export EVO_PG_ADMIN_ROLE=evo_admin_test EVO_PG_ADMIN_USER=evo_admin_login phase migrate bash "$root/tools/migrate-postgres.sh" bash "$root/tools/migrate-postgres.sh" # exact supported upgrade/restart is a no-op @@ -168,7 +172,7 @@ PGDATABASE=upgrade_path psql -X -v ON_ERROR_STOP=1 -1 -v "migration_sha=$v1_sha" -f "$root/migrations/0001_region_bootstrap.sql" > /dev/null test "$(PGDATABASE=upgrade_path psql -XAtc "SELECT string_agg(version::text, ',') FROM evolution.schema_migrations")" = 1 PGDATABASE=upgrade_path bash "$root/tools/migrate-postgres.sh" -test "$(PGDATABASE=upgrade_path psql -XAtc "SELECT string_agg(version::text, ',' ORDER BY version) FROM evolution.schema_migrations")" = 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61 +test "$(PGDATABASE=upgrade_path psql -XAtc "SELECT string_agg(version::text, ',' ORDER BY version) FROM evolution.schema_migrations")" = 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62 # v2 heads have no payload binding: v2->v3 fails closed and leaves history at v2. v2_sha="$(sha256sum "$root/migrations/0002_region_fencing.sql")" v2_sha="${v2_sha%% *}" @@ -189,7 +193,7 @@ PGDATABASE=v3_commits psql -X -v ON_ERROR_STOP=1 \ -c "INSERT INTO evolution.retained_builds VALUES (decode(repeat('b1', 32), 'hex'))" \ -c "SELECT evolution.provision_region_checkpoint(decode('4145564f52434d31' || '01000000' || '01000000' || '0100000000000000' || '0100000000000000' || '0900000000000000' || repeat('11', 16) || repeat('00', 8) || repeat('00', 16) || repeat('00', 32) || repeat('00', 16) || repeat('00', 16) || repeat('00', 8) || '50c3000000000000' || '020000000200000001000000010000000100000001000000010000000100000001000000' || repeat('b1', 32) || '00000000' || '00000000' || '01000000' || '6400000000000000' || repeat('a0', 32), 'hex'))" > /dev/null PGDATABASE=v3_commits bash "$root/tools/migrate-postgres.sh" -test "$(PGDATABASE=v3_commits psql -XAtc "SELECT count(*) || ':' || string_agg(version::text, ',' ORDER BY version) FROM evolution.schema_migrations")" = 61:1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61 +test "$(PGDATABASE=v3_commits psql -XAtc "SELECT count(*) || ':' || string_agg(version::text, ',' ORDER BY version) FROM evolution.schema_migrations")" = 62:1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62 test "$(PGDATABASE=v3_commits psql -XAtc "SELECT count(*) FROM evolution.region_commits")" = 1 # Review P1: a v4 database holding a published (possibly terminal) checkpoint has # no durable decisions for it. The v5 upgrade must refuse before changing anything. @@ -243,7 +247,7 @@ PGDATABASE=v6_populated psql -X -v ON_ERROR_STOP=1 \ -c "INSERT INTO evolution.retained_builds VALUES (decode(repeat('b1', 32), 'hex'))" \ -c "SELECT evolution.provision_region_checkpoint(decode('4145564f52434d31' || '02000000' || '01000000' || '0100000000000000' || '0100000000000000' || '0900000000000000' || repeat('11', 16) || repeat('00', 8) || repeat('00', 16) || repeat('00', 32) || repeat('00', 16) || repeat('00', 16) || repeat('00', 8) || '50c3000000000000' || '020000000200000001000000010000000100000001000000010000000100000001000000' || repeat('b1', 32) || '00000000' || '00000000' || '01000000' || '6400000000000000' || repeat('a0', 32) || repeat('00', 80), 'hex'))" > /dev/null PGDATABASE=v6_populated bash "$root/tools/migrate-postgres.sh" -test "$(PGDATABASE=v6_populated psql -XAtc "SELECT string_agg(version::text, ',' ORDER BY version) FROM evolution.schema_migrations")" = 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61 +test "$(PGDATABASE=v6_populated psql -XAtc "SELECT string_agg(version::text, ',' ORDER BY version) FROM evolution.schema_migrations")" = 1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62 test "$(PGDATABASE=v6_populated psql -XAtc "SELECT count(*) FROM evolution.region_commits c, LATERAL evolution.parse_checkpoint_manifest(c.manifest) m WHERE m.commit_sequence = 0 AND m.predecessor_commit IS NULL")" = 1 test "$(PGDATABASE=v6_populated psql -XAtc "SELECT string_agg(conname, ',') FROM pg_constraint WHERE conrelid = 'evolution.region_heads'::regclass AND contype = 'c' AND pg_get_constraintdef(oid) LIKE '%end_tick%'")" = region_heads_published_tick phase permission-audit @@ -301,9 +305,9 @@ expect_audit_failure 'REVOKE EXECUTE ON FUNCTION evolution.load_world_cellular_m expect_audit_failure 'GRANT EXECUTE ON FUNCTION evolution.fork_restored_history_v1(uuid) TO evo_runtime_test' 'REVOKE EXECUTE ON FUNCTION evolution.fork_restored_history_v1(uuid) FROM evo_runtime_test' phase checksum-drift # Unknown future versions and checksum drift must not be repaired silently. -psql -X -v ON_ERROR_STOP=1 -c 'UPDATE evolution.schema_migrations SET version=62 WHERE version=61' +psql -X -v ON_ERROR_STOP=1 -c 'UPDATE evolution.schema_migrations SET version=63 WHERE version=62' if bash "$root/tools/migrate-postgres.sh"; then exit 1; fi -psql -X -v ON_ERROR_STOP=1 -c "UPDATE evolution.schema_migrations SET version=61 WHERE version=62" +psql -X -v ON_ERROR_STOP=1 -c "UPDATE evolution.schema_migrations SET version=62 WHERE version=63" psql -X -v ON_ERROR_STOP=1 -c "UPDATE evolution.schema_migrations SET sha256=repeat('0',64) WHERE version=14" if bash "$root/tools/migrate-postgres.sh"; then exit 1; fi psql -X -v ON_ERROR_STOP=1 -c "UPDATE evolution.schema_migrations SET sha256=repeat('0',64) WHERE version=13" diff --git a/tools/migrate-postgres.sh b/tools/migrate-postgres.sh index 0e5539a..f53d365 100644 --- a/tools/migrate-postgres.sh +++ b/tools/migrate-postgres.sh @@ -3,6 +3,10 @@ set -euo pipefail root="$(cd "$(dirname "$0")/.." && pwd)" # Operator-created NOLOGIN group role granted to the region runtime login (ADR-0060). runtime_role="${EVO_PG_RUNTIME_ROLE:?set EVO_PG_RUNTIME_ROLE to the runtime group role}" +# Optional operator-created NOLOGIN group role of the admin API's login (ADR-0182): when set, +# every run grants it exactly the admin functions and audits it. +admin=() +if [ -n "${EVO_PG_ADMIN_ROLE:-}" ]; then admin=(--set="admin_role=$EVO_PG_ADMIN_ROLE"); fi if [ -n "${EVO_PGPASS_SOURCE:-}" ]; then umask 077 export PGPASSFILE @@ -134,6 +138,8 @@ digest_60="$(sha256sum "$root/migrations/0060_cellular_revamp_bundle.sql")" digest_60="${digest_60%% *}" digest_61="$(sha256sum "$root/migrations/0061_admin_read_views.sql")" digest_61="${digest_61%% *}" +digest_62="$(sha256sum "$root/migrations/0062_session_windows.sql")" +digest_62="${digest_62%% *}" psql -X --no-password --set=ON_ERROR_STOP=1 --set="migration_sha=$digest" \ --set="migration_sha_2=$digest_2" --set="migration_sha_3=$digest_3" \ --set="migration_sha_4=$digest_4" --set="migration_sha_5=$digest_5" \ @@ -183,5 +189,6 @@ psql -X --no-password --set=ON_ERROR_STOP=1 --set="migration_sha=$digest" \ --set="migration_sha_55=$digest_55" --set="migration_sha_56=$digest_56" \ --set="migration_sha_57=$digest_57" --set="migration_sha_58=$digest_58" --set="migration_sha_59=$digest_59" \ --set="migration_sha_60=$digest_60" --set="migration_sha_61=$digest_61" \ + --set="migration_sha_62=$digest_62" "${admin[@]}" \ --set="runtime_role=$runtime_role" \ --file="$root/migrations/apply.sql" diff --git a/tools/ops/load-drill.sh b/tools/ops/load-drill.sh index dfd2e7b..e0e99d6 100644 --- a/tools/ops/load-drill.sh +++ b/tools/ops/load-drill.sh @@ -90,16 +90,14 @@ restore() { } world="$(env_of REGION_WORLD)" region="$(env_of REGION_ID)" frame="$(env_of REGION_FRAME)" -window="$(env_of REGION_SESSION_WINDOW)" [ -n "$world" ] && [ -n "$region" ] && [ -n "$frame" ] || fail "cannot read the region identity" [ -z "$(env_of REGION_INPUTS)" ] || fail "REGION_INPUTS is already set: another drill may be running" -# The drill must end before the session window closes. +# The drill must end before the session window closes: the window is in SQL (ADR-0087 +# amendment), so open it in the admin portal for at least the drill's duration first. count=$(echo "$steps" | tr ',' '\n' | wc -l) most=$(echo "$steps" | tr ',' '\n' | sort -n | tail -1) needed=$(( count * (hold + warmup + most / 10 + 5) + 600 )) -expiry="${window##*:}" -[ -n "$expiry" ] && [ "$expiry" -gt $(( $(date -u +%s) + needed )) ] 2> /dev/null || - fail "the session window ($window) closes within the drill's ${needed} s: renew it first" +say "the drill needs about ${needed} s of open session window (admin portal)" size=$(wc -c < "$tokens/load-grants.bin") [ $(( size / 160 )) -ge $(( most * per_bot )) ] || fail "load-grants.bin holds $(( size / 160 )) grants; $most bots x $per_bot need $(( most * per_bot ))"