piphi-runtime-kit-python 0.4.2__py3-none-any.whl → 0.4.4__py3-none-any.whl

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/runtime/config_sync.py

@@ -3,13 +3,318 @@ from __future__ import annotations
 """Helpers for basic config-sync orchestration and generation tracking."""
 
 from dataclasses import dataclass
-from typing import Awaitable, Callable, TypeVar
+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(
     *,

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/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):

{piphi_runtime_kit_python-0.4.2.dist-info → piphi_runtime_kit_python-0.4.4.dist-info}/METADATA

@@ -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.dist-info → piphi_runtime_kit_python-0.4.4.dist-info}/RECORD

@@ -1,21 +1,21 @@
-piphi_runtime_kit_python-0.4.2.dist-info/METADATA,sha256=th_AhsVfZ_at7LDyKQv7ZA1EVxiasOUwoSdTxQvdulI,30849
-piphi_runtime_kit_python-0.4.2.dist-info/WHEEL,sha256=Z36eTX6lG3PITRleSd5hAZHCcz52yg3c0JQVxKBbLW0,90
-piphi_runtime_kit_python-0.4.2.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-piphi_runtime_kit_python-0.4.2.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
-piphi_runtime_kit_python/__init__.py,sha256=P8yx6C1P88xuXWuf3D58d5zhUD-pprhBhbVeyNbDaJQ,6013
+piphi_runtime_kit_python-0.4.4.dist-info/METADATA,sha256=itnYk2BZoSxO2w_x--KH4i937xkqhT4_HT5GZZKy-cA,30849
+piphi_runtime_kit_python-0.4.4.dist-info/WHEEL,sha256=Z36eTX6lG3PITRleSd5hAZHCcz52yg3c0JQVxKBbLW0,90
+piphi_runtime_kit_python-0.4.4.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+piphi_runtime_kit_python-0.4.4.dist-info/licenses/LICENSE,sha256=pS6szQI4X7qAin1ODdoDp-XwZvsFy6ZZ28-JAwGHgzo,1070
+piphi_runtime_kit_python/__init__.py,sha256=nw9We1D1bN6aucvw2mlgux3rs4znSIH-RyagYSbDgWE,6866
 piphi_runtime_kit_python/adapters/__init__.py,sha256=3jBhPZSBN3Qo7MKHlxAol2jPU3cK23BXHR2oTlircsw,361
 piphi_runtime_kit_python/adapters/fastapi.py,sha256=1QcOBYprg6AmQVrkI8g61NIelBB_7BTbdvNaMvG2-s8,2098
 piphi_runtime_kit_python/fastapi.py,sha256=OZ-ds2-g32kB4YkF90D5bM4vVVjpOWPtrNC-WdhDNyo,361
 piphi_runtime_kit_python/runtime/__init__.py,sha256=0WxNbgGodqba-uiJILOAuU3EwZhBtXeDyw6sYhduWzg,3717
 piphi_runtime_kit_python/runtime/auth.py,sha256=hL90c3K5pJgEpPdNGJ7ds6mqeN4tmjC3I8igfNam_L4,4648
-piphi_runtime_kit_python/runtime/config_sync.py,sha256=IzsH5AGxnISISWx8OYfNMTk2O20kbW4fBvBEGwO_cYg,5625
+piphi_runtime_kit_python/runtime/config_sync.py,sha256=FA9wcFpDpYWYBmmEXZRAhwRIuO-a-BHwlJTJzA748IA,15925
 piphi_runtime_kit_python/runtime/configuration.py,sha256=4kkoJeENOhJHeNvC9QDu81ejDJUQJG7S5GmQG1sv3YQ,3631
 piphi_runtime_kit_python/runtime/context.py,sha256=CwXgrivciBd7eTREn0u0zjqkDPy6VthASW-gsoZqCTg,1109
 piphi_runtime_kit_python/runtime/discovery.py,sha256=uH6rJ4BnLVukTCxu2QwvN8yJhsI_fcT29VEat62oBcY,2274
 piphi_runtime_kit_python/runtime/dispatch.py,sha256=QcbA9B5izyyg0znlKHq94dbr-oqHVxKW2LCjrQKYfkY,7341
 piphi_runtime_kit_python/runtime/errors.py,sha256=_mjqmJLsdM5NfrTwb6YFkhheqPfn6Df-QtAKgl9U6QU,4120
 piphi_runtime_kit_python/runtime/events.py,sha256=JcvrTZlJ-vgY237jTDVOAVTbSxbcuh9u2QCdOGyuduA,6543
-piphi_runtime_kit_python/runtime/health.py,sha256=9YO0K_UCJKTe6uSFLgb1kStr5dAgtIUc8Ha0dnRi2vA,1880
+piphi_runtime_kit_python/runtime/health.py,sha256=3pds8SYSUql2w2ijegbszwm0HK69VzfIrwz42bN97yk,1943
 piphi_runtime_kit_python/runtime/identity.py,sha256=cth0_QHR9R5LTdp-6DPD1IhM8cYJT5HB1OUQYW7kLGs,2762
 piphi_runtime_kit_python/runtime/lifespan.py,sha256=mVSdZZAS66xlcnlzAwkztFjzw_l2pyLrJqULJsb0Ezk,2850
 piphi_runtime_kit_python/runtime/mqtt.py,sha256=JKMN5zxg1BcOidu7TaYnuRD3HuoAJ_WcvXMTTSlAteo,6069
@@ -24,5 +24,5 @@ piphi_runtime_kit_python/runtime/starter.py,sha256=j5C4GOOcRHNLJ-HYu8fmf3bE00baD
 piphi_runtime_kit_python/runtime/state.py,sha256=4xvQGTT59DF9rXHAtM3kDyV_UGg2a9tLPvGiCp_PFMc,674
 piphi_runtime_kit_python/runtime/tasks.py,sha256=gMd-2K96jMU8tCPvI12xdWxuyNt5gsLDss2QWOoM94k,1241
 piphi_runtime_kit_python/runtime/telemetry.py,sha256=RN6SFrhmAZ7aJLyioQMBzJEFsxQgOjjA1pV5qNeaR4E,4279
-piphi_runtime_kit_python/schemas.py,sha256=LGz53OHmWwUEQb_nHbVBgRDGVGowJPT53S2P7otP3lo,9073
-piphi_runtime_kit_python-0.4.2.dist-info/RECORD,,
+piphi_runtime_kit_python/schemas.py,sha256=9jlsfmvz-O2YeoB0SVopXY7NhFlb1zgynez0NXEZkVE,9849
+piphi_runtime_kit_python-0.4.4.dist-info/RECORD,,