layr8 0.2.0__py3-none-any.whl

layr8/__init__.py

@@ -0,0 +1,46 @@
+"""Layr8 DIDComm Agent SDK for Python."""
+
+from .client import Client
+from .config import Config
+from .credentials import Credential, StoredCredential, VerifiedCredential
+from .errors import (
+    AlreadyConnectedError,
+    ClientClosedError,
+    ErrorKind,
+    Layr8ConnectionError,
+    Layr8Error,
+    NotConnectedError,
+    ProblemReportError,
+    SDKError,
+    ServerRejectError,
+    log_errors,
+)
+from .message import Attachment, AttachmentData, Credential, Message, MessageContext
+from .presentations import VerifiedPresentation
+from .rest import RESTError
+from .sentinel import PASS
+
+__all__ = [
+    "Attachment",
+    "AttachmentData",
+    "Client",
+    "Config",
+    "Message",
+    "MessageContext",
+    "Credential",
+    "VerifiedCredential",
+    "StoredCredential",
+    "VerifiedPresentation",
+    "RESTError",
+    "Layr8Error",
+    "NotConnectedError",
+    "AlreadyConnectedError",
+    "ClientClosedError",
+    "ProblemReportError",
+    "ServerRejectError",
+    "Layr8ConnectionError",
+    "ErrorKind",
+    "SDKError",
+    "log_errors",
+    "PASS",
+]

layr8/backoff.py

@@ -0,0 +1,22 @@
+"""Exponential backoff with a maximum delay."""
+
+from __future__ import annotations
+
+
+class Backoff:
+    """Exponential backoff with a maximum delay."""
+
+    __slots__ = ("_initial", "_max", "_current")
+
+    def __init__(self, initial: float, maximum: float) -> None:
+        self._initial = initial
+        self._max = maximum
+        self._current = initial
+
+    def next(self) -> float:
+        d = min(self._current, self._max)
+        self._current = min(self._current * 2, self._max)
+        return d
+
+    def reset(self) -> None:
+        self._current = self._initial

layr8/channel.py

