bundle.website.builtin.components.websocket.base.backend
========================================================

.. py:module:: bundle.website.builtin.components.websocket.base.backend


Attributes
----------

.. autoapisummary::

   bundle.website.builtin.components.websocket.base.backend.WebSocketHandler
   bundle.website.builtin.components.websocket.base.backend.TaskFactory


Functions
---------

.. autoapisummary::

   bundle.website.builtin.components.websocket.base.backend.create_router
   bundle.website.builtin.components.websocket.base.backend.run_websocket
   bundle.website.builtin.components.websocket.base.backend.every
   bundle.website.builtin.components.websocket.base.backend.drain_text
   bundle.website.builtin.components.websocket.base.backend.receive_json
   bundle.website.builtin.components.websocket.base.backend.now_ns
   bundle.website.builtin.components.websocket.base.backend.keepalive_loop


Module Contents
---------------

.. py:data:: WebSocketHandler

.. py:data:: TaskFactory

.. py:function:: create_router(endpoint: str, handler: WebSocketHandler | None = None) -> fastapi.APIRouter

   Build a websocket router bound to `endpoint`.

   :param endpoint: FastAPI websocket path (for example `/ws/ecc`).
   :param handler: Websocket coroutine handler. Defaults to `keepalive_loop`.

   :returns: APIRouter with one websocket entrypoint.


.. py:function:: run_websocket(websocket: fastapi.WebSocket, *task_factories: TaskFactory) -> None
   :async:


   Run one websocket session with composable async tasks.

   The function accepts the connection, starts all tasks, waits for completion,
   and performs robust cancellation cleanup when the socket closes.


.. py:function:: every(seconds: float, tick: TaskFactory) -> TaskFactory

   Return a task factory that runs `tick` periodically every `seconds`.


.. py:function:: drain_text(websocket: fastapi.WebSocket) -> None
   :async:


   Consume and discard incoming text frames until disconnect.


.. py:function:: receive_json(handle: collections.abc.Callable[[fastapi.WebSocket, dict], collections.abc.Awaitable[None]]) -> TaskFactory

   Return a task factory that reads JSON objects and forwards them to `handle`.


.. py:function:: now_ns() -> int

.. py:function:: keepalive_loop(websocket: fastapi.WebSocket) -> None
   :async:


   Default keepalive protocol: `keepalive` -> `keepalive_ack`.