python-plugin 0.1.0__py3-none-any.whl

pyplugin/logging_bridge.py

@@ -0,0 +1,70 @@
+"""Parse hclog log lines into structured ``logging.LogRecord`` calls.
+
+go-plugin pipes plugin stderr through go-hclog. hclog has two output modes:
+
+* JSON: ``{"@level":"info","@message":"...","@module":"foo","@timestamp":"...",...}``
+* Pretty: ``2025-01-01T12:00:00.000Z [INFO]  module: msg: key=value key2="quoted"``
+
+We try JSON first (cheap discriminator: starts with ``{``) and fall back to
+the pretty regex. Anything we can't parse is logged at INFO with the raw
+text. We always emit on the caller's logger so they can hook formatters.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+_LEVELS = {
+    "trace": logging.DEBUG,  # logging has no TRACE; map to DEBUG
+    "debug": logging.DEBUG,
+    "info":  logging.INFO,
+    "warn":  logging.WARNING,
+    "warning": logging.WARNING,
+    "error": logging.ERROR,
+    "fatal": logging.CRITICAL,
+    "critical": logging.CRITICAL,
+}
+
+# Pretty format: optional timestamp, then [LEVEL]  module: message ...
+_PRETTY = re.compile(
+    r"^(?P<ts>\S+)?\s*\[(?P<level>\w+)\]\s*(?P<module>[^:]+):\s*(?P<rest>.*)$"
+)
+
+
+def emit(logger: logging.Logger, raw: str) -> None:
+    """Parse ``raw`` and emit on ``logger`` at the matching level."""
+    raw = raw.rstrip("\r\n")
+    if not raw:
+        return
+
+    if raw.lstrip().startswith("{"):
+        rec = _parse_json(raw)
+        if rec is not None:
+            level, msg, module, extra = rec
+            logger.log(level, msg, extra={"plugin": module, "fields": extra})
+            return
+
+    m = _PRETTY.match(raw)
+    if m is not None:
+        level = _LEVELS.get(m["level"].lower(), logging.INFO)
+        module = m["module"].strip()
+        logger.log(level, m["rest"].strip(), extra={"plugin": module})
+        return
+
+    logger.info(raw)
+
+
+def _parse_json(raw: str) -> tuple[int, str, str, dict[str, Any]] | None:
+    try:
+        obj = json.loads(raw)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(obj, dict):
+        return None
+    level = _LEVELS.get(str(obj.pop("@level", "info")).lower(), logging.INFO)
+    msg = str(obj.pop("@message", ""))
+    module = str(obj.pop("@module", ""))
+    obj.pop("@timestamp", None)
+    return level, msg, module, obj

pyplugin/mtls.py

@@ -0,0 +1,169 @@
+"""AutoMTLS — ephemeral certificate generation matching go-plugin/mtls.go EXACTLY.
+
+go-plugin uses ECDSA P-521 + SHA-512. Python's ``ssl`` module (OpenSSL,
+which grpclib runs on) supports this natively, so we can match
+go-plugin's cert template byte-for-byte:
+
+* Curve: ECDSA P-521 (SECP521R1)
+* Signature: ECDSA-SHA-512
+* CN/SAN: ``localhost``
+* O: ``HashiCorp``
+* IsCA: true, BasicConstraints critical
+* KeyUsage: digital signature | key encipherment | key agreement | cert sign
+* ExtKeyUsage: clientAuth + serverAuth
+* Validity: NotBefore -30s, NotAfter +262980h (~30 years)
+
+The host's leaf cert is sent to the plugin via ``PLUGIN_CLIENT_CERT`` (PEM);
+the plugin's leaf is returned as base64.RawStdEncoding(DER) in handshake
+field 6.
+
+Both sides pin the peer's leaf cert as the trust root and use
+``RequireAndVerifyClientCert`` semantics.
+"""
+from __future__ import annotations
+
+import base64
+import datetime
+import secrets
+import ssl
+from dataclasses import dataclass
+
+from cryptography import x509
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.x509.oid import NameOID
+
+_NOT_BEFORE_SKEW = datetime.timedelta(seconds=30)
+_VALIDITY = datetime.timedelta(hours=262980)
+_HOST = "localhost"
+
+
+@dataclass(frozen=True)
+class Cert:
+    """A self-signed leaf usable as both the cert and its own CA (matches go-plugin)."""
+    cert_pem: bytes
+    key_pem: bytes
+    cert_der: bytes
+
+
+def generate() -> Cert:
+    """Generate one ephemeral cert+key pair, byte-compatible with go-plugin's ``generateCert``."""
+    key = ec.generate_private_key(ec.SECP521R1())
+
+    # Match Go's serial: random in [0, 2^128).
+    serial = int.from_bytes(secrets.token_bytes(16), "big")
+
+    now = datetime.datetime.now(datetime.timezone.utc)
+    subject = issuer = x509.Name([
+        x509.NameAttribute(NameOID.COMMON_NAME, _HOST),
+        x509.NameAttribute(NameOID.ORGANIZATION_NAME, "HashiCorp"),
+    ])
+
+    builder = (
+        x509.CertificateBuilder()
+        .subject_name(subject)
+        .issuer_name(issuer)
+        .public_key(key.public_key())
+        .serial_number(serial)
+        .not_valid_before(now - _NOT_BEFORE_SKEW)
+        .not_valid_after(now + _VALIDITY)
+        .add_extension(x509.SubjectAlternativeName([x509.DNSName(_HOST)]), critical=False)
+        .add_extension(x509.BasicConstraints(ca=True, path_length=None), critical=True)
+        .add_extension(
+            x509.KeyUsage(
+                digital_signature=True,
+                content_commitment=False,
+                key_encipherment=True,
+                data_encipherment=False,
+                key_agreement=True,
+                key_cert_sign=True,
+                crl_sign=False,
+                encipher_only=False,
+                decipher_only=False,
+            ),
+            critical=False,
+        )
+        .add_extension(
+            x509.ExtendedKeyUsage([
+                x509.ExtendedKeyUsageOID.CLIENT_AUTH,
+                x509.ExtendedKeyUsageOID.SERVER_AUTH,
+            ]),
+            critical=False,
+        )
+    )
+
+    cert = builder.sign(private_key=key, algorithm=hashes.SHA512())
+    cert_der = cert.public_bytes(serialization.Encoding.DER)
+    cert_pem = cert.public_bytes(serialization.Encoding.PEM)
+    key_pem = key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.TraditionalOpenSSL,  # "EC PRIVATE KEY"
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    return Cert(cert_pem=cert_pem, key_pem=key_pem, cert_der=cert_der)
+
+
+def encode_handshake_cert(cert_der: bytes) -> str:
+    """Encode a leaf cert DER for handshake field 6: base64.RawStdEncoding (no padding)."""
+    return base64.b64encode(cert_der).rstrip(b"=").decode("ascii")
+
+
+def decode_handshake_cert(b64: str) -> bytes:
+    """Inverse of :func:`encode_handshake_cert` — returns raw DER bytes."""
+    pad = "=" * (-len(b64) % 4)
+    return base64.b64decode(b64 + pad)
+
+
+def der_to_pem(cert_der: bytes) -> bytes:
+    """Wrap a raw DER cert in a single PEM CERTIFICATE block."""
+    cert = x509.load_der_x509_certificate(cert_der)
+    return cert.public_bytes(serialization.Encoding.PEM)
+
+
+def server_ssl_context(*, cert_pem: bytes, key_pem: bytes, peer_cert_pem: bytes) -> ssl.SSLContext:
+    """Build a server-side ``SSLContext`` mirroring go-plugin's tls.Config:
+
+    ``Certificates``, ``RequireAndVerifyClientCert``, ``ClientCAs=peer``,
+    ``RootCAs=peer``, ``MinVersion=TLS1.2``, ``ServerName=localhost``.
+    Uses ALPN ``h2`` for HTTP/2.
+    """
+    import tempfile
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    ctx.set_alpn_protocols(["h2"])
+    # SSLContext.load_* take file paths only — write to temp files.
+    with tempfile.NamedTemporaryFile(delete=False, suffix=".pem") as cf, \
+         tempfile.NamedTemporaryFile(delete=False, suffix=".pem") as kf, \
+         tempfile.NamedTemporaryFile(delete=False, suffix=".pem") as rf:
+        cf.write(cert_pem); cf.flush()
+        kf.write(key_pem); kf.flush()
+        rf.write(peer_cert_pem); rf.flush()
+        ctx.load_cert_chain(certfile=cf.name, keyfile=kf.name)
+        ctx.load_verify_locations(cafile=rf.name)
+    return ctx
+
+
+def client_ssl_context(*, cert_pem: bytes, key_pem: bytes, peer_cert_pem: bytes) -> ssl.SSLContext:
+    """Build a client-side ``SSLContext`` for AutoMTLS.
+
+    Trust root is the peer's cert; we present our own cert+key as client cert.
+    Hostname verification is **disabled** because (a) we're connecting over
+    unix sockets where there's no real hostname, and (b) we've already pinned
+    the exact peer cert, so hostname check would be redundant anyway.
+    """
+    import tempfile
+    ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    ctx.minimum_version = ssl.TLSVersion.TLSv1_2
+    ctx.check_hostname = False
+    ctx.verify_mode = ssl.CERT_REQUIRED
+    ctx.set_alpn_protocols(["h2"])
+    with tempfile.NamedTemporaryFile(delete=False, suffix=".pem") as cf, \
+         tempfile.NamedTemporaryFile(delete=False, suffix=".pem") as kf, \
+         tempfile.NamedTemporaryFile(delete=False, suffix=".pem") as rf:
+        cf.write(cert_pem); cf.flush()
+        kf.write(key_pem); kf.flush()
+        rf.write(peer_cert_pem); rf.flush()
+        ctx.load_cert_chain(certfile=cf.name, keyfile=kf.name)
+        ctx.load_verify_locations(cafile=rf.name)
+    return ctx

