Complete M7.6 bounded authoritative region host
ADR-0064: RegionHost<State> (environmental and lineage profiles) is a single-owner, single-threaded state machine advanced by step(now): acquire the fenced lease and recover the verified head, run, resolve ambiguous commits, drain and stop, or quarantine. Admission is provisional and bounded (64 inputs, 64 KiB) with backpressure; FinalAck and FinalOutcome are emitted only after a confirmed commit, and inputs that will never be acknowledged are reported with a reason. Ticks follow the caller's scheduling clock with bounded catch-up and measured tick debt, never invented inputs. A death seals the batch and commits in the same step, so no dependent tick uses an uncommitted outcome. Storage outages pause and retry, unknown outcomes resolve by exact bytes, fencing discards unconfirmed work and re-acquires; readiness fails closed. Drain commits pending ticks and releases the lease. evo-server hosts one region with a bounded stdin input feed, stdout event lines, a readiness file and SIGTERM drain (exit 0/3/4). Validated: Windows CTest 58/58; PostgreSQL suites under GCC Release, clang-tidy and ASan/UBSan including real-process SIGTERM drain and SIGKILL with successor recovery; four host mutations each caught. No gateway, metrics, Docker/Gitea CI or deployment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,170 @@
|
||||
#pragma once
|
||||
#include "evo/persistence/checkpoint_store.hpp"
|
||||
#include "evo/persistence/region_batch.hpp"
|
||||
#include "evo/persistence/region_lease.hpp"
|
||||
#include <chrono>
|
||||
#include <cstddef>
|
||||
#include <cstdint>
|
||||
#include <deque>
|
||||
#include <expected>
|
||||
#include <functional>
|
||||
#include <memory>
|
||||
#include <optional>
|
||||
#include <vector>
|
||||
|
||||
// M7.6 authoritative region host (ADR-0064). Linux; composes the fenced lease,
|
||||
// verified recovery and batch publication. One owner, one thread: every call runs
|
||||
// on the caller's thread and all I/O is bounded by the lease policy's deadlines.
|
||||
// While a batch commits the region is stopped, by design (ADR-0058).
|
||||
namespace evo::server {
|
||||
// One tick's host input, from the (future) gateway or a local feed.
|
||||
struct TickInput {
|
||||
persistence::Uuid request{}; // Caller identity for acknowledgement; nonzero.
|
||||
processes::EnvironmentalInput input{};
|
||||
friend bool operator==(const TickInput&, const TickInput&) = default;
|
||||
};
|
||||
inline constexpr std::size_t tick_input_bytes = 16 + 72; // Canonical accounting size.
|
||||
|
||||
enum class AdmissionError : std::uint8_t {
|
||||
not_ready, // No current authority or not recovered: nothing is accepted.
|
||||
draining, // Shutdown in progress.
|
||||
full, // Backpressure: bounded backlog (inputs or bytes) is full.
|
||||
duplicate, // Request identity already queued or pending in this host.
|
||||
invalid, // Zero request identity.
|
||||
};
|
||||
// Final: the input's tick is in a durably committed checkpoint.
|
||||
struct FinalAck {
|
||||
persistence::Uuid request{};
|
||||
std::uint64_t tick{};
|
||||
std::uint64_t commit_sequence{};
|
||||
friend bool operator==(const FinalAck&, const FinalAck&) = default;
|
||||
};
|
||||
// Final: the permanent outcome is durable (and in the outbox).
|
||||
struct FinalOutcome {
|
||||
persistence::BatchDecision decision{};
|
||||
std::uint64_t commit_sequence{};
|
||||
friend bool operator==(const FinalOutcome&, const FinalOutcome&) = default;
|
||||
};
|
||||
// Why an accepted input will never be acknowledged by this host.
|
||||
enum class Unacknowledged : std::uint8_t {
|
||||
refused, // The simulation rejected it; no tick consumed it.
|
||||
drained, // Still queued at shutdown.
|
||||
fenced, // Authority was lost before its tick committed; the next owner never saw it.
|
||||
quarantined,
|
||||
};
|
||||
struct Dropped {
|
||||
TickInput input{};
|
||||
Unacknowledged reason{};
|
||||
};
|
||||
|
||||
enum class HostPhase : std::uint8_t {
|
||||
acquiring, // Waiting for the lease (busy/unavailable) or recovering.
|
||||
running, // Authoritative: simulating and committing.
|
||||
resolving, // A commit outcome is unknown: paused until resolved.
|
||||
draining, // Shutdown: committing pending work, then releasing.
|
||||
stopped, // Drained (lease released when possible).
|
||||
quarantined, // Fail closed: committed state or history cannot be trusted.
|
||||
};
|
||||
struct HostStatus {
|
||||
HostPhase phase{HostPhase::acquiring};
|
||||
bool ready{}; // Authoritative now: recovered, running, lease may originate.
|
||||
std::uint64_t epoch{};
|
||||
std::uint64_t simulated_tick{}, committed_tick{}, committed_sequence{};
|
||||
std::size_t queued{}, queued_bytes{};
|
||||
std::uint64_t tick_debt{}, max_tick_debt{}; // Due minus simulated since running.
|
||||
std::uint64_t commits{}, store_failures{}, unknown_outcomes{}, fences{};
|
||||
};
|
||||
|
||||
using Connect =
|
||||
std::function<std::expected<std::unique_ptr<persistence::Postgres>, persistence::PgFailure>()>;
|
||||
struct HostConfig {
|
||||
persistence::RegionKey key{};
|
||||
std::uint64_t frame{};
|
||||
persistence::LeasePolicy lease{};
|
||||
// Region quantum; must equal the committed checkpoint's tick_microseconds.
|
||||
std::chrono::microseconds tick_quantum{50000};
|
||||
std::chrono::milliseconds flush_interval{1000}; // Commit a non-empty batch this often.
|
||||
std::size_t max_queued_inputs{64};
|
||||
std::size_t max_queued_bytes{65536};
|
||||
std::uint32_t max_catch_up_ticks{8}; // Per step; debt is never skipped.
|
||||
persistence::Sha256Digest build{};
|
||||
std::vector<persistence::Sha256Digest> retained_builds;
|
||||
std::size_t restore_budget{8000000};
|
||||
};
|
||||
enum class HostConfigError : std::uint8_t { invalid };
|
||||
|
||||
// Scheduling time comes from the caller (monotonic, may be scaled in tests); lease
|
||||
// deadlines always use LeaseClock (real, suspend-aware) and database time.
|
||||
using SchedulerTime = std::chrono::steady_clock::time_point;
|
||||
|
||||
template <typename State> class RegionHost {
|
||||
public:
|
||||
[[nodiscard]] static std::expected<std::unique_ptr<RegionHost>, HostConfigError>
|
||||
create(HostConfig config, Connect connect,
|
||||
std::unique_ptr<persistence::FilesystemObjectStore> objects);
|
||||
RegionHost(const RegionHost&) = delete;
|
||||
RegionHost& operator=(const RegionHost&) = delete;
|
||||
RegionHost(RegionHost&&) = delete;
|
||||
RegionHost& operator=(RegionHost&&) = delete;
|
||||
~RegionHost();
|
||||
|
||||
// Provisional admission only; nothing is final until a FinalAck.
|
||||
[[nodiscard]] std::expected<void, AdmissionError> submit(const TickInput& input);
|
||||
// Advances the state machine once: lease upkeep, recovery, resolution, commits
|
||||
// and up to max_catch_up_ticks ticks. Blocks at most for bounded I/O.
|
||||
const HostStatus& step(SchedulerTime now);
|
||||
// Stops admission, drops the backlog, commits pending ticks, releases the lease.
|
||||
void drain();
|
||||
|
||||
[[nodiscard]] std::vector<FinalAck> take_acks();
|
||||
[[nodiscard]] std::vector<FinalOutcome> take_outcomes();
|
||||
[[nodiscard]] std::vector<Dropped> take_dropped();
|
||||
[[nodiscard]] const HostStatus& status() const noexcept {
|
||||
return status_;
|
||||
}
|
||||
// Read-only view for diagnostics/tests; null unless recovered.
|
||||
[[nodiscard]] const State* state() const noexcept {
|
||||
return state_.get();
|
||||
}
|
||||
|
||||
private:
|
||||
struct Applied {
|
||||
TickInput input;
|
||||
std::uint64_t tick{};
|
||||
};
|
||||
RegionHost(HostConfig config, Connect connect,
|
||||
std::unique_ptr<persistence::FilesystemObjectStore> objects);
|
||||
bool database();
|
||||
void acquire(SchedulerTime now);
|
||||
void upkeep();
|
||||
void simulate(SchedulerTime now);
|
||||
void commit(SchedulerTime now);
|
||||
void resolve(SchedulerTime now);
|
||||
void confirmed(const persistence::PublishedBatch& batch, SchedulerTime now);
|
||||
void lose_authority(Unacknowledged reason, HostPhase next);
|
||||
void refresh(SchedulerTime now);
|
||||
[[nodiscard]] persistence::Uuid next_commit_id() const;
|
||||
|
||||
HostConfig config_;
|
||||
Connect connect_;
|
||||
std::unique_ptr<persistence::FilesystemObjectStore> objects_;
|
||||
std::unique_ptr<persistence::Postgres> db_;
|
||||
persistence::LeaseAuthority authority_;
|
||||
std::unique_ptr<State> state_;
|
||||
std::optional<persistence::RegionBatch<State>> batch_;
|
||||
std::optional<persistence::CommittedCheckpoint> committed_;
|
||||
std::optional<persistence::PreparedCommit> prepared_;
|
||||
std::deque<TickInput> queue_;
|
||||
std::vector<Applied> applied_;
|
||||
std::vector<FinalAck> acks_;
|
||||
std::vector<FinalOutcome> outcomes_;
|
||||
std::vector<Dropped> dropped_;
|
||||
SchedulerTime origin_{}, batch_started_{};
|
||||
std::uint64_t origin_tick_{};
|
||||
bool draining_{};
|
||||
HostStatus status_{};
|
||||
};
|
||||
|
||||
extern template class RegionHost<processes::EnvironmentalCommunity>;
|
||||
extern template class RegionHost<processes::LineageRegion>;
|
||||
} // namespace evo::server
|
||||
Reference in New Issue
Block a user