PKIPC 2.0.0__py3-none-any.whl

pkipc/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from .client import Client
+from .server import Server
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "Client",
+    "Server",
+    "__version__",
+]

pkipc/_grpc_common.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+ENDPOINT_ENV = "PKIPC_ENDPOINT"
+TOKEN_ENV = "PKIPC_TOKEN"
+TOKEN_METADATA_KEY = "x-pkipc-token"
+MAX_MESSAGE_BYTES = 16 * 1024 * 1024
+OUTGOING_QUEUE_SIZE = 256
+
+GRPC_OPTIONS: tuple[tuple[str, int], ...] = (
+    ("grpc.max_receive_message_length", MAX_MESSAGE_BYTES),
+    ("grpc.max_send_message_length", MAX_MESSAGE_BYTES),
+)

pkipc/_grpc_host.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import hmac
+import logging
+import threading
+from collections.abc import Callable, Iterator
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any
+
+import grpc
+
+from ._grpc_common import GRPC_OPTIONS, TOKEN_METADATA_KEY
+from ._runtime import CONFIG_EVENT, HandlerResolver, Runtime
+from .proto import pkipc_pb2, pkipc_pb2_grpc
+
+LOGGER = logging.getLogger(__name__)
+CloseCallback = Callable[[], None]
+
+
+class _HostServicer(pkipc_pb2_grpc.RuntimeServicer):
+    def __init__(self, host: GrpcHost) -> None:
+        self._host = host
+
+    def Run(
+        self,
+        request_iterator: Iterator[pkipc_pb2.Frame],
+        context: grpc.ServicerContext,
+    ) -> Iterator[pkipc_pb2.Frame]:
+        supplied_token = ""
+        for key, value in context.invocation_metadata():
+            if key == TOKEN_METADATA_KEY:
+                supplied_token = value
+                break
+
+        if not hmac.compare_digest(supplied_token, self._host._token):
+            context.abort(grpc.StatusCode.UNAUTHENTICATED, "Invalid PKIPC token")
+
+        if not self._host._attach(context):
+            context.abort(grpc.StatusCode.ALREADY_EXISTS, "Worker is already attached")
+
+        reader = threading.Thread(
+            target=self._host._read_worker_events,
+            args=(request_iterator, context),
+            name="pkipc-host-reader",
+            daemon=True,
+        )
+        reader.start()
+
+        try:
+            yield from self._host._runtime
+        finally:
+            self._host._mark_stream_closed()
+            reader.join(timeout=1.0)
+
+
+class GrpcHost:
+    """Parent-side gRPC endpoint for exactly one worker process."""
+
+    def __init__(
+        self,
+        *,
+        token: str,
+        config: dict[str, Any],
+        resolve_handler: HandlerResolver,
+        on_close: CloseCallback,
+    ) -> None:
+        self._token = token
+        self._on_close = on_close
+        self._runtime = Runtime(resolve_handler=resolve_handler)
+        self._runtime.send(CONFIG_EVENT, config)
+        self._server: grpc.Server | None = None
+        self._attached = threading.Event()
+        self._stream_closed = threading.Event()
+        self._attach_lock = threading.Lock()
+        self._close_lock = threading.Lock()
+
+    def start(self) -> str:
+        if self._server is not None:
+            raise RuntimeError("gRPC host is already started")
+
+        server = grpc.server(ThreadPoolExecutor(max_workers=2), options=GRPC_OPTIONS)
+        pkipc_pb2_grpc.add_RuntimeServicer_to_server(_HostServicer(self), server)
+        port = server.add_insecure_port("127.0.0.1:0")
+        if port == 0:
+            raise OSError("Failed to bind the PKIPC gRPC host")
+        server.start()
+        self._server = server
+        return f"127.0.0.1:{port}"
+
+    def wait_for_attach(self, timeout: float) -> bool:
+        return self._attached.wait(timeout=max(0.0, timeout))
+
+    def wait_for_close(self, timeout: float) -> bool:
+        return self._stream_closed.wait(timeout=max(0.0, timeout))
+
+    def send(self, event: str, data: Any) -> None:
+        if not self.is_connected():
+            raise ConnectionError("Worker is not connected")
+        self._runtime.send(event, data)
+
+    def request(self, event: str, data: Any, timeout: float) -> Any:
+        if not self.is_connected():
+            raise ConnectionError("Worker is not connected")
+        return self._runtime.request(event, data, timeout)
+
+    def close_stream(self) -> None:
+        self._runtime.close()
+
+    def stop(self, grace: float = 0.5) -> None:
+        self.close_stream()
+        server = self._server
+        self._server = None
+        if server is not None:
+            server.stop(max(0.0, grace)).wait(timeout=max(1.0, grace + 0.5))
+
+    def is_connected(self) -> bool:
+        return self._attached.is_set() and not self._stream_closed.is_set()
+
+    def _attach(self, context: grpc.ServicerContext) -> bool:
+        with self._attach_lock:
+            if self._attached.is_set() or self._runtime.is_closed():
+                return False
+            context.add_callback(self._mark_stream_closed)
+            self._attached.set()
+            return True
+
+    def _read_worker_events(
+        self,
+        request_iterator: Iterator[pkipc_pb2.Frame],
+        context: grpc.ServicerContext,
+    ) -> None:
+        try:
+            for frame in request_iterator:
+                self._runtime.dispatch(frame)
+        except ValueError as exc:
+            context.set_code(grpc.StatusCode.INVALID_ARGUMENT)
+            context.set_details(str(exc))
+        except grpc.RpcError:
+            pass
+        finally:
+            self._runtime.close()
+            self._mark_stream_closed()
+
+    def _mark_stream_closed(self) -> None:
+        with self._close_lock:
+            if self._stream_closed.is_set():
+                return
+            self._stream_closed.set()
+        self._runtime.close()
+        try:
+            self._on_close()
+        except Exception:
+            LOGGER.exception("Close callback raised")