pyplugin/plugin.py

@@ -0,0 +1,38 @@
+"""Plugin ABC and type aliases (grpclib version).
+
+A pyplugin author implements one ``Plugin`` subclass per service exposed.
+``servicers`` returns the grpclib ``Base`` instances to register on the
+plugin-side server; ``stub`` builds a typed client stub on the host side
+from an open ``grpclib.client.Channel``.
+
+Mirrors go-plugin's ``GRPCPlugin`` interface — both methods receive the
+``GRPCBroker`` so plugins can request callbacks back into the host.
+"""
+from __future__ import annotations
+
+import abc
+from typing import Any, Mapping, TYPE_CHECKING
+
+from grpclib.client import Channel
+
+if TYPE_CHECKING:
+    from .broker import GRPCBroker
+
+
+class Plugin(abc.ABC):
+    """Abstract base for a plugin type."""
+
+    @abc.abstractmethod
+    def servicers(self, broker: "GRPCBroker") -> list:
+        """Return grpclib servicer instances to register on the plugin server.
+
+        Called once on the plugin side during ``serve()`` setup.
+        """
+
+    @abc.abstractmethod
+    def stub(self, broker: "GRPCBroker", channel: Channel) -> Any:
+        """Build a typed grpclib client stub from an open channel (host side)."""
+
+
+PluginSet = Mapping[str, Plugin]
+VersionedPlugins = Mapping[int, PluginSet]

