python-aidot-cameras 0.7.13__tar.gz → 0.7.15__tar.gz

{python_aidot_cameras-0.7.13/src/python_aidot_cameras.egg-info → python_aidot_cameras-0.7.15}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-aidot-cameras"
-version = "0.7.13"
+version = "0.7.15"
 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.13 → python_aidot_cameras-0.7.15}/src/aidot/camera/client.py

@@ -39,6 +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,
     _build_stun_binding_success_response,
     _terminal_webrtc_ack,
     _install_highport_nomination_patch,
@@ -677,6 +678,60 @@ class CameraMixin(_CameraControlsMixin):
             _LOGGER.debug("http wake failed for %s: %s", self.device_id, exc)
             return False
 
+    def _live_stream_param_request(self):
+        """Build ``(url, headers, body)`` for the liveStreamParam provision call.
+
+        Pure/deterministic - unit-tested in tests/test_live_stream_param.py.  The
+        body MUST be a JSON array of device ids (object body -> HTTP 500) and the
+        ``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)
+        )
+        url = f"{self._smarthome_base}/api/ipc/liveStream/liveStreamParam"
+        return url, headers, json.dumps([self.device_id])
+
+    async def _async_fetch_live_stream_param(self) -> bool:
+        """Provision the camera's live-stream session via the cloud (app parity).
+
+        Battery cameras waking from deep sleep reject the MQTT ``livePlayReq``
+        with code ``-50019`` ("not ready") and then never run ICE - so no media
+        ever flows - unless the app's pre-connect HTTP call has armed the session
+        first.  The official app (``KVSPreConnectStrategy.fetchKvsParams``) POSTs
+        the device id to ``/api/ipc/liveStream/liveStreamParam``; the cloud
+        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.
+        """
+        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
+
     async def async_wake_camera(self, retries: int = 2) -> bool:
         """Wake a battery camera on demand via the cloud HTTP low-power endpoint.
 
@@ -2101,7 +2156,11 @@ class CameraMixin(_CameraControlsMixin):
         """Background task: keep SDES stream alive; push to go2rtc via RTSP."""
         _MIN_DELAY = 10.0
         _MAX_DELAY = 300.0
-        _retry_delay = _MIN_DELAY
+        # 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
 
         while self._streaming_active:
             try:
@@ -2112,18 +2171,18 @@ class CameraMixin(_CameraControlsMixin):
             except asyncio.CancelledError:
                 return
             except Exception as exc:
+                _delay = next_backoff(_attempt, base=_MIN_DELAY, cap=_MAX_DELAY)
                 _LOGGER.warning(
                     "SDES keepalive: stream open failed for %s (retry in %.0fs): %s",
-                    self.device_id, _retry_delay, exc,
+                    self.device_id, _delay, exc,
                 )
                 try:
-                    await asyncio.sleep(_retry_delay)
+                    await asyncio.sleep(_delay)
                 except asyncio.CancelledError:
                     return
-                _retry_delay = min(_retry_delay * 2, _MAX_DELAY)
+                _attempt += 1
                 continue
 
-            _retry_delay = _MIN_DELAY  # reset on success
             self._stream_session = session
             # Don't block solely on wait_done(): the SDES ffmpeg reads RTP over a
             # UDP socket with no input timeout, so when a battery camera tears the
@@ -2208,8 +2267,19 @@ class CameraMixin(_CameraControlsMixin):
                 _LOGGER.debug("camera %s: swallowed exception", '_sdes_keepalive_loop', exc_info=True)
 
             if self._streaming_active:
+                # 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)
                 try:
-                    await asyncio.sleep(_MIN_DELAY)
+                    await asyncio.sleep(_delay)
                 except asyncio.CancelledError:
                     return
 
@@ -2225,7 +2295,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
-        _retry_delay = _MIN_DELAY
+        # Consecutive failed / frameless opens; drives jittered backoff (see
+        # next_backoff). Reset after a session that produced frames.
+        _attempt = 0
 
         def _on_frame(frame) -> None:
             # Accept keyframes always; accept P-frames only after first keyframe.
