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

piphi_runtime_kit_python/runtime/configuration.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+"""Helpers for typed runtime config handling, safe logging, and responses."""
+
+from typing import Any, Mapping, TypeVar
+
+from ..schemas import RuntimeConfig, RuntimeConfigApplyResponse, RuntimeConfigRemoveResponse
+
+TConfig = TypeVar("TConfig", bound=RuntimeConfig)
+
+DEFAULT_CONFIG_SECRET_KEYS = (
+    "password",
+    "token",
+    "secret",
+    "api_key",
+    "access_token",
+    "refresh_token",
+)
+
+
+def redact_config_secrets(
+    payload: Mapping[str, Any] | None,
+    *,
+    secret_keys: tuple[str, ...] = DEFAULT_CONFIG_SECRET_KEYS,
+) -> dict[str, Any]:
+    """Return a copy of a config payload with secret-looking values redacted."""
+    if not payload:
+        return {}
+
+    normalized_secret_keys = {key.lower() for key in secret_keys}
+    redacted: dict[str, Any] = {}
+    for key, value in payload.items():
+        if key.lower() in normalized_secret_keys and value not in (None, ""):
+            redacted[key] = "***"
+        elif isinstance(value, Mapping):
+            redacted[key] = redact_config_secrets(value, secret_keys=secret_keys)
+        elif isinstance(value, list):
+            redacted[key] = [
+                redact_config_secrets(item, secret_keys=secret_keys)
+                if isinstance(item, Mapping)
+                else item
+                for item in value
+            ]
+        else:
+            redacted[key] = value
+    return redacted
+
+
+def format_config_apply_log(
+    payload: RuntimeConfig | Mapping[str, Any],
+    *,
+    action: str = "config_apply",
+    secret_keys: tuple[str, ...] = DEFAULT_CONFIG_SECRET_KEYS,
+) -> str:
+    """Build a consistent config lifecycle log message with redacted values."""
+    raw_payload = payload.model_dump() if isinstance(payload, RuntimeConfig) else dict(payload)
+    config_id = str(raw_payload.get("id") or "missing")
+    container_id = str(raw_payload.get("container_id") or "missing")
+    redacted_payload = redact_config_secrets(raw_payload, secret_keys=secret_keys)
+    return (
+        f"{action} "
+        f"config_id={config_id} "
+        f"container_id={container_id} "
+        f"payload={redacted_payload}"
+    )
+
+
+def build_config_apply_response(
+    *,
+    config_id: str,
+    container_id: str | None = None,
+    status: str = "configured",
+    metadata: dict[str, Any] | None = None,
+) -> RuntimeConfigApplyResponse:
+    """Build the standard response returned after a config is applied."""
+    return RuntimeConfigApplyResponse(
+        status=status,
+        config_id=config_id,
+        container_id=container_id,
+        metadata=metadata or {},
+    )
+
+
+def build_config_remove_response(
+    *,
+    config_id: str,
+    removed: bool,
+    status: str = "deconfigured",
+    metadata: dict[str, Any] | None = None,
+) -> RuntimeConfigRemoveResponse:
+    """Build the standard response returned after a config removal attempt."""
+    return RuntimeConfigRemoveResponse(
+        status=status,
+        config_id=config_id,
+        removed=removed,
+        metadata=metadata or {},
+    )
+
+
+def validate_typed_config(payload: TConfig | Mapping[str, Any], config_model: type[TConfig]) -> TConfig:
+    """Validate one config payload against an integration-specific RuntimeConfig subclass."""
+    if isinstance(payload, config_model):
+        return payload
+    return config_model.model_validate(payload)
+
+
+def validate_typed_configs(
+    payloads: list[TConfig] | list[Mapping[str, Any]],
+    config_model: type[TConfig],
+) -> list[TConfig]:
+    """Validate many config payloads into one typed integration config model."""
+    return [validate_typed_config(payload, config_model) for payload in payloads]

