python-aidot-cameras 0.13.0__tar.gz → 0.13.1__tar.gz

{python_aidot_cameras-0.13.0/python_aidot_cameras.egg-info → python_aidot_cameras-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.13.0
+Version: 0.13.1
 Summary: Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)
 Author-email: cbrightly <chris.brightly@gmail.com>
 License-Expression: MIT

{python_aidot_cameras-0.13.0 → python_aidot_cameras-0.13.1}/aidot_cameras/camera/client.py

@@ -854,6 +854,10 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         self._last_frame_time: float = 0.0
         self._keepalive_rtsp_url: Optional[str] = None  # local serve URL (go2rtc pulls)
         self._go2rtc_url: Optional[str] = None           # go2rtc API base (prefer-go2rtc)
+        # Whether WE own this camera's go2rtc stream registration.  False when the
+        # consumer registers the stream itself and passes the URL for viewer
+        # queries only - in which case we must neither add nor REMOVE it.
+        self._go2rtc_manages_stream: bool = True
         self._go2rtc_pull_url: Optional[str] = None      # go2rtc pull URL once registered
         self._go2rtc_task: "Optional[asyncio.Task[None]]" = None
         # Set by the DTLS serve loop once ffmpeg is bound + serving, so
@@ -2789,6 +2793,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         fast_connect: Optional[bool] = None,
         sdes_audio: Optional[bool] = None,
         go2rtc_url: Optional[str] = None,
+        go2rtc_register: bool = True,
         live_stream_param: Optional[bool] = None,
         serve_relay: Optional[bool] = None,
         stream_idle_s: Optional[float] = None,
@@ -2828,6 +2833,22 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         ``AIDOT_SERVE_RELAY`` env var (default on); set False to serve ffmpeg
         directly on the public port (the pre-0.7.18 behaviour).
 
+        ``go2rtc_url`` points at a go2rtc API base.  It does two things: register
+        the local serve with go2rtc (exposing its low-latency pull URL), and let
+        the idle-release logic ask go2rtc **who is watching**.
+
+        ``go2rtc_register=False`` keeps the second and drops the first, for a
+        consumer that registers the stream itself - registering it twice
+        re-points the source mid-stream and was observed leaving DTLS cameras
+        producing nothing at all.  Such a consumer must still pass ``go2rtc_url``:
+        withholding it does not merely lose a nicety, it silently disables viewer
+        detection, and in SDES **push** mode that is the only viewer signal there
+        is (the serve port is go2rtc's shared RTSP port, where every camera's own
+        publisher is connected, so a socket check would report a viewer for every
+        camera forever).  With no signal ``_viewer_present`` answers "unknown",
+        ``_idle_release_due`` correctly never releases on unknown, and a battery
+        camera's keepalive renews forever against a camera nobody is watching.
+
         ``stream_idle_s`` sets the no-viewer idle-release window in seconds,
         overriding the ``AIDOT_STREAM_IDLE_S`` env default (120).  ``0`` (or
         negative) keeps the warm WebRTC session forever so re-views are instant
@@ -2860,6 +2881,7 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             return
         self._keepalive_rtsp_url = rtsp_push_url
         self._go2rtc_url = go2rtc_url
+        self._go2rtc_manages_stream = bool(go2rtc_register)
         self._streaming_active = True
         # App parity: keep a battery camera awake for the whole view (mains cams
         # never sleep, so this is a no-op there). Single-instance; cancelled in
@@ -2874,7 +2896,18 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         # Prefer-go2rtc: if a go2rtc server is configured, register the local
         # serve with it once ready and expose its pull URL (ffmpeg fallback
         # otherwise). Opt-in: with no go2rtc_url, behaviour is unchanged.
-        if go2rtc_url:
+        #
+        # ``go2rtc_register=False`` stores the URL for QUERIES ONLY and skips
+        # registration.  That exists for a consumer that registers the stream
+        # itself: registering it twice re-points the source while a stream is
+        # mid-flight, which was observed leaving DTLS cameras producing nothing
+        # at all.  Such a consumer previously had to withhold go2rtc_url
+        # entirely, which silently disabled viewer detection - and in SDES push
+        # mode that means a battery camera can never idle-release, because
+        # ``_viewer_present`` answers "unknown" and ``_idle_release_due``
+        # (correctly) never releases on unknown.  The keepalive then renews
+        # forever against a camera nobody is watching.
+        if go2rtc_url and go2rtc_register:
             self._go2rtc_task = asyncio.ensure_future(self._register_with_go2rtc())
 
     @property
