ferp 0.7.1__py3-none-any.whl

ferp/fscp/host/host.py

@@ -0,0 +1,439 @@
+from __future__ import annotations
+
+import json
+import time
+from typing import Optional
+
+from ferp.fscp.host.managed_process import ManagedProcess, WorkerFn
+from ferp.fscp.host.process_registry import (
+    ProcessMetadata,
+    ProcessRegistry,
+)
+from ferp.fscp.protocol.messages import Message, MessageDirection, MessageType
+from ferp.fscp.protocol.state import HostState
+from ferp.fscp.protocol.validator import Endpoint, ProtocolValidator
+from ferp.fscp.transcript.events import TranscriptEvent
+
+
+class Host:
+    """
+    Authoritative ferp.fscp host.
+    """
+
+    def __init__(
+        self,
+        worker: WorkerFn,
+        timeout_ms: Optional[int] = None,
+        validator: Optional[ProtocolValidator] = None,
+        process_registry: ProcessRegistry | None = None,
+        process_metadata: ProcessMetadata | None = None,
+    ) -> None:
+        self.state: HostState = HostState.CREATED
+        self.process = ManagedProcess(worker=worker)
+
+        self.timeout_ms = timeout_ms
+        self.validator = validator or ProtocolValidator()
+        self._registry = process_registry
+        self._process_metadata = process_metadata
+        self._process_handle: str | None = None
+
+        self.transcript: list[TranscriptEvent] = []
+        self.results: list[dict] = []
+
+        self._start_time: Optional[float] = None
+        self._exit_seen = False
+        self._progress_updates: list[dict] = []
+        self._termination_mode: str | None = None
+
+        self._record_system("Host created")
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def start(self) -> None:
+        if self.state is not HostState.CREATED:
+            raise RuntimeError("Host can only be started from CREATED")
+
+        self.process.start()
+        self._register_process()
+        self._start_time = time.time()
+
+        self._transition(HostState.PROCESS_STARTED)
+
+    def poll(self) -> None:
+        if self.state in {
+            HostState.TERMINATED,
+            HostState.ERR_PROTOCOL,
+            HostState.ERR_TRANSPORT,
+        }:
+            return
+
+        self._check_timeout()
+
+        conn = self.process.connection
+        if conn is not None:
+            # -------------------------
+            # Drain messages from the pipe
+            # -------------------------
+            while True:
+                try:
+                    has_data = conn.poll(0)
+                except (OSError, ValueError) as exc:
+                    if self._exit_seen:
+                        self._cleanup_connection()
+                        break
+                    self._fail_transport(f"Connection poll failed: {exc}")
+                    return
+
+                if not has_data:
+                    break
+
+                try:
+                    payload = conn.recv()
+                except EOFError:
+                    if self._exit_seen:
+                        self._cleanup_connection()
+                        break
+                    if self.state is HostState.CANCELLING:
+                        self._record_system("Script connection closed during cancellation")
+                        self._cleanup_connection()
+                        exit_code = self.process.poll_exit()
+                        if exit_code is None:
+                            self._termination_mode = self._termination_mode or "cancel"
+                            self._record_exit(self.process.exit_code)
+                        else:
+                            if not self._exit_seen:
+                                self._termination_mode = self._termination_mode or "cancel"
+                            self._record_exit(exit_code)
+                        self._transition(HostState.TERMINATED)
+                        return
+                    self._fail_transport("Script connection closed unexpectedly")
+                    return
+                except Exception as exc:
+                    if self.state is HostState.CANCELLING:
+                        self._record_system(f"Pipe read error during cancellation: {exc}")
+                        self._cleanup_connection()
+                        exit_code = self.process.poll_exit()
+                        if exit_code is None:
+                            self._termination_mode = self._termination_mode or "cancel"
+                            self._record_exit(self.process.exit_code)
+                        else:
+                            if not self._exit_seen:
+                                self._termination_mode = self._termination_mode or "cancel"
+                            self._record_exit(exit_code)
+                        self._transition(HostState.TERMINATED)
+                        return
+                    self._fail_transport(f"Pipe read error: {exc}")
+                    return
+
+                if not isinstance(payload, dict):
+                    self._record_incoming(raw=str(payload), msg=None)
+                    self._fail_protocol("Invalid payload received from script")
+                    return
+
+                raw = json.dumps(payload)
+                try:
+                    msg = Message.from_dict(payload)
+                except Exception as exc:
+                    self._record_incoming(raw=raw, msg=None)
+                    self._fail_protocol(f"Invalid ferp.fscp message: {exc}")
+                    return
+
+                self.receive(msg, raw=raw)
+
+        # -------------------------
+        # Process exit detection
+        # -------------------------
+        exit_code = self.process.poll_exit()
+        if exit_code is None:
+            return
+
+        self._cleanup_connection()
+
+        if not self._exit_seen:
+            self._record_system("Process exited without exit message (abnormal)")
+            self._termination_mode = self._termination_mode or "abnormal-exit"
+
+        self._record_exit(exit_code)
+        self._transition(HostState.TERMINATED)
+
+    def shutdown(self, *, force: bool = False) -> None:
+        if self.state in {
+            HostState.TERMINATED,
+            HostState.ERR_PROTOCOL,
+            HostState.ERR_TRANSPORT,
+        }:
+            return
+
+        self._record_system("Shutdown initiated")
+        self._transition(HostState.CANCELLING)
+        self._termination_mode = "kill" if force else "terminate"
+
+        if force:
+            self.process.kill()
+        else:
+            self.process.terminate()
+        self._cleanup_connection()
+
+        # Ensure the registry sees a terminal state even if we don't poll again.
+        self._record_exit(self.process.exit_code)
+        self._transition(HostState.TERMINATED)
+
+    def request_cancel(self) -> None:
+        if self.state in {
+            HostState.TERMINATED,
+            HostState.ERR_PROTOCOL,
+            HostState.ERR_TRANSPORT,
+        }:
+            return
+
+        self._record_system("Cancellation requested")
+        self._termination_mode = self._termination_mode or "cancel"
+        msg = Message(type=MessageType.CANCEL, payload={})
+        self.send(msg)
+
+    # ------------------------------------------------------------------
+    # Protocol IO
+    # ------------------------------------------------------------------
+
+    def send(self, msg: Message) -> None:
+        self.validator.validate(msg, sender=Endpoint.HOST)
+
+        if msg.type is MessageType.INIT:
+            self._transition(HostState.INIT_SENT)
+
+        self._dispatch(msg)
+        self._record_outgoing(msg)
+
+    def receive(self, msg: Message, *, raw: Optional[str] = None) -> None:
+        self.validator.validate(msg, sender=Endpoint.SCRIPT)
+        self._handle_incoming(msg)
+        self._record_incoming(raw, msg)
+
+    def provide_input(self, payload: dict) -> None:
+        if self.state is not HostState.AWAITING_INPUT:
+            raise RuntimeError("No input is currently awaited")
+
+        msg = Message(type=MessageType.INPUT_RESPONSE, payload=payload)
+        self._transition(HostState.RUNNING)
+        self.send(msg)
+
+    def record_system(self, note: str) -> None:
+        """Add a system note to the transcript."""
+        self._record_system(note)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _dispatch(self, msg: Message) -> None:
+        conn = self.process.connection
+        if conn is None:
+            raise RuntimeError("Process connection unavailable")
+
+        payload = msg.to_dict()
+        try:
+            conn.send(payload)
+        except Exception as exc:
+            self._record_system(f"Pipe send failed: {exc}")
+            self._transition(HostState.ERR_TRANSPORT)
+            raise
+
+    def _cleanup_connection(self) -> None:
+        conn = self.process.connection
+        if conn is None:
+            return
+        try:
+            conn.close()
+        except Exception:
+            pass
+        finally:
+            self.process.connection = None
+
+    def _fail_transport(self, note: str) -> None:
+        if self.state not in {
+            HostState.TERMINATED,
+            HostState.ERR_PROTOCOL,
+            HostState.ERR_TRANSPORT,
+        }:
+            self._record_system(note)
+            self._transition(HostState.ERR_TRANSPORT)
+        self._termination_mode = self._termination_mode or "transport-error"
+        try:
+            self.process.kill()
+        except Exception:
+            pass
+        self._cleanup_connection()
+
+    def _fail_protocol(self, note: str) -> None:
+        if self.state not in {
+            HostState.TERMINATED,
+            HostState.ERR_PROTOCOL,
+            HostState.ERR_TRANSPORT,
+        }:
+            self._record_system(note)
+            self._transition(HostState.ERR_PROTOCOL)
+        self._termination_mode = self._termination_mode or "protocol-error"
+        try:
+            self.process.kill()
+        except Exception:
+            pass
+        self._cleanup_connection()
+
+    def _handle_incoming(self, msg: Message) -> None:
+        if self.state in {
+            HostState.TERMINATED,
+            HostState.ERR_PROTOCOL,
+            HostState.ERR_TRANSPORT,
+        }:
+            self._protocol_violation("Message received after termination")
+            return
+
+        if self.state is HostState.INIT_SENT:
+            self._transition(HostState.RUNNING)
+
+        match msg.type:
+            case MessageType.LOG:
+                return
+
+            case MessageType.PROGRESS:
+                payload = dict(msg.payload) if msg.payload else {}
+                self._progress_updates.append(payload)
+                return
+
+            case MessageType.RESULT:
+                if self._exit_seen:
+                    self._protocol_violation("Result after exit")
+                    return
+
+                self.results.append(dict(msg.payload))
+                return
+
+            case MessageType.REQUEST_INPUT:
+                if self.state is HostState.AWAITING_INPUT:
+                    self._protocol_violation("Multiple outstanding input requests")
+                    return
+
+                if self.state is not HostState.RUNNING:
+                    self._protocol_violation(
+                        f"'request_input' not allowed in state {self.state.name}"
+                    )
+                    return
+
+                self._transition(HostState.AWAITING_INPUT)
+                return
+
+            case MessageType.EXIT:
+                if self._exit_seen:
+                    self._protocol_violation("Duplicate exit")
+                    return
+                self._exit_seen = True
+                self._record_system(f"Exit received: {msg.payload}")
+                self._termination_mode = self._termination_mode or "exit"
+                self._transition(HostState.EXIT_RECEIVED)
+                return
+
+            case _:
+                self._protocol_violation(f"Unhandled message: {msg.type.value}")
+                return
+
+    def _protocol_violation(self, reason: str) -> None:
+        self._fail_protocol(f"Protocol violation: {reason}")
+
+    # ------------------------------------------------------------------
+    # State + timeout
+    # ------------------------------------------------------------------
+
+    def _transition(self, new_state: HostState) -> None:
+        self._record_system(f"State {self.state.name} → {new_state.name}")
+        self.state = new_state
+        self._update_registry_state()
+
+    def _check_timeout(self) -> None:
+        if self.timeout_ms is None or self._start_time is None:
+            return
+
+        elapsed_ms = (time.time() - self._start_time) * 1000
+        if elapsed_ms > self.timeout_ms:
+            self._record_system("Execution timeout")
+            self.shutdown(force=True)
+
+    # ------------------------------------------------------------------
+    # Transcript
+    # ------------------------------------------------------------------
+
+    def _record_incoming(
+        self,
+        raw: Optional[str],
+        msg: Optional[Message],
+    ) -> None:
+        self.transcript.append(
+            TranscriptEvent(
+                timestamp=time.time(),
+                direction=MessageDirection.RECV,
+                raw=raw,
+                message=msg,
+            )
+        )
+
+    def _record_outgoing(self, msg: Message) -> None:
+        self.transcript.append(
+            TranscriptEvent(
+                timestamp=time.time(),
+                direction=MessageDirection.SEND,
+                message=msg,
+            )
+        )
+
+    def _record_system(self, note: str) -> None:
+        self.transcript.append(
+            TranscriptEvent(
+                timestamp=time.time(),
+                direction=MessageDirection.INTERNAL,
+                raw=note,
+            )
+        )
+
+    def drain_progress_updates(self) -> list[dict]:
+        updates = self._progress_updates
+        self._progress_updates = []
+        return updates
+
+    # ------------------------------------------------------------------
+    # Process registry helpers
+    # ------------------------------------------------------------------
+
+    @property
+    def process_handle(self) -> str | None:
+        return self._process_handle
+
+    def _register_process(self) -> None:
+        if self._registry is None:
+            return
+
+        pid = self.process.process.pid if self.process.process else None
+        metadata = self._process_metadata
+        if metadata is None:
+            return
+
+        record = self._registry.register(
+            metadata,
+            pid=pid,
+            state=HostState.PROCESS_STARTED,
+        )
+        self._process_handle = record.handle
+
+    def _update_registry_state(self) -> None:
+        if self._registry is None or self._process_handle is None:
+            return
+        self._registry.update_state(self._process_handle, self.state)
+
+    def _record_exit(self, exit_code: int | None) -> None:
+        if self._registry is None or self._process_handle is None:
+            return
+        self._registry.record_exit(
+            self._process_handle,
+            exit_code,
+            termination_mode=self._termination_mode,
+        )

