bowire-plugin 0.3.0__py3-none-any.whl

bowire_plugin/__init__.py

@@ -0,0 +1,69 @@
+# Copyright 2026 Küstenlogik
+# SPDX-License-Identifier: Apache-2.0
+"""bowire-plugin — write a Bowire protocol plugin in Python.
+
+A *sidecar* plugin is any executable that speaks JSON-RPC 2.0 over its
+stdin/stdout to the Bowire host. This package hides the wire: subclass
+:class:`BowirePlugin`, implement the protocol methods you need, and call
+:func:`run`.
+
+    from bowire_plugin import BowirePlugin, ServiceInfo, MethodInfo, InvokeResult, run
+
+    class MyPlugin(BowirePlugin):
+        id = "myproto"
+        name = "MyProtocol"
+
+        def discover(self, server_url, show_internal, settings):
+            return [ServiceInfo("Things", methods=[MethodInfo("get")])]
+
+        def invoke(self, server_url, service, method, json_messages, show_internal, metadata,
+                   settings):
+            return InvokeResult(response="hello", status="OK")
+
+    if __name__ == "__main__":
+        run(MyPlugin())
+
+Ship the script + a ``sidecar.json`` manifest in a zip and install it
+with ``bowire plugin install --file my-plugin.zip``.
+"""
+from ._http import run_http
+from ._manual_entry import (
+    ManualCallKind,
+    ManualEntryForm,
+    ManualField,
+    manual_entry_problems,
+)
+from ._models import (
+    FieldInfo,
+    InvokeResult,
+    MessageInfo,
+    MethodInfo,
+    PluginSetting,
+    ServiceInfo,
+    SettingOption,
+)
+from ._plugin import BowirePlugin
+from ._runtime import SIDECAR_PROTOCOL_VERSION, run
+from ._settings import Settings
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "SIDECAR_PROTOCOL_VERSION",
+    "BowirePlugin",
+    "FieldInfo",
+    "InvokeResult",
+    "ManualCallKind",
+    "ManualEntryForm",
+    "ManualField",
+    "MessageInfo",
+    "MethodInfo",
+    "PluginSetting",
+    "ServiceInfo",
+    "SettingOption",
+    "Settings",
+    "__version__",
+    "manual_entry_problems",
+    "run",
+    "run_http",
+]

bowire_plugin/_http.py