pyplugin/process.py

@@ -0,0 +1,66 @@
+"""Subprocess + cross-platform termination helpers.
+
+go-plugin escalates Kill() through: client.Close() (calls
+``GRPCController.Shutdown``) → wait 2s for graceful exit → SIGKILL via the
+runner. We use the same shape, but split into discrete steps the client
+can sequence.
+"""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+from typing import Mapping, Sequence
+
+
+def is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
+def spawn(
+    cmd: Sequence[str],
+    *,
+    env: Mapping[str, str],
+    cwd: str | None = None,
+) -> subprocess.Popen[bytes]:
+    """Spawn a plugin subprocess. stdin → DEVNULL, stdout/stderr → pipes."""
+    creationflags = 0
+    start_new_session = False
+    if is_windows():
+        creationflags = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+    else:
+        start_new_session = True  # so SIGKILL won't take down the host
+
+    return subprocess.Popen(
+        list(cmd),
+        env=dict(env),
+        cwd=cwd,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        bufsize=0,
+        close_fds=True,
+        creationflags=creationflags,
+        start_new_session=start_new_session,
+    )
+
+
+def terminate(p: subprocess.Popen) -> None:
+    """SIGTERM (or CTRL_BREAK on Windows). Safe to call after process exit."""
+    if p.poll() is not None:
+        return
+    if is_windows():
+        try:
+            p.send_signal(signal.CTRL_BREAK_EVENT)  # type: ignore[attr-defined]
+        except (ValueError, OSError):
+            p.terminate()
+    else:
+        p.terminate()
+
+
+def kill(p: subprocess.Popen) -> None:
+    """SIGKILL / TerminateProcess. Last resort."""
+    if p.poll() is not None:
+        return
+    p.kill()

