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

onec_runtime/controller_worker.py

@@ -0,0 +1,400 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from enum import Enum
+from multiprocessing.connection import Connection
+from threading import Event
+from time import monotonic
+from typing import Protocol
+from uuid import UUID
+
+from onec_runtime.errors import (
+    CommandTimeout,
+    ControllerUnavailable,
+    InvalidMessageSequence,
+    LeaseConflict,
+    LeaseExpired,
+    StaleLeaseEpoch,
+)
+from onec_runtime.fault_injection import FaultPoint
+from onec_runtime.lease import LeaseAuthority, validate_lease_ttl
+from onec_runtime.recovery_journal import RecoveryJournal
+from onec_runtime.supervisor_model import LeaseHandle
+from onec_runtime.supervisor_protocol import (
+    ControlMessage,
+    MessageKind,
+    MessageReceiver,
+    MessageSender,
+)
+
+
+WORKER_POLL_INTERVAL_S = 0.05
+HEARTBEAT_INTERVAL_S = 0.25
+DEBUGGEE_START_TIMEOUT_S = 90.0
+SAFE_RUNTIME_STATES = frozenset(
+    {
+        "idle",
+        "main_pending",
+        "captured",
+        "evaluating_capture",
+        "debug_stopped",
+        "flushing",
+        "partial_writeback_failure",
+        "breakpoint_restore_failure",
+        "resuming",
+        "recovering",
+        "lost",
+        "completed",
+        "failed",
+    }
+)
+
+
+class BarrierMode(str, Enum):
+    CRASH = "crash"
+    HANG = "hang"
+    LEASE_EXPIRY = "lease_expiry"
+
+
+class _BarrierShutdown(BaseException):
+    """Unwinds driver execution when shutdown arrives at a phase barrier."""
+
+
+Publish = Callable[[MessageKind, dict[str, object]], None]
+BarrierWait = Callable[..., None]
+
+
+class PhaseBarrier:
+    """Publishes a durable phase boundary before entering its wait mode."""
+
+    def __init__(
+        self,
+        *,
+        point: FaultPoint,
+        publish: Publish,
+        flush: Callable[[], None],
+        wait: BarrierWait,
+        mode: BarrierMode = BarrierMode.CRASH,
+        payload: dict[str, object] | None = None,
+    ) -> None:
+        self._point = point
+        self._publish = publish
+        self._flush = flush
+        self._wait = wait
+        self._mode = mode
+        self._payload = payload or {}
+        self._fired = False
+
+    def __call__(self, point: FaultPoint) -> None:
+        if self._fired or point is not self._point:
+            return
+        self._fired = True
+        self._flush()
+        self._publish(
+            MessageKind.PHASE_REACHED,
+            {"point": point.value, **self._payload},
+        )
+        if self._mode is BarrierMode.HANG:
+            self._wait(heartbeat_enabled=False)
+        else:
+            self._wait()
+
+
+class RuntimeDriver(Protocol):
+    def prepare_debug_ui(self) -> None:
+        raise NotImplementedError
+
+    def attach_runtime(self) -> None:
+        raise NotImplementedError
+
+    def execute_phase(self, point: FaultPoint, barrier: PhaseBarrier) -> object:
+        raise NotImplementedError
+
+    def status(self) -> dict[str, object]:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        raise NotImplementedError
+
+
+class ControllerWorker:
+    """Single-writer child control plane for one supervised generation."""
+
+    def __init__(
+        self,
+        generation_id: int,
+        driver: RuntimeDriver,
+        *,
+        connection: Connection | None = None,
+        emit: Callable[[ControlMessage], None] | None = None,
+        clock: Callable[[], float] = monotonic,
+        journal: RecoveryJournal | None = None,
+    ) -> None:
+        if emit is None and connection is None:
+            raise ValueError("ControllerWorker requires a connection or emit callback")
+        self._generation_id = generation_id
+        self._driver = driver
+        self._connection = connection
+        self._emit = emit if emit is not None else connection.send  # type: ignore[union-attr]
+        self._clock = clock
+        self._journal = journal or RecoveryJournal()
+        self._leases = LeaseAuthority(generation_id, clock=clock)
+        self._sender = MessageSender(generation_id)
+        self._receiver = MessageReceiver(generation_id)
+        self._running = True
+        self._at_barrier = False
+        self._barrier_mode: BarrierMode | None = None
+        self._progress_sequence = 0
+        self._last_heartbeat_at = clock()
+
+    def run(self) -> None:
+        try:
+            try:
+                self._run()
+            finally:
+                self._driver.close()
+        except Exception as error:
+            self._publish(
+                MessageKind.FATAL,
+                {"error_type": type(error).__name__},
+            )
+            raise
+
+    def _run(self) -> None:
+        connection = self._require_connection()
+        self._driver.prepare_debug_ui()
+        self._advance_progress()
+        self._publish(MessageKind.DEBUG_READY, {})
+
+        deadline = self._clock() + DEBUGGEE_START_TIMEOUT_S
+        while True:
+            remaining = deadline - self._clock()
+            if remaining <= 0:
+                raise CommandTimeout("Timed out waiting for debuggee start")
+            if not connection.poll(min(WORKER_POLL_INTERVAL_S, remaining)):
+                continue
+            message = connection.recv()
+            self._receiver.accept(message)
+            if message.kind is not MessageKind.DEBUGGEE_STARTED:
+                raise InvalidMessageSequence(
+                    f"Unexpected {message.kind.value} before debuggee start"
+                )
+            self._advance_progress()
+            break
+
+        self._driver.attach_runtime()
+        self._advance_progress()
+        self._publish(MessageKind.READY, {})
+        self._last_heartbeat_at = self._clock()
+
+        while self._running:
+            self._expire_lease()
+            if connection.poll(WORKER_POLL_INTERVAL_S):
+                self.handle_message(connection.recv())
+            self._emit_heartbeat_if_due()
+
+    def handle_message(self, message: ControlMessage) -> None:
+        self._expire_lease()
+        self._receiver.accept(message)
+
+        if message.kind is MessageKind.GRANT_LEASE:
+            self._grant_lease(message.payload)
+        elif message.kind is MessageKind.RENEW_LEASE:
+            self._renew_lease(message.payload)
+        elif message.kind is MessageKind.EXECUTE_PHASE:
+            try:
+                self._execute_phase(message.payload)
+            except _BarrierShutdown:
+                return
+        elif message.kind is MessageKind.STATUS:
+            self._status()
+        elif message.kind is MessageKind.SHUTDOWN:
+            self._running = False
+        else:
+            raise InvalidMessageSequence(
+                f"Unexpected worker command {message.kind.value}"
+            )
+        self._advance_progress()
+
+    def poll_once(self) -> None:
+        self._expire_lease()
+
+    def _grant_lease(self, payload: dict[str, object]) -> None:
+        try:
+            handle = self._leases.grant(
+                self._owner(payload),
+                ttl_s=validate_lease_ttl(payload["ttl_s"]),
+            )
+        except (LeaseConflict, LeaseExpired) as error:
+            self._publish_lease_conflict(error)
+            return
+        self._publish_lease_granted(handle)
+
+    def _renew_lease(self, payload: dict[str, object]) -> None:
+        try:
+            handle = self._leases.renew(
+                self._lease_handle(payload),
+                ttl_s=validate_lease_ttl(payload["ttl_s"]),
+            )
+        except (LeaseConflict, LeaseExpired, StaleLeaseEpoch) as error:
+            self._publish_lease_conflict(error)
+            return
+        self._publish_lease_granted(handle)
+
+    def _execute_phase(self, payload: dict[str, object]) -> None:
+        if self._at_barrier:
+            self._publish_lease_conflict(
+                ControllerUnavailable("A phase barrier is already active")
+            )
+            return
+        try:
+            self._leases.validate(self._lease_handle(payload))
+        except (LeaseConflict, LeaseExpired, StaleLeaseEpoch) as error:
+            self._publish_lease_conflict(error)
+            return
+
+        point = FaultPoint(str(payload["point"]))
+        mode = BarrierMode(str(payload["barrier_mode"]))
+        barrier_payload: dict[str, object] = {}
+        operation_id_value = payload.get("operation_id")
+        operation_id = None
+        if operation_id_value is not None:
+            operation_id = self._positive_int(operation_id_value, "operation_id")
+            barrier_payload["operation_id"] = operation_id
+
+        barrier = PhaseBarrier(
+            point=point,
+            mode=mode,
+            publish=self._publish,
+            flush=self._journal.flush,
+            wait=self._wait_at_barrier,
+            payload=barrier_payload,
+        )
+        self._at_barrier = True
+        self._barrier_mode = mode
+        try:
+            self._driver.execute_phase(point, barrier)
+        finally:
+            self._barrier_mode = None
+            self._at_barrier = False
+        if not self._running:
+            return
+        result_payload: dict[str, object] = {"phase": point.value}
+        if operation_id is not None:
+            result_payload["operation_id"] = operation_id
+        self._publish(MessageKind.OPERATION_RESULT, result_payload)
+
+    def _status(self) -> None:
+        lease = self._leases.status()
+        driver_status = self._driver.status()
+        state = driver_status.get("state")
+        safe_state = (
+            state
+            if type(state) is str and state in SAFE_RUNTIME_STATES
+            else "unknown"
+        )
+        self._publish(
+            MessageKind.STATUS_RESULT,
+            {
+                "state": safe_state,
+                "lease_epoch": lease.lease_epoch,
+                "expires_in_s": lease.expires_in_s,
+                "lease_expired": lease.expired,
+            },
+        )
+
+    def _wait_at_barrier(self, *, heartbeat_enabled: bool = True) -> None:
+        if not heartbeat_enabled:
+            Event().wait()
+            return
+
+        connection = self._require_connection()
+        while self._running:
+            self._expire_lease()
+            if connection.poll(WORKER_POLL_INTERVAL_S):
+                self.handle_message(connection.recv())
+                if not self._running:
+                    raise _BarrierShutdown
+            self._emit_heartbeat_if_due()
+        raise _BarrierShutdown
+
+    def _expire_lease(self) -> None:
+        expired = self._leases.expire_if_due()
+        if expired is None:
+            return
+        self._publish(
+            MessageKind.LEASE_EXPIRED,
+            {"lease_epoch": expired.lease_epoch},
+        )
+
+    def _emit_heartbeat_if_due(self) -> None:
+        now = self._clock()
+        if now - self._last_heartbeat_at < HEARTBEAT_INTERVAL_S:
+            return
+        self._publish(
+            MessageKind.HEARTBEAT,
+            {
+                "progress_sequence": self._progress_sequence,
+                "busy_deadline": None,
+            },
+        )
+        self._last_heartbeat_at = now
+
+    def _publish_lease_granted(self, handle: LeaseHandle) -> None:
+        self._publish(
+            MessageKind.LEASE_GRANTED,
+            {
+                "lease_epoch": handle.lease_epoch,
+                "expires_in_s": self._leases.status().expires_in_s,
+            },
+        )
+
+    def _publish_lease_conflict(self, error: Exception) -> None:
+        self._publish(
+            MessageKind.LEASE_CONFLICT,
+            {"error_type": type(error).__name__},
+        )
+
+    def _publish(self, kind: MessageKind, payload: dict[str, object]) -> None:
+        self._emit(self._sender.create(kind, **payload))
+
+    def _lease_handle(self, payload: dict[str, object]) -> LeaseHandle:
+        return LeaseHandle(
+            generation_id=self._generation_id,
+            owner_id=self._owner(payload),
+            lease_epoch=self._positive_int(payload["lease_epoch"], "lease_epoch"),
+        )
+
+    @staticmethod
+    def _owner(payload: dict[str, object]) -> UUID:
+        return UUID(str(payload["owner_id"]))
+
+    @staticmethod
+    def _positive_int(value: object, field_name: str) -> int:
+        if type(value) is not int:
+            raise ValueError(f"{field_name} must be an integer")
+        if value <= 0:
+            raise ValueError(f"{field_name} must be positive")
+        return value
+
+    def _advance_progress(self) -> None:
+        self._progress_sequence += 1
+
+    def _require_connection(self) -> Connection:
+        if self._connection is None:
+            raise RuntimeError("ControllerWorker command loop requires a connection")
+        return self._connection
+
+
+def controller_worker_main(
+    generation_id: int,
+    connection: Connection,
+    driver: RuntimeDriver,
+    journal: RecoveryJournal | None = None,
+) -> None:
+    ControllerWorker(
+        generation_id,
+        driver,
+        connection=connection,
+        journal=journal,
+    ).run()

