yera.ui.server

Run Yera apps through the local browser UI.

The server owns live app runtimes, event routers, persisted session history, SSE publication, and the FastAPI application. HTTP route modules receive narrow callbacks rather than the server itself, keeping transport concerns separate from execution and persistence.

Symbols

class ServerLaunchConfig — Configure behavior when entering a Yera server.
class YeraServer — Coordinate app execution, persistence, event rendering, and HTTP delivery.

ServerLaunchConfig

Configure behavior when entering a Yera server.

Fields

startup_app_id
type: str | None = None

App to launch immediately when the root URL is opened, or None to redirect to app discovery.

Methods


ServerLaunchConfig.__init__

__init__(
    startup_app_id: str | None = None,
) → None

YeraServer

Inherits: uvicorn.Server

Coordinate app execution, persistence, event rendering, and HTTP delivery.

Each live session owns an executor, event stream, browser publisher, and router task. Output events are rendered into HTMX fragments and persisted before publication. Submitted input is correlated with the active request, validated, redacted for storage when necessary, and then returned to the app's event stream.

Stored sessions can be replayed without executing their app again. Server startup marks sessions that could not survive a previous process exit as interrupted, while shutdown stops active executors and wakes blocked router threads.

Methods

__init__ — Configure a local Yera UI server.
handle_exit — Handles server exit signals by stopping all active session executors.
__aenter__ — Open persistence and start serving the local UI.
__aexit__ — Stop live runtimes and close server-owned resources.

YeraServer.__init__

__init__(
    apps: Mapping[str, AppReference],
    executor_factory: Callable[[AppFunctionWrapper, tuple, dict, str], PyRuntimeExecutor] | None = None,
    session_store: BaseSessionStore | None = None,
    launch_config: ServerLaunchConfig | None = None,
    update_service: UpdateService | None = None,
    host: str = '127.0.0.1',
    port: int = 8000,
    server_socket: socket.socket | None = None,
)

Configure a local Yera UI server.

The server copies the supplied app registry, creates a session store when none is provided, and builds a FastAPI application from route registrars bound to its capabilities. App execution does not begin until a session is launched.

Parameters

apps
type: Mapping[str, AppReference]

Applications available to the UI, keyed by stable app ID.

executor_factory
type: Callable[[AppFunctionWrapper, tuple, dict, str], PyRuntimeExecutor] | None = None

Optional factory used to construct an executor for a newly launched session.

session_store
type: BaseSessionStore | None = None

Persistent session store. Defaults to a local SQLite store.

launch_config
type: ServerLaunchConfig | None = None

Initial navigation and startup-app behavior.

update_service
type: UpdateService | None = None

Optional service that checks for a newer Yera release in the background.

host
type: str = '127.0.0.1'

Network interface on which the local server listens.

port
type: int = 8000

TCP port on which the local server listens.

server_socket
type: socket.socket | None = None

Optional pre-bound socket supplied by the terminal launcher to make port selection race-safe.

Raises

ValueError

If launch_config names an app absent from apps.

YeraServer.handle_exit

handle_exit(
    sig: int,
    frame: FrameType | None,
) → None

Handles server exit signals by stopping all active session executors.

Parameters

sig
type: int

The signal number.

frame
type: FrameType | None

The current stack frame.

YeraServer.__aenter__

__aenter__() → YeraServer

Open persistence and start serving the local UI.

Startup initializes the session database, marks persisted running or waiting sessions as interrupted because their former process cannot resume them, and starts the optional release check in the background. The method waits until Uvicorn reports that it is serving.

Returns

type: YeraServer

The running Yera server.

Raises

RuntimeError

If the server exits before it finishes starting.

YeraServer.__aexit__

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

Stop live runtimes and close server-owned resources.

Shutdown signals every router, closes its event stream, stops its executor, and closes its publisher. Remaining live lifecycle states are persisted as interrupted before the session store and router thread pool are released.

Parameters

exc_type
type: type[BaseException] | None

Exception type if an error occurred.

exc_val
type: BaseException | None

Exception value if an error occurred.

exc_tb
type: TracebackType | None

Traceback if an error occurred.