ferp/fscp/host/managed_process.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from multiprocessing import Pipe, Process
+from multiprocessing.connection import Connection
+from typing import Callable, Optional
+
+WorkerFn = Callable[[Connection], None]
+
+
+@dataclass
+class ManagedProcess:
+    worker: WorkerFn
+
+    process: Optional[Process] = field(init=False, default=None)
+    connection: Optional[Connection] = field(init=False, default=None)
+    start_time: Optional[float] = field(init=False, default=None)
+    exit_code: Optional[int] = field(init=False, default=None)
+
+    def start(self) -> None:
+        """
+        Spawn the worker inside a multiprocessing.Process with a duplex Pipe.
+        """
+        if self.process is not None:
+            raise RuntimeError("Process already started")
+
+        parent_conn, child_conn = Pipe()
+
+        proc = Process(
+            target=self._bootstrap_worker,
+            args=(self.worker, child_conn),
+            daemon=False,
+        )
+        proc.start()
+
+        # Parent keeps the parent-side connection only.
+        child_conn.close()
+
+        self.process = proc
+        self.connection = parent_conn
+        self.start_time = time.time()
+
+    def terminate(self) -> None:
+        """
+        Attempt graceful termination of the worker.
+        """
+        if self.process is None:
+            return
+
+        self.process.terminate()
+        if not self._wait_for_exit(timeout=1.0):
+            # Process refused to exit, escalate to a kill.
+            self.kill()
+            return
+        self._cleanup_connection()
+
+    def kill(self) -> None:
+        """
+        Forcefully kill the worker.
+        """
+        if self.process is None:
+            return
+
+        self.process.kill()
+        self._wait_for_exit(timeout=1.0)
+        self._cleanup_connection()
+
+    def poll_exit(self) -> Optional[int]:
+        """
+        Return the worker's exit code if it has finished.
+        """
+        if self.process is None:
+            return None
+
+        if self.process.exitcode is None:
+            self.process.join(timeout=0)
+
+        self.exit_code = self.process.exitcode
+        return self.exit_code
+
+    def _wait_for_exit(self, *, timeout: Optional[float]) -> bool:
+        """
+        Wait for the subprocess to exit. Returns True if it exited.
+        """
+        if self.process is None:
+            return True
+
+        self.process.join(timeout=timeout)
+        if self.process.exitcode is not None:
+            self.exit_code = self.process.exitcode
+            return True
+
+        return False
+
+    def _cleanup_connection(self) -> None:
+        if self.connection is not None:
+            try:
+                self.connection.close()
+            except Exception:
+                pass
+            finally:
+                self.connection = None
+
+    @staticmethod
+    def _bootstrap_worker(worker: WorkerFn, conn: Connection) -> None:
+        try:
+            worker(conn)
+        finally:
+            try:
+                conn.close()
+            except Exception:
+                pass

