yera.ui.sessions_store.sqlite_store

Persist browser sessions and event histories in a local SQLite database.

The store uses WAL mode and one connection per calling thread. Each operation commits on success and rolls back on failure, while server shutdown closes every connection opened during the store context.

Symbols

class SQLiteSessionStore — Persist session metadata and ordered events in SQLite.

SQLiteSessionStore

Persist session metadata and ordered events in SQLite.

The database lives in Yera's home directory unless another root is supplied. Entering the store creates or migrates its schema and enables WAL mode. Runtime and HTTP threads receive separate connections, while a shared registry lets context exit close them all.

Event insertion and its optional metadata update occur in one transaction. This keeps transcript history, titles, timestamps, and lifecycle status consistent.

Methods

__init__ — Configure a closed SQLite session store.
create — Create a new session record for *app_id*.
has — Return ``True`` if a session with *session_id* exists in the store.
has_events — Check whether any events are stored for *session_id*.
get — Retrieve the :class:`SessionRecord` for *session_id*.
list — Return all stored sessions ordered by most recent update time.
update — Update metadata for *session_id*.
append_event — Append an event and optional metadata update in one transaction.
read_records — Read timestamped events in their original append order.
__enter__ — Create or migrate the database and open the store for operations.
__exit__ — Close every thread-local connection and mark the store closed.

SQLiteSessionStore.__init__

__init__(
    root_path: Path | None = None,
    timeout: float = 5.0,
) → None

Configure a closed SQLite session store.

No directory, database, or connection is created until the store enters its context.

Parameters

root_path
type: Path | None = None

Directory containing sessions.db, or None to use Yera's home directory.

timeout
type: float = 5.0

Seconds a connection waits for a database lock before failing.

SQLiteSessionStore.create

create(
    app_id: str,
) → SessionRecord

Create a new session record for app_id.

Parameters

app_id
type: str

Identifier of the application that owns the session.

Returns

type: SessionRecord

The newly created :class:SessionRecord.

SQLiteSessionStore.has

has(
    session_id: str,
) → bool

Return True if a session with session_id exists in the store.

Parameters

session_id
type: str

The UUID of the session to look up.

Returns

type: bool

True if the session is present, otherwise False.

SQLiteSessionStore.has_events

has_events(
    session_id: str,
) → bool

Check whether any events are stored for session_id.

Parameters

session_id
type: str

The UUID of the session whose event log is queried.

Returns

type: bool

True if at least one event exists, otherwise False.

SQLiteSessionStore.get

get(
    session_id: str,
) → SessionRecord

Retrieve the :class:SessionRecord for session_id.

Parameters

session_id
type: str

The UUID of the desired session.

Returns

type: SessionRecord

The corresponding :class:SessionRecord.

Raises

KeyError

If no such session exists.

SQLiteSessionStore.list

list() → list[SessionRecord]

Return all stored sessions ordered by most recent update time.

Returns

type: list[SessionRecord]

A list of :class:SessionRecord objects sorted descending by updated_at.

SQLiteSessionStore.update

update(
    session_id: str,
    title: str | None = None,
    status: SessionStatus | None = None,
) → None

Update metadata for session_id.

Parameters

session_id
type: str

The UUID of the session to modify.

title
type: str | None = None

Optional new title. If omitted, only the updated_at timestamp is refreshed.

status
type: SessionStatus | None = None

An optional new lifecycle status for the session.

Raises

KeyError

If the specified session does not exist.

SQLiteSessionStore.append_event

append_event(
    session_id: str,
    event: OutputEvent | InputEvent,
    update: SessionRecordUpdate | None = None,
) → None

Append an event and optional metadata update in one transaction.

The event is serialized with its concrete model name so it can be reconstructed as typed input or output during replay. The session's update timestamp is always refreshed; supplied title and status values are committed alongside the event.

Parameters

session_id
type: str

Session receiving the event.

event
type: OutputEvent | InputEvent

Typed runtime input or output event to serialize.

update
type: SessionRecordUpdate | None = None

Optional title or lifecycle change committed with the event.

Raises

KeyError

If the session does not exist.

SQLiteSessionStore.read_records

read_records(
    session_id: str,
) → Iterator[StoredEventRecord]

Read timestamped events in their original append order.

Rows are fetched while the store connection is open, then deserialized lazily by the returned iterator. The database creation timestamp is retained as the authoritative persistence time for each event.

Parameters

session_id
type: str

Session whose event history is read.

Returns

type: Iterator[StoredEventRecord]

An iterator of timestamped input and output event records.

Raises

KeyError

If the session does not exist. This is raised before the iterator is returned.

ValueError

If iteration encounters an unknown stored event type or an invalid persistence timestamp.

SQLiteSessionStore.__enter__

__enter__() → Self

Create or migrate the database and open the store for operations.

Returns

type: Self

The initialized, open store.

SQLiteSessionStore.__exit__

__exit__(
    exc_type: type[BaseException] | None,
    exc_val: BaseException | None,
    exc_tb: TracebackType | None,
) → None

Close every thread-local connection and mark the store closed.

Parameters

exc_type
type: type[BaseException] | None

Type of exception leaving the context, if any.

exc_val
type: BaseException | None

Exception instance leaving the context, if any.

exc_tb
type: TracebackType | None

Traceback associated with the exception, if any.