python-plugin 0.1.0__py3-none-any.whl

pyplugin/transport.py

@@ -0,0 +1,103 @@
+"""Listener helpers — unix socket on POSIX, TCP loopback elsewhere or when forced.
+
+Mirrors go-plugin's ``serverListener_unix`` / ``serverListener_tcp``.
+"""
+from __future__ import annotations
+
+import os
+import socket
+import sys
+import tempfile
+from dataclasses import dataclass
+
+from .handshake import NETWORK_TCP, NETWORK_UNIX
+
+ENV_MIN_PORT = "PLUGIN_MIN_PORT"
+ENV_MAX_PORT = "PLUGIN_MAX_PORT"
+ENV_UNIX_SOCKET_DIR = "PLUGIN_UNIX_SOCKET_DIR"
+ENV_UNIX_SOCKET_GROUP = "PLUGIN_UNIX_SOCKET_GROUP"
+
+
+@dataclass
+class Listener:
+    """A bound listener ready for ``grpc.Server.add_*_port``."""
+    network: str          # "unix" or "tcp"
+    address: str          # "/tmp/plugin123" or "127.0.0.1:port"
+    grpc_target: str      # what to pass to grpc: "unix:/tmp/sock" or "127.0.0.1:port"
+    cleanup_path: str | None = None  # filesystem path to remove on close, if any
+
+
+def _is_windows() -> bool:
+    return sys.platform.startswith("win")
+
+
+def open_listener(*, force_tcp: bool = False) -> Listener:
+    """Open a plugin-side listener following go-plugin's defaults.
+
+    On Windows or when ``force_tcp``, picks an unused TCP port in the range
+    given by ``PLUGIN_MIN_PORT``/``PLUGIN_MAX_PORT``. Otherwise creates a
+    unique-named unix socket file (under ``PLUGIN_UNIX_SOCKET_DIR`` if set).
+    """
+    if force_tcp or _is_windows():
+        return _open_tcp()
+    return _open_unix()
+
+
+def _open_unix() -> Listener:
+    socket_dir = os.environ.get(ENV_UNIX_SOCKET_DIR) or None
+    # Mirror go-plugin's serverListener_unix: claim a unique tempfile name,
+    # remove the file, hand the (now non-existent) path to grpc which will
+    # bind the unix socket itself.
+    fd, path = tempfile.mkstemp(prefix="plugin", dir=socket_dir)
+    os.close(fd)
+    os.remove(path)
+    return Listener(
+        network=NETWORK_UNIX,
+        address=path,
+        grpc_target=f"unix:{path}",
+        cleanup_path=path,
+    )
+
+
+def _open_tcp() -> Listener:
+    min_port = int(os.environ.get(ENV_MIN_PORT) or 0)
+    max_port = int(os.environ.get(ENV_MAX_PORT) or 0)
+
+    if min_port == 0 and max_port == 0:
+        # Pick a free port via OS.
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.bind(("127.0.0.1", 0))
+        port = s.getsockname()[1]
+        s.close()
+        return Listener(
+            network=NETWORK_TCP,
+            address=f"127.0.0.1:{port}",
+            grpc_target=f"127.0.0.1:{port}",
+        )
+
+    if min_port > max_port:
+        raise OSError(f"PLUGIN_MIN_PORT={min_port} > PLUGIN_MAX_PORT={max_port}")
+
+    for port in range(min_port, max_port + 1):
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        try:
+            s.bind(("127.0.0.1", port))
+            s.close()
+            return Listener(
+                network=NETWORK_TCP,
+                address=f"127.0.0.1:{port}",
+                grpc_target=f"127.0.0.1:{port}",
+            )
+        except OSError:
+            s.close()
+            continue
+    raise OSError("couldn't bind plugin TCP listener in configured port range")
+
+
+def grpc_dial_target(network: str, address: str) -> str:
+    """Translate a (network, address) pair from a handshake into a grpc.Dial target."""
+    if network == NETWORK_UNIX:
+        return f"unix:{address}"
+    if network == NETWORK_TCP:
+        return address
+    raise ValueError(f"unknown network type: {network!r}")

