python-oa3-client 0.1.0__py3-none-any.whl

openadr3_client/notifications.py

@@ -0,0 +1,159 @@
+"""NotificationChannel protocol and channel implementations.
+
+Provides a common interface for MqttChannel and WebhookChannel, wrapping
+the lower-level MQTTConnection and WebhookReceiver.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable, Protocol, runtime_checkable
+
+from openadr3_client.mqtt import MQTTConnection, MQTTMessage
+from openadr3_client.webhook import WebhookReceiver, WebhookMessage
+
+log = logging.getLogger(__name__)
+
+# Union of message types from either channel
+ChannelMessage = MQTTMessage | WebhookMessage
+
+
+@runtime_checkable
+class NotificationChannel(Protocol):
+    """Protocol for notification channels (MQTT, Webhook)."""
+
+    def start(self) -> None: ...
+    def stop(self) -> None: ...
+    def subscribe_topics(self, topics: list[str]) -> None: ...
+
+    @property
+    def messages(self) -> list[ChannelMessage]: ...
+
+    def await_messages(self, n: int, timeout: float = 5.0) -> list[ChannelMessage]: ...
+    def clear_messages(self) -> None: ...
+
+
+class MqttChannel:
+    """MQTT notification channel wrapping MQTTConnection.
+
+    Usage::
+
+        ch = MqttChannel("mqtt://broker:1883")
+        ch.start()
+        ch.subscribe_topics(["openadr3/programs/create"])
+        msgs = ch.await_messages(1, timeout=10.0)
+        ch.stop()
+    """
+
+    def __init__(
+        self,
+        broker_url: str,
+        client_id: str | None = None,
+        on_message: Callable[[str, Any], None] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._conn = MQTTConnection(
+            broker_url=broker_url,
+            client_id=client_id,
+            on_message=on_message,
+        )
+
+    def start(self) -> None:
+        """Connect to the MQTT broker."""
+        self._conn.connect()
+
+    def stop(self) -> None:
+        """Disconnect from the MQTT broker."""
+        self._conn.disconnect()
+
+    def subscribe_topics(self, topics: list[str]) -> None:
+        """Subscribe to MQTT topics."""
+        self._conn.subscribe(topics)
+
+    @property
+    def messages(self) -> list[MQTTMessage]:
+        return self._conn.messages
+
+    def messages_on_topic(self, topic: str) -> list[MQTTMessage]:
+        return self._conn.messages_on_topic(topic)
+
+    def await_messages(self, n: int, timeout: float = 5.0) -> list[MQTTMessage]:
+        return self._conn.await_messages(n, timeout)
+
+    def await_messages_on_topic(
+        self, topic: str, n: int, timeout: float = 5.0
+    ) -> list[MQTTMessage]:
+        return self._conn.await_messages_on_topic(topic, n, timeout)
+
+    def clear_messages(self) -> None:
+        self._conn.clear_messages()
+
+    @property
+    def is_connected(self) -> bool:
+        return self._conn.is_connected()
+
+
+class WebhookChannel:
+    """Webhook notification channel wrapping WebhookReceiver.
+
+    Usage::
+
+        ch = WebhookChannel(port=9000, bearer_token="secret")
+        ch.start()
+        print(ch.callback_url)  # Register with VTN
+        msgs = ch.await_messages(1, timeout=10.0)
+        ch.stop()
+    """
+
+    def __init__(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 0,
+        bearer_token: str | None = None,
+        path: str = "/notifications",
+        callback_host: str | None = None,
+        on_message: Callable[[str, Any], None] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._receiver = WebhookReceiver(
+            host=host,
+            port=port,
+            bearer_token=bearer_token,
+            path=path,
+            callback_host=callback_host,
+            on_message=on_message,
+        )
+
+    def start(self) -> None:
+        """Start the webhook HTTP server."""
+        self._receiver.start()
+
+    def stop(self) -> None:
+        """Stop the webhook HTTP server."""
+        self._receiver.stop()
+
+    def subscribe_topics(self, topics: list[str]) -> None:
+        """No-op for webhooks — topics are managed via VTN subscriptions."""
+        pass
+
+    @property
+    def callback_url(self) -> str:
+        return self._receiver.callback_url
+
+    @property
+    def messages(self) -> list[WebhookMessage]:
+        return self._receiver.messages
+
+    def messages_on_path(self, path: str) -> list[WebhookMessage]:
+        return self._receiver.messages_on_path(path)
+
+    def await_messages(self, n: int, timeout: float = 5.0) -> list[WebhookMessage]:
+        return self._receiver.await_messages(n, timeout)
+
+    def await_messages_on_path(
+        self, path: str, n: int, timeout: float = 5.0
+    ) -> list[WebhookMessage]:
+        return self._receiver.await_messages_on_path(path, n, timeout)
+
+    def clear_messages(self) -> None:
+        self._receiver.clear_messages()

openadr3_client/ven.py

@@ -0,0 +1,248 @@
+"""VenClient — VEN registration, program lookup, notification subscribe."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Callable
+
+import httpx
+
+from openadr3.api import success, body
+
+from openadr3_client.base import BaseClient
+from openadr3_client.notifications import (
+    MqttChannel,
+    NotificationChannel,
+    WebhookChannel,
+)
+
+log = logging.getLogger(__name__)
+
+
+def extract_topics(resp: httpx.Response) -> list[str] | None:
+    """Extract topic strings from a VTN MQTT topics response."""
+    if not success(resp):
+        return None
+    data = resp.json()
+    if not isinstance(data, dict):
+        return None
+    topics = data.get("topics", {})
+    return list(topics.values()) if topics else None
+
+
+class VenClient(BaseClient):
+    """OpenADR 3 VEN client with registration, program lookup, and notifications.
+
+    Extends BaseClient with VEN-specific capabilities:
+    - VEN registration (find-or-create by name)
+    - Program name→ID resolution with caching
+    - Notifier discovery and MQTT support detection
+    - Notification channel management (MQTT, webhook)
+    - subscribe() for topic-based notification subscription
+    - VEN-scoped topic methods that default to the registered ven_id
+    """
+
+    _client_type = "ven"
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._ven_id: str | None = None
+        self._ven_name: str | None = None
+        self._program_cache: dict[str, str] = {}  # name → id
+        self._channels: list[NotificationChannel] = []
+
+    # -- Lifecycle --
+
+    def stop(self) -> BaseClient:
+        """Stop all channels, then stop the base client."""
+        for ch in self._channels:
+            ch.stop()
+        self._channels.clear()
+        return super().stop()
+
+    # -- VEN registration --
+
+    @property
+    def ven_id(self) -> str | None:
+        return self._ven_id
+
+    @property
+    def ven_name(self) -> str | None:
+        return self._ven_name
+
+    def _require_ven_id(self) -> str:
+        if not self._ven_id:
+            raise RuntimeError("VEN not registered. Call register() first.")
+        return self._ven_id
+
+    def register(self, ven_name: str) -> VenClient:
+        """Register this VEN with the VTN. Idempotent — finds existing or creates new."""
+        with self._lock:
+            existing = self.api.find_ven_by_name(ven_name)
+            if existing:
+                vid = existing["id"]
+                log.info("VEN found, reusing: name=%s id=%s", ven_name, vid)
+            else:
+                resp = self.api.create_ven({
+                    "objectType": "VEN_VEN_REQUEST",
+                    "venName": ven_name,
+                })
+                resp.raise_for_status()
+                vid = resp.json().get("id")
+                if not vid:
+                    raise RuntimeError(
+                        f"VEN registration failed: {resp.status_code} {resp.text}"
+                    )
+                log.info("VEN registered: name=%s id=%s", ven_name, vid)
+            self._ven_id = vid
+            self._ven_name = ven_name
+        return self
+
+    # -- Program lookup --
+
+    def find_program_by_name(self, name: str) -> dict[str, Any] | None:
+        """Query VTN for a program by programName. Caches the ID on success."""
+        result = self.api.find_program_by_name(name)
+        if result and "id" in result:
+            self._program_cache[name] = result["id"]
+        return result
+
+    def resolve_program_id(self, name: str) -> str:
+        """Cached name→ID lookup. Queries VTN if not cached.
+
+        Raises KeyError if program not found.
+        """
+        if name in self._program_cache:
+            return self._program_cache[name]
+        result = self.find_program_by_name(name)
+        if not result:
+            raise KeyError(f"Program not found: {name!r}")
+        return self._program_cache[name]
+
+    # -- Notifier discovery --
+
+    def discover_notifiers(self) -> dict[str, Any] | None:
+        """GET /notifiers — discover VTN notification capabilities."""
+        resp = self.api.get_notifiers()
+        if success(resp):
+            return resp.json()
+        return None
+
+    def vtn_supports_mqtt(self) -> bool:
+        """Check if the VTN advertises MQTT notification support."""
+        notifiers = self.discover_notifiers()
+        if not notifiers:
+            return False
+        # VTN-RI returns a list of notifier dicts with "transport" field
+        if isinstance(notifiers, list):
+            return any(
+                n.get("transport", "").upper() == "MQTT" for n in notifiers
+            )
+        # Or it might be a dict with transport info
+        return "mqtt" in str(notifiers).lower()
+
+    # -- Channel management --
+
+    def add_mqtt(
+        self,
+        broker_url: str,
+        client_id: str | None = None,
+        on_message: Callable[[str, Any], None] | None = None,
+        **kwargs: Any,
+    ) -> MqttChannel:
+        """Create an MqttChannel (not started yet)."""
+        ch = MqttChannel(
+            broker_url=broker_url,
+            client_id=client_id,
+            on_message=on_message,
+            **kwargs,
+        )
+        self._channels.append(ch)
+        return ch
+
+    def add_webhook(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 0,
+        bearer_token: str | None = None,
+        path: str = "/notifications",
+        callback_host: str | None = None,
+        on_message: Callable[[str, Any], None] | None = None,
+        **kwargs: Any,
+    ) -> WebhookChannel:
+        """Create a WebhookChannel (not started yet)."""
+        ch = WebhookChannel(
+            host=host,
+            port=port,
+            bearer_token=bearer_token,
+            path=path,
+            callback_host=callback_host,
+            on_message=on_message,
+            **kwargs,
+        )
+        self._channels.append(ch)
+        return ch
+
+    # -- Subscribe --
+
+    def subscribe(
+        self,
+        program_names: list[str],
+        objects: list[str],
+        operations: list[str],
+        channel: NotificationChannel,
+    ) -> list[str]:
+        """Resolve program names to IDs, discover MQTT topics, and subscribe.
+
+        For MQTT channels: queries VTN for topics for each program and subscribes.
+        For webhook channels: creates VTN subscriptions with callback URLs.
+
+        Returns the list of topics subscribed to.
+        """
+        all_topics = []
+
+        for name in program_names:
+            program_id = self.resolve_program_id(name)
+
+            if isinstance(channel, MqttChannel):
+                # Query VTN for MQTT topics for this program's events
+                resp = self.api.get_mqtt_topics_program_events(program_id)
+                topics = extract_topics(resp)
+                if topics:
+                    channel.subscribe_topics(topics)
+                    all_topics.extend(topics)
+            elif isinstance(channel, WebhookChannel):
+                # Create a VTN subscription pointing to the webhook
+                self.api.create_subscription({
+                    "clientName": self._ven_name or "ven-client",
+                    "programID": program_id,
+                    "objectOperations": [{
+                        "objects": objects,
+                        "operations": operations,
+                        "callbackUrl": channel.callback_url,
+                        "bearerToken": channel._receiver.bearer_token,
+                    }],
+                })
+
+        return all_topics
+
+    # -- Poll events --
+
+    def poll_events(self, program_name: str) -> list:
+        """GET events filtered by program name."""
+        program_id = self.resolve_program_id(program_name)
+        return self.api.events(programID=program_id)
+
+    # -- VEN-scoped topic methods (default ven_id to registered) --
+
+    def get_mqtt_topics_ven(self, ven_id: str | None = None) -> httpx.Response:
+        return self.api.get_mqtt_topics_ven(ven_id or self._require_ven_id())
+
+    def get_mqtt_topics_ven_events(self, ven_id: str | None = None) -> httpx.Response:
+        return self.api.get_mqtt_topics_ven_events(ven_id or self._require_ven_id())
+
+    def get_mqtt_topics_ven_programs(self, ven_id: str | None = None) -> httpx.Response:
+        return self.api.get_mqtt_topics_ven_programs(ven_id or self._require_ven_id())
+
+    def get_mqtt_topics_ven_resources(self, ven_id: str | None = None) -> httpx.Response:
+        return self.api.get_mqtt_topics_ven_resources(ven_id or self._require_ven_id())

