bowire-plugin 0.3.0__py3-none-any.whl

bowire_plugin/_runtime.py

@@ -0,0 +1,258 @@
+# Copyright 2026 Küstenlogik
+# SPDX-License-Identifier: Apache-2.0
+"""The JSON-RPC dispatch + stdio runtime that drive a :class:`BowirePlugin`.
+
+Wire contract: NDJSON (one JSON-RPC 2.0 envelope per ``\\n``-terminated
+UTF-8 line) over the process's stdin/stdout, exactly the framing Bowire's
+host (and MCP's stdio transport) use. See the Bowire repo's
+``docs/architecture/sidecar-plugins.md`` for the full spec.
+
+The transport-agnostic dispatch lives in :class:`_Dispatcher`; the stdio
+runtime and the HTTP/SSE server (in ``_http``) both reuse it.
+
+Methods handled: initialize, ping, shutdown, discover, invoke,
+invokeStream (host-minted streamId in params; ack then emit
+``$/stream/data`` notifications + ``$/stream/end``).
+
+The ``initialize`` reply carries ``protocolVersion`` +
+``capabilities`` (#416), so the host knows which contract it is talking to
+and which calls it can skip.
+
+``discover`` / ``invoke`` / ``invokeStream`` params may carry a ``settings``
+object (Kuestenlogik/Bowire#693): the values set for the settings the plugin
+declared. Every call hands the plugin a fresh :class:`Settings` built from it,
+so a changed value applies from the next call on.
+"""
+from __future__ import annotations
+
+import json
+import sys
+import threading
+from collections.abc import Callable
+from typing import Any, TextIO
+
+from ._models import PluginSetting
+from ._plugin import BowirePlugin
+from ._settings import Settings
+
+# A notification sink: hands a fully-formed JSON-RPC notification
+# envelope to whichever transport is in play (stdout line / SSE event).
+EmitFn = Callable[[dict[str, Any]], None]
+
+#: The sidecar wire-contract version this SDK speaks (#416). The host
+#: accepts a sidecar inside its supported range and refuses one outside it
+#: at the handshake, rather than failing at the first call. A sidecar that
+#: sends none at all is tolerated as contract v1 — with a warning in the
+#: host log on every boot, which is what this SDK used to earn.
+SIDECAR_PROTOCOL_VERSION = 1
+
+
+def _capabilities(plugin: BowirePlugin) -> dict[str, bool]:
+    """What this plugin can actually answer, read off the subclass.
+
+    A flag set to ``False`` lets the host skip the call entirely. The base
+    class ships a polite default for every method — ``discover`` returns
+    ``[]``, ``invoke`` an "not implemented" result — so "did the author
+    override it?" is the only honest answer to "can it do this?", and the
+    host gets to stop asking questions whose answer is a stub.
+
+    ``channels`` is always ``False``: the Python SDK has no channel surface
+    at all, so the host's ``openChannel`` would round-trip to a method-not-
+    found every time an operator opened a duplex method.
+    """
+    cls = type(plugin)
+    return {
+        "discover": cls.discover is not BowirePlugin.discover,
+        "invoke": cls.invoke is not BowirePlugin.invoke,
+        "invokeStream": cls.invoke_stream is not BowirePlugin.invoke_stream,
+        "channels": False,
+    }
+
+
+class _Dispatcher:
+    """Transport-agnostic JSON-RPC dispatch over a :class:`BowirePlugin`.
+
+    :meth:`handle` turns one request into its reply envelope (or
+    ``None`` for notifications / post-shutdown). Streaming frames are
+    pushed through the injected :data:`EmitFn` so stdio and HTTP route
+    them to their own wire.
+    """
+
+    def __init__(self, plugin: BowirePlugin, emit: EmitFn) -> None:
+        self._plugin = plugin
+        self._emit = emit
+        self._stop = threading.Event()
+        self._stream_threads: list[threading.Thread] = []
+        self._declared: list[PluginSetting] | None = None
+
+    @property
+    def stopped(self) -> bool:
+        return self._stop.is_set()
+
+    def _declared_settings(self) -> list[PluginSetting]:
+        """What the plugin declared, asked once: the ``initialize`` reply and
+        every call's defaults have to agree on it. Built lazily rather than in
+        ``__init__`` so a plugin whose ``settings()`` raises fails the
+        handshake as a JSON-RPC error instead of the process start."""
+        if self._declared is None:
+            self._declared = list(self._plugin.settings())
+        return self._declared
+
+    def _call_settings(self, params: dict[str, Any]) -> Settings:
+        # Absent when nobody set anything — the common case, not an error.
+        raw = params.get("settings")
+        return Settings(raw if isinstance(raw, dict) else None, self._declared_settings())
+
+    def join_streams(self, timeout: float = 5) -> None:
+        """Let in-flight stream pumps flush their final frames on exit."""
+        for t in self._stream_threads:
+            t.join(timeout=timeout)
+
+    def handle(
+        self, method: str | None, req_id: Any, params: dict[str, Any]
+    ) -> tuple[dict[str, Any] | None, Callable[[], None] | None]:
+        """Return ``(reply, post_action)``. The caller writes ``reply``
+        (nothing if ``None``), then runs ``post_action`` if present.
+        Streaming starts in ``post_action`` so the ack is always on the
+        wire before the first ``$/stream/data`` frame."""
+        try:
+            result, post = self._invoke_method(method, params)
+        except _MethodNotFound:
+            return (None if req_id is None else _err(req_id, -32601, f"method not found: {method}")), None
+        except Exception as ex:  # noqa: BLE001 — surface as JSON-RPC error, never crash the loop
+            return (None if req_id is None else _err(req_id, -32000, f"{type(ex).__name__}: {ex}")), None
+        reply = None if req_id is None else {"jsonrpc": "2.0", "id": req_id, "result": result}
+        return reply, post
+
+    def _invoke_method(
+        self, method: str | None, params: dict[str, Any]
+    ) -> tuple[Any, Callable[[], None] | None]:
+        if method == "initialize":
+            reply: dict[str, Any] = {
+                "name": self._plugin.name,
+                "id": self._plugin.id,
+                "iconSvg": self._plugin.icon_svg,
+                "settings": [s.to_dict() for s in self._declared_settings()],
+                "protocolVersion": SIDECAR_PROTOCOL_VERSION,
+                "capabilities": _capabilities(self._plugin),
+            }
+            # Kuestenlogik/Bowire#1003 - absent when the plugin declares none.
+            form = self._plugin.manual_entry()
+            if form is not None:
+                reply["manualEntry"] = form.to_dict()
+            return reply, None
+        if method == "ping":
+            return "pong", None
+        if method == "shutdown":
+            try:
+                self._plugin.shutdown()
+            finally:
+                self._stop.set()
+            return True, None
+        if method == "discover":
+            services = self._plugin.discover(
+                params.get("serverUrl", ""),
+                bool(params.get("showInternalServices", False)),
+                self._call_settings(params),
+            )
+            return [s.to_dict() for s in services], None
+        if method == "invoke":
+            return self._plugin.invoke(
+                params.get("serverUrl", ""),
+                params.get("service", ""),
+                params.get("method", ""),
+                list(params.get("jsonMessages") or []),
+                bool(params.get("showInternalServices", False)),
+                dict(params.get("metadata") or {}),
+                self._call_settings(params),
+            ).to_dict(), None
+        if method == "invokeStream":
+            stream_id = params.get("streamId")
+
+            def start_pump() -> None:
+                t = threading.Thread(target=self._pump_stream, args=(stream_id, params), daemon=True)
+                self._stream_threads.append(t)
+                t.start()
+
+            # ack now; the caller starts the pump after writing it
+            return {"streamId": stream_id}, start_pump
+        raise _MethodNotFound
+
+    def _pump_stream(self, stream_id: Any, params: dict[str, Any]) -> None:
+        error: dict[str, Any] | None = None
+        try:
+            for message in self._plugin.invoke_stream(
+                params.get("serverUrl", ""),
+                params.get("service", ""),
+                params.get("method", ""),
+                list(params.get("jsonMessages") or []),
+                bool(params.get("showInternalServices", False)),
+                dict(params.get("metadata") or {}),
+                self._call_settings(params),
+            ):
+                if self._stop.is_set():
+                    break
+                self._emit({"jsonrpc": "2.0", "method": "$/stream/data",
+                            "params": {"streamId": stream_id, "message": message}})
+        except Exception as ex:  # noqa: BLE001
+            error = {"code": -32000, "message": f"{type(ex).__name__}: {ex}"}
+        finally:
+            self._emit({"jsonrpc": "2.0", "method": "$/stream/end",
+                        "params": {"streamId": stream_id, "error": error}})
+
+
+class _MethodNotFound(Exception):
+    pass
+
+
+def _err(req_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": req_id, "error": {"code": code, "message": message}}
+
+
+class _StdioRuntime:
+    """NDJSON JSON-RPC over stdin/stdout, driving a :class:`_Dispatcher`."""
+
+    def __init__(self, plugin: BowirePlugin, stdin: TextIO, stdout: TextIO) -> None:
+        self._stdin = stdin
+        self._stdout = stdout
+        self._write_lock = threading.Lock()
+        self._dispatcher = _Dispatcher(plugin, self._write)
+
+    def _write(self, envelope: dict[str, Any]) -> None:
+        line = json.dumps(envelope, separators=(",", ":"), ensure_ascii=False)
+        with self._write_lock:
+            self._stdout.write(line)
+            self._stdout.write("\n")
+            self._stdout.flush()
+
+    def run(self) -> int:
+        for raw in self._stdin:
+            line = raw.strip()
+            if not line:
+                continue
+            try:
+                msg = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if not isinstance(msg, dict):
+                continue
+
+            reply, post = self._dispatcher.handle(msg.get("method"), msg.get("id"), msg.get("params") or {})
+            if reply is not None:
+                self._write(reply)
+            if post is not None:
+                post()  # start streaming only after the ack is on the wire
+            if self._dispatcher.stopped:
+                break
+
+        self._dispatcher.join_streams()
+        return 0
+
+
+def run(plugin: BowirePlugin, *, stdin: TextIO | None = None, stdout: TextIO | None = None) -> int:
+    """Run ``plugin`` against the JSON-RPC-over-stdio contract until the
+    host sends ``shutdown`` (or stdin closes). Blocks; returns 0.
+
+    For the HTTP/SSE transport use :func:`bowire_plugin.run_http`.
+    """
+    return _StdioRuntime(plugin, stdin or sys.stdin, stdout or sys.stdout).run()

bowire_plugin/_settings.py

@@ -0,0 +1,203 @@
+# Copyright 2026 Küstenlogik
+# SPDX-License-Identifier: Apache-2.0
+"""The setting values the host sends with each call (Kuestenlogik/Bowire#693).
+
+A plugin declares its settings once, in :meth:`BowirePlugin.settings`; the
+host renders them in its Settings dialog and, on every ``discover`` /
+``invoke`` / ``invokeStream``, puts the values somebody actually set in a
+``settings`` object on the params. This module is the other half: what a
+plugin reads those values through.
+
+Three properties of the wire shape the API:
+
+- **Per call, not per process.** The values travel with each request, so a
+  changed setting takes effect on the next call without a restart. The
+  runtime builds a fresh :class:`Settings` for every call.
+- **Strings, whatever the declared type.** The dialog sends what a form
+  control produced; the plugin parses what it declared. The typed accessors
+  do that parse, with the same rules the host's own .NET accessors use.
+- **Only keys that are set.** An absent key means "use the default you
+  declared" — so the accessors fall back to the declared ``default_value``,
+  and a plugin whose settings nobody touched sees an empty mapping.
+"""
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from typing import Any, TypeVar
+
+from ._models import PluginSetting
+
+_T = TypeVar("_T")
+
+# ASCII digits only: Python's int()/float() also accept other Unicode digits,
+# underscores, "nan" and "inf", none of which a form control produces and none
+# of which the host's invariant-culture parse accepts.
+_INT = re.compile(r"[+-]?[0-9]+", re.ASCII)
+_FLOAT = re.compile(r"[+-]?(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?", re.ASCII)
+
+
+class _Unset:
+    """Marks "no explicit default given" — ``None`` is a legal default."""
+
+    def __repr__(self) -> str:
+        return "<declared default>"
+
+
+_UNSET = _Unset()
+
+
+def _parse_bool(text: str) -> bool | None:
+    t = text.strip().lower()
+    if t == "true":
+        return True
+    if t == "false":
+        return False
+    return None
+
+
+def _parse_int(text: str) -> int | None:
+    t = text.strip()
+    return int(t) if _INT.fullmatch(t) else None
+
+
+def _parse_float(text: str) -> float | None:
+    t = text.strip()
+    if not _FLOAT.fullmatch(t):
+        return None
+    value = float(t)
+    return value if math.isfinite(value) else None
+
+
+# The declared default is any JSON value the plugin wrote, so it is coerced
+# rather than parsed: ``default_value=5`` for a number setting is an int, not
+# the string "5". A bool is never taken as a number, although Python's bool
+# is an int — ``True`` as a probe window is a mistake, not ``1``.
+
+def _coerce_str(value: Any) -> str | None:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    return None
+
+
+def _coerce_bool(value: Any) -> bool | None:
+    if isinstance(value, bool):
+        return value
+    return _parse_bool(value) if isinstance(value, str) else None
+
+
+def _coerce_int(value: Any) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value) if value.is_integer() else None
+    return _parse_int(value) if isinstance(value, str) else None
+
+
+def _coerce_float(value: Any) -> float | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    return _parse_float(value) if isinstance(value, str) else None
+
+
+class Settings(Mapping[str, str]):
+    """The values set for this plugin's declared settings, for one call.
+
+    A read-only mapping of the raw strings the host sent — ``settings["key"]``,
+    ``"key" in settings``, ``settings.get("key")`` — plus typed accessors
+    that parse the string and fall back to the default the plugin declared::
+
+        def invoke(self, server_url, service, method, json_messages,
+                   show_internal, metadata, settings):
+            window = settings.get_float("probeWindow")   # 5.0 until somebody sets it
+            verbose = settings.get_bool("verbose")
+
+    Each accessor resolves in this order:
+
+    1. the value the host sent, when it parses as the requested type;
+    2. ``default``, when the caller passed one;
+    3. the ``default_value`` declared for that key in
+       :meth:`BowirePlugin.settings`;
+    4. otherwise :class:`KeyError` — the key has no value and nothing to fall
+       back to, which is a bug in the plugin rather than in its input.
+
+    A value that does not parse falls back exactly like an absent one, which
+    is what the host's .NET accessors do: an operator's typo in a probe
+    window degrades to the default instead of failing every discovery.
+    """
+
+    def __init__(
+        self,
+        values: Mapping[str, Any] | None = None,
+        declared: Iterable[PluginSetting] = (),
+    ) -> None:
+        # Strings on the wire; a number or bool is tolerated the way the host
+        # tolerates one in a hand-edited settings file. Anything else has no
+        # text form and is dropped rather than guessed at.
+        self._values: dict[str, str] = {}
+        for key, value in (values or {}).items():
+            text = _coerce_str(value)
+            if isinstance(key, str) and text is not None:
+                self._values[key] = text
+        self._defaults: dict[str, Any] = {s.key: s.default_value for s in declared}
+
+    def __getitem__(self, key: str) -> str:
+        return self._values[key]
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._values)
+
+    def __len__(self) -> int:
+        return len(self._values)
+
+    def __repr__(self) -> str:
+        return f"Settings({self._values!r})"
+
+    def get_str(self, key: str, default: str | _Unset = _UNSET) -> str:
+        """The value as text. An empty string is a value someone set, not an
+        absent one."""
+        return self._resolve(key, _coerce_str, default, "a string")
+
+    def get_bool(self, key: str, default: bool | _Unset = _UNSET) -> bool:
+        """The value as a flag: ``true`` / ``false``, case-insensitive."""
+        return self._resolve(key, _coerce_bool, default, "a bool")
+
+    def get_int(self, key: str, default: int | _Unset = _UNSET) -> int:
+        """The value as a whole number (ASCII digits, optional sign)."""
+        return self._resolve(key, _coerce_int, default, "an int")
+
+    def get_float(self, key: str, default: float | _Unset = _UNSET) -> float:
+        """The value as a finite number, decimal point and exponent allowed."""
+        return self._resolve(key, _coerce_float, default, "a float")
+
+    def _resolve(
+        self,
+        key: str,
+        convert: Callable[[Any], _T | None],
+        default: _T | _Unset,
+        kind: str,
+    ) -> _T:
+        raw = self._values.get(key)
+        if raw is not None:
+            parsed = convert(raw)
+            if parsed is not None:
+                return parsed
+        if not isinstance(default, _Unset):
+            return default
+        if key in self._defaults:
+            declared = convert(self._defaults[key])
+            if declared is not None:
+                return declared
+        raise KeyError(
+            f"setting '{key}' has no value that reads as {kind} and declares no default "
+            f"that does; declare one in settings() or pass default="
+        )