piphi-runtime-kit-python 0.4.2__tar.gz → 0.4.4__tar.gz

{piphi_runtime_kit_python-0.4.2 → piphi_runtime_kit_python-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: piphi-runtime-kit-python
-Version: 0.4.2
+Version: 0.4.4
 Summary: PiPhi Network runtime integration helpers
 Keywords: piphi,runtime,integration,iot
 Author-Email: KelvinSan <support@piphi.network>

{piphi_runtime_kit_python-0.4.2 → piphi_runtime_kit_python-0.4.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "piphi-runtime-kit-python"
-version = "0.4.2"
+version = "0.4.4"
 description = "PiPhi Network runtime integration helpers"
 authors = [
     { name = "KelvinSan", email = "support@piphi.network" },

{piphi_runtime_kit_python-0.4.2 → piphi_runtime_kit_python-0.4.4}/src/piphi_runtime_kit_python/__init__.py

@@ -8,7 +8,22 @@ from .runtime.auth import (
     format_runtime_auth_sync_log,
     mask_token,
 )
-from .runtime.config_sync import ConfigSyncCoordinator, build_sync_response, reconcile_config_ids
+from .runtime.config_sync import (
+    CORE_BASE_URL_ENV_NAME,
+    DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME,
+    DEFAULT_RUNTIME_VOLUME_DIR,
+    RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME,
+    ConfigSyncCoordinator,
+    RuntimeConfigRehydrateResult,
+    build_runtime_config_snapshot_from_core_rows,
+    build_sync_response,
+    fetch_core_runtime_config_snapshot,
+    load_runtime_config_snapshot,
+    reconcile_config_ids,
+    rehydrate_runtime_configs,
+    resolve_core_base_url,
+    resolve_runtime_config_snapshot_path,
+)
 from .runtime.configuration import (
     build_config_apply_response,
     build_config_remove_response,
@@ -109,6 +124,10 @@ __all__ = [
     "CoreUnavailableError",
     "CoreUnexpectedResponseError",
     "DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS",
+    "CORE_BASE_URL_ENV_NAME",
+    "DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME",
+    "DEFAULT_RUNTIME_VOLUME_DIR",
+    "RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME",
     "DEFAULT_RUNTIME_CONTAINER_ID_ENV_NAME",
     "DEFAULT_RUNTIME_INTERNAL_TOKEN_ENV_NAME",
     "RUNTIME_CONTAINER_ID_HEADER_NAME",
@@ -127,6 +146,7 @@ __all__ = [
     "RuntimeConfig",
     "RuntimeConfigApplyResponse",
     "RuntimeConfigRemoveResponse",
+    "RuntimeConfigRehydrateResult",
     "RuntimeConfigSnapshot",
     "RuntimeConfigSyncResponse",
     "RuntimeContext",
@@ -143,6 +163,7 @@ __all__ = [
     "EventTransport",
     "IntegrationEventIngestResponse",
     "IntegrationEventListResponse",
+    "build_runtime_config_snapshot_from_core_rows",
     "build_discovery_response",
     "classify_core_delivery_error",
     "build_core_event_payload",
@@ -165,10 +186,12 @@ __all__ = [
     "dispatch_event_delivery",
     "dispatch_telemetry_delivery",
     "extract_runtime_auth_headers",
+    "fetch_core_runtime_config_snapshot",
     "format_config_apply_log",
     "format_discovery_attempt_log",
     "format_event_log",
     "format_runtime_auth_sync_log",
+    "load_runtime_config_snapshot",
     "mask_token",
     "MqttBrokerConfig",
     "MqttJsonClient",
@@ -176,6 +199,9 @@ __all__ = [
     "normalize_event_payload",
     "redact_config_secrets",
     "reconcile_config_ids",
+    "rehydrate_runtime_configs",
+    "resolve_core_base_url",
+    "resolve_runtime_config_snapshot_path",
     "runtime_lifespan",
     "schedule_event_delivery",
     "schedule_telemetry_delivery",

piphi_runtime_kit_python-0.4.4/src/piphi_runtime_kit_python/runtime/config_sync.py

@@ -0,0 +1,462 @@
+from __future__ import annotations
+
+"""Helpers for basic config-sync orchestration and generation tracking."""
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+from typing import Any, Awaitable, Callable, TypeVar
+
+import httpx
+
+from ..schemas import RuntimeConfig, RuntimeConfigSnapshot, RuntimeConfigSyncResponse
+from .auth import build_runtime_auth_headers
+from .context import RuntimeContext
+from .lifespan import DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS
+from .state import RuntimeProcessState
+
+TConfig = TypeVar("TConfig", bound=RuntimeConfig)
+
+CORE_BASE_URL_ENV_NAME = "PIPHI_CORE_BASE_URL"
+RUNTIME_CONTAINER_ID_ENV_NAME = "PIPHI_CONTAINER_ID"
+RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME = "PIPHI_CONFIG_SNAPSHOT_PATH"
+DEFAULT_RUNTIME_VOLUME_DIR = "/.piphinetwork"
+DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME = "configs.json"
+CORE_RUNTIME_CONFIG_FETCH_PATH = (
+    "/api/v2/integrations/config/fetch/all/by/container/internal"
+)
+
+
+SnapshotApplyCallable = Callable[[Any], Awaitable[Any]]
+
+
+def resolve_core_base_url(default: str | None = None) -> str | None:
+    """Resolve Core's base URL from the managed-runtime environment."""
+    value = (os.getenv(CORE_BASE_URL_ENV_NAME) or "").strip().rstrip("/")
+    if value:
+        return value
+    return default.rstrip("/") if isinstance(default, str) and default.strip() else default
+
+
+def resolve_runtime_config_snapshot_path(
+    *,
+    container_id: str | None = None,
+    volume_dir: str | Path = DEFAULT_RUNTIME_VOLUME_DIR,
+) -> Path:
+    """Resolve the local config snapshot path mounted by PiPhi Core."""
+    explicit_path = (os.getenv(RUNTIME_CONFIG_SNAPSHOT_PATH_ENV_NAME) or "").strip()
+    if explicit_path:
+        return Path(explicit_path)
+
+    resolved_container_id = (
+        str(container_id or "").strip()
+        or (os.getenv(RUNTIME_CONTAINER_ID_ENV_NAME) or "").strip()
+    )
+    if resolved_container_id:
+        return Path(volume_dir).joinpath(f"{resolved_container_id}.json")
+    return Path(volume_dir).joinpath(DEFAULT_RUNTIME_CONFIG_SNAPSHOT_FILENAME)
+
+
+def load_runtime_config_snapshot(
+    *,
+    path: str | Path | None = None,
+    container_id: str | None = None,
+    volume_dir: str | Path = DEFAULT_RUNTIME_VOLUME_DIR,
+) -> RuntimeConfigSnapshot | None:
+    """Load Core's last known config snapshot from the mounted runtime volume.
+
+    Missing, unreadable, or invalid snapshots return ``None`` so integrations can
+    treat snapshot rehydration as a safe startup fallback rather than a crash
+    trigger.
+    """
+    snapshot_path = (
+        Path(path)
+        if path is not None
+        else resolve_runtime_config_snapshot_path(
+            container_id=container_id,
+            volume_dir=volume_dir,
+        )
+    )
+    try:
+        raw_payload = snapshot_path.read_text(encoding="utf-8")
+    except (FileNotFoundError, OSError):
+        return None
+
+    try:
+        payload = json.loads(raw_payload)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(payload, dict):
+        return None
+
+    try:
+        return RuntimeConfigSnapshot.model_validate(payload)
+    except ValueError:
+        return None
+
+
+@dataclass(slots=True)
+class RuntimeConfigRehydrateResult:
+    """Describe what happened during runtime startup config rehydration."""
+
+    snapshot_found: bool = False
+    snapshot_applied: bool = False
+    snapshot_config_count: int = 0
+    snapshot_generation: int | None = None
+    core_attempted: bool = False
+    core_applied: bool = False
+    core_config_count: int = 0
+    core_generation: int | None = None
+    core_error: str | None = None
+    missing_runtime_auth: bool = False
+
+    @property
+    def applied_any(self) -> bool:
+        """Return whether any startup source applied configs."""
+        return self.snapshot_applied or self.core_applied
+
+
+def _model_validate_or_create(model_type: type[Any], payload: dict[str, Any]) -> Any:
+    validator = getattr(model_type, "model_validate", None)
+    if callable(validator):
+        return validator(payload)
+    return model_type(**payload)
+
+
+def _snapshot_validate_or_create(model_type: type[Any], payload: dict[str, Any]) -> Any:
+    validator = getattr(model_type, "model_validate", None)
+    if callable(validator):
+        return validator(payload)
+    return model_type(**payload)
+
+
+def _convert_snapshot_configs(
+    snapshot: RuntimeConfigSnapshot,
+    *,
+    config_model: type[TConfig],
+    snapshot_model: type[Any],
+    reason: str,
+) -> Any:
+    configs = [
+        _model_validate_or_create(config_model, config.model_dump())
+        for config in snapshot.configs
+    ]
+    return _snapshot_validate_or_create(
+        snapshot_model,
+        {
+            "schema_version": snapshot.schema_version,
+            "container_id": snapshot.container_id,
+            "integration_id": snapshot.integration_id,
+            "driver_pid": snapshot.driver_pid,
+            "reason": snapshot.reason or reason,
+            "generation": snapshot.generation,
+            "updated_at": snapshot.updated_at,
+            "configs": configs,
+            "deleted_config_ids": snapshot.deleted_config_ids,
+            "config_hash": snapshot.config_hash,
+            "internal_token": snapshot.internal_token,
+        },
+    )
+
+
+def build_runtime_config_snapshot_from_core_rows(
+    rows: list[dict[str, Any]],
+    *,
+    container_id: str,
+    config_model: type[TConfig] = RuntimeConfig,
+    snapshot_model: type[Any] = RuntimeConfigSnapshot,
+    reason: str = "startup_rehydrate",
+) -> Any:
+    """Build a runtime config snapshot from Core's internal config rows.
+
+    Core returns database-shaped rows where the integration config lives under
+    ``config_data``. This helper turns those rows into the same snapshot shape
+    integrations receive from the normal config-sync endpoint.
+    """
+    configs: list[Any] = []
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        config_data = row.get("config_data")
+        if not isinstance(config_data, dict):
+            continue
+        payload = {**config_data}
+        payload["container_id"] = payload.get("container_id") or container_id
+        configs.append(_model_validate_or_create(config_model, payload))
+
+    return _snapshot_validate_or_create(
+        snapshot_model,
+        {
+            "container_id": container_id,
+            "reason": reason,
+            "configs": configs,
+        },
+    )
+
+
+async def fetch_core_runtime_config_snapshot(
+    *,
+    runtime_context: RuntimeContext,
+    client: httpx.AsyncClient,
+    core_base_url: str | None = None,
+    config_model: type[TConfig] = RuntimeConfig,
+    snapshot_model: type[Any] = RuntimeConfigSnapshot,
+    timeout_seconds: float = DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
+    reason: str = "startup_rehydrate",
+) -> Any | None:
+    """Fetch the latest runtime configs from Core using managed-runtime auth."""
+    container_id, internal_token = runtime_context.auth.resolve()
+    if not container_id or not internal_token:
+        return None
+
+    base_url = resolve_core_base_url(core_base_url) or resolve_core_base_url(
+        "http://127.0.0.1:31419"
+    )
+    if not base_url:
+        return None
+
+    response = await client.get(
+        f"{base_url}{CORE_RUNTIME_CONFIG_FETCH_PATH}",
+        params={"container_id": container_id},
+        headers=build_runtime_auth_headers(
+            container_id=container_id,
+            internal_token=internal_token,
+        ),
+        timeout=timeout_seconds,
+    )
+    response.raise_for_status()
+
+    rows = response.json()
+    if not rows:
+        return None
+    if not isinstance(rows, list):
+        raise ValueError("Core runtime config response must be a list.")
+
+    return build_runtime_config_snapshot_from_core_rows(
+        rows,
+        container_id=container_id,
+        config_model=config_model,
+        snapshot_model=snapshot_model,
+        reason=reason,
+    )
+
+
+async def rehydrate_runtime_configs(
+    *,
+    runtime_context: RuntimeContext,
+    client: httpx.AsyncClient,
+    apply_snapshot: SnapshotApplyCallable,
+    config_model: type[TConfig] = RuntimeConfig,
+    snapshot_model: type[Any] = RuntimeConfigSnapshot,
+    core_base_url: str | None = None,
+    timeout_seconds: float = DEFAULT_CORE_CLIENT_TIMEOUT_SECONDS,
+    snapshot_path: str | Path | None = None,
+    snapshot_volume_dir: str | Path = DEFAULT_RUNTIME_VOLUME_DIR,
+    snapshot_reason: str = "startup_snapshot_rehydrate",
+    core_reason: str = "startup_rehydrate",
+    raise_core_errors: bool = False,
+) -> RuntimeConfigRehydrateResult:
+    """Rehydrate runtime configs from the mounted snapshot and then Core.
+
+    Integration authors provide only their config model and apply callback. The
+    SDK handles startup ordering, managed-runtime auth, Core request headers,
+    local snapshot fallback, and safe offline behavior.
+    """
+    result = RuntimeConfigRehydrateResult()
+    container_id = runtime_context.auth.container_id
+
+    cached_snapshot = load_runtime_config_snapshot(
+        path=snapshot_path,
+        container_id=container_id,
+        volume_dir=snapshot_volume_dir,
+    )
+    if cached_snapshot is not None:
+        result.snapshot_found = True
+        snapshot = _convert_snapshot_configs(
+            cached_snapshot,
+            config_model=config_model,
+            snapshot_model=snapshot_model,
+            reason=snapshot_reason,
+        )
+        await apply_snapshot(snapshot)
+        result.snapshot_applied = True
+        result.snapshot_config_count = len(getattr(snapshot, "configs", []) or [])
+        result.snapshot_generation = getattr(snapshot, "generation", None)
+
+    resolved_container_id, resolved_internal_token = runtime_context.auth.resolve()
+    if not resolved_container_id or not resolved_internal_token:
+        result.missing_runtime_auth = True
+        return result
+
+    result.core_attempted = True
+    try:
+        core_snapshot = await fetch_core_runtime_config_snapshot(
+            runtime_context=runtime_context,
+            client=client,
+            core_base_url=core_base_url,
+            config_model=config_model,
+            snapshot_model=snapshot_model,
+            timeout_seconds=timeout_seconds,
+            reason=core_reason,
+        )
+    except Exception as exc:
+        result.core_error = f"{type(exc).__name__}: {exc}"
+        if raise_core_errors:
+            raise
+        return result
+
+    if core_snapshot is None:
+        return result
+
+    await apply_snapshot(core_snapshot)
+    result.core_applied = True
+    result.core_config_count = len(getattr(core_snapshot, "configs", []) or [])
+    result.core_generation = getattr(core_snapshot, "generation", None)
+    return result
+
+
+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,
+            },
+        )

{piphi_runtime_kit_python-0.4.2 → piphi_runtime_kit_python-0.4.4}/src/piphi_runtime_kit_python/runtime/health.py

@@ -15,6 +15,7 @@ def _build_runtime_snapshot(runtime_context: RuntimeContext) -> dict[str, Any]:
         "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,
+        "config_generation": process_state.current_generation,
         "pending_task_count": len(
             [task for task in process_state.background_tasks if not task.done()]
         ),

{piphi_runtime_kit_python-0.4.2 → piphi_runtime_kit_python-0.4.4}/src/piphi_runtime_kit_python/schemas.py

@@ -35,12 +35,34 @@ class RuntimeConfig(BaseModel):
 
 class RuntimeConfigSnapshot(BaseModel):
     """Snapshot payload sent from PiPhi Core to an integration runtime."""
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    schema_version: int | None = Field(
+        default=None,
+        validation_alias=AliasChoices("schema_version", "schemaVersion"),
+    )
     container_id: str
     integration_id: str | None = None
     driver_pid: int | None = None
     reason: str | None = None
     generation: int | None = None
+    updated_at: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("updated_at", "updatedAt"),
+    )
     configs: list[RuntimeConfig] = Field(default_factory=list)
+    deleted_config_ids: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices("deleted_config_ids", "deletedConfigIds"),
+    )
+    config_hash: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("config_hash", "configHash"),
+    )
+    internal_token: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("internal_token", "internalToken"),
+    )
 
 
 class RuntimeConfigSyncResponse(BaseModel):