esa-livefeed 0.0.1__tar.gz

esa_livefeed-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+© 2026 Ely-Sandra LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

esa_livefeed-0.0.1/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: esa-livefeed
+Version: 0.0.1
+Summary: Low-latency live feed server and managed client over raw TCP with JSONL framing, heartbeats, liveness detection, and unbounded per-client backpressure.
+Author-email: Ely-Sandra <info@ely-sandra.com>
+License-Expression: MIT
+Project-URL: Documentation, https://esa-livefeed.readthedocs.io/
+Project-URL: Homepage, https://github.com/ely-sandra/esa-livefeed
+Project-URL: Repository, https://github.com/ely-sandra/esa-livefeed.git
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hanaro>=2.0.1
+Dynamic: license-file
+
+# esa-livefeed
+
+Low-latency live feed server and managed client over raw TCP with JSONL framing,
+client-driven heartbeats, bidirectional liveness detection, and unbounded
+per-client backpressure. Pure Python stdlib; zero runtime dependencies.
+
+- `LivefeedServer` / `LivefeedServerSettings` — accepts clients (one
+  `LivefeedSession` per client: dedicated sender/receiver threads and an
+  unbounded outbound queue), fans out pre-encoded frames via
+  `publish(data: bytes)`, exposes connected clients via the `clients`
+  property, delivers client data frames to a registered message callback
+  (with the originating session for targeted replies), drops clients only
+  on liveness loss, and logs delivery-delay warnings without ever dropping
+  data.
+- `LivefeedClient` / `LivefeedClientSettings` — managed bidirectional
+  client: `start()` spawns background threads that connect, handshake,
+  deliver data frames to a registered message callback, send messages via
+  `send_message(dict)`, heartbeat after 3s of inactivity, detect a dead
+  server, and auto-reconnect into fresh state (no backlog).
+- Callbacks are registered on the objects themselves via
+  `set_message_callback` / `set_connect_callback` / `set_disconnect_callback`
+  (settings carry no callables), and every callback receives the peer
+  object first so handlers can communicate back.
+
+Wire protocol: newline-delimited JSON. Control frames: `hello`, `auth`,
+`heartbeat` (client only), `ack`, `ping`, `pong`. Data frames are
+application-defined (e.g. `{"type":"data",...}`).
+
+## Building
+
+```bash
+uv build          # or: pip wheel .
+```
+
+## Tests
+
+```bash
+python -m punit
+```

esa_livefeed-0.0.1/README.md

@@ -0,0 +1,39 @@
+# esa-livefeed
+
+Low-latency live feed server and managed client over raw TCP with JSONL framing,
+client-driven heartbeats, bidirectional liveness detection, and unbounded
+per-client backpressure. Pure Python stdlib; zero runtime dependencies.
+
+- `LivefeedServer` / `LivefeedServerSettings` — accepts clients (one
+  `LivefeedSession` per client: dedicated sender/receiver threads and an
+  unbounded outbound queue), fans out pre-encoded frames via
+  `publish(data: bytes)`, exposes connected clients via the `clients`
+  property, delivers client data frames to a registered message callback
+  (with the originating session for targeted replies), drops clients only
+  on liveness loss, and logs delivery-delay warnings without ever dropping
+  data.
+- `LivefeedClient` / `LivefeedClientSettings` — managed bidirectional
+  client: `start()` spawns background threads that connect, handshake,
+  deliver data frames to a registered message callback, send messages via
+  `send_message(dict)`, heartbeat after 3s of inactivity, detect a dead
+  server, and auto-reconnect into fresh state (no backlog).
+- Callbacks are registered on the objects themselves via
+  `set_message_callback` / `set_connect_callback` / `set_disconnect_callback`
+  (settings carry no callables), and every callback receives the peer
+  object first so handlers can communicate back.
+
+Wire protocol: newline-delimited JSON. Control frames: `hello`, `auth`,
+`heartbeat` (client only), `ack`, `ping`, `pong`. Data frames are
+application-defined (e.g. `{"type":"data",...}`).
+
+## Building
+
+```bash
+uv build          # or: pip wheel .
+```
+
+## Tests
+
+```bash
+python -m punit
+```