@@ -0,0 +1,127 @@
+# Copyright 2026 Küstenlogik
+# SPDX-License-Identifier: Apache-2.0
+"""HTTP/SSE server transport — the MCP-style streamable-HTTP shape.
+
+The same :class:`_Dispatcher` that powers the stdio runtime drives an
+HTTP service here: JSON-RPC requests arrive as ``POST`` (the HTTP
+response body carries the reply); server-initiated notifications
+(``$/stream/data`` / ``$/channel/data`` …) stream back over one
+long-lived SSE ``GET`` on the same path. Bowire's host wires to this
+with a ``"transport": "http"`` sidecar manifest pointing at the URL.
+
+Pure stdlib (``http.server``) — no extra dependencies.
+"""
+from __future__ import annotations
+
+import json
+import queue
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from ._plugin import BowirePlugin
+from ._runtime import _Dispatcher
+
+# Sentinel pushed onto the SSE queue to wake the GET loop for shutdown.
+_STOP = object()
+
+
+class _HttpServer:
+    """A running HTTP/SSE sidecar server. Reusable from tests
+    (start/port/shutdown); :func:`run_http` wraps it for the blocking
+    process entry point."""
+
+    def __init__(self, plugin: BowirePlugin, host: str = "127.0.0.1", port: int = 8770) -> None:
+        # One SSE event queue drained by the connected GET client. emit()
+        # from the dispatcher (incl. its stream-pump threads) lands here.
+        self._sse: queue.Queue[Any] = queue.Queue()
+        self._dispatcher = _Dispatcher(plugin, self._sse.put)
+        self._stop = threading.Event()
+
+        dispatcher = self._dispatcher
+        sse = self._sse
+        stop = self._stop
+
+        class Handler(BaseHTTPRequestHandler):
+            protocol_version = "HTTP/1.1"
+
+            def log_message(self, *args: Any) -> None:  # silence default stderr logging
+                pass
+
+            def do_POST(self) -> None:
+                length = int(self.headers.get("Content-Length", "0") or "0")
+                raw = self.rfile.read(length) if length else b""
+                try:
+                    msg = json.loads(raw)
+                except json.JSONDecodeError:
+                    self._send_json(400, {"error": "invalid json"})
+                    return
+                reply, post = dispatcher.handle(msg.get("method"), msg.get("id"), msg.get("params") or {})
+                self._send_json(200, reply if reply is not None else {})
+                if post is not None:
+                    post()  # start streaming only after the ack response is sent
+                if dispatcher.stopped:
+                    # shutdown handled — wake the SSE loop + stop serving
+                    # (on a separate thread; can't stop from a handler).
+                    stop.set()
+                    sse.put(_STOP)
+                    threading.Thread(target=self.server.shutdown, daemon=True).start()
+
+            def do_GET(self) -> None:
+                self.send_response(200)
+                self.send_header("Content-Type", "text/event-stream")
+                self.send_header("Cache-Control", "no-cache")
+                self.send_header("Connection", "keep-alive")
+                self.end_headers()
+                while not stop.is_set():
+                    try:
+                        evt = sse.get(timeout=0.5)
+                    except queue.Empty:
+                        continue
+                    if evt is _STOP:
+                        break
+                    try:
+                        payload = json.dumps(evt, separators=(",", ":"), ensure_ascii=False)
+                        self.wfile.write(f"data: {payload}\n\n".encode())
+                        self.wfile.flush()
+                    except (BrokenPipeError, ConnectionResetError):
+                        break
+
+            def _send_json(self, status: int, body: dict[str, Any]) -> None:
+                data = json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode()
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(data)))
+                self.end_headers()
+                self.wfile.write(data)
+
+        self._server = ThreadingHTTPServer((host, port), Handler)
+
+    @property
+    def port(self) -> int:
+        return self._server.server_address[1]
+
+    def serve_forever(self) -> None:
+        try:
+            self._server.serve_forever()
+        finally:
+            self._stop.set()
+            self._dispatcher.join_streams(timeout=2)
+            self._server.server_close()
+
+    def shutdown(self) -> None:
+        self._stop.set()
+        self._sse.put(_STOP)
+        self._server.shutdown()
+
+
+def run_http(plugin: BowirePlugin, *, host: str = "127.0.0.1", port: int = 8770) -> int:
+    """Serve ``plugin`` over HTTP/SSE on ``host:port`` until the host
+    sends ``shutdown``. Blocks; returns 0.
+
+    Point a sidecar manifest at it:
+
+        { "transport": "http", "url": "http://127.0.0.1:8770/" }
+    """
+    _HttpServer(plugin, host, port).serve_forever()
+    return 0

bowire_plugin/_manual_entry.py

