Source code for mstar.model.cosmos3.sessions

"""Per-session world state for windowed rollouts.

A ``session_id`` on a windowed request names a world the client may come back
to (``resume_session``). The DiT node keeps the rollout's last window under
it and the streaming decoder its decode context, each in a ``SessionStore``.
The store is bounded and LRU-ordered, and it knows which sessions have a
request in flight: those are never evicted and refuse a second request, so
two rollouts cannot write the same world at once. Idle sessions expire after
their timeout, so a client that crashes mid-rollout does not leave a state
behind forever.
"""

from __future__ import annotations

import math
import time
from collections import OrderedDict
from dataclasses import dataclass
from typing import Any


@dataclass
class _Entry:
    value: Any                 # what the node keeps for the session; None until stored
    expires_at: float          # clock time an idle entry is dropped at
    live: str | None = None    # request id generating under this session


[docs] class SessionStore: """Bounded, LRU-ordered session state with in-flight pins and a TTL. A request that names a session ``begin``s it, which pins it for the request's duration (a second request on a live session is refused), reads the stored state with ``get`` (which promotes it, so every node's store ages the same way), and either ``put``s the new state when it is done or ``end``s the session. ``release`` unpins whatever a removed request held. Only idle sessions count against ``capacity`` and can be evicted (expired ones first, then the oldest); live ones never are, so the store holds at most ``capacity`` idle plus the in-flight sessions. """ def __init__( self, capacity: int, default_ttl_s: float, max_ttl_s: float, clock=time.monotonic, ): self.capacity = max(1, int(capacity)) self.default_ttl_s = float(default_ttl_s) self.max_ttl_s = float(max_ttl_s) self._clock = clock self._entries: OrderedDict[str, _Entry] = OrderedDict()
[docs] def ttl(self, requested: float | None) -> float: """A request's session timeout: the default when unset, else clamped to the served maximum.""" if requested is None: return self.default_ttl_s ttl = float(requested) if not ttl > 0: raise ValueError(f"session_timeout_s must be > 0, got {requested!r}") return min(ttl, self.max_ttl_s)
[docs] def begin(self, session_id: str, request_id: str) -> None: """Pin ``session_id`` for ``request_id`` until it stores or ends the session (or is removed). Refused while another request holds it.""" self._sweep() entry = self._entries.get(session_id) if entry is None: entry = self._entries[session_id] = _Entry(value=None, expires_at=math.inf) elif entry.live not in (None, request_id): raise ValueError( f"session {session_id!r} is in use by request {entry.live!r}; " "wait for it to finish or pick another session_id" ) entry.live = request_id self._entries.move_to_end(session_id)
[docs] def get(self, session_id: str) -> Any | None: """The stored state, promoting the session; None when the session is unknown, expired or has not stored anything yet.""" self._sweep() entry = self._entries.get(session_id) if entry is None or entry.value is None: return None self._entries.move_to_end(session_id) return entry.value
[docs] def put(self, session_id: str, value: Any, ttl_s: float | None = None) -> None: """Store the session's state and unpin it: the request under it is done with the session. Idle sessions over capacity go, oldest first.""" entry = self._entries.get(session_id) if entry is None: entry = self._entries[session_id] = _Entry(value=None, expires_at=0.0) entry.value = value entry.expires_at = self._clock() + self.ttl(ttl_s) entry.live = None self._entries.move_to_end(session_id) self._evict()
[docs] def end(self, session_id: str) -> None: """Forget the session, stored state and pin alike.""" self._entries.pop(session_id, None)
[docs] def release(self, request_id: str) -> None: """Unpin whatever ``request_id`` holds (the request was removed before it stored or ended its session). A session it never stored goes.""" for session_id, entry in list(self._entries.items()): if entry.live == request_id: entry.live = None if entry.value is None: del self._entries[session_id] self._evict()
[docs] def live(self, session_id: str) -> str | None: """The request generating under the session, if any.""" entry = self._entries.get(session_id) return None if entry is None else entry.live
[docs] def ids(self) -> list[str]: """Sessions in LRU order, oldest first.""" return list(self._entries)
def __contains__(self, session_id: str) -> bool: entry = self._entries.get(session_id) return entry is not None and entry.value is not None def __len__(self) -> int: return len(self._entries) def _sweep(self) -> None: now = self._clock() for session_id, entry in list(self._entries.items()): if entry.live is None and entry.expires_at <= now: del self._entries[session_id] def _evict(self) -> None: idle = [sid for sid, entry in self._entries.items() if entry.live is None] while len(idle) > self.capacity: del self._entries[idle.pop(0)]