refactor(gateway/hosted_rooms): table-driven task transitions in hosted_room_driver; fold replica schema init, share leaf helpers (-40% LOC, parity-neutral)

This commit is contained in:
Teknium
2026-09-02 16:19:39 -07:00
parent b0be4c5bdd
commit 44e37bc7e3
2 changed files with 443 additions and 839 deletions
File diff suppressed because it is too large Load Diff
+60 -131
View File
@@ -17,8 +17,9 @@ from __future__ import annotations
import json
import sqlite3
import time
from contextlib import contextmanager
from pathlib import Path
from typing import Any
from typing import Any, Iterator
from gateway.hosted_rooms import (
MAX_ACTOR_ID_CHARS,
@@ -34,14 +35,15 @@ from gateway.hosted_rooms import (
_validate_room_name,
local_authority_gateway_id,
)
from gateway.hosted_rooms_common import positive_int, utf8_len
MAX_REPLICA_ROOMS = 256
MAX_REPLICA_EVENT_BYTES = 256 * 1024 * 1024
_SYSTEM_ACTOR = {"kind": "system", "id": "authority-control"}
_INSERT_ROOM_EVENT = """INSERT INTO hosted_room_events
(room_id, seq, event_id, kind, actor_json, authority_epoch,
payload_json, created_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)"""
_EVENT_COLUMNS = "(room_id, seq, event_id, kind, actor_json, authority_epoch, payload_json, created_at)"
_INSERT_ROOM_EVENT = f"INSERT INTO hosted_room_events {_EVENT_COLUMNS} VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
_INSERT_REPLICA_EVENT = f"INSERT INTO hosted_room_replica_events {_EVENT_COLUMNS} VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
_SELECT_REPLICA = "SELECT * FROM hosted_room_replicas WHERE room_id=?"
class ReplicaError(HostedRoomError):
@@ -59,44 +61,40 @@ class ReplicaEpochRegressionError(ReplicaError):
def _initialize_replica_schema(conn: sqlite3.Connection) -> None:
conn.execute(
"""CREATE TABLE IF NOT EXISTS hosted_room_replicas (
room_id TEXT PRIMARY KEY,
name TEXT NOT NULL,
members_json TEXT NOT NULL,
room_id TEXT PRIMARY KEY, name TEXT NOT NULL, members_json TEXT NOT NULL,
authority_gateway_id TEXT NOT NULL,
authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 1),
last_seq INTEGER NOT NULL DEFAULT 0 CHECK (last_seq >= 0),
latest_seq INTEGER NOT NULL DEFAULT 0,
event_bytes INTEGER NOT NULL DEFAULT 0,
created_at REAL NOT NULL,
updated_at REAL NOT NULL
latest_seq INTEGER NOT NULL DEFAULT 0, event_bytes INTEGER NOT NULL DEFAULT 0,
created_at REAL NOT NULL, updated_at REAL NOT NULL
)"""
)
conn.execute(
"""CREATE TABLE IF NOT EXISTS hosted_room_replica_events (
room_id TEXT NOT NULL,
seq INTEGER NOT NULL CHECK (seq >= 1),
event_id TEXT NOT NULL,
kind TEXT NOT NULL,
actor_json TEXT NOT NULL,
authority_epoch INTEGER,
payload_json TEXT NOT NULL,
created_at REAL NOT NULL,
room_id TEXT NOT NULL, seq INTEGER NOT NULL CHECK (seq >= 1), event_id TEXT NOT NULL,
kind TEXT NOT NULL, actor_json TEXT NOT NULL, authority_epoch INTEGER,
payload_json TEXT NOT NULL, created_at REAL NOT NULL,
PRIMARY KEY (room_id, seq)
)"""
)
def _replica_transaction(db_path: Path | str):
return _transaction(db_path, immediate=True)
@contextmanager
def _replica_transaction(db_path: Path | str) -> Iterator[sqlite3.Connection]:
"""Ensure the replica schema (own autocommit connection), then open an IMMEDIATE transaction.
def _ensure_schema(db_path: Path | str) -> None:
The schema DDL is re-run inside the transaction too; that double init is the
established statement order and is intentionally preserved.
"""
conn = _connect(db_path)
try:
with conn:
_initialize_replica_schema(conn)
finally:
conn.close()
with _transaction(db_path, immediate=True) as conn:
_initialize_replica_schema(conn)
yield conn
def _room_id(value: Any) -> str:
@@ -104,9 +102,7 @@ def _room_id(value: Any) -> str:
def _positive_int(value: Any, message: str) -> int:
if isinstance(value, bool) or not isinstance(value, int) or value < 1:
raise ReplicaError(message)
return value
return positive_int(value, error=ReplicaError, message=message)
def _clock(now: float | None) -> float:
@@ -122,11 +118,10 @@ def _control_event_json(payload: dict[str, Any]) -> tuple[str, str]:
def _event_bytes(event: dict[str, Any]) -> int:
return (
len(str(event["event_id"]).encode("utf-8"))
+ len(str(event["kind"]).encode("utf-8"))
+ len(json.dumps(event["actor"], ensure_ascii=False, separators=(",", ":")).encode("utf-8"))
+ len(json.dumps(event["payload"], ensure_ascii=False, separators=(",", ":")).encode("utf-8"))
return utf8_len(
str(event["event_id"]), str(event["kind"]),
json.dumps(event["actor"], ensure_ascii=False, separators=(",", ":")),
json.dumps(event["payload"], ensure_ascii=False, separators=(",", ":")),
)
@@ -140,13 +135,9 @@ def _validate_page(page: Any) -> tuple[list[dict[str, Any]], dict[str, Any]]:
if not isinstance(authority, dict):
raise ReplicaError("page.authority is required for replication")
gateway_id = _validate_identifier(
authority.get("gateway_id"),
label="page.authority.gateway_id",
max_chars=MAX_ACTOR_ID_CHARS,
)
epoch = _positive_int(
authority.get("epoch"), "page.authority.epoch must be a positive integer"
authority.get("gateway_id"), label="page.authority.gateway_id", max_chars=MAX_ACTOR_ID_CHARS
)
epoch = _positive_int(authority.get("epoch"), "page.authority.epoch must be a positive integer")
previous_seq: int | None = None
for event in events:
if not isinstance(event, dict):
@@ -166,13 +157,7 @@ def _validate_page(page: Any) -> tuple[list[dict[str, Any]], dict[str, Any]]:
def ingest_page(
db_path: Path | str,
*,
room_id: Any,
room_name: Any,
members: Any,
page: Any,
now: float | None = None,
db_path: Path | str, *, room_id: Any, room_name: Any, members: Any, page: Any, now: float | None = None
) -> dict[str, Any]:
"""Persist one replay page idempotently; refuses seq gaps and epoch regressions.
@@ -184,13 +169,10 @@ def ingest_page(
_, members_json = _validate_members(members)
events, authority = _validate_page(page)
now = _clock(now)
_ensure_schema(db_path)
with _replica_transaction(db_path) as conn:
_initialize_replica_schema(conn)
row = conn.execute(
"""SELECT authority_gateway_id, authority_epoch, last_seq,
latest_seq, event_bytes
"""SELECT authority_gateway_id, authority_epoch, last_seq, latest_seq, event_bytes
FROM hosted_room_replicas WHERE room_id=?""",
(room_id,),
).fetchone()
@@ -200,14 +182,11 @@ def ingest_page(
raise ReplicaError("replica room capacity exhausted")
stored_epoch = last_seq = stored_bytes = 0
else:
stored_epoch = int(row["authority_epoch"])
last_seq = int(row["last_seq"])
stored_bytes = int(row["event_bytes"])
if authority["epoch"] < stored_epoch:
raise ReplicaEpochRegressionError(
"page authority epoch is older than the stored replica epoch"
stored_epoch, last_seq, stored_bytes = (
int(row["authority_epoch"]), int(row["last_seq"]), int(row["event_bytes"])
)
if authority["epoch"] < stored_epoch:
raise ReplicaEpochRegressionError("page authority epoch is older than the stored replica epoch")
new_events = [e for e in events if int(e["seq"]) > last_seq]
if new_events and int(new_events[0]["seq"]) != last_seq + 1:
@@ -218,18 +197,12 @@ def ingest_page(
if stored_bytes + added_bytes + size > MAX_REPLICA_EVENT_BYTES:
raise ReplicaError("replica event storage exhausted")
actor_json = _canonical_json(event["actor"], label="actor", max_bytes=4 * 1024)
payload_json = _canonical_json(
event["payload"], label="payload", max_bytes=MAX_EVENT_JSON_BYTES
)
payload_json = _canonical_json(event["payload"], label="payload", max_bytes=MAX_EVENT_JSON_BYTES)
conn.execute(
"""INSERT INTO hosted_room_replica_events
(room_id, seq, event_id, kind, actor_json, authority_epoch,
payload_json, created_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
_INSERT_REPLICA_EVENT,
(
room_id, int(event["seq"]), event["event_id"], event["kind"], actor_json,
event.get("authority_epoch"), payload_json,
float(event.get("created_at") or now),
event.get("authority_epoch"), payload_json, float(event.get("created_at") or now),
),
)
added_bytes += size
@@ -240,9 +213,8 @@ def ingest_page(
if row is None:
conn.execute(
"""INSERT INTO hosted_room_replicas
(room_id, name, members_json, authority_gateway_id,
authority_epoch, last_seq, latest_seq, event_bytes,
created_at, updated_at)
(room_id, name, members_json, authority_gateway_id, authority_epoch, last_seq, latest_seq,
event_bytes, created_at, updated_at)
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
(
room_id, room_name, members_json, authority["gateway_id"], authority["epoch"],
@@ -252,9 +224,8 @@ def ingest_page(
else:
conn.execute(
"""UPDATE hosted_room_replicas
SET name=?, members_json=?, authority_gateway_id=?,
authority_epoch=?, last_seq=?, latest_seq=?,
event_bytes=event_bytes+?, updated_at=?
SET name=?, members_json=?, authority_gateway_id=?, authority_epoch=?, last_seq=?,
latest_seq=?, event_bytes=event_bytes+?, updated_at=?
WHERE room_id=?""",
(
room_name, members_json, authority["gateway_id"], authority["epoch"],
@@ -273,22 +244,15 @@ def ingest_page(
def replica_state(db_path: Path | str, *, room_id: Any) -> dict[str, Any]:
"""Return the stored replica's coverage and authority lineage."""
room_id = _room_id(room_id)
_ensure_schema(db_path)
with _replica_transaction(db_path) as conn:
_initialize_replica_schema(conn)
row = conn.execute(
"SELECT * FROM hosted_room_replicas WHERE room_id=?", (room_id,)
).fetchone()
row = conn.execute(_SELECT_REPLICA, (room_id,)).fetchone()
if row is None:
raise ReplicaError("replica not found")
return {
"room_id": row["room_id"],
"name": row["name"],
"members": json.loads(row["members_json"]),
"authority": {
"gateway_id": row["authority_gateway_id"],
"epoch": int(row["authority_epoch"]),
},
"authority": {"gateway_id": row["authority_gateway_id"], "epoch": int(row["authority_epoch"])},
"last_seq": int(row["last_seq"]),
"latest_seq": int(row["latest_seq"]),
"event_bytes": int(row["event_bytes"]),
@@ -298,11 +262,7 @@ def replica_state(db_path: Path | str, *, room_id: Any) -> dict[str, Any]:
def promote_replica(
db_path: Path | str,
*,
room_id: Any,
reason: Any = "authority-unreachable",
now: float | None = None,
db_path: Path | str, *, room_id: Any, reason: Any = "authority-unreachable", now: float | None = None
) -> dict[str, Any]:
"""Continue a replicated room on THIS gateway at ``epoch + 1``.
@@ -316,34 +276,22 @@ def promote_replica(
raise ReplicaError("reason must be a non-empty string of at most 200 chars")
now = _clock(now)
local_gateway = local_authority_gateway_id()
_ensure_schema(db_path)
with _replica_transaction(db_path) as conn:
_initialize_replica_schema(conn)
replica = conn.execute(
"SELECT * FROM hosted_room_replicas WHERE room_id=?", (room_id,)
).fetchone()
replica = conn.execute(_SELECT_REPLICA, (room_id,)).fetchone()
if replica is None:
raise ReplicaError("replica not found")
if replica["authority_gateway_id"] == local_gateway:
raise ReplicaError("this gateway already holds the room authority")
if conn.execute(
"SELECT 1 FROM hosted_rooms WHERE room_id=?", (room_id,)
).fetchone():
raise RoomConflictError(
"room_id already exists in the local authoritative store"
)
if conn.execute(
"SELECT 1 FROM hosted_room_retired_ids WHERE room_id=?",
(room_id,),
).fetchone():
if conn.execute("SELECT 1 FROM hosted_rooms WHERE room_id=?", (room_id,)).fetchone():
raise RoomConflictError("room_id already exists in the local authoritative store")
if conn.execute("SELECT 1 FROM hosted_room_retired_ids WHERE room_id=?", (room_id,)).fetchone():
raise RoomConflictError("room_id belongs to a disbanded room")
previous_gateway = str(replica["authority_gateway_id"])
previous_epoch = int(replica["authority_epoch"])
target_epoch = previous_epoch + 1
last_seq = int(replica["last_seq"])
claim_seq = last_seq + 1
claim_seq = int(replica["last_seq"]) + 1
claim_event_id = f"system:authority-claimed:{target_epoch}"
claim_actor_json, claim_payload_json = _control_event_json({
"previous_gateway_id": previous_gateway,
@@ -352,18 +300,12 @@ def promote_replica(
"promoted_from_replica": True,
"reason": reason,
})
claim_bytes = (
len(claim_event_id.encode("utf-8"))
+ len(b"authority.claimed")
+ len(claim_actor_json.encode("utf-8"))
+ len(claim_payload_json.encode("utf-8"))
)
claim_bytes = utf8_len(claim_event_id, "authority.claimed", claim_actor_json, claim_payload_json)
conn.execute(
"""INSERT INTO hosted_rooms
(room_id, name, members_json, authority_gateway_id,
authority_epoch, next_seq, event_bytes, revision,
created_at, updated_at, disbanded_at)
(room_id, name, members_json, authority_gateway_id, authority_epoch, next_seq, event_bytes,
revision, created_at, updated_at, disbanded_at)
VALUES (?, ?, ?, ?, ?, ?, ?, 1, ?, ?, NULL)""",
(
room_id, replica["name"], replica["members_json"], local_gateway, target_epoch,
@@ -371,11 +313,8 @@ def promote_replica(
),
)
conn.execute(
"""INSERT INTO hosted_room_events
(room_id, seq, event_id, kind, actor_json, authority_epoch,
payload_json, created_at)
SELECT room_id, seq, event_id, kind, actor_json,
authority_epoch, payload_json, created_at
f"""INSERT INTO hosted_room_events {_EVENT_COLUMNS}
SELECT room_id, seq, event_id, kind, actor_json, authority_epoch, payload_json, created_at
FROM hosted_room_replica_events WHERE room_id=?""",
(room_id,),
)
@@ -400,12 +339,7 @@ def promote_replica(
def demote_room(
db_path: Path | str,
*,
room_id: Any,
observed_gateway_id: Any,
observed_epoch: Any,
now: float | None = None,
db_path: Path | str, *, room_id: Any, observed_gateway_id: Any, observed_epoch: Any, now: float | None = None
) -> dict[str, Any]:
"""Fence THIS gateway's stale room authority against a proven newer epoch.
@@ -418,13 +352,11 @@ def demote_room(
observed_gateway_id = _validate_identifier(
observed_gateway_id, label="observed_gateway_id", max_chars=MAX_ACTOR_ID_CHARS
)
observed_epoch = _positive_int(
observed_epoch, "observed_epoch must be a positive integer"
)
observed_epoch = _positive_int(observed_epoch, "observed_epoch must be a positive integer")
now = _clock(now)
local_gateway = local_authority_gateway_id()
with _replica_transaction(db_path) as conn:
with _transaction(db_path, immediate=True) as conn:
row = conn.execute(
"""SELECT authority_gateway_id, authority_epoch, next_seq
FROM hosted_rooms WHERE room_id=? AND disbanded_at IS NULL""",
@@ -442,9 +374,7 @@ def demote_room(
"idempotent": True,
}
if observed_epoch <= current_epoch:
raise ReplicaEpochRegressionError(
"observed epoch does not supersede the stored authority"
)
raise ReplicaEpochRegressionError("observed epoch does not supersede the stored authority")
if current_gateway != local_gateway:
raise ReplicaError("room is not locally authoritative; nothing to demote")
lost_actor_json, lost_payload_json = _control_event_json({
@@ -461,8 +391,7 @@ def demote_room(
)
conn.execute(
"""UPDATE hosted_rooms
SET authority_gateway_id=?, authority_epoch=?,
next_seq=next_seq+1, revision=revision+1, updated_at=?
SET authority_gateway_id=?, authority_epoch=?, next_seq=next_seq+1, revision=revision+1, updated_at=?
WHERE room_id=?""",
(observed_gateway_id, observed_epoch, now, room_id),
)