@camstack/addon-import-alexa 0.2.191 → 0.2.192

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-import-alexa",
-  "version": "0.2.191",
+  "version": "0.2.192",
   "description": "Alexa device-import provider for CamStack — imports the smart-home devices in a user's Alexa account via the unofficial alexa-remote2 cookie/token client (the inverse of the Alexa exporter)",
   "keywords": [
     "camstack",
@@ -72,7 +72,7 @@
       }
     ],
     "requires": {
-      "server": ">=1.2.784"
+      "server": ">=1.2.786"
     }
   },
   "files": [

package/python/alexa_gateway.py

@@ -10,17 +10,23 @@ import time
 from pathlib import Path
 from types import SimpleNamespace
 
+from alexa_push import Emit, PushChannel
 from alexa_sequences import EchoTarget, build_volume_node
 
 REGIONS = ("NA", "EU", "FE")
 REGION_LOCALE = {"NA": "en-US", "EU": "en-GB", "FE": "ja-JP"}
 
-# The `/api/np/command` bodies. Only these four are offered.
+# The `/api/np/command` bodies. Amazon's shuffle and repeat are booleans sent as the
+# strings "true" / "false"; there is no repeat-one.
 NP_COMMANDS = {
-    "play": "PlayCommand",
-    "pause": "PauseCommand",
-    "next": "NextCommand",
-    "previous": "PreviousCommand",
+    "play": {"type": "PlayCommand"},
+    "pause": {"type": "PauseCommand"},
+    "next": {"type": "NextCommand"},
+    "previous": {"type": "PreviousCommand"},
+    "shuffle-on": {"type": "ShuffleCommand", "shuffle": "true"},
+    "shuffle-off": {"type": "ShuffleCommand", "shuffle": "false"},
+    "repeat-on": {"type": "RepeatCommand", "repeat": "true"},
+    "repeat-off": {"type": "RepeatCommand", "repeat": "false"},
 }
 RATE_LIMITED = "rate-limited"
 
@@ -116,7 +122,9 @@ VOLUMES_PATH = "/api/devices/deviceType/dsn/audio/v1/allDeviceVolumes"
 class AlexaPyGateway:
     """Holds one AlexaLogin for the life of the process (one process per broker)."""
 
-    def __init__(self) -> None:
+    def __init__(self, emit: Emit | None = None) -> None:
+        self._emit = emit
+        self._push: PushChannel | None = None
         self._login = None
         self._devices: list[dict] = []
         self._logged_in = False
@@ -206,7 +214,19 @@ class AlexaPyGateway:
                 }
         await login.login(cookies=cookies)
         await self._persist_session()
-        return self._status_result()
+        result = self._status_result()
+        if result["status"] == "ok":
+            self._start_push(login)
+        return result
+
+    def _start_push(self, login) -> None:
+        """Open the push channel on this session; a new sign-in replaces the old channel."""
+        if self._emit is None:
+            return
+        if self._push is not None:
+            self._push.stop()
+        self._push = PushChannel(login, self._emit)
+        self._push.start()
 
     async def devices(self) -> dict:
         login = self._require_login()
@@ -282,7 +302,7 @@ class AlexaPyGateway:
         device_type = self._device_type_of(serial)
         async with self._lock(serial):
             try:
-                await run_command(self._api_for(serial, device_type).set_media({"type": body}), "the media command")
+                await run_command(self._api_for(serial, device_type).set_media(dict(body)), "the media command")
             except Exception as err:  # noqa: BLE001 — typed below
                 if is_rate_limited(err):
                     raise RateLimitedError("amazon rate limit (429) on a media command") from err

package/python/alexa_push.py

