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

piphi_runtime_kit_python/__init__.py

@@ -0,0 +1,180 @@
+from .runtime.auth import (
+    RUNTIME_CONTAINER_ID_HEADER_NAME,
+    RUNTIME_INTERNAL_TOKEN_HEADER_NAME,
+    RuntimeAuthContext,
+    RuntimeAuthHeaders,
+    build_runtime_auth_headers,
+    extract_runtime_auth_headers,
+    format_runtime_auth_sync_log,
+    mask_token,
+)
+from .runtime.config_sync import ConfigSyncCoordinator, build_sync_response, reconcile_config_ids
+from .runtime.configuration import (
+    build_config_apply_response,
+    build_config_remove_response,
+    format_config_apply_log,
+    redact_config_secrets,
+    validate_typed_config,
+    validate_typed_configs,
+)
+from .runtime.context import RuntimeContext
+from .runtime.discovery import (
+    build_discovery_response,
+    format_discovery_attempt_log,
+    normalize_discovery_inputs,
+)
+from .runtime.errors import (
+    CoreAuthError,
+    CoreDeliveryError,
+    CoreRouteNotFoundError,
+    CoreServerError,
+    CoreTimeoutError,
+    CoreUnavailableError,
+    CoreUnexpectedResponseError,
+    classify_core_delivery_error,
+)
+from .runtime.dispatch import (
+    build_local_event_record,
+    dispatch_event_delivery,
+    dispatch_telemetry_delivery,
+    schedule_event_delivery,
+    schedule_telemetry_delivery,
+)
+from .runtime.events import (
+    EventClient,
+    build_core_event_payload,
+    build_event_ingest_response,
+    build_event_list_response,
+    format_event_log,
+    normalize_event_payload,
+)
+from .runtime.health import build_runtime_diagnostics_response, build_runtime_health_response
+from .runtime.lifespan import (
+    DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
+    DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME,
+    DEFAULT_RUNTIME_INTERNAL_TOKEN_ENV_NAME,
+    bind_core_http_client,
+    bootstrap_runtime_auth_from_env,
+    runtime_lifespan,
+)
+from .runtime.mqtt import (
+    DEFAULT_SOURCE_TOPIC_PREFIX,
+    MqttBrokerConfig,
+    MqttJsonClient,
+    build_source_errors_topic,
+    build_source_model_packets_topic,
+    build_source_packet_envelope,
+    build_source_packets_topic,
+    build_source_status_topic,
+    build_source_topic_root,
+)
+from .runtime.registry import RuntimeRegistry
+from .runtime.state import RuntimeProcessState
+from .runtime.starter import RuntimeStarter, create_runtime_starter
+from .runtime.tasks import create_tracked_task, shutdown_background_tasks, track_background_task
+from .runtime.telemetry import TelemetryClient, build_core_auth_headers
+from .schemas import (
+    CoreEventPayload,
+    EventSeverity,
+    EventTransport,
+    IntegrationCommandRequest,
+    IntegrationDiscoveryRequest,
+    IntegrationDiscoveryResponse,
+    IntegrationEventIngestResponse,
+    IntegrationEventListResponse,
+    IntegrationEventRequest,
+    RuntimeConfig,
+    RuntimeConfigApplyResponse,
+    RuntimeConfigRemoveResponse,
+    RuntimeConfigSnapshot,
+    RuntimeConfigSyncResponse,
+    RuntimeDiagnosticsResponse,
+    RuntimeHealthResponse,
+    TelemetryPayload,
+)
+
+__all__ = [
+    "ConfigSyncCoordinator",
+    "CoreAuthError",
+    "CoreDeliveryError",
+    "CoreRouteNotFoundError",
+    "CoreServerError",
+    "CoreTimeoutError",
+    "CoreUnavailableError",
+    "CoreUnexpectedResponseError",
+    "DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS",
+    "DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME",
+    "DEFAULT_RUNTIME_INTERNAL_TOKEN_ENV_NAME",
+    "RUNTIME_CONTAINER_ID_HEADER_NAME",
+    "RUNTIME_INTERNAL_TOKEN_HEADER_NAME",
+    "IntegrationCommandRequest",
+    "IntegrationDiscoveryRequest",
+    "IntegrationDiscoveryResponse",
+    "IntegrationEventRequest",
+    "RuntimeAuthContext",
+    "RuntimeAuthHeaders",
+    "RuntimeConfig",
+    "RuntimeConfigApplyResponse",
+    "RuntimeConfigRemoveResponse",
+    "RuntimeConfigSnapshot",
+    "RuntimeConfigSyncResponse",
+    "RuntimeContext",
+    "RuntimeRegistry",
+    "RuntimeProcessState",
+    "RuntimeStarter",
+    "RuntimeDiagnosticsResponse",
+    "RuntimeHealthResponse",
+    "TelemetryClient",
+    "EventClient",
+    "TelemetryPayload",
+    "CoreEventPayload",
+    "EventSeverity",
+    "EventTransport",
+    "IntegrationEventIngestResponse",
+    "IntegrationEventListResponse",
+    "build_discovery_response",
+    "classify_core_delivery_error",
+    "build_core_event_payload",
+    "build_event_ingest_response",
+    "build_event_list_response",
+    "build_local_event_record",
+    "build_core_auth_headers",
+    "build_config_apply_response",
+    "build_config_remove_response",
+    "build_runtime_auth_headers",
+    "build_runtime_diagnostics_response",
+    "build_runtime_health_response",
+    "build_sync_response",
+    "bind_core_http_client",
+    "bootstrap_runtime_auth_from_env",
+    "create_tracked_task",
+    "create_runtime_starter",
+    "dispatch_event_delivery",
+    "dispatch_telemetry_delivery",
+    "extract_runtime_auth_headers",
+    "format_config_apply_log",
+    "format_discovery_attempt_log",
+    "format_event_log",
+    "format_runtime_auth_sync_log",
+    "mask_token",
+    "MqttBrokerConfig",
+    "MqttJsonClient",
+    "normalize_discovery_inputs",
+    "normalize_event_payload",
+    "redact_config_secrets",
+    "reconcile_config_ids",
+    "runtime_lifespan",
+    "schedule_event_delivery",
+    "schedule_telemetry_delivery",
+    "shutdown_background_tasks",
+    "track_background_task",
+    "validate_typed_config",
+    "validate_typed_configs",
+    "DEFAULT_SOURCE_TOPIC_PREFIX",
+    "build_source_errors_topic",
+    "build_source_model_packets_topic",
+    "build_source_packet_envelope",
+    "build_source_packets_topic",
+    "build_source_status_topic",
+    "build_source_topic_root",
+]