@@ -2248,6 +2320,7 @@ class CameraMixin(_CameraControlsMixin):
                 _LOGGER.debug("Streaming encode failed for %s: %s", self.device_id, enc_exc)
 
         while self._streaming_active:
+            _open_time = asyncio.get_running_loop().time()
             try:
                 session = await self.async_open_webrtc_stream(on_frame=_on_frame)
             except asyncio.CancelledError:
@@ -2266,18 +2339,18 @@ class CameraMixin(_CameraControlsMixin):
                     return
                 continue
             except Exception as exc:
+                _delay = next_backoff(_attempt, base=_MIN_DELAY, cap=_MAX_DELAY)
                 _LOGGER.warning(
                     "Stream open failed for %s (retry in %.0fs): %s",
-                    self.device_id, _retry_delay, exc,
+                    self.device_id, _delay, exc,
                 )
                 try:
-                    await asyncio.sleep(_retry_delay)
+                    await asyncio.sleep(_delay)
                 except asyncio.CancelledError:
                     return
-                _retry_delay = min(_retry_delay * 2, _MAX_DELAY)
+                _attempt += 1
                 continue
 
-            _retry_delay = _MIN_DELAY  # reset on success
             self._stream_session = session
             try:
                 while self._streaming_active:
@@ -2302,8 +2375,17 @@ class CameraMixin(_CameraControlsMixin):
                 _LOGGER.debug("camera %s: swallowed exception", '_on_frame', exc_info=True)
 
             if self._streaming_active:
+                # 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)
                 try:
-                    await asyncio.sleep(_MIN_DELAY)
+                    await asyncio.sleep(_delay)
                 except asyncio.CancelledError:
                     return
 
@@ -2419,7 +2501,7 @@ 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"))
-        retry_delay = _MIN_DELAY
+        _attempt = 0  # consecutive failed opens; drives jittered backoff
         _last_open_at = 0.0  # monotonic of the previous open attempt (0 = none yet)
         loop = asyncio.get_running_loop()
         while self._streaming_active:
@@ -2428,7 +2510,7 @@ class CameraMixin(_CameraControlsMixin):
             aq: "_queue.Queue" = _queue.Queue(maxsize=600)
             self._serve_ready.clear()  # fresh (cold) session: not ready until bound
             # Hard inter-attempt gate (APK parity): never start an open within
-            # _open_gate seconds of the previous one, regardless of retry_delay.
+            # _open_gate seconds of the previous one, regardless of the backoff.
             _since_open = loop.time() - _last_open_at
             if _last_open_at and _since_open < _open_gate:
                 try:
@@ -2455,18 +2537,19 @@ class CameraMixin(_CameraControlsMixin):
                     return
                 continue
             except Exception as exc:
+                _delay = next_backoff(_attempt, base=_MIN_DELAY, cap=_MAX_DELAY)
                 _LOGGER.warning(
                     "DTLS serve: open failed for %s (retry %.0fs): %s",
-                    self.device_id, retry_delay, exc,
+                    self.device_id, _delay, exc,
                 )
                 try:
-                    await asyncio.sleep(retry_delay)
+                    await asyncio.sleep(_delay)
                 except asyncio.CancelledError:
                     return
-                retry_delay = min(retry_delay * 2, _MAX_DELAY)
+                _attempt += 1
                 continue
 
-            retry_delay = _MIN_DELAY
+            _attempt = 0
             self._stream_session = session
             pc = session._pc
             # PC-dead test for the serve loop.  closed/failed are terminal at
@@ -3079,6 +3162,21 @@ class CameraMixin(_CameraControlsMixin):
 
         use_sdes = force_sdes if force_sdes is not None else self.is_sdes_camera
 
+        # Battery cameras must have their live-stream session provisioned by the
+        # cloud BEFORE MQTT signaling, or the camera rejects livePlayReq with
+        # -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"):
+            _lsp_ok = await self._async_fetch_live_stream_param()
+            _LOGGER.debug("camera %s: liveStreamParam provisioned ok=%s",
+                          self.device_id, _lsp_ok)
+
         # AIDOT_FAST_CONNECT (default off): LAN-direct mode.  Both transports stall
         # the offer on a TURN relay allocation to the cloud TURN server before ICE
         # can even start - for DTLS, aiortc's setLocalDescription blocks until ICE