openadr3_client/webhook.py

@@ -0,0 +1,232 @@
+"""Webhook notification receiver for OpenADR 3 clients.
+
+Runs a Flask HTTP server in a background thread to receive POST
+callbacks from the VTN. Shares the same message collection interface
+as MQTTConnection.
+
+Requires the ``webhooks`` extra: ``pip install python-oa3-client[webhooks]``
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Callable
+
+import socket
+
+from openadr3.entities import coerce_notification, is_notification
+
+log = logging.getLogger(__name__)
+
+
+def detect_lan_ip() -> str:
+    """Detect this machine's LAN IP address.
+
+    Uses a UDP socket connect to a non-routable address to ask the OS
+    which network interface it would use for outbound traffic. No packets
+    are actually sent.
+
+    Returns the LAN IP as a string (e.g. "192.168.1.50").
+    Falls back to "127.0.0.1" if detection fails.
+    """
+    try:
+        s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        s.connect(("10.255.255.255", 1))
+        ip = s.getsockname()[0]
+        s.close()
+        return ip
+    except Exception:
+        return "127.0.0.1"
+
+
+@dataclass
+class WebhookMessage:
+    """A received webhook notification."""
+
+    path: str
+    payload: Any
+    time: float
+    raw_payload: bytes
+
+
+def _parse_webhook_payload(raw: bytes, path: str) -> Any:
+    """Parse webhook body as JSON, coercing notifications."""
+    try:
+        s = raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return raw
+
+    try:
+        parsed = json.loads(s)
+    except (json.JSONDecodeError, ValueError):
+        return s
+
+    if isinstance(parsed, dict) and is_notification(parsed):
+        return coerce_notification(
+            parsed, {"openadr/channel": "webhook", "openadr/path": path}
+        )
+    return parsed
+
+
+class WebhookReceiver:
+    """HTTP server that receives VTN webhook notifications.
+
+    Runs Flask in a daemon thread. The VTN POSTs notification JSON to
+    the callback URL, optionally authenticated with a Bearer token.
+
+    Usage::
+
+        receiver = WebhookReceiver(port=9000, bearer_token="my-secret")
+        receiver.start()
+        # callbackUrl = "http://my-host:9000/notifications"
+        # ... create subscription with VTN pointing to that URL ...
+        msgs = receiver.await_messages(n=1, timeout=10.0)
+        receiver.stop()
+    """
+
+    def __init__(
+        self,
+        host: str = "0.0.0.0",
+        port: int = 0,
+        bearer_token: str | None = None,
+        path: str = "/notifications",
+        callback_host: str | None = None,
+        on_message: Callable[[str, Any], None] | None = None,
+    ) -> None:
+        self.host = host
+        self.port = port
+        self.bearer_token = bearer_token
+        self.path = path
+        self.callback_host = callback_host or "127.0.0.1"
+        self.on_message_callback = on_message
+        self._messages: list[WebhookMessage] = []
+        self._lock = threading.Lock()
+        self._server_thread: threading.Thread | None = None
+        self._server: Any = None  # werkzeug Server instance
+
+    @property
+    def callback_url(self) -> str:
+        """The URL the VTN should POST notifications to.
+
+        Uses callback_host (not bind host) and the actual listening port
+        (resolved after start() when port=0).
+        """
+        return f"http://{self.callback_host}:{self.port}{self.path}"
+
+    def start(self) -> None:
+        """Start the webhook server in a background thread."""
+        try:
+            from flask import Flask, request, abort
+        except ImportError:
+            raise ImportError(
+                "Flask is required for webhook support. "
+                "Install it with: pip install python-oa3-client[webhooks]"
+            )
+
+        app = Flask(__name__)
+        # Suppress Flask/werkzeug request logging
+        flask_log = logging.getLogger("werkzeug")
+        flask_log.setLevel(logging.WARNING)
+
+        receiver = self  # capture for closure
+
+        @app.route(self.path, methods=["POST"])
+        def receive_notification():
+            # Verify bearer token if configured
+            if receiver.bearer_token:
+                auth = request.headers.get("Authorization", "")
+                if auth != f"Bearer {receiver.bearer_token}":
+                    abort(403)
+
+            raw = request.get_data()
+            path = request.path
+            parsed = _parse_webhook_payload(raw, path)
+
+            msg = WebhookMessage(
+                path=path,
+                payload=parsed,
+                time=time.time(),
+                raw_payload=raw,
+            )
+            with receiver._lock:
+                receiver._messages.append(msg)
+            log.debug("Webhook received: path=%s", path)
+
+            if receiver.on_message_callback:
+                receiver.on_message_callback(path, parsed)
+
+            return "", 200
+
+        @app.route(self.path, methods=["GET"])
+        def health():
+            return {"status": "ok"}, 200
+
+        from werkzeug.serving import make_server
+
+        self._server = make_server(self.host, self.port, app)
+        # Resolve actual port (important when port=0 for OS-assigned)
+        self.port = self._server.socket.getsockname()[1]
+        self._server_thread = threading.Thread(
+            target=self._server.serve_forever,
+            daemon=True,
+        )
+        self._server_thread.start()
+        log.info(
+            "Webhook server started: %s (bind=%s:%d)",
+            self.callback_url, self.host, self.port,
+        )
+
+    def stop(self) -> None:
+        """Stop the webhook server."""
+        if self._server:
+            self._server.shutdown()
+            self._server = None
+        if self._server_thread:
+            self._server_thread.join(timeout=5.0)
+            self._server_thread = None
+        log.info("Webhook server stopped")
+
+    @property
+    def messages(self) -> list[WebhookMessage]:
+        """All collected messages (snapshot)."""
+        with self._lock:
+            return list(self._messages)
+
+    def messages_on_path(self, path: str) -> list[WebhookMessage]:
+        """Messages received on a specific path."""
+        with self._lock:
+            return [m for m in self._messages if m.path == path]
+
+    def clear_messages(self) -> None:
+        """Clear collected messages."""
+        with self._lock:
+            self._messages.clear()
+
+    def await_messages(self, n: int, timeout: float = 5.0) -> list[WebhookMessage]:
+        """Wait until at least n messages collected, or timeout."""
+        deadline = time.time() + timeout
+        while True:
+            with self._lock:
+                if len(self._messages) >= n:
+                    return list(self._messages)
+            if time.time() >= deadline:
+                with self._lock:
+                    return list(self._messages)
+            time.sleep(0.05)
+
+    def await_messages_on_path(
+        self, path: str, n: int, timeout: float = 5.0
+    ) -> list[WebhookMessage]:
+        """Wait until at least n messages on a specific path, or timeout."""
+        deadline = time.time() + timeout
+        while True:
+            msgs = self.messages_on_path(path)
+            if len(msgs) >= n:
+                return msgs
+            if time.time() >= deadline:
+                return msgs
+            time.sleep(0.05)