piphi_runtime_kit_python/adapters/__init__.py

@@ -0,0 +1,13 @@
+"""Optional framework adapters layered on top of the core runtime helpers."""
+
+from .fastapi import (
+    get_payload_container_id,
+    sync_runtime_auth_from_fastapi_payload,
+    sync_runtime_auth_from_fastapi_request,
+)
+
+__all__ = [
+    "get_payload_container_id",
+    "sync_runtime_auth_from_fastapi_payload",
+    "sync_runtime_auth_from_fastapi_request",
+]

piphi_runtime_kit_python/adapters/fastapi.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+"""Optional FastAPI-facing helpers for common PiPhi runtime patterns."""
+
+from typing import TYPE_CHECKING, Any, Mapping
+
+from ..runtime.auth import RuntimeAuthHeaders
+from ..runtime.context import RuntimeContext
+
+if TYPE_CHECKING:
+    from fastapi import Request
+
+
+def get_payload_container_id(
+    payload: object | Mapping[str, Any] | None,
+    *,
+    attribute_name: str = "container_id",
+) -> str | None:
+    """Return a normalized container id from a payload object or mapping.
+
+    This lets integrations share one helper across Pydantic models, dataclasses,
+    or plain dictionaries when wiring request auth to PiPhi container scope.
+    """
+    if payload is None:
+        return None
+
+    value: Any
+    if isinstance(payload, Mapping):
+        value = payload.get(attribute_name)
+    else:
+        value = getattr(payload, attribute_name, None)
+
+    normalized = str(value or "").strip()
+    return normalized or None
+
+
+def sync_runtime_auth_from_fastapi_request(
+    runtime_context: RuntimeContext,
+    request: "Request",
+    *,
+    payload_container_id: str | None = None,
+) -> RuntimeAuthHeaders:
+    """Sync runtime auth from a FastAPI request's headers into the context.
+
+    Typical usage:
+        parsed = sync_runtime_auth_from_fastapi_request(
+            runtime_context,
+            request,
+            payload_container_id=payload.container_id,
+        )
+    """
+    return runtime_context.auth.sync_from_headers(
+        request.headers,
+        payload_container_id=payload_container_id,
+    )
+
+
+def sync_runtime_auth_from_fastapi_payload(
+    runtime_context: RuntimeContext,
+    request: "Request",
+    payload: object | Mapping[str, Any] | None,
+    *,
+    attribute_name: str = "container_id",
+) -> RuntimeAuthHeaders:
+    """Sync request auth using a payload object that carries container scope."""
+    return sync_runtime_auth_from_fastapi_request(
+        runtime_context,
+        request,
+        payload_container_id=get_payload_container_id(
+            payload,
+            attribute_name=attribute_name,
+        ),
+    )