@@ -0,0 +1,165 @@
+"""How a call to the plugin is entered by hand (Kuestenlogik/Bowire#1003).
+
+A plugin returns a :class:`ManualEntryForm` from
+:meth:`~bowire_plugin.BowirePlugin.manual_entry`; the SDK puts it in the
+``initialize`` reply as ``manualEntry``, and the workbench renders a Compose
+form from it and offers exactly these method types in its freeform form.
+The wire shape is the Bowire repo's docs/architecture/sidecar-plugins.md,
+"A hand-entry form".
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from ._models import SettingOption
+
+#: How a call kind runs: Unary is invoke, ServerStreaming is invokeStream,
+#: ClientStreaming and Duplex open a channel.
+METHOD_TYPES = ("Unary", "ServerStreaming", "ClientStreaming", "Duplex")
+
+_PLACEHOLDER = re.compile(r"\{([^{}]+)\}")
+
+
+@dataclass
+class ManualCallKind:
+    """One kind of call the plugin offers, e.g. produce or consume.
+
+    ``service`` and ``method`` are templates: ``{key}`` is the value of the
+    field with that key.
+    """
+
+    id: str
+    method_type: str
+    label: str | None = None
+    service: str = ""
+    method: str = ""
+    description: str | None = None
+    body_example: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "id": self.id,
+            "label": self.label or self.id,
+            "methodType": self.method_type,
+            "service": self.service,
+            "method": self.method,
+        }
+        if self.description is not None:
+            d["description"] = self.description
+        if self.body_example is not None:
+            d["bodyExample"] = self.body_example
+        return d
+
+
+@dataclass
+class ManualField:
+    """One field of the form.
+
+    ``placement`` ``"template"`` feeds only the call kinds' templates;
+    ``"metadata"`` (the default) goes into the call's metadata under ``key``.
+    ``call_kinds`` limits the field to those kinds; empty means all.
+    """
+
+    key: str
+    label: str | None = None
+    placement: str = "metadata"
+    description: str | None = None
+    placeholder: str | None = None
+    required: bool = False
+    type: str = "string"
+    options: list[SettingOption] = field(default_factory=list)
+    default_value: str | None = None
+    call_kinds: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "key": self.key,
+            "label": self.label or self.key,
+            "placement": self.placement,
+            "required": self.required,
+            "type": self.type,
+        }
+        for name, value in (
+            ("description", self.description),
+            ("placeholder", self.placeholder),
+            ("defaultValue", self.default_value),
+        ):
+            if value is not None:
+                d[name] = value
+        if self.options:
+            d["options"] = [o.to_dict() for o in self.options]
+        if self.call_kinds:
+            d["callKinds"] = list(self.call_kinds)
+        return d
+
+
+def manual_entry_problems(form: ManualEntryForm) -> list[str]:
+    """What is wrong with a form, or nothing — the check the host runs
+    before it serves one."""
+    problems: list[str] = []
+    if not form.call_kinds:
+        problems.append("it offers no call kind")
+
+    kind_ids: set[str] = set()
+    for kind in form.call_kinds:
+        if not kind.id:
+            problems.append("a call kind has no id")
+        elif kind.id in kind_ids:
+            problems.append(f"call kind '{kind.id}' is declared twice")
+        else:
+            kind_ids.add(kind.id)
+        if kind.method_type not in METHOD_TYPES:
+            problems.append(f"call kind '{kind.id}' has method type '{kind.method_type}'")
+
+    field_keys: set[str] = set()
+    for f in form.fields:
+        if not f.key:
+            problems.append("a field has no key")
+        elif f.key in field_keys:
+            problems.append(f"field '{f.key}' is declared twice")
+        else:
+            field_keys.add(f.key)
+        if f.type == "select" and not f.options:
+            problems.append(f"select field '{f.key}' has no options")
+        for kind_id in f.call_kinds:
+            if kind_id not in kind_ids:
+                problems.append(f"field '{f.key}' names unknown call kind '{kind_id}'")
+
+    for kind in form.call_kinds:
+        for template in (kind.service, kind.method):
+            for key in _PLACEHOLDER.findall(template or ""):
+                if key not in field_keys:
+                    problems.append(
+                        f"call kind '{kind.id}' uses the placeholder '{key}', which no field declares"
+                    )
+    return problems
+
+
+@dataclass
+class ManualEntryForm:
+    """How a call to this plugin is entered by hand.
+
+    A form the host would refuse — an unknown method type, a placeholder no
+    field declares, a ``select`` without options — is refused here, when it
+    is declared, rather than silently never appearing in the workbench.
+    """
+
+    call_kinds: list[ManualCallKind]
+    fields: list[ManualField] = field(default_factory=list)
+    url_placeholder: str | None = None
+
+    def __post_init__(self) -> None:
+        problems = manual_entry_problems(self)
+        if problems:
+            raise ValueError("manual entry form: " + "; ".join(problems))
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "callKinds": [k.to_dict() for k in self.call_kinds],
+            "fields": [f.to_dict() for f in self.fields],
+        }
+        if self.url_placeholder is not None:
+            d["urlPlaceholder"] = self.url_placeholder
+        return d

bowire_plugin/_models.py

@@ -0,0 +1,194 @@
+# Copyright 2026 Küstenlogik
+# SPDX-License-Identifier: Apache-2.0
+"""Data models mirroring Bowire's discovery / invocation shapes.
+
+The host (a .NET process) deserializes these as camelCase JSON — the
+same `BowireServiceInfo` / `BowireMethodInfo` / `InvokeResult` shapes the
+in-tree .NET plugins emit. The ``to_dict`` methods produce exactly that
+camelCase wire form.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class FieldInfo:
+    """One field of a request/response message (mirrors BowireFieldInfo)."""
+
+    name: str
+    number: int = 0
+    type: str = "string"
+    label: str = "optional"
+    is_map: bool = False
+    is_repeated: bool = False
+    required: bool = False
+    description: str | None = None
+    source: str | None = None  # REST-style: path/query/header/body
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "name": self.name,
+            "number": self.number,
+            "type": self.type,
+            "label": self.label,
+            "isMap": self.is_map,
+            "isRepeated": self.is_repeated,
+            "messageType": None,
+            "enumValues": None,
+            "required": self.required,
+        }
+        if self.description is not None:
+            d["description"] = self.description
+        if self.source is not None:
+            d["source"] = self.source
+        return d
+
+
+@dataclass
+class MessageInfo:
+    """A request or response message type (mirrors BowireMessageInfo)."""
+
+    name: str
+    full_name: str = ""
+    fields: list[FieldInfo] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "fullName": self.full_name or self.name,
+            "fields": [f.to_dict() for f in self.fields],
+        }
+
+
+@dataclass
+class MethodInfo:
+    """A single method within a service (mirrors BowireMethodInfo)."""
+
+    name: str
+    full_name: str = ""
+    method_type: str = "Unary"  # Unary | ServerStreaming | ClientStreaming | Duplex
+    input_type: MessageInfo | None = None
+    output_type: MessageInfo | None = None
+    client_streaming: bool = False
+    server_streaming: bool = False
+    summary: str | None = None
+    description: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "name": self.name,
+            "fullName": self.full_name or self.name,
+            "clientStreaming": self.client_streaming,
+            "serverStreaming": self.server_streaming,
+            "inputType": (self.input_type or MessageInfo(self.name + "Input")).to_dict(),
+            "outputType": (self.output_type or MessageInfo(self.name + "Output")).to_dict(),
+            "methodType": self.method_type,
+        }
+        if self.summary is not None:
+            d["summary"] = self.summary
+        if self.description is not None:
+            d["description"] = self.description
+        return d
+
+
+@dataclass
+class ServiceInfo:
+    """A discovered service + its methods (mirrors BowireServiceInfo)."""
+
+    name: str
+    package: str = ""
+    methods: list[MethodInfo] = field(default_factory=list)
+    source: str = "sidecar"
+    origin_url: str | None = None
+    description: str | None = None
+    version: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "name": self.name,
+            "package": self.package,
+            "methods": [m.to_dict() for m in self.methods],
+            "source": self.source,
+        }
+        if self.origin_url is not None:
+            d["originUrl"] = self.origin_url
+        if self.description is not None:
+            d["description"] = self.description
+        if self.version is not None:
+            d["version"] = self.version
+        return d
+
+
+@dataclass
+class InvokeResult:
+    """Result of a unary invocation (mirrors InvokeResult)."""
+
+    response: str | None = None
+    duration_ms: int = 0
+    status: str = "OK"
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "response": self.response,
+            "durationMs": self.duration_ms,
+            "status": self.status,
+            "metadata": self.metadata,
+        }
+
+
+@dataclass
+class SettingOption:
+    """One choice of a ``select`` setting (mirrors BowirePluginSettingOption).
+
+    ``value`` is what the host sends back when the operator picks it;
+    ``label`` is what the dialog shows, and defaults to the value.
+    """
+
+    value: str
+    label: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"value": self.value}
+        if self.label is not None:
+            d["label"] = self.label
+        return d
+
+
+@dataclass
+class PluginSetting:
+    """A setting the plugin contributes to the Bowire Settings dialog.
+
+    ``type`` is ``"bool"``, ``"string"``, ``"number"`` or ``"select"``. A
+    ``select`` needs ``options`` — without them the dialog has nothing to
+    offer, so declaring one is refused here rather than rendered empty.
+
+    The value comes back on every call as a :class:`~bowire_plugin.Settings`
+    argument; ``default_value`` is what its accessors return while nobody
+    has set one.
+    """
+
+    key: str
+    label: str
+    description: str | None = None
+    type: str = "bool"
+    default_value: Any = None
+    options: list[SettingOption] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.type == "select" and not self.options:
+            raise ValueError(f"select setting '{self.key}' declares no options")
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "key": self.key,
+            "label": self.label,
+            "description": self.description,
+            "type": self.type,
+            "defaultValue": self.default_value,
+        }
+        if self.options:
+            d["options"] = [o.to_dict() for o in self.options]
+        return d

