piphi-runtime-kit-python 0.3.0__py3-none-any.whl

piphi_runtime_kit_python/runtime/events.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+"""Helpers for standardizing PiPhi runtime event payload handling."""
+
+import datetime as dt
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any, Iterable, Mapping
+from uuid import uuid4
+
+import httpx
+
+from ..schemas import (
+    CoreEventPayload,
+    EventSeverity,
+    EventTransport,
+    IntegrationEventIngestResponse,
+    IntegrationEventListResponse,
+    IntegrationEventRequest,
+)
+from .auth import RuntimeAuthContext, build_runtime_auth_headers
+from .errors import classify_core_delivery_error
+from .state import RuntimeProcessState
+
+DEFAULT_CORE_BASE_URL = "http://127.0.0.1:31419"
+DEFAULT_EVENTS_INGEST_PATH = "/api/v2/events/ingest"
+DEFAULT_TIMEOUT_SECONDS = 3.0
+
+
+def normalize_event_payload(
+    payload: IntegrationEventRequest | Mapping[str, Any],
+) -> IntegrationEventRequest:
+    """Return a validated event payload regardless of input representation."""
+    if isinstance(payload, IntegrationEventRequest):
+        return payload
+    return IntegrationEventRequest.model_validate(payload)
+
+
+def build_event_list_response(
+    events: Iterable[Mapping[str, Any] | dict[str, Any]],
+) -> IntegrationEventListResponse:
+    """Build a standard event list response from stored runtime events."""
+    return IntegrationEventListResponse(events=[dict(event) for event in events])
+
+
+def build_event_ingest_response(
+    event: Mapping[str, Any] | dict[str, Any],
+    *,
+    status: str = "accepted",
+) -> IntegrationEventIngestResponse:
+    """Build the standard response returned after an event is ingested."""
+    return IntegrationEventIngestResponse(status=status, event=dict(event))
+
+
+def format_event_log(payload: IntegrationEventRequest | Mapping[str, Any]) -> str:
+    """Build a compact, consistent log message for ingested runtime events."""
+    event = normalize_event_payload(payload)
+    return (
+        "event_ingested "
+        f"event_type={event.event_type} "
+        f"source={event.source or 'unknown'}"
+    )
+
+
+def build_core_event_payload(
+    *,
+    event_type: str,
+    integration_id: str,
+    config_id: str,
+    container_id: str,
+    device_id: str | None = None,
+    payload: Mapping[str, Any] | None = None,
+    source: str | None = None,
+    severity: EventSeverity | str = EventSeverity.info,
+    topic: str | None = None,
+    transport: EventTransport | str = EventTransport.rest,
+    event_id: str | None = None,
+    ts: str | dt.datetime | None = None,
+) -> CoreEventPayload:
+    """Build the canonical Core event payload from runtime event details."""
+    event_data = dict(payload or {})
+    if source:
+        event_data.setdefault("source", source)
+
+    if isinstance(ts, str):
+        parsed_ts = dt.datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    else:
+        parsed_ts = ts
+
+    return CoreEventPayload(
+        event_id=event_id or uuid4().hex,
+        type=event_type,
+        ts=parsed_ts or dt.datetime.now(dt.timezone.utc),
+        integration_id=integration_id,
+        config_id=config_id,
+        container_id=container_id,
+        device_id=device_id,
+        severity=severity,
+        transport=transport,
+        topic=topic,
+        data=event_data,
+    )
+
+
+@dataclass(slots=True)
+class EventClient:
+    """Thin Core events client for runtime integrations.
+
+    This mirrors the telemetry client pattern so integrations can post discrete
+    events back to Core using the same shared runtime auth and HTTP client flow.
+    """
+
+    process_state: RuntimeProcessState
+    core_base_url: str = DEFAULT_CORE_BASE_URL
+    events_ingest_path: str = DEFAULT_EVENTS_INGEST_PATH
+    timeout_seconds: float = DEFAULT_TIMEOUT_SECONDS
+
+    @property
+    def events_ingest_url(self) -> str:
+        """Return the fully qualified Core event ingest endpoint URL."""
+        return f"{self.core_base_url.rstrip('/')}{self.events_ingest_path}"
+
+    @asynccontextmanager
+    async def borrow_http_client(self):
+        """Yield a shared Core client when present, otherwise a temporary client."""
+        if self.process_state.core_http_client is not None:
+            yield self.process_state.core_http_client
+            return
+
+        async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+            yield client
+
+    async def send_event(
+        self,
+        *,
+        event_type: str,
+        integration_id: str | None,
+        config_id: str | None,
+        auth_context: RuntimeAuthContext,
+        container_id: str | None = None,
+        device_id: str | None = None,
+        payload: Mapping[str, Any] | None = None,
+        source: str | None = None,
+        severity: EventSeverity | str = EventSeverity.info,
+        topic: str | None = None,
+        event_id: str | None = None,
+        ts: str | dt.datetime | None = None,
+    ) -> bool:
+        """Send one runtime event to PiPhi Core.
+
+        Returns `False` when the runtime does not yet have enough scope
+        information to publish a canonical Core event.
+        """
+        resolved_container_id, resolved_internal_token = auth_context.resolve(
+            container_id=container_id,
+        )
+        if not resolved_container_id or not integration_id or not config_id:
+            return False
+
+        event = build_core_event_payload(
+            event_type=event_type,
+            integration_id=integration_id,
+            config_id=config_id,
+            container_id=resolved_container_id,
+            device_id=device_id,
+            payload=payload,
+            source=source,
+            severity=severity,
+            topic=topic,
+            event_id=event_id,
+            ts=ts,
+        )
+        headers = build_runtime_auth_headers(
+            container_id=resolved_container_id,
+            internal_token=resolved_internal_token,
+        )
+
+        async with self.borrow_http_client() as client:
+            try:
+                response = await client.post(
+                    self.events_ingest_url,
+                    json=event.model_dump(mode="json"),
+                    headers=headers,
+                    timeout=self.timeout_seconds,
+                )
+                response.raise_for_status()
+                return True
+            except (httpx.HTTPStatusError, httpx.ConnectError, httpx.ReadTimeout) as exc:
+                raise classify_core_delivery_error(
+                    exc=exc,
+                    operation="event_delivery",
+                    url=self.events_ingest_url,
+                    timeout_seconds=self.timeout_seconds,
+                ) from exc