piphi_runtime_kit_python/fastapi.py

@@ -0,0 +1,13 @@
+"""Convenience re-exports for the optional FastAPI adapter layer."""
+
+from .adapters.fastapi import (
+    get_payload_container_id,
+    sync_runtime_auth_from_fastapi_payload,
+    sync_runtime_auth_from_fastapi_request,
+)
+
+__all__ = [
+    "get_payload_container_id",
+    "sync_runtime_auth_from_fastapi_payload",
+    "sync_runtime_auth_from_fastapi_request",
+]

piphi_runtime_kit_python/runtime/__init__.py

@@ -0,0 +1,124 @@
+from .auth import (
+    RUNTIME_CONTAINER_ID_HEADER_NAME,
+    RUNTIME_INTERNAL_TOKEN_HEADER_NAME,
+    RuntimeAuthContext,
+    RuntimeAuthHeaders,
+    build_runtime_auth_headers,
+    extract_runtime_auth_headers,
+    format_runtime_auth_sync_log,
+    mask_token,
+)
+from .config_sync import ConfigSyncCoordinator, build_sync_response, reconcile_config_ids
+from .configuration import (
+    build_config_apply_response,
+    build_config_remove_response,
+    format_config_apply_log,
+    redact_config_secrets,
+    validate_typed_config,
+    validate_typed_configs,
+)
+from .context import RuntimeContext
+from .discovery import (
+    build_discovery_response,
+    format_discovery_attempt_log,
+    normalize_discovery_inputs,
+)
+from .errors import (
+    CoreAuthError,
+    CoreDeliveryError,
+    CoreRouteNotFoundError,
+    CoreServerError,
+    CoreTimeoutError,
+    CoreUnavailableError,
+    CoreUnexpectedResponseError,
+    classify_core_delivery_error,
+)
+from .dispatch import (
+    build_local_event_record,
+    dispatch_event_delivery,
+    dispatch_telemetry_delivery,
+    schedule_event_delivery,
+    schedule_telemetry_delivery,
+)
+from .events import (
+    EventClient,
+    build_core_event_payload,
+    build_event_ingest_response,
+    build_event_list_response,
+    format_event_log,
+    normalize_event_payload,
+)
+from .health import build_runtime_diagnostics_response, build_runtime_health_response
+from .lifespan import (
+    DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
+    DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME,
+    DEFAULT_RUNTIME_INTERNAL_TOKEN_ENV_NAME,
+    bind_core_http_client,
+    bootstrap_runtime_auth_from_env,
+    runtime_lifespan,
+)
+from .registry import RuntimeRegistry
+from .state import RuntimeProcessState
+from .starter import RuntimeStarter, create_runtime_starter
+from .tasks import create_tracked_task, shutdown_background_tasks, track_background_task
+from .telemetry import TelemetryClient, build_core_auth_headers
+
+__all__ = [
+    "ConfigSyncCoordinator",
+    "CoreAuthError",
+    "CoreDeliveryError",
+    "CoreRouteNotFoundError",
+    "CoreServerError",
+    "CoreTimeoutError",
+    "CoreUnavailableError",
+    "CoreUnexpectedResponseError",
+    "RUNTIME_CONTAINER_ID_HEADER_NAME",
+    "RUNTIME_INTERNAL_TOKEN_HEADER_NAME",
+    "RuntimeAuthContext",
+    "RuntimeAuthHeaders",
+    "RuntimeContext",
+    "RuntimeRegistry",
+    "RuntimeProcessState",
+    "RuntimeStarter",
+    "TelemetryClient",
+    "EventClient",
+    "build_local_event_record",
+    "build_config_apply_response",
+    "build_config_remove_response",
+    "build_discovery_response",
+    "build_core_event_payload",
+    "build_event_ingest_response",
+    "build_event_list_response",
+    "build_core_auth_headers",
+    "build_runtime_auth_headers",
+    "build_sync_response",
+    "bind_core_http_client",
+    "bootstrap_runtime_auth_from_env",
+    "classify_core_delivery_error",
+    "create_tracked_task",
+    "create_runtime_starter",
+    "dispatch_event_delivery",
+    "dispatch_telemetry_delivery",
+    "DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS",
+    "DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME",
+    "DEFAULT_RUNTIME_INTERNAL_TOKEN_ENV_NAME",
+    "extract_runtime_auth_headers",
+    "format_config_apply_log",
+    "format_discovery_attempt_log",
+    "format_event_log",
+    "format_runtime_auth_sync_log",
+    "mask_token",
+    "build_runtime_diagnostics_response",
+    "build_runtime_health_response",
+    "normalize_discovery_inputs",
+    "normalize_event_payload",
+    "redact_config_secrets",
+    "reconcile_config_ids",
+    "runtime_lifespan",
+    "schedule_event_delivery",
+    "schedule_telemetry_delivery",
+    "shutdown_background_tasks",
+    "track_background_task",
+    "validate_typed_config",
+    "validate_typed_configs",
+]