piphi_runtime_kit_python/runtime/context.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+"""Higher-level runtime context that bundles auth and process state together."""
+
+from dataclasses import dataclass, field
+
+import httpx
+
+from .auth import RuntimeAuthContext
+from .state import RuntimeProcessState
+
+
+@dataclass(slots=True)
+class RuntimeContext:
+    """Top-level runtime helper container for simple integrations.
+
+    This is the easiest entry point when an integration wants one object that
+    carries both request/runtime auth state and process-scoped helper state.
+    """
+    auth: RuntimeAuthContext = field(default_factory=RuntimeAuthContext)
+    process_state: RuntimeProcessState = field(default_factory=RuntimeProcessState)
+
+    def set_core_http_client(self, client: httpx.AsyncClient | None) -> None:
+        """Attach or clear a shared HTTP client used for Core-bound requests."""
+        self.process_state.core_http_client = client
+
+    def set_current_generation(self, generation: int | None) -> None:
+        """Record the latest applied config generation for config sync flows."""
+        self.process_state.current_generation = generation

piphi_runtime_kit_python/runtime/discovery.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+"""Helpers for thin, framework-agnostic discovery request/response handling."""
+
+from typing import Any, Iterable, Mapping
+
+from ..schemas import IntegrationDiscoveryResponse
+
+DEFAULT_DISCOVERY_SECRET_KEYS = ("password", "token", "secret", "api_key")
+
+
+def normalize_discovery_inputs(
+    inputs: Mapping[str, Any] | None,
+    *,
+    drop_empty: bool = True,
+) -> dict[str, Any]:
+    """Normalize discovery inputs by trimming strings and dropping blank values.
+
+    This keeps runtime discovery handlers from repeating the same request-shape
+    cleanup for optional fields such as usernames, passwords, hostnames, or
+    discovery hints.
+    """
+    if not inputs:
+        return {}
+
+    normalized: dict[str, Any] = {}
+    for key, value in inputs.items():
+        if isinstance(value, str):
+            stripped = value.strip()
+            if not stripped and drop_empty:
+                continue
+            normalized[key] = stripped
+            continue
+
+        if value is None and drop_empty:
+            continue
+
+        normalized[key] = value
+
+    return normalized
+
+
+def build_discovery_response(
+    devices: Iterable[Mapping[str, Any] | dict[str, Any]],
+) -> IntegrationDiscoveryResponse:
+    """Build a standard discovery response from any iterable of device mappings."""
+    return IntegrationDiscoveryResponse(devices=[dict(device) for device in devices])
+
+
+def format_discovery_attempt_log(
+    *,
+    inputs: Mapping[str, Any] | None = None,
+    secret_keys: Iterable[str] = DEFAULT_DISCOVERY_SECRET_KEYS,
+) -> str:
+    """Build a safe log message describing a discovery attempt.
+
+    Values for secret-looking fields are never logged. Instead, the message
+    records which inputs were provided and whether any secret fields were used.
+    """
+    normalized_inputs = normalize_discovery_inputs(inputs)
+    normalized_secret_keys = {key.lower() for key in secret_keys}
+    provided_keys = sorted(normalized_inputs.keys())
+    used_secret_keys = sorted(
+        key for key in provided_keys if key.lower() in normalized_secret_keys
+    )
+    return (
+        "discovery_attempt "
+        f"input_keys={provided_keys} "
+        f"uses_secrets={bool(used_secret_keys)} "
+        f"secret_keys={used_secret_keys}"
+    )