pkipc/_runtime.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+import json
+import logging
+import math
+import threading
+import time
+import uuid
+from collections.abc import Callable, Iterator
+from concurrent.futures import Future
+from dataclasses import dataclass
+from typing import Any
+
+from ._stream import OutgoingStream
+from .proto import pkipc_pb2
+
+CONFIG_EVENT = "pkipc.config"
+CONTROL_EVENT = "pkipc.control"
+LOG_EVENT = "pkipc.log"
+RESPONSE_EVENT = "pkipc.response"
+
+LOGGER = logging.getLogger(__name__)
+EventHandler = Callable[[Any], Any]
+HandlerResolver = Callable[[str], EventHandler | None]
+
+
+@dataclass(frozen=True, slots=True)
+class Envelope:
+    event: str
+    data: Any
+    request_id: str | None = None
+    reply_to: str | None = None
+    error: str | None = None
+
+
+def encode_frame(
+    event: str,
+    data: Any,
+    *,
+    request_id: str | None = None,
+    reply_to: str | None = None,
+    error: str | None = None,
+) -> pkipc_pb2.Frame:
+    """Encode one application envelope into a transport frame."""
+    envelope = Envelope(event, data, request_id, reply_to, error)
+    _validate_envelope(envelope)
+    value: dict[str, Any] = {"event": event, "data": data}
+    if request_id is not None:
+        value["id"] = request_id
+    if reply_to is not None:
+        value["reply_to"] = reply_to
+    if error is not None:
+        value["error"] = error
+    try:
+        payload = json.dumps(
+            value,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            allow_nan=False,
+        ).encode("utf-8")
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"Event data is not valid JSON: {exc}") from exc
+    return pkipc_pb2.Frame(payload=payload)
+
+
+def decode_frame(frame: pkipc_pb2.Frame) -> Envelope:
+    """Decode and validate one transport frame."""
+    try:
+        value = json.loads(
+            frame.payload.decode("utf-8"),
+            parse_constant=_raise_invalid_constant,
+        )
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"Frame payload is not valid UTF-8 JSON: {exc}") from exc
+
+    if not isinstance(value, dict):
+        raise ValueError("Frame payload must be a JSON object")
+    if "event" not in value or "data" not in value:
+        raise ValueError("Frame payload requires event and data fields")
+
+    envelope = Envelope(
+        event=value["event"],
+        data=value["data"],
+        request_id=value.get("id"),
+        reply_to=value.get("reply_to"),
+        error=value.get("error"),
+    )
+    _validate_envelope(envelope)
+    return envelope
+
+
+class Runtime:
+    """Encode, route, correlate, and queue PKIPC application events."""
+
+    def __init__(
+        self,
+        *,
+        first_event: str | None = None,
+        resolve_handler: HandlerResolver | None = None,
+    ) -> None:
+        if first_event is not None:
+            validate_event_name(first_event)
+        self._first_event = first_event
+        self._resolve_handler = resolve_handler
+        self._received_events = 0
+        self._handlers: dict[str, EventHandler] = {}
+        self._handlers_lock = threading.RLock()
+        self._pending: dict[str, Future[Any]] = {}
+        self._pending_lock = threading.Lock()
+        self._dispatch_state = threading.local()
+        self._outgoing: OutgoingStream[pkipc_pb2.Frame] = OutgoingStream()
+
+    def on(self, event: str, handler: EventHandler) -> EventHandler:
+        """Register a handler for an event and return it for decorator use."""
+        validate_event_name(event)
+        if event == RESPONSE_EVENT:
+            raise ValueError(f"{RESPONSE_EVENT} is managed by the runtime")
+        with self._handlers_lock:
+            self._handlers[event] = handler
+        return handler
+
+    def send(self, event: str, data: Any) -> None:
+        """Queue one event without waiting for a response."""
+        self._outgoing.send(encode_frame(event, data))
+
+    def request(self, event: str, data: Any, timeout: float = 10.0) -> Any:
+        """Send a request and block until its correlated response arrives."""
+        if getattr(self._dispatch_state, "active", False):
+            raise RuntimeError("request() cannot be called from an event handler")
+        if timeout <= 0 or not math.isfinite(timeout):
+            raise ValueError("timeout must be a finite positive number")
+
+        deadline = time.monotonic() + timeout
+        future: Future[Any] = Future()
+        with self._pending_lock:
+            request_id = uuid.uuid4().hex
+            while request_id in self._pending:
+                request_id = uuid.uuid4().hex
+            self._pending[request_id] = future
+
+        try:
+            self._outgoing.send(
+                encode_frame(event, data, request_id=request_id),
+                timeout=timeout,
+            )
+        except BaseException:
+            with self._pending_lock:
+                self._pending.pop(request_id, None)
+            raise
+
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            with self._pending_lock:
+                self._pending.pop(request_id, None)
+            raise TimeoutError(f"Request {event!r} timed out after {timeout}s")
+
+        try:
+            return future.result(timeout=remaining)
+        except TimeoutError as exc:
+            with self._pending_lock:
+                self._pending.pop(request_id, None)
+            raise TimeoutError(f"Request {event!r} timed out after {timeout}s") from exc
+
+    def dispatch(self, frame: pkipc_pb2.Frame) -> None:
+        """Validate a frame, resolve responses, or invoke its event handler."""
+        envelope = decode_frame(frame)
+        with self._handlers_lock:
+            if self._received_events == 0 and self._first_event not in (None, envelope.event):
+                raise ValueError(
+                    f"First event must be {self._first_event!r}, got {envelope.event!r}"
+                )
+            if self._received_events > 0 and envelope.event == self._first_event:
+                raise ValueError(f"Event {envelope.event!r} may only be received once")
+            self._received_events += 1
+            handler = self._handlers.get(envelope.event)
+            resolver = self._resolve_handler
+
+        if envelope.reply_to is not None:
+            self._resolve_response(envelope)
+            return
+        if handler is None and resolver is not None:
+            handler = resolver(envelope.event)
+        if envelope.request_id is not None:
+            self._handle_request(envelope, handler)
+        elif handler is not None:
+            self._handle_event(envelope, handler)
+
+    def close(self) -> None:
+        self._outgoing.close()
+        with self._pending_lock:
+            pending = list(self._pending.values())
+            self._pending.clear()
+        for future in pending:
+            future.set_exception(ConnectionError("The PKIPC stream is closed"))
+
+    def is_closed(self) -> bool:
+        return self._outgoing.is_closed()
+
+    def __iter__(self) -> Iterator[pkipc_pb2.Frame]:
+        return iter(self._outgoing)
+
+    def _handle_event(self, envelope: Envelope, handler: EventHandler) -> None:
+        try:
+            self._invoke_handler(handler, envelope.data)
+        except Exception:
+            LOGGER.exception("Handler for event %r raised", envelope.event)
+
+    def _handle_request(
+        self,
+        envelope: Envelope,
+        handler: EventHandler | None,
+    ) -> None:
+        assert envelope.request_id is not None
+        try:
+            if handler is None:
+                raise LookupError(f"No handler registered for event {envelope.event!r}")
+            result = self._invoke_handler(handler, envelope.data)
+            response = encode_frame(
+                RESPONSE_EVENT,
+                result,
+                reply_to=envelope.request_id,
+            )
+        except Exception as exc:
+            response = encode_frame(
+                RESPONSE_EVENT,
+                None,
+                reply_to=envelope.request_id,
+                error=f"{type(exc).__name__}: {exc}",
+            )
+        try:
+            self._outgoing.send(response)
+        except ConnectionError:
+            LOGGER.debug("Could not send response for event %r", envelope.event)
+
+    def _resolve_response(self, envelope: Envelope) -> None:
+        assert envelope.reply_to is not None
+        with self._pending_lock:
+            future = self._pending.pop(envelope.reply_to, None)
+        if future is None:
+            LOGGER.debug("Ignoring response for unknown request %s", envelope.reply_to)
+            return
+        if envelope.error is not None:
+            future.set_exception(RuntimeError(f"Remote handler failed: {envelope.error}"))
+        else:
+            future.set_result(envelope.data)
+
+    def _invoke_handler(self, handler: EventHandler, data: Any) -> Any:
+        previous = getattr(self._dispatch_state, "active", False)
+        self._dispatch_state.active = True
+        try:
+            return handler(data)
+        finally:
+            self._dispatch_state.active = previous
+
+
+def validate_event_name(event: object) -> None:
+    if not isinstance(event, str) or not event.strip():
+        raise ValueError("event must be a non-empty string")
+
+
+def validate_application_event(event: object) -> None:
+    validate_event_name(event)
+    if event in (CONFIG_EVENT, RESPONSE_EVENT):
+        raise ValueError(f"{event} is managed by the runtime")
+
+
+def _validate_id(name: str, value: str | None) -> None:
+    if value is not None and (not isinstance(value, str) or not value):
+        raise ValueError(f"{name} must be a non-empty string")
+
+
+def _validate_envelope(envelope: Envelope) -> None:
+    validate_event_name(envelope.event)
+    _validate_id("id", envelope.request_id)
+    _validate_id("reply_to", envelope.reply_to)
+    if envelope.request_id is not None and envelope.reply_to is not None:
+        raise ValueError("Frame cannot contain both id and reply_to")
+    if envelope.error is not None and (not isinstance(envelope.error, str) or not envelope.error):
+        raise ValueError("error must be a non-empty string")
+
+    if envelope.event == RESPONSE_EVENT:
+        if envelope.reply_to is None:
+            raise ValueError(f"{RESPONSE_EVENT} requires reply_to")
+    elif envelope.reply_to is not None or envelope.error is not None:
+        raise ValueError(f"Only {RESPONSE_EVENT} may contain reply_to or error")
+
+    if envelope.event == CONFIG_EVENT and envelope.request_id is not None:
+        raise ValueError(f"{CONFIG_EVENT} cannot be sent as a request")
+    _validate_reserved_event(envelope.event, envelope.data)
+
+
+def _validate_action(action: object) -> None:
+    if not isinstance(action, str) or not action.strip():
+        raise ValueError("control action must be a non-empty string")
+
+
+def _validate_reserved_event(event: str, data: Any) -> None:
+    if event == CONFIG_EVENT and not isinstance(data, dict):
+        raise ValueError("pkipc.config data must be a JSON object")
+    if event == CONTROL_EVENT:
+        if not isinstance(data, dict):
+            raise ValueError("pkipc.control data must be a JSON object")
+        _validate_action(data.get("action"))
+    if event == LOG_EVENT:
+        if not isinstance(data, dict):
+            raise ValueError("pkipc.log data must be a JSON object")
+        if not isinstance(data.get("level"), str) or not data["level"]:
+            raise ValueError("pkipc.log level must be a non-empty string")
+        if not isinstance(data.get("message"), str):
+            raise ValueError("pkipc.log message must be a string")
+
+
+def _raise_invalid_constant(value: str) -> Any:
+    raise ValueError(f"Invalid JSON number constant: {value}")

