python-aidot-cameras 0.7.16__tar.gz → 0.7.18__tar.gz

{python_aidot_cameras-0.7.16/src/python_aidot_cameras.egg-info → python_aidot_cameras-0.7.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.7.16
+Version: 0.7.18
 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.7.16 → python_aidot_cameras-0.7.18}/pyproject.toml

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

{python_aidot_cameras-0.7.16 → python_aidot_cameras-0.7.18}/src/aidot/camera/client.py

@@ -39,7 +39,7 @@ from .sdes import SdesSession  # re-exported (split into sdes.py)
 from .controls import _CameraControlsMixin
 from .protocol import (  # split into protocol.py; re-imported for use + back-compat
     _mqtt_timestamp,
-    next_backoff,
+    ReconnectPacer,
     _build_stun_binding_success_response,
     _terminal_webrtc_ack,
     _install_highport_nomination_patch,
@@ -55,6 +55,9 @@ from .protocol import (  # split into protocol.py; re-imported for use + back-co
     _save_sprop,
     _inject_sprop,
     _sdes_serve_port,
+    _ServeRelay,
+    _rewrite_serve_port,
+    _grab_free_port,
     _tcp_table_has_established_on_port,
     _idle_release_due,
     _dtls_av_mux_run,
@@ -502,6 +505,9 @@ class CameraMixin(_CameraControlsMixin):
         # camera.stream_source() can wait and hand HA a ready URL (avoids HA's
         # ~40s connection-refused retry gap on cold start).
         self._serve_ready: "asyncio.Event" = asyncio.Event()
+        # Cold-start serve-port relay (holds the public port connectable through
+        # the handshake so an eager go2rtc pull waits instead of being refused).
+        self._serve_relay: "Optional[_ServeRelay]" = None
         # Motion/event polling (cloud event list). NOTE: the camera does NOT push motion
         # to a passive MQTT subscriber - alarmType is only emitted during an active live
         # view (decompiled NewLiveFragment) - so real-time-ish motion for HA comes from
@@ -636,48 +642,67 @@ class CameraMixin(_CameraControlsMixin):
             "Content-Type":    "application/json",
         }
 
-    async def _async_http_wake(self) -> bool:
-        """Wake a battery camera via the cloud HTTP low-power endpoint.
+    def _owner_id(self) -> str:
+        """The Leedarson ``owner`` (userId) header value some IPC endpoints require.
 
-        Mirrors DeviceWakeUpRepos.j() in the official app (n.java): POST
-        ``{smarthome}/api/ipc/devices/{id}/lowPowerActiveState`` with body
-        ``{"deviceId": id, "status": "wakeup"}`` and owner+token headers.  The
-        cloud forwards the wake to the camera's always-on low-power channel, so it
-        reaches a deeply-sleeping camera that has dropped its MQTT session - unlike
-        the MQTT ``lowPowerActiveStateReq``, which only lands if the camera is
-        already connected.  Returns True if the request was accepted (HTTP 200).
+        ``_leedarson_headers`` deliberately omits ``owner`` (it breaks
+        recording/playback); the wake and liveStreamParam endpoints need it.
         """
-        import aiohttp
-
-        headers = self._leedarson_headers()
-        # The wake endpoint (unlike recording/playback) DOES require owner - the app
-        # sends it (n.java:71).  owner is the Leedarson userId.
-        headers["owner"] = (
+        return (
             self._user_info.get("owner")
             or self._user_info.get("id")
             or self._user_info.get("userId")
             or str(self.user_id)
         )
-        url = (f"{self._smarthome_base}/api/ipc/devices/"
-               f"{self.device_id}/lowPowerActiveState")
-        body = {"deviceId": self.device_id, "status": "wakeup"}
+
+    async def _async_post_ok(
+        self, url: str, headers: dict, body: str, *, timeout: float = 10.0,
+        label: str = "ipc post",
+    ) -> bool:
+        """POST a JSON ``body`` string to a Leedarson IPC endpoint; True on success.
+
+        Success = HTTP 200 with a ``code`` of 0/200/absent. Best-effort: any
+        network/parse error returns False, never raises. Shared by the wake and
+        liveStreamParam provisioning calls.
+        """
+        import aiohttp
+
         try:
             async with aiohttp.ClientSession() as session:
                 async with session.post(
-                    url, headers=headers, json=body,
-                    timeout=aiohttp.ClientTimeout(total=10),
+                    url, headers=headers, data=body,
+                    timeout=aiohttp.ClientTimeout(total=timeout),
                 ) as resp:
                     status = resp.status
                     data = await resp.json(content_type=None)
             code = data.get("code") if isinstance(data, dict) else None
             ok = status == 200 and (code in (None, 0, 200, "0", "200"))
-            _LOGGER.debug("http wake %s: status=%s code=%s ok=%s",
-                          self.device_id, status, code, ok)
+            _LOGGER.debug("%s %s: status=%s code=%s ok=%s",
+                          label, self.device_id, status, code, ok)
             return bool(ok)
         except Exception as exc:
-            _LOGGER.debug("http wake failed for %s: %s", self.device_id, exc)
+            _LOGGER.debug("%s failed for %s: %s", label, self.device_id, exc)
             return False
 
+    async def _async_http_wake(self) -> bool:
+        """Wake a battery camera via the cloud HTTP low-power endpoint.
+
+        Mirrors DeviceWakeUpRepos.j() in the official app (n.java): POST
+        ``{smarthome}/api/ipc/devices/{id}/lowPowerActiveState`` with body
+        ``{"deviceId": id, "status": "wakeup"}`` and owner+token headers.  The
+        cloud forwards the wake to the camera's always-on low-power channel, so it
+        reaches a deeply-sleeping camera that has dropped its MQTT session - unlike
+        the MQTT ``lowPowerActiveStateReq``, which only lands if the camera is
+        already connected.  Returns True if the request was accepted (HTTP 200).
+        """
+        # The wake endpoint (unlike recording/playback) DOES require owner (n.java:71).
+        headers = self._leedarson_headers()
+        headers["owner"] = self._owner_id()
+        url = (f"{self._smarthome_base}/api/ipc/devices/"
+               f"{self.device_id}/lowPowerActiveState")
+        body = json.dumps({"deviceId": self.device_id, "status": "wakeup"})
+        return await self._async_post_ok(url, headers, body, label="http wake")
+
     def _live_stream_param_request(self):
         """Build ``(url, headers, body)`` for the liveStreamParam provision call.
 
@@ -686,12 +711,7 @@ class CameraMixin(_CameraControlsMixin):
         ``owner`` header is required (as on the wake endpoint).
         """
         headers = self._leedarson_headers()
-        headers["owner"] = (
-            self._user_info.get("owner")
-            or self._user_info.get("id")
-            or self._user_info.get("userId")
-            or str(self.user_id)
-        )
+        headers["owner"] = self._owner_id()
         url = f"{self._smarthome_base}/api/ipc/liveStream/liveStreamParam"
         return url, headers, json.dumps([self.device_id])
 
@@ -706,31 +726,10 @@ class CameraMixin(_CameraControlsMixin):
         provisions the session (and brings the camera online) and returns AWS KVS
         credentials.  We only need the provisioning side effect - the library
         streams over the proprietary MQTT/SDES path, not AWS KVS - so the returned
-        credentials are ignored.
-
-        The request body is a JSON **array** of device ids (an object body returns
-        HTTP 500) and needs the ``owner`` header (like the wake endpoint).
-        Best-effort: returns True on HTTP 200, never raises.
+        credentials are ignored.  Best-effort: returns True on HTTP 200.
         """
-        import aiohttp
-
         url, headers, body = self._live_stream_param_request()
-        try:
-            async with aiohttp.ClientSession() as session:
-                async with session.post(
-                    url, headers=headers, data=body,
-                    timeout=aiohttp.ClientTimeout(total=10),
-                ) as resp:
-                    status = resp.status
-                    data = await resp.json(content_type=None)
-            code = data.get("code") if isinstance(data, dict) else None
-            ok = status == 200 and (code in (None, 0, 200, "0", "200"))
-            _LOGGER.debug("liveStreamParam %s: status=%s code=%s ok=%s",
-                          self.device_id, status, code, ok)
-            return bool(ok)
-        except Exception as exc:
-            _LOGGER.debug("liveStreamParam failed for %s: %s", self.device_id, exc)
-            return False
+        return await self._async_post_ok(url, headers, body, label="liveStreamParam")
 
     async def async_wake_camera(self, retries: int = 2) -> bool:
         """Wake a battery camera on demand via the cloud HTTP low-power endpoint.
@@ -1945,6 +1944,8 @@ class CameraMixin(_CameraControlsMixin):
         fast_connect: Optional[bool] = None,
         sdes_audio: Optional[bool] = None,
         go2rtc_url: Optional[str] = None,
+        live_stream_param: Optional[bool] = None,
+        serve_relay: Optional[bool] = None,
     ) -> None:
         """Start a persistent stream that keeps the camera session alive.
 
@@ -1962,12 +1963,27 @@ class CameraMixin(_CameraControlsMixin):
         to the ``AIDOT_FAST_CONNECT`` env var; ``True``/``False`` override it (e.g.
         from a Home Assistant config-entry option, since HA OS can't set env vars).
 
+        ``live_stream_param`` toggles the battery-camera cloud pre-connect
+        (liveStreamParam); like ``fast_connect`` it overrides the
+        ``AIDOT_LIVESTREAM_PARAM`` env var, so an integration on HA OS (no env vars)
+        can still disable it per camera.
+
+        ``serve_relay`` toggles the cold-start serve-port relay (holds the public
+        serve port connectable through the WebRTC handshake so an eager go2rtc
+        pull waits instead of getting connection-refused).  Overrides the
+        ``AIDOT_SERVE_RELAY`` env var (default on); set False to serve ffmpeg
+        directly on the public port (the pre-0.7.18 behaviour).
+
         Safe to call multiple times - does nothing if already running.
         """
         if fast_connect is not None:
             self._fast_connect_opt = fast_connect
         if sdes_audio is not None:
             self._sdes_audio_opt = sdes_audio
+        if live_stream_param is not None:
+            self._live_stream_param_opt = live_stream_param
+        if serve_relay is not None:
+            self._serve_relay_opt = serve_relay
         if self._stream_task is not None and not self._stream_task.done():
             return
         self._keepalive_rtsp_url = rtsp_push_url
@@ -2153,16 +2169,35 @@ class CameraMixin(_CameraControlsMixin):
         return found if read_any else None
 
     async def _sdes_keepalive_loop(self) -> None:
+        """Keep the cold-start serve relay alive around the SDES keepalive loop.
+
+        The relay holds the public serve port connectable through every (re)open
+        so an eager go2rtc pull waits instead of getting connection-refused while
+        the SDES handshake runs (the same race fixed for the DTLS serve)."""
+        self._serve_relay = self._maybe_start_serve_relay(self._keepalive_rtsp_url)
+        try:
+            await self._sdes_keepalive_loop_inner()
+        finally:
+            _relay = self._serve_relay
+            self._serve_relay = None
+            if _relay is not None:
+                _relay.close()
+
+    async def _sdes_keepalive_loop_inner(self) -> None:
         """Background task: keep SDES stream alive; push to go2rtc via RTSP."""
         _MIN_DELAY = 10.0
         _MAX_DELAY = 300.0
-        # Consecutive failed / no-media opens; drives jittered exponential
-        # backoff so a degraded camera (or a fleet reconnecting at once) isn't
-        # hammered into further degradation / cloud rate-limiting. Reset only
-        # after a session that actually delivered media (see end of loop).
-        _attempt = 0
+        # Jittered-backoff pacer: escalates on failed/no-media opens so a degraded
+        # camera (or a fleet reconnecting at once) isn't hammered into further
+        # degradation / cloud rate-limiting; resets after a session that delivered
+        # media (see end of loop).
+        _pacer = ReconnectPacer(_MIN_DELAY, _MAX_DELAY)
 
         while self._streaming_active:
+            if self._serve_relay is not None:
+                # Clear any stale backend from a prior session; the open below
+                # points the relay at this session's fresh internal ffmpeg port.
+                self._serve_relay.set_backend(None)
             try:
                 session = await self.async_open_webrtc_stream(
                     rtsp_push_url=self._keepalive_rtsp_url,
@@ -2171,7 +2206,7 @@ class CameraMixin(_CameraControlsMixin):
             except asyncio.CancelledError:
                 return
             except Exception as exc:
-                _delay = next_backoff(_attempt, base=_MIN_DELAY, cap=_MAX_DELAY)
+                _delay = _pacer.fail_delay()
                 _LOGGER.warning(
                     "SDES keepalive: stream open failed for %s (retry in %.0fs): %s",
                     self.device_id, _delay, exc,
@@ -2180,7 +2215,6 @@ class CameraMixin(_CameraControlsMixin):
                     await asyncio.sleep(_delay)
                 except asyncio.CancelledError:
                     return
-                _attempt += 1
                 continue
 
             self._stream_session = session
@@ -2270,16 +2304,10 @@ class CameraMixin(_CameraControlsMixin):
                 # Escalate backoff only when the session never delivered media
                 # (camera refused / degraded on a rapid reconnect); a session
                 # that streamed fine and then ended (battery teardown, consumer
-                # gone) is a normal lifecycle event and resets to the base
-                # interval so the next view reconnects promptly.
-                if session.last_media_monotonic > 0.0:
-                    _attempt = 0
-                    _delay = _MIN_DELAY
-                else:
-                    _attempt += 1
-                    _delay = next_backoff(_attempt, base=_MIN_DELAY, cap=_MAX_DELAY)
+                # gone) is a normal lifecycle event and resets to the base interval.
+                _healthy = session.last_media_monotonic > 0.0
                 try:
-                    await asyncio.sleep(_delay)
+                    await asyncio.sleep(_pacer.session_end_delay(healthy=_healthy))
                 except asyncio.CancelledError:
                     return
 
@@ -2295,9 +2323,9 @@ class CameraMixin(_CameraControlsMixin):
         # to 15 s here (+ the SDES/serve loops) if strict app parity is wanted.
         _MIN_DELAY = 5.0
         _MAX_DELAY = 300.0
-        # Consecutive failed / frameless opens; drives jittered backoff (see
-        # next_backoff). Reset after a session that produced frames.
-        _attempt = 0
+        # Jittered-backoff pacer: escalates on failed/frameless opens, resets after
+        # a session that produced frames.
+        _pacer = ReconnectPacer(_MIN_DELAY, _MAX_DELAY)
 
         def _on_frame(frame) -> None:
             # Accept keyframes always; accept P-frames only after first keyframe.
@@ -2339,7 +2367,7 @@ class CameraMixin(_CameraControlsMixin):
                     return
                 continue
             except Exception as exc:
-                _delay = next_backoff(_attempt, base=_MIN_DELAY, cap=_MAX_DELAY)
+                _delay = _pacer.fail_delay()
                 _LOGGER.warning(
                     "Stream open failed for %s (retry in %.0fs): %s",
                     self.device_id, _delay, exc,
@@ -2348,7 +2376,6 @@ class CameraMixin(_CameraControlsMixin):
                     await asyncio.sleep(_delay)
                 except asyncio.CancelledError:
                     return
-                _attempt += 1
                 continue
 
             self._stream_session = session
@@ -2378,14 +2405,9 @@ class CameraMixin(_CameraControlsMixin):
                 # Reset backoff if this session produced frames (a normal drop
                 # after good streaming); escalate with jitter if it never did
                 # (the camera-degradation case).
-                if self._last_frame_time > _open_time:
-                    _attempt = 0
-                    _delay = _MIN_DELAY
-                else:
-                    _attempt += 1
-                    _delay = next_backoff(_attempt, base=_MIN_DELAY, cap=_MAX_DELAY)
+                _produced = self._last_frame_time > _open_time
                 try:
-                    await asyncio.sleep(_delay)
+                    await asyncio.sleep(_pacer.session_end_delay(healthy=_produced))
                 except asyncio.CancelledError:
                     return
 
@@ -2458,6 +2480,38 @@ class CameraMixin(_CameraControlsMixin):
                 got_a = self._install_encoded_tap(_r, aq, False)
         return got_v
 
+    def _maybe_start_serve_relay(self, serve_url: Optional[str]) -> "Optional[_ServeRelay]":
+        """Hold the public serve port via a _ServeRelay so an eager go2rtc pull
+        connects-and-waits instead of hitting ECONNREFUSED during the ~16-25s
+        cold handshake (ffmpeg only binds its -listen socket after input frames).
+
+        Returns the started relay, or None when disabled / not an http serve /
+        the bind fails - in which case the caller serves ffmpeg directly on the
+        public port (the pre-relay behaviour, so a bind clash never breaks
+        streaming)."""
+        if not (serve_url and serve_url.startswith("http")):
+            return None
+        opt = getattr(self, "_serve_relay_opt", None)
+        if opt is None:
+            opt = os.environ.get("AIDOT_SERVE_RELAY", "1") != "0"
+        if not opt:
+            return None
+        port = _sdes_serve_port(serve_url)
+        if port is None:
+            return None
+        relay = _ServeRelay(port)
+        try:
+            relay.start()
+        except OSError as exc:
+            _LOGGER.warning(
+                "serve relay: bind :%s failed (%s) - serving ffmpeg directly",
+                port, exc,
+            )
+            return None
+        _LOGGER.debug(
+            "serve relay: holding public port :%s for %s", port, self.device_id)
+        return relay
+
     async def _dtls_serve_loop(self) -> None:
         """Acquire a concurrent-stream slot, then run the serve loop.
 
@@ -2472,9 +2526,14 @@ class CameraMixin(_CameraControlsMixin):
                 self.device_id,
             )
         await slots.acquire()
+        self._serve_relay = self._maybe_start_serve_relay(self._keepalive_rtsp_url)
         try:
             await self._dtls_serve_loop_inner()
         finally:
+            _relay = self._serve_relay
+            self._serve_relay = None
+            if _relay is not None:
+                _relay.close()
             slots.release()
 
     async def _dtls_serve_loop_inner(self) -> None:
@@ -2501,7 +2560,11 @@ class CameraMixin(_CameraControlsMixin):
         # attempts so no code path (reset bug, fast PC-death) can pound the camera.
         _MIN_DELAY, _MAX_DELAY = 15.0, 300.0
         _open_gate = float(os.environ.get("AIDOT_DTLS_RETRY_GATE_S", "15"))
-        _attempt = 0  # consecutive failed opens; drives jittered backoff
+        # Jittered-backoff pacer for failed opens. Unlike the SDES/JPEG loops this
+        # serve loop resets on any successful open (it has the _open_gate spacing
+        # below) rather than escalating on no-media - hence reset() not
+        # session_end_delay().
+        _pacer = ReconnectPacer(_MIN_DELAY, _MAX_DELAY)
         _last_open_at = 0.0  # monotonic of the previous open attempt (0 = none yet)
         loop = asyncio.get_running_loop()
         while self._streaming_active:
@@ -2537,7 +2600,7 @@ class CameraMixin(_CameraControlsMixin):
                     return
                 continue
             except Exception as exc:
-                _delay = next_backoff(_attempt, base=_MIN_DELAY, cap=_MAX_DELAY)
+                _delay = _pacer.fail_delay()
                 _LOGGER.warning(
                     "DTLS serve: open failed for %s (retry %.0fs): %s",
                     self.device_id, _delay, exc,
@@ -2546,10 +2609,9 @@ class CameraMixin(_CameraControlsMixin):
                     await asyncio.sleep(_delay)
                 except asyncio.CancelledError:
                     return
-                _attempt += 1
                 continue
 
-            _attempt = 0
+            _pacer.reset()
             self._stream_session = session
             pc = session._pc
             # PC-dead test for the serve loop.  closed/failed are terminal at
@@ -2599,12 +2661,24 @@ class CameraMixin(_CameraControlsMixin):
                         except _queue.Empty:
                             pass
                     await self._send_video_pli(pc)  # request a clean keyframe
+                    # With the relay holding the public port, ffmpeg listens on a
+                    # fresh internal port each cycle and the relay splices to it;
+                    # without it, ffmpeg owns the public port directly (old path).
+                    _relay = self._serve_relay
+                    if _relay is not None:
+                        _ff_port = _grab_free_port()
+                        _ff_url = _rewrite_serve_port(serve_url, _ff_port)
+                    else:
+                        _ff_port = None
+                        _ff_url = serve_url
                     rfd, wfd = os.pipe()
-                    proc = await self._spawn_dtls_serve_ffmpeg(serve_url, rfd)
+                    proc = await self._spawn_dtls_serve_ffmpeg(_ff_url, rfd)
                     os.close(rfd)
                     if proc is None:
                         os.close(wfd)
                         break
+                    if _relay is not None:
+                        _relay.set_backend(_ff_port)
                     wfile = os.fdopen(wfd, "wb", buffering=0)
                     progress = [loop.time()]
                     stop_flag = _threading.Event()
@@ -2661,6 +2735,8 @@ class CameraMixin(_CameraControlsMixin):
                     wfile = None
                     mux_thread.join(timeout=2.0)
                     mux_thread = stop_flag = None
+                    if _relay is not None:
+                        _relay.set_backend(None)  # no backend until next ffmpeg
                     _terminate_proc(proc)
                     proc = None
                     if idle_release:
@@ -3167,12 +3243,15 @@ class CameraMixin(_CameraControlsMixin):
         # -50019 ("not ready") and never runs ICE -> no media.  App parity:
         # KVSPreConnectStrategy.fetchKvsParams calls liveStreamParam first.  We
         # only need the provisioning side effect (we stream over MQTT/SDES, not
-        # AWS KVS).  Mains cameras are always stream-ready, so skip them.  Disable
-        # via AIDOT_LIVESTREAM_PARAM=0.  Validated live on L2_170 (A001513): with
-        # this call livePlay succeeds and decrypted RTP flows; without it,
-        # persistent -50019.
-        if (self.is_battery_camera
-                and os.environ.get("AIDOT_LIVESTREAM_PARAM", "1") != "0"):
+        # AWS KVS).  Mains cameras are always stream-ready, so skip them.
+        # Validated live on L2_170 (A001513): with this call livePlay succeeds and
+        # decrypted RTP flows; without it, persistent -50019.  Controllable like
+        # fast_connect/sdes_audio: start_keepalive(live_stream_param=...) wins,
+        # else the AIDOT_LIVESTREAM_PARAM env var (default on).
+        _lsp = getattr(self, "_live_stream_param_opt", None)
+        if _lsp is None:
+            _lsp = os.environ.get("AIDOT_LIVESTREAM_PARAM", "1") != "0"
+        if self.is_battery_camera and _lsp:
             _lsp_ok = await self._async_fetch_live_stream_param()
             _LOGGER.debug("camera %s: liveStreamParam provisioned ok=%s",
                           self.device_id, _lsp_ok)
@@ -9428,6 +9507,16 @@ class CameraMixin(_CameraControlsMixin):
             )
 
         if rtsp_push_url and rtsp_push_url.startswith("http"):
+            # Cold-start relay: when the keepalive loop is holding the public
+            # serve port, point ffmpeg at a fresh internal port and let the relay
+            # splice the public port to it - so an early go2rtc pull waits through
+            # this handshake instead of being refused.  set_backend retries the
+            # dial until ffmpeg's -listen socket binds (only after input frames).
+            _relay = getattr(self, "_serve_relay", None)
+            if _relay is not None:
+                _ff_port = _grab_free_port()
+                rtsp_push_url = _rewrite_serve_port(rtsp_push_url, _ff_port)
+                _relay.set_backend(_ff_port)
             # PULL model: SERVE the decrypted stream over an HTTP-listen socket so
             # go2rtc / HA's stream integration pull it the standard way
             # (streams.add) - no go2rtc pre-registration needed.  ffmpeg -listen 1

{python_aidot_cameras-0.7.16 → python_aidot_cameras-0.7.18}/src/aidot/camera/protocol.py

@@ -12,6 +12,8 @@ import json
 import logging
 import os
 import random
+import select
+import socket
 import struct
 import tempfile
 import threading
@@ -429,6 +431,46 @@ def next_backoff(
     return base + rand() * (ceiling - base)
 
 
+class ReconnectPacer:
+    """Reconnect-delay state machine shared by the camera reconnect loops.
+
+    Centralizes the attempt counter, the jittered-backoff math (:func:`next_backoff`),
+    and the escalate-on-failure / reset-on-healthy policy + increment ordering that
+    the SDES keepalive, JPEG streaming, and DTLS serve loops would otherwise each
+    re-implement.  Each loop keeps only its own liveness signal and feeds it in, so
+    a loop's policy (does it escalate on no-media, or just reset on open?) is an
+    explicit method call rather than hidden in copy-pasted counter bookkeeping.
+    Not thread-safe; one instance per loop scope.
+    """
+
+    def __init__(
+        self, base: float, cap: float,
+        *, rand: Optional[Callable[[], float]] = None,
+    ) -> None:
+        self._base = base
+        self._cap = cap
+        self._rand = rand  # forwarded to next_backoff; injectable for tests
+        self._attempt = 0
+
+    def fail_delay(self) -> float:
+        """Delay after a failed OPEN (no session established): the current attempt's
+        backoff, then escalate - so the first failure waits exactly ``base``."""
+        delay = next_backoff(self._attempt, base=self._base, cap=self._cap, rand=self._rand)
+        self._attempt += 1
+        return delay
+
+    def session_end_delay(self, *, healthy: bool) -> float:
+        """Delay after a session ENDED: reset to ``base`` if it delivered media
+        (``healthy``), else escalate first, then return the delay."""
+        self._attempt = 0 if healthy else self._attempt + 1
+        return next_backoff(self._attempt, base=self._base, cap=self._cap, rand=self._rand)
+
+    def reset(self) -> None:
+        """Clear the failure count - e.g. after a successful open in a loop that has
+        no end-of-session escalation (the DTLS serve loop, gated by its own spacing)."""
+        self._attempt = 0
+
+
 def _write_text_file(path: str, text: str) -> None:
     """Write ``text`` to ``path`` synchronously.
 
@@ -572,6 +614,187 @@ def _sdes_serve_port(url: "Optional[str]") -> "Optional[int]":
         return None
 
 
+class _ServeRelay:
+    """Keep a public TCP serve port continuously connectable while the real
+    server (ffmpeg ``-listen 1``) comes and goes on an internal port.
+
+    Why this exists: the library advertises the public serve port to go2rtc / HA
+    the moment a view starts, but ffmpeg only binds its ``-listen`` socket AFTER
+    the ~16-25 s WebRTC handshake delivers the first frames - ffmpeg probes its
+    input before it opens any output (verified empirically: ``ffmpeg -i pipe:0
+    ... -f mpegts -listen 1`` does not bind the port until input data flows).  An
+    eager pull therefore hits ``ECONNREFUSED`` and go2rtc gives up within
+    ~200 ms, so the camera card stays blank on the first (cold) view.
+
+    This relay binds the public port up front and holds it for the whole
+    streaming session.  An early pull CONNECTS and waits; the relay keeps
+    redialing the current internal ffmpeg port (set via :meth:`set_backend`) and,
+    once ffmpeg is listening, splices bytes both ways.  The public listener
+    survives ffmpeg restarts (go2rtc reconnects), so the consumer never sees a
+    refused connection mid-session.
+    """
+
+    def __init__(self, public_port: int, *, host: str = "127.0.0.1",
+                 dial_timeout: float = 90.0, dial_interval: float = 0.1) -> None:
+        self._public_port = public_port
+        self._host = host
+        self._dial_timeout = dial_timeout
+        self._dial_interval = dial_interval
+        self._backend_port: "Optional[int]" = None
+        self._listen: "Optional[socket.socket]" = None
+        self._accept_thread: "Optional[threading.Thread]" = None
+        self._conns: "set[socket.socket]" = set()
+        self._lock = threading.Lock()
+        self._closed = threading.Event()
+
+    @property
+    def port(self) -> int:
+        """The bound public port (resolved after :meth:`start` if 0 was passed)."""
+        return self._public_port
+
+    def start(self) -> None:
+        """Bind the public port and begin accepting.  Raises OSError on bind."""
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        s.bind((self._host, self._public_port))
+        s.listen(8)
+        s.settimeout(0.5)
+        self._public_port = s.getsockname()[1]
+        self._listen = s
+        self._accept_thread = threading.Thread(
+            target=self._accept_loop,
+            name=f"serve-relay-{self._public_port}",
+            daemon=True,
+        )
+        self._accept_thread.start()
+
+    def set_backend(self, port: "Optional[int]") -> None:
+        """Point the relay at the current internal ffmpeg port (None = no backend
+        running yet; connected pulls wait for the next backend)."""
+        with self._lock:
+            self._backend_port = port
+
+    def close(self) -> None:
+        """Tear down the listener, the accept thread, and any live connections."""
+        self._closed.set()
+        try:
+            if self._listen is not None:
+                self._listen.close()
+        except OSError:
+            pass
+        with self._lock:
+            conns = list(self._conns)
+            self._conns.clear()
+        for s in conns:
+            try:
+                s.close()
+            except OSError:
+                pass
+        t = self._accept_thread
+        if t is not None:
+            t.join(timeout=2.0)
+
+    def _accept_loop(self) -> None:
+        while not self._closed.is_set():
+            try:
+                cli, _ = self._listen.accept()  # type: ignore[union-attr]
+            except TimeoutError:
+                continue
+            except OSError:
+                break
+            threading.Thread(
+                target=self._handle, args=(cli,), daemon=True
+            ).start()
+
+    def _handle(self, cli: "socket.socket") -> None:
+        with self._lock:
+            self._conns.add(cli)
+        be: "Optional[socket.socket]" = None
+        try:
+            be = self._dial_backend()
+            if be is not None:
+                self._splice(cli, be)
+        finally:
+            for s in (cli, be):
+                if s is not None:
+                    try:
+                        s.close()
+                    except OSError:
+                        pass
+            with self._lock:
+                self._conns.discard(cli)
+
+    def _dial_backend(self) -> "Optional[socket.socket]":
+        """Block until the backend is set + connectable (or timeout / close)."""
+        deadline = time.monotonic() + self._dial_timeout
+        while not self._closed.is_set() and time.monotonic() < deadline:
+            with self._lock:
+                port = self._backend_port
+            if port:
+                try:
+                    return socket.create_connection(
+                        (self._host, port), timeout=2.0)
+                except OSError:
+                    pass
+            time.sleep(self._dial_interval)
+        return None
+
+    def _splice(self, a: "socket.socket", b: "socket.socket") -> None:
+        a.setblocking(True)
+        b.setblocking(True)
+        socks = [a, b]
+        while not self._closed.is_set():
+            try:
+                r, _, x = select.select(socks, [], socks, 1.0)
+            except (OSError, ValueError):
+                return
+            if x:
+                return
+            for s in r:
+                peer = b if s is a else a
+                try:
+                    data = s.recv(65536)
+                except OSError:
+                    return
+                if not data:
+                    return
+                try:
+                    peer.sendall(data)
+                except OSError:
+                    return
+
+
+def _rewrite_serve_port(url: "Optional[str]", new_port: int) -> "Optional[str]":
+    """Return ``url`` with its host port replaced by ``new_port``.
+
+    Used to point ffmpeg at an internal _ServeRelay backend port while the public
+    port (in the advertised URL) is held by the relay.  ``http://127.0.0.1:18989/
+    x.ts`` -> ``http://127.0.0.1:<new_port>/x.ts``.  Pure (unit-testable)."""
+    if not url:
+        return url
+    try:
+        scheme, rest = url.split("://", 1)
+        hostport, slash, path = rest.partition("/")
+        host = hostport.rsplit(":", 1)[0]
+        return f"{scheme}://{host}:{new_port}{slash}{path}"
+    except (ValueError, IndexError):
+        return url
+
+
+def _grab_free_port(host: str = "127.0.0.1") -> int:
+    """Bind an ephemeral TCP port, release it, and return the number.
+
+    There's an inherent TOCTOU window before ffmpeg rebinds it, but it's a
+    loopback-only internal port and ffmpeg's launch retries the serve cycle on
+    failure, so a lost race is self-healing."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        s.bind((host, 0))
+        return s.getsockname()[1]
+    finally:
+        s.close()
+
+
 def _tcp_table_has_established_on_port(table_text: str, port: int) -> bool:
     """True if any row in a /proc/net/tcp[6] dump is ESTABLISHED on local ``port``.
 

{python_aidot_cameras-0.7.16 → python_aidot_cameras-0.7.18/src/python_aidot_cameras.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 0.7.16
+Version: 0.7.18
 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.7.16 → python_aidot_cameras-0.7.18}/src/python_aidot_cameras.egg-info/SOURCES.txt

@@ -47,6 +47,7 @@ tests/test_sdes_idle_release.py
 tests/test_sdes_sprop.py
 tests/test_sdes_talk.py
 tests/test_sdes_watchdog.py
+tests/test_serve_relay.py
 tests/test_speak.py
 tests/test_stream_cap.py
 tests/test_talk.py

{python_aidot_cameras-0.7.16 → python_aidot_cameras-0.7.18}/tests/test_backoff.py

@@ -10,7 +10,7 @@ import sys
 
 sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "src"))
 