piphi_runtime_kit_python/runtime/health.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+"""Helpers for standard runtime health and diagnostics responses."""
+
+from typing import Any, Mapping
+
+from ..schemas import RuntimeDiagnosticsResponse, RuntimeHealthResponse
+from .context import RuntimeContext
+
+
+def _build_runtime_snapshot(runtime_context: RuntimeContext) -> dict[str, Any]:
+    process_state = runtime_context.process_state
+    return {
+        "container_id": runtime_context.auth.container_id or None,
+        "core_auth_present": bool(runtime_context.auth.internal_token),
+        "core_http_client_bound": process_state.core_http_client is not None,
+        "current_generation": process_state.current_generation,
+        "pending_task_count": len(
+            [task for task in process_state.background_tasks if not task.done()]
+        ),
+    }
+
+
+def build_runtime_health_response(
+    runtime_context: RuntimeContext,
+    *,
+    integration: Mapping[str, Any] | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    status: str = "ok",
+) -> RuntimeHealthResponse:
+    """Build a compact health response for a PiPhi runtime integration."""
+    return RuntimeHealthResponse(
+        status=status,
+        integration=dict(integration or {}),
+        runtime=_build_runtime_snapshot(runtime_context),
+        metadata=dict(metadata or {}),
+    )
+
+
+def build_runtime_diagnostics_response(
+    runtime_context: RuntimeContext,
+    *,
+    integration: Mapping[str, Any] | None = None,
+    diagnostics: Mapping[str, Any] | None = None,
+    status: str = "ok",
+) -> RuntimeDiagnosticsResponse:
+    """Build a more detailed diagnostics response for support and debugging."""
+    payload = _build_runtime_snapshot(runtime_context)
+    payload.update(dict(diagnostics or {}))
+    return RuntimeDiagnosticsResponse(
+        status=status,
+        integration=dict(integration or {}),
+        diagnostics=payload,
+    )