bowire_plugin/_plugin.py

@@ -0,0 +1,95 @@
+# Copyright 2026 Küstenlogik
+# SPDX-License-Identifier: Apache-2.0
+"""The base class a Python sidecar plugin subclasses."""
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+
+from ._manual_entry import ManualEntryForm
+from ._models import InvokeResult, PluginSetting, ServiceInfo
+from ._settings import Settings
+
+
+class BowirePlugin:
+    """Subclass this and implement the methods you need, then hand an
+    instance to :func:`bowire_plugin.run`. The runtime drives the
+    JSON-RPC-over-stdio contract; you only write protocol logic.
+
+    Set :attr:`id`, :attr:`name`, and (optionally) :attr:`icon_svg` as
+    class attributes. The ``id`` must match the ``protocol.id`` in the
+    plugin's ``sidecar.json`` manifest.
+
+    Every call receives ``settings``: the values set for what
+    :meth:`settings` declared, read fresh for that call (see
+    :class:`~bowire_plugin.Settings`).
+    """
+
+    #: Short protocol id (e.g. ``"zenoh"``). Must match sidecar.json.
+    id: str = ""
+    #: Display name shown in the workbench tab (e.g. ``"Zenoh"``).
+    name: str = ""
+    #: Inline SVG for the protocol tab. Optional — the host falls back
+    #: to a generic plug icon when empty.
+    icon_svg: str = ""
+
+    def settings(self) -> list[PluginSetting]:
+        """Settings this plugin contributes to the Settings dialog.
+
+        Read once per process, for the ``initialize`` reply. The values come back
+        as the ``settings`` argument of every call, and the defaults
+        declared here are what its accessors return for a key nobody set.
+        """
+        return []
+
+    def manual_entry(self) -> ManualEntryForm | None:
+        """How a call to this plugin is entered by hand (Kuestenlogik/Bowire#1003).
+
+        Sent in the ``initialize`` reply as ``manualEntry``; the workbench
+        renders a Compose form from it. Default: none.
+        """
+        return None
+
+    def discover(
+        self, server_url: str, show_internal: bool, settings: Settings
+    ) -> Iterable[ServiceInfo]:
+        """Enumerate services + methods for ``server_url``.
+
+        Return an empty list to decline the URL (the host then tries
+        other plugins). Default: nothing discovered.
+        """
+        return []
+
+    def invoke(
+        self,
+        server_url: str,
+        service: str,
+        method: str,
+        json_messages: list[str],
+        show_internal: bool,
+        metadata: dict[str, str],
+        settings: Settings,
+    ) -> InvokeResult:
+        """Perform a unary call and return the result. Default: an error
+        result noting the plugin didn't implement invoke."""
+        return InvokeResult(status="invoke not implemented by sidecar")
+
+    def invoke_stream(
+        self,
+        server_url: str,
+        service: str,
+        method: str,
+        json_messages: list[str],
+        show_internal: bool,
+        metadata: dict[str, str],
+        settings: Settings,
+    ) -> Iterator[str]:
+        """Server-streaming call: yield each message (a JSON string) as
+        it arrives. The runtime forwards every yielded value to the host
+        as a ``$/stream/data`` notification and sends ``$/stream/end``
+        when the generator finishes. Default: an empty stream."""
+        return iter(())
+
+    def shutdown(self) -> None:
+        """Optional cleanup hook, called when the host asks the sidecar
+        to exit. Default: no-op."""
+        return