pkipc/_stream.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+from collections.abc import Iterator
+from typing import Generic, TypeVar
+
+from ._grpc_common import OUTGOING_QUEUE_SIZE
+
+T = TypeVar("T")
+
+
+class OutgoingStream(Generic[T]):
+    """Thread-safe bounded iterator used as a gRPC request stream."""
+
+    def __init__(self) -> None:
+        self._items: deque[T] = deque()
+        self._closed = False
+        self._changed = threading.Condition()
+
+    def send(self, item: T, timeout: float = 5.0) -> None:
+        deadline = time.monotonic() + max(0.0, timeout)
+        with self._changed:
+            while len(self._items) >= OUTGOING_QUEUE_SIZE and not self._closed:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise ConnectionError("The gRPC stream send queue is full")
+                self._changed.wait(remaining)
+            if self._closed:
+                raise ConnectionError("The gRPC stream is closed")
+            self._items.append(item)
+            self._changed.notify()
+
+    def close(self) -> None:
+        with self._changed:
+            self._closed = True
+            self._changed.notify_all()
+
+    def __iter__(self) -> Iterator[T]:
+        while True:
+            with self._changed:
+                while not self._items and not self._closed:
+                    self._changed.wait()
+                if not self._items:
+                    return
+                item = self._items.popleft()
+                self._changed.notify()
+            yield item
+
+    def is_closed(self) -> bool:
+        with self._changed:
+            return self._closed