-from aidot.camera.protocol import next_backoff
+from aidot.camera.protocol import ReconnectPacer, next_backoff
 
 _BASE = 10.0
 _CAP = 300.0
@@ -69,6 +69,46 @@ def test_negative_attempt_treated_as_zero():
     assert next_backoff(-3, base=_BASE, cap=_CAP, rand=_lo) == _BASE
 
 
+# --- ReconnectPacer: the escalate/reset policy shared by the reconnect loops --- #
+
+def test_pacer_first_fail_is_base_then_escalates():
+    # fail_delay uses the current attempt then increments: first failure == base,
+    # subsequent failures climb the ceiling (rand=_hi gives the ceiling).
+    p = ReconnectPacer(_BASE, _CAP, rand=_hi)
+    assert p.fail_delay() == _BASE          # attempt 0
+    assert p.fail_delay() == 2 * _BASE      # attempt 1 ceiling
+    assert p.fail_delay() == 4 * _BASE      # attempt 2 ceiling
+
+
+def test_pacer_session_end_healthy_resets_to_base():
+    p = ReconnectPacer(_BASE, _CAP, rand=_hi)
+    p.fail_delay(); p.fail_delay()          # climb to attempt 2
+    assert p.session_end_delay(healthy=True) == _BASE   # reset
+    assert p.session_end_delay(healthy=True) == _BASE   # stays at base
+
+
+def test_pacer_session_end_unhealthy_escalates_then_resets():
+    # session_end escalates first, then computes: from attempt 0, no-media -> attempt 1.
+    p = ReconnectPacer(_BASE, _CAP, rand=_hi)
+    assert p.session_end_delay(healthy=False) == 2 * _BASE   # attempt 1 ceiling
+    assert p.session_end_delay(healthy=False) == 4 * _BASE   # attempt 2 ceiling
+    assert p.session_end_delay(healthy=True) == _BASE        # healthy resets
+
+
+def test_pacer_reset_clears_failures():
+    p = ReconnectPacer(_BASE, _CAP, rand=_hi)
+    p.fail_delay(); p.fail_delay(); p.fail_delay()
+    p.reset()
+    assert p.fail_delay() == _BASE          # back to attempt 0
+
+
+def test_pacer_delays_within_bounds_real_rng():
+    p = ReconnectPacer(_BASE, _CAP)
+    for _ in range(20):
+        d = p.fail_delay()
+        assert _BASE <= d <= _CAP
+
+
 if __name__ == "__main__":
     import traceback
     _fail = 0

