Files
dingoandClaude Opus 5.5 6de2b7b1ca
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (checks) (push) Successful in 6s
Foundation / checks (deploy) (push) Successful in 6s
Foundation / checks (ecs) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 4s
Foundation / checks (tsan) (push) Successful in 5s
Foundation / postgres-tools (push) Successful in 5m17s
Foundation / image (push) Successful in 6m23s
Foundation / server-image (push) Successful in 8m26s
feat(admin): end a stranded life from the portal (schema 69)
ADR-0182 section 18. Region 16 refused every birth for an account with
"Existing cell is already bound to this account" although no cell in it
held the account: a published reservation was never ended, and the only
remedy was tools/ops/end-account-life.sql as the database owner.

- Account action POST /api/accounts/<uuid>/end-life?request=N. The admin
  API reads the life's region from the account's lives and refuses while
  that region's live view lists a cell holding the account (also a bud,
  split offspring or organism control moved to), a region it cannot view,
  an incomplete view, an unpublished request or a life no longer open.
- Schema 69: admin_end_account_life_v1 (admin role only) ends it at the
  region's latest commit and appends who and why to admin_life_endings.
- The account page shows End life for each published life not ended.
- A region refusing a birth because the account holds a cell (life_exists)
  could never record it: reject_primitive_life accepted reasons 1..3 only.
  The reservation stayed open and unpublished and refused every later
  birth. Schema 69 and the C++ wrapper accept existing_life (4).
- A region with no ticking cells ignored queued admin commands (such as a
  spawn) until something else woke it; a queued command now keeps it
  ticking until applied.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 07:32:08 -04:00

174 lines
10 KiB
C++