piphi_runtime_kit_python/runtime/lifespan.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+"""Helpers for bootstrapping runtime auth, shared clients, and shutdown cleanup."""
+
+import os
+from contextlib import asynccontextmanager
+from typing import AsyncIterator, Awaitable, Callable
+
+import httpx
+
+from .context import RuntimeContext
+from .tasks import shutdown_background_tasks
+
+
+DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME = "PIPHI_CONTAINER_ID"
+DEFAULT_RUNTIME_INTERNAL_TOKEN_ENV_NAME = "PIPHI_INTEGRATION_INTERNAL_TOKEN"
+DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS = 10.0
+
+
+def bootstrap_runtime_auth_from_env(
+    runtime_context: RuntimeContext,
+    *,
+    container_env_name: str = DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME,
+    token_env_name: str = DEFAULT_RUNTIME_INTERNAL_TOKEN_ENV_NAME,
+) -> tuple[str, str]:
+    """Load runtime auth values from environment variables into the context."""
+    container_id = (os.getenv(container_env_name) or "").strip()
+    internal_token = (os.getenv(token_env_name) or "").strip()
+    runtime_context.auth.update(
+        container_id=container_id,
+        internal_token=internal_token,
+    )
+    return container_id, internal_token
+
+
+@asynccontextmanager
+async def bind_core_http_client(
+    runtime_context: RuntimeContext,
+    *,
+    timeout_seconds: float = DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
+) -> AsyncIterator[httpx.AsyncClient]:
+    """Bind a shared Core HTTP client to the runtime context for the duration of the scope."""
+    async with httpx.AsyncClient(timeout=timeout_seconds) as client:
+        runtime_context.set_core_http_client(client)
+        try:
+            yield client
+        finally:
+            runtime_context.set_core_http_client(None)
+
+
+@asynccontextmanager
+async def runtime_lifespan(
+    runtime_context: RuntimeContext,
+    *,
+    on_startup: Callable[[RuntimeContext, httpx.AsyncClient], Awaitable[None]] | None = None,
+    on_shutdown: Callable[[RuntimeContext], Awaitable[None]] | None = None,
+    container_env_name: str = DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME,
+    token_env_name: str = DEFAULT_RUNTIME_INTERNAL_TOKEN_ENV_NAME,
+    core_client_timeout_seconds: float = DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
+) -> AsyncIterator[RuntimeContext]:
+    """Manage a runtime's shared Core client, env auth bootstrap, and task cleanup."""
+    bootstrap_runtime_auth_from_env(
+        runtime_context,
+        container_env_name=container_env_name,
+        token_env_name=token_env_name,
+    )
+
+    async with bind_core_http_client(
+        runtime_context,
+        timeout_seconds=core_client_timeout_seconds,
+    ) as client:
+        if on_startup is not None:
+            await on_startup(runtime_context, client)
+        try:
+            yield runtime_context
+        finally:
+            await shutdown_background_tasks(runtime_context.process_state)
+            if on_shutdown is not None:
+                await on_shutdown(runtime_context)

piphi_runtime_kit_python/runtime/mqtt.py