onec_runtime/credentials.py

@@ -0,0 +1,18 @@
+"""Safe diagnostic representations of 1C launch arguments."""
+
+from collections.abc import Sequence
+
+
+def redact_command(command: Sequence[str]) -> tuple[str, ...]:
+    """Hide /P values; consume /N values even when they look like switches."""
+    result: list[str] = []
+    credential: str | None = None
+    for argument in command:
+        if credential is not None:
+            result.append("<redacted>" if credential == "/p" and argument else argument)
+            credential = None
+        else:
+            result.append(argument)
+            if argument.casefold() in ("/n", "/p"):
+                credential = argument.casefold()
+    return tuple(result)

onec_runtime/epf_container.py

@@ -0,0 +1,196 @@
+from __future__ import annotations
+
+"""Minimal deterministic codec for the 32-bit 1C container used by Worker EPF.
+
+The layout and field interpretation are derived from the MIT-licensed
+``saby-integration/v8unpack`` container reader/writer (copyright 2015
+Infactum).  This module intentionally implements only the bounded format used
+by the one-object-module runtime Worker; it is not a general 1C file library.
+"""
+
+from collections.abc import Mapping
+from io import BytesIO
+from struct import Struct
+import zlib
+
+
+_END_MARKER = 0x7FFFFFFF
+_DEFAULT_BLOCK_SIZE = 0x200
+_CONTAINER_HEADER = Struct("<4i")
+_INDEX_ENTRY = Struct("<3i")
+_FILE_ATTRIBUTES = Struct("<QQi")
+_BLOCK_HEADER_SIZE = 31
+_INDEX_OFFSET = _CONTAINER_HEADER.size
+
+
+class EpfContainerError(ValueError):
+    """The byte sequence is outside the supported bounded container format."""
+
+
+def raw_deflate(payload: bytes) -> bytes:
+    compressor = zlib.compressobj(wbits=-15)
+    return compressor.compress(payload) + compressor.flush()
+
+
+def raw_inflate(payload: bytes) -> bytes:
+    try:
+        decompressor = zlib.decompressobj(wbits=-15)
+        result = decompressor.decompress(payload) + decompressor.flush()
+    except zlib.error as error:
+        raise EpfContainerError("Invalid raw-deflate stream") from error
+    if not decompressor.eof:
+        raise EpfContainerError("Invalid raw-deflate stream is truncated")
+    if decompressor.unused_data or decompressor.unconsumed_tail:
+        raise EpfContainerError("Invalid raw-deflate stream contains trailing data")
+    return result
+
+
+def build_container(entries: Mapping[str, bytes]) -> bytes:
+    ordered = tuple(sorted(entries.items()))
+    if not ordered:
+        raise EpfContainerError("Container must contain at least one entry")
+    if len({name for name, _payload in ordered}) != len(ordered):
+        raise EpfContainerError("Container entry names must be unique")
+
+    stream = BytesIO()
+    stream.write(
+        _CONTAINER_HEADER.pack(
+            _END_MARKER,
+            _DEFAULT_BLOCK_SIZE,
+            len(ordered),
+            0,
+        )
+    )
+    stream.write(b"\x00" * (_BLOCK_HEADER_SIZE + _DEFAULT_BLOCK_SIZE))
+
+    table: list[tuple[int, int]] = []
+    for name, payload in ordered:
+        if not name or "\x00" in name:
+            raise EpfContainerError("Container entry name is invalid")
+        if not isinstance(payload, bytes):
+            raise TypeError("Container entries must contain bytes")
+        attributes = (
+            _FILE_ATTRIBUTES.pack(0, 0, 0)
+            + name.encode("utf-16-le")
+            + b"\x00" * 4
+        )
+        attribute_offset = _write_document(stream, attributes)
+        data_offset = _write_document(
+            stream,
+            payload,
+            minimum_block_size=_DEFAULT_BLOCK_SIZE,
+        )
+        table.append((attribute_offset, data_offset))
+
+    toc = b"".join(
+        _INDEX_ENTRY.pack(attribute_offset, data_offset, _END_MARKER)
+        for attribute_offset, data_offset in table
+    )
+    _write_document(
+        stream,
+        toc,
+        minimum_block_size=_DEFAULT_BLOCK_SIZE,
+        offset=_INDEX_OFFSET,
+    )
+    return stream.getvalue()
+
+
+def read_container(payload: bytes) -> dict[str, bytes]:
+    if len(payload) < _INDEX_OFFSET + _BLOCK_HEADER_SIZE:
+        raise EpfContainerError("Container is truncated")
+    try:
+        end_marker, block_size, count, reserved = _CONTAINER_HEADER.unpack_from(
+            payload, 0
+        )
+    except Exception as error:
+        raise EpfContainerError("Container header is invalid") from error
+    if (
+        end_marker != _END_MARKER
+        or block_size != _DEFAULT_BLOCK_SIZE
+        or count <= 0
+        or reserved != 0
+    ):
+        raise EpfContainerError("Container header is unsupported")
+
+    toc = _read_document(payload, _INDEX_OFFSET)
+    if not toc or len(toc) % _INDEX_ENTRY.size:
+        raise EpfContainerError("Container table of contents is invalid")
+
+    result: dict[str, bytes] = {}
+    # Platform-built nested module containers may retain a header count that is
+    # one lower than the actual TOC entry count.  v8unpack likewise treats the
+    # bounded TOC document as authoritative.
+    toc_count = len(toc) // _INDEX_ENTRY.size
+    if toc_count not in {count, count + 1}:
+        raise EpfContainerError("Container entry count does not match its bounded TOC")
+    for index in range(toc_count):
+        position = index * _INDEX_ENTRY.size
+        attribute_offset, data_offset, marker = _INDEX_ENTRY.unpack_from(toc, position)
+        if marker != _END_MARKER:
+            raise EpfContainerError("Container table marker is invalid")
+        attributes = _read_document(payload, attribute_offset)
+        if len(attributes) < _FILE_ATTRIBUTES.size + 4:
+            raise EpfContainerError("Container entry attributes are truncated")
+        name_bytes = attributes[_FILE_ATTRIBUTES.size :]
+        try:
+            name = name_bytes.decode("utf-16-le").split("\x00", 1)[0]
+        except UnicodeDecodeError as error:
+            raise EpfContainerError("Container entry name is invalid") from error
+        if not name or name in result:
+            raise EpfContainerError("Container entry name is empty or duplicated")
+        result[name] = _read_document(payload, data_offset)
+    return result
+
+
+def _write_document(
+    stream: BytesIO,
+    data: bytes,
+    *,
+    minimum_block_size: int = 0,
+    offset: int | None = None,
+) -> int:
+    if offset is None:
+        stream.seek(0, 2)
+        offset = stream.tell()
+    else:
+        stream.seek(offset)
+    current_block_size = max(minimum_block_size, len(data))
+    if current_block_size > _END_MARKER:
+        raise EpfContainerError("Container document is too large")
+    header = (
+        f"\r\n{len(data):08x} {current_block_size:08x} "
+        f"{_END_MARKER:08x} \r\n"
+    ).encode("ascii")
+    if len(header) != _BLOCK_HEADER_SIZE:
+        raise AssertionError("Unexpected 1C block header size")
+    stream.write(header)
+    stream.write(data)
+    stream.write(b"\x00" * (current_block_size - len(data)))
+    return offset
+
+
+def _read_document(payload: bytes, offset: int) -> bytes:
+    if offset < _INDEX_OFFSET or offset + _BLOCK_HEADER_SIZE > len(payload):
+        raise EpfContainerError("Container document offset is outside the file")
+    header = payload[offset : offset + _BLOCK_HEADER_SIZE]
+    if (
+        header[:2] != b"\r\n"
+        or header[10:11] != b" "
+        or header[19:20] != b" "
+        or header[28:29] != b" "
+        or header[29:] != b"\r\n"
+    ):
+        raise EpfContainerError("Container document header is invalid")
+    try:
+        document_size = int(header[2:10], 16)
+        current_block_size = int(header[11:19], 16)
+        next_offset = int(header[20:28], 16)
+    except ValueError as error:
+        raise EpfContainerError("Container document size is invalid") from error
+    if current_block_size < document_size or next_offset != _END_MARKER:
+        raise EpfContainerError("Chained container documents are unsupported")
+    start = offset + _BLOCK_HEADER_SIZE
+    end = start + current_block_size
+    if end > len(payload):
+        raise EpfContainerError("Container document is truncated")
+    return payload[start : start + document_size]