Files
aevolution/include/evo/server/admin/admin_api.hpp
T
dingoandClaude Opus 5.5 9b854e6960
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 5s
Foundation / checks (deploy) (push) Successful in 4m31s
Foundation / postgres-tools (push) Successful in 27s
Foundation / server-image (push) Successful in 4m33s
Foundation / image (push) Successful in 5m39s
feat(admin): open a fresh region from the portal (ADR-0182 section 15)
The Regions page opens the next region in place of the one DEV serves: the
admin API reads the region overlay, its kustomization, the grant broker and the
portal deployment from main at one commit, rewrites only the region id, routes,
genesis commit and seeded wildlife range (refusing files whose layout differs),
commits them in one Gitea multi-file commit as aevolution-bot, then starts a full
Argo sync of exactly that commit. The page follows the sync until the region is
live, across the portal's own restart.

Credentials come from Secret aevolution-admin mounted read-only as files
(--deploy-config); without it the feature stays off. A small OpenSSL HTTPS
client talks to Gitea (verified) and argocd-server (verification per
ARGOCD_TLS_VERIFY). The portal's NetworkPolicy gains egress to the node's
ingress for Gitea and to the argocd-server pods, as approved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 13:51:36 -04:00

168 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
// 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 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