piphi_runtime_kit_python/runtime/dispatch.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+"""Helpers for background dispatch of telemetry and event delivery."""
+
+from typing import Any, Callable, Mapping
+
+from .events import EventClient
+from .tasks import create_tracked_task
+from .telemetry import TelemetryClient
+from .auth import RuntimeAuthContext
+from .state import RuntimeProcessState
+
+EventRecorder = Callable[[dict[str, Any]], Any]
+SkipHandler = Callable[[str, dict[str, Any]], Any]
+ErrorHandler = Callable[[Exception, dict[str, Any]], Any]
+
+
+def build_local_event_record(
+    *,
+    event_type: str,
+    device: Mapping[str, Any],
+    payload: Mapping[str, Any] | None = None,
+    source: str,
+    severity: str,
+) -> dict[str, Any]:
+    """Build the canonical local runtime event record shape."""
+    return {
+        "event_type": event_type,
+        "source": source,
+        "payload": dict(payload or {}),
+        "device_id": device.get("device_id"),
+        "container_id": device.get("container_id"),
+        "integration_id": device.get("integration_id"),
+        "config_id": device.get("config_id"),
+        "severity": severity,
+    }
+
+
+async def dispatch_telemetry_delivery(
+    *,
+    telemetry_client: TelemetryClient,
+    auth_context: RuntimeAuthContext,
+    device_id: str,
+    metrics: dict[str, Any],
+    container_id: str | None = None,
+    units: dict[str, Any] | None = None,
+    timestamp: str | None = None,
+    on_skipped: SkipHandler | None = None,
+    on_error: ErrorHandler | None = None,
+) -> bool:
+    """Send telemetry and return whether a delivery attempt succeeded."""
+    resolved_container_id, _ = auth_context.resolve(container_id=container_id)
+    if not resolved_container_id:
+        if on_skipped is not None:
+            on_skipped(
+                "missing_container_id",
+                {"device_id": device_id, "container_id": container_id},
+            )
+        return False
+
+    try:
+        await telemetry_client.send_metrics(
+            device_id=device_id,
+            metrics=metrics,
+            auth_context=auth_context,
+            container_id=resolved_container_id,
+            units=units,
+            timestamp=timestamp,
+        )
+        return True
+    except Exception as exc:
+        if on_error is not None:
+            on_error(exc, {"device_id": device_id, "container_id": resolved_container_id})
+            return False
+        raise
+
+
+def schedule_telemetry_delivery(
+    *,
+    process_state: RuntimeProcessState,
+    telemetry_client: TelemetryClient,
+    auth_context: RuntimeAuthContext,
+    device_id: str,
+    metrics: dict[str, Any],
+    container_id: str | None = None,
+    units: dict[str, Any] | None = None,
+    timestamp: str | None = None,
+    on_skipped: SkipHandler | None = None,
+    on_error: ErrorHandler | None = None,
+):
+    """Schedule background telemetry delivery on the tracked runtime task set."""
+    return create_tracked_task(
+        dispatch_telemetry_delivery(
+            telemetry_client=telemetry_client,
+            auth_context=auth_context,
+            device_id=device_id,
+            metrics=metrics,
+            container_id=container_id,
+            units=units,
+            timestamp=timestamp,
+            on_skipped=on_skipped,
+            on_error=on_error,
+        ),
+        process_state=process_state,
+    )
+
+
+async def dispatch_event_delivery(
+    *,
+    event_client: EventClient,
+    auth_context: RuntimeAuthContext,
+    event_type: str,
+    device: Mapping[str, Any],
+    payload: Mapping[str, Any] | None = None,
+    source: str,
+    severity: str = "info",
+    on_skipped: SkipHandler | None = None,
+    on_error: ErrorHandler | None = None,
+) -> bool:
+    """Send one event to Core and return whether delivery succeeded."""
+    try:
+        event_sent = await event_client.send_event(
+            event_type=event_type,
+            integration_id=device.get("integration_id"),
+            config_id=device.get("config_id") or device.get("device_id"),
+            auth_context=auth_context,
+            container_id=device.get("container_id"),
+            device_id=device.get("device_id"),
+            payload=payload,
+            source=source,
+            severity=severity,
+        )
+        if not event_sent and on_skipped is not None:
+            on_skipped(
+                "missing_event_scope",
+                {
+                    "event_type": event_type,
+                    "device_id": device.get("device_id"),
+                    "container_id": device.get("container_id"),
+                    "integration_id": device.get("integration_id"),
+                    "config_id": device.get("config_id"),
+                },
+            )
+        return event_sent
+    except Exception as exc:
+        if on_error is not None:
+            on_error(
+                exc,
+                {
+                    "event_type": event_type,
+                    "device_id": device.get("device_id"),
+                    "container_id": device.get("container_id"),
+                },
+            )
+            return False
+        raise
+
+
+def schedule_event_delivery(
+    *,
+    process_state: RuntimeProcessState,
+    event_client: EventClient,
+    auth_context: RuntimeAuthContext,
+    event_type: str,
+    device: Mapping[str, Any],
+    payload: Mapping[str, Any] | None = None,
+    source: str,
+    severity: str = "info",
+    record_event: EventRecorder | None = None,
+    on_skipped: SkipHandler | None = None,
+    on_error: ErrorHandler | None = None,
+):
+    """Record an optional local event and schedule delivery to Core."""
+    if record_event is not None:
+        record_event(
+            build_local_event_record(
+                event_type=event_type,
+                device=device,
+                payload=payload,
+                source=source,
+                severity=severity,
+            )
+        )
+    return create_tracked_task(
+        dispatch_event_delivery(
+            event_client=event_client,
+            auth_context=auth_context,
+            event_type=event_type,
+            device=device,
+            payload=payload,
+            source=source,
+            severity=severity,
+            on_skipped=on_skipped,
+            on_error=on_error,
+        ),
+        process_state=process_state,
+    )