pyplugin/proto/grpc_broker.proto

@@ -0,0 +1,21 @@
+// Vendored from hashicorp/go-plugin internal/plugin/grpc_broker.proto
+// SPDX-License-Identifier: MPL-2.0
+syntax = "proto3";
+package plugin;
+option go_package = "github.com/hashicorp/go-plugin/internal/plugin";
+
+message ConnInfo {
+    uint32 service_id = 1;
+    string network = 2;
+    string address = 3;
+    message Knock {
+        bool knock = 1;
+        bool ack = 2;
+        string error = 3;
+    }
+    Knock knock = 4;
+}
+
+service GRPCBroker {
+    rpc StartStream(stream ConnInfo) returns (stream ConnInfo);
+}

pyplugin/proto/grpc_controller.proto

@@ -0,0 +1,12 @@
+// Vendored from hashicorp/go-plugin internal/plugin/grpc_controller.proto
+// SPDX-License-Identifier: MPL-2.0
+syntax = "proto3";
+package plugin;
+option go_package = "github.com/hashicorp/go-plugin/internal/plugin";
+
+message Empty {
+}
+
+service GRPCController {
+    rpc Shutdown(Empty) returns (Empty);
+}

pyplugin/proto/grpc_stdio.proto

@@ -0,0 +1,22 @@
+// Vendored from hashicorp/go-plugin internal/plugin/grpc_stdio.proto
+// SPDX-License-Identifier: MPL-2.0
+syntax = "proto3";
+package plugin;
+option go_package = "github.com/hashicorp/go-plugin/internal/plugin";
+
+import "google/protobuf/empty.proto";
+
+service GRPCStdio {
+  rpc StreamStdio(google.protobuf.Empty) returns (stream StdioData);
+}
+
+message StdioData {
+  enum Channel {
+    INVALID = 0;
+    STDOUT = 1;
+    STDERR = 2;
+  }
+
+  Channel channel = 1;
+  bytes data = 2;
+}

pyplugin/reattach.py