piphi_runtime_kit_python/runtime/auth.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+"""Helpers for resolving PiPhi runtime auth across requests and background work."""
+
+import os
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+
+DEFAULT_INTERNAL_TOKEN_ENV_NAME = "PIPHI_INTEGRATION_INTERNAL_TOKEN"
+RUNTIME_CONTAINER_ID_HEADER_NAME = "X-Container-Id"
+RUNTIME_INTERNAL_TOKEN_HEADER_NAME = "X-PiPhi-Integration-Token"
+
+
+def mask_token(token: str | None) -> str:
+    """Return a log-safe representation of an internal runtime token."""
+    normalized = (token or "").strip()
+    if not normalized:
+        return "missing"
+    if len(normalized) <= 10:
+        return "present"
+    return f"{normalized[:6]}...{normalized[-4:]}"
+
+
+def _get_header_value(headers: Mapping[str, Any], name: str) -> str:
+    for key, value in headers.items():
+        if str(key).lower() == name.lower():
+            return str(value or "").strip()
+    return ""
+
+
+@dataclass(slots=True, frozen=True)
+class RuntimeAuthHeaders:
+    """Normalized PiPhi runtime auth values extracted from request headers."""
+    container_id: str = ""
+    internal_token: str = ""
+
+
+def extract_runtime_auth_headers(headers: Mapping[str, Any]) -> RuntimeAuthHeaders:
+    """Extract PiPhi runtime auth headers from any case-insensitive header mapping."""
+    return RuntimeAuthHeaders(
+        container_id=_get_header_value(headers, RUNTIME_CONTAINER_ID_HEADER_NAME),
+        internal_token=_get_header_value(headers, RUNTIME_INTERNAL_TOKEN_HEADER_NAME),
+    )
+
+
+def build_runtime_auth_headers(
+    *,
+    container_id: str,
+    internal_token: str | None,
+) -> dict[str, str]:
+    """Build the standard PiPhi runtime auth headers for outbound Core calls."""
+    headers = {RUNTIME_CONTAINER_ID_HEADER_NAME: container_id}
+    if internal_token:
+        headers[RUNTIME_INTERNAL_TOKEN_HEADER_NAME] = internal_token
+    return headers
+
+
+def format_runtime_auth_sync_log(
+    parsed_headers: RuntimeAuthHeaders,
+    *,
+    payload_container_id: str | None = None,
+) -> str:
+    """Build a consistent log message for request-scoped runtime auth sync.
+
+    This keeps token masking and field naming consistent across integrations
+    that want to log the incoming runtime auth context for debugging.
+    """
+    return (
+        "runtime_internal_auth "
+        f"header_container_id={parsed_headers.container_id or 'missing'} "
+        f"payload_container_id={payload_container_id or 'missing'} "
+        f"token={mask_token(parsed_headers.internal_token)}"
+    )
+
+
+@dataclass(slots=True)
+class RuntimeAuthContext:
+    """In-memory auth context shared by a runtime process.
+
+    Integrations can keep the most recent container scope and internal token here,
+    then reuse it for outbound telemetry or config sync calls.
+    """
+    container_id: str = ""
+    internal_token: str = ""
+
+    def update(
+        self,
+        *,
+        container_id: str | None = None,
+        internal_token: str | None = None,
+    ) -> None:
+        """Update the stored auth context with any non-empty incoming values."""
+        if container_id is not None:
+            resolved_container_id = str(container_id).strip()
+            if resolved_container_id:
+                self.container_id = resolved_container_id
+
+        if internal_token is not None:
+            resolved_internal_token = str(internal_token).strip()
+            if resolved_internal_token:
+                self.internal_token = resolved_internal_token
+
+    def sync_from_headers(
+        self,
+        headers: Mapping[str, Any],
+        *,
+        payload_container_id: str | None = None,
+    ) -> RuntimeAuthHeaders:
+        """Update the context from request headers and return the parsed values.
+
+        Typical usage:
+            parsed = runtime_context.auth.sync_from_headers(
+                request.headers,
+                payload_container_id=payload.container_id,
+            )
+        """
+        parsed_headers = extract_runtime_auth_headers(headers)
+        self.update(
+            container_id=parsed_headers.container_id or payload_container_id,
+            internal_token=parsed_headers.internal_token,
+        )
+        return parsed_headers
+
+    def resolve(
+        self,
+        *,
+        container_id: str | None = None,
+        token_env_name: str = DEFAULT_INTERNAL_TOKEN_ENV_NAME,
+    ) -> tuple[str, str]:
+        """Resolve the effective container scope and internal token for a request."""
+        resolved_container_id = str(container_id or "").strip() or self.container_id
+        resolved_internal_token = self.internal_token or (os.getenv(token_env_name) or "").strip()
+        return resolved_container_id, resolved_internal_token