{python_aidot_cameras-0.7.13 → python_aidot_cameras-0.7.15}/src/aidot/camera/protocol.py

@@ -396,6 +396,39 @@ async def _webrtc_consume_video(track: Any, on_frame: Callable) -> None:
             break
 
 
+def next_backoff(
+    attempt: int,
+    *,
+    base: float,
+    cap: float,
+    rand: Optional[Callable[[], float]] = None,
+) -> float:
+    """Jittered exponential backoff (AWS-style) with a hard floor at ``base``.
+
+    Returns the retry delay for 0-based ``attempt``: an exponential ceiling
+    ``base * 2**attempt`` (capped at ``cap``), with the actual delay drawn
+    uniformly in ``[base, ceiling]``. The random spread de-synchronizes
+    concurrent reconnects so a fleet of cameras (or repeated failures of one)
+    recovering at the same moment doesn't stampede the cloud / MQTT broker into
+    a reconnect storm or rate-limit -- plain ``delay *= 2`` keeps every retrier
+    in lockstep, jitter breaks the lockstep while preserving the same average
+    growth.
+
+    ``attempt`` 0 always returns exactly ``base`` (preserving the loops'
+    existing minimum spacing). ``rand`` defaults to ``random.random`` and is
+    injectable so the policy is unit-testable without randomness.
+    """
+    if rand is None:
+        rand = random.random
+    # Clamp the exponent: a long-lived failing camera can drive ``attempt`` high,
+    # and 2**attempt overflows float64 around attempt~1024. The ceiling saturates
+    # at ``cap`` long before that, so 30 doublings is always enough headroom.
+    ceiling = min(cap, base * (2 ** min(max(attempt, 0), 30)))
+    if ceiling <= base:
+        return base
+    return base + rand() * (ceiling - base)
+
+
 def _write_text_file(path: str, text: str) -> None:
     """Write ``text`` to ``path`` synchronously.
 

{python_aidot_cameras-0.7.13 → python_aidot_cameras-0.7.15/src/python_aidot_cameras.egg-info}/PKG-INFO

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

@@ -35,9 +35,11 @@ src/python_aidot_cameras.egg-info/dependency_links.txt
 src/python_aidot_cameras.egg-info/requires.txt
 src/python_aidot_cameras.egg-info/top_level.txt
 tests/test_alarm_event.py
+tests/test_backoff.py
 tests/test_go2rtc.py
 tests/test_highport_nomination.py
 tests/test_lan_control.py
+tests/test_live_stream_param.py
 tests/test_motion_poll.py
 tests/test_no_undefined_names.py
 tests/test_post_merge_hardening.py

python_aidot_cameras-0.7.15/tests/test_backoff.py

@@ -0,0 +1,84 @@
+"""Unit tests for the jittered exponential-backoff helper.
+
+next_backoff() is the pure reconnect-delay policy the camera keepalive/serve
+loops use so a degraded camera (or a fleet reconnecting at once) is met with
+spread-out, escalating retries instead of a synchronized storm. Randomness is
+injected so the bounds are deterministic. No camera/network needed.
+"""
+import os
+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
+
+_BASE = 10.0
+_CAP = 300.0
+
+
+def _lo():  # rand() -> 0.0 : the low end of the jitter window
+    return 0.0
+
+
+def _hi():  # rand() -> ~1.0 : the high end of the jitter window
+    return 1.0
+
+
+def test_attempt_zero_is_exactly_base():
+    # First retry must preserve the loops' existing minimum spacing.
+    assert next_backoff(0, base=_BASE, cap=_CAP, rand=_lo) == _BASE
+    assert next_backoff(0, base=_BASE, cap=_CAP, rand=_hi) == _BASE
+
+
+def test_floor_is_always_base():
+    # Low end of the window never dips below base, at any attempt.
+    for a in range(0, 12):
+        assert next_backoff(a, base=_BASE, cap=_CAP, rand=_lo) >= _BASE
+
+
+def test_ceiling_grows_exponentially_until_cap():
+    # rand()->1 gives the ceiling: base*2**attempt, capped at cap.
+    assert next_backoff(1, base=_BASE, cap=_CAP, rand=_hi) == 20.0
+    assert next_backoff(2, base=_BASE, cap=_CAP, rand=_hi) == 40.0
+    assert next_backoff(3, base=_BASE, cap=_CAP, rand=_hi) == 80.0
+
+
+def test_ceiling_saturates_at_cap():
+    # 10*2**5 = 320 > cap(300) -> saturates at cap.
+    assert next_backoff(5, base=_BASE, cap=_CAP, rand=_hi) == _CAP
+    assert next_backoff(50, base=_BASE, cap=_CAP, rand=_hi) == _CAP
+
+
+def test_delay_within_bounds_for_real_rng():
+    # With the real RNG every draw stays in [base, min(cap, base*2**attempt)].
+    for a in range(0, 10):
+        ceiling = min(_CAP, _BASE * (2 ** a))
+        for _ in range(200):
+            d = next_backoff(a, base=_BASE, cap=_CAP)
+            assert _BASE <= d <= ceiling
+
+
+def test_large_attempt_does_not_overflow():
+    # A long-lived failing camera can drive attempt very high; the exponent is
+    # clamped so base*2**attempt never overflows float64.
+    assert next_backoff(5000, base=_BASE, cap=_CAP, rand=_hi) == _CAP
+    assert next_backoff(5000, base=_BASE, cap=_CAP, rand=_lo) == _BASE
+
+
+def test_negative_attempt_treated_as_zero():
+    assert next_backoff(-3, base=_BASE, cap=_CAP, rand=_lo) == _BASE
+
+
+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)

python_aidot_cameras-0.7.15/tests/test_live_stream_param.py

@@ -0,0 +1,75 @@
+"""Unit tests for the liveStreamParam provision-request builder.
+
+Battery cameras (e.g. L2_170, A001513) must have their live-stream session
+provisioned by the cloud before MQTT signaling, or they reject livePlayReq with
+-50019 and never stream. The request shape is exact: a JSON ARRAY body of device
+ids (an object body returns HTTP 500) plus an ``owner`` header. This locks that
+format in. No network: builds the request from a bare instance.
+"""
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "src"))
+
+import aidot.camera.client as cc
+
+# The camera mixin class that defines the builder (avoid hard-coding the name).
+_CAM = next(v for v in vars(cc).values()
+            if isinstance(v, type) and "_live_stream_param_request" in v.__dict__)
+
+
+def _stub(**over):
+    cam = _CAM.__new__(_CAM)
+    cam._user_info = over.get("user_info", {"accessToken": "TKN", "id": "owner-123"})
+    cam._region = "us"  # _smarthome_base is a property derived from _region
+    cam.device_id = over.get("device_id", "DEV1234")
+    cam.user_id = "U1"
+    return cam
+
+
+def test_url_is_livestreamparam_endpoint():
+    url, _, _ = _stub()._live_stream_param_request()
+    assert url.endswith("/api/ipc/liveStream/liveStreamParam")
+    assert url.startswith("https://")
+
+
+def test_body_is_json_array_of_device_id():
+    # MUST be a JSON array - an object body ({"deviceId": id}) returns HTTP 500.
+    _, _, body = _stub()._live_stream_param_request()
+    parsed = json.loads(body)
+    assert isinstance(parsed, list)
+    assert parsed == ["DEV1234"]
+
+
+def test_owner_header_required():
+    # The endpoint needs owner (like the wake endpoint); falls back across keys.
+    _, headers, _ = _stub()._live_stream_param_request()
+    assert headers.get("owner") == "owner-123"
+
+
+def test_owner_falls_back_to_user_id():
+    cam = _stub(user_info={"accessToken": "T"})  # no id/owner/userId
+    _, headers, _ = cam._live_stream_param_request()
+    assert headers.get("owner") == "U1"
+
+
+def test_auth_headers_carried():
+    _, headers, _ = _stub()._live_stream_param_request()
+    assert headers.get("token") == "TKN"
+    assert headers.get("terminal") == "app"
+
+
+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)