pkipc/client.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+import subprocess
+import threading
+import time
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, NoReturn
+
+from ._grpc_common import ENDPOINT_ENV, TOKEN_ENV
+from ._grpc_host import GrpcHost
+from ._runtime import validate_application_event
+
+LOGGER = logging.getLogger(__name__)
+EventCallback = Callable[[Any], Any]
+CloseCallback = Callable[[], None]
+
+
+class Client:
+    """Start one worker process and own its private gRPC endpoint."""
+
+    def __init__(
+        self,
+        executable: str,
+        *,
+        config: Mapping[str, Any] | None = None,
+        args: Sequence[str] = (),
+        working_directory: str | None = None,
+        environment: Mapping[str, str] | None = None,
+        start_timeout: float = 5.0,
+        stop_timeout: float = 2.0,
+    ) -> None:
+        if not executable:
+            raise ValueError("executable must not be empty")
+        self._executable = executable
+        self._config = dict(config or {})
+        self._args = tuple(args)
+        self._working_directory = working_directory
+        self._environment = dict(environment or {})
+        self._start_timeout = max(0.1, start_timeout)
+        self._stop_timeout = max(0.1, stop_timeout)
+        self._callbacks: dict[str, EventCallback] = {}
+        self._close_callback: CloseCallback | None = None
+        self._host: GrpcHost | None = None
+        self._process: subprocess.Popen[bytes] | None = None
+        self._lock = threading.RLock()
+        self._started = False
+        self._start_attempted = False
+        self._closing = False
+
+    def on(self, event: str) -> Callable[[EventCallback], EventCallback]:
+        """Register the handler for one named application event."""
+        validate_application_event(event)
+
+        def decorator(callback: EventCallback) -> EventCallback:
+            with self._lock:
+                self._callbacks[event] = callback
+            return callback
+
+        return decorator
+
+    def on_close(self, callback: CloseCallback) -> CloseCallback:
+        """Register the callback for an unexpected stream close."""
+        with self._lock:
+            self._close_callback = callback
+        return callback
+
+    def start(self) -> Client:
+        """Start the process and wait until it opens the gRPC stream."""
+        with self._lock:
+            if self._start_attempted or self._closing:
+                raise RuntimeError("Client instances cannot be started more than once")
+            self._start_attempted = True
+
+        token = secrets.token_urlsafe(32)
+        host = GrpcHost(
+            token=token,
+            config=self._config,
+            resolve_handler=self._resolve_handler,
+            on_close=self._handle_close,
+        )
+        endpoint = host.start()
+        child_environment = os.environ.copy()
+        child_environment.update(self._environment)
+        child_environment[ENDPOINT_ENV] = endpoint
+        child_environment[TOKEN_ENV] = token
+
+        try:
+            process = self._spawn_worker(child_environment)
+        except OSError as exc:
+            host.stop()
+            with self._lock:
+                self._closing = True
+            raise OSError(f"Failed to start worker process: {self._executable}") from exc
+
+        with self._lock:
+            self._host = host
+            self._process = process
+
+        deadline = time.monotonic() + self._start_timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                self._fail_start(
+                    TimeoutError(f"Worker did not attach within {self._start_timeout:.1f}s")
+                )
+            if host.wait_for_attach(min(0.05, remaining)):
+                break
+            exit_code = process.poll()
+            if exit_code is not None:
+                self._fail_start(
+                    ChildProcessError(f"Worker exited before attaching, exit code={exit_code}")
+                )
+
+        with self._lock:
+            self._started = True
+        return self
+
+    def send(self, event: str, data: Any = None) -> None:
+        """Send one named application event to the worker."""
+        validate_application_event(event)
+        with self._lock:
+            host = self._host
+            if not self._started or self._closing or host is None:
+                raise ConnectionError("Client is not connected")
+        host.send(event, data)
+
+    def request(self, event: str, data: Any = None, timeout: float = 10.0) -> Any:
+        """Send a request and block until the worker returns a response."""
+        validate_application_event(event)
+        with self._lock:
+            host = self._host
+            if not self._started or self._closing or host is None:
+                raise ConnectionError("Client is not connected")
+        return host.request(event, data, timeout)
+
+    def close(self) -> None:
+        """Close the stream, then terminate a worker that ignores it."""
+        with self._lock:
+            if self._closing:
+                return
+            self._closing = True
+            host = self._host
+            process = self._process
+
+        if host is not None:
+            host.close_stream()
+        if process is not None and not self._wait_for_process(process, self._stop_timeout):
+            self._terminate_process(process)
+        if host is not None:
+            host.wait_for_close(0.5)
+            host.stop()
+
+        with self._lock:
+            self._started = False
+
+    def wait(self, timeout: float | None = None) -> int | None:
+        """Wait for the worker and return its exit code, or None on timeout."""
+        process = self._process
+        if process is None:
+            raise RuntimeError("Client has not been started")
+        try:
+            exit_code = process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            return None
+        if self._host is not None:
+            self._host.wait_for_close(1.0)
+            self._host.stop()
+        return exit_code
+
+    def is_connected(self) -> bool:
+        """Return whether the worker stream is open."""
+        host = self._host
+        return self._started and not self._closing and host is not None and host.is_connected()
+
+    def is_running(self) -> bool:
+        """Return whether the worker process is alive."""
+        return self._process is not None and self._process.poll() is None
+
+    @property
+    def pid(self) -> int:
+        """Return the worker PID, or zero before start."""
+        return self._process.pid if self._process is not None else 0
+
+    @property
+    def exit_code(self) -> int:
+        """Return the worker exit code, or -1 while it is running."""
+        if self._process is None:
+            return -1
+        exit_code = self._process.poll()
+        return -1 if exit_code is None else exit_code
+
+    def _spawn_worker(self, environment: Mapping[str, str]) -> subprocess.Popen[bytes]:
+        creationflags = 0
+        if os.name == "nt" and hasattr(subprocess, "CREATE_NO_WINDOW"):
+            creationflags = subprocess.CREATE_NO_WINDOW
+        process = subprocess.Popen(
+            [self._executable, *self._args],
+            stdin=subprocess.DEVNULL,
+            cwd=self._working_directory or None,
+            env=environment,
+            creationflags=creationflags,
+        )
+        LOGGER.info("Started worker process %s", process.pid)
+        return process
+
+    def _fail_start(self, error: Exception) -> NoReturn:
+        host = self._host
+        process = self._process
+        if host is not None:
+            host.close_stream()
+        if process is not None:
+            self._terminate_process(process)
+        if host is not None:
+            host.stop()
+        with self._lock:
+            self._closing = True
+        raise error
+
+    def _terminate_process(self, process: subprocess.Popen[bytes]) -> None:
+        if process.poll() is not None:
+            return
+        LOGGER.warning("Terminating worker process %s", process.pid)
+        process.terminate()
+        if self._wait_for_process(process, self._stop_timeout):
+            return
+        process.kill()
+        process.wait(timeout=2.0)
+
+    @staticmethod
+    def _wait_for_process(
+        process: subprocess.Popen[bytes],
+        timeout: float,
+    ) -> bool:
+        try:
+            process.wait(timeout=max(0.1, timeout))
+        except subprocess.TimeoutExpired:
+            return False
+        return True
+
+    def _resolve_handler(self, event: str) -> EventCallback | None:
+        with self._lock:
+            return self._callbacks.get(event)
+
+    def _handle_close(self) -> None:
+        with self._lock:
+            if self._closing:
+                return
+            callback = self._close_callback
+        if callback is not None:
+            callback()