@@ -0,0 +1,27 @@
+"""ReattachConfig — host re-connects to a pre-existing plugin process."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .handshake import NETWORK_UNIX, PROTOCOL_GRPC
+
+
+@dataclass(frozen=True)
+class ReattachConfig:
+    """Information needed to re-attach to a running plugin without spawning.
+
+    Mirrors go-plugin's ``ReattachConfig``. ``test=True`` (set by serving with
+    ``ServeConfig.test_mode``) tells the host's ``kill()`` to NOT terminate
+    the process — the test harness is responsible for shutdown.
+    """
+    pid: int
+    addr: str                      # unix path or "host:port"
+    network: str = NETWORK_UNIX
+    protocol: str = PROTOCOL_GRPC
+    protocol_version: int = 1
+    server_cert_pem: bytes | None = None  # for AutoMTLS reattach
+    # If reattaching with AutoMTLS, the host must supply the *original* host
+    # client cert+key it generated for the plugin so the TLS handshake works.
+    client_cert_pem: bytes | None = None
+    client_key_pem: bytes | None = None
+    test: bool = False

pyplugin/server.py

@@ -0,0 +1,204 @@
+"""Plugin-side ``serve()`` entry point (grpclib async).
+
+Mirrors go-plugin's ``Serve(opts *ServeConfig)`` lifecycle:
+
+1. Validate magic cookie (or skip in test mode).
+2. Negotiate protocol version against ``PLUGIN_PROTOCOL_VERSIONS``.
+3. Open a listener (unix on POSIX, TCP loopback on Windows or when forced).
+4. Build SSL context if ``PLUGIN_CLIENT_CERT`` is set (AutoMTLS).
+5. Collect servicers: GRPCBroker + GRPCController + GRPCStdio + Health
+   (service name = "plugin") + reflection + each user plugin.
+6. Build ``grpclib.server.Server`` and start it on the listener.
+7. Emit the handshake line to stdout, flush.
+8. Block until ``GRPCController.Shutdown`` fires or SIGTERM is received.
+
+``serve()`` is sync from the caller's perspective; it spins up its own
+asyncio event loop. Plugin authors implement async servicers but call
+``serve(config)`` from a normal ``main()``.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import ssl
+import sys
+from dataclasses import dataclass, field
+from typing import Optional, Union
+
+from grpclib.reflection.service import ServerReflection
+from grpclib.server import Server
+
+from . import mtls, transport
+from .broker import TLSMaterial, make_server_side_broker
+from .controller import GRPCControllerServicer
+from .cookie import validate_or_exit
+from .health import StaticHealth
+from .handshake import (
+    HandshakeConfig,
+    PROTOCOL_GRPC,
+    format_line,
+)
+from .plugin import Plugin, PluginSet, VersionedPlugins
+from .stdio import GRPCStdioServicer
+
+GRPC_HEALTH_SERVICE_NAME = "plugin"  # what the go-plugin host pings
+ENV_CLIENT_CERT = "PLUGIN_CLIENT_CERT"
+ENV_PROTOCOL_VERSIONS = "PLUGIN_PROTOCOL_VERSIONS"
+ENV_MULTIPLEX_GRPC = "PLUGIN_MULTIPLEX_GRPC"
+
+
+@dataclass
+class ServeConfig:
+    """Configuration handed to :func:`serve`."""
+    handshake_config: HandshakeConfig
+    plugins: Union[PluginSet, VersionedPlugins]
+    logger: Optional[logging.Logger] = None
+    test_mode: bool = False
+    force_tcp: bool = False
+    grpc_options: list = field(default_factory=list)
+
+
+def _is_versioned(p: Union[PluginSet, VersionedPlugins]) -> bool:
+    if not p:
+        return False
+    return all(isinstance(k, int) for k in p.keys())
+
+
+def _negotiate_version(cfg: ServeConfig) -> tuple[int, PluginSet]:
+    """Pick (version, PluginSet) — mirrors go-plugin's protocolVersion()."""
+    versioned: dict[int, PluginSet] = {}
+    if _is_versioned(cfg.plugins):
+        versioned.update(cfg.plugins)  # type: ignore[arg-type]
+    else:
+        versioned[cfg.handshake_config.protocol_version] = cfg.plugins  # type: ignore[assignment]
+
+    client_versions: list[int] = []
+    raw = os.environ.get(ENV_PROTOCOL_VERSIONS, "")
+    for s in (p for p in raw.split(",") if p):
+        try:
+            client_versions.append(int(s))
+        except ValueError:
+            sys.stderr.write(f"server sent invalid plugin version {s!r}\n")
+
+    server_versions = sorted(versioned.keys(), reverse=True)
+    for v in server_versions:
+        if v in client_versions:
+            return v, versioned[v]
+
+    fallback = sorted(versioned.keys())[0]
+    return fallback, versioned[fallback]
+
+
+async def _serve_async(config: ServeConfig) -> None:
+    logger = config.logger or logging.getLogger("pyplugin.server")
+
+    proto_version, plugin_set = _negotiate_version(config)
+    listener = transport.open_listener(force_tcp=config.force_tcp)
+
+    # AutoMTLS — match server.go: read PLUGIN_CLIENT_CERT, generate our cert,
+    # trust the host's cert as both client CA and root.
+    server_cert_b64 = ""
+    server_ssl: Optional[ssl.SSLContext] = None
+    server_cert: Optional[mtls.Cert] = None
+    client_cert_pem = os.environ.get(ENV_CLIENT_CERT)
+    if client_cert_pem:
+        server_cert = mtls.generate()
+        server_cert_b64 = mtls.encode_handshake_cert(server_cert.cert_der)
+        server_ssl = mtls.server_ssl_context(
+            cert_pem=server_cert.cert_pem,
+            key_pem=server_cert.key_pem,
+            peer_cert_pem=client_cert_pem.encode(),
+        )
+
+    # Build the broker's servicer + facade; the demux task we'll start under
+    # this same event loop.
+    broker_tls: Optional[TLSMaterial] = None
+    if server_cert is not None and client_cert_pem:
+        broker_tls = TLSMaterial(
+            cert_pem=server_cert.cert_pem,
+            key_pem=server_cert.key_pem,
+            peer_cert_pem=client_cert_pem.encode(),
+        )
+    broker_servicer, broker, demux_task = make_server_side_broker(broker_tls)
+
+    controller = GRPCControllerServicer()
+    stdio_servicer = GRPCStdioServicer()
+    health = StaticHealth()
+
+    user_servicers: list = []
+    for name, p in plugin_set.items():
+        if not isinstance(p, Plugin):
+            raise TypeError(f"plugin {name!r} must be a pyplugin.Plugin instance")
+        user_servicers.extend(p.servicers(broker))
+
+    base_servicers: list = [
+        broker_servicer,
+        controller,
+        stdio_servicer,
+        health,
+    ] + user_servicers
+
+    # Reflection extends the servicer list with its own service.
+    all_servicers = ServerReflection.extend(base_servicers)
+
+    server = Server(all_servicers)
+    if listener.network == "unix":
+        await server.start(path=listener.address, ssl=server_ssl)
+    else:
+        host, port = listener.address.split(":")
+        await server.start(host=host, port=int(port), ssl=server_ssl)
+
+    # Emit handshake. go-plugin always emits 6 segments; if PLUGIN_MULTIPLEX_GRPC
+    # is set, the 7th tells the host whether we *support* mux. We don't, so we
+    # advertise false (opt-out) — the host will then fail loudly if it required it.
+    multiplex: Optional[bool] = None
+    if os.environ.get(ENV_MULTIPLEX_GRPC):
+        multiplex = False
+    line = format_line(
+        app_protocol_version=proto_version,
+        network=listener.network,
+        address=listener.address,
+        protocol=PROTOCOL_GRPC,
+        server_cert=server_cert_b64,
+        multiplex_supported=multiplex,
+    )
+    if not config.test_mode:
+        sys.stdout.write(line + "\n")
+        sys.stdout.flush()
+
+    # Suppress SIGINT — go-plugin "eats" interrupts so the host owns shutdown.
+    # SIGTERM still triggers shutdown via the signal handler below.
+    loop = asyncio.get_running_loop()
+    if not config.test_mode:
+        try:
+            loop.add_signal_handler(signal.SIGINT, lambda: None)
+            loop.add_signal_handler(signal.SIGTERM, controller.shutdown_event.set)
+        except (NotImplementedError, RuntimeError):
+            pass  # Windows / non-main thread — best effort
+
+    try:
+        await controller.shutdown_event.wait()
+    finally:
+        # GracefulStop the gRPC server, then unlink the unix socket.
+        server.close()
+        try:
+            await asyncio.wait_for(server.wait_closed(), timeout=2.0)
+        except asyncio.TimeoutError:
+            pass
+        await broker.close()
+        stdio_servicer.close()
+        demux_task.cancel()
+        if listener.cleanup_path and os.path.exists(listener.cleanup_path):
+            try:
+                os.remove(listener.cleanup_path)
+            except OSError:
+                pass
+
+
+def serve(config: ServeConfig) -> None:
+    """Run the plugin server (sync entry point). Plugin's ``main()`` calls this."""
+    if not config.test_mode:
+        validate_or_exit(config.handshake_config)
+    asyncio.run(_serve_async(config))

