phystack-hub-client 6.16.0__tar.gz → 6.18.2__tar.gz

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/CHANGELOG.md

@@ -6,6 +6,24 @@ publishes even minors from `main`, so a Python release is the next even minor at
 or above the npm version it matches; the entries below name the npm version and
 PRs each change was ported from.
 
+## 6.18.0 — parity with npm 6.16.0 (TECH-1521)
+
+### Changed
+
+- Removed the hardcoded Google STUN fallback (npm 6.16.0, ps-platform #973,
+  TECH-1516/TECH-1521). `MediaStreamOptions.stun_servers` and
+  `DataChannelOptions.stun_servers` now default to the `PHYSTACK_STUN_URL` env
+  var when set, otherwise an empty list — with no `ice_servers_provider`
+  resolving, connections degrade to host candidates only instead of contacting
+  `stun.l.google.com`. All STUN normally comes from the phyhub-minted ICE list
+  (`stun:turn-<region>.phystack.com:3478`).
+- Every configuration builder now returns an explicit `RTCConfiguration`
+  (possibly with an empty server list) instead of `None`: aiortc substitutes
+  its own default — Google STUN — when a peer connection is created without a
+  configuration, which would have silently reintroduced the third-party STUN.
+- Guard tests: defaults carry no third-party STUN, and a source scan fails the
+  suite if a Google STUN host/port literal ever reappears in the package.
+
 ## 6.16.0 — parity with npm 6.15.1 (TECH-1483)
 
 ### Added

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: phystack-hub-client
-Version: 6.16.0
+Version: 6.18.2
 Summary: Python client for PhyHub - events, actions, DataChannel, and MediaStream
 Project-URL: Homepage, https://github.com/phystack/phystack-pypi
 Project-URL: Documentation, https://docs.phystack.com

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/pyproject.toml

@@ -7,7 +7,7 @@ name = "phystack-hub-client"
 # Fixed version group with the Node hub-client (@phystack/hub-client in
 # phystack/ps-platform): both clients implement the same twin/WebRTC contract
 # and are released together under the same version.
-version = "6.16.0"
+version = "6.18.2"
 description = "Python client for PhyHub - events, actions, DataChannel, and MediaStream"
 readme = "README.md"
 license = "MIT"

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/src/phystack/hub_client/client.py

@@ -365,8 +365,18 @@ class PhyHubClient:
 
         self._connection.on(self.EVENTS.TWIN_MESSAGE, on_twin_message)
 
-        def on_twin_updated(payload: dict[str, Any]) -> None:
-            """Handle twin property update events."""
+        def on_twin_updated(payload: dict[str, Any], *_extra: Any) -> None:
+            """Handle twin property update events.
+
+            ``*_extra`` absorbs any trailing positional argument the server
+            appends to the ``twinUpdated`` emit. Some phyhub builds send twin
+            lifecycle events with a second positional arg (event metadata);
+            JS clients silently ignore it, but python-socketio passes every
+            positional arg through, so a strict ``(payload)`` signature raises
+            "takes 1 positional argument but 2 were given" and DROPS EVERY twin
+            update — the device stops seeing settings/desired-property changes
+            until restarted. Matches the tolerant ``on_twin_message`` sibling.
+            """
             twin_data = payload.get("data") or payload
             twin_id = payload.get("twinId") or (twin_data.get("id") if isinstance(twin_data, dict) else None)
 

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/src/phystack/hub_client/cloud_twins.py

@@ -83,15 +83,23 @@ class CloudTwinStore:
 
     # --- lifecycle events ---
 
-    def apply_created(self, payload: CloudTwinLifecycleEvent) -> None:
+    # ``*_extra`` on these three absorbs any trailing positional arg the
+    # server appends to a twin lifecycle emit. They are registered directly
+    # as socket.io handlers (PhyHubClient cloud-app mode), so a strict
+    # ``(payload)`` signature would raise "takes 1 positional argument but 2
+    # were given" and silently drop every cloud-twin update — the same defect
+    # fixed in PhyHubClient.on_twin_updated. Direct internal callers still
+    # pass a single argument.
+
+    def apply_created(self, payload: CloudTwinLifecycleEvent, *_extra: Any) -> None:
         """Apply a ``twinCreated`` event and notify ``on_created`` listeners."""
         self._apply(_KIND_CREATED, payload)
 