python_plugin-0.1.0.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.4
+Name: python-plugin
+Version: 0.1.0
+Summary: Wire-compatible Python port of go-plugin (gRPC subprocess plugins with AutoMTLS)
+Project-URL: Homepage, https://github.com/mlund01/py-plugin
+Project-URL: Repository, https://github.com/mlund01/py-plugin
+Project-URL: Issues, https://github.com/mlund01/py-plugin/issues
+Author: Max Lund
+License-Expression: MIT
+License-File: LICENSE
+Keywords: go-plugin,grpc,ipc,mtls,plugin,rpc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41
+Requires-Dist: grpclib[protobuf]>=0.4.7
+Requires-Dist: protobuf>=4.25
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.2; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyplugin
+
+A Python port of [`go-plugin`](https://github.com/hashicorp/go-plugin),
+**byte-for-byte wire-compatible** with the original — including AutoMTLS
+with ECDSA P-521 ephemeral certs.
+
+A Python host can launch a Go plugin built with go-plugin, and a Go host
+built against go-plugin can launch a Python plugin built with pyplugin.
+**Both directions, with or without AutoMTLS.** Verified against the
+upstream `examples/grpc/plugin-go-grpc` binary in the test suite.
+
+## Install
+
+```bash
+pip install python-plugin
+```
+
+The PyPI distribution name is `python-plugin`; the Python import name is
+`pyplugin` (`from pyplugin import Client, serve, ...`).
+
+## Why grpclib (and async)
+
+go-plugin generates **ECDSA P-521** ephemeral certificates for AutoMTLS.
+`grpcio` is built on BoringSSL, which deliberately omits P-521 from its
+TLS signature algorithm list — there's no way to configure it back in,
+and we want exact wire-compat. `grpclib` is a pure-Python gRPC library
+on top of Python's `ssl` module (OpenSSL), which supports P-521 freely.
+That makes interop with stock go-plugin work out of the box.
+
+The cost: the public API is **async**. Plugin servicers are `async def`;
+host code uses `async with Client(...) as c: await c.start()` etc.
+
+## Quick start
+
+A complete runnable example lives in [`examples/greeter/`](examples/greeter/) —
+clone the repo, `pip install -e '.[dev]'`, then:
+
+```bash
+python examples/greeter/host.py "ada"            # insecure
+AUTO_MTLS=1 python examples/greeter/host.py "ada" # P-521 mTLS
+```
+
+### Plugin (async)
+
+```python
+# my_plugin.py
+from pyplugin import HandshakeConfig, Plugin, ServeConfig, serve
+from grpclib.client import Channel
+
+# stubs generated by grpclib's protoc plugin (see scripts/gen_protos.py):
+import myservice_grpc, myservice_pb2
+
+class MyServicer(myservice_grpc.MyServiceBase):
+    async def Greet(self, stream):
+        request = await stream.recv_message()
+        await stream.send_message(myservice_pb2.GreetResponse(message=f"hello {request.name}"))
+
+class MyPlugin(Plugin):
+    def servicers(self, broker):
+        return [MyServicer()]
+    def stub(self, broker, channel: Channel):
+        return myservice_grpc.MyServiceStub(channel)
+
+if __name__ == "__main__":
+    serve(ServeConfig(
+        handshake_config=HandshakeConfig(
+            protocol_version=1,
+            magic_cookie_key="MYPLUGIN_COOKIE",
+            magic_cookie_value="hello",
+        ),
+        plugins={"my": MyPlugin()},
+    ))
+```
+
+### Host (async)
+
+```python
+import asyncio, sys
+from pyplugin import Client, ClientConfig, HandshakeConfig
+
+async def main():
+    async with Client(ClientConfig(
+        handshake_config=HandshakeConfig(1, "MYPLUGIN_COOKIE", "hello"),
+        plugins={"my": MyPlugin()},
+        cmd=[sys.executable, "my_plugin.py"],
+        auto_mtls=True,           # P-521 mTLS, fully wire-compatible with go-plugin
+    )) as client:
+        stub = client.dispense("my")
+        resp = await stub.Greet(myservice_pb2.GreetRequest(name="world"))
+        print(resp.message)
+
+asyncio.run(main())
+```
+
+## What's implemented
+
+| Feature | Status |
+| --- | --- |
+| stdout handshake protocol (6/7 segments, base64.RawStdEncoding cert) | ✅ |
+| magic cookie validation | ✅ |
+| gRPC transport: unix sockets (POSIX) and TCP loopback | ✅ |
+| AutoMTLS with **ECDSA P-521 / SHA-512** (matches go-plugin) | ✅ |
+| `GRPCController.Shutdown` graceful exit | ✅ |
+| Kill ladder: Shutdown → SIGTERM → SIGKILL | ✅ |
+| stderr forwarding with hclog parser (JSON + pretty) | ✅ |
+| `GRPCBroker` bidirectional sub-channels (Accept/Dial) | ✅ |
+| `GRPCStdio` post-handshake stdout/stderr stream | ✅ |
+| `ReattachConfig` (host re-connects to running plugin) | ✅ |
+| `VersionedPlugins` negotiation | ✅ |
+| gRPC reflection + health (service name `plugin`) | ✅ |
+| `PLUGIN_MULTIPLEX_GRPC` (broker over single socket) | ❌ deferred (advertised as not supported) |
+
+## Verified Python ↔ Go interop
+
+The test suite includes 4 real interop tests against upstream go-plugin:
+
+```
+tests/interop/test_python_host_drives_go_plugin.py
+    test_python_host_drives_go_plugin_no_mtls          ✓
+    test_python_host_drives_go_plugin_with_p521_automtls ✓
+
+tests/interop/test_go_host_drives_python_plugin.py
+    test_go_host_drives_python_plugin_no_mtls            ✓
+    test_go_host_drives_python_plugin_with_p521_automtls ✓
+```
+
+These run only when the binaries are present; the README of
+`tests/interop/` describes how to build them. Out of the box you can
+reproduce the matrix locally:
+
+```bash
+# Build go-plugin's example KV plugin (Go)
+git clone --depth=1 https://github.com/hashicorp/go-plugin /tmp/gp
+(cd /tmp/gp/examples/grpc && go build -o /tmp/plugin-go-grpc ./plugin-go-grpc)
+PYPLUGIN_GO_PLUGIN_KV=/tmp/plugin-go-grpc pytest tests/interop/test_python_host_drives_go_plugin.py
+```
+
+For the Go-host-drives-Python-plugin direction, see the small Go host
+template at the end of this README — drop it into `tests/interop/go-host/`
+with a `replace` directive in `go.mod` pointing at the local go-plugin
+clone, `go build`, then point `PYPLUGIN_GO_HOST_BIN` at the binary.
+
+## Layout
+
+```
+src/pyplugin/
+  handshake.py      # stdout protocol line format/parse
+  cookie.py         # magic-cookie validation
+  mtls.py           # ephemeral P-521 cert generation + ssl.SSLContext builders
+  transport.py      # unix / tcp listener helpers
+  server.py         # serve(ServeConfig) — sync entry, internal asyncio loop
+  client.py         # Client / ClientConfig — async host launcher
+  process.py        # cross-platform subprocess termination
+  reattach.py       # ReattachConfig
+  controller.py     # GRPCController.Shutdown servicer (grpclib async)
+  broker.py         # GRPCBroker bidirectional multiplexer (grpclib async)
+  stdio.py          # GRPCStdio post-handshake stream (grpclib async)
+  health.py         # static grpc.health.v1 servicer (returns SERVING for "plugin")
+  plugin.py         # Plugin ABC, PluginSet, VersionedPlugins
+  logging_bridge.py # hclog (JSON + pretty) line parser
+  errors.py         # exception hierarchy
+  proto/            # vendored .proto files from go-plugin (verbatim)
+  _generated/       # checked-in grpclib stubs
+fixtures/example_kv/  # example KV plugin used by smoke tests
+tests/                # 40 unit + Python↔Python tests
+tests/interop/        # 4 real-go-plugin interop tests
+```
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/python scripts/gen_protos.py     # regenerate stubs
+.venv/bin/python -m pytest                  # run tests
+```
+
+## Go host template
+
+Use this with `go.mod`'s `replace github.com/hashicorp/go-plugin => /path/to/clone`:
+
+```go
+package main
+
+import (
+    "fmt"; "io"; "log"; "os"; "os/exec"
+    hclog "github.com/hashicorp/go-hclog"
+    "github.com/hashicorp/go-plugin"
+    "github.com/hashicorp/go-plugin/examples/grpc/shared"
+)
+
+func main() {
+    log.SetOutput(io.Discard)
+    client := plugin.NewClient(&plugin.ClientConfig{
+        HandshakeConfig:  shared.Handshake,
+        Plugins:          map[string]plugin.Plugin{shared.PluginGRPC: &shared.KVGRPCPlugin{}},
+        Cmd:              exec.Command(os.Args[1], os.Args[2]),
+        AllowedProtocols: []plugin.Protocol{plugin.ProtocolGRPC},
+        AutoMTLS:         os.Getenv("AUTO_MTLS") == "1",
+        Logger:           hclog.New(&hclog.LoggerOptions{Output: io.Discard, Level: hclog.Off}),
+    })
+    defer client.Kill()
+    rpc, err := client.Client(); if err != nil { panic(err) }
+    raw, err := rpc.Dispense(shared.PluginGRPC); if err != nil { panic(err) }
+    kv := raw.(shared.KV)
+    if err := kv.Put(os.Args[4], []byte(os.Args[5])); err != nil { panic(err) }
+    v, err := kv.Get(os.Args[4]); if err != nil { panic(err) }
+    fmt.Print(string(v))
+}
+```
+
+## License
+
+MIT. The vendored `.proto` files in `src/pyplugin/proto/` retain their
+upstream MPL-2.0 headers from
+[hashicorp/go-plugin](https://github.com/hashicorp/go-plugin); MPL-2.0 is
+file-level and is compatible with MIT for the rest of the project.

python_plugin-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+pyplugin/__init__.py,sha256=J1sgTlsqJCngvI2FeYD4H3uYSk79COGsQBOHhrMcfHs,1204
+pyplugin/broker.py,sha256=z3mSzP1FyiDiNNZsC9iNFrEQQmU-_GVnPT6I5wfLgyI,7989
+pyplugin/client.py,sha256=Fx4iq0Czqytoelj6tkUgj3mGUdRGqt8ZrVqJow_kIuI,15278
+pyplugin/controller.py,sha256=MBkAl_9eMc694-21hUuiQTrCbkJUmNJiuZY-Dr_Db5k,757
+pyplugin/cookie.py,sha256=kDta4YhHaK1rfiv_-iPyZWvCLjMmrn3UHlc2qwFrQFk,1407
+pyplugin/errors.py,sha256=2tF-bITFFt-lDWs866qYd6XvhprIVsrOuwdWJRFsXow,1115
+pyplugin/handshake.py,sha256=g2yYjxap_vLkHW1y3hQjSoTft8Ep6PkECKGNdqduIVI,3821
+pyplugin/health.py,sha256=XqAzdMt5aMjXryV1qzxZNH9t9FEqhrJekgpLa5X0sls,1653
+pyplugin/logging_bridge.py,sha256=Icxjw3iGAJ03IgazsVUiPIDjUY_fZR7WIzTDQAH81no,2247
+pyplugin/mtls.py,sha256=5gYFr-iQUshY09UrGiHg0TphK9UmbBqjWh2vr35swdg,6483
+pyplugin/plugin.py,sha256=UbPP_S0dfqD1rrqS2a0Wjo0S9ngMA6nDg-QwQHXtr0I,1199
+pyplugin/process.py,sha256=vomevPuBmTOZrgnb4QnmmQPe2qUOrSxmMHb27Iy1bno,1764
+pyplugin/reattach.py,sha256=ExmkGvigeG421Lo6DzcX5qM-3GK0h3Yg8XtZpX9LCHE,1049
+pyplugin/server.py,sha256=gmgWC6_YiK4WW9U7pE5nPUvvgeQ1-Yg7iND2_vvw3Mg,7404
+pyplugin/stdio.py,sha256=TsxBnhcHCm14oCPVpj7eHsJPcHDrq9l93fJ82SqR2Yo,1264
+pyplugin/transport.py,sha256=j7E_O44fMwYE6G1rAh25V8ZPz_bylS5hThOBkc3C1wU,3370
+pyplugin/_generated/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyplugin/_generated/grpc_broker_grpc.py,sha256=sj0dWUXQFyfCBVY5lXm7f2IRDb_WOeDXBOCHSEfVroo,1127
+pyplugin/_generated/grpc_broker_pb2.py,sha256=Yc5cfRt20Hjm6vCCxNgVizshGq5_kFAu4Pj98BeLiNQ,2027
+pyplugin/_generated/grpc_controller_grpc.py,sha256=frLWKtv-zFh3K380N_TNGDR8zq8lG5oh-z1RwL-akto,1138
+pyplugin/_generated/grpc_controller_pb2.py,sha256=A8qRX9pcb8WcFLjYScXV46z-9KtZxbvt8uJ8EgR8AK4,1589
+pyplugin/_generated/grpc_stdio_grpc.py,sha256=YhdaTvyPtXVMvjMgbhy78Zlz7vKF9M6rinXR08Rnqhc,1173
+pyplugin/_generated/grpc_stdio_pb2.py,sha256=igVl4onDwxkD0XgUKR_vY8lAWD_h15qmu2K9CN5luT4,2025
+pyplugin/proto/grpc_broker.proto,sha256=VJn8FNFAgnnaTj8Zj_Tt0-gp_83gEHpjAeBXHmjCpX0,516
+pyplugin/proto/grpc_controller.proto,sha256=Vw2Om0jlGbfPu0uuxZb_vG1mcL87ZQAAOGC-wbdNRVQ,304
+pyplugin/proto/grpc_stdio.proto,sha256=u2CW22euvSA7BGeLN4YbQm2cMyurY1BiMjBexneWzoA,477
+python_plugin-0.1.0.dist-info/METADATA,sha256=43EHSne8d3JaUCfuniCNao5EJwbwrKj6QU18G6U9BSo,9597
+python_plugin-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_plugin-0.1.0.dist-info/licenses/LICENSE,sha256=fILwPEdelkIjeEzc0o8FY3rqqQNQW_bKBYoD0gX6zmY,1065
+python_plugin-0.1.0.dist-info/RECORD,,

python_plugin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_plugin-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Lund
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.