phystack-hub-client 6.6.0__tar.gz → 6.8.0__tar.gz

{phystack_hub_client-6.6.0 → phystack_hub_client-6.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: phystack-hub-client
-Version: 6.6.0
+Version: 6.8.0
 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.6.0 → phystack_hub_client-6.8.0}/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.6.0"
+version = "6.8.0"
 description = "Python client for PhyHub - events, actions, DataChannel, and MediaStream"
 readme = "README.md"
 license = "MIT"

{phystack_hub_client-6.6.0 → phystack_hub_client-6.8.0}/src/phystack/hub_client/__init__.py

@@ -46,12 +46,20 @@ Or with context manager:
 
 from phystack.hub_client.client import PhyHubClient, connect_phy_client
 from phystack.hub_client.types.twin_types import (
+    PeripheralCreateResult,
+    PeripheralHandover,
+    PeripheralOwnershipLoss,
     TwinMessageResult,
     TwinMessageResultStatus,
     TwinProperties,
     TwinTypeEnum,
     TwinStatusEnum,
 )
+from phystack.hub_client.scoped_hardware_id import (
+    HARDWARE_ID_SCOPES,
+    HARDWARE_ID_USER_PART_MAX_LENGTH,
+    format_scoped_hardware_id,
+)
 from phystack.hub_client.instances import (
     BaseInstance,
     EdgeInstance,
@@ -66,6 +74,8 @@ from phystack.hub_client.services.webrtc.data_channel import (
 from phystack.hub_client.services.webrtc.media_stream import (
     MediaStreamHandler,
     MediaStreamOptions,
+    MediaTrackKind,
+    MissingMediaTrackError,
     PhygridMediaStream,
     WebcamVideoTrack,
 )
@@ -113,7 +123,7 @@ from phystack.hub_client.services.signals import (
 
 # Kept in a fixed version group with @phystack/hub-client (npm) — same
 # contract, same release version.
-__version__ = "6.5.0"
+__version__ = "6.8.0"
 __all__ = [
     # Client
     "PhyHubClient",
@@ -129,12 +139,21 @@ __all__ = [
     "TwinProperties",
     "TwinTypeEnum",
     "TwinStatusEnum",
+    # Peripheral identity + ownership (TECH-1394)
+    "PeripheralCreateResult",
+    "PeripheralHandover",
+    "PeripheralOwnershipLoss",
+    "HARDWARE_ID_SCOPES",
+    "HARDWARE_ID_USER_PART_MAX_LENGTH",
+    "format_scoped_hardware_id",
     # WebRTC
     "DataChannelHandler",
     "DataChannelOptions",
     "PhygridDataChannel",
     "MediaStreamHandler",
     "MediaStreamOptions",
+    "MediaTrackKind",
+    "MissingMediaTrackError",
     "PhygridMediaStream",
     "WebcamVideoTrack",
     "FrameSourceTrack",

{phystack_hub_client-6.6.0 → phystack_hub_client-6.8.0}/src/phystack/hub_client/client.py

@@ -83,6 +83,7 @@ class PhyHubClient:
         DISCONNECT = "disconnect"
         TWIN_MESSAGE = "twinMessage"
         TWIN_SUBSCRIBE = "twinSubscribe"
+        TWIN_UNSUBSCRIBE = "twinUnsubscribe"
         TWIN_UPDATED = "twinUpdated"
         GET_TWIN_BY_ID = "getTwinById"
         REPORT_SCREEN_PROPERTIES = "reportScreenTwinProperties"
@@ -210,7 +211,15 @@ class PhyHubClient:
         return self
 
     async def disconnect(self) -> None:
-        """Disconnect from PhyHub."""
+        """Disconnect from PhyHub.
+
+        npm 6.7.0 parity: clears the twin listener registries, cached
+        instances, subscribed-twin set, and the emit queue — listeners
+        registered before a disconnect() do not survive into a later
+        reconnect, and queued emits fail instead of hanging. The client
+        stays reusable. WebRTC connections are NOT torn down — hold the
+        stop()/close() handles from the responder/stream APIs.
+        """
         if self._cloud_app_connection:
             await self._cloud_app_connection.disconnect()
             self._cloud_app_connection = None
@@ -221,6 +230,15 @@ class PhyHubClient:
         self._instance = None
         if self._registry:
             self._registry.clear()
+        self._twin_message_listeners.clear()
+        self._twin_update_listeners.clear()
+        self._subscribed_twins.clear()
+        pending_emits, self._emit_queue = self._emit_queue, []
+        for _method, _payload, _needs_ack, pending_future in pending_emits:
+            if pending_future and not pending_future.done():
+                pending_future.set_exception(
+                    ConnectionError("disconnect() dropped the queued emit")
+                )
 
     # =========================================================================
     # Cloud-app mode (npm PhyHubClientParams.cloudApp parity)
@@ -347,10 +365,23 @@ class PhyHubClient:
             if not twin_id:
                 return
 
+            # Ownership-loss detection (TECH-1394): peripheral hardwareIds
+            # are unique tenant-wide, so another device — or another instance
+            # on THIS device — registering the same id takes our twin over.
+            # Level-triggered against the twin's current owner identity
+            # (deviceId + desired.instanceId), not edge-triggered on the
+            # takeover event itself: every later twinUpdated re-delivers the
+            # signal, so a takeover missed during a disconnect self-heals on
+            # the next twin activity. Only instances ACQUIRED as owner are
+            # considered — a consumer holding a sibling instance's peripheral
+            # legitimately sees a foreign instanceId forever.
+            if isinstance(twin_data, dict) and twin_data.get("deviceId"):
+                self._detect_peripheral_ownership_loss(twin_id, twin_data)
+
             # Notify twin update listeners
             listeners = self._twin_update_listeners.get(twin_id)
             if listeners:
-                for callback in listeners:
+                for callback in list(listeners):
                     try:
                         callback(twin_data)
                     except Exception as e:
@@ -670,6 +701,8 @@ class PhyHubClient:
         Returns:
             Updated twin data.
         """
+        from phystack.hub_client.types.twin_types import PeripheralOwnershipLoss
+
         # Dispatch to correct event based on twin type (matches Node.js behavior)
         if twin_type == TwinTypeEnum.Screen:
             event = self.EVENTS.REPORT_SCREEN_PROPERTIES
@@ -680,6 +713,19 @@ class PhyHubClient:
 
         payload = {"twinId": twin_id, "data": properties}
         result = await self._emit_to_socket(event, payload, callback=True)
+        if result and result.get("status") not in (None, "success"):
+            # Ownership-loss fallback (TECH-1394): a report rejected with
+            # PeripheralOwnershipError means another device took the twin
+            # over while we were offline — the twinUpdated notification
+            # never reached us, so revoke here.
+            if result.get("errorType") == "PeripheralOwnershipError":
+                self._handle_peripheral_ownership_lost(
+                    twin_id, PeripheralOwnershipLoss()
+                )
+            # npm 6.5.1 parity: carry the server's reason from the ack.
+            raise RuntimeError(
+                result.get("message") or "updateReportedProperties failed"
+            )
         return result.get("twin") if result else None
 
     # =========================================================================
@@ -788,6 +834,168 @@ class PhyHubClient:
             self._device_status_cache = (now, result)
         return result
 
+    async def resolve_device_space_id(self, timeout_seconds: float = 3.0) -> str:
+        """Resolve the device's current spaceId for space-scoped hardwareId
+        minting (TECH-1394). Bypasses get_device_status's 10s cache window
+        unless the cached status already carries a spaceId; otherwise asks
+        directly with its own timeout.
+
+        Raises:
+            RuntimeError: When the status request yields no answer in time or
+                the response carries no spaceId.
+        """
+        if self._device_status_cache:
+            cached_space_id = self._device_status_cache[1].get("spaceId")
+            if cached_space_id:
+                return str(cached_space_id)
+
+        try:
+            status = await asyncio.wait_for(
+                self._emit_to_socket(self.EVENTS.GET_DEVICE_STATUS, {}, callback=True),
+                timeout=timeout_seconds,
+            )
+        except asyncio.TimeoutError as timeout_error:
+            raise RuntimeError(
+                "generate_scoped_hardware_id: could not get spaceId — "
+                f"getDeviceStatus gave no answer within {timeout_seconds}s"
+            ) from timeout_error
+
+        space_id = (status or {}).get("spaceId")
+        if not space_id:
+            raise RuntimeError(
+                "generate_scoped_hardware_id: the device status response "
+                "did not include a spaceId"
+            )
+        return str(space_id)
+
+    def _detect_peripheral_ownership_loss(
+        self, twin_id: str, twin_data: dict[str, Any]
+    ) -> None:
+        """Compare an updated twin's owner identity against a pooled
+        owner-acquired peripheral instance; revoke on mismatch."""
+        from phystack.hub_client.types.twin_types import PeripheralOwnershipLoss
+
+        registry = self._registry
+        owned_peripheral = (
+            registry.get_cached_peripheral_instance(twin_id) if registry else None
+        )
+        if owned_peripheral is None or not owned_peripheral.acquired_as_owner:
+            return
+
+        own_device_id = owned_peripheral.edge_instance.device_id
+        own_instance_id = owned_peripheral.edge_instance.id
+        if not own_device_id:
+            return
+
+        updated_device_id = twin_data.get("deviceId")
+        updated_instance_id = (
+            twin_data.get("properties", {}).get("desired", {}).get("instanceId")
+        )
+        lost_to_device = updated_device_id != own_device_id
+        lost_to_instance = (
+            not lost_to_device
+            and own_instance_id is not None
+            and updated_instance_id is not None
+            and updated_instance_id != own_instance_id
+        )
+        if not lost_to_device and not lost_to_instance:
+            return
+
+        self._handle_peripheral_ownership_lost(
+            twin_id,
+            PeripheralOwnershipLoss(
+                new_owner_device_id=updated_device_id if lost_to_device else None,
+                new_owner_instance_id=(
+                    updated_instance_id if lost_to_instance else None
+                ),
+            ),
+        )
+
+    def _handle_peripheral_ownership_lost(
+        self, twin_id: str, loss: "PeripheralOwnershipLoss"
+    ) -> None:
+        """Revoke a peripheral this app lost to another device or to another
+        instance on this device (TECH-1394):
+
+        - mark the pooled PeripheralInstance ownership-lost (its
+          emit/update_reported start raising locally, its listeners are
+          dropped, on_ownership_lost fires so the app releases the hardware);
+        - drop it from the registry pool, so a later re-acquire (after taking
+          the twin back via create_peripheral_twin) builds a fresh instance;
+        - unsubscribe from the twin room, server-side AND locally — removing
+          the id from _subscribed_twins is what stops the reconnect
+          re-subscribe from silently rejoining the room we were evicted from.
+        """
+        registry = self._registry
+        peripheral_instance = (
+            registry.get_cached_peripheral_instance(twin_id) if registry else None
+        )
+        if peripheral_instance is None:
+            return
+
+        if loss.new_owner_device_id:
+            new_owner_label = f" by device {loss.new_owner_device_id}"
+        elif loss.new_owner_instance_id:
+            new_owner_label = (
+                f" by instance {loss.new_owner_instance_id} on this device"
+            )
+        else:
+            new_owner_label = ""
+        logger.warning(
+            "peripheral %s was taken over%s — revoking the local instance",
+            twin_id,
+            new_owner_label,
+        )
+
+        self._subscribed_twins.discard(twin_id)
+        if registry:
+            registry.remove_peripheral_instance(twin_id)
+
+        # Best-effort server-side unsubscribe: phyhub already evicted our
+        # sockets from the twin room at takeover; this covers the case where
+        # that eviction failed or raced our reconnect.
+        try:
+            unsubscribe_payload = {
+                "twinId": twin_id,
+                "sourceTwinId": peripheral_instance.edge_instance.id,
+            }
+            asyncio.create_task(
+                self._emit_to_socket(self.EVENTS.TWIN_UNSUBSCRIBE, unsubscribe_payload)
+            )
+        except Exception as unsubscribe_error:
+            logger.warning(
+                "Failed to send twinUnsubscribe for taken-over peripheral %s: %s",
+                twin_id,
+                unsubscribe_error,
+            )
+
+        peripheral_instance.mark_ownership_lost(loss)
+
+    def stop_responders_for_twin(self, twin_id: str) -> None:
+        """Stop any armed media/data responders publishing on a twin.
+
+        Best-effort: used by ownership-loss revocation so a taken-over
+        peripheral stops serving viewers the new owner should serve.
+        """
+        for key in list(self._media_responders):
+            if key.startswith(f"{twin_id}:"):
+                responder = self._media_responders.pop(key)
+                try:
+                    asyncio.create_task(responder.stop())
+                except Exception as stop_error:
+                    logger.warning(
+                        "Failed to stop media responder %s: %s", key, stop_error
+                    )
+        for key in list(self._data_responders):
+            if key.startswith(f"{twin_id}:"):
+                responder = self._data_responders.pop(key)
+                try:
+                    asyncio.create_task(responder.stop())
+                except Exception as stop_error:
+                    logger.warning(
+                        "Failed to stop data responder %s: %s", key, stop_error
+                    )
+
     async def get_device_instance(self) -> Optional[dict[str, Any]]:
         """Get device instance data.
 

{phystack_hub_client-6.6.0 → phystack_hub_client-6.8.0}/src/phystack/hub_client/instances/base_instance.py

@@ -109,14 +109,31 @@ class BaseInstance:
         self,
         event_type: str,
         callback: Callable[[Any, Optional[Callable[[TwinMessageResult], None]]], None],
-    ) -> None:
+    ) -> Callable[[], None]:
         """Listen for events, with optional respond callback for request-response.
 
         Args:
             event_type: Type of event to listen for.
             callback: Handler function (data, respond?) => None
+
+        Returns:
+            An unsubscribe callable that removes exactly this listener
+            (npm 6.7.0 parity).
+        """
+        return self._messaging.on(event_type, callback)
+
+    def off(
+        self,
+        event_type: str,
+        callback: Callable[[Any, Optional[Callable[[TwinMessageResult], None]]], None],
+    ) -> bool:
+        """Remove a listener registered with on(), matched by the caller's
+        original callback identity (npm 6.7.0 parity).
+
+        Returns:
+            True when a listener was found and removed.
         """
-        self._messaging.on(event_type, callback)
+        return self._messaging.off(event_type, callback)
 
     def to(self, target_twin_id: str) -> TargetedEmitter:
         """Target a specific twin for messaging.

{phystack_hub_client-6.6.0 → phystack_hub_client-6.8.0}/src/phystack/hub_client/instances/edge_instance.py

@@ -11,6 +11,7 @@ from phystack.hub_client.instances.base_instance import BaseInstance
 if TYPE_CHECKING:
     from phystack.hub_client.client import PhyHubClient
     from phystack.hub_client.twin_messaging import TwinMessaging
+    from phystack.hub_client.types.twin_types import PeripheralCreateResult
 
 logger = logging.getLogger("phystack.hub_client.instances.edge")
 
@@ -66,30 +67,46 @@ class EdgeInstance(BaseInstance):
 
     def on_update_reported(
         self, callback: Callable[[dict[str, Any]], None]
-    ) -> None:
+    ) -> Callable[[], None]:
         """Subscribe to reported property changes.
 
         Args:
             callback: Handler called with new reported properties when they change.
+
+        Returns:
+            An unsubscribe callable (npm 6.7.0 parity).
         """
         self._update_reported_listeners.add(callback)
 
         # Set up twin update listener if not already set
         self._setup_property_listeners()
 
+        def unsubscribe() -> None:
+            self._update_reported_listeners.discard(callback)
+
+        return unsubscribe
+
     def on_update_desired(
         self, callback: Callable[[dict[str, Any]], None]
-    ) -> None:
+    ) -> Callable[[], None]:
         """Subscribe to desired property changes.
 
         Args:
             callback: Handler called with new desired properties when they change.
+
+        Returns:
+            An unsubscribe callable (npm 6.7.0 parity).
         """
         self._update_desired_listeners.add(callback)
 
         # Set up twin update listener if not already set
         self._setup_property_listeners()
 
+        def unsubscribe() -> None:
+            self._update_desired_listeners.discard(callback)
+
+        return unsubscribe
+
     def _setup_property_listeners(self) -> None:
         """Set up twin update listener for property change detection.
 
@@ -148,28 +165,67 @@ class EdgeInstance(BaseInstance):
         desired_properties: Optional[dict[str, Any]] = None,
         descriptors: Optional[dict[str, str]] = None,
     ) -> dict[str, Any]:
-        """Create a new peripheral twin associated with this edge.
+        """Create or update the peripheral twin for a hardwareId (npm parity).
+
+        The server's create-or-update (keyed tenant-wide by hardwareId) is
+        the uniqueness authority — there is no client-side existence check,
+        and re-calling create is the supported re-registration path: refresh
+        the name, re-point the owner instance, update descriptor pins.
+        Requires a phyhub with the peripheral upsert (TECH-408); against
+        older phyhub versions an unconditional create can duplicate twins.
 
         Args:
             name: Name for the peripheral.
-            hardware_id: Unique hardware identifier.
-            desired_properties: Optional initial desired properties.
-            descriptors: Optional descriptors for the peripheral.
+            hardware_id: Unique hardware identifier (tenant-wide).
+            desired_properties: Optional initial desired properties (seed the
+                twin on first create only — operator-set values survive
+                re-registration).
+            descriptors: Optional descriptor version pins.
 
         Returns:
-            Created peripheral twin data.
+            The peripheral twin data (created or updated).
+
+        Raises:
+            RuntimeError: On an error ack, carrying the server's rejection
+                reason.
+        """
+        result = await self.create_peripheral_twin_detailed(
+            name, hardware_id, desired_properties, descriptors
+        )
+        if result.handover is not None:
+            previous_owner = (
+                f"device {result.handover.previous_device_id}"
+                if result.handover.previous_device_id
+                else f"instance {result.handover.previous_instance_id}"
+            )
+            logger.warning(
+                "create_peripheral_twin(): took over peripheral %s from %s "
+                "— expected once after an app move; repeated takeovers mean "
+                "two deployments share this hardwareId",
+                hardware_id,
+                previous_owner,
+            )
+        return result.twin
+
+    async def create_peripheral_twin_detailed(
+        self,
+        name: str,
+        hardware_id: str,
+        desired_properties: Optional[dict[str, Any]] = None,
+        descriptors: Optional[dict[str, str]] = None,
+    ) -> "PeripheralCreateResult":
+        """Create or update a peripheral twin, resolving the full ack (npm
+        createPeripheralTwinDetailed parity): the twin plus `created` and, on
+        a takeover, the `handover` describing the previous owner.
 
         Raises:
-            ValueError: If peripheral with same hardware_id already exists.
+            RuntimeError: On an error ack (server rejection reason in the
+                message) or a missing response.
         """
-        # Check for existing peripheral with same hardware_id
-        existing = await self.get_peripheral_twins()
-        for twin in existing:
-            props = twin.get("properties", {}).get("desired", {})
-            if props.get("hardwareId") == hardware_id:
-                raise ValueError(
-                    f"Peripheral with hardwareId {hardware_id} already exists"
-                )
+        from phystack.hub_client.types.twin_types import (
+            PeripheralCreateResult,
+            PeripheralHandover,
+        )
 
         payload = {
             "data": {
@@ -186,19 +242,82 @@ class EdgeInstance(BaseInstance):
         result = await self._client._emit_to_socket(
             "createPeripheralTwin", payload, callback=True
         )
-        return result.get("twin", {}) if result else {}
+        if not result:
+            raise RuntimeError(
+                f"createPeripheralTwin: no response for hardwareId {hardware_id}"
+            )
+        if result.get("status") != "success":
+            raise RuntimeError(
+                result.get("message")
+                or f"createPeripheralTwin failed for hardwareId {hardware_id}"
+            )
+
+        handover_data = result.get("handover")
+        return PeripheralCreateResult(
+            twin=result.get("twin", {}),
+            # Absent on older phyhub — treated as an update, not a create.
+            created=bool(result.get("created")),
+            handover=(
+                PeripheralHandover.from_dict(handover_data)
+                if isinstance(handover_data, dict)
+                else None
+            ),
+        )
 
     async def get_peripheral_twins(self) -> list[dict[str, Any]]:
-        """Get all peripheral twins for this edge instance.
+        """Get all peripheral twins owned by this edge instance.
+
+        Raises on an error ack instead of returning [] — a failed lookup used
+        to be indistinguishable from "no peripherals exist", which drove
+        find-or-create logic into duplicate registrations (npm 6.5.1 parity).
+        Callers polling in a loop must catch.
 
         Returns:
             List of peripheral twin data.
+
+        Raises:
+            RuntimeError: On an error ack, carrying the server's reason.
         """
         payload = {"data": {"instanceId": self.id}}
         result = await self._client._emit_to_socket(
             "getPeripheralTwins", payload, callback=True
         )
-        return result.get("twins", []) if result else []
+        if not result:
+            raise RuntimeError("getPeripheralTwins: no response from server")
+        if result.get("status") != "success":
+            raise RuntimeError(
+                result.get("message") or "getPeripheralTwins failed"
+            )
+        return result.get("twins") or []
+
+    async def generate_scoped_hardware_id(
+        self, user_id: str, scope: str = "global"
+    ) -> str:
+        """Mint a hardwareId carrying its uniqueness scope (TECH-1394).
+
+        Formats: `g:<id>` (global, default), `s-<spaceId>:<id>` (space —
+        survives device moves within the space), `d-<deviceId-no-dashes>:<id>`
+        (device-pinned). Violations and unresolvable scope ids raise — the
+        helper never silently falls back to an unscoped id. The pure
+        formatter is exported as `format_scoped_hardware_id`.
+
+        Args:
+            user_id: Natural identity (zone name, vendor UID, hashed URL, …);
+                max 64 chars of [a-zA-Z0-9._-].
+            scope: 'global' (default), 'space', or 'device'.
+
+        Raises:
+            ValueError: Bad user_id/scope input.
+            RuntimeError: 'space' scope when the spaceId cannot be resolved.
+        """
+        from phystack.hub_client.scoped_hardware_id import format_scoped_hardware_id
+
+        if scope == "space":
+            space_id = await self._client.resolve_device_space_id()
+            return format_scoped_hardware_id(user_id, scope, space_id)
+        if scope == "device":
+            return format_scoped_hardware_id(user_id, scope, self.device_id)
+        return format_scoped_hardware_id(user_id, scope)
 
     # =========================================================================
     # Settings API