-    def apply_updated(self, payload: CloudTwinLifecycleEvent) -> None:
+    def apply_updated(self, payload: CloudTwinLifecycleEvent, *_extra: Any) -> None:
         """Apply a ``twinUpdated`` event and notify ``on_updated`` listeners."""
         self._apply(_KIND_UPDATED, payload)
 
-    def apply_deleted(self, payload: CloudTwinLifecycleEvent) -> None:
+    def apply_deleted(self, payload: CloudTwinLifecycleEvent, *_extra: Any) -> None:
         """Apply a ``twinDeleted`` event and notify ``on_deleted`` listeners."""
         self._apply(_KIND_DELETED, payload)
 

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/src/phystack/hub_client/services/webrtc/data_channel.py

@@ -39,6 +39,7 @@ from aiortc import (
 )
 
 from phystack.hub_client.services.webrtc.media_stream import (
+    _get_default_stun_servers,
     apply_remote_ice_candidate,
     build_ice_servers,
 )
@@ -110,9 +111,9 @@ class DataChannelOptions:
     """Options for DataChannel connection."""
 
     use_stun: bool = True
-    stun_servers: list[str] = field(
-        default_factory=lambda: ["stun:stun.l.google.com:19302", "stun:stun1.l.google.com:19302"]
-    )
+    # Static STUN fallback (PHYSTACK_STUN_URL or empty — never third-party;
+    # TECH-1521, mirroring npm @phystack/hub-client 6.16.0).
+    stun_servers: list[str] = field(default_factory=_get_default_stun_servers)
     turn_servers: list[dict[str, str]] = field(default_factory=_get_default_turn_servers)
     ice_transport_policy: str = field(default_factory=_get_default_ice_transport_policy)
     connection_timeout: float = 15.0
@@ -384,7 +385,10 @@ class DataChannelHandler:
         if self._is_closed:
             raise RuntimeError("DataChannelHandler closed during connection attempt")
 
-        configuration = RTCConfiguration(iceServers=ice_servers) if ice_servers else None
+        # Always pass an explicit configuration: aiortc substitutes ITS OWN
+        # default (Google STUN) when given None — an explicit empty list means
+        # host candidates only (TECH-1521).
+        configuration = RTCConfiguration(iceServers=ice_servers)
         peer_connection = RTCPeerConnection(configuration=configuration)
         self._pc = peer_connection
         self._pending_remote_candidates = []

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/src/phystack/hub_client/services/webrtc/data_responder.py

@@ -536,9 +536,11 @@ class DataChannelResponder:
             self._clear_connect_timer(peer_key)
             self._unhealthy_since.pop(peer_key, None)
 
-    async def _build_configuration(self) -> Optional[RTCConfiguration]:
+    async def _build_configuration(self) -> RTCConfiguration:
         ice_servers = await resolve_data_channel_ice_servers(
             self._options.ice_options,
             provider=self._options.ice_servers_provider,
         )
-        return RTCConfiguration(iceServers=ice_servers) if ice_servers else None
+        # Explicit configuration always: aiortc's None default is Google STUN
+        # (TECH-1521); an empty list means host candidates only.
+        return RTCConfiguration(iceServers=ice_servers)

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/src/phystack/hub_client/services/webrtc/media_responder.py

@@ -476,7 +476,7 @@ class MediaStreamResponder:
             fps=ice_options.video_fps,
         )
 
-    async def _build_configuration(self) -> Optional[RTCConfiguration]:
+    async def _build_configuration(self) -> RTCConfiguration:
         extra_servers: list[dict[str, Any]] = []
         if self._options.ice_servers_provider:
             try:
@@ -489,7 +489,9 @@ class MediaStreamResponder:
                     provider_error,
                 )
         ice_servers = build_ice_servers(self._options.ice_options, extra_servers)