@@ -2934,9 +2967,17 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             _LOGGER.debug("camera %s: swallowed exception in %s", getattr(self, "device_id", "?"), '_register_with_go2rtc', exc_info=True)
 
     async def _deregister_go2rtc(self) -> None:
-        """Remove this camera's stream from go2rtc (best-effort)."""
+        """Remove this camera's stream from go2rtc (best-effort).
+
+        Only ever removes a registration this client created.  With
+        ``go2rtc_register=False`` the consumer owns the stream and merely lent us
+        the URL to ask who is watching; deleting its stream on stop or
+        idle-release would tear down the very thing it is serving from.
+        """
         base = self._go2rtc_url
         self._go2rtc_pull_url = None
+        if not self._go2rtc_manages_stream:
+            return
         # Deliberately NOT gated on `pull`: go2rtc answers the register call with
         # 400 when it cannot immediately validate the source (a camera that has
         # not started producing yet), yet it still keeps the stream registered.
@@ -3099,22 +3140,21 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
 
         name = self._go2rtc_stream_name()
         base = self._go2rtc_url
-        if not base:
-            # No go2rtc to ask.  In PUSH mode the fallback below is not merely
-            # unavailable, it is WRONG: the "serve port" is go2rtc's shared RTSP
-            # port (8554), where every camera's own publisher is connected, so the
-            # check reports a viewer for every camera forever and nothing ever
-            # releases.  Answer "unknown" instead of a confident lie - the caller
-            # then holds the stream rather than tearing down a live view, and the
-            # honest way out is for the consumer to pass go2rtc_url.
-            if self._keepalive_rtsp_url and not str(
-                    self._keepalive_rtsp_url).startswith("http"):
-                _LOGGER.debug(
-                    "no go2rtc url and the serve is an RTSP push to a shared "
-                    "port; cannot tell whether anyone is watching",
-                )
-                self._viewer_cache = (_now_mono, None)
-                return None
+
+        # In PUSH mode the "serve port" is go2rtc's SHARED RTSP port (8554),
+        # where every camera's own publisher is connected - so the socket
+        # fallback below is not merely unavailable, it is WRONG: it would report
+        # a viewer for every camera forever and nothing would ever release.
+        # Tracked separately from `base` because it must gate the fallback even
+        # when go2rtc IS configured but the query fails.
+        push_mode = bool(self._keepalive_rtsp_url) and not str(
+            self._keepalive_rtsp_url).startswith("http")
+
+        # Ask go2rtc when we can. This is the only viewer signal that works in
+        # push mode, which is why a consumer that registers its own stream
+        # should still pass go2rtc_url with go2rtc_register=False rather than
+        # withholding it (withholding it silently pins push-mode cameras to
+        # "unknown", and unknown never releases).
         if base and name:
             try:
                 import aiohttp
@@ -3128,6 +3168,18 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
                     return _answer
             except Exception as exc:
                 _LOGGER.debug("go2rtc viewer check failed: %s", exc)
+
+        if push_mode:
+            # Answer "unknown" instead of a confident lie - the caller then holds
+            # the stream rather than tearing down a live view.
+            _LOGGER.debug(
+                "cannot tell whether anyone is watching: the serve is an RTSP "
+                "push to a shared port and go2rtc %s",
+                "did not answer" if base else "was not configured",
+            )
+            self._viewer_cache = (_now_mono, None)
+            return None
+
         _answer = self._sdes_serve_consumer_present(port)
         self._viewer_cache = (_now_mono, _answer)
         return _answer

