// M9.7 dev session operator tool (ADR-0083). Dev environment only. // // evo-dev-session credentials --environment dev --server-name NAME --out DIR [--days N] // Writes dev-ca.pem, server.pem, server.key and grant.key into DIR (which must not // already contain them). server.key and grant.key are secrets (owner-only on POSIX): // they belong in the dev namespace Secret, never in images, logs or the repository. // evo-dev-session grants --environment dev --key FILE --world N --frame N --region N // --subject N --out FILE [--count 1..64] [--lifetime 60..14400] // Writes COUNT single-use 108-byte grants for one test subject. Clients consume one // per connection; the HMAC key itself never leaves the operator machine. // evo-dev-session probe --connect HOST:PORT --server-name NAME --ca FILE --grants FILE // [--expect-restart] [--timeout 10..600] // Connects as a dev client, waits for a view, sends one intention and requires its // durable no-effect acknowledgement. With --expect-restart it then waits (printing // "probe awaiting-restart") for the connection to be lost and re-established at a // newer epoch with a fresh baseline, and repeats the acknowledgement check. // Prints "probe passed" on success. Used by tools/ops/session-drill.sh. // evo-dev-session trace --connect HOST:PORT --server-name NAME --ca FILE --grants FILE // [--intents 1..1000] [--interval-ms 50..10000] [--out FILE.csv] [--timeout 10..600] // M10.1 timing experiment: after a fresh baseline, sends one intention per interval // and records, on the client's monotonic clock, send -> IntentResult (admission // round trip) and send -> IntentOutcome (durable), the outcome tick against the view // tick at send, view inter-arrival times and received bytes. Prints nearest-rank // percentiles ("trace ..." lines); --out writes every sample as CSV. Fails on any // loss or rejection, so a run measures one uninterrupted session. // Exit: 0 written/passed, 1 failure, 2 usage. #include "evo/network/dev_credentials.hpp" #include "evo/network/session_client.hpp" #include #include #include #include #include #include #include #include #include #include #include #include #include #include #ifndef _WIN32 #include #include #endif namespace { using namespace evo::network; std::optional number(std::string_view text) { std::uint64_t value{}; const auto [end, error] = std::from_chars(text.data(), text.data() + text.size(), value); if (error != std::errc{} || end != text.data() + text.size()) return std::nullopt; return value; } // Exclusive create; secrets get owner-only permissions on POSIX. bool write_new(const std::filesystem::path& path, std::span bytes, bool secret) { #ifdef _WIN32 (void)secret; // Windows ACLs are inherited from the chosen directory. std::FILE* file = nullptr; if (fopen_s(&file, path.string().c_str(), "wbx") != 0 || file == nullptr) return false; #else const int fd = ::open(path.c_str(), O_WRONLY | O_CREAT | O_EXCL | O_CLOEXEC, secret ? 0600 : 0644); if (fd < 0) return false; std::FILE* file = ::fdopen(fd, "wb"); if (file == nullptr) { ::close(fd); return false; } #endif const bool ok = std::fwrite(bytes.data(), 1, bytes.size(), file) == bytes.size(); return std::fclose(file) == 0 && ok; } bool write_new(const std::filesystem::path& path, const std::string& text, bool secret) { return write_new(path, {reinterpret_cast(text.data()), text.size()}, secret); } struct Args { std::vector> values; [[nodiscard]] std::optional get(std::string_view name) const { for (const auto& [k, v] : values) if (k == name) return v; return std::nullopt; } }; std::optional parse(int argc, char** argv) { Args a; for (int i = 2; i < argc; i += 2) { if (i + 1 >= argc || std::string_view{argv[i]}.substr(0, 2) != "--") return std::nullopt; a.values.emplace_back(argv[i], argv[i + 1]); } return a; } int credentials(const Args& a) { const auto out = a.get("--out"); const auto name = a.get("--server-name"); const auto days = number(a.get("--days").value_or("90")); if (a.get("--environment") != "dev" || !out || !name || !days || *days > 825) return 2; const auto made = generate_dev_credentials(DeploymentEnvironment::dev, *name, static_cast(*days), std::chrono::system_clock::now()); if (!made) { std::fputs("credential generation failed\n", stderr); return 1; } const std::filesystem::path dir{std::string{*out}}; std::error_code error; std::filesystem::create_directories(dir, error); if (!write_new(dir / "dev-ca.pem", made->authority_pem, false) || !write_new(dir / "server.pem", made->server_certificate_pem, false) || !write_new(dir / "server.key", made->server_key_pem, true) || !write_new(dir / "grant.key", format_grant_key(made->grant_key) + "\n", true)) { std::fputs("refusing to overwrite or failed to write credential files\n", stderr); return 1; } std::printf("wrote dev-ca.pem server.pem server.key grant.key for %.*s (dev only)\n", static_cast(name->size()), name->data()); return 0; } int grants(const Args& a) { const auto key_path = a.get("--key"); const auto out = a.get("--out"); const auto world = number(a.get("--world").value_or("")); const auto frame = number(a.get("--frame").value_or("")); const auto region = number(a.get("--region").value_or("")); const auto subject = number(a.get("--subject").value_or("")); const auto count = number(a.get("--count").value_or("16")); const auto lifetime = number(a.get("--lifetime").value_or("14400")); if (a.get("--environment") != "dev" || !key_path || !out || !world || !frame || !region || !subject || !count || *count == 0 || *count > 64 || !lifetime || *lifetime < 60 || *lifetime > 14400) return 2; std::ifstream file{std::string{*key_path}}; const std::string text{std::istreambuf_iterator{file}, std::istreambuf_iterator{}}; const auto secret = parse_grant_key(text); if (!secret) { std::fputs("grant key must be 64 lowercase hex digits\n", stderr); return 1; } const auto key = DevGrantKey::import(DeploymentEnvironment::dev, *secret); if (!key) return 1; const auto now = static_cast(std::chrono::duration_cast( std::chrono::system_clock::now().time_since_epoch()) .count()); std::vector bundle; for (std::uint64_t i = 0; i < *count; ++i) { const auto id = random_grant_id(); if (!id) return 1; const auto grant = key->issue({*id, *subject, {*world, *frame}, *region, now, now + *lifetime}); if (!grant) { std::fputs("invalid grant claims\n", stderr); return 1; } bundle.insert(bundle.end(), grant->begin(), grant->end()); } if (!write_new(std::filesystem::path{std::string{*out}}, bundle, true)) { std::fputs("refusing to overwrite or failed to write the grant bundle\n", stderr); return 1; } std::printf("wrote %llu single-use dev grants for subject %llu, valid %llu s\n", static_cast(*count), static_cast(*subject), static_cast(*lifetime)); return 0; } std::vector read_file(std::string_view path) { std::ifstream file{std::string{path}, std::ios::binary}; return {std::istreambuf_iterator{file}, std::istreambuf_iterator{}}; } int probe(const Args& a, bool expect_restart) { const auto connect = a.get("--connect"); const auto name = a.get("--server-name"); const auto ca = a.get("--ca"); const auto bundle_path = a.get("--grants"); const auto timeout = number(a.get("--timeout").value_or("240")); if (!connect || !name || !ca || !bundle_path || !timeout || *timeout < 10 || *timeout > 600) return 2; const auto colon = connect->rfind(':'); if (colon == std::string_view::npos || colon == 0) return 2; const std::uint64_t port = number(connect->substr(colon + 1)).value_or(0); const auto bundle = read_file(*bundle_path); if (port == 0 || port > 65535 || bundle.empty() || bundle.size() % dev_grant_bytes != 0) return 2; SessionClientConfig config; config.host = std::string{connect->substr(0, colon)}; config.port = static_cast(port); const auto pem = read_file(*ca); config.trust = {{pem.begin(), pem.end()}, std::string{*name}}; for (std::size_t at = 0; at < bundle.size(); at += dev_grant_bytes) { DevGrant grant{}; std::copy_n(bundle.begin() + static_cast(at), grant.size(), grant.begin()); config.grants.push_back(grant); } config.max_retry = std::chrono::milliseconds{2000}; auto made = SessionClient::create(std::move(config)); if (!made) return 2; auto& c = **made; const auto deadline = std::chrono::steady_clock::now() + std::chrono::seconds{*timeout}; std::uint64_t sequence = 0, epoch = 0; const auto failed = [](const char* why) { std::printf("probe failed: %s\n", why); return 1; }; // One acknowledged round: a session newer than `after_epoch`, a view, one durable intent. const auto round = [&](std::uint64_t after_epoch) -> const char* { bool sent = false; while (std::chrono::steady_clock::now() < deadline) { c.poll(std::chrono::steady_clock::now()); for (const auto& e : c.take_events()) { using Kind = ClientEvent::Kind; if (e.kind == Kind::welcome) std::printf("probe welcome session=%llu epoch=%llu tick=%llu commit=%llu\n", static_cast(e.welcome.session), static_cast(e.welcome.epoch), static_cast(e.welcome.server_tick), static_cast(e.welcome.commit_watermark)); else if (e.kind == Kind::closed) std::printf("probe closed reason=%u\n", static_cast(e.reason)); else if (e.kind == Kind::lost) std::puts("probe lost"); else if (e.kind == Kind::exhausted) return "grants exhausted"; else if (e.kind == Kind::result && e.result.status != IntentStatus::admitted) return "intention rejected"; else if (e.kind == Kind::outcome) { if (e.outcome.finality != IntentFinality::committed_no_effect) return "intention not committed"; std::printf("probe durable sequence=%llu tick=%llu commit=%llu\n", static_cast(e.sequence), static_cast(e.outcome.tick), static_cast(e.outcome.commit_sequence)); epoch = c.welcome()->epoch; return nullptr; } } std::fflush(stdout); const auto w = c.welcome(); if (!sent && w && w->epoch > after_epoch && c.latest_view() && c.environment().freshness() == evo::client::Freshness::current && c.send({++sequence, 0, 1000, 0})) sent = true; std::this_thread::sleep_for(std::chrono::milliseconds{5}); } return "timeout"; }; if (const auto* why = round(0)) return failed(why); if (expect_restart) { std::puts("probe awaiting-restart"); std::fflush(stdout); if (const auto* why = round(epoch)) return failed(why); } std::puts("probe passed"); return 0; } // Nearest-rank percentile of a non-empty sample (sorted copy). double percentile(std::vector v, double p) { std::sort(v.begin(), v.end()); const auto rank = static_cast(std::ceil(p / 100.0 * static_cast(v.size()))); return v[std::clamp(rank, 1, v.size()) - 1]; } void report(const char* name, const std::vector& v) { if (v.empty()) { std::printf("trace %s n=0\n", name); return; } std::printf("trace %s n=%zu p50=%.1f p95=%.1f p99=%.1f max=%.1f\n", name, v.size(), percentile(v, 50), percentile(v, 95), percentile(v, 99), *std::max_element(v.begin(), v.end())); } int trace(const Args& a) { const auto connect = a.get("--connect"); const auto name = a.get("--server-name"); const auto ca = a.get("--ca"); const auto bundle_path = a.get("--grants"); const auto timeout = number(a.get("--timeout").value_or("300")); const auto intents = number(a.get("--intents").value_or("120")); const auto interval = number(a.get("--interval-ms").value_or("250")); if (!connect || !name || !ca || !bundle_path || !timeout || *timeout < 10 || *timeout > 600 || !intents || *intents < 1 || *intents > 1000 || !interval || *interval < 50 || *interval > 10000) return 2; const auto colon = connect->rfind(':'); if (colon == std::string_view::npos || colon == 0) return 2; const std::uint64_t port = number(connect->substr(colon + 1)).value_or(0); const auto bundle = read_file(*bundle_path); if (port == 0 || port > 65535 || bundle.empty() || bundle.size() % dev_grant_bytes != 0) return 2; SessionClientConfig config; config.host = std::string{connect->substr(0, colon)}; config.port = static_cast(port); const auto pem = read_file(*ca); config.trust = {{pem.begin(), pem.end()}, std::string{*name}}; for (std::size_t at = 0; at < bundle.size(); at += dev_grant_bytes) { DevGrant grant{}; std::copy_n(bundle.begin() + static_cast(at), grant.size(), grant.begin()); config.grants.push_back(grant); } auto made = SessionClient::create(std::move(config)); if (!made) return 2; auto& c = **made; using Clock = std::chrono::steady_clock; const auto start = Clock::now(); const auto ms = [&](Clock::time_point t) { return std::chrono::duration(t - start).count(); }; const auto deadline = start + std::chrono::seconds{*timeout}; struct Sample { double sent{}, result{-1}, outcome{-1}; std::uint64_t tick_at_send{}, outcome_tick{}, commit{}; int status{-1}; }; std::vector samples; std::vector view_at; std::vector view_tick; std::vector view_bytes; std::optional last_tick; ClientTraffic seen{}; std::uint64_t sequence = 0, resolved = 0; std::optional next_send; const auto failed = [](const char* why) { std::printf("trace failed: %s\n", why); return 1; }; while (resolved < *intents) { const auto now = Clock::now(); if (now >= deadline) return failed("timeout"); c.poll(now); for (const auto& e : c.take_events()) { using Kind = ClientEvent::Kind; if (e.kind == Kind::lost || e.kind == Kind::closed || e.kind == Kind::unknown || e.kind == Kind::exhausted || e.kind == Kind::backpressure) return failed("session interrupted (a trace must be one uninterrupted session)"); if ((e.kind == Kind::result || e.kind == Kind::outcome) && (e.sequence == 0 || e.sequence > samples.size())) return failed("unexpected sequence"); if (e.kind == Kind::result) { auto& sample = samples[e.sequence - 1]; sample.result = ms(now); sample.status = static_cast(e.result.status); if (e.result.status != IntentStatus::admitted) { std::printf("trace rejected sequence=%llu status=%u\n", static_cast(e.sequence), static_cast(e.result.status)); return failed("intention rejected"); } } else if (e.kind == Kind::outcome) { auto& sample = samples[e.sequence - 1]; sample.outcome = ms(now); sample.outcome_tick = e.outcome.tick; sample.commit = e.outcome.commit_sequence; ++resolved; } } const auto traffic = c.traffic(); if (const auto v = c.latest_view(); v && (!last_tick || *last_tick != v->server_tick)) { last_tick = v->server_tick; view_at.push_back(ms(now)); view_tick.push_back(v->server_tick); const auto views = traffic.environment_views - seen.environment_views; if (views > 0) view_bytes.push_back(static_cast(traffic.environment_view_bytes - seen.environment_view_bytes) / static_cast(views)); seen = traffic; } // Start after a fresh, current baseline; then one intention per interval. if (samples.size() < *intents && c.latest_view() && c.environment().freshness() == evo::client::Freshness::current) { if (!next_send) next_send = now; if (now >= *next_send) { const auto x = static_cast(sequence % 2 == 0 ? 1000 : -1000); if (c.send({sequence + 1, 0, x, 0})) { ++sequence; samples.push_back({ms(now), -1, -1, c.latest_view()->server_tick, 0, 0, -1}); *next_send += std::chrono::milliseconds{*interval}; } } } // Poll continuously: a 1 ms sleep is about one 15.6 ms timer tick on Windows and // would dominate the measured round trips. Costs one core for the run. std::this_thread::yield(); } std::vector admission, durable, lead, intervals; std::uint64_t admitted = 0, durable_count = 0; for (const auto& s : samples) { if (s.status == static_cast(IntentStatus::admitted)) { ++admitted; admission.push_back(s.result - s.sent); } if (s.outcome >= 0) { ++durable_count; durable.push_back(s.outcome - s.sent); lead.push_back(static_cast(s.outcome_tick) - static_cast(s.tick_at_send)); } } for (std::size_t i = 1; i < view_at.size(); ++i) intervals.push_back(view_at[i] - view_at[i - 1]); const double seconds = ms(Clock::now()) / 1000.0; std::printf("trace intents=%zu admitted=%llu outcomes=%llu interval_ms=%llu\n", samples.size(), static_cast(admitted), static_cast(durable_count), static_cast(*interval)); report("admission_ms", admission); report("durable_ms", durable); report("outcome_tick_lead", lead); report("view_interval_ms", intervals); report("environment_view_bytes", view_bytes); const auto total = c.traffic(); std::printf("trace views=%zu ticks=%llu seconds=%.1f received_bytes_per_s=%.0f frames=%llu\n", view_at.size(), static_cast( view_tick.empty() ? 0 : view_tick.back() - view_tick.front()), seconds, static_cast(total.bytes) / seconds, static_cast(total.frames)); if (const auto out = a.get("--out")) { std::ofstream csv{std::string{*out}, std::ios::trunc}; csv << "kind,sequence,sent_ms,tick_at_send,result_ms,status,outcome_ms,outcome_tick," "commit\n"; for (std::size_t i = 0; i < samples.size(); ++i) { const auto& s = samples[i]; csv << "intent," << i + 1 << ',' << s.sent << ',' << s.tick_at_send << ',' << s.result << ',' << s.status << ',' << s.outcome << ',' << s.outcome_tick << ',' << s.commit << '\n'; } for (std::size_t i = 0; i < view_at.size(); ++i) csv << "view,," << view_at[i] << ',' << view_tick[i] << ",,,,,\n"; if (!csv) return failed("cannot write --out"); } std::puts("trace passed"); return 0; } } // namespace int main(int argc, char** argv) { const auto args = parse(argc, argv); const std::string_view command = argc > 1 ? argv[1] : ""; int code = 2; if (args && command == "credentials") code = credentials(*args); else if (args && command == "grants") code = grants(*args); else if (command == "probe") { // --expect-restart takes no value; strip it before pairing the rest. std::vector rest{argv, argv + argc}; const bool restart = std::erase_if(rest, [](const char* x) { return std::string_view{x} == "--expect-restart"; }) > 0; const auto probe_args = parse(static_cast(rest.size()), rest.data()); code = probe_args ? probe(*probe_args, restart) : 2; } else if (args && command == "trace") code = trace(*args); if (code == 2) std::fputs( "usage: evo-dev-session credentials --environment dev --server-name NAME " "--out DIR [--days N]\n" " evo-dev-session grants --environment dev --key FILE --world N " "--frame N --region N --subject N --out FILE [--count N] [--lifetime S]\n" " evo-dev-session probe --connect HOST:PORT --server-name NAME --ca FILE " "--grants FILE [--expect-restart] [--timeout S]\n" " evo-dev-session trace --connect HOST:PORT --server-name NAME --ca FILE " "--grants FILE [--intents N] [--interval-ms MS] [--out FILE.csv] [--timeout S]\n", stderr); return code; }