onec-interactive-runtime-core 0.1.19__py3-none-any.whl

onec_runtime/extension_lifecycle.py

@@ -0,0 +1,402 @@
+from __future__ import annotations
+
+import re
+import tempfile
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from typing import ContextManager, Protocol
+
+from onec_runtime.config import RuntimeConfig
+from onec_runtime.errors import (
+    ExtensionIdentityConflict,
+    ExtensionLifecycleError,
+    ExtensionNotInstalled,
+)
+from onec_runtime.extension_bundle import (
+    ExtensionBundle,
+    ExtensionFingerprints,
+    ExtensionHandshakeEvidence,
+    fingerprint_extension_dump,
+)
+from onec_runtime.extension_state import (
+    ExtensionStateStore,
+    InfobaseExtensionLock,
+    VerifiedExtensionState,
+)
+from onec_runtime.performance_profile import PhaseRecorder
+from onec_runtime.toolchain import ToolResult
+
+_PRODUCT_VERSION = re.compile(r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\Z")
+
+
+def _product_version_key(value: str) -> tuple[tuple[int, str], ...]:
+    match = _PRODUCT_VERSION.fullmatch(value)
+    if match is None:
+        raise ExtensionLifecycleError(
+            "extension artifact versions must use canonical MAJOR.MINOR.PATCH decimal syntax"
+        )
+    return tuple((len(component), component) for component in match.groups())
+
+
+class TargetExtensionState(StrEnum):
+    ABSENT = "absent"
+    CURRENT = "current"
+    OLDER = "older"
+    FOREIGN = "foreign"
+    INSTALLED = "installed"
+    UPDATED = "updated"
+    USER_MANAGED = "user-managed"
+
+
+class LifecycleMode(StrEnum):
+    FAST = "fast"
+    PROBED = "probed"
+    SLOW = "slow"
+    MANUAL = "manual"
+
+
+@dataclass(frozen=True, slots=True)
+class LifecycleDecision:
+    mode: LifecycleMode
+    target_state: TargetExtensionState
+    bundle: ExtensionBundle
+    retry_allowed: bool
+
+
+class ExtensionToolOperations(Protocol):
+    def mutation_session(self, log_dir: Path) -> ContextManager[None]: ...
+
+    def dump_files(self, destination: Path, log_path: Path) -> ToolResult: ...
+
+    def dump_cfe(self, destination: Path, log_path: Path) -> ToolResult: ...
+
+    def load_cfe(self, source: Path, log_path: Path) -> ToolResult | None: ...
+
+    def apply(self, log_path: Path) -> ToolResult | None: ...
+
+    def disable_safe_mode(self, log_dir: Path) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class _OperationPaths:
+    root: Path
+    initial_dump: Path
+    final_dump: Path
+    rollback_dump: Path
+    backup_cfe: Path
+
+    def log(self, name: str) -> Path:
+        return self.root / f"{name}.log"
+
+
+class ExtensionLifecycle:
+    def __init__(
+        self,
+        config: RuntimeConfig,
+        bundle: ExtensionBundle,
+        state_store: ExtensionStateStore,
+        tools: ExtensionToolOperations,
+        profiler: PhaseRecorder | None = None,
+        *,
+        lifecycle_lock: InfobaseExtensionLock | None = None,
+        lock_timeout_s: float = 30.0,
+    ) -> None:
+        self.config = config
+        self.bundle = bundle
+        self.state_store = state_store
+        self.tools = tools
+        self.profiler = profiler if profiler is not None else PhaseRecorder()
+        state_root = config.runtime_dir / "extension-state"
+        self._lock = lifecycle_lock or InfobaseExtensionLock(
+            state_root, config.infobase_identity
+        )
+        self._lock_timeout_s = lock_timeout_s
+
+    def prepare(self, *, force_slow: bool = False) -> LifecycleDecision:
+        manifest = self.bundle.manifest
+        if not force_slow and self.state_store.matches(manifest):
+            return self._fast_decision()
+
+        with self._lock.acquire(timeout_s=self._lock_timeout_s):
+            if not force_slow and self.state_store.matches(manifest):
+                return self._fast_decision()
+            self.state_store.invalidate()
+            paths = self._new_operation_paths()
+            state, installed = self._inspect(paths.initial_dump, paths.log("inspect"))
+            if state not in (
+                TargetExtensionState.ABSENT,
+                TargetExtensionState.CURRENT,
+                TargetExtensionState.OLDER,
+            ):
+                raise ExtensionIdentityConflict(
+                    "installed extension has a foreign permanent identity"
+                )
+
+            # The exact artifact is already present. Admit it only after the
+            # live client/server handshake and safe-mode property check;
+            # repair through the Agent if either check fails.
+            if state is TargetExtensionState.CURRENT and not force_slow:
+                return LifecycleDecision(
+                    LifecycleMode.PROBED,
+                    TargetExtensionState.CURRENT,
+                    self.bundle,
+                    retry_allowed=True,
+                )
+
+            with self.tools.mutation_session(paths.root / "agent"):
+                if state is TargetExtensionState.ABSENT:
+                    self._install(paths)
+                    result_state = TargetExtensionState.INSTALLED
+                elif state is TargetExtensionState.CURRENT:
+                    result_state = TargetExtensionState.CURRENT
+                else:
+                    assert installed is not None
+                    self._update(paths, installed)
+                    result_state = TargetExtensionState.UPDATED
+
+                if state is TargetExtensionState.ABSENT:
+                    self._require_current(paths.final_dump, paths.log("verify"))
+                self.profiler.measure(
+                    "extension.safe_mode",
+                    lambda: self.tools.disable_safe_mode(paths.root / "safe-mode"),
+                )
+            return LifecycleDecision(
+                LifecycleMode.SLOW,
+                result_state,
+                self.bundle,
+                retry_allowed=False,
+            )
+
+    def invalidate_marker(self) -> None:
+        self.state_store.invalidate()
+
+    def prepare_manual(self) -> LifecycleDecision:
+        with self._lock.acquire(timeout_s=self._lock_timeout_s):
+            self.state_store.invalidate()
+        return LifecycleDecision(
+            LifecycleMode.MANUAL,
+            TargetExtensionState.USER_MANAGED,
+            self.bundle,
+            retry_allowed=False,
+        )
+
+    def commit_handshake(
+        self,
+        evidence: tuple[ExtensionHandshakeEvidence, ExtensionHandshakeEvidence],
+    ) -> None:
+        def commit() -> None:
+            self._validated_handshake(evidence)
+            manifest = self.bundle.manifest
+            state = VerifiedExtensionState(
+                infobase_path=self.config.infobase_identity,
+                product_id=manifest.product_id,
+                cfe_sha256=manifest.cfe_sha256,
+                manifest_schema_version=manifest.schema_version,
+                artifact_version=manifest.artifact_version,
+                protocol_version=manifest.protocol_version,
+                identity_sha256=manifest.fingerprints.identity_sha256,
+            )
+            with self._lock.acquire(timeout_s=self._lock_timeout_s):
+                self.state_store.write(state)
+
+        self.profiler.measure("extension.handshake", commit)
+
+    def accept_manual_handshake(
+        self,
+        evidence: tuple[ExtensionHandshakeEvidence, ExtensionHandshakeEvidence],
+    ) -> str:
+        def accept() -> str:
+            managed, _server = self._validated_handshake(
+                evidence,
+                allow_artifact_version_mismatch=True,
+            )
+            return managed.artifact_version
+
+        return self.profiler.measure("extension.handshake", accept)
+
+    def _fast_decision(self) -> LifecycleDecision:
+        return LifecycleDecision(
+            LifecycleMode.FAST,
+            TargetExtensionState.CURRENT,
+            self.bundle,
+            retry_allowed=True,
+        )
+
+    def _new_operation_paths(self) -> _OperationPaths:
+        parent = self.config.runtime_dir / "extension-lifecycle"
+        parent.mkdir(parents=True, exist_ok=True)
+        root = Path(tempfile.mkdtemp(prefix="attempt-", dir=parent))
+        root.chmod(0o700)
+        return _OperationPaths(
+            root=root,
+            initial_dump=root / "installed-before",
+            final_dump=root / "installed-after",
+            rollback_dump=root / "installed-rollback",
+            backup_cfe=root / "installed-backup.cfe",
+        )
+
+    def _inspect(
+        self, destination: Path, log_path: Path
+    ) -> tuple[TargetExtensionState, ExtensionFingerprints | None]:
+        def inspect() -> ExtensionFingerprints | None:
+            try:
+                self.tools.dump_files(destination, log_path)
+            except ExtensionNotInstalled:
+                return None
+            return fingerprint_extension_dump(destination, expected_product_id=None)
+
+        installed = self.profiler.measure("extension.inspect", inspect)
+        if installed is None:
+            return TargetExtensionState.ABSENT, None
+
+        expected = self.bundle.manifest.fingerprints
+        if installed == expected:
+            return TargetExtensionState.CURRENT, installed
+        if (
+            installed.identity == expected.identity
+            and installed.identity_sha256 == expected.identity_sha256
+        ):
+            installed_version = _product_version_key(
+                installed.artifact.artifact_version
+            )
+            packaged_version = _product_version_key(expected.artifact.artifact_version)
+            if installed_version < packaged_version:
+                return TargetExtensionState.OLDER, installed
+            raise ExtensionLifecycleError(
+                "installed same-identity extension is not a strictly older artifact"
+            )
+        return TargetExtensionState.FOREIGN, installed
+
+    def _install(self, paths: _OperationPaths) -> None:
+        self.profiler.measure(
+            "extension.install",
+            lambda: self.tools.load_cfe(self.bundle.cfe_path, paths.log("install")),
+        )
+        self._apply(paths.log("apply"))
+
+    def _update(
+        self, paths: _OperationPaths, old_fingerprints: ExtensionFingerprints
+    ) -> None:
+        backup_ready = False
+
+        def backup_and_load() -> ToolResult | None:
+            nonlocal backup_ready
+            self.tools.dump_cfe(paths.backup_cfe, paths.log("backup"))
+            backup_ready = True
+            return self.tools.load_cfe(self.bundle.cfe_path, paths.log("update"))
+
+        try:
+            self.profiler.measure("extension.update", backup_and_load)
+            self._apply(paths.log("apply"))
+            self._require_current(paths.final_dump, paths.log("verify"))
+        except BaseException as primary_error:
+            if backup_ready:
+                try:
+                    self._rollback(paths, old_fingerprints)
+                except BaseException as rollback_error:  # noqa: BLE001
+                    primary_error.add_note(
+                        f"Extension rollback failed: {type(rollback_error).__name__}"
+                    )
+            raise
+
+    def _rollback(
+        self, paths: _OperationPaths, old_fingerprints: ExtensionFingerprints
+    ) -> None:
+        self.profiler.measure(
+            "extension.update",
+            lambda: self.tools.load_cfe(paths.backup_cfe, paths.log("rollback-load")),
+        )
+        self._apply(paths.log("rollback-apply"))
+        restored = self.profiler.measure(
+            "extension.inspect",
+            lambda: self._dump_fingerprints(
+                paths.rollback_dump, paths.log("rollback-verify")
+            ),
+        )
+        if restored != old_fingerprints:
+            raise ExtensionLifecycleError(
+                "extension rollback did not restore the exact prior artifact"
+            )
+
+    def _apply(self, log_path: Path) -> None:
+        self.profiler.measure("extension.apply", lambda: self.tools.apply(log_path))
+
+    def _require_current(self, destination: Path, log_path: Path) -> None:
+        state, _ = self._inspect(destination, log_path)
+        if state is not TargetExtensionState.CURRENT:
+            raise ExtensionLifecycleError(
+                "extension mutation did not produce the exact packaged artifact"
+            )
+
+    def _dump_fingerprints(
+        self, destination: Path, log_path: Path
+    ) -> ExtensionFingerprints:
+        self.tools.dump_files(destination, log_path)
+        return fingerprint_extension_dump(destination)
+
+    def _validated_handshake(
+        self,
+        evidence: tuple[ExtensionHandshakeEvidence, ExtensionHandshakeEvidence],
+        *,
+        allow_artifact_version_mismatch: bool = False,
+    ) -> tuple[ExtensionHandshakeEvidence, ExtensionHandshakeEvidence]:
+        if not isinstance(evidence, tuple) or len(evidence) != 2:
+            raise ExtensionLifecycleError(
+                "extension handshake requires exactly two evidence records"
+            )
+        if any(not isinstance(item, ExtensionHandshakeEvidence) for item in evidence):
+            raise ExtensionLifecycleError("extension handshake evidence is malformed")
+        by_target = {item.target_type: item for item in evidence}
+        if len(by_target) != len(evidence):
+            raise ExtensionLifecycleError(
+                "extension handshake contains duplicate target records"
+            )
+        server_target_type = self.config.server_target_type
+        if set(by_target) != {"ManagedClient", server_target_type}:
+            raise ExtensionLifecycleError(
+                "extension handshake requires one managed and one server record"
+            )
+
+        managed = by_target["ManagedClient"]
+        server = by_target[server_target_type]
+        manifest = self.bundle.manifest
+        expected_locations = {
+            "ManagedClient": manifest.breakpoints.managed,
+            server_target_type: manifest.breakpoints.server_entry,
+        }
+        if any(
+            item.location != expected_locations[item.target_type]
+            for item in (managed, server)
+        ):
+            raise ExtensionLifecycleError(
+                "extension handshake does not match required breakpoint locations"
+            )
+        if (
+            managed.product_id != server.product_id
+            or managed.artifact_version != server.artifact_version
+            or managed.protocol_version != server.protocol_version
+        ):
+            raise ExtensionLifecycleError(
+                "extension client/server handshake values disagree"
+            )
+        if (
+            managed.product_id != manifest.product_id
+            or managed.protocol_version != manifest.protocol_version
+            or (
+                not allow_artifact_version_mismatch
+                and managed.artifact_version != manifest.artifact_version
+            )
+        ):
+            raise ExtensionLifecycleError(
+                "extension handshake does not match the packaged manifest"
+            )
+        return managed, server
+
+__all__ = [
+    "ExtensionLifecycle",
+    "ExtensionToolOperations",
+    "LifecycleDecision",
+    "LifecycleMode",
+    "TargetExtensionState",
+]

onec_runtime/extension_state.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import errno
+import json
+import math
+import os
+import sys
+import tempfile
+import time
+from collections.abc import Iterator
+from contextlib import AbstractContextManager, contextmanager
+from dataclasses import asdict, dataclass
+from hashlib import sha256
+from pathlib import Path
+from typing import BinaryIO
+
+from onec_runtime.errors import ExtensionLockTimeout
+from onec_runtime.extension_bundle import ExtensionManifest
+
+if sys.platform == "win32":
+    import msvcrt
+else:
+    import fcntl
+
+_STATE_FIELDS = {
+    "infobase_path",
+    "product_id",
+    "cfe_sha256",
+    "manifest_schema_version",
+    "artifact_version",
+    "protocol_version",
+    "identity_sha256",
+    "safe_mode",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class VerifiedExtensionState:
+    infobase_path: str
+    product_id: str
+    cfe_sha256: str
+    manifest_schema_version: int
+    artifact_version: str
+    protocol_version: str
+    identity_sha256: str
+    safe_mode: bool = False
+
+
+def _canonical_infobase(infobase_dir: Path | str) -> str:
+    # Strings are already canonical connection identities from RuntimeConfig.
+    # Keep Path callers and existing file cache keys backward compatible.
+    if isinstance(infobase_dir, str):
+        return infobase_dir
+    return str(infobase_dir.resolve())
+
+
+def _infobase_key(canonical_infobase: str) -> str:
+    return sha256(canonical_infobase.encode()).hexdigest()
+
+
+def _is_int(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _is_hash(value: object) -> bool:
+    return (
+        isinstance(value, str)
+        and len(value) == 64
+        and all(character in "0123456789abcdef" for character in value)
+    )
+
+
+def _decode_state(
+    payload: object, *, canonical_infobase: str
+) -> VerifiedExtensionState | None:
+    if not isinstance(payload, dict) or set(payload) != _STATE_FIELDS:
+        return None
+    if payload["safe_mode"] is not False:
+        return None
+    if not _is_int(payload["manifest_schema_version"]):
+        return None
+    if payload["infobase_path"] != canonical_infobase:
+        return None
+    for field in ("product_id", "artifact_version", "protocol_version"):
+        value = payload[field]
+        if not isinstance(value, str) or not value:
+            return None
+    for field in ("cfe_sha256", "identity_sha256"):
+        if not _is_hash(payload[field]):
+            return None
+    return VerifiedExtensionState(
+        infobase_path=payload["infobase_path"],
+        product_id=payload["product_id"],
+        cfe_sha256=payload["cfe_sha256"],
+        manifest_schema_version=payload["manifest_schema_version"],
+        artifact_version=payload["artifact_version"],
+        protocol_version=payload["protocol_version"],
+        identity_sha256=payload["identity_sha256"],
+        safe_mode=False,
+    )
+
+
+class ExtensionStateStore:
+    def __init__(self, runtime_dir: Path, infobase_dir: Path | str) -> None:
+        self._canonical_infobase = _canonical_infobase(infobase_dir)
+        self.path = runtime_dir / f"{_infobase_key(self._canonical_infobase)}.json"
+
+    def read(self) -> VerifiedExtensionState | None:
+        try:
+            payload = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+            return None
+        return _decode_state(payload, canonical_infobase=self._canonical_infobase)
+
+    def matches(self, manifest: ExtensionManifest) -> bool:
+        state = self.read()
+        if state is None:
+            return False
+        return bool(
+            state.product_id == manifest.product_id
+            and state.cfe_sha256 == manifest.cfe_sha256
+            and state.manifest_schema_version == manifest.schema_version
+            and state.artifact_version == manifest.artifact_version
+            and state.protocol_version == manifest.protocol_version
+            and state.identity_sha256 == manifest.fingerprints.identity_sha256
+        )
+
+    def write(self, state: VerifiedExtensionState) -> None:
+        payload = asdict(state)
+        if _decode_state(payload, canonical_infobase=self._canonical_infobase) != state:
+            raise ValueError("extension state is invalid for this infobase")
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary_name = tempfile.mkstemp(
+            prefix=f".{self.path.stem}-",
+            suffix=".tmp",
+            dir=self.path.parent,
+        )
+        temporary_path = Path(temporary_name)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as handle:
+                json.dump(payload, handle, sort_keys=True, separators=(",", ":"))
+                handle.write("\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary_path, self.path)
+        finally:
+            temporary_path.unlink(missing_ok=True)
+
+    def invalidate(self) -> None:
+        self.path.unlink(missing_ok=True)
+
+
+class InfobaseExtensionLock:
+    def __init__(self, runtime_dir: Path, infobase_dir: Path | str) -> None:
+        canonical_infobase = _canonical_infobase(infobase_dir)
+        self.path = runtime_dir / f"{_infobase_key(canonical_infobase)}.lock"
+
+    def acquire(self, *, timeout_s: float) -> AbstractContextManager[None]:
+        if not math.isfinite(timeout_s) or timeout_s < 0:
+            raise ValueError("timeout_s must be finite and non-negative")
+        return self._acquire(timeout_s=timeout_s)
+
+    @contextmanager
+    def _acquire(self, *, timeout_s: float) -> Iterator[None]:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a+b") as handle:
+            self._ensure_lock_byte(handle)
+            deadline = time.monotonic() + timeout_s
+            while not self._try_lock(handle):
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise ExtensionLockTimeout(
+                        f"timed out acquiring extension lifecycle lock: {self.path}"
+                    )
+                time.sleep(min(0.01, remaining))
+            try:
+                yield None
+            finally:
+                self._unlock(handle)
+
+    @staticmethod
+    def _ensure_lock_byte(handle: BinaryIO) -> None:
+        handle.seek(0, os.SEEK_END)
+        if handle.tell() == 0:
+            handle.write(b"\0")
+            handle.flush()
+            os.fsync(handle.fileno())
+
+    @staticmethod
+    def _try_lock(handle: BinaryIO) -> bool:
+        handle.seek(0)
+        if sys.platform == "win32":
+            try:
+                msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+            except OSError as error:
+                if error.errno in {errno.EACCES, errno.EAGAIN, errno.EDEADLK}:
+                    return False
+                raise
+        else:
+            try:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            except OSError as error:
+                if error.errno in {errno.EACCES, errno.EAGAIN}:
+                    return False
+                raise
+        return True
+
+    @staticmethod
+    def _unlock(handle: BinaryIO) -> None:
+        handle.seek(0)
+        if sys.platform == "win32":
+            msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+__all__ = [
+    "ExtensionStateStore",
+    "InfobaseExtensionLock",
+    "VerifiedExtensionState",
+]

onec_runtime/fault_injection.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import Callable
+
+from onec_runtime.errors import RdbgTransportError
+
+
+class FaultPoint(str, Enum):
+    AFTER_CAPTURE_CHECKPOINT = "after_capture_checkpoint"
+    AFTER_FIRST_ROOT_WRITE = "after_first_root_write"
+    AFTER_CONTINUE_ACK = "after_continue_ack"
+
+
+class InjectedTransportFailure(RdbgTransportError):
+    """A deterministic transport loss at a tested lifecycle boundary."""
+
+
+class CloseTransportAt:
+    def __init__(self, point: FaultPoint, close: Callable[[], None]) -> None:
+        self.point = point
+        self.close = close
+        self.fired = False
+
+    def __call__(self, point: FaultPoint) -> None:
+        if self.fired or point is not self.point:
+            return
+        self.fired = True
+        self.close()
+        raise InjectedTransportFailure(f"Injected fault at {point.value}")