-        return RTCConfiguration(iceServers=ice_servers) if ice_servers else None
+        # Explicit configuration always: aiortc's None default is Google STUN
+        # (TECH-1521); an empty list means host candidates only.
+        return RTCConfiguration(iceServers=ice_servers)
 
     # =========================================================================
     # Connect-timeout eviction (npm responder-fanout connectTimers parity)

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/src/phystack/hub_client/services/webrtc/media_stream.py

@@ -94,6 +94,20 @@ def _get_default_ice_transport_policy() -> str:
     return "relay" if os.environ.get("PHYSTACK_TURN_URL") else "all"
 
 
+def _get_default_stun_servers() -> list[str]:
+    """Static STUN fallback, used only when no ice_servers_provider resolves.
+
+    Must be OUR coturn (stun:turn-<region>.phystack.com:3478 via
+    PHYSTACK_STUN_URL) — never a third-party service like Google STUN
+    (TECH-1521, mirroring npm @phystack/hub-client 6.16.0). With nothing
+    configured the fallback is host candidates only: same-network connections
+    still work, and cross-NAT needs TURN anyway (which bare STUN never
+    provided).
+    """
+    url = os.environ.get("PHYSTACK_STUN_URL")
+    return [url] if url else []
+
+
 def build_ice_servers(
     options: "MediaStreamOptions",
     extra_servers: Optional[list[dict[str, Any]]] = None,
@@ -181,9 +195,7 @@ class MediaStreamOptions:
     """Options for MediaStream connection."""
 
     use_stun: bool = True
-    stun_servers: list[str] = field(
-        default_factory=lambda: ["stun:stun.l.google.com:19302", "stun:stun1.l.google.com:19302"]
-    )
+    stun_servers: list[str] = field(default_factory=_get_default_stun_servers)
     turn_servers: list[dict[str, str]] = field(default_factory=_get_default_turn_servers)
     ice_transport_policy: str = field(default_factory=_get_default_ice_transport_policy)
     connection_timeout: float = 15.0
@@ -594,7 +606,7 @@ class MediaStreamHandler:
             return []
         return servers or []
 
-    async def _build_rtc_configuration(self, use_stun: bool) -> Optional[RTCConfiguration]:
+    async def _build_rtc_configuration(self, use_stun: bool) -> RTCConfiguration:
         """Build the RTCConfiguration for one connection attempt.
 
         Provider-supplied servers take precedence (listed first). The per-attempt
@@ -613,7 +625,11 @@ class MediaStreamHandler:
         ice_servers = build_ice_servers(source_options, extra_servers)
         if not use_stun or self._options.ice_transport_policy == "relay":
             ice_servers = keep_turn_servers(ice_servers)
-        return RTCConfiguration(iceServers=ice_servers) if ice_servers else None
+        # Always pass an explicit configuration: aiortc substitutes ITS OWN
+        # default (Google STUN) when given None, which would silently
+        # reintroduce the third-party STUN this client no longer uses. An
+        # explicit empty list means host candidates only (TECH-1521).
+        return RTCConfiguration(iceServers=ice_servers)
 
     async def _create_peer_connection(self, use_stun: bool) -> RTCPeerConnection:
         """Create a fresh RTCPeerConnection and wire its track/state handlers."""

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/tests/test_client_integration.py

@@ -12,6 +12,7 @@ class FakeConnection:
         self.emitted: list[tuple[str, dict[str, Any]]] = []
         self.device_id = "device-1"
         self.ack_response: Optional[dict[str, Any]] = {"status": "success"}
+        self.handlers: dict[str, Any] = {}
 
     @property
     def is_connected(self) -> bool:
@@ -22,7 +23,7 @@ class FakeConnection:
         return True
 
     def on(self, event: str, handler: Any) -> None:
-        return None
+        self.handlers[event] = handler
 
     async def emit(
         self, method: str, payload: Any = None, callback: bool = False
@@ -95,6 +96,35 @@ async def test_device_status_cached_for_ten_seconds() -> None:
     assert status_calls.count("getDeviceStatus") == 1
 
 
+def test_twin_updated_handler_tolerates_trailing_positional_arg() -> None:
+    """Regression: some phyhub builds emit `twinUpdated` with a second
+    positional arg. python-socketio forwards every positional arg, so a
+    strict `(payload)` handler raised "takes 1 positional argument but 2 were
+    given" and dropped every twin update fleet-wide (edge apps stopped seeing
+    settings changes until restarted). The handler must accept and ignore the
+    extra arg the way JS clients do."""
+    client, connection = make_client()
+    client._setup_socket_listeners()
+
+    on_twin_updated = connection.handlers["twinUpdated"]
+    received: list[dict[str, Any]] = []
+    # Register the listener directly to keep the test on the handler's arity,
+    # not the subscribe machinery (`on_twin_update` spawns an async task).
+    client._twin_update_listeners["twin-x"] = {lambda data: received.append(data)}
+
+    payload = {
+        "twinId": "twin-x",
+        "data": {"id": "twin-x", "properties": {"desired": {"volume": 5}}},
+    }
+
+    # One positional arg (phyhub master) — the baseline that already worked.
+    on_twin_updated(payload)
+    # Two positional args (the QA build that triggered the crash) — must not raise.
+    on_twin_updated(payload, {"eventId": "evt-1"})
+
+    assert received == [payload["data"], payload["data"]]
+
+
 def test_public_exports_importable() -> None:
     import phystack.hub_client as hub_client
 

{phystack_hub_client-6.16.0 → phystack_hub_client-6.18.2}/tests/test_media_resilience.py

@@ -63,7 +63,10 @@ def make_handler(bus: FakeTwinMessageBus, options: MediaStreamOptions) -> MediaS
 # =============================================================================
 
 
-async def test_ice_servers_provider_servers_land_in_configuration_first() -> None:
+async def test_ice_servers_provider_servers_land_in_configuration_first(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PHYSTACK_STUN_URL", raising=False)
     provider_calls: list[int] = []
 
     async def provider() -> list[dict[str, Any]]:
@@ -84,11 +87,17 @@ async def test_ice_servers_provider_servers_land_in_configuration_first() -> Non
     first_url = first_server_urls[0] if isinstance(first_server_urls, list) else first_server_urls
     assert first_url == TURN_URL
     assert configuration.iceServers[0].username == "user"
-    # Static STUN entries still follow the provider list.
-    assert any(url.startswith("stun:") for url in urls)
+    # No static third-party STUN follows the provider list: with
+    # PHYSTACK_STUN_URL unset the static fallback is empty (TECH-1521), so
+    # the provider-supplied servers stand alone.
+    assert len(configuration.iceServers) == 1
+
 
+async def test_ice_servers_provider_failure_falls_back_to_static(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.delenv("PHYSTACK_STUN_URL", raising=False)
 
-async def test_ice_servers_provider_failure_falls_back_to_static() -> None:
     async def failing_provider() -> list[dict[str, Any]]:
         raise RuntimeError("phyhub unreachable")
 
@@ -99,10 +108,12 @@ async def test_ice_servers_provider_failure_falls_back_to_static() -> None:
 
     configuration = await handler._build_rtc_configuration(use_stun=True)
 
+    # TECH-1521: the static fallback carries no third-party STUN — with
+    # PHYSTACK_STUN_URL unset it is EMPTY (host candidates only), and the
+    # configuration must still be explicit (None would invoke aiortc's own
+    # Google STUN default).
     assert configuration is not None
-    urls = flatten_urls(configuration)
-    assert all(url.startswith("stun:") for url in urls)
-    assert urls  # static STUN fallback present
+    assert configuration.iceServers == []
 
 
 async def test_ice_servers_provider_timeout_falls_back_to_static(
@@ -121,10 +132,12 @@ async def test_ice_servers_provider_timeout_falls_back_to_static(
 
     configuration = await handler._build_rtc_configuration(use_stun=True)
 
+    # TECH-1521: the hung provider's TURN never lands, and the static
+    # fallback is empty (no third-party STUN) — explicit, not None.
     assert configuration is not None
     urls = flatten_urls(configuration)
     assert TURN_URL not in urls
-    assert any(url.startswith("stun:") for url in urls)
+    assert urls == []
 
 
 # =============================================================================

phystack_hub_client-6.18.2/tests/test_no_google_stun.py

@@ -0,0 +1,77 @@
+"""Guard tests for TECH-1521: no third-party STUN (Google or otherwise) may
+ever be baked into the client. STUN comes from the phyhub ice_servers_provider
+(our regional coturn) or from PHYSTACK_STUN_URL; with neither configured the
+static fallback is empty (host candidates only).
+
+Also pins the aiortc gotcha: RTCPeerConnection given NO configuration (None)
+substitutes aiortc's own default — which is Google STUN — so every
+configuration builder must return an explicit RTCConfiguration, never None.
+"""
+
+import asyncio
+import importlib
+from pathlib import Path
+
+from aiortc import RTCConfiguration
+
+import phystack.hub_client.services.webrtc.media_stream as media_stream_module
+from phystack.hub_client.services.webrtc.data_channel import DataChannelOptions
+from phystack.hub_client.services.webrtc.media_responder import MediaStreamResponder
+from phystack.hub_client.services.webrtc.media_stream import (
+    MediaStreamOptions,
+    build_ice_servers,
+)
+
+# Needles split so this file does not match its own scan.
+GOOGLE_STUN_HOST = "l.google" + ".com"
+GOOGLE_STUN_PORT = ":1930" + "2"
+
+
+def test_default_stun_servers_empty_without_env(monkeypatch) -> None:
+    monkeypatch.delenv("PHYSTACK_STUN_URL", raising=False)
+    assert MediaStreamOptions().stun_servers == []
+    assert DataChannelOptions().stun_servers == []
+
+
+def test_default_stun_servers_from_env(monkeypatch) -> None:
+    monkeypatch.setenv("PHYSTACK_STUN_URL", "stun:turn-qa.phystack.com:3478")
+    assert MediaStreamOptions().stun_servers == ["stun:turn-qa.phystack.com:3478"]
+    assert DataChannelOptions().stun_servers == ["stun:turn-qa.phystack.com:3478"]
+    for url in MediaStreamOptions().stun_servers:
+        assert "google" not in url
+        assert GOOGLE_STUN_PORT not in url
+
+
+def test_build_ice_servers_defaults_carry_no_third_party_stun(monkeypatch) -> None:
+    monkeypatch.delenv("PHYSTACK_STUN_URL", raising=False)
+    monkeypatch.delenv("PHYSTACK_TURN_URL", raising=False)
+    servers = build_ice_servers(MediaStreamOptions())
+    assert servers == []
+
+
+def test_responder_configuration_is_explicit_even_when_empty(monkeypatch) -> None:
+    # aiortc's None-configuration default is Google STUN; the builder must
+    # return an explicit (possibly empty) RTCConfiguration instead.
+    monkeypatch.delenv("PHYSTACK_STUN_URL", raising=False)
+    monkeypatch.delenv("PHYSTACK_TURN_URL", raising=False)
+    responder = MediaStreamResponder(
+        twin_id="twin-guard-test",
+        twin_messaging=None,  # type: ignore[arg-type]  # start() is never called
+        callback=lambda peer: None,
+    )
+    configuration = asyncio.run(responder._build_configuration())
+    assert isinstance(configuration, RTCConfiguration)
+    assert configuration.iceServers == []
+
+
+def test_no_google_stun_literal_anywhere_in_source() -> None:
+    package_root = Path(importlib.import_module("phystack.hub_client").__file__).parent
+    scanned = 0
+    for source_path in package_root.rglob("*.py"):
+        content = source_path.read_text(encoding="utf-8", errors="ignore")
+        assert GOOGLE_STUN_HOST not in content, f"Google STUN host in {source_path}"
+        assert GOOGLE_STUN_PORT not in content, f"Google STUN port in {source_path}"
+        scanned += 1
+    assert scanned > 10  # sanity: the walk really covered the package
+    # media_stream must exist and stay the single source of the default.
+    assert hasattr(media_stream_module, "_get_default_stun_servers")