pkipc/proto/__init__.py

@@ -0,0 +1 @@
+"""Generated protobuf contract for PKIPC."""

pkipc/proto/pkipc.proto

@@ -0,0 +1,11 @@
+syntax = "proto3";
+
+package pkipc.runtime.v2;
+
+service Runtime {
+  rpc Run(stream Frame) returns (stream Frame);
+}
+
+message Frame {
+  bytes payload = 1;
+}

pkipc/proto/pkipc_pb2.py

@@ -0,0 +1,38 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: pkipc/proto/pkipc.proto
+# Protobuf Python Version: 6.33.5
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    33,
+    5,
+    '',
+    'pkipc/proto/pkipc.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x17pkipc/proto/pkipc.proto\x12\x10pkipc.runtime.v2\"\x18\n\x05\x46rame\x12\x0f\n\x07payload\x18\x01 \x01(\x0c\x32\x46\n\x07Runtime\x12;\n\x03Run\x12\x17.pkipc.runtime.v2.Frame\x1a\x17.pkipc.runtime.v2.Frame(\x01\x30\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'pkipc.proto.pkipc_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_FRAME']._serialized_start=45
+  _globals['_FRAME']._serialized_end=69
+  _globals['_RUNTIME']._serialized_start=71
+  _globals['_RUNTIME']._serialized_end=141
+# @@protoc_insertion_point(module_scope)

