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

phystack_hub_client-6.16.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog — phystack-hub-client (Python)
+
+Fixed version group with npm `@phystack/hub-client` (phystack/ps-platform): same
+twin/WebRTC contract, released under the same version. The PyPI workflow only
+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.16.0 — parity with npm 6.15.1 (TECH-1483)
+
+### Added
+
+- `PhyHubClient.create_web_session_code(twin_id=… | endpoint_id=…)` and
+  `PhyHubClient.subscribe_web_session_code(listener, …)`: the device-side
+  web-session claim-code issuer (npm 6.10.0 / 6.11.0, ps-platform #893, #896).
+  Same wire event (`createWebSessionCode`) and ack contract as npm; the
+  rotating issuer renews at a fraction of the code TTL with downward jitter,
+  re-mints after a socket reconnect, retries failures with capped exponential
+  backoff, and reports `unavailable` states (terminal for a non-Web twin).
+  Device sessions only, as in npm (`services/web_session_code.py`).
+
+### Parity audit — device-session semantics vs npm 6.14.0 / 6.15.0 / 6.15.1
+
+npm 6.9.0–6.15.x is mostly web-session work (browser sessions behind a web
+endpoint), which has no Python counterpart and is not needed for edge apps.
+Verified, no code change required:
+
+- Twin messages from a device are sent fire-and-forget (`_send_event` →
+  `twinMessage` without an ack callback; requests settle on the `response` twin
+  message or the 10 s timeout). npm 6.15.0 added ack-based fail-fast and
+  6.15.1 (ps-platform #927) reverted it for device sessions because the
+  edge-hub relays acks that do not describe delivery. Python never had it.
+- Consumer media dials use the client's own identity
+  (`PhyHubClient.create_media_stream(twin_id)`); the responder replies to the
+  offer's `sourceTwinId`, so this matches the 6.15.1 device behaviour.
+- Owner-only peripheral methods (`update_reported`, `update_desired`,
+  `remove`) are not gated client-side; the server decides (npm 6.15.1).
+- `disconnect()` leaves the client reusable (npm 6.14.0 fixed a cached dead
+  client on the Node side; Python re-connects through `PhyHubConnection`).
+
+Not ported (web-session only): `connect({ webApp })`, `getWebInstance()`,
+session persistence/resume, web `getPeripheralInstance()`, the `media:view`
+signaling gate (phyhub-side).
+
+## 6.8.0 — parity with npm 6.8.0 (TECH-1417)
+
+See the release notes on GitHub.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: phystack-hub-client
-Version: 6.8.0
+Version: 6.16.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
@@ -103,6 +103,35 @@ def handle_action(data, respond):
 instance.on("my-action", handle_action)
 ```
 
+### Web-session claim codes (QR for web apps)
+
+A screen/edge app can mint the claim codes a phone scans to open a web app
+session (the device side of the web-app QR flow). Identify the Web endpoint by
+exactly one of `twin_id` (the Web twin's `_id`, what a settings twin picker
+stores) or `endpoint_id` (the Web twin's `deviceId`, as shown by the Console
+and `phy web-endpoint get`).
+
+```python
+# One code — the URL is the complete link to render as a QR
+issued = await client.create_web_session_code(twin_id=settings["remoteWeb"]["id"])
+print(issued.url, issued.expires_in)
+
+# Rotating codes for a permanently displayed QR: the listener gets the initial
+# code, every rotation, a re-mint after each reconnect, and `unavailable`
+# states while minting fails (hide the QR instead of showing a dead code).
+def render(state):
+    if state.status == "active":
+        show_qr(state.url)
+    else:
+        hide_qr(state.message)
+
+subscription = client.subscribe_web_session_code(render, endpoint_id="863d9307-…")
+subscription.refresh()   # mint now
+subscription.stop()      # release timers and the reconnect listener
+```
+
+Device sessions only: phyhub registers `createWebSessionCode` on device sockets, so a cloud-app session raises immediately.
+
 ### WebRTC DataChannel
 
 ```python

{phystack_hub_client-6.8.0 → phystack_hub_client-6.16.0}/README.md

@@ -72,6 +72,35 @@ def handle_action(data, respond):
 instance.on("my-action", handle_action)
 ```
 
+### Web-session claim codes (QR for web apps)
+
+A screen/edge app can mint the claim codes a phone scans to open a web app
+session (the device side of the web-app QR flow). Identify the Web endpoint by
+exactly one of `twin_id` (the Web twin's `_id`, what a settings twin picker
+stores) or `endpoint_id` (the Web twin's `deviceId`, as shown by the Console
+and `phy web-endpoint get`).
+
+```python
+# One code — the URL is the complete link to render as a QR
+issued = await client.create_web_session_code(twin_id=settings["remoteWeb"]["id"])
+print(issued.url, issued.expires_in)
+
+# Rotating codes for a permanently displayed QR: the listener gets the initial
+# code, every rotation, a re-mint after each reconnect, and `unavailable`
+# states while minting fails (hide the QR instead of showing a dead code).
+def render(state):
+    if state.status == "active":
+        show_qr(state.url)
+    else:
+        hide_qr(state.message)
+
+subscription = client.subscribe_web_session_code(render, endpoint_id="863d9307-…")
+subscription.refresh()   # mint now
+subscription.stop()      # release timers and the reconnect listener
+```
+
+Device sessions only: phyhub registers `createWebSessionCode` on device sockets, so a cloud-app session raises immediately.
+
 ### WebRTC DataChannel
 
 ```python

{phystack_hub_client-6.8.0 → phystack_hub_client-6.16.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.8.0"
+version = "6.16.0"
 description = "Python client for PhyHub - events, actions, DataChannel, and MediaStream"
 readme = "README.md"
 license = "MIT"

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

@@ -110,6 +110,13 @@ from phystack.hub_client.services.cloud_app_connection import (
     CloudAppConnectResult,
 )
 from phystack.hub_client.cloud_twins import CloudTwinStore
+from phystack.hub_client.services.web_session_code import (
+    WebSessionCode,
+    WebSessionCodeConfigError,
+    WebSessionCodeIssuer,
+    WebSessionCodeListener,
+    WebSessionCodeState,
+)
 from phystack.hub_client.services.signals import (
     SignalsService,
     InitSignalPayload,
@@ -123,7 +130,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.8.0"
+__version__ = "6.16.0"
 __all__ = [
     # Client
     "PhyHubClient",
@@ -177,6 +184,12 @@ __all__ = [
     "CloudAppConnectionParams",
     "CloudAppConnectResult",
     "CloudTwinStore",
+    # Web-session claim codes (device-side QR issuer)
+    "WebSessionCode",
+    "WebSessionCodeConfigError",
+    "WebSessionCodeIssuer",
+    "WebSessionCodeListener",
+    "WebSessionCodeState",
     # Signals
     "SignalsService",
     "InitSignalPayload",

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

@@ -50,6 +50,14 @@ from phystack.hub_client.services.webrtc.data_responder import (
     DataChannelResponderOptions,
     ResponderChannel,
 )
+from phystack.hub_client.services.web_session_code import (
+    DEFAULT_RENEW_AT_FRACTION,
+    DEFAULT_REQUEST_TIMEOUT_SECONDS,
+    WebSessionCode,
+    WebSessionCodeIssuer,
+    WebSessionCodeListener,
+    create_web_session_code,
+)
 from phystack.hub_client.services.cloud_app_connection import (
     CloudAppConnection,
     CloudAppConnectionParams,
@@ -616,6 +624,78 @@ class PhyHubClient:
 
         return result.get("twin") if result else None
 
+    # =========================================================================
+    # Web-session claim codes (device sessions only) — npm 6.10.0 / 6.11.0 parity
+    # =========================================================================
+
+    def _assert_device_session(self, operation: str) -> None:
+        """Claim-code issuing is a device-session capability: phyhub registers
+        `createWebSessionCode` only on authenticated device sockets (a cloud
+        session would hang with no handler) — fail fast instead."""
+        if self._cloud_app_params is not None:
+            raise RuntimeError(
+                f"{operation} is only available for device sessions (screen/edge apps)"
+            )
+
+    def _web_session_code_adapter(self) -> "_WebSessionCodeAdapter":
+        return _WebSessionCodeAdapter(self)
+
+    async def create_web_session_code(
+        self,
+        *,
+        twin_id: Optional[str] = None,
+        endpoint_id: Optional[str] = None,
+        request_timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+    ) -> WebSessionCode:
+        """Mint ONE claim code for a Web endpoint (device sessions only). The
+        returned ``url`` is the complete public link
+        (``{root}/{urlId}/#code={code}``) to render as a QR. Identify the
+        endpoint by exactly one of:
+
+        - ``twin_id`` — the Web twin's ``_id``, as stored by a settings twin picker
+        - ``endpoint_id`` — the Web twin's ``deviceId``, as shown in Console/CLI
+
+        Codes expire after the endpoint's ``codeTtlSeconds``; for a
+        continuously displayed QR use :meth:`subscribe_web_session_code`, which
+        rotates them.
+        """
+        self._assert_device_session("create_web_session_code()")
+        return await create_web_session_code(
+            self._web_session_code_adapter(),
+            twin_id=twin_id,
+            endpoint_id=endpoint_id,
+            request_timeout_seconds=request_timeout_seconds,
+        )
+
+    def subscribe_web_session_code(
+        self,
+        listener: WebSessionCodeListener,
+        *,
+        twin_id: Optional[str] = None,
+        endpoint_id: Optional[str] = None,
+        renew_at_fraction: float = DEFAULT_RENEW_AT_FRACTION,
+        request_timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+    ) -> WebSessionCodeIssuer:
+        """Keep a fresh claim code available for a QR display (device sessions
+        only). ``listener`` receives a :class:`WebSessionCodeState` for the
+        initial code, every rotation (at ``renew_at_fraction`` of the code
+        TTL, with downward jitter), after every socket reconnect, and as
+        ``unavailable`` while minting fails (capped exponential backoff; a
+        non-Web twin is terminal). Returns the issuer: call ``refresh()`` to
+        mint now, ``stop()`` to release it. Must be called from a running
+        event loop.
+        """
+        self._assert_device_session("subscribe_web_session_code()")
+        issuer = WebSessionCodeIssuer(
+            self._web_session_code_adapter(),
+            listener,
+            twin_id=twin_id,
+            endpoint_id=endpoint_id,
+            renew_at_fraction=renew_at_fraction,
+            request_timeout_seconds=request_timeout_seconds,
+        )
+        return issuer.start()
+
     # =========================================================================
     # Settings API
     # =========================================================================
@@ -1334,3 +1414,31 @@ async def connect_phy_client() -> PhyHubClient:
     client = PhyHubClient.from_env()
     await client.connect()
     return client
+
+
+class _WebSessionCodeAdapter:
+    """PhyHubClient slice for the web-session code issuer (see
+    services/web_session_code.py). Kept off the client's public surface."""
+
+    def __init__(self, client: PhyHubClient) -> None:
+        self._client = client
+
+    async def ensure_connection(self) -> None:
+        connection = self._client._connection
+        if connection is not None and connection.is_connected:
+            return
+        await self._client.connect()
+
+    async def emit_with_ack(self, method: str, payload: dict[str, Any]) -> Any:
+        return await self._client._emit_to_socket(method, payload, callback=True)
+
+    async def get_twin_by_id(self, twin_id: str) -> Optional[dict[str, Any]]:
+        return await self._client.get_twin_by_id(twin_id)
+
+    def on_connect(self, handler: Callable[[], None]) -> None:
+        if self._client._connection is not None:
+            self._client._connection.on("connect", handler)
+
+    def off_connect(self, handler: Callable[[], None]) -> None:
+        if self._client._connection is not None:
+            self._client._connection.off("connect", handler)

phystack_hub_client-6.16.0/src/phystack/hub_client/services/web_session_code.py

@@ -0,0 +1,468 @@
+"""Web-session claim-code issuer (device side of the web-app QR flow).
+
+Port of npm ``@phystack/hub-client`` ``services/web-session-code.service.ts``
+(ps-platform #893 / #896, npm 6.10.0 / 6.11.0).
+
+A device session (screen/edge app) asks phyhub to mint a short-lived claim
+code for a Web endpoint via the ``createWebSessionCode`` socket event; the ack
+carries the complete public URL (``{webAppsRoot}/{urlId}/#code={code}``) that
+a phone scans as a QR to start a scoped web session. phyhub registers this
+event on authenticated device sockets only.
+
+Codes expire server-side after the endpoint's ``codeTtlSeconds``, so a QR
+display must rotate them. :class:`WebSessionCodeIssuer` owns that lifecycle so
+apps only render state:
+
+- resolves the endpointId once (a settings twin picker hands the app the Web
+  twin's ``_id``, but phyhub's issuer API requires the twin's ``deviceId``, the
+  endpointId; see :func:`resolve_web_session_endpoint_id`)
+- renews at a fraction of the code TTL (with downward jitter so a fleet of
+  screens doesn't mint in sync)
+- re-mints after a socket reconnect (the displayed code likely expired while
+  offline)
+- retries failures with capped exponential backoff, reporting an explicit
+  ``unavailable`` state so the app hides the QR instead of showing a dead code
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Awaitable, Callable, Optional, Protocol
+
+logger = logging.getLogger(__name__)
+
+# Wire name of phyhub's device-session issuer event.
+CREATE_WEB_SESSION_CODE_EVENT = "createWebSessionCode"
+
+DEFAULT_RENEW_AT_FRACTION = 0.8
+MIN_RENEW_AT_FRACTION = 0.05
+MAX_RENEW_AT_FRACTION = 0.95
+DEFAULT_REQUEST_TIMEOUT_SECONDS = 15.0
+# Downward-only jitter on the rotation delay (never pushes past the TTL fraction).
+RENEWAL_JITTER_FRACTION = 0.1
+RETRY_BACKOFF_BASE_SECONDS = 5.0
+RETRY_BACKOFF_CAP_SECONDS = 60.0
+# Never rotate faster than this, whatever the TTL says.
+MIN_ROTATION_DELAY_SECONDS = 1.0
+
+
+class WebSessionCodeConfigError(Exception):
+    """Configuration the issuer cannot retry its way out of (currently only
+    "the picked twin is not a Web twin"). Terminal: the subscription reports
+    ``unavailable`` with ``retry_at=None`` and stops."""
+
+
+@dataclass(frozen=True)
+class WebSessionCode:
+    """A minted claim code, as delivered by phyhub's ack."""
+
+    # Claim code (also embedded in ``url``).
+    code: str
+    # Complete public URL to render as a QR: ``{webAppsRoot}/{urlId}/#code={code}``.
+    url: str
+    # Code lifetime in seconds (the endpoint's ``codeTtlSeconds``).
+    expires_in: int
+    # Client-clock expiry (``now + expires_in``), timezone-aware UTC.
+    expires_at: datetime
+    # The endpointId the code was minted for.
+    endpoint_id: str
+
+
+@dataclass(frozen=True)
+class WebSessionCodeState:
+    """What a :class:`WebSessionCodeIssuer` listener receives.
+
+    ``status == "active"``: ``code``/``url``/``expires_in``/``expires_at``/
+    ``endpoint_id`` are set. ``status == "unavailable"``: ``message`` says why;
+    ``retry_at`` is when the next automatic retry fires, or ``None`` when the
+    issuer gave up (configuration error).
+    """
+
+    status: str
+    code: Optional[str] = None
+    url: Optional[str] = None
+    expires_in: Optional[int] = None
+    expires_at: Optional[datetime] = None
+    endpoint_id: Optional[str] = None
+    message: Optional[str] = None
+    retry_at: Optional[datetime] = None
+
+    @classmethod
+    def active(cls, issued: WebSessionCode) -> "WebSessionCodeState":
+        return cls(
+            status="active",
+            code=issued.code,
+            url=issued.url,
+            expires_in=issued.expires_in,
+            expires_at=issued.expires_at,
+            endpoint_id=issued.endpoint_id,
+        )
+
+    @classmethod
+    def unavailable(cls, message: str, retry_at: Optional[datetime]) -> "WebSessionCodeState":
+        return cls(status="unavailable", message=message, retry_at=retry_at)
+
+
+WebSessionCodeListener = Callable[[WebSessionCodeState], None]
+
+
+class WebSessionCodeClientAdapter(Protocol):
+    """The slice of PhyHubClient the issuer needs, so it is testable without a
+    socket. ``emit_with_ack`` follows the client's ack convention: it resolves
+    with the raw ack payload (a dict) or ``None``."""
+
+    async def ensure_connection(self) -> None: ...
+
+    async def emit_with_ack(self, method: str, payload: dict[str, Any]) -> Any: ...
+
+    async def get_twin_by_id(self, twin_id: str) -> Optional[dict[str, Any]]: ...
+
+    def on_connect(self, handler: Callable[[], None]) -> None: ...
+
+    def off_connect(self, handler: Callable[[], None]) -> None: ...
+
+
+def _describe_target(twin_id: Optional[str], endpoint_id: Optional[str]) -> str:
+    return f"twinId {twin_id}" if twin_id else f"endpointId {endpoint_id}"
+
+
+def assert_web_session_code_target(twin_id: Optional[str], endpoint_id: Optional[str]) -> None:
+    """Exactly one of twin_id / endpoint_id. Raises ``ValueError`` — this is a
+    programmer error, not a runtime condition."""
+    has_twin_id = bool(twin_id)
+    has_endpoint_id = bool(endpoint_id)
+    if has_twin_id == has_endpoint_id:
+        raise ValueError("Web session code target requires exactly one of twin_id or endpoint_id")
+
+
+async def resolve_web_session_endpoint_id(
+    client: WebSessionCodeClientAdapter,
+    twin_id: Optional[str],
+    endpoint_id: Optional[str],
+) -> str:
+    """Resolve the target to the endpointId phyhub's issuer requires (the Web
+    twin's ``deviceId``). A twin_id that resolves to a non-Web twin is a
+    terminal configuration error — a twin's type never changes, so retrying
+    cannot fix it."""
+    if endpoint_id:
+        return endpoint_id
+    twin = await client.get_twin_by_id(twin_id or "")
+    if not twin:
+        raise RuntimeError(f"Twin {twin_id} not found — cannot mint web session codes")
+    twin_type = twin.get("type")
+    if twin_type != "Web":
+        raise WebSessionCodeConfigError(
+            f"Twin {twin_id} is a {twin_type} twin, not a Web twin — check the settings picker"
+        )
+    device_id = twin.get("deviceId")
+    if not device_id:
+        raise RuntimeError(f"Web twin {twin_id} has no deviceId (endpointId) — cannot mint codes")
+    return str(device_id)
+
+
+async def _bounded(operation: Awaitable[Any], timeout_seconds: float, operation_name: str) -> Any:
+    """Bound an awaited step with a timeout so a dropped ack can never wedge
+    the mint pipeline (npm ``guardWithTimeout``). A late settlement of the
+    underlying awaitable is discarded."""
+    try:
+        return await asyncio.wait_for(operation, timeout=timeout_seconds)
+    except asyncio.TimeoutError as timeout_error:
+        raise TimeoutError(
+            f"Timed out after {timeout_seconds:g}s waiting for {operation_name}"
+        ) from timeout_error
+
+
+async def request_web_session_code(
+    client: WebSessionCodeClientAdapter,
+    endpoint_id: str,
+    request_timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+) -> WebSessionCode:
+    """Ask phyhub to mint one claim code for the endpoint. Raises on an error
+    ack, a malformed ack, or when no ack arrives within
+    ``request_timeout_seconds`` (the emit may be queued while the socket is
+    offline — the timeout keeps callers from hanging on a code that would be
+    stale by the time it arrived).
+
+    Every ack this event can produce (mirrors phyhub's WebSessionCodeAckPayload):
+    success ``{status: 'success', message, code, url, expiresIn}``; phyhub
+    failure ``{status: 'error', message: 'Failed to create web session code[: reason]'}``
+    (opaque unknown/disabled/foreign-tenant endpoint, validation, internal);
+    device offline from phyhub ``{status: 'error', message: 'PhyHub instance not found'}``
+    (edge-hub default forward); simulator ``{status: 'error', message: 'Unknown method: …'}``.
+    """
+    response = await _bounded(
+        client.emit_with_ack(CREATE_WEB_SESSION_CODE_EVENT, {"data": {"endpointId": endpoint_id}}),
+        request_timeout_seconds,
+        "the web session code ack",
+    )
+    if (
+        not isinstance(response, dict)
+        or response.get("status") != "success"
+        or not isinstance(response.get("code"), str)
+        or not isinstance(response.get("url"), str)
+        or not isinstance(response.get("expiresIn"), (int, float))
+        or isinstance(response.get("expiresIn"), bool)
+    ):
+        reason = (
+            response.get("message")
+            if isinstance(response, dict) and response.get("message")
+            else "malformed ack"
+        )
+        raise RuntimeError(f"Failed to create web session code: {reason}")
+    expires_in = int(response["expiresIn"])
+    return WebSessionCode(
+        code=response["code"],
+        url=response["url"],
+        expires_in=expires_in,
+        expires_at=datetime.now(timezone.utc) + timedelta(seconds=expires_in),
+        endpoint_id=endpoint_id,
+    )
+
+
+async def create_web_session_code(
+    client: WebSessionCodeClientAdapter,
+    *,
+    twin_id: Optional[str] = None,
+    endpoint_id: Optional[str] = None,
+    request_timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+) -> WebSessionCode:
+    """One-shot mint: resolve the endpoint, request a single code. Rotation
+    lives in :class:`WebSessionCodeIssuer`."""
+    assert_web_session_code_target(twin_id, endpoint_id)
+    logger.info(
+        "[web-session-code] Minting one web session code (%s)",
+        _describe_target(twin_id, endpoint_id),
+    )
+    await _bounded(client.ensure_connection(), request_timeout_seconds, "the hub connection")
+    resolved_endpoint_id = await _bounded(
+        resolve_web_session_endpoint_id(client, twin_id, endpoint_id),
+        request_timeout_seconds,
+        "the web endpoint twin lookup",
+    )
+    if twin_id:
+        logger.info(
+            "[web-session-code] Resolved twin %s to web endpoint %s", twin_id, resolved_endpoint_id
+        )
+    issued = await request_web_session_code(client, resolved_endpoint_id, request_timeout_seconds)
+    # Logging the URL (which embeds the code) is deliberate: the issuer runs
+    # on the device that renders that same URL as an on-screen QR.
+    logger.info(
+        "[web-session-code] Minted web session code for endpoint %s: %s (expires in %ss)",
+        resolved_endpoint_id,
+        issued.url,
+        issued.expires_in,
+    )
+    return issued
+
+
+class WebSessionCodeIssuer:
+    """Rotating issuer behind ``PhyHubClient.subscribe_web_session_code()``.
+
+    The listener receives the initial code and every rotation through the same
+    callback; all runtime failures surface as ``unavailable`` states, never as
+    exceptions. ``refresh()`` mints now; ``stop()`` releases timers and the
+    reconnect listener (idempotent).
+    """
+
+    def __init__(
+        self,
+        client: WebSessionCodeClientAdapter,
+        listener: WebSessionCodeListener,
+        *,
+        twin_id: Optional[str] = None,
+        endpoint_id: Optional[str] = None,
+        renew_at_fraction: float = DEFAULT_RENEW_AT_FRACTION,
+        request_timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS,
+        retry_backoff_base_seconds: float = RETRY_BACKOFF_BASE_SECONDS,
+        retry_backoff_cap_seconds: float = RETRY_BACKOFF_CAP_SECONDS,
+        random_source: Callable[[], float] = random.random,
+    ) -> None:
+        assert_web_session_code_target(twin_id, endpoint_id)
+        self._client = client
+        self._listener = listener
+        self._twin_id = twin_id
+        self._endpoint_id_target = endpoint_id
+        self._renew_at_fraction = min(
+            max(renew_at_fraction, MIN_RENEW_AT_FRACTION), MAX_RENEW_AT_FRACTION
+        )
+        self._request_timeout_seconds = request_timeout_seconds
+        self._retry_backoff_base_seconds = retry_backoff_base_seconds
+        self._retry_backoff_cap_seconds = retry_backoff_cap_seconds
+        self._random = random_source
+        self._stopped = False
+        self._mint_in_flight = False
+        self._endpoint_id: Optional[str] = None
+        self._consecutive_failures = 0
+        self._timer: Optional[asyncio.TimerHandle] = None
+        self._mint_task: Optional[asyncio.Task[None]] = None
+        self._reconnect_handler: Optional[Callable[[], None]] = None
+
+    @property
+    def endpoint_id(self) -> Optional[str]:
+        """The resolved endpointId, once the first mint resolved it."""
+        return self._endpoint_id
+
+    def start(self) -> "WebSessionCodeIssuer":
+        """Kick off the first mint and arm the reconnect re-mint. Never raises."""
+        logger.info(
+            "[web-session-code] Starting code subscription (%s, renew at %d%% of code TTL)",
+            _describe_target(self._twin_id, self._endpoint_id_target),
+            round(self._renew_at_fraction * 100),
+        )
+        self._arm_reconnect_listener()
+        self._spawn_mint()
+        return self
+
+    def refresh(self) -> None:
+        """Mint a new code now (cancels the pending rotation timer)."""
+        if self._stopped:
+            return
+        logger.info("[web-session-code] Refresh requested — minting a fresh code")
+        self._cancel_timer()
+        self._spawn_mint()
+
+    def stop(self) -> None:
+        """Stop rotating and release timers/listeners. Idempotent."""
+        if self._stopped:
+            return
+        self._stopped = True
+        logger.info("[web-session-code] Code subscription stopped")
+        self._cancel_timer()
+        if self._reconnect_handler is not None:
+            self._client.off_connect(self._reconnect_handler)
+            self._reconnect_handler = None
+
+    def _spawn_mint(self) -> None:
+        if self._stopped or self._mint_in_flight:
+            return
+        self._mint_task = asyncio.get_event_loop().create_task(self._run_mint())
+
+    async def _run_mint(self) -> None:
+        if self._stopped or self._mint_in_flight:
+            return
+        self._mint_in_flight = True
+        # Every awaited step below is time-bounded: an await that never
+        # settles would hold _mint_in_flight forever, and the single-flight
+        # guard would then silently kill the subscription (no retry, no state,
+        # refresh() and reconnects all no-ops).
+        try:
+            await _bounded(
+                self._client.ensure_connection(),
+                self._request_timeout_seconds,
+                "the hub connection",
+            )
+            # The socket may only exist after ensure_connection — arm late if
+            # start() ran before the client connected.
+            self._arm_reconnect_listener()
+            if self._endpoint_id is None:
+                self._endpoint_id = await _bounded(
+                    resolve_web_session_endpoint_id(
+                        self._client, self._twin_id, self._endpoint_id_target
+                    ),
+                    self._request_timeout_seconds,
+                    "the web endpoint twin lookup",
+                )
+                if self._twin_id:
+                    logger.info(
+                        "[web-session-code] Resolved twin %s to web endpoint %s",
+                        self._twin_id,
+                        self._endpoint_id,
+                    )
+            logger.info("[web-session-code] Requesting a code for endpoint %s", self._endpoint_id)
+            issued = await request_web_session_code(
+                self._client, self._endpoint_id, self._request_timeout_seconds
+            )
+            if self._stopped:
+                return
+            self._consecutive_failures = 0
+            logger.info(
+                "[web-session-code] Code active: %s (expires %s, in %ss)",
+                issued.url,
+                issued.expires_at.isoformat(),
+                issued.expires_in,
+            )
+            self._emit_state(WebSessionCodeState.active(issued))
+            self._schedule_rotation(issued.expires_in)
+        except Exception as error:  # noqa: BLE001 — every failure becomes an `unavailable` state
+            if self._stopped:
+                return
+            self._handle_mint_failure(error)
+        finally:
+            self._mint_in_flight = False
+
+    def _handle_mint_failure(self, error: Exception) -> None:
+        message = str(error)
+        if isinstance(error, WebSessionCodeConfigError):
+            logger.error(
+                "[web-session-code] Failed to mint web session code (terminal config error): %s",
+                message,
+            )
+            self._emit_state(WebSessionCodeState.unavailable(message, None))
+            return
+        self._consecutive_failures += 1
+        backoff_seconds = min(
+            self._retry_backoff_base_seconds * (2 ** (self._consecutive_failures - 1)),
+            self._retry_backoff_cap_seconds,
+        )
+        logger.warning(
+            "[web-session-code] Failed to mint web session code (attempt %d), retry in %.1fs: %s",
+            self._consecutive_failures,
+            backoff_seconds,
+            message,
+        )
+        self._emit_state(
+            WebSessionCodeState.unavailable(
+                message, datetime.now(timezone.utc) + timedelta(seconds=backoff_seconds)
+            )
+        )
+        self._schedule(backoff_seconds)
+
+    def _schedule_rotation(self, expires_in_seconds: int) -> None:
+        self._cancel_timer()
+        base_delay = expires_in_seconds * self._renew_at_fraction
+        # Downward-only jitter: rotate a bit early, never later than the fraction.
+        jittered_delay = base_delay * (1 - RENEWAL_JITTER_FRACTION * self._random())
+        delay = max(jittered_delay, MIN_ROTATION_DELAY_SECONDS)
+        logger.info("[web-session-code] Next code rotation in %ds", round(delay))
+        self._schedule(delay)
+
+    def _schedule(self, delay_seconds: float) -> None:
+        self._cancel_timer()
+
+        def fire() -> None:
+            self._timer = None
+            self._spawn_mint()
+
+        self._timer = asyncio.get_event_loop().call_later(delay_seconds, fire)
+
+    def _cancel_timer(self) -> None:
+        if self._timer is not None:
+            self._timer.cancel()
+            self._timer = None
+
+    def _arm_reconnect_listener(self) -> None:
+        """Re-mint right after a reconnect: the displayed code likely expired
+        while the socket was down, and a fresh one costs a single event."""
+        if self._stopped or self._reconnect_handler is not None:
+            return
+
+        def on_connect() -> None:
+            if self._stopped:
+                return
+            logger.info("[web-session-code] Socket reconnected — replacing the displayed code")
+            self.refresh()
+
+        self._reconnect_handler = on_connect
+        self._client.on_connect(on_connect)
+
+    def _emit_state(self, state: WebSessionCodeState) -> None:
+        try:
+            self._listener(state)
+        except Exception as listener_error:  # noqa: BLE001 — a bad listener must not stop rotation
+            logger.error(
+                "[web-session-code] Failed to notify web session code listener: %s", listener_error
+            )

phystack_hub_client-6.16.0/tests/test_web_session_code.py

@@ -0,0 +1,354 @@
+"""Web-session claim-code issuer (device side of the web-app QR flow).
+
+Port of npm `web-session-code.test.ts`: target validation, endpoint
+resolution, the mint ack contract, and the rotating issuer's lifecycle
+(rotation, backoff, refresh, reconnect re-mint, stop, listener faults,
+single-flight). Timers run on the real event loop with tiny delays.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime, timezone
+from typing import Any, Callable, Optional
+
+import pytest
+
+from phystack.hub_client.services.web_session_code import (
+    CREATE_WEB_SESSION_CODE_EVENT,
+    WebSessionCodeConfigError,
+    WebSessionCodeIssuer,
+    WebSessionCodeState,
+    assert_web_session_code_target,
+    create_web_session_code,
+    request_web_session_code,
+    resolve_web_session_endpoint_id,
+)
+
+ENDPOINT_ID = "863d9307-b06e-4fd0-bef4-2d906bcb5898"
+WEB_TWIN_ID = "6a8ff5721a1a8137a4de69d1"
+
+
+def success_ack(code: str = "VJSVALA3MB", expires_in: int = 300) -> dict[str, Any]:
+    return {
+        "status": "success",
+        "message": "Web session code created",
+        "code": code,
+        "url": f"https://w-qa.phystack.com/amco-5119/kp-office-remote/#code={code}",
+        "expiresIn": expires_in,
+    }
+
+
+class FakeClient:
+    """Scripted WebSessionCodeClientAdapter."""
+
+    def __init__(self, twin: Optional[dict[str, Any]] = None) -> None:
+        self.twin = twin
+        self.emits: list[tuple[str, dict[str, Any]]] = []
+        self.acks: list[Any] = []
+        self.ack_delay_seconds = 0.0
+        self.connect_handlers: list[Callable[[], None]] = []
+        self.ensure_connection_calls = 0
+        self.twin_lookups = 0
+        self.hang_twin_lookup = False
+
+    async def ensure_connection(self) -> None:
+        self.ensure_connection_calls += 1
+
+    async def emit_with_ack(self, method: str, payload: dict[str, Any]) -> Any:
+        self.emits.append((method, payload))
+        if self.ack_delay_seconds:
+            await asyncio.sleep(self.ack_delay_seconds)
+        if not self.acks:
+            return success_ack()
+        ack = self.acks.pop(0)
+        if isinstance(ack, Exception):
+            raise ack
+        return ack
+
+    async def get_twin_by_id(self, twin_id: str) -> Optional[dict[str, Any]]:
+        self.twin_lookups += 1
+        if self.hang_twin_lookup:
+            await asyncio.sleep(3600)
+        return self.twin
+
+    def on_connect(self, handler: Callable[[], None]) -> None:
+        self.connect_handlers.append(handler)
+
+    def off_connect(self, handler: Callable[[], None]) -> None:
+        self.connect_handlers = [
+            existing for existing in self.connect_handlers if existing is not handler
+        ]
+
+    def fire_connect(self) -> None:
+        for handler in list(self.connect_handlers):
+            handler()
+
+
+async def settle(seconds: float = 0.02) -> None:
+    await asyncio.sleep(seconds)
+
+
+def collect(states: list[WebSessionCodeState]) -> Callable[[WebSessionCodeState], None]:
+    return states.append
+
+
+def test_target_requires_exactly_one_of_twin_id_or_endpoint_id() -> None:
+    with pytest.raises(ValueError):
+        assert_web_session_code_target(WEB_TWIN_ID, ENDPOINT_ID)
+    with pytest.raises(ValueError):
+        assert_web_session_code_target(None, None)
+    assert_web_session_code_target(None, ENDPOINT_ID)
+
+
+async def test_explicit_endpoint_id_skips_the_twin_lookup() -> None:
+    client = FakeClient()
+    assert await resolve_web_session_endpoint_id(client, None, ENDPOINT_ID) == ENDPOINT_ID
+    assert client.twin_lookups == 0
+
+
+async def test_twin_id_resolves_to_the_web_twin_device_id() -> None:
+    client = FakeClient(twin={"id": WEB_TWIN_ID, "type": "Web", "deviceId": ENDPOINT_ID})
+    assert await resolve_web_session_endpoint_id(client, WEB_TWIN_ID, None) == ENDPOINT_ID
+
+
+async def test_non_web_twin_is_a_terminal_config_error() -> None:
+    client = FakeClient(twin={"id": WEB_TWIN_ID, "type": "Peripheral", "deviceId": "dev"})
+    with pytest.raises(WebSessionCodeConfigError):
+        await resolve_web_session_endpoint_id(client, WEB_TWIN_ID, None)
+
+
+async def test_request_emits_the_event_with_the_endpoint_id_and_parses_the_ack() -> None:
+    client = FakeClient()
+    issued = await request_web_session_code(client, ENDPOINT_ID)
+    assert client.emits == [(CREATE_WEB_SESSION_CODE_EVENT, {"data": {"endpointId": ENDPOINT_ID}})]
+    assert issued.code == "VJSVALA3MB"
+    assert issued.url.endswith("#code=VJSVALA3MB")
+    assert issued.expires_in == 300
+    assert issued.endpoint_id == ENDPOINT_ID
+    assert issued.expires_at.tzinfo is timezone.utc
+    assert issued.expires_at > datetime.now(timezone.utc)
+
+
+async def test_request_raises_on_an_error_ack_with_the_server_message() -> None:
+    client = FakeClient()
+    client.acks = [
+        {
+            "status": "error",
+            "message": "Failed to create web session code: Web endpoint not found or unauthorized",
+        }
+    ]
+    with pytest.raises(RuntimeError, match="Web endpoint not found or unauthorized"):
+        await request_web_session_code(client, ENDPOINT_ID)
+
+
+async def test_request_raises_on_a_malformed_ack() -> None:
+    client = FakeClient()
+    client.acks = [{"status": "success", "code": "X"}]
+    with pytest.raises(RuntimeError, match="malformed ack"):
+        await request_web_session_code(client, ENDPOINT_ID)
+
+
+async def test_request_times_out_when_no_ack_arrives() -> None:
+    client = FakeClient()
+    client.ack_delay_seconds = 1.0
+    with pytest.raises(TimeoutError, match="web session code ack"):
+        await request_web_session_code(client, ENDPOINT_ID, request_timeout_seconds=0.05)
+
+
+async def test_create_ensures_the_connection_resolves_the_twin_and_mints_once() -> None:
+    client = FakeClient(twin={"id": WEB_TWIN_ID, "type": "Web", "deviceId": ENDPOINT_ID})
+    issued = await create_web_session_code(client, twin_id=WEB_TWIN_ID)
+    assert client.ensure_connection_calls == 1
+    assert client.twin_lookups == 1
+    assert len(client.emits) == 1
+    assert issued.endpoint_id == ENDPOINT_ID
+
+
+async def test_issuer_delivers_the_initial_code_as_an_active_state() -> None:
+    client = FakeClient()
+    states: list[WebSessionCodeState] = []
+    issuer = WebSessionCodeIssuer(client, collect(states), endpoint_id=ENDPOINT_ID).start()
+    await settle()
+    assert [state.status for state in states] == ["active"]
+    assert states[0].url is not None and states[0].url.endswith("#code=VJSVALA3MB")
+    assert issuer.endpoint_id == ENDPOINT_ID
+    issuer.stop()
+
+
+async def test_issuer_rotates_at_the_renew_fraction_of_the_ttl() -> None:
+    client = FakeClient()
+    # 2 s TTL × 0.5 renew fraction = 1 s… clamped by the 1 s minimum rotation delay.
+    client.acks = [success_ack("FIRST", expires_in=2), success_ack("SECOND", expires_in=2)]
+    states: list[WebSessionCodeState] = []
+    issuer = WebSessionCodeIssuer(
+        client,
+        collect(states),
+        endpoint_id=ENDPOINT_ID,
+        renew_at_fraction=0.5,
+        random_source=lambda: 0.0,
+    ).start()
+    await settle()
+    assert [state.code for state in states] == ["FIRST"]
+    await settle(1.1)
+    assert [state.code for state in states] == ["FIRST", "SECOND"]
+    issuer.stop()
+
+
+async def test_issuer_reports_unavailable_with_backoff_and_recovers() -> None:
+    client = FakeClient()
+    client.acks = [
+        {
+            "status": "error",
+            "message": "Failed to create web session code: PhyHub instance not found",
+        },
+        success_ack("RECOVERED"),
+    ]
+    states: list[WebSessionCodeState] = []
+    issuer = WebSessionCodeIssuer(
+        client, collect(states), endpoint_id=ENDPOINT_ID, retry_backoff_base_seconds=0.05
+    ).start()
+    await settle()
+    assert states[0].status == "unavailable"
+    assert states[0].retry_at is not None
+    assert "PhyHub instance not found" in (states[0].message or "")
+    await settle(0.15)
+    assert states[-1].status == "active"
+    assert states[-1].code == "RECOVERED"
+    issuer.stop()
+
+
+async def test_issuer_stops_permanently_on_a_non_web_twin() -> None:
+    client = FakeClient(twin={"id": WEB_TWIN_ID, "type": "Peripheral", "deviceId": "dev"})
+    states: list[WebSessionCodeState] = []
+    issuer = WebSessionCodeIssuer(
+        client, collect(states), twin_id=WEB_TWIN_ID, retry_backoff_base_seconds=0.01
+    ).start()
+    await settle()
+    assert [state.status for state in states] == ["unavailable"]
+    assert states[0].retry_at is None
+    await settle(0.1)
+    assert len(states) == 1  # no retries
+    assert client.emits == []
+    issuer.stop()
+
+
+async def test_refresh_mints_immediately_and_cancels_the_rotation_timer() -> None:
+    client = FakeClient()
+    client.acks = [success_ack("FIRST", expires_in=3600), success_ack("REFRESHED", expires_in=3600)]
+    states: list[WebSessionCodeState] = []
+    issuer = WebSessionCodeIssuer(client, collect(states), endpoint_id=ENDPOINT_ID).start()
+    await settle()
+    issuer.refresh()
+    await settle()
+    assert [state.code for state in states] == ["FIRST", "REFRESHED"]
+    issuer.stop()
+
+
+async def test_issuer_re_mints_when_the_socket_reconnects() -> None:
+    client = FakeClient()
+    client.acks = [
+        success_ack("FIRST", expires_in=3600),
+        success_ack("AFTER_RECONNECT", expires_in=3600),
+    ]
+    states: list[WebSessionCodeState] = []
+    issuer = WebSessionCodeIssuer(client, collect(states), endpoint_id=ENDPOINT_ID).start()
+    await settle()
+    assert len(client.connect_handlers) == 1
+    client.fire_connect()
+    await settle()
+    assert [state.code for state in states] == ["FIRST", "AFTER_RECONNECT"]
+    issuer.stop()
+
+
+async def test_stop_detaches_the_reconnect_listener_and_silences_further_states() -> None:
+    client = FakeClient()
+    client.acks = [success_ack("FIRST", expires_in=2)]
+    states: list[WebSessionCodeState] = []
+    issuer = WebSessionCodeIssuer(
+        client,
+        collect(states),
+        endpoint_id=ENDPOINT_ID,
+        renew_at_fraction=0.5,
+        random_source=lambda: 0.0,
+    ).start()
+    await settle()
+    issuer.stop()
+    issuer.stop()  # idempotent
+    assert client.connect_handlers == []
+    client.fire_connect()
+    await settle(1.1)
+    assert len(states) == 1
+    assert len(client.emits) == 1
+
+
+async def test_issuer_survives_a_raising_listener_and_keeps_rotating() -> None:
+    client = FakeClient()
+    client.acks = [success_ack("FIRST", expires_in=2), success_ack("SECOND", expires_in=2)]
+    seen: list[str] = []
+
+    def bad_listener(state: WebSessionCodeState) -> None:
+        seen.append(state.code or state.status)
+        raise RuntimeError("render failed")
+
+    issuer = WebSessionCodeIssuer(
+        client,
+        bad_listener,
+        endpoint_id=ENDPOINT_ID,
+        renew_at_fraction=0.5,
+        random_source=lambda: 0.0,
+    ).start()
+    await settle(1.15)
+    assert seen == ["FIRST", "SECOND"]
+    issuer.stop()
+
+
+async def test_issuer_times_out_a_hung_twin_lookup_and_recovers_on_retry() -> None:
+    client = FakeClient(twin={"id": WEB_TWIN_ID, "type": "Web", "deviceId": ENDPOINT_ID})
+    client.hang_twin_lookup = True
+    states: list[WebSessionCodeState] = []
+    issuer = WebSessionCodeIssuer(
+        client,
+        collect(states),
+        twin_id=WEB_TWIN_ID,
+        request_timeout_seconds=0.05,
+        retry_backoff_base_seconds=0.05,
+    ).start()
+    await settle(0.1)
+    assert states[0].status == "unavailable"
+    assert "twin lookup" in (states[0].message or "")
+    client.hang_twin_lookup = False
+    await settle(0.15)
+    assert states[-1].status == "active"
+    issuer.stop()
+
+
+async def test_a_single_mint_stays_in_flight_when_refresh_is_spammed() -> None:
+    client = FakeClient()
+    client.ack_delay_seconds = 0.05
+    states: list[WebSessionCodeState] = []
+    issuer = WebSessionCodeIssuer(client, collect(states), endpoint_id=ENDPOINT_ID).start()
+    for _ in range(5):
+        issuer.refresh()
+    await settle(0.15)
+    assert len(client.emits) == 1
+    assert [state.status for state in states] == ["active"]
+    issuer.stop()
+
+
+async def test_client_methods_are_device_session_only() -> None:
+    from phystack.hub_client.client import PhyHubClient
+    from phystack.hub_client.services.cloud_app_connection import CloudAppConnectionParams
+
+    cloud_client = PhyHubClient(
+        cloud_app=CloudAppConnectionParams(
+            app_registration_id="app-registration-1",
+            app_secret="secret",
+            core_api_url="http://localhost:14100",
+            phyhub_url="http://localhost:14401",
+        )
+    )
+    with pytest.raises(RuntimeError, match="device sessions"):
+        await cloud_client.create_web_session_code(endpoint_id=ENDPOINT_ID)
+    with pytest.raises(RuntimeError, match="device sessions"):
+        cloud_client.subscribe_web_session_code(lambda state: None, endpoint_id=ENDPOINT_ID)