piphi_runtime_kit_python/runtime/config_sync.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+"""Helpers for basic config-sync orchestration and generation tracking."""
+
+from dataclasses import dataclass
+from typing import Awaitable, Callable, TypeVar
+
+from ..schemas import RuntimeConfig, RuntimeConfigSnapshot, RuntimeConfigSyncResponse
+from .state import RuntimeProcessState
+
+TConfig = TypeVar("TConfig", bound=RuntimeConfig)
+
+
+def reconcile_config_ids(
+    *,
+    active_ids: list[str],
+    incoming_ids: list[str],
+) -> tuple[list[str], list[str]]:
+    """Return removed ids and unchanged ids from two config-id lists."""
+    active_set = set(active_ids)
+    incoming_set = set(incoming_ids)
+    removed_ids = sorted(active_set - incoming_set)
+    unchanged_ids = sorted(active_set & incoming_set)
+    return removed_ids, unchanged_ids
+
+
+def build_sync_response(
+    *,
+    status: str,
+    container_id: str,
+    reason: str | None = None,
+    generation: int | None = None,
+    applied: list[str] | None = None,
+    removed: list[str] | None = None,
+    active_config_ids: list[str] | None = None,
+    metadata: dict | None = None,
+) -> RuntimeConfigSyncResponse:
+    """Build a standard PiPhi config-sync response payload."""
+    return RuntimeConfigSyncResponse(
+        status=status,
+        container_id=container_id,
+        reason=reason,
+        generation=generation,
+        applied=applied or [],
+        removed=removed or [],
+        active_config_ids=active_config_ids or [],
+        metadata=metadata or {},
+    )
+
+
+@dataclass(slots=True)
+class ConfigSyncCoordinator:
+    """Track config generations and common sync response patterns.
+
+    This class intentionally stays small. It helps integrations decide whether
+    an incoming snapshot is stale and keeps generation tracking in one place.
+    """
+    process_state: RuntimeProcessState
+
+    def get_current_generation(self) -> int | None:
+        """Return the latest applied config generation for the process."""
+        return self.process_state.current_generation
+
+    def mark_generation(self, generation: int | None) -> int | None:
+        """Persist a new generation and return the effective stored value."""
+        if generation is not None:
+            self.process_state.current_generation = int(generation)
+        return self.process_state.current_generation
+
+    def is_stale(self, snapshot: RuntimeConfigSnapshot) -> bool:
+        """Return whether an incoming snapshot is older than the current state."""
+        incoming_generation = snapshot.generation
+        current_generation = self.process_state.current_generation
+        return bool(
+            incoming_generation is not None
+            and current_generation is not None
+            and int(incoming_generation) < int(current_generation)
+        )
+
+    def build_stale_response(
+        self,
+        *,
+        snapshot: RuntimeConfigSnapshot,
+        active_config_ids: list[str],
+    ) -> RuntimeConfigSyncResponse:
+        """Build the standard response for an ignored stale snapshot."""
+        return build_sync_response(
+            status="stale_ignored",
+            container_id=snapshot.container_id,
+            reason=snapshot.reason,
+            generation=self.process_state.current_generation,
+            active_config_ids=active_config_ids,
+            metadata={
+                "stale_generation_ignored": True,
+                "incoming_generation": snapshot.generation,
+                "current_generation": self.process_state.current_generation,
+            },
+        )
+
+    async def apply_snapshot(
+        self,
+        *,
+        snapshot: RuntimeConfigSnapshot,
+        active_config_ids: list[str],
+        apply_config: Callable[[RuntimeConfig], Awaitable[None]],
+        remove_config: Callable[[str], Awaitable[bool]],
+        get_active_config_ids: Callable[[], list[str]] | None = None,
+    ) -> RuntimeConfigSyncResponse:
+        """Apply a config snapshot using caller-provided apply/remove callbacks.
+
+        This keeps the integration-specific logic in the callbacks while the SDK
+        handles the generic PiPhi sync flow: stale detection, diffing, generation
+        tracking, and standard response payloads.
+        """
+        if self.is_stale(snapshot):
+            return self.build_stale_response(
+                snapshot=snapshot,
+                active_config_ids=active_config_ids,
+            )
+
+        incoming_ids = [config.id for config in snapshot.configs]
+        removed_ids, _unchanged_ids = reconcile_config_ids(
+            active_ids=active_config_ids,
+            incoming_ids=incoming_ids,
+        )
+
+        removed: list[str] = []
+        applied: list[str] = []
+
+        for config_id in removed_ids:
+            was_removed = await remove_config(config_id)
+            if was_removed:
+                removed.append(config_id)
+
+        for config in snapshot.configs:
+            await apply_config(config)
+            applied.append(config.id)
+
+        current_generation = self.mark_generation(snapshot.generation)
+        next_active_config_ids = (
+            get_active_config_ids() if get_active_config_ids is not None else incoming_ids
+        )
+
+        return build_sync_response(
+            status="synced",
+            container_id=snapshot.container_id,
+            reason=snapshot.reason,
+            generation=current_generation,
+            applied=applied,
+            removed=removed,
+            active_config_ids=next_active_config_ids,
+            metadata={
+                "applied_count": len(applied),
+                "removed_count": len(removed),
+                "current_generation": current_generation,
+            },
+        )