pkipc/proto/pkipc_pb2.pyi

@@ -0,0 +1,11 @@
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Optional as _Optional
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class Frame(_message.Message):
+    __slots__ = ("payload",)
+    PAYLOAD_FIELD_NUMBER: _ClassVar[int]
+    payload: bytes
+    def __init__(self, payload: _Optional[bytes] = ...) -> None: ...

pkipc/proto/pkipc_pb2_grpc.py

@@ -0,0 +1,97 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from pkipc.proto import pkipc_pb2 as pkipc_dot_proto_dot_pkipc__pb2
+
+GRPC_GENERATED_VERSION = '1.81.1'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in pkipc/proto/pkipc_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class RuntimeStub:
+    """Missing associated documentation comment in .proto file."""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Run = channel.stream_stream(
+                '/pkipc.runtime.v2.Runtime/Run',
+                request_serializer=pkipc_dot_proto_dot_pkipc__pb2.Frame.SerializeToString,
+                response_deserializer=pkipc_dot_proto_dot_pkipc__pb2.Frame.FromString,
+                _registered_method=True)
+
+
+class RuntimeServicer:
+    """Missing associated documentation comment in .proto file."""
+
+    def Run(self, request_iterator, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_RuntimeServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Run': grpc.stream_stream_rpc_method_handler(
+                    servicer.Run,
+                    request_deserializer=pkipc_dot_proto_dot_pkipc__pb2.Frame.FromString,
+                    response_serializer=pkipc_dot_proto_dot_pkipc__pb2.Frame.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'pkipc.runtime.v2.Runtime', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('pkipc.runtime.v2.Runtime', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class Runtime:
+    """Missing associated documentation comment in .proto file."""
+
+    @staticmethod
+    def Run(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(
+            request_iterator,
+            target,
+            '/pkipc.runtime.v2.Runtime/Run',
+            pkipc_dot_proto_dot_pkipc__pb2.Frame.SerializeToString,
+            pkipc_dot_proto_dot_pkipc__pb2.Frame.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

pkipc/server.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import logging
+import os
+import threading
+from collections.abc import Callable
+from typing import Any
+
+import grpc
+
+from ._grpc_common import (
+    ENDPOINT_ENV,
+    GRPC_OPTIONS,
+    TOKEN_ENV,
+    TOKEN_METADATA_KEY,
+)
+from ._runtime import CONFIG_EVENT, Runtime, validate_application_event
+from .proto import pkipc_pb2_grpc
+
+LOGGER = logging.getLogger(__name__)
+EventCallback = Callable[[Any], Any]
+
+
+class Server:
+    """Worker-side API backed by one long-lived gRPC stream."""
+
+    def __init__(self) -> None:
+        self._runtime = Runtime(first_event=CONFIG_EVENT)
+        self._runtime.on(CONFIG_EVENT, self._receive_config)
+        self._channel: grpc.Channel | None = None
+        self._call: grpc.Call | None = None
+        self._receiver: threading.Thread | None = None
+        self._config_ready = threading.Event()
+        self._stop_requested = threading.Event()
+        self._connected = threading.Event()
+        self._config: dict[str, Any] | None = None
+        self._start_error: Exception | None = None
+
+    def on(self, event: str) -> Callable[[EventCallback], EventCallback]:
+        """Register the handler for one named application event."""
+        validate_application_event(event)
+
+        def decorator(callback: EventCallback) -> EventCallback:
+            return self._runtime.on(event, callback)
+
+        return decorator
+
+    def start(self, timeout: float = 10.0) -> dict[str, Any]:
+        """Connect to the parent and return its startup configuration."""
+        if self._channel is not None:
+            raise RuntimeError("Server instances cannot be started more than once")
+
+        endpoint = os.environ.get(ENDPOINT_ENV, "")
+        token = os.environ.get(TOKEN_ENV, "")
+        if not endpoint or not token:
+            raise RuntimeError(f"{ENDPOINT_ENV} and {TOKEN_ENV} must be provided by PKIPC Client")
+
+        channel = grpc.insecure_channel(endpoint, options=GRPC_OPTIONS)
+        self._channel = channel
+        self._call = pkipc_pb2_grpc.RuntimeStub(channel).Run(
+            iter(self._runtime),
+            metadata=((TOKEN_METADATA_KEY, token),),
+        )
+        self._receiver = threading.Thread(
+            target=self._receive_frames,
+            name="pkipc-worker-reader",
+            daemon=True,
+        )
+        self._receiver.start()
+
+        if not self._config_ready.wait(timeout=max(0.0, timeout)):
+            self.close()
+            raise TimeoutError(f"Timed out waiting for startup configuration after {timeout}s")
+        if self._start_error is not None:
+            error = self._start_error
+            self.close()
+            raise error
+        if self._config is None:
+            self.close()
+            raise ConnectionError("Host closed before sending startup configuration")
+        return dict(self._config)
+
+    def send(self, event: str, data: Any = None) -> None:
+        """Send one named application event to the parent."""
+        validate_application_event(event)
+        self._require_connected()
+        self._runtime.send(event, data)
+
+    def request(self, event: str, data: Any = None, timeout: float = 10.0) -> Any:
+        """Send a request and block until the parent returns a response."""
+        validate_application_event(event)
+        self._require_connected()
+        return self._runtime.request(event, data, timeout)
+
+    def close(self, grace: float = 2.0) -> None:
+        """Finish pending sends and release the gRPC channel."""
+        self._runtime.close()
+        receiver = self._receiver
+        if receiver is not None and receiver is not threading.current_thread():
+            receiver.join(timeout=max(0.0, grace))
+            if receiver.is_alive() and self._call is not None:
+                self._call.cancel()
+                receiver.join(timeout=1.0)
+        if self._channel is not None:
+            self._channel.close()
+        self._connected.clear()
+        self._stop_requested.set()
+
+    def stop_requested(self) -> bool:
+        """Return whether the parent closed the stream."""
+        return self._stop_requested.is_set()
+
+    def is_connected(self) -> bool:
+        """Return whether the gRPC stream is accepting messages."""
+        return self._connected.is_set() and not self._stop_requested.is_set()
+
+    def _receive_frames(self) -> None:
+        try:
+            assert self._call is not None
+            for frame in self._call:
+                self._runtime.dispatch(frame)
+        except grpc.RpcError as exc:
+            if self._config is None:
+                self._start_error = ConnectionError(
+                    f"gRPC connection failed: {exc.code().name}: {exc.details()}"
+                )
+        except ValueError as exc:
+            if self._config is None:
+                self._start_error = exc
+            else:
+                LOGGER.error("Closing invalid PKIPC stream: %s", exc)
+            if self._call is not None:
+                self._call.cancel()
+        finally:
+            if self._config is None and self._start_error is None:
+                self._start_error = ConnectionError(
+                    "Host closed before sending startup configuration"
+                )
+            self._config_ready.set()
+            self._connected.clear()
+            self._stop_requested.set()
+            self._runtime.close()
+
+    def _receive_config(self, config: Any) -> None:
+        self._config = dict(config)
+        self._connected.set()
+        self._config_ready.set()
+
+    def _require_connected(self) -> None:
+        if not self.is_connected():
+            raise ConnectionError("Server is not connected")

pkipc-2.0.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: PKIPC
+Version: 2.0.0
+Summary: Event runtime over gRPC for parent-child process communication
+Author: PKIPC
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: grpcio<2,>=1.81.1
+Requires-Dist: protobuf<7,>=6.33.5
+Provides-Extra: test
+Requires-Dist: pytest>=8.2; extra == "test"
+Requires-Dist: ruff>=0.12; extra == "test"
+Provides-Extra: build
+Requires-Dist: grpcio-tools<2,>=1.81.1; extra == "build"
+Requires-Dist: pyinstaller>=6.0; extra == "build"
+
+# pyPKIPC
+
+`pyPKIPC 2` 是用于父子进程通信的轻量事件运行时。父进程负责启动子进程，双方通过一条长期 gRPC 双向流收发任意 JSON 事件。
+
+运行时不使用 `stdin/stdout` 传输，不定义应用层握手，也没有旧协议兼容代码。
+
+## 安装
+
+```powershell
+python -m pip install PKIPC
+```
+
+本地开发和打包依赖：
+
+```powershell
+python -m pip install -e .[test,build]
+```
+
+## 子进程：Server
+
+```python
+import threading
+
+from pkipc import Server
+
+server = Server()
+stopped = threading.Event()
+
+
+@server.on("solver.add")
+def add(data):
+    return {"result": data["a"] + data["b"]}
+
+
+@server.on("worker.stop")
+def stop(_data):
+    stopped.set()
+
+
+config = server.start()
+server.send(
+    "pkipc.log",
+    {
+        "level": "INFO",
+        "message": f"worker started with {config}",
+    },
+)
+while not stopped.wait(0.1) and not server.stop_requested():
+    pass
+server.close()
+```
+
+`start()` 建立 gRPC 流并返回父进程下发的配置。事件回调在单一接收线程中按顺序执行。
+
+## 父进程：Client
+
+```python
+import sys
+
+from pkipc import Client
+
+client = Client(
+    sys.executable,
+    args=("worker.py",),
+    config={"value": 42},
+)
+
+
+@client.on("pkipc.log")
+def log_received(data):
+    print(data["level"], data["message"])
+
+
+client.start()
+result = client.request(
+    "solver.add",
+    {
+        "a": 10,
+        "b": 20,
+    },
+    timeout=5.0,
+)
+print(result)
+client.send("worker.stop")
+client.wait()
+client.close()
+```
+
+父子两端使用完全相同的 `send(event, data)`、`request(event, data, timeout)` 和 `on(event)`。`send()` 是不等待结果的单向事件；`request()` 阻塞等待对应 handler 的返回值，请求 ID 和响应匹配完全由 Runtime 管理。框架不提供 `send_data`、`send_log`、`on_data` 或 `on_log`；业务层可以按需用普通函数做薄封装。
+
+`request()` 不能在 `@on` handler 内调用，因为 handler 运行在单一接收线程中；Runtime 会直接抛出 `RuntimeError`，避免嵌套同步请求死锁。请求超时抛出 `TimeoutError`，断连时所有等待中的请求抛出 `ConnectionError`，远端 handler 异常则在调用端表现为 `RuntimeError`。
+
+框架不定义自有异常类型：无效事件抛出 `ValueError`，断连抛出 `ConnectionError`，启动等待超时抛出 `TimeoutError`，子进程提前退出抛出 `ChildProcessError`，重复启动等生命周期错误抛出 `RuntimeError`。
+
+## 运行模型
+
+1. 父进程在 `127.0.0.1:0` 启动专属 gRPC Server。
+2. 父进程生成随机 token，通过环境变量把 endpoint 和 token 传给子进程。
+3. 子进程建立 `Runtime.Run` 双向流。
+4. 父进程发送的第一帧固定为 `pkipc.config`，由 `Server.start()` 消费。
+5. 配置完成后，父子进程通过同样的 Frame 双向收发任意命名事件。
+6. 流结束即表示停止，错误由 gRPC status 表达。
+
+传输层只有一个无类型消息和一个 RPC：
+
+```protobuf
+service Runtime {
+  rpc Run(stream Frame) returns (stream Frame);
+}
+
+message Frame {
+  bytes payload = 1;
+}
+```
+
+`Frame.payload` 是 UTF-8 JSON，统一由 Runtime 层编码、校验和分发：
+
+```json
+{"event":"pkipc.config","data":{"threads":8}}
+{"event":"pkipc.control","data":{"action":"PAUSE"}}
+{"event":"pkipc.data","data":{"progress":0.5}}
+{"event":"pkipc.log","data":{"level":"INFO","message":"solver started"}}
+```
+
+同步请求增加 `id`，响应使用内部事件 `pkipc.response` 和 `reply_to`：
+
+```json
+{"event":"solver.add","data":{"a":10,"b":20},"id":"request-id"}
+{"event":"pkipc.response","data":{"result":30},"reply_to":"request-id"}
+```
+
+`event` 必须是非空字符串，`data` 必须存在且可以是任意合法 JSON。`id`、`reply_to` 和错误响应由 Runtime 独占管理。`pkipc.config` 由启动流程管理；`pkipc.control`、`pkipc.data` 和 `pkipc.log` 是经过校验的标准事件约定，但不绑定专用 Python API。自定义事件名会原样传输，不需要修改或重新生成 Protobuf。
+
+协议定义在：
+
+- `pkipc/proto/pkipc.proto`
+
+Python 生成代码和 `.proto` 一起发布。C++ 实现只需要从同一份 `.proto` 生成传输 stub，并在 Runtime dispatcher 中实现相同的 JSON 信封约定。
+
+## 完整示例
+
+- `examples/01_request_response/`：同步请求响应，实现计算器
+- `examples/02_commands/`：单向命令，实现暂停、恢复和停止
+- `examples/03_progress/`：长任务持续推送进度，最后返回结果
+- `examples/04_reverse_request/`：Server 反向请求 Client
+- `examples/05_errors/`：请求超时、连接断开和远端 handler 异常
+
+每个目录包含一组 `client.py` 和 `server.py`。只运行 `client.py`，Client 会负责启动
+Server 子进程：
+
+```powershell
+python examples/01_request_response/client.py
+python examples/02_commands/client.py
+python examples/03_progress/client.py
+python examples/04_reverse_request/client.py
+python examples/05_errors/client.py
+```
+
+完整说明见 `examples/README.md`。
+
+## 测试
+
+```powershell
+python -m pytest -q
+```
+
+测试覆盖单一 Frame 协议、信封校验、双向通用事件分发、五组完整示例、启动失败、
+stdout 独立性、主动关闭和子进程异常退出。

pkipc-2.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+pkipc/__init__.py,sha256=wQjxYPHEEt3v1XaHeX5kAF0OXMtY4J979jnEPZdijW0,175
+pkipc/_grpc_common.py,sha256=JYc4MRWUX-wExgqIqdhUD3cNR4iHFb9jS37H7Qjqmt8,360
+pkipc/_grpc_host.py,sha256=OqUrESpHcnXGqZw7zAatJVP98yOLV30NdVj7WGJ5EYw,5049
+pkipc/_runtime.py,sha256=m-c7Z_ODaEnYIvWyEU07WyYOmgr7A2xulaeCRz13INU,11668
+pkipc/_stream.py,sha256=MiuQbVwfGN-VvVvNO_J7qmk9865EQ3rihUMJpo9BoSE,1682
+pkipc/client.py,sha256=bljEPFYa--Mf1cU9Bop6t-fNM0nTF1I03WahWrFJLIg,8862
+pkipc/server.py,sha256=yiti62w3CTE_9_o2VEOnF0PUm6r3BMMeNEcWWIMIvhM,5627
+pkipc/proto/__init__.py,sha256=h9xWjvc7Er9ibz4C_Y-4_jH6FJHQAsP55JnoG3yKotY,45
+pkipc/proto/pkipc.proto,sha256=rqEkiUZ9IRIqa2ClPHJLrt6X6h7QTeGgLVXPdLOsk40,155
+pkipc/proto/pkipc_pb2.py,sha256=5KLWJWmzwjFWbpPLALDp8vPvtuNgNeC84-S2186yB4g,1505
+pkipc/proto/pkipc_pb2.pyi,sha256=RMdUUuzXGqYbgC468lMN8bweDK7A3FdOym6PjpZ-cuc,396
+pkipc/proto/pkipc_pb2_grpc.py,sha256=n7I0Ro_whSumoqbEQYyG-_DeVMBMv5e48Tygaea2g5c,3469
+pkipc-2.0.0.dist-info/METADATA,sha256=73DsjSR32imvJukUnzPLSYrNA9JFgT1yKUQSOWEeazI,5945
+pkipc-2.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pkipc-2.0.0.dist-info/top_level.txt,sha256=nqx0Nalxl2qZh7N1s3uK5-LC6LK-qxQB9nys7UOMms8,6
+pkipc-2.0.0.dist-info/RECORD,,

pkipc-2.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pkipc-2.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pkipc