#pragma once
#include "evo/persistence/postgres.hpp"
#include "evo/server/admin/https_client.hpp"
#include "evo/server/broker/access_token.hpp"
#include "evo/server/ops_http.hpp"
#include <chrono>
#include <cstdint>
#include <functional>
#include <map>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
// ADR-0182 read-only admin API and portal host. One world; every /api route needs a Keycloak
// access token carrying the admin realm role. The portal's static files and its OIDC settings
// are public; they carry no secret.
//
// GET /healthz ok
// GET / and the portal's files the portal (index.html, app.js, style.css)
// GET /config.json issuer, client id and world for the portal's sign-in
// GET /api/me the signed-in admin's subject and email
// GET /api/accounts every account with session, lives, deaths and resets
// GET /api/accounts/<uuid> one account, its life requests and ban history
// POST /api/accounts/<uuid>/ban?banned=1|0[&reason=R] bans (and logs out) or lifts a ban
// POST /api/accounts/<uuid>/logout ends the account's sessions now
// POST /api/accounts/<uuid>/end-life?request=N[&reason=R]
// ends a stranded published life (its reservation was
// never ended), refused while a cell in its region still
// holds the account (ADR-0182 section 18)
// GET /api/regions the world's regions, leases and heads
// GET /api/regions/<n>/view the region's live view (render_cellular_admin_view)
// GET /api/regions/<n>/session-window the current session window and its last changes
// POST /api/regions/<n>/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.
// GET /api/regions/<n>/commands the region's last admin commands and where they applied
// POST /api/regions/<n>/commands?kind=K[&count=N][&target=ID][&energy=PJ][&carbon=FG]
// [&nitrogen=FG][&phosphorus=FG][&other=FG][&reason=R]
// queues a command (remove_cell, grant_reserve,
// add_bubbles, add_pool, release_pool, spawn_wildlife)
// GET /api/regions/<n>/schedules the region's resource schedules (schema 65)
// POST /api/regions/<n>/schedules?kind=K&count=N&interval=S[&id=ID][&enabled=0|1]
// [&energy=PJ][&carbon=FG]...[&reason=R]
// creates (no id) or replaces a schedule repeating
// add_bubbles, release_pool or spawn_wildlife
// GET /api/tuning the world's rules-13 tuning revisions, the newest text,
// the baseline file regions opened with (schema 66) and
// the region tuning file they restart with (read only)
// GET /api/tuning/<revision> one revision's text
// POST /api/tuning[?check=1][&reason=R] the request body is a tuning text (the Git
// revamp file format): checked, then stored as a new
// revision that every region of the world adopts at its
// next tick (check=1: checked only, nothing stored)
// POST /api/tuning?base=baseline|REV[&check=1][&reason=R] the body holds only changed
// `key = value` lines, applied to the baseline file or to
// revision REV (which must be the newest: 409 stale_base),
// keeping its comments; then as above
// GET /api/deploy[?argo=1] ADR-0182 section 15: whether opening a region is
// configured, the region Git main serves, the next region
// and its seeded wildlife range, and the Argo Application's
// sync (argo=1: the Argo status only)
// POST /api/deploy/region?region=N[&reason=R] opens region N (the next one) in place of
// the served region: one Gitea commit to the region,
// broker and portal files, then a full Argo sync
namespace evo::server::admin {
struct AdminAsset {
std::string path; // "/index.html", ...; "/" serves "/index.html".
std::string content_type, body;
};
struct AdminConfig {
std::uint64_t world{};
// The world's regions: their live view can be fetched and they adopt tuning revisions.
std::vector<std::uint64_t> view_regions;
// The revamp tuning file the world's regions opened with (empty: unknown).
std::string baseline_tuning;
// The region tuning file (shape, movement, currents) they read at startup (empty: unknown).
std::string region_tuning;
std::string portal_config_json; // Served at /config.json.
std::string content_security_policy; // Sent with every portal file.
std::chrono::milliseconds db_timeout{3000};
std::chrono::milliseconds view_cache{750}; // A fetched view answers repeats this long.
};
// ADR-0182 section 15: where the admin API commits a region switch and what it syncs. The
// tokens come from mounted Secret files and are only ever sent in request headers.
struct AdminDeployConfig {
std::string gitea_base; // https://git.example[:port][/prefix]
std::string gitea_repository; // owner/name
std::string gitea_token;
std::string branch{"main"};
std::string argo_server; // host:port, https assumed
std::string argo_application;
std::string argo_token;
bool argo_verify{true};
};
using AdminConnect = std::function<std::unique_ptr<persistence::Postgres>()>;
// The region's /admin/view body, or nullopt when it cannot be reached or is not ready.
using AdminRegionView = std::function<std::optional<std::string>(std::uint64_t region)>;
class AdminApi {
public:
AdminApi(AdminConfig config, broker::TokenVerifier verifier, AdminConnect connect,
AdminRegionView view, std::vector<AdminAsset> assets);
// `now_seconds` is wall time (token expiry); `now` paces the view cache.
[[nodiscard]] OpsResponse handle(const ApiRequest& request, std::uint64_t now_seconds,
std::chrono::steady_clock::time_point now);
// Turns on /api/deploy with the given services and transport (tests pass a fake).
void enable_deploy(AdminDeployConfig config, HttpsTransport transport);
private:
[[nodiscard]] OpsResponse api(std::string_view method, std::string_view path,
std::string_view query, std::string_view body,
const broker::AccessTokenClaims& admin,
std::chrono::steady_clock::time_point now);
[[nodiscard]] OpsResponse accounts(std::optional<std::string_view> account);
[[nodiscard]] OpsResponse account_action(std::string_view account, std::string_view action,
std::string_view query,
const broker::AccessTokenClaims& admin);
[[nodiscard]] OpsResponse end_life(std::string_view account, std::string_view query,
const broker::AccessTokenClaims& admin);
[[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 commands(std::uint64_t region);
[[nodiscard]] OpsResponse schedules(std::uint64_t region);
[[nodiscard]] OpsResponse set_schedule(std::uint64_t region, std::string_view query,
const broker::AccessTokenClaims& admin);
[[nodiscard]] OpsResponse enqueue(std::uint64_t region, std::string_view query,
const broker::AccessTokenClaims& admin);
[[nodiscard]] OpsResponse set_window(std::uint64_t region, std::string_view query,
const broker::AccessTokenClaims& admin);
[[nodiscard]] OpsResponse tuning();
[[nodiscard]] OpsResponse tuning_text(std::uint64_t revision);
[[nodiscard]] OpsResponse set_tuning(std::string_view query, std::string_view text,
const broker::AccessTokenClaims& admin);
[[nodiscard]] OpsResponse deploy_status(std::string_view query);
[[nodiscard]] OpsResponse open_region(std::string_view query,
const broker::AccessTokenClaims& admin);
[[nodiscard]] std::optional<std::uint64_t> next_region(std::uint64_t served);
[[nodiscard]] std::optional<persistence::PgRows> query(const std::string& sql,
std::vector<std::string> parameters);
AdminConfig config_;
broker::TokenVerifier verifier_;
AdminConnect connect_;
AdminRegionView view_;
std::vector<AdminAsset> assets_;
std::optional<AdminDeployConfig> deploy_;
HttpsTransport https_;
std::unique_ptr<persistence::Postgres> db_;
struct CachedView {
std::chrono::steady_clock::time_point at;
std::string body;
};
std::map<std::uint64_t, CachedView> views_;
};
// Bounded blocking HTTP/1.1 GET of `path` from "host:port" (a name is resolved): the body of
// a 200 answer of at most `limit` bytes, or nullopt on any error, other status or timeout.
[[nodiscard]] std::optional<std::string> http_get(std::string_view address, std::string_view path,
std::chrono::milliseconds timeout,
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<std::string> query_value(std::string_view query, std::string_view name,
std::size_t limit = 200);
} // namespace evo::server::admin