@@ -0,0 +1,178 @@
+"""The Alexa push channel (alexapy's HTTP/2 client), forwarded as protocol lines.
+
+One channel per signed-in account, opened with the session the gateway already
+holds. Every event leaves as one unsolicited stdout line (no ``id``):
+
+    {"push": "channel", "state": "up" | "down", "reason": str, "retryInMs": int}
+    {"push": "event", "command": str, "serial": str | null}
+
+Only the event name and the Echo's serial are forwarded: the addon re-reads the
+Echo it names, so no payload (and nothing Amazon sent in it) crosses the pipe.
+A channel that closes is reopened with a bounded, doubling delay; the addon keeps
+polling as the fallback in the meantime.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import time
+from typing import Any, Awaitable, Callable
+
+RECONNECT_BASE_S = 5
+RECONNECT_MAX_S = 300
+# A stream must stay up this long before the backoff starts over; one that opens and
+# closes at once keeps doubling instead of flapping every few seconds.
+STABLE_UP_S = 60
+
+Emit = Callable[[dict], None]
+ClientFactory = Callable[..., Any]
+Sleep = Callable[[float], Awaitable[None]]
+
+
+def _loads(text: object) -> object:
+    if not isinstance(text, str):
+        return None
+    try:
+        return json.loads(text)
+    except ValueError:
+        return None
+
+
+def _serial_of(payload: dict) -> str | None:
+    doppler = payload.get("dopplerId")
+    if isinstance(doppler, dict) and isinstance(doppler.get("deviceSerialNumber"), str):
+        return doppler["deviceSerialNumber"]
+    key = payload.get("key")
+    if isinstance(key, dict) and isinstance(key.get("entryId"), str):
+        parts = key["entryId"].split("#")
+        if len(parts) > 2 and parts[2] != "":
+            return parts[2]
+    return None
+
+
+def parse_push_message(message: object) -> list[dict]:
+    """The events of one HTTP/2 push message; a malformed item is skipped, never raised."""
+    if not isinstance(message, dict):
+        return []
+    directive = message.get("directive")
+    payload = directive.get("payload") if isinstance(directive, dict) else None
+    updates = payload.get("renderingUpdates") if isinstance(payload, dict) else None
+    if not isinstance(updates, list):
+        return []
+    events: list[dict] = []
+    for item in updates:
+        if not isinstance(item, dict):
+            continue
+        resource = _loads(item.get("resourceMetadata"))
+        if not isinstance(resource, dict):
+            continue
+        command = resource.get("command")
+        if not isinstance(command, str) or command == "":
+            continue
+        body = _loads(resource.get("payload"))
+        serial = _serial_of(body) if isinstance(body, dict) else None
+        events.append({"push": "event", "command": command, "serial": serial})
+    return events
+
+
+def reconnect_delay_s(attempt: int) -> int:
+    return min(RECONNECT_BASE_S * 2 ** min(attempt, 10), RECONNECT_MAX_S)
+
+
+def default_client_factory(login, msg_cb, open_cb, close_cb, error_cb):
+    from alexapy import HTTP2EchoClient
+
+    return HTTP2EchoClient(login, msg_cb, open_cb, close_cb, error_cb)
+
+
+class PushChannel:
+    def __init__(
+        self,
+        login: object,
+        emit: Emit,
+        client_factory: ClientFactory | None = None,
+        sleep: Sleep = asyncio.sleep,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._login = login
+        self._emit = emit
+        self._factory = client_factory
+        self._sleep = sleep
+        self._clock = clock
+        self._stopped = False
+        self._up = False
+        self._task: asyncio.Task | None = None
+
+    def start(self) -> None:
+        if self._task is None:
+            self._task = asyncio.get_running_loop().create_task(self.run())
+
+    def stop(self) -> None:
+        self._stopped = True
+        if self._task is not None:
+            self._task.cancel()
+            self._task = None
+
+    def _down(self, reason: str, retry_s: int) -> None:
+        if not self._up:
+            return
+        self._up = False
+        self._emit(
+            {"push": "channel", "state": "down", "reason": reason[:200], "retryInMs": retry_s * 1000}
+        )
+
+    async def run(self) -> None:
+        attempt = 0
+        while not self._stopped:
+            closed = asyncio.Event()
+            reason = "closed"
+            opened_at: float | None = None
+
+            async def on_message(message: object) -> None:
+                for event in parse_push_message(message):
+                    self._emit(event)
+
+            async def on_open() -> None:
+                nonlocal opened_at
+                opened_at = self._clock()
+                self._up = True
+                self._emit({"push": "channel", "state": "up", "reason": "connected", "retryInMs": 0})
+
+            async def on_close() -> None:
+                closed.set()
+
+            async def on_error(error: str) -> None:
+                nonlocal reason
+                reason = f"error: {error}"
+
+            client = None
+            try:
+                client = (self._factory or default_client_factory)(self._login, on_message, on_open, on_close, on_error)
+                await client.async_run()
+                if opened_at is None and not closed.is_set():
+                    # Returned without opening or closing: that is a failed attempt, not a wait.
+                    reason = "stream ended before opening"
+                else:
+                    await closed.wait()
+            except asyncio.CancelledError:
+                raise
+            except Exception as err:  # noqa: BLE001 — a failed connect is a retry, never a crash
+                reason = f"{type(err).__name__}: {err}"
+            finally:
+                if client is not None:
+                    with contextlib.suppress(Exception):
+                        client.on_close("channel ended")
+            if opened_at is not None and self._clock() - opened_at >= STABLE_UP_S:
+                attempt = 0
+            delay = reconnect_delay_s(attempt)
+            attempt += 1
+            if not self._up:
+                # Never opened: the attempt itself failed; tell the addon once per failed attempt.
+                self._emit(
+                    {"push": "channel", "state": "down", "reason": reason[:200], "retryInMs": delay * 1000}
+                )
+            else:
+                self._down(reason, delay)
+            await self._sleep(delay)

package/python/alexa_worker.py

@@ -14,12 +14,18 @@ import traceback
 from alexa_logging import configure_logging
 
 
+def emit(line: dict) -> None:
+    """An unsolicited line (a push event). Same thread as the responses, so lines never interleave."""
+    sys.stdout.write(json.dumps(line) + "\n")
+    sys.stdout.flush()
+
+
 async def serve() -> None:
     # Imported here so `python -m unittest` of the protocol does not need alexapy.
     from alexa_gateway import AlexaPyGateway
     from alexa_protocol import Session
 
-    session = Session(AlexaPyGateway())
+    session = Session(AlexaPyGateway(emit))
     loop = asyncio.get_running_loop()
     reader = asyncio.StreamReader()
     protocol = asyncio.StreamReaderProtocol(reader)

package/python/test_alexa_gateway_echo.py

@@ -134,6 +134,20 @@ class EchoMediaTests(unittest.TestCase):
         with self.assertRaises(ValueError):
             run(gateway.np_command("s1", "rewind"))
 
+    def test_np_command_shuffle_and_repeat_post_the_boolean_string_bodies(self) -> None:
+        gateway, calls = install_fake()
+        for name in ("shuffle-on", "shuffle-off", "repeat-on", "repeat-off"):
+            run(gateway.np_command("s1", name))
+        self.assertEqual(
+            [data for _, data in calls["media"]],
+            [
+                {"type": "ShuffleCommand", "shuffle": "true"},
+                {"type": "ShuffleCommand", "shuffle": "false"},
+                {"type": "RepeatCommand", "repeat": "true"},
+                {"type": "RepeatCommand", "repeat": "false"},
+            ],
+        )
+
     def test_set_volume_posts_the_volume_behaviour_clamped(self) -> None:
         gateway, calls = install_fake()
         run(gateway.set_volume("s1", 140))

package/python/test_alexa_push.py

@@ -0,0 +1,227 @@
+"""The push channel parses alexapy's HTTP/2 messages and forwards them, with a fake client.
+
+No network, no alexapy: the client the channel opens is a fake that the test drives.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import alexa_push
+from alexa_push import PushChannel, parse_push_message, reconnect_delay_s
+from test_alexa_gateway import install_fake_alexapy, remove_fake_alexapy
+
+
+def message(command: str, payload: dict) -> dict:
+    resource = {"command": command, "payload": json.dumps(payload)}
+    return {"directive": {"payload": {"renderingUpdates": [{"resourceMetadata": json.dumps(resource)}]}}}
+
+
+def volume_message(serial: str) -> dict:
+    return message("PUSH_VOLUME_CHANGE", {"dopplerId": {"deviceSerialNumber": serial}, "volumeSetting": 30})
+
+
+class ParseTests(unittest.TestCase):
+    def test_reads_command_and_serial_from_the_doppler_id(self) -> None:
+        self.assertEqual(
+            parse_push_message(volume_message("S1")),
+            [{"push": "event", "command": "PUSH_VOLUME_CHANGE", "serial": "S1"}],
+        )
+
+    def test_reads_the_serial_from_a_key_entry_id(self) -> None:
+        events = parse_push_message(message("PUSH_NOTIFICATION_CHANGE", {"key": {"entryId": "a#b#SERIAL9"}}))
+        self.assertEqual(events[0]["serial"], "SERIAL9")
+
+    def test_an_event_without_a_serial_keeps_none_and_never_carries_the_payload(self) -> None:
+        events = parse_push_message(message("PUSH_EQUALIZER_STATE_CHANGE", {"bass": 1}))
+        self.assertEqual(events, [{"push": "event", "command": "PUSH_EQUALIZER_STATE_CHANGE", "serial": None}])
+
+    def test_garbage_is_skipped_not_raised(self) -> None:
+        for bad in (None, [], {}, {"directive": {"payload": {"renderingUpdates": [1, {"resourceMetadata": "{"}]}}}):
+            self.assertEqual(parse_push_message(bad), [])
+
+    def test_the_delay_doubles_and_is_bounded(self) -> None:
+        self.assertEqual([reconnect_delay_s(n) for n in (0, 1, 2)], [5, 10, 20])
+        self.assertEqual(reconnect_delay_s(50), alexa_push.RECONNECT_MAX_S)
+
+
+class FakeClient:
+    """Stands in for HTTP2EchoClient; `script` decides what each connection does."""
+
+    instances: list["FakeClient"] = []
+
+    def __init__(self, login, msg_cb, open_cb, close_cb, error_cb) -> None:
+        self.msg_cb, self.open_cb, self.close_cb = msg_cb, open_cb, close_cb
+        self.closed_by_channel = False
+        FakeClient.instances.append(self)
+
+    async def async_run(self) -> None:
+        index = len(FakeClient.instances) - 1
+        if index == 0:
+            await self.open_cb()
+            await self.msg_cb(volume_message("S1"))
+            await self.close_cb()
+        elif index == 1:
+            raise RuntimeError("HTTP2 open timeout")
+        else:
+            await self.open_cb()
+            await self.msg_cb(volume_message("S2"))
+            await asyncio.sleep(3600)
+
+    def on_close(self, _reason=None) -> None:
+        self.closed_by_channel = True
+
+
+class ChannelTests(unittest.TestCase):
+    def test_forwards_events_and_reconnects_with_a_bounded_delay(self) -> None:
+        FakeClient.instances = []
+        lines: list[dict] = []
+        sleeps: list[float] = []
+
+        async def fake_sleep(seconds: float) -> None:
+            sleeps.append(seconds)
+            await asyncio.sleep(0)
+
+        async def scenario() -> None:
+            channel = PushChannel(object(), lines.append, FakeClient, fake_sleep)
+            channel.start()
+            for _ in range(50):
+                await asyncio.sleep(0)
+            channel.stop()
+
+        asyncio.run(scenario())
+        kinds = [(line["push"], line.get("state") or line.get("command"), line.get("serial")) for line in lines]
+        self.assertEqual(
+            kinds,
+            [
+                ("channel", "up", None),
+                ("event", "PUSH_VOLUME_CHANGE", "S1"),
+                ("channel", "down", None),  # first stream ended
+                ("channel", "down", None),  # second attempt never opened
+                ("channel", "up", None),  # third connected
+                ("event", "PUSH_VOLUME_CHANGE", "S2"),
+            ],
+        )
+        self.assertEqual(sleeps[:2], [5, 10])
+        self.assertTrue(all(client.closed_by_channel for client in FakeClient.instances[:2]))
+        self.assertEqual(lines[3]["reason"], "RuntimeError: HTTP2 open timeout")
+        self.assertEqual(lines[3]["retryInMs"], 10_000)
+
+
+class FlapClient:
+    """Opens and closes at once, or returns without doing either."""
+
+    mode = "flap"
+    made = 0
+    hold = 0.0
+    now = [0.0]
+
+    def __init__(self, login, msg_cb, open_cb, close_cb, error_cb) -> None:
+        self.open_cb, self.close_cb = open_cb, close_cb
+        FlapClient.made += 1
+
+    async def async_run(self) -> None:
+        if FlapClient.mode == "flap":
+            await self.open_cb()
+            FlapClient.now[0] += FlapClient.hold  # how long the stream stayed up
+            await self.close_cb()
+        # mode "silent": returns with neither open nor close
+
+    def on_close(self, _reason=None) -> None:
+        pass
+
+
+class BackoffTests(unittest.TestCase):
+    def run_channel(self, mode: str, hold: float, passes: int = 40) -> tuple[list[dict], list[float]]:
+        FlapClient.mode, FlapClient.made, FlapClient.hold = mode, 0, hold
+        FlapClient.now = now = [0.0]
+        lines: list[dict] = []
+        sleeps: list[float] = []
+
+        async def fake_sleep(seconds: float) -> None:
+            sleeps.append(seconds)
+            await asyncio.sleep(0)
+
+        async def scenario() -> None:
+            channel = PushChannel(object(), lines.append, FlapClient, fake_sleep, lambda: now[0])
+            channel.start()
+            for _ in range(passes):
+                await asyncio.sleep(0)
+            channel.stop()
+
+        asyncio.run(scenario())
+        return lines, sleeps
+
+    def test_a_stream_that_opens_and_closes_at_once_keeps_backing_off(self) -> None:
+        _, sleeps = self.run_channel("flap", hold=0.0)
+        self.assertEqual(sleeps[:5], [5, 10, 20, 40, 80])
+
+    def test_the_backoff_starts_over_only_after_a_stable_stretch(self) -> None:
+        _, sleeps = self.run_channel("flap", hold=alexa_push.STABLE_UP_S + 1)
+        self.assertEqual(sleeps[:3], [5, 5, 5])
+
+    def test_a_client_that_returns_without_opening_is_retried_and_reported_down(self) -> None:
+        lines, sleeps = self.run_channel("silent", hold=0.0)
+        self.assertGreaterEqual(FlapClient.made, 2)
+        self.assertEqual(sleeps[:2], [5, 10])
+        self.assertEqual(lines[0]["state"], "down")
+        self.assertEqual(lines[0]["reason"], "stream ended before opening")
+
+
+class GatewayPushTests(unittest.TestCase):
+    def tearDown(self) -> None:
+        remove_fake_alexapy()
+
+    def test_a_good_sign_in_opens_the_channel_with_the_same_login(self) -> None:
+        from alexa_gateway import AlexaPyGateway
+
+        install_fake_alexapy()
+        FakeClient.instances = []
+        seen: list[object] = []
+        lines: list[dict] = []
+        original = alexa_push.default_client_factory
+
+        def factory(login, *callbacks):
+            seen.append(login)
+            return FakeClient(login, *callbacks)
+
+        alexa_push.default_client_factory = factory
+
+        async def scenario() -> AlexaPyGateway:
+            gateway = AlexaPyGateway(lines.append)
+            with tempfile.TemporaryDirectory() as directory:
+                await gateway.login_broker("alexa_001", "tok", "App", "amazon.it", "EU", str(Path(directory) / "s"))
+            for _ in range(10):
+                await asyncio.sleep(0)
+            return gateway
+
+        try:
+            gateway = asyncio.run(scenario())
+        finally:
+            alexa_push.default_client_factory = original
+        self.assertIs(seen[0], gateway._login)
+        self.assertEqual(lines[0]["push"], "channel")
+
+    def test_no_emitter_means_no_channel(self) -> None:
+        from alexa_gateway import AlexaPyGateway
+
+        install_fake_alexapy()
+
+        async def scenario() -> AlexaPyGateway:
+            gateway = AlexaPyGateway()
+            with tempfile.TemporaryDirectory() as directory:
+                await gateway.login_broker("alexa_001", "tok", "App", "amazon.it", "EU", str(Path(directory) / "s"))
+            return gateway
+
+        self.assertIsNone(asyncio.run(scenario())._push)
+
+
+if __name__ == "__main__":
+    unittest.main()