piphi_runtime_kit_python/runtime/errors.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+"""Typed delivery errors for PiPhi runtime-to-Core communication."""
+
+from dataclasses import dataclass
+
+import httpx
+
+
+@dataclass(eq=False)
+class CoreDeliveryError(Exception):
+    """Base error for failed runtime delivery attempts to PiPhi Core."""
+
+    operation: str
+    url: str
+    message: str
+    retryable: bool
+    status_code: int | None = None
+    timeout_seconds: float | None = None
+
+    def __str__(self) -> str:
+        details = [self.message, f"operation={self.operation}", f"url={self.url}"]
+        if self.status_code is not None:
+            details.append(f"status_code={self.status_code}")
+        if self.timeout_seconds is not None:
+            details.append(f"timeout_seconds={self.timeout_seconds}")
+        details.append(f"retryable={self.retryable}")
+        return " ".join(details)
+
+
+@dataclass(eq=False)
+class CoreUnavailableError(CoreDeliveryError):
+    """Raised when PiPhi Core cannot be reached over the network."""
+
+
+@dataclass(eq=False)
+class CoreTimeoutError(CoreDeliveryError):
+    """Raised when PiPhi Core does not respond before the configured timeout."""
+
+
+@dataclass(eq=False)
+class CoreRouteNotFoundError(CoreDeliveryError):
+    """Raised when the expected PiPhi Core route does not exist."""
+
+
+@dataclass(eq=False)
+class CoreAuthError(CoreDeliveryError):
+    """Raised when PiPhi Core rejects runtime authentication."""
+
+
+@dataclass(eq=False)
+class CoreServerError(CoreDeliveryError):
+    """Raised when PiPhi Core returns a 5xx response."""
+
+
+@dataclass(eq=False)
+class CoreUnexpectedResponseError(CoreDeliveryError):
+    """Raised when PiPhi Core returns an unexpected non-success response."""
+
+
+def classify_core_delivery_error(
+    *,
+    exc: Exception,
+    operation: str,
+    url: str,
+    timeout_seconds: float | None,
+) -> CoreDeliveryError:
+    """Convert raw HTTP client exceptions into stable PiPhi delivery errors."""
+    if isinstance(exc, httpx.ReadTimeout):
+        return CoreTimeoutError(
+            operation=operation,
+            url=url,
+            message="PiPhi Core did not respond before the request timeout",
+            retryable=True,
+            timeout_seconds=timeout_seconds,
+        )
+
+    if isinstance(exc, httpx.ConnectError):
+        return CoreUnavailableError(
+            operation=operation,
+            url=url,
+            message="PiPhi Core is unreachable",
+            retryable=True,
+            timeout_seconds=timeout_seconds,
+        )
+
+    if isinstance(exc, httpx.HTTPStatusError):
+        status_code = exc.response.status_code
+        if status_code == 404:
+            return CoreRouteNotFoundError(
+                operation=operation,
+                url=url,
+                message="PiPhi Core route is not available",
+                retryable=False,
+                status_code=status_code,
+                timeout_seconds=timeout_seconds,
+            )
+        if status_code in {401, 403}:
+            return CoreAuthError(
+                operation=operation,
+                url=url,
+                message="PiPhi Core rejected the runtime authentication headers",
+                retryable=False,
+                status_code=status_code,
+                timeout_seconds=timeout_seconds,
+            )
+        if 500 <= status_code <= 599:
+            return CoreServerError(
+                operation=operation,
+                url=url,
+                message="PiPhi Core failed while processing the delivery request",
+                retryable=True,
+                status_code=status_code,
+                timeout_seconds=timeout_seconds,
+            )
+        return CoreUnexpectedResponseError(
+            operation=operation,
+            url=url,
+            message="PiPhi Core returned an unexpected non-success response",
+            retryable=False,
+            status_code=status_code,
+            timeout_seconds=timeout_seconds,
+        )
+
+    return CoreUnexpectedResponseError(
+        operation=operation,
+        url=url,
+        message=str(exc) or exc.__class__.__name__,
+        retryable=False,
+        timeout_seconds=timeout_seconds,
+    )