hosted_rooms_common.py 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151
  1. """Shared leaf helpers for the gateway hosted-room modules.
  2. Each hosted-room module validates identifiers, bounded integers, exact field sets and
  3. canonical JSON with its own error class and pinned error strings; these helpers take the
  4. error class and message templates as parameters so failures stay byte-identical while the
  5. logic lives once. Must stay a leaf: never import a hosted_room* module (import cycle).
  6. """
  7. from __future__ import annotations
  8. import json
  9. import re
  10. import sqlite3
  11. import time
  12. from pathlib import Path
  13. from typing import Any, Callable, Iterator, Mapping
  14. IDENTIFIER_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]*$")
  15. DbPath = Path | str
  16. def identifier(
  17. value: Any, *, label: str, error: type[Exception], max_chars: int = 128,
  18. pattern: re.Pattern[str] | None = IDENTIFIER_RE, invalid: str | None = None) -> str:
  19. """Strip and validate a bounded string; ``pattern=None`` skips the shape check."""
  20. if not isinstance(value, str):
  21. raise error(f"{label} must be a string")
  22. value = value.strip()
  23. if not value or len(value) > max_chars or (pattern is not None and not pattern.fullmatch(value)):
  24. raise error(invalid or f"invalid {label}")
  25. return value
  26. def bounded_int(value: Any, *, error: type[Exception], message: str, low: int = 0, high: int | None = None) -> int:
  27. """Reject bools, non-ints and values outside ``[low, high]`` (``message`` is the exact text)."""
  28. if isinstance(value, bool) or not isinstance(value, int) or value < low or (high is not None and value > high):
  29. raise error(message)
  30. return value
  31. def exact_fields(
  32. value: Any, *, label: str, required: frozenset[str] | set[str], optional: frozenset[str] | set[str] = frozenset(),
  33. error: type[Exception], not_object: str | None = None, missing_fmt: str = "{label} is missing fields: {fields}",
  34. unknown_fmt: str = "{label} has unknown fields: {fields}") -> Mapping[str, Any]:
  35. """Require exactly ``required`` (+ any ``optional``) keys; formats name the offenders sorted."""
  36. if not isinstance(value, Mapping):
  37. raise error(not_object or f"{label} must be an object")
  38. keys = frozenset(value)
  39. missing = required - keys
  40. unknown = keys - required - optional
  41. if missing:
  42. raise error(missing_fmt.format(label=label, fields=", ".join(sorted(missing))))
  43. if unknown:
  44. raise error(unknown_fmt.format(label=label, fields=", ".join(sorted(unknown))))
  45. return value
  46. def text(value: Any, *, error: type[Exception], label: str, max_bytes: int, strip: bool = True) -> str:
  47. """Non-blank string bounded by ``max_bytes`` of UTF-8; ``strip=False`` keeps and measures the raw text."""
  48. if not isinstance(value, str):
  49. raise error(f"{label} must be a string")
  50. if not value.strip():
  51. raise error(f"{label} must not be empty")
  52. if strip:
  53. value = value.strip()
  54. if len(value.encode("utf-8")) > max_bytes:
  55. raise error(f"{label} is too large")
  56. return value
  57. def compact_json(value: Any, *, ensure_ascii: bool = True) -> str:
  58. """Sorted-key, separator-free JSON (the digest/storage canonical form)."""
  59. return json.dumps(value, ensure_ascii=ensure_ascii, sort_keys=True, separators=(",", ":"))
  60. def canonical_json(value: Any, *, error: type[Exception], label: str, max_bytes: int, ensure_ascii: bool) -> str:
  61. """``compact_json`` bounded by ``max_bytes`` of UTF-8; unserializable input raises ``error``."""
  62. try:
  63. encoded = compact_json(value, ensure_ascii=ensure_ascii)
  64. except (TypeError, ValueError, RecursionError) as exc:
  65. raise error(f"{label} must be JSON-serializable") from exc
  66. if len(encoded.encode("utf-8")) > max_bytes:
  67. raise error(f"{label} is too large")
  68. return encoded
  69. def utf8_len(*parts: str) -> int:
  70. return len("".join(parts).encode("utf-8"))
  71. def clock(now: float | None) -> float:
  72. """``now`` as a float, or the current wall clock when ``None``."""
  73. return time.time() if now is None else float(now)
  74. def open_sqlite(path: DbPath, *, timeout: float = 10) -> sqlite3.Connection:
  75. """Row-factory connection with foreign keys on; no journal or schema work (steady-state readers)."""
  76. from hermes_cli.sqlite_util import open_db
  77. return open_db(path, db_label="shared-state.db", busy_timeout_ms=int(timeout * 1000), wal=False,
  78. foreign_keys=True)
  79. def connect(
  80. db_path: DbPath, *, db_label: str, ready: Callable[[sqlite3.Connection], bool],
  81. initialize: Callable[[sqlite3.Connection], None], lock_retries: int = 1) -> sqlite3.Connection:
  82. """Open the shared root store: WAL, foreign keys, then ``initialize`` in one IMMEDIATE txn if not ``ready``.
  83. Multiple profile gateways share this database, so every draft-schema transition
  84. is serialized in SQLite itself: a crash rolls back the whole DDL/data migration and
  85. another process can safely retry it.
  86. """
  87. def _initialize(conn: sqlite3.Connection) -> None:
  88. if not ready(conn):
  89. try:
  90. conn.execute("BEGIN IMMEDIATE")
  91. initialize(conn)
  92. conn.commit()
  93. except Exception:
  94. conn.rollback()
  95. raise
  96. # Late import: a gateway that outlives an on-disk upgrade has the OLD sqlite_util cached.
  97. from hermes_cli.sqlite_util import open_db
  98. return open_db(db_path, db_label=db_label, busy_timeout_ms=10_000, foreign_keys=True,
  99. wal_lock_retries=lock_retries, initialize=_initialize)
  100. def fenced_update(conn: sqlite3.Connection, sql: str, params: tuple, error: Exception) -> None:
  101. """Run a compare-and-swap UPDATE; anything but exactly one row means the fence was lost."""
  102. if conn.execute(sql, params).rowcount != 1:
  103. raise error
  104. def table_exists(conn: sqlite3.Connection, table: str) -> bool:
  105. row = conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name=?", (table,)).fetchone()
  106. return row is not None
  107. def table_columns(conn: sqlite3.Connection, table: str) -> frozenset[str]:
  108. return frozenset(row[1] for row in conn.execute(f"PRAGMA table_info({table})"))
  109. def transaction(
  110. connect: Callable[[DbPath], sqlite3.Connection], db_path: DbPath, *, immediate: bool
  111. ) -> Iterator[sqlite3.Connection]:
  112. """Open via ``connect``, optionally ``BEGIN IMMEDIATE``, commit on success, always close."""
  113. from hermes_cli.sqlite_util import transaction as _transaction
  114. return _transaction(connect(db_path), immediate=immediate)