pyplugin/stdio.py

@@ -0,0 +1,36 @@
+"""GRPCStdio servicer — streams plugin stdout/stderr writes to the host (grpclib async)."""
+from __future__ import annotations
+
+import asyncio
+
+from ._generated import grpc_stdio_grpc, grpc_stdio_pb2
+
+
+class GRPCStdioServicer(grpc_stdio_grpc.GRPCStdioBase):
+    """Streams stdio chunks. ``StreamStdio`` is called once by the host."""
+
+    def __init__(self) -> None:
+        self._q: asyncio.Queue[grpc_stdio_pb2.StdioData | None] = asyncio.Queue()
+        self._consumed = asyncio.Event()
+
+    def write_stdout(self, data: bytes) -> None:
+        if data:
+            self._q.put_nowait(grpc_stdio_pb2.StdioData(
+                channel=grpc_stdio_pb2.StdioData.STDOUT, data=data))
+
+    def write_stderr(self, data: bytes) -> None:
+        if data:
+            self._q.put_nowait(grpc_stdio_pb2.StdioData(
+                channel=grpc_stdio_pb2.StdioData.STDERR, data=data))
+
+    def close(self) -> None:
+        self._q.put_nowait(None)
+
+    async def StreamStdio(self, stream) -> None:  # noqa: N802
+        await stream.recv_message()  # request is google.protobuf.Empty
+        self._consumed.set()
+        while True:
+            chunk = await self._q.get()
+            if chunk is None:
+                return
+            await stream.send_message(chunk)