{python_aidot_cameras-0.13.0 → python_aidot_cameras-0.13.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-aidot-cameras"
-version = "0.13.0"
+version = "0.13.1"
 description = "Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)"
 readme = "README.md"
 license = "MIT"

{python_aidot_cameras-0.13.0 → python_aidot_cameras-0.13.1/python_aidot_cameras.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.13.0
+Version: 0.13.1
 Summary: Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)
 Author-email: cbrightly <chris.brightly@gmail.com>
 License-Expression: MIT

{python_aidot_cameras-0.13.0 → python_aidot_cameras-0.13.1}/python_aidot_cameras.egg-info/SOURCES.txt

@@ -151,5 +151,6 @@ tests/test_turn_create_permission.py
 tests/test_upstream_compat.py
 tests/test_viewer_check_throttle.py
 tests/test_viewer_presence.py
+tests/test_viewer_present_push_mode.py
 tests/test_wait_or_event.py
 tests/test_wake_readiness_retry.py

python_aidot_cameras-0.13.1/tests/test_viewer_present_push_mode.py

@@ -0,0 +1,236 @@
+"""``_viewer_present`` in SDES push mode, and the ``go2rtc_register`` seam.
+
+Why this file exists, in one paragraph:
+
+In push mode the "serve port" is go2rtc's SHARED RTSP port (8554), where every
+camera's own publisher is connected - so a socket check there reports a viewer
+for every camera forever. ``_viewer_present`` therefore refuses to use it and
+answers "unknown", and ``_idle_release_due`` correctly never releases on
+unknown. That is all deliberate and right. The trap is what it composes into: a
+consumer that withholds ``go2rtc_url`` (to avoid a duplicate registration that
+re-points the stream mid-flight) removes the ONLY viewer signal push mode has,
+so every push-mode camera is pinned to "unknown" and a battery camera's
+keepalive renews forever against a camera nobody is watching. Observed live: a
+sleeping battery L2 still being renewed every ~100 s.
+
+``go2rtc_register=False`` is the way out - keep the query, drop the
+registration. These tests pin the decision table so neither half can regress
+silently, since both failure modes are quiet ones.
+"""
+
+import asyncio
+import types
+
+import pytest
+
+from aidot_cameras.camera.protocol import _idle_release_due
+
+PUSH_URL = "rtsp://127.0.0.1:8554/aidot_cam1"     # go2rtc's shared RTSP port
+HTTP_SERVE = "http://127.0.0.1:18000/aidot_cam1"  # our own -listen socket
+
+
+def _client(go2rtc_url=None, keepalive_url=PUSH_URL, viewers=None, raises=False):
+    """A stand-in exposing exactly what ``_viewer_present`` touches.
+
+    Built by binding the real method onto a namespace rather than constructing a
+    CameraDeviceClient, which would need a device record, an account and a live
+    loop - none of which this decision depends on.
+    """
+    from aidot_cameras.camera.client import CameraMixin
+
+    obj = types.SimpleNamespace(
+        # Sentinel, not None: if the throttle ever short-circuits, the test
+        # returns "STALE" and fails loudly instead of passing vacuously
+        # because the cached value happened to match the expected answer.
+        _viewer_cache=(0.0, "STALE"),
+        _go2rtc_url=go2rtc_url,
+        _keepalive_rtsp_url=keepalive_url,
+        _go2rtc_stream_name=lambda: "aidot_cam1",
+        _sdes_serve_consumer_present=lambda port: True,  # the WRONG answer in push mode
+    )
+
+    async def _fake_count(self, name):
+        if raises:
+            raise RuntimeError("go2rtc unreachable")
+        return viewers
+
+    obj._viewer_present = CameraMixin._viewer_present.__get__(obj)
+    obj._fake_count = _fake_count
+    return obj
+
+
+def _ask(obj, monkeypatch, port=8554):
+    """Call _viewer_present with the go2rtc client stubbed out."""
+    from aidot_cameras.camera import client as client_mod
+
+    class _Stub:
+        def __init__(self, session, base):
+            pass
+
+        async def viewer_count(self, name):
+            return await obj._fake_count(obj, name)
+
+    class _Sess:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *a):
+            return False
+
+    import aidot_cameras.camera.go2rtc as g2
+    monkeypatch.setattr(g2, "Go2rtcClient", _Stub)
+    monkeypatch.setattr(client_mod, "_VIEWER_CHECK_INTERVAL_S", 0, raising=False)
+
+    import aiohttp
+    monkeypatch.setattr(aiohttp, "ClientSession", lambda *a, **k: _Sess())
+    return asyncio.run(obj._viewer_present(port))
+
+
+# --------------------------------------------------------------------------- #
+# push mode: the socket fallback must never be consulted
+# --------------------------------------------------------------------------- #
+
+def test_push_mode_without_go2rtc_is_unknown_not_a_confident_lie(monkeypatch):
+    """No go2rtc + push mode -> unknown.
+
+    The stub's socket check returns True; if it were ever consulted the answer
+    would be True, every camera would look watched, and nothing would release.
+    """
+    obj = _client(go2rtc_url=None)
+    assert _ask(obj, monkeypatch) is None
+
+
+def test_push_mode_falls_back_to_unknown_when_go2rtc_query_fails(monkeypatch):
+    """go2rtc configured but unreachable must NOT drop to the socket check.
+
+    This is the case the restructure fixed: previously the shared-port guard sat
+    behind `if not base`, so configuring go2rtc and having the query fail fell
+    straight through to the wrong check.
+    """
+    obj = _client(go2rtc_url="http://go2rtc:1984", raises=True)
+    assert _ask(obj, monkeypatch) is None
+
+
+def test_push_mode_falls_back_to_unknown_when_go2rtc_returns_none(monkeypatch):
+    obj = _client(go2rtc_url="http://go2rtc:1984", viewers=None)
+    assert _ask(obj, monkeypatch) is None
+
+
+# --------------------------------------------------------------------------- #
+# push mode WITH go2rtc: real answers, which is the whole point
+# --------------------------------------------------------------------------- #
+
+def test_push_mode_with_go2rtc_reports_a_real_viewer(monkeypatch):
+    obj = _client(go2rtc_url="http://go2rtc:1984", viewers=2)
+    assert _ask(obj, monkeypatch) is True
+
+
+def test_push_mode_with_go2rtc_reports_nobody_watching(monkeypatch):
+    """The answer that actually lets a battery camera release.
+
+    Without go2rtc this is unreachable in push mode - it answers unknown, and
+    unknown never releases.
+    """
+    obj = _client(go2rtc_url="http://go2rtc:1984", viewers=0)
+    assert _ask(obj, monkeypatch) is False
+
+
+# --------------------------------------------------------------------------- #
+# non-push (our own HTTP -listen serve): the socket check is legitimate there
+# --------------------------------------------------------------------------- #
+
+def test_http_serve_still_uses_the_socket_check(monkeypatch):
+    """On our own serve port the socket check is meaningful and must be kept."""
+    obj = _client(go2rtc_url=None, keepalive_url=HTTP_SERVE)
+    assert _ask(obj, monkeypatch) is True
+
+
+# --------------------------------------------------------------------------- #
+# the composition that caused the live bug
+# --------------------------------------------------------------------------- #
+
+@pytest.mark.parametrize("answer,expected_release", [
+    (True, False),    # someone watching -> hold
+    (None, False),    # unknown          -> hold (fail-safe)
+    (False, True),    # nobody watching  -> release
+])
+def test_only_a_definite_no_releases(answer, expected_release):
+    """`unknown` must never release - and therefore must never be the only answer.
+
+    Pinned here next to the push-mode tests because the live bug was not in
+    either half: `_viewer_present` answering unknown is right, and
+    `_idle_release_due` holding on unknown is right. The defect was that push
+    mode without go2rtc made unknown the *only reachable* answer, so "never
+    release" became unconditional.
+    """
+    assert _idle_release_due(answer, last_consumer=0.0, now=10_000.0,
+                             idle_secs=120.0) is expected_release
+
+
+# --------------------------------------------------------------------------- #
+# the registration seam
+# --------------------------------------------------------------------------- #
+
+def test_deregister_never_removes_a_stream_we_did_not_register():
+    """The dangerous half of the seam.
+
+    ``_deregister_go2rtc`` gates on ``_go2rtc_url`` alone. Before this seam
+    existed a query-only consumer withheld that URL, so deregistration was
+    unreachable by accident. Passing the URL for queries makes it reachable - and
+    it would then DELETE the stream the consumer registered itself, on every stop
+    and every idle-release, tearing down the thing it serves from.
+    """
+    from aidot_cameras.camera.client import CameraMixin
+
+    removed = []
+
+    class _Client:
+        def __init__(self, session, base):
+            pass
+
+        async def remove_stream(self, name):
+            removed.append(name)
+
+    class _Sess:
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *a):
+            return False
+
+    import aidot_cameras.camera.go2rtc as g2
+    import aiohttp
+    _orig_client, _orig_sess = g2.Go2rtcClient, aiohttp.ClientSession
+    g2.Go2rtcClient = _Client
+    aiohttp.ClientSession = lambda *a, **k: _Sess()
+    try:
+        for manages, expected in ((False, []), (True, ["aidot_cam1"])):
+            removed.clear()
+            obj = types.SimpleNamespace(
+                _go2rtc_url="http://go2rtc:1984",
+                _go2rtc_pull_url="x",
+                _go2rtc_manages_stream=manages,
+                _go2rtc_stream_name=lambda: "aidot_cam1",
+                device_id="cam1",
+            )
+            obj._deregister_go2rtc = CameraMixin._deregister_go2rtc.__get__(obj)
+            asyncio.run(obj._deregister_go2rtc())
+            assert removed == expected, (
+                f"manages={manages}: expected {expected}, got {removed}"
+            )
+            # The pull URL is cleared either way - it is ours regardless.
+            assert obj._go2rtc_pull_url is None
+    finally:
+        g2.Go2rtcClient, aiohttp.ClientSession = _orig_client, _orig_sess
+
+
+def test_start_keepalive_exposes_go2rtc_register():
+    import inspect
+
+    from aidot_cameras.camera.client import CameraMixin
+
+    params = inspect.signature(CameraMixin.start_keepalive).parameters
+    assert "go2rtc_register" in params
+    assert params["go2rtc_register"].default is True, (
+        "default must stay True so existing callers are unaffected"
+    )