hosted_rooms.py 66 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166116711681169117011711172117311741175117611771178117911801181118211831184118511861187118811891190119111921193119411951196119711981199120012011202120312041205120612071208120912101211121212131214121512161217121812191220122112221223
  1. """Durable state for gateway-hosted Bot Mode rooms.
  2. Owns only hosted-room identity and its append-only event log; delivery, relay leasing and agent turns
  3. belong to the relay and the hosted-room driver, so the log composes with a durable relay without a second
  4. transport queue. Callers supply the database path (production handlers use the gateway's root ``state.db``).
  5. """
  6. from __future__ import annotations
  7. import hashlib
  8. import json
  9. import re
  10. import sqlite3
  11. from contextlib import closing
  12. from functools import partial
  13. from pathlib import Path
  14. from typing import Any, Callable, Mapping
  15. from gateway.hosted_rooms_common import (
  16. DbPath, bounded_int, canonical_json, clock as _now, compact_json, connect, fenced_update as _fenced_update,
  17. identifier, open_sqlite, table_columns, table_exists, transaction, utf8_len)
  18. PROTOCOL_VERSION = 2
  19. MAX_ROOM_ID_CHARS = 128
  20. MAX_EVENT_ID_CHARS = 128
  21. MAX_ROOM_NAME_CHARS = 200
  22. MAX_EVENT_KIND_CHARS = 64
  23. MAX_ACTOR_ID_CHARS = 128
  24. MAX_ACTOR_LABEL_CHARS = 200
  25. MAX_MEMBERS = 128
  26. MAX_MEMBERS_JSON_BYTES = 128 * 1024
  27. MAX_EVENT_JSON_BYTES = 256 * 1024
  28. MAX_LOG_LIMIT = 500
  29. MAX_LOG_PAGE_BYTES = 2 * 1024 * 1024
  30. MAX_ROOM_LIST_LIMIT = 500
  31. MAX_ACTIVE_ROOMS = 256
  32. MAX_DISBANDED_ROOM_TOMBSTONES = 512
  33. DISBANDED_ROOM_RETENTION_SECONDS = 90 * 24 * 60 * 60
  34. MAX_EVENTS_PER_ROOM = 50_000
  35. MAX_ROOM_EVENT_BYTES = 256 * 1024 * 1024
  36. # Leave substantial headroom below the pre-update state.db snapshot ceiling: event accounting excludes
  37. # SQLite indexes and repeated room ids, so the logical budget must stay well below the physical-file limit.
  38. MAX_GATEWAY_EVENT_BYTES = 16 * 1024 * 1024
  39. CONTROL_EVENT_COUNT_RESERVE = 64
  40. CONTROL_EVENT_BYTE_RESERVE = 1024 * 1024
  41. _JOURNAL_MODE_LOCK_RETRIES = 8
  42. _EVENT_KIND_RE = re.compile(r"^[a-z][a-z0-9_.-]*$")
  43. _CONTROL_EVENT_KINDS = frozenset({"authority.claimed", "authority.lost", "room.disbanded", "room.stop_requested"})
  44. _EVENT_KINDS_BY_ACTOR = {
  45. "user": frozenset({"message.user"}), "member": frozenset({"message.member"}),
  46. "gateway": frozenset({
  47. "member.unavailable", "room.activity", "room.assignment", "room.continued", "room.routed", "room.stop_requested",
  48. "turn.deferred", "turn.reassigned",
  49. "turn.cancelled", "turn.failed", "turn.settled", "turn.started"}),
  50. "system": frozenset({
  51. "authority.claimed", "authority.lost", "room.context_set", "room.created", "room.disbanded",
  52. "room.members_changed", "room.renamed"})}
  53. _OPTIONAL_ACTOR_FIELDS = (
  54. ("display_name", MAX_ACTOR_LABEL_CHARS), ("profile", MAX_ACTOR_ID_CHARS), ("connection_id", MAX_ACTOR_ID_CHARS))
  55. _ACTOR_FIELDS = frozenset({"kind", "id", *(field for field, _ in _OPTIONAL_ACTOR_FIELDS)})
  56. # --- schema -----------------------------------------------------------------
  57. _REMOTE_RUN_IDENTITY_COLUMNS = (
  58. "room_id", "home_install_id", "authority_gateway_id", "authority_epoch", "member_id", "target_install_id",
  59. "target_profile", "task_id", "execution_generation")
  60. _REMOTE_RUNS_BODY = """
  61. room_id TEXT NOT NULL,
  62. home_install_id TEXT NOT NULL,
  63. authority_gateway_id TEXT NOT NULL,
  64. authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 1),
  65. member_id TEXT NOT NULL,
  66. task_id TEXT NOT NULL,
  67. execution_generation INTEGER NOT NULL CHECK (execution_generation >= 1),
  68. target_install_id TEXT NOT NULL,
  69. target_profile TEXT NOT NULL,
  70. run_id TEXT NOT NULL,
  71. session_id TEXT NOT NULL,
  72. created_at REAL NOT NULL,
  73. updated_at REAL NOT NULL,
  74. PRIMARY KEY (
  75. room_id, home_install_id, authority_gateway_id, authority_epoch,
  76. member_id, target_install_id, target_profile, task_id,
  77. execution_generation
  78. )
  79. """
  80. # Executed in this exact order on first open / migration.
  81. _SCHEMA_DDL = (
  82. """CREATE TABLE IF NOT EXISTS hosted_rooms (
  83. room_id TEXT PRIMARY KEY,
  84. name TEXT NOT NULL,
  85. members_json TEXT NOT NULL,
  86. authority_gateway_id TEXT NOT NULL,
  87. authority_epoch INTEGER NOT NULL DEFAULT 1 CHECK (authority_epoch >= 1),
  88. next_seq INTEGER NOT NULL DEFAULT 1 CHECK (next_seq >= 1),
  89. event_bytes INTEGER NOT NULL DEFAULT 0 CHECK (event_bytes >= 0),
  90. revision INTEGER NOT NULL DEFAULT 1 CHECK (revision >= 1),
  91. created_at REAL NOT NULL,
  92. updated_at REAL NOT NULL,
  93. disbanded_at REAL
  94. )""",
  95. """CREATE TABLE IF NOT EXISTS hosted_room_events (
  96. room_id TEXT NOT NULL,
  97. seq INTEGER NOT NULL CHECK (seq >= 1),
  98. event_id TEXT NOT NULL,
  99. kind TEXT NOT NULL,
  100. actor_json TEXT NOT NULL,
  101. authority_epoch INTEGER CHECK (authority_epoch IS NULL OR authority_epoch >= 1),
  102. payload_json TEXT NOT NULL,
  103. created_at REAL NOT NULL,
  104. PRIMARY KEY (room_id, seq),
  105. UNIQUE (room_id, event_id),
  106. FOREIGN KEY (room_id) REFERENCES hosted_rooms(room_id)
  107. )""",
  108. """CREATE TABLE IF NOT EXISTS hosted_room_retired_ids (
  109. room_id TEXT PRIMARY KEY,
  110. retired_at REAL NOT NULL
  111. )""",
  112. """CREATE TABLE IF NOT EXISTS hosted_room_links (
  113. room_id TEXT NOT NULL,
  114. member_id TEXT NOT NULL,
  115. target_url TEXT NOT NULL,
  116. target_profile TEXT NOT NULL,
  117. grant TEXT NOT NULL,
  118. catalog_json TEXT NOT NULL,
  119. cancellation_scope_id TEXT NOT NULL,
  120. trace_id TEXT NOT NULL,
  121. transport_security TEXT NOT NULL,
  122. status TEXT NOT NULL DEFAULT 'ready',
  123. updated_at REAL NOT NULL,
  124. PRIMARY KEY (room_id, member_id)
  125. )""", f"CREATE TABLE IF NOT EXISTS hosted_room_remote_runs ({_REMOTE_RUNS_BODY})",
  126. """CREATE TABLE IF NOT EXISTS hosted_room_revoked_grants (
  127. scope_key TEXT PRIMARY KEY,
  128. expires_at REAL NOT NULL,
  129. revoked_before REAL NOT NULL
  130. )""",
  131. """CREATE TABLE IF NOT EXISTS hosted_room_peer_reservations (
  132. room_id TEXT NOT NULL,
  133. member_id TEXT NOT NULL,
  134. target_profile TEXT NOT NULL,
  135. authority_gateway_id TEXT NOT NULL,
  136. authority_epoch INTEGER NOT NULL CHECK (authority_epoch >= 1),
  137. expires_at REAL NOT NULL,
  138. revoked_at REAL,
  139. created_at REAL NOT NULL,
  140. updated_at REAL NOT NULL,
  141. PRIMARY KEY (room_id, member_id, target_profile)
  142. )""")
  143. # (table, required columns) parsed from the DDL, in the order _schema_is_current probes them.
  144. _REQUIRED_COLUMNS = tuple(
  145. (re.search(r"EXISTS (\w+)", ddl).group(1),
  146. frozenset(re.findall(r"^\s*(\w+) (?:TEXT|INTEGER|REAL)\b", ddl.split("(", 1)[1], re.MULTILINE))) for ddl in _SCHEMA_DDL)
  147. _REMOTE_RUN_SCHEMA_COLUMNS = _REQUIRED_COLUMNS[4][1]
  148. # --- SQL fragments (statement text must stay byte-stable after whitespace normalisation) ---
  149. _EVENT_COLUMNS = ("room_id, seq, event_id, kind, actor_json, authority_epoch, payload_json, created_at")
  150. _SELECT_EVENT = f"SELECT {_EVENT_COLUMNS} FROM hosted_room_events WHERE room_id=? AND event_id=?"
  151. _INSERT_EVENT = (f"INSERT INTO hosted_room_events ({_EVENT_COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?)")
  152. _ROOM_COLUMNS = (
  153. "room_id, name, members_json, authority_gateway_id, authority_epoch, next_seq, revision,"
  154. " created_at, updated_at, disbanded_at")
  155. _ROOM_COLUMNS_WITH_BYTES = (
  156. "room_id, name, members_json, authority_gateway_id, authority_epoch, next_seq, event_bytes,"
  157. " revision, created_at, updated_at, disbanded_at")
  158. _SELECT_ROOM = f"SELECT {_ROOM_COLUMNS} FROM hosted_rooms WHERE room_id=?"
  159. _SELECT_ROOM_WITH_BYTES = f"SELECT {_ROOM_COLUMNS_WITH_BYTES} FROM hosted_rooms WHERE room_id=?"
  160. _SUM_EVENT_BYTES = "SELECT COALESCE(SUM(event_bytes), 0) FROM hosted_rooms"
  161. _INSERT_RETIRED = ("INSERT OR IGNORE INTO hosted_room_retired_ids (room_id, retired_at) VALUES (?, ?)")
  162. _RETIRE_FROM_ROOMS = (
  163. "INSERT OR IGNORE INTO hosted_room_retired_ids (room_id, retired_at)"
  164. " SELECT room_id, disbanded_at FROM hosted_rooms WHERE {where}")
  165. _LINK_COLUMNS = (
  166. "room_id", "member_id", "target_url", "target_profile", "grant", "catalog_json", "cancellation_scope_id",
  167. "trace_id", "transport_security", "status", "updated_at")
  168. _REMOTE_RUN_WHERE = " AND ".join(f"{column}=?" for column in _REMOTE_RUN_IDENTITY_COLUMNS)
  169. _SELECT_REMOTE_RUN = f"SELECT * FROM hosted_room_remote_runs WHERE {_REMOTE_RUN_WHERE}"
  170. _LIVE_RESERVATION_WHERE = ("WHERE room_id=? AND target_profile=? AND expires_at>? AND revoked_at IS NULL")
  171. _SELECT_LIVE_RESERVATION = (f"SELECT 1 FROM hosted_room_peer_reservations {_LIVE_RESERVATION_WHERE} LIMIT 1")
  172. class HostedRoomError(ValueError): """Base class for invalid or conflicting hosted-room operations."""
  173. class RoomNotFoundError(HostedRoomError): """Raised when a room does not exist or has been disbanded."""
  174. class RoomHistoryExpiredError(RoomNotFoundError):
  175. """Raised when a retired room remains reserved after history compaction."""
  176. reason = "room_history_expired"
  177. class RoomConflictError(HostedRoomError): """Raised when an idempotency key is reused for different room state."""
  178. class RoomProbeUnavailableError(HostedRoomError):
  179. """Raised when a non-blocking ownership probe cannot read the room store."""
  180. class EventConflictError(HostedRoomError): """Raised when an event id is reused with different immutable content."""
  181. class EventCursorConflictError(HostedRoomError):
  182. """Raised when new room events invalidate an uncommitted publication plan."""
  183. class EventAttachmentConflictError(EventCursorConflictError):
  184. """A publication lost its file commitments; use the same fresh-plan retry."""
  185. class AuthorityConflictError(HostedRoomError):
  186. """Raised when a stale room authority attempts to mutate hosted state."""
  187. reason = "authority_conflict"
  188. class AuthoritySupersededError(AuthorityConflictError):
  189. """Raised when a successful authority claim was later superseded."""
  190. # --- validation ---------------------------------------------------------------
  191. _canonical_json = partial(canonical_json, error=HostedRoomError, ensure_ascii=False)
  192. _validate_identifier = partial(identifier, error=HostedRoomError)
  193. _room_id = partial(_validate_identifier, label="room_id", max_chars=MAX_ROOM_ID_CHARS)
  194. _event_id = partial(_validate_identifier, label="event_id", max_chars=MAX_EVENT_ID_CHARS)
  195. _actor_json = partial(_canonical_json, label="actor", max_bytes=4 * 1024)
  196. _payload_json = partial(_canonical_json, label="payload", max_bytes=MAX_EVENT_JSON_BYTES)
  197. _bounded_int = partial(bounded_int, error=HostedRoomError)
  198. _validate_room_name = partial(
  199. _validate_identifier, label="name", max_chars=MAX_ROOM_NAME_CHARS, pattern=None, invalid="invalid room name")
  200. _validate_event_kind = partial(
  201. _validate_identifier, label="kind", max_chars=MAX_EVENT_KIND_CHARS, pattern=_EVENT_KIND_RE,
  202. invalid="invalid event kind")
  203. def _actor_id(value: Any, label: str) -> str:
  204. return _validate_identifier(value, label=label, max_chars=MAX_ACTOR_ID_CHARS)
  205. def _require_positive_int(value: Any, label: str) -> int:
  206. return _bounded_int(value, message=f"{label} must be a positive integer", low=1)
  207. def _bounded_limit(value: Any, maximum: int) -> int:
  208. return _bounded_int(value, message=f"limit must be between 1 and {maximum}", low=1, high=maximum)
  209. def _non_negative(value: Any, label: str) -> int:
  210. return _bounded_int(value, message=f"{label} must be a non-negative integer")
  211. def _system_actor_json(actor_id: str) -> str:
  212. return _actor_json({"kind": "system", "id": actor_id})
  213. def _claim_payload_json(previous_gateway_id: str, new_gateway_id: str, epoch: int) -> str:
  214. return _payload_json(
  215. {"previous_gateway_id": previous_gateway_id, "authority_gateway_id": new_gateway_id, "authority_epoch": epoch})
  216. def user_event_id(client_event_id: Any) -> str:
  217. """Map a client retry key into the server-owned user-event namespace."""
  218. return f"user:{hashlib.sha256(_event_id(client_event_id).encode('utf-8')).hexdigest()}"
  219. def _validate_members(value: Any) -> tuple[list[dict[str, Any]], str]:
  220. if not isinstance(value, list):
  221. raise HostedRoomError("members must be a list")
  222. if len(value) > MAX_MEMBERS:
  223. raise HostedRoomError("too many room members")
  224. if not all(isinstance(member, dict) for member in value):
  225. raise HostedRoomError("each room member must be an object")
  226. members = [dict(member) for member in value]
  227. return members, _canonical_json(members, label="members", max_bytes=MAX_MEMBERS_JSON_BYTES)
  228. def _legacy_members_match(existing_json: str, proposed: list[dict[str, Any]]) -> bool:
  229. """Allow adoption to add routing metadata an older room could not store."""
  230. try:
  231. existing = json.loads(existing_json)
  232. except (TypeError, ValueError):
  233. return False
  234. if not isinstance(existing, list) or len(existing) != len(proposed):
  235. return False
  236. for previous, current in zip(existing, proposed, strict=True):
  237. if not isinstance(previous, dict):
  238. return False
  239. previous, current = dict(previous), dict(current)
  240. previous_target, current_target = previous.pop("target", None), current.pop("target", None)
  241. if previous != current or (previous_target not in (None, {}) and previous_target != current_target):
  242. return False
  243. return True
  244. def _validate_actor(value: Any, *, kind: str) -> tuple[dict[str, str], str]:
  245. if not isinstance(value, dict):
  246. raise HostedRoomError("actor must be an object")
  247. unknown = set(value) - _ACTOR_FIELDS
  248. if unknown:
  249. raise HostedRoomError(f"unknown actor fields: {', '.join(sorted(unknown))}")
  250. actor_kind = value.get("kind")
  251. if not isinstance(actor_kind, str) or actor_kind not in _EVENT_KINDS_BY_ACTOR:
  252. raise HostedRoomError("invalid actor.kind")
  253. if kind not in _EVENT_KINDS_BY_ACTOR[actor_kind]:
  254. raise HostedRoomError(f"actor kind '{actor_kind}' cannot append '{kind}'")
  255. actor = {"kind": actor_kind, "id": _actor_id(value.get("id"), "actor.id")}
  256. for field, max_chars in _OPTIONAL_ACTOR_FIELDS:
  257. field_value = value.get(field)
  258. if field_value is None:
  259. continue
  260. if not isinstance(field_value, str):
  261. raise HostedRoomError(f"actor.{field} must be a string")
  262. if len(field_value := field_value.strip()) > max_chars:
  263. raise HostedRoomError(f"actor.{field} is too long")
  264. if field_value:
  265. actor[field] = field_value
  266. return actor, _actor_json(actor)
  267. # --- schema / connections -------------------------------------------------------
  268. def _remote_run_schema_current(conn: sqlite3.Connection, columns: frozenset[str]) -> bool:
  269. if not _REMOTE_RUN_SCHEMA_COLUMNS.issubset(columns):
  270. return False
  271. pk_rows = [row for row in conn.execute("PRAGMA table_info(hosted_room_remote_runs)") if row[5]]
  272. return tuple(str(row[1]) for row in sorted(pk_rows, key=lambda row: int(row[5]))) == _REMOTE_RUN_IDENTITY_COLUMNS
  273. def _migrate_remote_run_schema(conn: sqlite3.Connection) -> None:
  274. """Fence legacy receipts behind a complete authority-lineage key."""
  275. columns = table_columns(conn, "hosted_room_remote_runs")
  276. if _remote_run_schema_current(conn, columns):
  277. return
  278. conn.execute("DROP TABLE IF EXISTS hosted_room_remote_runs_migrating")
  279. conn.execute(f"CREATE TABLE hosted_room_remote_runs_migrating ({_REMOTE_RUNS_BODY})")
  280. if columns:
  281. fallbacks = (("home_install_id", "'legacy'"), ("authority_gateway_id", "'legacy'"), ("authority_epoch", "1"))
  282. home, gateway, epoch = (column if column in columns else default for column, default in fallbacks)
  283. conn.execute(
  284. f"""INSERT OR IGNORE INTO hosted_room_remote_runs_migrating(
  285. room_id, home_install_id, authority_gateway_id,
  286. authority_epoch, member_id, task_id,
  287. execution_generation, target_install_id, target_profile,
  288. run_id, session_id, created_at, updated_at
  289. )
  290. SELECT room_id, {home}, {gateway}, {epoch}, member_id, task_id,
  291. execution_generation, target_install_id, target_profile,
  292. run_id, session_id, created_at, updated_at
  293. FROM hosted_room_remote_runs""")
  294. conn.execute("DROP TABLE hosted_room_remote_runs")
  295. conn.execute("ALTER TABLE hosted_room_remote_runs_migrating RENAME TO hosted_room_remote_runs")
  296. # Draft builds before the actor contract carried no identity. Preserve their inert replay rows explicitly
  297. # as legacy system events rather than guessing a user or Bot author.
  298. _LEGACY_ACTOR_JSON = _system_actor_json("legacy").replace("'", "''")
  299. # (table, column, declaration, default literal) applied in this exact order; each table's PRAGMA is read on
  300. # first use. The default is also what the pre-isolation import selects for a source that predates the column.
  301. _LEGACY_COLUMNS = (
  302. ("hosted_rooms", "authority_gateway_id", "TEXT NOT NULL", "'legacy'"),
  303. ("hosted_rooms", "authority_epoch", "INTEGER NOT NULL", "1"),
  304. ("hosted_rooms", "event_bytes", "INTEGER NOT NULL", "0"),
  305. ("hosted_room_events", "actor_json", "TEXT NOT NULL", f"'{_LEGACY_ACTOR_JSON}'"),
  306. ("hosted_room_events", "authority_epoch", "INTEGER", None))
  307. _EVENT_BYTES_BACKFILL = """UPDATE hosted_rooms
  308. SET event_bytes=COALESCE((
  309. SELECT SUM(
  310. length(CAST(event_id AS BLOB)) +
  311. length(CAST(kind AS BLOB)) +
  312. length(CAST(actor_json AS BLOB)) +
  313. length(CAST(payload_json AS BLOB))
  314. )
  315. FROM hosted_room_events
  316. WHERE hosted_room_events.room_id=hosted_rooms.room_id
  317. ), 0) WHERE {where}"""
  318. def _migrate_legacy_columns(conn: sqlite3.Connection) -> None:
  319. """Add columns draft schemas lacked; backfill event_bytes when first introduced."""
  320. columns: dict[str, frozenset[str]] = {}
  321. for table, column, declaration, default in _LEGACY_COLUMNS:
  322. if table not in columns:
  323. columns[table] = table_columns(conn, table)
  324. if column not in columns[table]:
  325. conn.execute(f"ALTER TABLE {table} ADD COLUMN {column} {declaration}"
  326. + (f" DEFAULT {default}" if default is not None else ""))
  327. if "event_bytes" not in columns["hosted_rooms"]:
  328. conn.execute(_EVENT_BYTES_BACKFILL.format(where="1"))
  329. _KIND_INDEX = "idx_hosted_room_events_kind"
  330. def _initialize_schema(conn: sqlite3.Connection) -> None:
  331. for statement in _SCHEMA_DDL:
  332. conn.execute(statement)
  333. _migrate_legacy_columns(conn)
  334. # Old schemas kept the final identity tombstone in hosted_rooms itself. Copy those identities before
  335. # bounded history pruning can remove their heavier room/event payloads. This compact registry is
  336. # intentionally permanent: a stale coordinate must never name a different Group Chat.
  337. conn.execute(_RETIRE_FROM_ROOMS.format(where="disbanded_at IS NOT NULL"))
  338. _migrate_remote_run_schema(conn)
  339. conn.execute("CREATE INDEX IF NOT EXISTS idx_hosted_room_events_cursor ON hosted_room_events(room_id, seq)")
  340. # Latest-event-of-a-kind reads (room purpose/notes) seek here instead of walking the room's history.
  341. conn.execute(f"CREATE INDEX IF NOT EXISTS {_KIND_INDEX} ON hosted_room_events(room_id, kind, seq)")
  342. if not _schema_is_current(conn):
  343. raise HostedRoomError("hosted room schema migration did not complete")
  344. def _schema_is_current(conn: sqlite3.Connection) -> bool:
  345. # Read every table first (fixed PRAGMA order), then compare.
  346. actual = [table_columns(conn, table) for table, _ in _REQUIRED_COLUMNS]
  347. return all(
  348. required.issubset(columns)
  349. and (table != "hosted_room_remote_runs" or _remote_run_schema_current(conn, columns))
  350. for (table, required), columns in zip(_REQUIRED_COLUMNS, actual, strict=True)) and conn.execute(
  351. "SELECT 1 FROM sqlite_master WHERE type='index' AND name='idx_hosted_room_events_cursor'"
  352. ).fetchone() is not None and conn.execute(
  353. "SELECT 1 FROM sqlite_master WHERE type='index' AND name=?", (_KIND_INDEX,)).fetchone() is not None
  354. def default_db_path() -> Path:
  355. """Return the hosted-room coordination database for the active install.
  356. Profile gateways (``~/.hermes/profiles/<name>/``) resolve to the shared
  357. ROOT ``shared-state.db`` instead of the master ``state.db``: hosted-room
  358. coordination is the only thing this module owns, and pointing profile
  359. gateways at the master session store makes every profile process a
  360. long-lived writer on state.db — the recurring multi-writer corruption
  361. vector observed across a 6-gateway fleet (state.db WAL/FTS collisions
  362. during bot-gateway restart storms, 2026-09-03). Keeping the hosted_room*
  363. tables in a dedicated file means profile gateways never open the master
  364. session store writable.
  365. """
  366. from hermes_constants import get_hermes_home
  367. home = get_hermes_home()
  368. return (home.parent.parent if home.parent.name == "profiles" else home) / "shared-state.db"
  369. def local_authority_gateway_id() -> str:
  370. """Return the stable server-owned identity for hosted-room authority."""
  371. from hermes_cli.install_identity import get_install_id
  372. install_id = get_install_id()
  373. if not install_id:
  374. raise HostedRoomError("stable gateway install identity is unavailable")
  375. return _actor_id(f"install:{install_id}", "authority_gateway_id")
  376. def _store_ready(conn: sqlite3.Connection, db_path: Path) -> bool:
  377. """The store can serve rooms once its schema is current and the pre-isolation import has run."""
  378. from gateway.hosted_rooms_legacy_import import settled
  379. return _schema_is_current(conn) and settled(conn, db_path)
  380. def _initialize_store(conn: sqlite3.Connection, db_path: Path) -> None:
  381. """Create or migrate the schema, then copy the pre-isolation rows in (#109775)."""
  382. from gateway.hosted_rooms_legacy_import import import_legacy_rooms
  383. _initialize_schema(conn)
  384. import_legacy_rooms(conn, db_path)
  385. def _connect(db_path: DbPath) -> sqlite3.Connection:
  386. """Open the shared room store; ``initialize`` carries the path so the one-shot import can find it."""
  387. path = Path(db_path)
  388. return connect(
  389. path, db_label="shared-state.db (hosted_rooms)", ready=partial(_store_ready, db_path=path),
  390. initialize=partial(_initialize_store, db_path=path), lock_retries=_JOURNAL_MODE_LOCK_RETRIES)
  391. def _read_connection(db_path: DbPath) -> sqlite3.Connection:
  392. """Open the room store without steady-state journal or migration writes."""
  393. path = Path(db_path)
  394. if not path.is_file():
  395. _connect(path).close()
  396. conn = open_sqlite(path)
  397. if not _store_ready(conn, path):
  398. conn.close()
  399. _connect(path).close()
  400. conn = open_sqlite(path)
  401. return conn
  402. _transaction = partial(transaction, _connect, immediate=False)
  403. # --- row helpers ------------------------------------------------------------------
  404. def _is_retired(conn: sqlite3.Connection, room_id: str) -> bool:
  405. return conn.execute("SELECT 1 FROM hosted_room_retired_ids WHERE room_id=?", (room_id,)).fetchone() is not None
  406. def _room_row(conn: sqlite3.Connection, sql: str, params: tuple[Any, ...], room_id: str) -> sqlite3.Row:
  407. """Fetch one hosted_rooms row or raise the precise not-found/expired error."""
  408. row = conn.execute(sql, params).fetchone()
  409. if row is not None:
  410. return row
  411. # A retained disband tombstone still has replayable history; the caller did not opt into disbanded rooms.
  412. retained = conn.execute("SELECT 1 FROM hosted_rooms WHERE room_id=?", (room_id,)).fetchone()
  413. if retained is None and _is_retired(conn, room_id):
  414. raise RoomHistoryExpiredError("Group Chat history expired; room_id remains permanently retired")
  415. raise RoomNotFoundError("hosted room not found")
  416. def _require_authority(room: sqlite3.Row, gateway_id: str, epoch: int, message: str) -> None:
  417. if str(room["authority_gateway_id"]) != gateway_id or int(room["authority_epoch"]) != epoch:
  418. raise AuthorityConflictError(message)
  419. def _reload(conn: sqlite3.Connection, sql: str, params: tuple, missing: str) -> sqlite3.Row:
  420. """Re-read a row this transaction just wrote; a miss is an invariant violation."""
  421. row = conn.execute(sql, params).fetchone()
  422. if row is None: # pragma: no cover - guarded by the write above
  423. raise RuntimeError(missing)
  424. return row
  425. def _room_from_row(row: sqlite3.Row, *, idempotent: bool = False) -> dict[str, Any]:
  426. keys = row.keys() # sqlite3.Row: ``x in row`` scans values, so ``.keys()`` is load-bearing.
  427. return {
  428. "room_id": row["room_id"], "name": row["name"], "members": json.loads(row["members_json"]),
  429. "authority_gateway_id": row["authority_gateway_id"], "authority_epoch": int(row["authority_epoch"]),
  430. "revision": int(row["revision"]), "created_at": float(row["created_at"]),
  431. "updated_at": float(row["updated_at"]), "idempotent": idempotent,
  432. **({"disbanded_at": float(row["disbanded_at"])} if "disbanded_at" in keys and row["disbanded_at"] is not None
  433. else {}),
  434. **({"latest_seq": int(row["next_seq"]) - 1} if "next_seq" in keys else {})}
  435. def _event_from_row(row: sqlite3.Row, *, idempotent: bool = False) -> dict[str, Any]:
  436. epoch = row["authority_epoch"]
  437. return {
  438. "room_id": row["room_id"], "seq": int(row["seq"]), "event_id": row["event_id"], "kind": row["kind"],
  439. "actor": json.loads(row["actor_json"]), "authority_epoch": int(epoch) if epoch is not None else None,
  440. "payload": json.loads(row["payload_json"]), "created_at": float(row["created_at"]), "idempotent": idempotent}
  441. def _load_event(conn: sqlite3.Connection, room_id: str, event_id: str) -> sqlite3.Row | None:
  442. return conn.execute(_SELECT_EVENT, (room_id, event_id)).fetchone()
  443. def _event_content(row: sqlite3.Row) -> tuple[Any, Any, Any, Any]:
  444. """The immutable (kind, actor_json, authority_epoch, payload_json) an event id is bound to."""
  445. return row["kind"], row["actor_json"], row["authority_epoch"], row["payload_json"]
  446. def _gateway_event_bytes(conn: sqlite3.Connection) -> int:
  447. return int(conn.execute(_SUM_EVENT_BYTES).fetchone()[0])
  448. def _insert_event(
  449. conn: sqlite3.Connection, room: sqlite3.Row, room_id: str, seq: int, event_id: str, kind: str, actor_json: str,
  450. epoch: int, payload_json: str, now: float, *, allow_control: bool = False) -> int:
  451. """Capacity-check then INSERT one event at ``seq``; returns its accounted bytes."""
  452. event_bytes = _prepare_event(conn, room, event_id, kind, actor_json, payload_json, allow_control=allow_control)
  453. conn.execute(_INSERT_EVENT, (room_id, seq, event_id, kind, actor_json, epoch, payload_json, now))
  454. return event_bytes
  455. def _prepare_event(
  456. conn: sqlite3.Connection, room: sqlite3.Row, event_id: str, kind: str, actor_json: str, payload_json: str, *,
  457. allow_control: bool = False) -> int:
  458. """Size one pending event and enforce per-room and gateway capacity; returns its bytes."""
  459. additional_bytes = utf8_len(event_id, kind, actor_json, payload_json)
  460. count_reserve, byte_reserve = (CONTROL_EVENT_COUNT_RESERVE, CONTROL_EVENT_BYTE_RESERVE) if allow_control else (0, 0)
  461. gateway_byte_limit = MAX_GATEWAY_EVENT_BYTES + byte_reserve
  462. if int(room["next_seq"]) - 1 >= MAX_EVENTS_PER_ROOM + count_reserve:
  463. raise HostedRoomError("This Group Chat reached its history limit. Start a new Group Chat to continue.")
  464. if int(room["event_bytes"]) + additional_bytes > MAX_ROOM_EVENT_BYTES + byte_reserve:
  465. raise HostedRoomError("This Group Chat reached its storage limit. Start a new Group Chat to continue.")
  466. gateway_bytes = _gateway_event_bytes(conn)
  467. if gateway_bytes + additional_bytes > gateway_byte_limit:
  468. _prune_disbanded_rooms_locked(
  469. conn, now=None, max_gateway_event_bytes=max(0, gateway_byte_limit - additional_bytes))
  470. gateway_bytes = _gateway_event_bytes(conn)
  471. if gateway_bytes + additional_bytes > gateway_byte_limit:
  472. raise HostedRoomError("Group Chat storage is full on this host. Delete an old Group Chat and try again.")
  473. return additional_bytes
  474. # --- retention -------------------------------------------------------------------
  475. # Deleted in this order when a disbanded room's payload is purged.
  476. _DEPENDENT_TABLES = (
  477. "hosted_room_policy_transcript_state", "hosted_room_policy_transcript", "hosted_room_policy_publications",
  478. "hosted_room_policy_watermarks", "hosted_room_policy_events", "hosted_room_policy_threads",
  479. "hosted_room_policy_cursors", "hosted_room_driver_tasks", "hosted_room_driver_leases", "hosted_room_remote_runs",
  480. "hosted_room_links", "hosted_room_peer_reservations", "hosted_room_events")
  481. def _room_ids(conn: sqlite3.Connection, sql: str, params: tuple[Any, ...]) -> list[str]:
  482. return [str(row["room_id"]) for row in conn.execute(sql, params).fetchall()]
  483. def _prune_disbanded_rooms_locked(
  484. conn: sqlite3.Connection, *, now: float | None, max_gateway_event_bytes: int | None = None) -> int:
  485. candidates: set[str] = set()
  486. if now is not None:
  487. candidates.update(_room_ids(
  488. conn, """SELECT room_id FROM hosted_rooms
  489. WHERE disbanded_at IS NOT NULL AND disbanded_at<=?""", (now - DISBANDED_ROOM_RETENTION_SECONDS,)))
  490. candidates.update(_room_ids(
  491. conn, """SELECT room_id FROM hosted_rooms WHERE disbanded_at IS NOT NULL
  492. ORDER BY disbanded_at DESC, room_id ASC LIMIT -1 OFFSET ?""", (MAX_DISBANDED_ROOM_TOMBSTONES,)))
  493. if max_gateway_event_bytes is not None:
  494. retained_bytes = _gateway_event_bytes(conn)
  495. if retained_bytes > max_gateway_event_bytes:
  496. for row in conn.execute("""SELECT room_id, event_bytes FROM hosted_rooms WHERE disbanded_at IS NOT NULL
  497. ORDER BY disbanded_at ASC, room_id ASC"""
  498. ).fetchall():
  499. candidates.add(str(row["room_id"]))
  500. retained_bytes -= int(row["event_bytes"])
  501. if retained_bytes <= max_gateway_event_bytes:
  502. break
  503. if not candidates:
  504. return 0
  505. placeholders = ",".join("?" for _ in candidates)
  506. room_ids = tuple(sorted(candidates))
  507. conn.execute(_RETIRE_FROM_ROOMS.format(where=f"room_id IN ({placeholders}) AND disbanded_at IS NOT NULL"), room_ids)
  508. for table in _DEPENDENT_TABLES:
  509. if table_exists(conn, table):
  510. conn.execute(f"DELETE FROM {table} WHERE room_id IN ({placeholders})", room_ids)
  511. conn.execute(f"DELETE FROM hosted_rooms WHERE room_id IN ({placeholders})", room_ids)
  512. return len(room_ids)
  513. def prune_disbanded_rooms(db_path: DbPath, *, now: float | None = None) -> int:
  514. """Purge deleted Group Chat payloads while reserving their identities."""
  515. with _transaction(db_path, immediate=True) as conn:
  516. return _prune_disbanded_rooms_locked(conn, now=_now(now))
  517. # --- room links / grants / reservations / remote runs ---------------------------------
  518. def list_room_link_records(db_path: DbPath) -> list[dict[str, Any]]:
  519. """Return private RoomLink records without logging or formatting grants."""
  520. with _transaction(db_path) as conn:
  521. rows = conn.execute("""SELECT room_id, member_id, target_url, target_profile, grant,
  522. catalog_json, cancellation_scope_id, trace_id,
  523. transport_security, status, updated_at
  524. FROM hosted_room_links
  525. ORDER BY room_id, member_id""").fetchall()
  526. return [dict(row) for row in rows]
  527. def upsert_room_link_record(db_path: DbPath, *, record: Mapping[str, Any], max_links: int) -> None:
  528. """Atomically insert or replace one private RoomLink record."""
  529. with _transaction(db_path, immediate=True) as conn:
  530. existing = conn.execute(
  531. "SELECT 1 FROM hosted_room_links WHERE room_id=? AND member_id=?", (record["room_id"], record["member_id"])
  532. ).fetchone()
  533. if existing is None and int(conn.execute("SELECT COUNT(*) FROM hosted_room_links").fetchone()[0]) >= max_links:
  534. raise HostedRoomError("too many stored room links")
  535. conn.execute("""INSERT INTO hosted_room_links(
  536. room_id, member_id, target_url, target_profile, grant,
  537. catalog_json, cancellation_scope_id, trace_id,
  538. transport_security, status, updated_at
  539. ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
  540. ON CONFLICT(room_id, member_id) DO UPDATE SET
  541. target_url=excluded.target_url,
  542. target_profile=excluded.target_profile,
  543. grant=excluded.grant,
  544. catalog_json=excluded.catalog_json,
  545. cancellation_scope_id=excluded.cancellation_scope_id,
  546. trace_id=excluded.trace_id,
  547. transport_security=excluded.transport_security,
  548. status=excluded.status,
  549. updated_at=excluded.updated_at""",
  550. tuple(record[column] for column in _LINK_COLUMNS))
  551. def update_room_link_status(
  552. db_path: DbPath, *, room_id: str, member_id: str, status: str, now: float | None = None) -> bool:
  553. """Persist a non-secret route health classification."""
  554. with _transaction(db_path, immediate=True) as conn:
  555. return conn.execute(
  556. "UPDATE hosted_room_links SET status=?, updated_at=? WHERE room_id=? AND member_id=?",
  557. (status, _now(now), room_id, member_id)).rowcount == 1
  558. def delete_room_link_records(db_path: DbPath, *, room_id: str) -> int:
  559. """Delete persisted peer routes after their target grants are revoked."""
  560. with _transaction(db_path, immediate=True) as conn:
  561. return conn.execute("DELETE FROM hosted_room_links WHERE room_id=?", (room_id,)).rowcount
  562. def _claim_values(claims: Mapping[str, Any], keys: tuple[str, ...]) -> dict[str, str]:
  563. return {key: str(claims.get(key) or "") for key in keys}
  564. def _room_grant_scope_key(claims: Mapping[str, Any]) -> str:
  565. """Return a stable non-secret key for one room/home/target/profile scope."""
  566. fields = _claim_values(claims, (
  567. "room_id", "home_install_id", "authority_gateway_id", "authority_epoch", "member_id", "target_install_id",
  568. "target_profile"))
  569. if not all(fields.values()):
  570. raise HostedRoomError("room grant scope is incomplete")
  571. return hashlib.sha256(compact_json(fields).encode("utf-8")).hexdigest()
  572. def revoke_room_grant_scope(
  573. db_path: DbPath, *, claims: Mapping[str, Any], expires_at: float, now: float | None = None) -> None:
  574. """Revoke every grant issued at or before now for one exact room scope."""
  575. scope_key = _room_grant_scope_key(claims)
  576. timestamp = _now(now)
  577. expiry = float(expires_at)
  578. if expiry <= timestamp:
  579. return
  580. with _transaction(db_path, immediate=True) as conn:
  581. conn.execute("DELETE FROM hosted_room_revoked_grants WHERE expires_at<=?", (timestamp,))
  582. conn.execute("""INSERT INTO hosted_room_revoked_grants(
  583. scope_key, expires_at, revoked_before
  584. ) VALUES (?, ?, ?)
  585. ON CONFLICT(scope_key) DO UPDATE SET
  586. expires_at=MAX(hosted_room_revoked_grants.expires_at,
  587. excluded.expires_at),
  588. revoked_before=MAX(hosted_room_revoked_grants.revoked_before,
  589. excluded.revoked_before)""", (scope_key, expiry, timestamp))
  590. conn.execute("""UPDATE hosted_room_peer_reservations SET revoked_at=?, updated_at=? WHERE room_id=?
  591. AND member_id=? AND target_profile=? AND authority_gateway_id=?
  592. AND authority_epoch=?""",
  593. (
  594. timestamp, timestamp,
  595. *_claim_values(claims, ("room_id", "member_id", "target_profile", "authority_gateway_id")).values(),
  596. int(claims.get("authority_epoch") or 0)))
  597. def _reservation_claims(claims: Mapping[str, Any]) -> tuple[str, str, str, str, int]:
  598. """Validate (room_id, member_id, target_profile, authority_gateway_id, authority_epoch)."""
  599. values = (
  600. _room_id(claims.get("room_id")),
  601. *(_actor_id(claims.get(key), key) for key in ("member_id", "target_profile", "authority_gateway_id")),
  602. int(claims.get("authority_epoch") or 0))
  603. if values[4] < 1:
  604. raise HostedRoomError("authority_epoch must be positive")
  605. return values
  606. def _reservation_superseded(row: sqlite3.Row, gateway_id: str, epoch: int) -> bool:
  607. """A newer epoch, or the same epoch under another gateway, outranks this claim."""
  608. row_epoch = int(row["authority_epoch"])
  609. return row_epoch > epoch or (row_epoch == epoch and str(row["authority_gateway_id"]) != gateway_id)
  610. def reserve_peer_room(
  611. db_path: DbPath, *, claims: Mapping[str, Any], expires_at: float, now: float | None = None) -> None:
  612. """Fence direct Desktop prompts before the first peer run is admitted."""
  613. timestamp = _now(now)
  614. expiry = float(expires_at)
  615. if expiry <= timestamp:
  616. raise HostedRoomError("peer room reservation must expire in the future")
  617. values = _reservation_claims(claims)
  618. room_id, _, target_profile, gateway_id, epoch = values
  619. with _transaction(db_path, immediate=True) as conn:
  620. conn.execute("DELETE FROM hosted_room_peer_reservations WHERE expires_at<=?", (timestamp,))
  621. authority_rows = conn.execute(
  622. f"""SELECT authority_gateway_id, authority_epoch
  623. FROM hosted_room_peer_reservations {_LIVE_RESERVATION_WHERE}""", (room_id, target_profile, timestamp)
  624. ).fetchall()
  625. if any(_reservation_superseded(row, gateway_id, epoch) for row in authority_rows):
  626. raise AuthorityConflictError("peer room reservation authority changed")
  627. conn.execute("""UPDATE hosted_room_peer_reservations SET revoked_at=?, updated_at=? WHERE room_id=?
  628. AND target_profile=? AND authority_epoch<? AND revoked_at IS NULL""",
  629. (timestamp, timestamp, room_id, target_profile, epoch))
  630. existing = conn.execute("""SELECT authority_gateway_id, authority_epoch FROM hosted_room_peer_reservations
  631. WHERE room_id=? AND member_id=? AND target_profile=?""", values[:3]).fetchone()
  632. if existing is not None and _reservation_superseded(existing, gateway_id, epoch):
  633. raise AuthorityConflictError("peer room reservation authority changed")
  634. conn.execute("""INSERT INTO hosted_room_peer_reservations(
  635. room_id, member_id, target_profile, authority_gateway_id,
  636. authority_epoch, expires_at, revoked_at, created_at, updated_at
  637. ) VALUES (?, ?, ?, ?, ?, ?, NULL, ?, ?)
  638. ON CONFLICT(room_id, member_id, target_profile) DO UPDATE SET
  639. authority_gateway_id=excluded.authority_gateway_id,
  640. authority_epoch=excluded.authority_epoch,
  641. expires_at=MAX(hosted_room_peer_reservations.expires_at,
  642. excluded.expires_at),
  643. revoked_at=NULL,
  644. updated_at=excluded.updated_at""", (*values, expiry, timestamp, timestamp))
  645. def _read_one(db_path: DbPath, sql: str, params: tuple[Any, ...]) -> sqlite3.Row | None:
  646. with _transaction(db_path) as conn:
  647. return conn.execute(sql, params).fetchone()
  648. def peer_room_is_reserved(db_path: DbPath, *, room_id: str, target_profile: str, now: float | None = None) -> bool:
  649. """Return whether a live target-side RoomLink reservation fences Desktop."""
  650. params = (_room_id(room_id), _actor_id(target_profile, "target_profile"), _now(now))
  651. return _read_one(db_path, _SELECT_LIVE_RESERVATION, params) is not None
  652. def peer_room_grant_is_current(db_path: DbPath, *, claims: Mapping[str, Any], now: float | None = None) -> bool:
  653. """Require a grant to match the target's current live reservation."""
  654. timestamp = _now(now)
  655. return _read_one(
  656. db_path, """SELECT 1 FROM hosted_room_peer_reservations WHERE room_id=? AND member_id=?
  657. AND target_profile=? AND authority_gateway_id=? AND authority_epoch=?
  658. AND expires_at>? AND revoked_at IS NULL LIMIT 1""", (*_reservation_claims(claims), timestamp)) is not None
  659. def room_grant_is_revoked(db_path: DbPath, *, claims: Mapping[str, Any], now: float | None = None) -> bool:
  660. """Return whether a grant predates its exact scope's revocation fence."""
  661. timestamp = _now(now)
  662. scope_key = _room_grant_scope_key(claims)
  663. issued_at = float(claims.get("issued_at") or 0)
  664. row = _read_one(
  665. db_path, """SELECT revoked_before FROM hosted_room_revoked_grants
  666. WHERE scope_key=? AND expires_at>?""", (scope_key, timestamp))
  667. return row is not None and issued_at <= float(row["revoked_before"])
  668. def _remote_run_identity(record: Mapping[str, Any]) -> tuple[Any, ...]:
  669. return tuple(record[column] for column in _REMOTE_RUN_IDENTITY_COLUMNS)
  670. def upsert_remote_run_receipt(db_path: DbPath, *, record: Mapping[str, Any], now: float | None = None) -> None:
  671. """Durably bind one logical peer task attempt to its remote run handle."""
  672. timestamp = _now(now)
  673. identity = _remote_run_identity(record)
  674. immutable = (*identity, record["run_id"], record["session_id"])
  675. with _transaction(db_path, immediate=True) as conn:
  676. existing = conn.execute(_SELECT_REMOTE_RUN, identity).fetchone()
  677. if existing is not None:
  678. if (*_remote_run_identity(existing), existing["run_id"], existing["session_id"]) != immutable:
  679. raise HostedRoomError("remote run receipt conflicts with its logical task")
  680. conn.execute(
  681. f"UPDATE hosted_room_remote_runs SET updated_at=? WHERE {_REMOTE_RUN_WHERE}", (timestamp, *identity))
  682. return
  683. conn.execute("""INSERT INTO hosted_room_remote_runs(
  684. room_id, home_install_id, authority_gateway_id,
  685. authority_epoch, member_id, target_install_id,
  686. target_profile, task_id, execution_generation, run_id,
  687. session_id, created_at, updated_at
  688. ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""", (*immutable, timestamp, timestamp))
  689. from gateway.hosted_room_work_records import capture_transition_locked
  690. capture_transition_locked(conn, record["room_id"])
  691. def list_remote_run_receipts(
  692. db_path: DbPath, *, room_id: str | None = None, target_profile: str | None = None, session_id: str | None = None
  693. ) -> list[dict[str, Any]]:
  694. """Return remote run handles in durable task order."""
  695. candidates = (("room_id", room_id), ("target_profile", target_profile), ("session_id", session_id))
  696. filters = [(column, value) for column, value in candidates if value is not None]
  697. where = f" WHERE {' AND '.join(f'{column}=?' for column, _ in filters)}" if filters else ""
  698. with _transaction(db_path) as conn:
  699. rows = conn.execute(
  700. "SELECT * FROM hosted_room_remote_runs" + where
  701. + " ORDER BY created_at, task_id, execution_generation", [value for _, value in filters]).fetchall()
  702. return [dict(row) for row in rows]
  703. def remote_run_receipt(db_path: DbPath, *, record: Mapping[str, Any]) -> dict[str, Any] | None:
  704. """Return the exact durable remote run handle for one task attempt."""
  705. row = _read_one(db_path, _SELECT_REMOTE_RUN, _remote_run_identity(record))
  706. return dict(row) if row is not None else None
  707. # --- rooms and events -------------------------------------------------------------
  708. def _adopt_legacy_room(
  709. conn: sqlite3.Connection, existing: sqlite3.Row, *, room_id: str, members_json: str, authority_gateway_id: str,
  710. now: float) -> dict[str, Any]:
  711. """Claim a 'legacy'-authority room for a real gateway with a fenced claim event."""
  712. target_epoch = int(existing["authority_epoch"]) + 1
  713. seq = int(existing["next_seq"])
  714. claim_bytes = _insert_event(
  715. conn, existing, room_id, seq, "system:authority-adopted", "authority.claimed",
  716. _system_actor_json("authority-control"), target_epoch,
  717. _claim_payload_json("legacy", authority_gateway_id, target_epoch), now, allow_control=True)
  718. _fenced_update(conn, """UPDATE hosted_rooms
  719. SET members_json=?, authority_gateway_id=?, authority_epoch=?,
  720. next_seq=next_seq+1, revision=revision+1, event_bytes=event_bytes+?, updated_at=?
  721. WHERE room_id=? AND authority_gateway_id='legacy' AND authority_epoch=? AND next_seq=?
  722. AND disbanded_at IS NULL""",
  723. (
  724. members_json, authority_gateway_id, target_epoch, claim_bytes, now, room_id,
  725. int(existing["authority_epoch"]), seq), AuthorityConflictError("legacy room adoption lost its fence"))
  726. existing = _reload(conn, _SELECT_ROOM, (room_id,), "adopted room could not be reloaded")
  727. claim_event = _reload(
  728. conn, _SELECT_EVENT, (room_id, "system:authority-adopted"), "legacy adoption event could not be reloaded")
  729. return {**_room_from_row(existing, idempotent=True), "adopted": True, "claim_event": _event_from_row(claim_event)}
  730. def create_room(
  731. db_path: DbPath, *, room_id: Any, name: Any, members: Any, authority_gateway_id: Any, now: float | None = None,
  732. admit: Callable[[sqlite3.Connection], Any] | None = None,
  733. ) -> dict[str, Any]:
  734. """Create a room, or return the identical existing room idempotently.
  735. ``admit(conn)`` runs first inside the write transaction (after payload validation), so a
  736. caller's side effect such as an owner claim commits only together with this create."""
  737. room_id = _room_id(room_id)
  738. name = _validate_room_name(name)
  739. normalized_members, members_json = _validate_members(members)
  740. authority_gateway_id = _actor_id(authority_gateway_id, "authority_gateway_id")
  741. now = _now(now)
  742. with _transaction(db_path, immediate=True) as conn:
  743. if admit is not None:
  744. admit(conn)
  745. if _is_retired(conn, room_id):
  746. raise RoomConflictError("room_id belongs to a disbanded room")
  747. existing = conn.execute(_SELECT_ROOM_WITH_BYTES, (room_id,)).fetchone()
  748. if existing is not None:
  749. if existing["disbanded_at"] is not None:
  750. raise RoomConflictError("room_id belongs to a disbanded room")
  751. legacy_adoption = (existing["authority_gateway_id"] == "legacy" and authority_gateway_id != "legacy")
  752. members_match = existing["members_json"] == members_json or (
  753. legacy_adoption and _legacy_members_match(existing["members_json"], normalized_members))
  754. if existing["name"] != name or not members_match:
  755. raise RoomConflictError("room_id already exists with different state")
  756. if legacy_adoption:
  757. return _adopt_legacy_room(
  758. conn, existing, room_id=room_id, members_json=members_json,
  759. authority_gateway_id=authority_gateway_id, now=now)
  760. if existing["authority_gateway_id"] != authority_gateway_id:
  761. raise RoomConflictError("room_id already belongs to a different authority")
  762. return _room_from_row(existing, idempotent=True)
  763. active = conn.execute("SELECT COUNT(*) FROM hosted_rooms WHERE disbanded_at IS NULL").fetchone()[0]
  764. if int(active) >= MAX_ACTIVE_ROOMS:
  765. raise HostedRoomError("This host has too many active Group Chats. Delete one and try again.")
  766. conn.execute(
  767. f"""INSERT INTO hosted_rooms ({_ROOM_COLUMNS_WITH_BYTES})
  768. VALUES (?, ?, ?, ?, 1, 1, 0, 1, ?, ?, NULL)""",
  769. (room_id, name, members_json, authority_gateway_id, now, now))
  770. row = _reload(
  771. conn, """SELECT room_id, name, members_json, authority_gateway_id, authority_epoch, revision,
  772. created_at, updated_at FROM hosted_rooms WHERE room_id=?""", (room_id,),
  773. "created room could not be reloaded")
  774. return {**_room_from_row(row), "members": normalized_members}
  775. def list_rooms(
  776. db_path: DbPath, *, include_disbanded: bool = False, limit: int = MAX_ROOM_LIST_LIMIT, offset: int = 0
  777. ) -> list[dict[str, Any]]:
  778. """Return one bounded read-only page ordered by most recent change."""
  779. limit = _bounded_limit(limit, MAX_ROOM_LIST_LIMIT)
  780. offset = _non_negative(offset, "offset")
  781. with closing(_read_connection(db_path)) as conn:
  782. rows = conn.execute(
  783. f"""SELECT {_ROOM_COLUMNS} FROM hosted_rooms WHERE disbanded_at IS NULL OR ?
  784. ORDER BY updated_at DESC, room_id ASC LIMIT ? OFFSET ?""", (int(include_disbanded), limit, offset)
  785. ).fetchall()
  786. return [_room_from_row(row) for row in rows]
  787. def rename_room(db_path: DbPath, *, room_id: Any, event_id: Any, name: Any, now: float | None = None) -> dict[str, Any]:
  788. """Rename a live room and append its replay event atomically."""
  789. room_id = _room_id(room_id)
  790. event_id = _event_id(event_id)
  791. name = _validate_room_name(name)
  792. now = _now(now)
  793. actor_json = _system_actor_json("room-control")
  794. payload_json = _payload_json({"name": name})
  795. with _transaction(db_path, immediate=True) as conn:
  796. room = _room_row(conn, _SELECT_ROOM_WITH_BYTES, (room_id,), room_id)
  797. if room["disbanded_at"] is not None:
  798. raise RoomNotFoundError("hosted room not found")
  799. existing = _load_event(conn, room_id, event_id)
  800. if existing is not None:
  801. if existing["kind"] != "room.renamed" or existing["payload_json"] != payload_json:
  802. raise EventConflictError("event_id already exists with different immutable content")
  803. return {**_room_from_row(room, idempotent=True), "event": _event_from_row(existing, idempotent=True)}
  804. seq = int(room["next_seq"])
  805. event_bytes = _prepare_event(conn, room, event_id, "room.renamed", actor_json, payload_json)
  806. # Rename updates the room row before inserting its event (order is load-bearing).
  807. conn.execute("""UPDATE hosted_rooms
  808. SET name=?, next_seq=?, event_bytes=event_bytes+?, revision=revision+1, updated_at=?
  809. WHERE room_id=?""", (name, seq + 1, event_bytes, now, room_id))
  810. conn.execute(_INSERT_EVENT, (
  811. room_id, seq, event_id, "room.renamed", actor_json, int(room["authority_epoch"]), payload_json, now))
  812. updated = conn.execute(_SELECT_ROOM, (room_id,)).fetchone()
  813. return {**_room_from_row(updated), "event": _event_from_row(_load_event(conn, room_id, event_id))}
  814. def append_event(
  815. db_path: DbPath, *, room_id: Any, event_id: Any, kind: Any, actor: Any, payload: Any,
  816. authority_gateway_id: Any = None, authority_epoch: Any = None, now: float | None = None,
  817. expected_latest_seq: int | None = None, control_reserve: bool = False) -> dict[str, Any]:
  818. """Append one immutable event and allocate its per-room sequence atomically; repeating an ``event_id``
  819. with identical content returns the original, different content fails closed. ``control_reserve`` lets a
  820. bounded gateway notice use the control headroom, so a room whose log is full can still say why.
  821. ``payload`` may be a function of the write-locked connection returning the payload, for one derived
  822. from current room state: no concurrent append can land between that read and this write."""
  823. room_id = _room_id(room_id)
  824. event_id = _event_id(event_id)
  825. if expected_latest_seq is not None:
  826. _bounded_int(expected_latest_seq, message="expected_latest_seq must be a nonnegative integer")
  827. kind = _validate_event_kind(kind)
  828. normalized_actor, actor_json = _validate_actor(actor, kind=kind)
  829. # Every admitted actor kind is room-scoped, so authority fields are always required.
  830. authority_gateway_id = _actor_id(authority_gateway_id, "authority_gateway_id")
  831. if normalized_actor["kind"] == "gateway" and normalized_actor["id"] != authority_gateway_id:
  832. raise HostedRoomError("gateway actor.id must match authority_gateway_id")
  833. authority_epoch = _require_positive_int(authority_epoch, "authority_epoch")
  834. resolve = payload if callable(payload) else lambda _conn: payload
  835. now = _now(now)
  836. with _transaction(db_path, immediate=True) as conn:
  837. if not isinstance(resolved := resolve(conn), dict):
  838. raise HostedRoomError("payload must be an object")
  839. payload_json = _payload_json(resolved)
  840. existing = _load_event(conn, room_id, event_id)
  841. if existing is not None:
  842. if _event_content(existing) != (kind, actor_json, authority_epoch, payload_json):
  843. raise EventConflictError("event_id already exists with different content")
  844. return _event_from_row(existing, idempotent=True)
  845. room = _room_row(
  846. conn, """SELECT next_seq, event_bytes, authority_gateway_id, authority_epoch
  847. FROM hosted_rooms WHERE room_id=? AND disbanded_at IS NULL""", (room_id,), room_id)
  848. _require_authority(room, authority_gateway_id, authority_epoch, "stale hosted room authority")
  849. seq = int(room["next_seq"])
  850. if expected_latest_seq is not None and seq - 1 != expected_latest_seq:
  851. raise EventCursorConflictError("room changed before event publication")
  852. if kind in {"message.user", "message.member"}:
  853. from gateway.hosted_room_attachments import retain_message_attachments
  854. retain_message_attachments(conn, room_id=room_id, event_id=event_id,
  855. manifest=json.loads(payload_json).get("attachments", []), now=now)
  856. event_bytes = _insert_event(
  857. conn, room, room_id, seq, event_id, kind, actor_json, authority_epoch, payload_json, now,
  858. allow_control=kind in _CONTROL_EVENT_KINDS or (control_reserve and normalized_actor["kind"] == "gateway"))
  859. _fenced_update(conn, """UPDATE hosted_rooms SET next_seq=?, event_bytes=event_bytes+?, updated_at=?
  860. WHERE room_id=? AND next_seq=?""", (seq + 1, event_bytes, now, room_id, seq),
  861. RuntimeError("hosted room sequence advance lost its write fence"))
  862. row = _reload(
  863. conn, f"SELECT {_EVENT_COLUMNS} FROM hosted_room_events WHERE room_id=? AND seq=?", (room_id, seq),
  864. "appended event could not be reloaded")
  865. return {**_event_from_row(row), "actor": normalized_actor}
  866. def _probe(path: Path, table: str, query: str, params: tuple[Any, ...], unavailable: str) -> bool:
  867. """Non-blocking existence probe: short timeout, no schema creation or migration."""
  868. if not path.is_file():
  869. return False
  870. try:
  871. with closing(sqlite3.connect(path, timeout=0.05)) as conn:
  872. table_row = conn.execute(
  873. f"SELECT 1 FROM sqlite_master WHERE type='table' AND name='{table}' LIMIT 1").fetchone()
  874. return table_row is not None and conn.execute(query, params).fetchone() is not None
  875. except sqlite3.Error as exc:
  876. raise RoomProbeUnavailableError(unavailable) from exc
  877. def probe_hosted_room(db_path: DbPath, *, room_id: Any) -> bool:
  878. """Check room ownership without creating or migrating the shared store; runs on the synchronous
  879. prompt-admission path for older Desktop clients, so it fails fast under contention instead of blocking
  880. the WebSocket reader for SQLite's ten-second timeout."""
  881. return _probe(
  882. Path(db_path), "hosted_rooms", "SELECT 1 FROM hosted_rooms WHERE room_id=? AND disbanded_at IS NULL LIMIT 1",
  883. (_room_id(room_id),), "hosted room ownership is temporarily unavailable")
  884. def probe_peer_room_reservation(
  885. db_path: DbPath, *, room_id: Any, target_profile: Any, now: float | None = None) -> bool:
  886. """Check a peer reservation without creating or migrating shared state."""
  887. params = (_room_id(room_id), _actor_id(target_profile, "target_profile"), _now(now))
  888. return _probe(
  889. Path(db_path), "hosted_room_peer_reservations", _SELECT_LIVE_RESERVATION, params,
  890. "peer room ownership is temporarily unavailable")
  891. def room_state(db_path: DbPath, *, room_id: Any, include_disbanded: bool = False) -> dict[str, Any]:
  892. """Return durable replay and authority state for one room."""
  893. room_id = _room_id(room_id)
  894. with _transaction(db_path) as conn:
  895. row = _room_row(
  896. conn,
  897. f"""SELECT {_ROOM_COLUMNS} FROM hosted_rooms WHERE room_id=? AND (disbanded_at IS NULL
  898. OR ?)""", (room_id, int(include_disbanded)), room_id)
  899. claim_row = conn.execute(
  900. f"""SELECT {_EVENT_COLUMNS} FROM hosted_room_events WHERE room_id=?
  901. AND kind='authority.claimed' AND authority_epoch=? ORDER BY seq DESC LIMIT 1""",
  902. (room_id, int(row["authority_epoch"]))).fetchone()
  903. return {**_room_from_row(row), **({"authority_claim": _event_from_row(claim_row)} if claim_row is not None else {})}
  904. def request_room_stop(
  905. db_path: DbPath, *, room_id: Any, cancel_id: Any, expected_gateway_id: Any, expected_epoch: Any) -> dict[str, Any]:
  906. """Append an idempotent fence that supersedes earlier user turns."""
  907. cancel_id = _validate_identifier(cancel_id, label="cancel_id", max_chars=MAX_EVENT_ID_CHARS)
  908. return append_event(
  909. db_path, room_id=room_id, event_id=f"room-stop:{hashlib.sha256(cancel_id.encode()).hexdigest()[:32]}",
  910. kind="room.stop_requested", actor={"kind": "gateway", "id": expected_gateway_id},
  911. payload={"cancel_id": cancel_id}, authority_gateway_id=expected_gateway_id, authority_epoch=expected_epoch)
  912. def claim_authority(
  913. db_path: DbPath, *, room_id: Any, expected_gateway_id: Any, expected_epoch: Any, new_gateway_id: Any, event_id: Any,
  914. now: float | None = None) -> dict[str, Any]:
  915. """Fence a verified authority transfer with a compare-and-swap epoch; does not decide *when* takeover is
  916. safe (a replicated driver calls it only after its lease/quorum policy established that the previous
  917. owner can no longer commit)."""
  918. room_id = _room_id(room_id)
  919. expected_gateway_id = _actor_id(expected_gateway_id, "expected_gateway_id")
  920. new_gateway_id = _actor_id(new_gateway_id, "new_gateway_id")
  921. event_id = _event_id(event_id)
  922. _require_positive_int(expected_epoch, "expected_epoch")
  923. now = _now(now)
  924. target_epoch = expected_epoch + 1
  925. claim_actor_json = _system_actor_json("authority-control")
  926. claim_payload_json = _claim_payload_json(expected_gateway_id, new_gateway_id, target_epoch)
  927. with _transaction(db_path, immediate=True) as conn:
  928. row = _room_row(
  929. conn, """SELECT authority_gateway_id, authority_epoch, next_seq, event_bytes
  930. FROM hosted_rooms WHERE room_id=? AND disbanded_at IS NULL""", (room_id,), room_id)
  931. existing_event = _load_event(conn, room_id, event_id)
  932. idempotent = existing_event is not None
  933. if idempotent:
  934. if _event_content(existing_event) != (
  935. "authority.claimed", claim_actor_json, target_epoch, claim_payload_json):
  936. raise EventConflictError("event_id already exists with different content")
  937. if str(row["authority_gateway_id"]) != new_gateway_id or int(row["authority_epoch"]) != target_epoch:
  938. raise AuthoritySupersededError("authority claim succeeded but was later superseded")
  939. else:
  940. _require_authority(row, expected_gateway_id, expected_epoch, "hosted room authority changed")
  941. # Insert the claim event, then CAS the room's authority behind the epoch fence.
  942. claim_bytes = _insert_event(
  943. conn, row, room_id, int(row["next_seq"]), event_id, "authority.claimed", claim_actor_json, target_epoch,
  944. claim_payload_json, now, allow_control=True)
  945. _fenced_update(conn, """UPDATE hosted_rooms SET authority_gateway_id=?,
  946. authority_epoch=authority_epoch+1, next_seq=next_seq+1,
  947. event_bytes=event_bytes+?, revision=revision+1, updated_at=? WHERE room_id=?
  948. AND disbanded_at IS NULL AND authority_gateway_id=? AND authority_epoch=?""",
  949. (new_gateway_id, claim_bytes, now, room_id, expected_gateway_id, expected_epoch),
  950. AuthorityConflictError("hosted room authority changed"))
  951. existing_event = _load_event(conn, room_id, event_id)
  952. state_row = _reload(
  953. conn, """SELECT room_id, name, members_json, authority_gateway_id, authority_epoch, next_seq,
  954. revision, created_at, updated_at FROM hosted_rooms WHERE room_id=?""", (room_id,),
  955. "claimed room could not be reloaded")
  956. if existing_event is None: # pragma: no cover - both claim paths set it
  957. raise RuntimeError("authority claim event could not be reloaded")
  958. return {
  959. **_room_from_row(state_row, idempotent=idempotent),
  960. "claim_event": _event_from_row(existing_event, idempotent=idempotent)}
  961. def _disband_replay(conn: sqlite3.Connection, room_id: str, room: sqlite3.Row | None) -> dict[str, Any] | None:
  962. """Idempotent replay for a retired or already-disbanded room; None when the room is live."""
  963. if room is None:
  964. retired = conn.execute("SELECT retired_at FROM hosted_room_retired_ids WHERE room_id=?", (room_id,)).fetchone()
  965. if retired is None:
  966. raise RoomNotFoundError("hosted room not found")
  967. return {
  968. "room_id": room_id, "disbanded_at": float(retired["retired_at"]), "idempotent": True,
  969. "history_expired": True}
  970. if room["disbanded_at"] is None:
  971. return None
  972. conn.execute(_INSERT_RETIRED, (room_id, float(room["disbanded_at"])))
  973. event = _load_event(conn, room_id, "system:room-disbanded")
  974. return {
  975. "room_id": room_id, "disbanded_at": float(room["disbanded_at"]), "idempotent": True,
  976. **({"event": _event_from_row(event, idempotent=True)} if event is not None else {})}
  977. def disband_room(
  978. db_path: DbPath, *, room_id: Any, expected_gateway_id: Any, expected_epoch: Any, now: float | None = None
  979. ) -> dict[str, Any]:
  980. """Tombstone a room id permanently and idempotently."""
  981. room_id = _room_id(room_id)
  982. expected_gateway_id = _actor_id(expected_gateway_id, "expected_gateway_id")
  983. _require_positive_int(expected_epoch, "expected_epoch")
  984. now = _now(now)
  985. with _transaction(db_path, immediate=True) as conn:
  986. room = conn.execute("""SELECT authority_gateway_id, authority_epoch, next_seq, event_bytes, disbanded_at
  987. FROM hosted_rooms WHERE room_id=?""", (room_id,)).fetchone()
  988. if (replay := _disband_replay(conn, room_id, room)) is not None:
  989. return replay
  990. _require_authority(room, expected_gateway_id, expected_epoch, "stale hosted room authority")
  991. disband_bytes = _insert_event(
  992. conn, room, room_id, int(room["next_seq"]), "system:room-disbanded", "room.disbanded",
  993. _system_actor_json("room-control"), int(room["authority_epoch"]), _payload_json({"room_id": room_id}), now,
  994. allow_control=True)
  995. _fenced_update(conn, """UPDATE hosted_rooms
  996. SET disbanded_at=?, updated_at=?, revision=revision+1,
  997. next_seq=next_seq+1, event_bytes=event_bytes+?
  998. WHERE room_id=? AND disbanded_at IS NULL AND authority_gateway_id=?
  999. AND authority_epoch=?""",
  1000. (now, now, disband_bytes, room_id, expected_gateway_id, expected_epoch),
  1001. RoomConflictError("hosted room disband lost its fence"))
  1002. conn.execute(_INSERT_RETIRED, (room_id, now))
  1003. event = _reload(
  1004. conn, _SELECT_EVENT, (room_id, "system:room-disbanded"), "room disband event could not be reloaded")
  1005. _prune_disbanded_rooms_locked(conn, now=now, max_gateway_event_bytes=MAX_GATEWAY_EVENT_BYTES)
  1006. return {"room_id": room_id, "disbanded_at": now, "idempotent": False, "event": _event_from_row(event)}
  1007. def read_events(
  1008. db_path: DbPath, *, room_id: Any, since_seq: Any = 0, limit: Any = 100, include_disbanded: bool = False
  1009. ) -> dict[str, Any]:
  1010. """Read a monotonic room-log delta after ``since_seq``."""
  1011. room_id = _room_id(room_id)
  1012. since_seq = _non_negative(since_seq, "since_seq")
  1013. limit = _bounded_limit(limit, MAX_LOG_LIMIT)
  1014. with _transaction(db_path) as conn:
  1015. room = _room_row(
  1016. conn, """SELECT next_seq, authority_gateway_id, authority_epoch FROM hosted_rooms
  1017. WHERE room_id=? AND (disbanded_at IS NULL OR ?)""", (room_id, int(include_disbanded)), room_id)
  1018. latest_seq = int(room["next_seq"]) - 1
  1019. authority = {"gateway_id": str(room["authority_gateway_id"]), "epoch": int(room["authority_epoch"])}
  1020. if since_seq > latest_seq:
  1021. raise HostedRoomError("since_seq is ahead of the hosted room log")
  1022. rows = conn.execute(
  1023. f"""WITH candidates AS (
  1024. SELECT {_EVENT_COLUMNS},
  1025. SUM(
  1026. LENGTH(CAST(event_id AS BLOB)) +
  1027. LENGTH(CAST(kind AS BLOB)) +
  1028. LENGTH(CAST(actor_json AS BLOB)) +
  1029. LENGTH(CAST(payload_json AS BLOB))
  1030. ) OVER (ORDER BY seq ASC) AS cumulative_bytes
  1031. FROM hosted_room_events
  1032. WHERE room_id=? AND seq>?
  1033. ORDER BY seq ASC LIMIT ?
  1034. )
  1035. SELECT {_EVENT_COLUMNS}
  1036. FROM candidates
  1037. WHERE cumulative_bytes<=?
  1038. ORDER BY seq ASC""", (room_id, since_seq, limit, MAX_LOG_PAGE_BYTES)).fetchall()
  1039. events = [_event_from_row(row) for row in rows]
  1040. def build_page(page_events: list[dict[str, Any]]) -> dict[str, Any]:
  1041. cursor = page_events[-1]["seq"] if page_events else since_seq
  1042. return {"events": page_events, "cursor": cursor, "latest_seq": latest_seq, "has_more": cursor < latest_seq,
  1043. "authority": authority}
  1044. def fits(page_events: list[dict[str, Any]]) -> bool:
  1045. page_json = json.dumps(build_page(page_events), ensure_ascii=False, separators=(",", ":"))
  1046. return utf8_len(page_json) <= MAX_LOG_PAGE_BYTES
  1047. if events and not fits(events):
  1048. # Binary-search the largest prefix whose serialized page fits the budget.
  1049. low, high = 1, len(events)
  1050. while low < high:
  1051. middle = (low + high + 1) // 2
  1052. low, high = (middle, high) if fits(events[:middle]) else (low, middle - 1)
  1053. events = events[:low]
  1054. if not fits(events):
  1055. raise HostedRoomError("hosted room event exceeds replay page limit")
  1056. return build_page(events)