| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209 |
- """The session owner's server→client requests to a local viewer, and who may settle them.
- The owner sends a request frame (``tui_gateway/contracts/server_requests.py``: ``sudo``, ``secret``,
- ``clarify``, the Desktop UI requests) to the viewers attached to a session's event stream and blocks the
- agent thread until one answers, the turn is interrupted, or it times out: the canonical side of main's
- sidecar ``tui_gateway/server_requests.py``. A viewer answers with a JSON-RPC response frame
- (:func:`resolve`) or, for a batch clarify, per question with ``clarify.lock`` (:func:`lock_answer`); both go
- through :func:`may_settle`, and a batch's terminal result comes from ``tools.clarify_batch.settle_batch``,
- the rule the sidecar uses too. Values are never published, journaled or logged: they travel only in the
- viewer's response frame.
- """
- from __future__ import annotations
- import contextlib
- import threading
- import uuid
- from tools.clarify_batch import settle_batch
- REQUEST_TIMEOUT_S = 120 # main: ``_ask("sudo", ..., timeout=120)``
- _POLL_S = 0.25
- class _Pending:
- __slots__ = ("event", "events", "locked", "method", "params", "qids", "replay", "result", "session_id", "value")
- def __init__(self, session_id, qids=None, events=None, method=None, params=None, replay=True):
- self.event = threading.Event()
- self.session_id = session_id
- self.method = method
- # The frame's params as sent, so a viewer that reconnects gets the request again; ``replay`` False
- # for an automatic window request (a preview click), which a second delivery would run twice.
- self.params = params or {}
- self.replay = replay
- # The live session's own event stream the request went out on: one per authority (profile) and
- # session mount, so a viewer of another profile's same-named session can never settle it.
- self.events = events
- self.value = ""
- self.result = None
- # A batch clarify: its question ids and the answers ``clarify.lock`` has locked so far.
- self.qids = tuple(qids) if qids else None
- self.locked = {}
- _lock = threading.Lock()
- _open: dict[str, _Pending] = {}
- def owned_by(authority, session_id, events) -> bool:
- """True when *authority*'s live *session_id* is the very stream a request was sent on."""
- live = authority.sessions.get(session_id)
- return live is not None and events is not None and live.event_stream is events
- def may_settle(authority, actor, session_id, events) -> bool:
- """The one rule for who may settle an owner request (a response frame or ``clarify.lock``): the
- request went out on *authority*'s own live stream for that session (session ids repeat across
- profiles and ``_open`` is process-wide), *actor* holds ``session:respond`` there, and *actor* is
- attached to that session, the same set of connections the request frame was written to."""
- from gateway.session_contract import SessionRef
- from hermes_state_runtime import RuntimeStoreError
- if not owned_by(authority, session_id, events):
- return False
- try:
- authority.authorize(actor, SessionRef(authority.profile_id, session_id), "session:respond")
- except RuntimeStoreError:
- return False
- live = authority.sessions.get(session_id)
- return live is not None and actor in live.subscribers.values()
- def is_response_frame(frame) -> bool:
- """A viewer's answer to one of the owner's requests: a string ``srq-`` id, a result/error, no method."""
- return (isinstance(frame, dict) and "method" not in frame and isinstance(frame.get("id"), str)
- and frame["id"].startswith("srq-") and ("result" in frame or "error" in frame))
- def resolve(frame, *, session_ok=lambda session_id, events: True) -> bool:
- """Settle the open request *frame* answers; False when nothing (here) waits for that id.
- ``session_ok(session_id, events)`` lets the caller refuse an answer from a connection not entitled
- to that session: the caller's own authority must own ``events``, the stream the request was sent on
- (session ids are only unique per profile, and ``_open`` is process-wide)."""
- with _lock:
- pending = _open.get(frame["id"])
- if pending is None or not session_ok(pending.session_id, pending.events):
- return False
- _open.pop(frame["id"], None)
- locked = dict(pending.locked) if pending.qids is not None else None
- result = frame.get("result") if "error" not in frame else None
- if locked is not None:
- # One rule with main's sidecar registry: the frame's answers over the locks, or a cancel-all.
- result = settle_batch(locked, result)
- value = result.get("value") if isinstance(result, dict) else ""
- pending.value = value if isinstance(value, str) else ""
- pending.result = result if isinstance(result, dict) else None
- pending.event.set()
- return True
- def ask_viewer(events, session_id, method, params, *, cancelled=lambda: False, timeout=REQUEST_TIMEOUT_S,
- replay=True) -> str:
- """Send one one-string server→client request (``sudo``, ``secret``: ``ValueResult``) to the
- session's attached viewers and wait for its ``value``; "" on skip, interrupt, timeout or no viewer.
- ``replay=False``: a reconnecting viewer is not handed it again (``open_requests``)."""
- pending = _ask(events, session_id, method, params, cancelled=cancelled, timeout=timeout, replay=replay)
- return pending.value if pending is not None else ""
- def ask_viewer_result(events, session_id, method, params, *, cancelled=lambda: False, timeout=REQUEST_TIMEOUT_S,
- qids=None):
- """The same round trip for a structured answer (``clarify``: ``ClarifyResult``): the viewer's
- ``result`` dict, or None on interrupt, timeout, an error response or no attached viewer.
- ``qids`` makes it a batch, which always ends with ``{answers: <locked so far>, outcome}`` once
- asked: ``lock_answer`` (the ``clarify.lock`` verb) answers it per question."""
- pending = _ask(events, session_id, method, params, cancelled=cancelled, timeout=timeout, qids=qids)
- return pending.result if pending is not None else None
- def waiting(events, session_id, method) -> bool:
- """Whether a *method* request is open on this live session's stream (the card still waits)."""
- with _lock:
- return any(p.session_id == session_id and p.events is events and p.method == method for p in _open.values())
- def open_requests(events, session_id) -> list[dict]:
- """The requests still waiting on this live session's stream, oldest first, as their frames
- carried them (plus a batch's answers locked so far): what ``session.resume`` and
- ``session.events.since`` hand a reconnecting viewer to re-render (``OpenRequestEntry``)."""
- with _lock:
- waiting_now = [(rid, p) for rid, p in _open.items()
- if p.session_id == session_id and p.events is events and p.replay]
- return [{"id": rid, "method": p.method,
- "params": {**p.params, "answers": dict(p.locked)} if p.locked else dict(p.params)}
- for rid, p in waiting_now]
- def withdraw(events, session_id, method) -> int:
- """Settle every open *method* request on this live session's stream with no answer, the way a
- viewer that answered would: the asker reads None and every renderer gets ``request.cancel
- reason: resolved``."""
- with _lock:
- settled = [_open.pop(rid) for rid, p in list(_open.items())
- if p.session_id == session_id and p.events is events and p.method == method]
- for pending in settled:
- pending.event.set()
- return len(settled)
- def lock_answer(request_id, question_id, answer, *, session_ok=lambda session_id, events: False):
- """Lock one answer of an open batch request (``clarify.lock``; editable until the last lock;
- ``None`` = skipped). Returns the question ids still unanswered; the lock that empties it settles
- the request with ``{answers, outcome: submitted}``. ``None`` when no open batch has that id or the
- caller may not answer its session (expired, or another profile's / session's request: see
- :func:`resolve`); ``ValueError`` for an unknown question id."""
- with _lock:
- pending = _open.get(request_id)
- if pending is None or pending.qids is None or not session_ok(pending.session_id, pending.events):
- return None
- if question_id not in pending.qids:
- raise ValueError(question_id)
- pending.locked[question_id] = answer
- remaining = [qid for qid in pending.qids if qid not in pending.locked]
- if not remaining:
- _open.pop(request_id, None)
- pending.result = settle_batch(pending.locked, ended="submitted")
- if not remaining:
- pending.event.set()
- return remaining
- def _ask(events, session_id, method, params, *, cancelled, timeout, qids=None, replay=True):
- if not events.fanout.transports():
- return None
- request_id = f"srq-{uuid.uuid4().hex[:12]}"
- pending = _Pending(session_id, qids, events, method, {"session_id": session_id, **params}, replay)
- with _lock:
- _open[request_id] = pending
- events.fanout.write({"jsonrpc": "2.0", "id": request_id, "method": method, "params": pending.params})
- waited = 0.0
- reason = "timeout"
- while not pending.event.wait(_POLL_S):
- waited += _POLL_S
- if cancelled():
- reason = "interrupted"
- break
- if timeout is not None and waited >= timeout:
- break
- with _lock:
- still_open = _open.pop(request_id, None) is pending
- if still_open and pending.qids is not None:
- # A batch keeps every answer locked before the wait ended (main's sidecar: "locked
- # answers survive a timeout"); sudo/secret have no question ids and stay unanswered.
- pending.result = settle_batch(pending.locked,
- ended="cancelled" if reason == "interrupted" else "timed_out")
- if still_open:
- # The same teardown main's renderers key on (``request.cancel``): the card closes and a
- # timed-out password prompt says so.
- with contextlib.suppress(Exception):
- events.publish(session_id, {"id": request_id, "method": method, "reason": reason},
- event_type="request.cancel")
- return pending if pending.qids is not None else None
- # Settled by a viewer (a response frame or the last ``clarify.lock``): every OTHER viewer still
- # shows the card, and a classic CLI is parked inside its modal callback. Withdraw it everywhere
- # with ``reason: resolved`` (``RequestCancelReason``) so each renderer closes the matching card and
- # the CLI's connection thread releases its modal (``hermes_cli.gateway_agent``). No answer rides it.
- with contextlib.suppress(Exception):
- events.publish(session_id, {"id": request_id, "method": method, "reason": "resolved"},
- event_type="request.cancel")
- return pending
|