esa_livefeed-0.0.1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "esa-livefeed"
+version = "0.0.1"
+description = "Low-latency live feed server and managed client over raw TCP with JSONL framing, heartbeats, liveness detection, and unbounded per-client backpressure."
+authors = [
+    { name="Ely-Sandra", email="info@ely-sandra.com" }
+]
+readme = "README.md"
+license = "MIT"
+classifiers = [
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python"
+]
+requires-python = ">=3.11"
+dependencies = [
+    "hanaro (>=2.0.1)"
+]
+
+[dependency-groups]
+dev = [
+    "build",
+    "coverage",
+    "mypy",
+    "punit (>=1.14.1)",
+    "py-conventional-semver (>=1.3.5)",
+    "twine"
+]
+
+[project.urls]
+Documentation = "https://esa-livefeed.readthedocs.io/"
+Homepage = "https://github.com/ely-sandra/esa-livefeed"
+Repository = "https://github.com/ely-sandra/esa-livefeed.git"
+
+
+[tool.uv.sources]
+esa-livefeed = { path = "src/esa-livefeed", editable = true }
+
+[tool.uv]
+package = true

esa_livefeed-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

esa_livefeed-0.0.1/src/esa_livefeed/__init__.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: © 2026 Ely-Sandra LLC
+# SPDX-License-Identifier: LicenseRef-Ely-Sandra-Proprietary=https://ely-sandra.com/LICENSE.md
+
+from .livefeed_client import LivefeedClient
+from .livefeed_client_settings import LivefeedClientSettings
+from .livefeed_server import LivefeedServer
+from .livefeed_server_settings import LivefeedServerSettings
+from .livefeed_session import LivefeedSession
+
+__version__ = '0.0.1'
+__commit__ = 'f80fb34'
+__all__ = [
+    '__version__', '__commit__',
+    'LivefeedClient',
+    'LivefeedClientSettings',
+    'LivefeedServer',
+    'LivefeedServerSettings',
+    'LivefeedSession',
+]

esa_livefeed-0.0.1/src/esa_livefeed/livefeed_client.py