@@ -0,0 +1,213 @@
+from __future__ import annotations
+
+"""Optional MQTT helpers for shared source-oriented data streams."""
+
+import asyncio
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+import logging
+from typing import Any, AsyncIterator, Awaitable, Callable, Iterable
+
+logger = logging.getLogger("piphi_runtime_kit_python.mqtt")
+
+DEFAULT_SOURCE_TOPIC_PREFIX = "piphi/sources"
+
+
+@dataclass(slots=True, frozen=True)
+class MqttBrokerConfig:
+    hostname: str
+    port: int = 1883
+    username: str | None = None
+    password: str | None = None
+    client_id: str | None = None
+    keepalive: int = 60
+    transport: str = "tcp"
+    qos: int = 0
+
+
+def build_source_topic_root(
+    source: str,
+    *,
+    prefix: str = DEFAULT_SOURCE_TOPIC_PREFIX,
+) -> str:
+    return f"{prefix.rstrip('/')}/{_sanitize_topic_segment(source)}"
+
+
+def build_source_packets_topic(
+    source: str,
+    *,
+    prefix: str = DEFAULT_SOURCE_TOPIC_PREFIX,
+) -> str:
+    return f"{build_source_topic_root(source, prefix=prefix)}/packets"
+
+
+def build_source_model_packets_topic(
+    source: str,
+    model: str,
+    *,
+    prefix: str = DEFAULT_SOURCE_TOPIC_PREFIX,
+) -> str:
+    return (
+        f"{build_source_topic_root(source, prefix=prefix)}"
+        f"/models/{_sanitize_topic_segment(model)}/packets"
+    )
+
+
+def build_source_status_topic(
+    source: str,
+    *,
+    prefix: str = DEFAULT_SOURCE_TOPIC_PREFIX,
+) -> str:
+    return f"{build_source_topic_root(source, prefix=prefix)}/status"
+
+
+def build_source_errors_topic(
+    source: str,
+    *,
+    prefix: str = DEFAULT_SOURCE_TOPIC_PREFIX,
+) -> str:
+    return f"{build_source_topic_root(source, prefix=prefix)}/errors"
+
+
+def build_source_packet_envelope(
+    *,
+    source: str,
+    packet: dict[str, Any],
+    received_at: str | None = None,
+    metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    model = _coerce_optional_string(packet.get("model"))
+    device_hint = {
+        "model": model,
+        "id": _coerce_optional_string(_first_present(packet, ("id", "device_id", "device", "sid", "unit"))),
+        "channel": _coerce_optional_string(_first_present(packet, ("channel", "subtype"))),
+    }
+    return {
+        "source": source,
+        "received_at": received_at or datetime.now(timezone.utc).isoformat(),
+        "model": model,
+        "device_hint": device_hint,
+        "packet": dict(packet),
+        "metadata": dict(metadata or {}),
+    }
+
+
+class MqttJsonClient:
+    """Thin JSON-oriented MQTT helper around aiomqtt."""
+
+    def __init__(self, config: MqttBrokerConfig):
+        self.config = config
+
+    @asynccontextmanager
+    async def session(self) -> AsyncIterator["_MqttJsonSession"]:
+        aiomqtt = _load_aiomqtt()
+        async with aiomqtt.Client(
+            hostname=self.config.hostname,
+            port=self.config.port,
+            username=self.config.username,
+            password=self.config.password,
+            identifier=self.config.client_id,
+            keepalive=self.config.keepalive,
+            transport=self.config.transport,
+        ) as client:
+            yield _MqttJsonSession(client=client, config=self.config)
+
+    async def run_subscription_forever(
+        self,
+        *,
+        topics: Iterable[str],
+        handler: Callable[[str, dict[str, Any]], Awaitable[None]],
+        retry_delay_seconds: float = 5.0,
+    ) -> None:
+        while True:
+            try:
+                async with self.session() as session:
+                    await session.consume_json(topics=topics, handler=handler)
+            except Exception as exc:
+                logger.warning(
+                    "mqtt_subscription_failed error=%s retrying_in=%ss",
+                    exc,
+                    retry_delay_seconds,
+                )
+            await asyncio.sleep(retry_delay_seconds)
+
+
+class _MqttJsonSession:
+    def __init__(self, *, client: Any, config: MqttBrokerConfig):
+        self.client = client
+        self.config = config
+
+    async def publish_json(
+        self,
+        topic: str,
+        payload: dict[str, Any],
+        *,
+        retain: bool = False,
+        qos: int | None = None,
+    ) -> None:
+        await self.client.publish(
+            topic,
+            payload=json.dumps(payload),
+            retain=retain,
+            qos=self.config.qos if qos is None else qos,
+        )
+
+    async def consume_json(
+        self,
+        *,
+        topics: Iterable[str],
+        handler: Callable[[str, dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        topic_list = list(topics)
+        for topic in topic_list:
+            await self.client.subscribe(topic, qos=self.config.qos)
+        async for message in self.client.messages:
+            payload = _decode_json_payload(message.payload)
+            if payload is None:
+                logger.debug("mqtt_message_skipped topic=%s", message.topic)
+                continue
+            await handler(str(message.topic), payload)
+
+
+def _decode_json_payload(payload: bytes | str | Any) -> dict[str, Any] | None:
+    if isinstance(payload, bytes):
+        text = payload.decode("utf-8", errors="replace")
+    else:
+        text = str(payload)
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    return parsed
+
+
+def _sanitize_topic_segment(value: str) -> str:
+    return str(value).strip().replace("/", "_").replace(" ", "_")
+
+
+def _coerce_optional_string(value: Any) -> str | None:
+    if value in (None, ""):
+        return None
+    return str(value)
+
+
+def _first_present(payload: dict[str, Any], keys: tuple[str, ...]) -> Any:
+    for key in keys:
+        value = payload.get(key)
+        if value not in (None, ""):
+            return value
+    return None
+
+
+def _load_aiomqtt() -> Any:
+    try:
+        import aiomqtt
+    except ImportError as exc:
+        raise RuntimeError(
+            "aiomqtt is not installed. Install piphi-runtime-kit-python with the 'mqtt' extra."
+        ) from exc
+    return aiomqtt

piphi_runtime_kit_python/runtime/registry.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+"""Typed in-memory registry helpers for runtime-managed device/config state."""
+
+import datetime as dt
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar
+
+TEntry = TypeVar("TEntry", bound=dict[str, Any])
+TState = TypeVar("TState", bound=dict[str, Any])
+TEvent = TypeVar("TEvent", bound=dict[str, Any])
+
+
+@dataclass(slots=True)
+class RuntimeRegistry(Generic[TEntry, TState, TEvent]):
+    """Small in-memory registry for runtime-managed entries, state, and events.
+
+    Core remains the source of truth for configs. This registry only tracks the
+    runtime working set currently loaded in memory.
+    """
+
+    entries: dict[str, TEntry] = field(default_factory=dict)
+    state_snapshots: dict[str, dict[str, Any]] = field(default_factory=dict)
+    recent_events: list[TEvent] = field(default_factory=list)
+    max_recent_events: int = 100
+
+    def get(self, entry_id: str) -> TEntry | None:
+        """Return one active entry by id when present."""
+        return self.entries.get(entry_id)
+
+    def set(self, entry_id: str, entry: TEntry) -> TEntry:
+        """Upsert one active entry and return the stored value."""
+        self.entries[entry_id] = entry
+        return entry
+
+    def remove(self, entry_id: str) -> TEntry | None:
+        """Remove one active entry and return the removed value when present."""
+        removed = self.entries.pop(entry_id, None)
+        self.state_snapshots.pop(entry_id, None)
+        return removed
+
+    def ids(self) -> list[str]:
+        """Return the active entry ids in insertion order."""
+        return list(self.entries.keys())
+
+    def primary_entry(self) -> TEntry | None:
+        """Return the first active entry when one exists."""
+        if not self.entries:
+            return None
+        first_entry_id = next(iter(self.entries))
+        return self.entries[first_entry_id]
+
+    def update_state(self, entry_id: str, state: dict[str, Any]) -> dict[str, Any]:
+        """Store the latest state snapshot and mirror it onto the active entry."""
+        timestamp = dt.datetime.now(dt.timezone.utc).isoformat()
+        latest_state = {
+            "device_id": entry_id,
+            "state": state,
+            "last_updated": timestamp,
+        }
+        self.state_snapshots[entry_id] = latest_state
+        if entry_id in self.entries:
+            self.entries[entry_id]["latest_state"] = state
+            self.entries[entry_id]["last_updated"] = timestamp
+        return latest_state
+
+    def append_event(self, event: TEvent) -> TEvent:
+        """Append one local event record and keep the recent-event window bounded."""
+        record = {
+            "received_at": dt.datetime.now(dt.timezone.utc).isoformat(),
+            **event,
+        }
+        typed_record = record  # satisfy generic return without runtime coercion
+        self.recent_events.append(typed_record)  # type: ignore[arg-type]
+        if len(self.recent_events) > self.max_recent_events:
+            del self.recent_events[:-self.max_recent_events]
+        return typed_record  # type: ignore[return-value]