ferp/fscp/host/process_registry.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import itertools
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from threading import Lock
+
+from ferp.fscp.protocol.state import HostState
+
+_TERMINAL_STATES = {
+    HostState.TERMINATED,
+    HostState.ERR_PROTOCOL,
+    HostState.ERR_TRANSPORT,
+}
+
+
+@dataclass(frozen=True)
+class ProcessMetadata:
+    script_name: str
+    script_id: str | None
+    target_path: Path
+
+
+@dataclass
+class ProcessRecord:
+    handle: str
+    pid: int | None
+    metadata: ProcessMetadata
+    state: HostState
+    start_time: float
+    exit_code: int | None = None
+    end_time: float | None = None
+    termination_mode: str | None = None
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.state in _TERMINAL_STATES
+
+
+class ProcessRegistry:
+    """Tracks processes spawned by the FSCP host."""
+
+    def __init__(self) -> None:
+        self._records: dict[str, ProcessRecord] = {}
+        self._lock = Lock()
+        self._counter = itertools.count(1)
+
+    def register(
+        self, metadata: ProcessMetadata, *, pid: int | None, state: HostState
+    ) -> ProcessRecord:
+        handle = f"proc-{next(self._counter)}"
+        record = ProcessRecord(
+            handle=handle,
+            pid=pid,
+            metadata=metadata,
+            state=state,
+            start_time=time.time(),
+        )
+        with self._lock:
+            self._records[handle] = record
+        return record
+
+    def update_state(self, handle: str, state: HostState) -> None:
+        with self._lock:
+            record = self._records.get(handle)
+            if record is None:
+                return
+            record.state = state
+            if state in _TERMINAL_STATES:
+                record.end_time = record.end_time or time.time()
+
+    def record_exit(
+        self, handle: str, exit_code: int | None, *, termination_mode: str | None
+    ) -> None:
+        with self._lock:
+            record = self._records.get(handle)
+            if record is None:
+                return
+            record.exit_code = exit_code
+            if termination_mode:
+                record.termination_mode = termination_mode
+            record.end_time = record.end_time or time.time()
+            if record.state not in _TERMINAL_STATES:
+                record.state = HostState.TERMINATED
+
+    def list_all(self) -> list[ProcessRecord]:
+        with self._lock:
+            return [self._clone(record) for record in self._records.values()]
+
+    def list_active(self) -> list[ProcessRecord]:
+        with self._lock:
+            return [
+                self._clone(record)
+                for record in self._records.values()
+                if not record.is_terminal
+            ]
+
+    def prune_finished(self) -> list[ProcessRecord]:
+        with self._lock:
+            finished = [
+                handle for handle, record in self._records.items() if record.is_terminal
+            ]
+            removed = [self._records.pop(handle) for handle in finished]
+        return [self._clone(record) for record in removed]
+
+    def _clone(self, record: ProcessRecord) -> ProcessRecord:
+        return ProcessRecord(
+            handle=record.handle,
+            pid=record.pid,
+            metadata=record.metadata,
+            state=record.state,
+            start_time=record.start_time,
+            exit_code=record.exit_code,
+            end_time=record.end_time,
+            termination_mode=record.termination_mode,
+        )
+
+
+__all__ = [
+    "ProcessMetadata",
+    "ProcessRecord",
+    "ProcessRegistry",
+]

ferp/fscp/protocol/__init__.py

@@ -0,0 +1,13 @@
+from .errors import ProtocolViolation
+from .messages import Message, MessageDirection, MessageType
+from .state import HostState
+from .validator import ProtocolValidator
+
+__all__ = [
+    "HostState",
+    "Message",
+    "MessageType",
+    "MessageDirection",
+    "ProtocolValidator",
+    "ProtocolViolation",
+]

ferp/fscp/protocol/errors.py

@@ -0,0 +1,2 @@
+class ProtocolViolation(RuntimeError):
+    """Raised when protocol rules are violated."""