@@ -0,0 +1,480 @@
+# SPDX-FileCopyrightText: © 2026 Ely-Sandra LLC
+# SPDX-License-Identifier: LicenseRef-Ely-Sandra-Proprietary=https://ely-sandra.com/LICENSE.md
+
+"""Managed livefeed client.
+
+Provides the ``LivefeedClient`` class which maintains a livefeed connection
+for the lifetime of a :meth:`start`/:meth:`stop` pair.  A background
+control thread hosts the connect/stream/reconnect cycle;  each connection
+is serviced by a dedicated sender thread (blocked on the client's unbounded
+outbound queue, the sole writer to the socket) and a dedicated receiver
+thread (blocked on the socket, the sole reader).
+
+The application registers callbacks with :meth:`set_message_callback`,
+:meth:`set_connect_callback`, and :meth:`set_disconnect_callback`, and sends
+messages with :meth:`send_message`.  Data frames are delivered to the
+message callback serially, in receive order;  the callback receives the
+client first, so it can reply to the server.  A message callback that
+raises ends the connection and triggers the normal reconnect cycle.
+
+When the connection breaks (server stop, network loss, liveness timeout),
+the client invokes the disconnect callback and automatically reconnects
+into fresh state;  no backlog is ever replayed.
+
+Usage
+-----
+
+    settings = LivefeedClientSettings(host='10.0.0.5', port=3001)
+    client = LivefeedClient(settings)
+    client.set_message_callback(on_bar)
+    client.start()
+    ...
+    client.stop()
+
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from contextlib import suppress
+from queue import Empty, Queue
+import socket
+import time
+from threading import Event, Thread
+
+from .livefeed_client_settings import LivefeedClientSettings
+from .protocol import (
+    TYPE_AUTH,
+    TYPE_AUTHOK,
+    TYPE_HEARTBEAT,
+    TYPE_HELLO,
+    control_types,
+    encode_message,
+    parse_message,
+    split_frames,
+)
+
+HEARTBEAT_TICK_SECONDS: float = 0.5
+RECV_BUFFER_SIZE: int = 65536
+RECV_TICK_SECONDS: float = 0.5
+STOP_JOIN_TIMEOUT_SECONDS: float = 10.0
+
+
+class LivefeedClient:
+    """
+    Managed livefeed client with automatic reconnection.
+
+    The application only calls :meth:`start`, :meth:`stop`, and
+    :meth:`send_message`.  Everything else — connect, handshake, data
+    delivery, heartbeats, liveness detection, and reconnection — is
+    maintained by the client's background threads.  The sender thread is
+    the sole writer to the socket:  it drains the unbounded outbound queue
+    and emits heartbeats after the configured inactivity interval.  The
+    receiver thread is the sole reader:  it delivers data frames to the
+    registered message callback, serially, in receive order.  Liveness is
+    enforced by the sender thread, which wakes on queue timeouts.
+
+    All callbacks receive the client as their first argument so the
+    application can communicate back to the server.  A message callback
+    that raises ends the connection and triggers the normal reconnect
+    cycle.
+
+    Usage
+    -----
+
+    .. code-block:: python
+
+        settings = LivefeedClientSettings(host='10.0.0.5', port=3001)
+        client = LivefeedClient(settings)
+        client.set_message_callback(on_bar)
+        client.start()
+        ...
+        client.stop()
+    """
+
+    __connect_callback: Callable[[LivefeedClient, dict], None] | None
+    __disconnect_callback: Callable[[LivefeedClient, str], None] | None
+    __end_reason: str
+    __last_rx: float
+    __last_tx: float
+    __logger: logging.Logger
+    __message_callback: Callable[[LivefeedClient, dict], None] | None
+    __queue: Queue | None
+    __receiver_thread: Thread | None
+    __running: bool
+    __sender_thread: Thread | None
+    __settings: LivefeedClientSettings
+    __socket: socket.socket | None
+    __stopped: Event
+    __thread: Thread | None
+
+    def __init__(self, settings: LivefeedClientSettings) -> None:
+        """
+        Initialize the client (inert until :meth:`start` is called).
+
+        :param settings: The client configuration.
+        """
+        self.__connect_callback = None
+        self.__disconnect_callback = None
+        self.__end_reason = ''
+        self.__last_rx = 0.0
+        self.__last_tx = 0.0
+        self.__logger = logging.getLogger('esa_livefeed.client')
+        self.__message_callback = None
+        self.__queue = None
+        self.__receiver_thread = None
+        self.__running = False
+        self.__sender_thread = None
+        self.__settings = settings
+        self.__socket = None
+        self.__stopped = Event()
+        self.__thread = None
+
+    def __authenticate(self, sock: socket.socket) -> None:
+        """
+        Send the auth frame and wait for the server's authok confirmation.
+
+        :param sock: The handshake socket (must have a timeout set).
+        :raises ConnectionError: When the server rejects the token or the confirmation is malformed.
+        :returns: None
+        """
+        sock.sendall(encode_message({'type': TYPE_AUTH, 'token': self.__settings.token}))
+        try:
+            ack = parse_message(self.__read_line(sock))
+        except ValueError as ex:
+            raise ConnectionError(f'malformed authok frame from server: {ex}') from ex
+        if ack.get('type') != TYPE_AUTHOK or ack.get('ok') is not True:
+            raise ConnectionError(f'authentication rejected by server: {ack!r}')
+        self.__last_rx = time.monotonic()
+
+    def __check_liveness(self, sock: socket.socket) -> bool:
+        """
+        Close the connection when no frame has been received within the liveness window.
+
+        :param sock: The connection socket to close when stale.
+        :returns: True when the connection is still live, False when it was closed.
+        """
+        if time.monotonic() - self.__last_rx <= self.__settings.liveness_timeout_seconds:
+            return True
+        self.__set_end_reason(f'no frame received from server within {self.__settings.liveness_timeout_seconds} seconds')
+        with suppress(OSError):
+            sock.close()
+        return False
+
+    def __connect_and_stream(self) -> None:
+        """
+        Open one connection:  handshake, then stream until the connection ends.
+
+        Never raises;  the end reason is recorded on the client for the
+        reconnect cycle.
+
+        :returns: None
+        """
+        try:
+            sock = socket.create_connection(
+                (self.__settings.host, self.__settings.port),
+                timeout=self.__settings.connect_timeout_seconds,
+            )
+        except OSError as ex:
+            self.__set_end_reason(str(ex) or ex.__class__.__name__)
+            return
+        sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        self.__socket = sock
+        self.__queue = Queue()
+        self.__last_rx = time.monotonic()
+        self.__last_tx = time.monotonic()
+        self.__end_reason = ''
+        sender = Thread(target=self.__send_loop, name='livefeed-client-sender', daemon=True)
+        receiver = Thread(target=self.__recv_loop, name='livefeed-client-receiver', daemon=True)
+        started = False
+        try:
+            hello_line = self.__read_line(sock)
+            try:
+                hello = parse_message(hello_line)
+            except ValueError as ex:
+                raise ConnectionError(f'malformed hello frame from server: {ex}') from ex
+            if hello.get('type') != TYPE_HELLO:
+                raise ConnectionError(f'expected hello frame, got {hello.get("type")!r}')
+            if hello.get('auth'):
+                if self.__settings.token is None:
+                    raise ConnectionError('server requires authentication but no token is configured')
+                self.__authenticate(sock)
+            self.__logger.info(f'livefeed client connected to {self.__settings.host}:{self.__settings.port}')
+            self.__invoke(self.__connect_callback, self, hello)
+            sock.settimeout(RECV_TICK_SECONDS)
+            sender.start()
+            receiver.start()
+            started = True
+            self.__sender_thread = sender
+            self.__receiver_thread = receiver
+            while self.__running and sender.is_alive() and receiver.is_alive():
+                time.sleep(0.05)
+        except Exception as ex:
+            self.__set_end_reason(str(ex) or ex.__class__.__name__)
+        finally:
+            with suppress(OSError):
+                sock.close()
+            if started:
+                sender.join(timeout=STOP_JOIN_TIMEOUT_SECONDS)
+                receiver.join(timeout=STOP_JOIN_TIMEOUT_SECONDS)
+            self.__sender_thread = None
+            self.__receiver_thread = None
+            self.__queue = None
+            self.__socket = None
+
+    def __invoke(self, callback: Callable | None, *args) -> None:
+        """
+        Invoke a registered callback.
+
+        :param callback: The callback to invoke (None is a no-op).
+        :param args: The positional arguments to pass.
+        :returns: None
+        """
+        if callback is not None:
+            callback(*args)
+
+    def __read_line(self, sock: socket.socket) -> bytes:
+        """
+        Read one newline-terminated frame from the socket.
+
+        :param sock: The socket to read from (must have a timeout set).
+        :returns: The raw frame, including the trailing newline.
+        :raises ConnectionError: When the connection closes before a complete frame arrives.
+        """
+        buffer = bytearray()
+        while not buffer.endswith(b'\n'):
+            chunk = sock.recv(4096)
+            if not chunk:
+                raise ConnectionError('server closed the connection during handshake')
+            buffer.extend(chunk)
+        return bytes(buffer)
+
+    def __recv_loop(self) -> None:
+        """
+        Run the receiver thread:  read frames until the connection ends, delivering data frames to the message callback.
+
+        This thread is the sole reader of the socket.  Control frames are
+        consumed by the library and are not delivered.
+
+        :returns: None
+        """
+        sock = self.__socket
+        if sock is None:
+            return
+        buffer = bytearray()
+        try:
+            while self.__running:
+                try:
+                    chunk = sock.recv(RECV_BUFFER_SIZE)
+                except socket.timeout:
+                    continue
+                if not chunk:
+                    self.__set_end_reason('server closed the connection')
+                    with suppress(OSError):
+                        sock.close()
+                    return
+                buffer.extend(chunk)
+                for frame in split_frames(buffer):
+                    self.__last_rx = time.monotonic()
+                    message = parse_message(frame)
+                    if message.get('type') in control_types():
+                        continue
+                    try:
+                        self.__invoke(self.__message_callback, self, message)
+                    except Exception as ex:
+                        self.__logger.exception(f'livefeed message callback error: {ex}')
+                        self.__set_end_reason(f'message callback raised: {ex}')
+                        with suppress(OSError):
+                            sock.close()
+                        return
+        except (OSError, ValueError) as ex:
+            self.__set_end_reason(str(ex) or ex.__class__.__name__)
+
+    def __run(self) -> None:
+        """
+        Run the connect/stream/reconnect cycle until stopped.
+
+        :returns: None
+        """
+        while not self.__stopped.is_set():
+            self.__connect_and_stream()
+            if self.__stopped.is_set():
+                break
+            reason = self.__end_reason or 'connection closed'
+            self.__logger.info(
+                f'livefeed client disconnected ({reason}), reconnecting in {self.__settings.reconnect_delay_seconds} seconds'
+            )
+            try:
+                self.__invoke(self.__disconnect_callback, self, reason)
+            except Exception as ex:
+                self.__logger.exception(f'livefeed disconnect callback error: {ex}')
+            deadline = time.monotonic() + self.__settings.reconnect_delay_seconds
+            while not self.__stopped.is_set() and time.monotonic() < deadline:
+                time.sleep(0.05)
+
+    def __send_loop(self) -> None:
+        """
+        Run the sender thread:  drain the outbound queue until the connection ends.
+
+        This thread is the sole writer to the socket.  It emits heartbeats
+        after the configured inactivity interval and enforces the liveness
+        timeout, waking on queue timeouts and after each send.
+
+        :returns: None
+        """
+        sock = self.__socket
+        queue = self.__queue
+        if sock is None or queue is None:
+            return
+        try:
+            while self.__running:
+                try:
+                    data = queue.get(timeout=HEARTBEAT_TICK_SECONDS)
+                except Empty:
+                    if time.monotonic() - self.__last_tx < self.__settings.heartbeat_seconds:
+                        if not self.__check_liveness(sock):
+                            return
+                        continue
+                    data = encode_message({'type': TYPE_HEARTBEAT, 'ts': time.time_ns()})
+                self.__send(sock, data)
+                self.__last_tx = time.monotonic()
+                if not self.__check_liveness(sock):
+                    return
+        except OSError:
+            pass
+
+    def __send(self, sock: socket.socket, data: bytes) -> None:
+        """
+        Send raw bytes to the server, retrying through socket timeouts.
+
+        :param sock: The connection socket to write to.
+        :param data: The bytes to send.
+        :raises OSError: When the send fails.
+        """
+        view = memoryview(data)
+        while view:
+            try:
+                sent = sock.send(view)
+            except socket.timeout:
+                continue
+            view = view[sent:]
+
+    def __set_end_reason(self, reason: str) -> None:
+        """
+        Record the connection end reason, keeping the first reason set.
+
+        :param reason: A short human-readable reason.
+        :returns: None
+        """
+        if not self.__end_reason:
+            self.__end_reason = reason
+
+    def __thread_main(self) -> None:
+        """
+        Run the client's control loop (background thread body).
+        """
+        try:
+            self.__run()
+        except Exception as ex:
+            self.__logger.exception(f'livefeed client run error: {ex}')
+
+    @property
+    def is_running(self) -> bool:
+        """
+        Determine whether the client has been started and not stopped.
+
+        :returns: True when the client's background thread is active.
+        """
+        return self.__running
+
+    def send_message(self, message: dict) -> None:
+        """
+        Enqueue a message to send to the server.
+
+        The frame is written to the socket by the client's sender thread.
+        A no-op when there is no active connection (during startup,
+        shutdown, or a reconnect gap).
+
+        :param message: The JSON-serializable message to send.
+        :returns: None
+        """
+        queue = self.__queue
+        if queue is None:
+            return
+        queue.put(encode_message(message))
+
+    def set_connect_callback(self, callback: Callable[[LivefeedClient, dict], None] | None) -> None:
+        """
+        Register the callback invoked when the client finishes connecting.
+
+        :param callback: The callback to invoke with the client and the server's hello frame, or None to clear.
+        :returns: None
+        """
+        self.__connect_callback = callback
+
+    def set_disconnect_callback(self, callback: Callable[[LivefeedClient, str], None] | None) -> None:
+        """
+        Register the callback invoked when a connection ends (not on stop).
+
+        :param callback: The callback to invoke with the client and the end reason, or None to clear.
+        :returns: None
+        """
+        self.__disconnect_callback = callback
+
+    def set_message_callback(self, callback: Callable[[LivefeedClient, dict], None] | None) -> None:
+        """
+        Register the callback invoked when a data frame is received from the server.
+
+        The callback receives the client first, so it can reply to the
+        server via :meth:`send_message`.  Control frames (hello, ack,
+        pong, ...) are consumed by the library and are not delivered.
+
+        :param callback: The callback to invoke with the client and the decoded frame, or None to clear.
+        :returns: None
+        """
+        self.__message_callback = callback
+
+    def start(self) -> None:
+        """
+        Start the client's background connection thread.
+
+        Idempotent;  a second call while running is a no-op.
+
+        :returns: None
+        """
+        if self.__running:
+            return
+        self.__running = True
+        self.__stopped.clear()
+        self.__thread = Thread(target=self.__thread_main, name='livefeed-client', daemon=True)
+        self.__thread.start()
+
+    def stop(self) -> None:
+        """
+        Stop the client, closing the current connection and joining the threads.
+
+        Idempotent;  a second call is a no-op.  Blocks until the background
+        thread has exited (bounded wait).
+
+        :returns: None
+        """
+        if not self.__running:
+            return
+        self.__running = False
+        self.__stopped.set()
+        sock = self.__socket
+        if sock is not None:
+            with suppress(OSError):
+                sock.close()
+        thread = self.__thread
+        if thread is not None:
+            thread.join(timeout=STOP_JOIN_TIMEOUT_SECONDS)
+        self.__thread = None
+        self.__socket = None
+        self.__queue = None
+
+
+__all__ = [
+    'LivefeedClient',
+]