python_aidot_cameras-0.7.18/tests/test_serve_relay.py

@@ -0,0 +1,179 @@
+"""Unit tests for _ServeRelay - the cold-start port holder.
+
+The relay keeps a public serve port connectable while ffmpeg (the real
+-listen backend) is not up yet, so an eager go2rtc pull CONNECTS and waits
+instead of getting ECONNREFUSED and giving up.  These tests use real localhost
+sockets with ephemeral ports - no camera, no ffmpeg, fully deterministic.
+"""
+import os
+import socket
+import sys
+import threading
+import time
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "src"))
+
+from aidot.camera.protocol import _ServeRelay, _grab_free_port, _rewrite_serve_port
+
+
+def test_rewrite_serve_port_swaps_only_the_port():
+    assert (_rewrite_serve_port("http://127.0.0.1:18989/abc.ts", 40001)
+            == "http://127.0.0.1:40001/abc.ts")
+    # Path and scheme preserved; host preserved.
+    assert (_rewrite_serve_port("http://127.0.0.1:8554/aidot_x", 9)
+            == "http://127.0.0.1:9/aidot_x")
+
+
+def test_rewrite_serve_port_handles_missing_or_malformed():
+    assert _rewrite_serve_port(None, 1) is None
+    assert _rewrite_serve_port("not a url", 1) == "not a url"
+
+
+def test_grab_free_port_returns_a_bindable_port():
+    p = _grab_free_port()
+    assert isinstance(p, int) and 1024 < p < 65536
+
+
+def _free_port():
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.bind(("127.0.0.1", 0))
+    p = s.getsockname()[1]
+    s.close()
+    return p
+
+
+class _EchoBackend:
+    """A tiny one-shot -listen-style backend: accepts one client and echoes,
+    optionally prefixing a tag so tests can tell backends apart."""
+
+    def __init__(self, tag=b""):
+        self._tag = tag
+        self._srv = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._srv.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        self._srv.bind(("127.0.0.1", 0))
+        self._srv.listen(1)
+        self.port = self._srv.getsockname()[1]
+        self._t = threading.Thread(target=self._run, daemon=True)
+        self._t.start()
+
+    def _run(self):
+        try:
+            cli, _ = self._srv.accept()
+        except OSError:
+            return
+        try:
+            cli.sendall(self._tag)
+            while True:
+                d = cli.recv(4096)
+                if not d:
+                    break
+                cli.sendall(d)
+        except OSError:
+            pass
+        finally:
+            cli.close()
+
+    def close(self):
+        try:
+            self._srv.close()
+        except OSError:
+            pass
+
+
+def test_connect_before_backend_does_not_refuse_then_flows():
+    # The core guarantee: a pull that arrives BEFORE the backend exists connects
+    # (no ECONNREFUSED) and gets data once the backend appears.
+    relay = _ServeRelay(_free_port(), dial_timeout=10.0)
+    relay.start()
+    try:
+        cli = socket.create_connection(("127.0.0.1", relay.port), timeout=2.0)
+        # Backend comes up ~now, after the client already connected.
+        be = _EchoBackend()
+        relay.set_backend(be.port)
+        cli.sendall(b"GET /x.ts HTTP/1.0\r\n\r\n")
+        cli.settimeout(5.0)
+        got = cli.recv(4096)
+        assert b"GET /x.ts" in got
+        cli.close()
+        be.close()
+    finally:
+        relay.close()
+
+
+def test_without_relay_connection_is_refused():
+    # Control: this is the bug the relay fixes - an unbound port refuses fast.
+    port = _free_port()
+    try:
+        socket.create_connection(("127.0.0.1", port), timeout=1.0)
+        assert False, "expected ConnectionRefusedError on an unbound port"
+    except ConnectionRefusedError:
+        pass
+
+
+def test_backend_swap_between_connections():
+    # After ffmpeg restarts (go2rtc reconnect) the relay redials the new backend.
+    relay = _ServeRelay(_free_port(), dial_timeout=10.0)
+    relay.start()
+    try:
+        be1 = _EchoBackend(tag=b"ONE:")
+        relay.set_backend(be1.port)
+        c1 = socket.create_connection(("127.0.0.1", relay.port), timeout=2.0)
+        c1.settimeout(5.0)
+        assert c1.recv(16).startswith(b"ONE:")
+        c1.close()
+        be1.close()
+
+        be2 = _EchoBackend(tag=b"TWO:")
+        relay.set_backend(be2.port)
+        c2 = socket.create_connection(("127.0.0.1", relay.port), timeout=2.0)
+        c2.settimeout(5.0)
+        assert c2.recv(16).startswith(b"TWO:")
+        c2.close()
+        be2.close()
+    finally:
+        relay.close()
+
+
+def test_close_frees_the_public_port():
+    port = _free_port()
+    relay = _ServeRelay(port)
+    relay.start()
+    relay.close()
+    # SO_REUSEADDR + a real close means we can rebind immediately (this is what
+    # lets ffmpeg/other consumers take the port back after teardown).
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    s.bind(("127.0.0.1", port))
+    s.close()
+
+
+def test_dial_timeout_closes_idle_client():
+    # A client that connects but whose backend never appears is dropped after
+    # the dial timeout (so it can retry) rather than hanging forever.
+    relay = _ServeRelay(_free_port(), dial_timeout=0.5, dial_interval=0.05)
+    relay.start()
+    try:
+        cli = socket.create_connection(("127.0.0.1", relay.port), timeout=2.0)
+        cli.settimeout(3.0)
+        t0 = time.monotonic()
+        got = cli.recv(16)  # blocks until relay closes the conn (EOF -> b"")
+        assert got == b""
+        assert time.monotonic() - t0 >= 0.4
+        cli.close()
+    finally:
+        relay.close()
+
+
+if __name__ == "__main__":
+    import traceback
+    _fail = 0
+    for _k, _v in sorted(globals().items()):
+        if _k.startswith("test_"):
+            try:
+                _v()
+                print(f"PASS {_k}")
+            except Exception:
+                _fail += 1
+                print(f"FAIL {_k}")
+                traceback.print_exc()
+    raise SystemExit(1 if _fail else 0)