Complete M7.3 fenced region ownership
ADR-0060 and schema v2 add database-time region leases and a fenced head advance. Acquire/renew/release/advance lock the lease row, check holder, epoch and expiry with clock_timestamp() after the lock wait, and the advance compares the exact predecessor. Holders are DB-generated tokens; epochs never wrap or repeat. The runtime group role gets EXECUTE on five SECURITY DEFINER functions only - no table, provisioning or CREATE rights. Migration history admits clean->v2, v1->v2 and a v2 no-op, and refuses privileged runtime roles. Host side: portable LeaseAuthority fences from send-time deadlines on CLOCK_BOOTTIME, keeps the earlier deadline on unknown renewal and stays fenced until a newer epoch. Selected timings: 20s lease, 5s renew, 2s margin, 2s renew and 5s commit deadlines. Linux evo::postgres wraps the functions with typed LeaseStoreError results. Validated: Windows CTest 55/55; WSL Release, clang-tidy and ASan/UBSan private-PostgreSQL suites (contenders, expiry, paused/queued stale writers, unknown renewal, exhaustion, bypass denial, upgrade path). Three SQL mutations were each caught. Docker/Gitea CI, remote TLS and cluster runs were not executed. No director, host or deployment added. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,99 @@
|
||||
#pragma once
|
||||
#include <array>
|
||||
#include <chrono>
|
||||
#include <cstdint>
|
||||
#include <optional>
|
||||
|
||||
// Portable host-side region authority contract (ADR-0060). No database types:
|
||||
// PostgreSQL arbitrates ownership; this only decides when a holder must stop.
|
||||
namespace evo::persistence {
|
||||
using Uuid = std::array<std::uint8_t, 16>;
|
||||
using Sha256Digest = std::array<std::uint8_t, 32>;
|
||||
|
||||
struct RegionKey {
|
||||
std::uint64_t world{};
|
||||
std::uint64_t region{};
|
||||
};
|
||||
struct RegionHead {
|
||||
std::uint64_t frame{};
|
||||
std::uint64_t sequence{};
|
||||
Uuid commit{};
|
||||
Sha256Digest digest{};
|
||||
std::uint64_t end_tick{};
|
||||
friend bool operator==(const RegionHead&, const RegionHead&) = default;
|
||||
};
|
||||
// Holder is a database-generated per-acquisition token, not a Pod identity.
|
||||
struct LeaseGrant {
|
||||
Uuid holder{};
|
||||
std::uint64_t epoch{};
|
||||
std::uint64_t frame{};
|
||||
std::chrono::milliseconds duration{};
|
||||
};
|
||||
|
||||
// Selected M7.3 timings. Validity: duration 1..60s (database bound); margin at
|
||||
// least 10% of duration (clock-rate and check-to-effect allowance); two complete
|
||||
// renewal attempts fit before local fencing; I/O deadlines within adapter limits.
|
||||
struct LeasePolicy {
|
||||
std::chrono::milliseconds duration{20000};
|
||||
std::chrono::milliseconds renew_interval{5000};
|
||||
std::chrono::milliseconds safety_margin{2000};
|
||||
std::chrono::milliseconds renew_timeout{2000};
|
||||
std::chrono::milliseconds commit_timeout{5000};
|
||||
};
|
||||
[[nodiscard]] bool valid(const LeasePolicy& policy) noexcept;
|
||||
|
||||
// Monotonic clock that keeps advancing while the process or machine is suspended
|
||||
// (Linux CLOCK_BOOTTIME). A paused worker must observe that time passed.
|
||||
struct LeaseClock {
|
||||
using duration = std::chrono::nanoseconds;
|
||||
using rep = duration::rep;
|
||||
using period = duration::period;
|
||||
using time_point = std::chrono::time_point<LeaseClock>;
|
||||
static constexpr bool is_steady = true;
|
||||
[[nodiscard]] static time_point now() noexcept;
|
||||
};
|
||||
|
||||
enum class LeaseState : std::uint8_t { absent, active, renew_due, fenced };
|
||||
|
||||
// Single-owner local view of one region lease. Every time point is a LeaseClock
|
||||
// reading supplied by the host. The local deadline is request-send time plus the
|
||||
// granted duration minus the safety margin: the database set its expiry no earlier
|
||||
// than that send, so the holder stops before any successor can acquire. Fencing is
|
||||
// sticky until a strictly newer epoch is acquired; renewal never revives it.
|
||||
class LeaseAuthority {
|
||||
public:
|
||||
explicit LeaseAuthority(const LeasePolicy& policy) noexcept : policy_(policy) {}
|
||||
[[nodiscard]] const LeasePolicy& policy() const noexcept {
|
||||
return policy_;
|
||||
}
|
||||
[[nodiscard]] const std::optional<LeaseGrant>& grant() const noexcept {
|
||||
return grant_;
|
||||
}
|
||||
// Returns false (and fences) for an invalid policy, reused/older epoch or late reply.
|
||||
[[nodiscard]] bool acquired(const LeaseGrant& grant, LeaseClock::time_point sent,
|
||||
LeaseClock::time_point received) noexcept;
|
||||
[[nodiscard]] bool renewed(std::uint64_t epoch, std::chrono::milliseconds granted,
|
||||
LeaseClock::time_point sent,
|
||||
LeaseClock::time_point received) noexcept;
|
||||
// Ambiguous renewal: the database may have applied a shorter expiry, so keep
|
||||
// the earlier of the old deadline and the one the attempt could have set.
|
||||
void renewal_unknown(std::chrono::milliseconds requested, LeaseClock::time_point sent) noexcept;
|
||||
void fence() noexcept;
|
||||
[[nodiscard]] LeaseState state(LeaseClock::time_point now) const noexcept;
|
||||
// Admission, simulation and final output require an unfenced lease.
|
||||
[[nodiscard]] bool may_originate(LeaseClock::time_point now) const noexcept;
|
||||
// Liveness guard: begin a commit only if its deadline ends before local fencing.
|
||||
[[nodiscard]] bool may_begin_commit(LeaseClock::time_point now) const noexcept;
|
||||
[[nodiscard]] LeaseClock::time_point deadline() const noexcept {
|
||||
return deadline_;
|
||||
}
|
||||
|
||||
private:
|
||||
LeasePolicy policy_;
|
||||
std::optional<LeaseGrant> grant_;
|
||||
std::uint64_t highest_epoch_{};
|
||||
LeaseClock::time_point last_sent_{};
|
||||
LeaseClock::time_point deadline_{};
|
||||
bool fenced_{};
|
||||
};
|
||||
} // namespace evo::persistence
|
||||
@@ -0,0 +1,50 @@
|
||||
#pragma once
|
||||
#include "evo/persistence/postgres.hpp"
|
||||
#include "evo/persistence/region_lease.hpp"
|
||||
#include <chrono>
|
||||
#include <cstdint>
|
||||
#include <expected>
|
||||
|
||||
// Linux-only calls to the fenced database functions of migration v2 (ADR-0060).
|
||||
// Each call is one statement on a caller-owned connection; outside an explicit
|
||||
// transaction it commits by itself. No retries. Rejections are ordinary results.
|
||||
namespace evo::persistence {
|
||||
enum class LeaseStoreError : std::uint8_t {
|
||||
busy, // Another holder's lease is unexpired in database time.
|
||||
fenced, // Holder/epoch superseded, released or expired: stop originating.
|
||||
head_mismatch, // Expected predecessor is not the committed head.
|
||||
not_provisioned, // No genesis; runtime can never create one.
|
||||
exhausted, // Epoch or commit sequence would wrap: fail closed.
|
||||
invalid, // Rejected arguments; nothing changed.
|
||||
store, // Other SQL/configuration failure; nothing committed.
|
||||
unknown, // May have executed; reconnect and reconcile before reuse.
|
||||
};
|
||||
struct LeaseStoreFailure {
|
||||
LeaseStoreError kind{};
|
||||
PgFailure cause{};
|
||||
};
|
||||
struct HeadAdvance {
|
||||
Uuid commit{};
|
||||
Sha256Digest digest{};
|
||||
std::uint64_t end_tick{};
|
||||
};
|
||||
|
||||
[[nodiscard]] std::expected<LeaseGrant, LeaseStoreFailure>
|
||||
acquire_region_lease(Postgres& db, RegionKey key, std::chrono::milliseconds duration,
|
||||
std::chrono::milliseconds timeout);
|
||||
// Returns the granted duration; the caller measures it from its request send time.
|
||||
[[nodiscard]] std::expected<std::chrono::milliseconds, LeaseStoreFailure>
|
||||
renew_region_lease(Postgres& db, RegionKey key, const LeaseGrant& lease,
|
||||
std::chrono::milliseconds duration, std::chrono::milliseconds timeout);
|
||||
[[nodiscard]] std::expected<void, LeaseStoreFailure>
|
||||
release_region_lease(Postgres& db, RegionKey key, const LeaseGrant& lease,
|
||||
std::chrono::milliseconds timeout);
|
||||
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
|
||||
load_region_head(Postgres& db, RegionKey key, std::chrono::milliseconds timeout);
|
||||
// Locks the lease then the head; requires unexpired holder/epoch and the exact
|
||||
// expected predecessor. head_mismatch after unknown: load the head and compare.
|
||||
[[nodiscard]] std::expected<RegionHead, LeaseStoreFailure>
|
||||
advance_region_head(Postgres& db, RegionKey key, const LeaseGrant& lease,
|
||||
const RegionHead& expected, const HeadAdvance& next,
|
||||
std::chrono::milliseconds timeout);
|
||||
} // namespace evo::persistence
|
||||
Reference in New Issue
Block a user