@@ -0,0 +1,454 @@
+"""Phoenix Channel V2 transport over WebSocket."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import socket
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
+
+import websockets
+import websockets.asyncio.client
+
+from .backoff import Backoff
+
+
+@dataclass
+class ServerReply:
+    """Parsed reply from the Phoenix server for a sent message."""
+
+    status: str = ""
+    reason: str = ""
+
+
+def _is_localhost(host: str) -> bool:
+    """Return True if host is 'localhost' or a subdomain of it (RFC 6761)."""
+    return host == "localhost" or host.endswith(".localhost")
+
+
+def _create_localhost_socket(ws_url: str) -> socket.socket | None:
+    """
+    Create a pre-connected TCP socket to 127.0.0.1 for *.localhost URLs (RFC 6761).
+
+    The websockets library does not reliably override the Host header via
+    additional_headers when connecting to 127.0.0.1. Instead, we pre-connect
+    a raw socket to loopback and pass it to websockets.connect(), which then
+    sends the correct Host header derived from the original URL.
+
+    Returns a connected socket if the host is *.localhost, or None otherwise.
+    """
+    parsed = urlparse(ws_url)
+    hostname = parsed.hostname or ""
+    if not _is_localhost(hostname):
+        return None
+    port = parsed.port or (443 if parsed.scheme in ("wss", "https") else 80)
+    sock = socket.create_connection(("127.0.0.1", port), timeout=10)
+    return sock
+
+
+class PhoenixChannel:
+    """
+    Phoenix Channel transport over WebSocket.
+
+    Implements the same wire protocol as the Go SDK's phoenixChannel:
+    V2 JSON array format [join_ref, ref, topic, event, payload].
+    """
+
+    def __init__(
+        self,
+        ws_url: str,
+        api_key: str,
+        agent_did: str,
+        *,
+        on_message: Callable[[Any], None],
+        on_disconnect: Callable[[Exception], None] | None = None,
+        on_reconnect: Callable[[], None] | None = None,
+    ) -> None:
+        self._ws_url = ws_url
+        self._api_key = api_key
+        self._topic = f"plugins:{agent_did}"
+        self._on_message = on_message
+        self._on_disconnect = on_disconnect
+        self._on_reconnect = on_reconnect
+
+        self._ws: websockets.asyncio.client.ClientConnection | None = None
+        self._ref_counter = 0
+        self._join_ref = ""
+        self._assigned_did = ""
+        self._closed = False
+        self._reconnecting: bool = False
+        self._protocols: list[str] = []
+        self._read_task: asyncio.Task[None] | None = None
+        self._heartbeat_task: asyncio.Task[None] | None = None
+        self._reconnect_task: asyncio.Task[None] | None = None
+        self._join_future: asyncio.Future[Any] | None = None
+        self._pending_refs: dict[str, asyncio.Future[ServerReply]] = {}
+        # Monotonic timestamp (time.monotonic()) of the most recently
+        # observed inbound Phoenix frame. Powers the application-layer
+        # watchdog in _heartbeat_loop — closes #5 by detecting "TCP healthy
+        # but Phoenix Channel GenServer hung" within ~75s.
+        #
+        # WS-level liveness (TCP / NAT / LB half-dead) is covered separately
+        # by the `websockets` library's built-in ping/pong mechanism, made
+        # explicit in the connect() call below — closes #4.
+        self._last_frame_at = time.monotonic()
+        self._reply_protocol: bool = False
+
+    async def connect(self, protocols: list[str]) -> None:
+        """Establish WebSocket connection and join the Phoenix channel."""
+        self._protocols = protocols
+        await self._dial()
+
+    async def _dial(self) -> None:
+        """Open the WebSocket and join the channel (used by connect and reconnect)."""
+        self._ref_counter = 0
+
+        parsed = urlparse(self._ws_url)
+        qs = parse_qs(parsed.query)
+        qs["api_key"] = [self._api_key]
+        qs["vsn"] = ["2.0.0"]
+        new_query = urlencode(qs, doseq=True)
+        full_url = urlunparse(parsed._replace(query=new_query))
+
+        # For *.localhost, pre-connect a raw socket to 127.0.0.1 so the
+        # websockets library sends the correct Host header from the URL.
+        sock = _create_localhost_socket(full_url)
+
+        try:
+            # Explicit WS-level ping/pong (issue #4 — defense-in-depth):
+            # `websockets` defaults to ping_interval=20, ping_timeout=20
+            # which already protects against TCP / NAT / LB half-dead. We
+            # set them explicitly so a future maintainer can't accidentally
+            # disable the layer (e.g. by passing ping_interval=None in a
+            # test scenario and shipping it). 30 / 20 leaves a 50s detection
+            # window — well under AWS NLB's 350s idle timeout — and matches
+            # the policy enforced in go-sdk.
+            self._ws = await websockets.asyncio.client.connect(
+                full_url,
+                sock=sock,
+                open_timeout=10,
+                ping_interval=30,
+                ping_timeout=20,
+                close_timeout=10,
+            )
+        except Exception as exc:
+            if sock:
+                sock.close()
+            raise _make_connection_error(self._ws_url, exc) from exc
+
+        # Reset the watchdog clock so the first heartbeat tick after
+        # (re)connect measures silence from "just now", not from before
+        # the disconnect.
+        self._last_frame_at = time.monotonic()
+        self._read_task = asyncio.create_task(self._read_loop())
+        self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+
+        await self._join(self._protocols)
+
+    async def _join(self, protocols: list[str]) -> None:
+        """Send phx_join and wait for the reply."""
+        ref = self._next_ref()
+        self._join_ref = ref
+
+        join_payload: dict[str, Any] = {
+            "payload_types": protocols,
+            "reply_protocol": True,
+            "did_spec": {
+                "mode": "Create",
+                "storage": "ephemeral",
+                "type": "plugin",
+                "verificationMethods": [
+                    {"purpose": "authentication"},
+                    {"purpose": "assertionMethod"},
+                    {"purpose": "keyAgreement"},
+                ],
+            },
+        }
+
+        loop = asyncio.get_running_loop()
+        self._join_future = loop.create_future()
+
+        await self._write_msg(ref, ref, self._topic, "phx_join", join_payload)
+
+        try:
+            reply = await asyncio.wait_for(self._join_future, timeout=10)
+        except asyncio.TimeoutError:
+            raise _make_connection_error(self._ws_url, "join timed out")
+
+        status = reply.get("status")
+        if status != "ok":
+            response = reply.get("response", {})
+            reason = response.get("reason", "") if isinstance(response, dict) else ""
+            if reason:
+                raise _make_connection_error(self._ws_url, reason)
+            raise _make_connection_error(
+                self._ws_url, f"join rejected: {status}"
+            )
+
+        response = reply.get("response", {})
+        if isinstance(response, dict) and response.get("did"):
+            self._assigned_did = response["did"]
+        capabilities = response.get("capabilities", []) if isinstance(response, dict) else []
+        self._reply_protocol = "reply_protocol/1" in capabilities
+
+    async def send(self, event: str, payload: Any) -> ServerReply:
+        """Send a Phoenix Channel event and wait for server reply."""
+        ref = self._next_ref()
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future[ServerReply] = loop.create_future()
+        self._pending_refs[ref] = future
+
+        try:
+            await self._write_msg(None, ref, self._topic, event, payload)
+            return await asyncio.wait_for(future, timeout=15)
+        except asyncio.TimeoutError:
+            self._pending_refs.pop(ref, None)
+            raise
+        except Exception:
+            self._pending_refs.pop(ref, None)
+            raise
+
+    async def send_fire_and_forget(self, event: str, payload: Any) -> None:
+        """Send a Phoenix Channel event without waiting for server reply."""
+        ref = self._next_ref()
+        await self._write_msg(None, ref, self._topic, event, payload)
+
+    async def send_ack(self, ids: list[str]) -> None:
+        """Acknowledge message IDs to the cloud-node."""
+        await self.send_fire_and_forget("ack", {"ids": ids})
+
+    @property
+    def assigned_did(self) -> str:
+        return self._assigned_did
+
+    @property
+    def reply_protocol(self) -> bool:
+        return self._reply_protocol
+
+    async def close(self) -> None:
+        """Send phx_leave and shut down gracefully."""
+        if self._closed:
+            return
+        self._closed = True
+        self._reconnecting = False
+
+        if self._reconnect_task:
+            self._reconnect_task.cancel()
+            try:
+                await self._reconnect_task
+            except asyncio.CancelledError:
+                pass
+            self._reconnect_task = None
+
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+
+        # Cancel all pending ref futures
+        for ref, future in list(self._pending_refs.items()):
+            if not future.done():
+                future.cancel()
+        self._pending_refs.clear()
+
+        if self._ws:
+            try:
+                ref = self._next_ref()
+                await self._write_msg(None, ref, self._topic, "phx_leave", {})
+            except Exception:
+                pass
+            await self._ws.close()
+            self._ws = None
+
+        if self._read_task:
+            self._read_task.cancel()
+            try:
+                await self._read_task
+            except asyncio.CancelledError:
+                pass
+
+    async def _read_loop(self) -> None:
+        """Continuously read WebSocket messages and dispatch them."""
+        assert self._ws is not None
+        try:
+            async for raw in self._ws:
+                if self._closed:
+                    return
+                # Any inbound frame proves the connection is alive
+                # end-to-end — update the watchdog clock before parsing.
+                # Heartbeat ack, message event, phx_reply, phx_error,
+                # all count.
+                self._last_frame_at = time.monotonic()
+                try:
+                    arr = json.loads(raw)
+                    if not isinstance(arr, list) or len(arr) != 5:
+                        continue
+                    join_ref, ref, topic, event, payload = arr
+                    self._handle_inbound(join_ref, ref, topic, event, payload)
+                except (json.JSONDecodeError, ValueError):
+                    continue
+        except websockets.exceptions.ConnectionClosed:
+            pass
+        except Exception as exc:
+            if not self._closed:
+                if self._on_disconnect:
+                    self._on_disconnect(exc)
+                self._reject_pending_refs()
+                if not self._reconnecting:
+                    self._reconnect_task = asyncio.create_task(self._reconnect_loop())
+                return
+
+        # Iterator ended (clean close) or ConnectionClosed — trigger reconnect
+        if not self._closed:
+            if self._on_disconnect:
+                self._on_disconnect(Exception("WebSocket closed"))
+            self._reject_pending_refs()
+            if not self._reconnecting:
+                self._reconnect_task = asyncio.create_task(self._reconnect_loop())
+
+    def _handle_inbound(
+        self,
+        join_ref: str | None,
+        ref: str | None,
+        topic: str,
+        event: str,
+        payload: Any,
+    ) -> None:
+        """Route inbound Phoenix messages to the appropriate handler."""
+        if event == "phx_reply":
+            # Join reply
+            if self._join_future and not self._join_future.done() and ref == self._join_ref:
+                self._join_future.set_result(payload)
+                return
+
+            # Message send reply (ref tracking)
+            if ref and ref in self._pending_refs:
+                future = self._pending_refs.pop(ref)
+                if not future.done():
+                    status = ""
+                    reason = ""
+                    if isinstance(payload, dict):
+                        status = payload.get("status", "")
+                        response = payload.get("response", {})
+                        if isinstance(response, dict):
+                            reason = response.get("reason", "")
+                    future.set_result(ServerReply(status=status, reason=reason))
+        elif event == "message":
+            self._on_message(payload)
+        elif event in ("phx_error", "phx_close"):
+            if self._on_disconnect:
+                self._on_disconnect(Exception(f"channel {event}"))
+
+    # Maximum time a connection may be silent before the Phoenix-layer
+    # watchdog treats it as hung. 2.5× the heartbeat interval — tolerates
+    # one missed reply, trips on two consecutive misses. Catches the case
+    # where TCP + cowboy pong are healthy but cloud-node's per-tenant
+    # Phoenix Channel GenServer has stopped processing (OOM cascade,
+    # deploy window, etc.) — closes #5.
+    _HEARTBEAT_INTERVAL_S = 30
+    _HEARTBEAT_MAX_SILENT_S = 75
+
+    async def _heartbeat_loop(self) -> None:
+        """Send heartbeat every 30 seconds; close the WS if no inbound frame
+        has arrived within _HEARTBEAT_MAX_SILENT_S.
+        """
+        try:
+            while not self._closed:
+                await asyncio.sleep(self._HEARTBEAT_INTERVAL_S)
+                if self._closed or not self._ws:
+                    return
+
+                silent = time.monotonic() - self._last_frame_at
+                if silent > self._HEARTBEAT_MAX_SILENT_S:
+                    # Application-layer hang: TCP + cowboy pong are still
+                    # working (we wouldn't be here otherwise), but the
+                    # Phoenix Channel GenServer is no longer responding to
+                    # heartbeats. Close the socket; the read loop's
+                    # ConnectionClosed handler will schedule reconnect.
+                    try:
+                        await self._ws.close()
+                    except Exception:
+                        # ignore — already in a bad state
+                        pass
+                    return
+
+                ref = self._next_ref()
+                await self._write_msg(None, ref, "phoenix", "heartbeat", {})
+        except asyncio.CancelledError:
+            pass
+        except Exception:
+            pass
+
+    def _next_ref(self) -> str:
+        self._ref_counter += 1
+        return str(self._ref_counter)
+
+    async def _write_msg(
+        self,
+        join_ref: str | None,
+        ref: str | None,
+        topic: str,
+        event: str,
+        payload: Any,
+    ) -> None:
+        if not self._ws or self._reconnecting:
+            from .errors import NotConnectedError
+
+            raise NotConnectedError()
+        data = json.dumps([join_ref, ref, topic, event, payload])
+        await self._ws.send(data)
+
+    def _reject_pending_refs(self) -> None:
+        """Cancel all pending ref futures."""
+        for ref, future in list(self._pending_refs.items()):
+            if not future.done():
+                future.cancel()
+        self._pending_refs.clear()
+
+    async def _reconnect_loop(self) -> None:
+        """Attempt to reconnect with exponential backoff."""
+        if self._reconnecting:
+            return
+        self._reconnecting = True
+
+        # Clean up old connection
+        if self._ws:
+            try:
+                await self._ws.close()
+            except Exception:
+                pass
+            self._ws = None
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+
+        bo = Backoff(1.0, 30.0)
+
+        while not self._closed:
+            delay = bo.next()
+            await asyncio.sleep(delay)
+            if self._closed:
+                return
+            try:
+                self._reconnecting = False
+                await self._dial()
+                if self._on_reconnect:
+                    self._on_reconnect()
+                return
+            except Exception:
+                self._reconnecting = True
+                continue
+
+
+def _make_connection_error(
+    url: str, exc: Exception | str
+) -> Exception:
+    from .errors import Layr8ConnectionError
+
+    reason = str(exc) if isinstance(exc, Exception) else exc
+    return Layr8ConnectionError(url=url, reason=reason)