bowire-plugin 0.3.0__tar.gz → 0.4.0__tar.gz

{bowire_plugin-0.3.0 → bowire_plugin-0.4.0}/.github/workflows/ci.yml

@@ -44,14 +44,19 @@ jobs:
   # there is the one that runs the plugin. The script then starts the
   # workbench, sets the example's settings through the Settings dialog's own
   # endpoint and checks the next invoke and stream use them (#4).
+  #
+  # Both transports (#8): over stdio the host spawns the sidecar; over http
+  # the script starts it on its own, installs a manifest that points at it,
+  # runs the same checks, and stops it while the host is still connected.
   e2e:
-    name: e2e against Bowire (${{ matrix.os }})
+    name: e2e against Bowire (${{ matrix.os }}, ${{ matrix.transport }})
     runs-on: ${{ matrix.os }}
     timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
+        transport: [stdio, http]
     defaults:
       run:
         shell: bash
@@ -79,7 +84,9 @@ jobs:
         run: dotnet tool install Kuestenlogik.Bowire.Tool --tool-path "$RUNNER_TEMP/bowire-tool"
 
       - name: Install the example, discover, and round-trip its settings
-        run: python scripts/e2e.py --bowire "$RUNNER_TEMP/bowire-tool/bowire" --work "$RUNNER_TEMP/e2e"
+        run: >-
+          python scripts/e2e.py --transport ${{ matrix.transport }}
+          --bowire "$RUNNER_TEMP/bowire-tool/bowire" --work "$RUNNER_TEMP/e2e"
 
   gate:
     name: gate

{bowire_plugin-0.3.0 → bowire_plugin-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bowire-plugin
-Version: 0.3.0
+Version: 0.4.0
 Summary: Write a Bowire protocol plugin in Python — JSON-RPC sidecar SDK (stdio + HTTP/SSE).
 Project-URL: Homepage, https://bowire.io/
 Project-URL: Repository, https://github.com/Kuestenlogik/Bowire.Sdk.Python
@@ -439,6 +439,21 @@ notifications (`$/stream/data`, …). Point the manifest at it with
 | Best for | local plugin shipped as a zip | hosted / remote / shared by many hosts |
 | Deps | none | none (stdlib `http.server`) |
 
+An http sidecar outlives the hosts that use it. Every connected host gets
+every notification on its own SSE stream. A host's `shutdown` is answered,
+and the server keeps serving. `run_http` stops on SIGTERM (what a container
+manager sends) or Ctrl-C, ends the SSE streams hosts hold open, and returns
+0. Pass `port=0` and `on_listening=` to let the OS pick a free port and
+learn which one it picked:
+
+```python
+run_http(MyPlugin(), port=0, on_listening=lambda port: print(f"listening on {port}"))
+```
+
+The echo example runs this way with `python echo_plugin.py --http
+127.0.0.1:0`. `scripts/e2e.py --transport http` drives it through a real
+host, and CI runs both transports.
+
 ## API surface
 
 | Override | When it's called | Return |

{bowire_plugin-0.3.0 → bowire_plugin-0.4.0}/README.md

@@ -213,6 +213,21 @@ notifications (`$/stream/data`, …). Point the manifest at it with
 | Best for | local plugin shipped as a zip | hosted / remote / shared by many hosts |
 | Deps | none | none (stdlib `http.server`) |
 
+An http sidecar outlives the hosts that use it. Every connected host gets
+every notification on its own SSE stream. A host's `shutdown` is answered,
+and the server keeps serving. `run_http` stops on SIGTERM (what a container
+manager sends) or Ctrl-C, ends the SSE streams hosts hold open, and returns
+0. Pass `port=0` and `on_listening=` to let the OS pick a free port and
+learn which one it picked:
+
+```python
+run_http(MyPlugin(), port=0, on_listening=lambda port: print(f"listening on {port}"))
+```
+
+The echo example runs this way with `python echo_plugin.py --http
+127.0.0.1:0`. `scripts/e2e.py --transport http` drives it through a real
+host, and CI runs both transports.
+
 ## API surface
 
 | Override | When it's called | Return |

{bowire_plugin-0.3.0 → bowire_plugin-0.4.0}/examples/echo/echo_plugin.py

@@ -14,6 +14,11 @@ uses it — no restart.
 Run it standalone for a smoke test:
     echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python echo_plugin.py
 
+Or serve it over HTTP/SSE, on its own, for a manifest that says
+``"transport": "http"`` and points ``"url"`` at it (port 0 lets the OS pick;
+the line printed once it listens says which):
+    python echo_plugin.py --http 127.0.0.1:0
+
 Or package echo_plugin.py + sidecar.json into a zip and install:
     bowire plugin install --file echo-sidecar.zip
     bowire --url echo://demo
@@ -24,6 +29,7 @@ bit — it is a module the interpreter runs, on every platform alike.
 """
 from __future__ import annotations
 
+import sys
 from collections.abc import Iterator
 
 from bowire_plugin import (
@@ -37,6 +43,7 @@ from bowire_plugin import (
     SettingOption,
     Settings,
     run,
+    run_http,
 )
 
 
@@ -140,5 +147,20 @@ class EchoPlugin(BowirePlugin):
             yield f'{{"tick":{i}}}'
 
 
+def _main(argv: list[str]) -> int:
+    if not argv:
+        return run(EchoPlugin())
+    if len(argv) == 2 and argv[0] == "--http":
+        host, _, port = argv[1].rpartition(":")
+        return run_http(
+            EchoPlugin(),
+            host=host or "127.0.0.1",
+            port=int(port),
+            on_listening=lambda bound: print(f"listening on http://{host}:{bound}/", flush=True),
+        )
+    print("usage: echo_plugin.py [--http <host:port>]", file=sys.stderr)
+    return 2
+
+
 if __name__ == "__main__":
-    run(EchoPlugin())
+    sys.exit(_main(sys.argv[1:]))

{bowire_plugin-0.3.0 → bowire_plugin-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bowire-plugin"
-version = "0.3.0"
+version = "0.4.0"
 description = "Write a Bowire protocol plugin in Python — JSON-RPC sidecar SDK (stdio + HTTP/SSE)."
 readme = "README.md"
 requires-python = ">=3.10"

{bowire_plugin-0.3.0 → bowire_plugin-0.4.0}/scripts/e2e.py

@@ -21,17 +21,25 @@ It is Python rather than shell so the same steps run on Linux and Windows:
 the manifest names its interpreter, and a manifest that only works on one
 platform is the failure this exists to catch.
 
-    python scripts/e2e.py --bowire <path-to-bowire> --work <empty-temp-dir>
+    python scripts/e2e.py --bowire <path-to-bowire> --work <empty-temp-dir> [--transport http]
 
 The interpreter the host spawns is whatever ``python`` the caller's ``PATH``
 resolves — the SDK has to be installed there, the way a plugin author
 installs it.
+
+With ``--transport http`` (#8) the host does not spawn the sidecar: this
+script starts the example in HTTP mode on a port the OS picks, installs a zip
+whose manifest says ``"transport": "http"`` and points ``"url"`` at it, and
+runs the same checks. The sidecar is the script's to stop, not the host's;
+it is stopped while the host is still connected, and has to exit cleanly.
 """
 from __future__ import annotations
 
 import argparse
 import json
+import os
 import re
+import signal
 import subprocess
 import sys
 import threading
@@ -48,6 +56,7 @@ _EXAMPLE = _REPO / "examples" / "echo"
 _PLUGIN_FILES = ("sidecar.json", "echo_plugin.py")
 _SERVER_URL = "echo@http://localhost:1"
 _BANNER = re.compile(r"Bowire is running at:\s+(\S+)")
+_LISTENING = re.compile(r"listening on (http://\S+)")
 
 # Loopback only; a proxy from the runner's environment has no business here.
 _HTTP = urllib.request.build_opener(urllib.request.ProxyHandler({}))
@@ -64,6 +73,52 @@ def _package(work: Path) -> Path:
     return archive
 
 
+def _start_http_sidecar() -> tuple[subprocess.Popen[str], str]:
+    """Start the example as an http sidecar and return it with its URL.
+
+    The example prints its URL once the socket accepts connections, so
+    reading its stdout up to that line is the readiness handshake, and
+    ``:0`` lets the OS pick the port.
+    """
+    cmd = [sys.executable, str(_EXAMPLE / "echo_plugin.py"), "--http", "127.0.0.1:0"]
+    print("$ " + " ".join(cmd), flush=True)
+    proc = subprocess.Popen(cmd, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
+                            stderr=subprocess.STDOUT, text=True,
+                            encoding="utf-8", errors="replace")
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        sys.stdout.write(line)
+        match = _LISTENING.search(line)
+        if match:
+            threading.Thread(target=_drain, args=(proc.stdout,), daemon=True).start()
+            return proc, match.group(1)
+    raise SystemExit(f"the http sidecar exited ({proc.wait()}) before it was listening")
+
+
+def _package_http(work: Path, url: str) -> Path:
+    """A zip with nothing but a manifest: an http sidecar ships no code to
+    the host, only where to reach it."""
+    stdio = json.loads((_EXAMPLE / "sidecar.json").read_text(encoding="utf-8"))
+    manifest = {k: v for k, v in stdio.items() if k not in ("executable", "args", "envPrefix")}
+    manifest.update(packageId=stdio["packageId"] + ".Http", transport="http", url=url)
+    archive = work / "echo-python-http.zip"
+    with zipfile.ZipFile(archive, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("sidecar.json", json.dumps(manifest, indent=2))
+    print(f"packaged {archive}: sidecar.json -> {url}", flush=True)
+    return archive
+
+
+def _stop_http_sidecar(proc: subprocess.Popen[str]) -> None:
+    """Stop the sidecar the way a container manager does, and require a
+    clean exit. On Windows there is no such signal a process can handle,
+    so there the exit is only awaited."""
+    proc.send_signal(signal.SIGTERM)
+    code = proc.wait()
+    if os.name != "nt" and code != 0:
+        raise SystemExit(f"the http sidecar did not stop cleanly: exit {code}")
+    print(f"http sidecar: stopped with the host still connected (exit {code})", flush=True)
+
+
 def _bowire(bowire: str, plugin_dir: Path, *args: str) -> str:
     cmd = [bowire, "--plugin-dir", str(plugin_dir), *args]
     print("$ " + " ".join(cmd), flush=True)
@@ -158,7 +213,8 @@ def _manual_entry(base: str) -> None:
     print("manual entry: the declared form is served", flush=True)
 
 
-def _settings_round_trip(bowire: str, plugin_dir: Path, storage: Path) -> None:
+def _settings_round_trip(bowire: str, plugin_dir: Path, storage: Path,
+                         sidecar: subprocess.Popen[str] | None) -> None:
     storage.mkdir(parents=True, exist_ok=True)
     proc, base = _serve(bowire, plugin_dir)
     try:
@@ -203,6 +259,8 @@ def _settings_round_trip(bowire: str, plugin_dir: Path, storage: Path) -> None:
             raise SystemExit("invokeStream did not see the settings set for it")
 
         _manual_entry(base)
+        if sidecar is not None:
+            _stop_http_sidecar(sidecar)
     finally:
         proc.terminate()
         proc.wait()
@@ -213,23 +271,35 @@ def main() -> int:
     parser.add_argument("--bowire", required=True, help="the bowire executable to drive")
     parser.add_argument("--work", required=True, type=Path,
                         help="an empty directory for the zip and the plugin tree")
+    parser.add_argument("--transport", choices=("stdio", "http"), default="stdio",
+                        help="spawned by the host (stdio) or running on its own (http)")
     opts = parser.parse_args()
 
     work: Path = opts.work.resolve()
     work.mkdir(parents=True, exist_ok=True)
     plugin_dir = work / "plugins"
 
-    archive = _package(work)
-    _bowire(opts.bowire, plugin_dir, "plugin", "install", "--file", str(archive))
-    _bowire(opts.bowire, plugin_dir, "plugin", "list", "--verbose")
-
-    out = _bowire(opts.bowire, plugin_dir, "discover", "--url", "echo@http://localhost:1")
-    if "Echo" not in out:
-        raise SystemExit("discover succeeded but listed no Echo service")
-
-    _settings_round_trip(opts.bowire, plugin_dir, work / "workspace")
+    sidecar: subprocess.Popen[str] | None = None
+    try:
+        if opts.transport == "http":
+            sidecar, url = _start_http_sidecar()
+            archive = _package_http(work, url)
+        else:
+            archive = _package(work)
+        _bowire(opts.bowire, plugin_dir, "plugin", "install", "--file", str(archive))
+        _bowire(opts.bowire, plugin_dir, "plugin", "list", "--verbose")
+
+        out = _bowire(opts.bowire, plugin_dir, "discover", "--url", "echo@http://localhost:1")
+        if "Echo" not in out:
+            raise SystemExit("discover succeeded but listed no Echo service")
+
+        _settings_round_trip(opts.bowire, plugin_dir, work / "workspace", sidecar)
+    finally:
+        if sidecar is not None and sidecar.poll() is None:
+            sidecar.kill()
+            sidecar.wait()
 
-    print("e2e: ok", flush=True)
+    print(f"e2e: ok ({opts.transport})", flush=True)
     return 0
 
 

{bowire_plugin-0.3.0 → bowire_plugin-0.4.0}/src/bowire_plugin/__init__.py

@@ -46,7 +46,7 @@ from ._plugin import BowirePlugin
 from ._runtime import SIDECAR_PROTOCOL_VERSION, run
 from ._settings import Settings
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "SIDECAR_PROTOCOL_VERSION",

bowire_plugin-0.4.0/src/bowire_plugin/_http.py

@@ -0,0 +1,211 @@
+# 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`` …) stream back over a long-lived SSE ``GET`` on the
+same path. Bowire's host wires to this with a ``"transport": "http"``
+sidecar manifest pointing at the URL.
+
+Unlike a stdio sidecar, an http one is not its host's: it runs on its own,
+any number of hosts connect to it over its lifetime, and each holds an SSE
+stream open while it uses the sidecar. So every subscriber gets every
+notification, a host's ``shutdown`` is acknowledged without stopping the
+server, and the server stops when its process is told to (SIGTERM, Ctrl-C)
+or :meth:`_HttpServer.shutdown` is called.
+
+Pure stdlib (``http.server``) — no extra dependencies.
+"""
+from __future__ import annotations
+
+import json
+import queue
+import signal
+import sys
+import threading
+from collections.abc import Callable
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+from ._plugin import BowirePlugin
+from ._runtime import _Dispatcher
+
+# Sentinel pushed onto every subscriber's queue to end its SSE stream.
+_STOP = object()
+
+
+class _Subscribers:
+    """The SSE streams open right now, one queue each.
+
+    One shared queue used to feed them all, so subscribers took turns: a
+    host that had gone away could still take an event off the queue, fail
+    to write it and drop it, and the host that was waiting for it never got
+    it. Each subscriber now has a queue of its own, and a notification goes
+    into all of them.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._queues: set[queue.Queue[Any]] = set()
+        self._closed = False
+
+    def add(self) -> queue.Queue[Any]:
+        q: queue.Queue[Any] = queue.Queue()
+        with self._lock:
+            if self._closed:
+                q.put(_STOP)
+            else:
+                self._queues.add(q)
+        return q
+
+    def remove(self, q: queue.Queue[Any]) -> None:
+        with self._lock:
+            self._queues.discard(q)
+
+    def emit(self, event: Any) -> None:
+        with self._lock:
+            for q in self._queues:
+                q.put(event)
+
+    def close(self) -> None:
+        with self._lock:
+            self._closed = True
+            for q in self._queues:
+                q.put(_STOP)
+
+
+class _Server(ThreadingHTTPServer):
+    """A host that goes away resets its keep-alive connections; that is a
+    host leaving, not an error, so it is not printed as a traceback."""
+
+    def handle_error(self, request: Any, client_address: Any) -> None:
+        if isinstance(sys.exc_info()[1], (ConnectionResetError, ConnectionAbortedError, BrokenPipeError)):
+            return
+        super().handle_error(request, client_address)
+
+
+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:
+        subscribers = _Subscribers()
+        dispatcher = _Dispatcher(plugin, subscribers.emit)
+        self._subscribers = subscribers
+        self._dispatcher = dispatcher
+
+        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
+                # A host's `shutdown` is the host leaving, not the sidecar
+                # being told to stop: it is answered, and the server keeps
+                # serving the hosts still connected and the ones to come.
+                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
+
+            def do_GET(self) -> None:
+                # Subscribed before the headers go out, so a host that has
+                # them can rely on getting every notification after.
+                q = subscribers.add()
+                try:
+                    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 True:
+                        evt = q.get()
+                        if evt is _STOP:
+                            break
+                        payload = json.dumps(evt, separators=(",", ":"), ensure_ascii=False)
+                        self.wfile.write(f"data: {payload}\n\n".encode())
+                        self.wfile.flush()
+                except (BrokenPipeError, ConnectionResetError, ConnectionAbortedError):
+                    pass  # the host went away
+                finally:
+                    subscribers.remove(q)
+                    # The stream ends with this response; the connection is
+                    # not reused for another request.
+                    self.close_connection = True
+
+            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 = _Server((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._subscribers.close()
+            self._dispatcher.join_streams(timeout=2)
+            self._server.server_close()
+
+    def shutdown(self) -> None:
+        """Stop serving: end every open SSE stream, then let
+        :meth:`serve_forever` return. Safe from any thread but the one
+        running :meth:`serve_forever`."""
+        self._subscribers.close()
+        self._server.shutdown()
+
+
+def run_http(
+    plugin: BowirePlugin,
+    *,
+    host: str = "127.0.0.1",
+    port: int = 8770,
+    on_listening: Callable[[int], None] | None = None,
+) -> int:
+    """Serve ``plugin`` over HTTP/SSE on ``host:port`` until the process is
+    told to stop: SIGTERM (what a container manager sends) or Ctrl-C. Blocks;
+    returns 0 once it has stopped cleanly. A host's ``shutdown`` does not
+    stop it: an http sidecar outlives the hosts that connect to it.
+
+    ``on_listening`` is called with the bound port once the socket accepts
+    connections, before serving starts: with ``port=0`` the OS picks the
+    port, and this is how a caller learns which one.
+
+    Point a sidecar manifest at it:
+
+        { "transport": "http", "url": "http://127.0.0.1:8770/" }
+    """
+    server = _HttpServer(plugin, host, port)
+
+    # serve_forever runs on this thread, and shutdown() waits for it to
+    # return, so the handlers hand the stop to a thread of its own.
+    def stop(_signum: int, _frame: object) -> None:
+        threading.Thread(target=server.shutdown, daemon=True).start()
+
+    if threading.current_thread() is threading.main_thread():
+        signal.signal(signal.SIGTERM, stop)
+        signal.signal(signal.SIGINT, stop)
+
+    if on_listening is not None:
+        on_listening(server.port)
+    server.serve_forever()
+    return 0

{bowire_plugin-0.3.0 → bowire_plugin-0.4.0}/tests/test_http.py

@@ -107,6 +107,61 @@ def test_http_unknown_method_errors(server):
     assert out["error"]["code"] == -32601
 
 
-def test_http_shutdown_stops_serving(server):
+def test_a_hosts_shutdown_is_answered_and_the_server_keeps_serving(server):
+    # An http sidecar outlives its hosts: the shutdown a host sends when it
+    # lets go of the sidecar must not stop it for the next one.
     out = _post(server.port, {"jsonrpc": "2.0", "id": 6, "method": "shutdown", "params": {}})
     assert out["result"] is True
+    again = _post(server.port, {"jsonrpc": "2.0", "id": 7, "method": "ping", "params": {}})
+    assert again["result"] == "pong"
+
+
+def _stream_frames(sse) -> list[str]:
+    frames: list[str] = []
+    for raw in sse:
+        line = raw.decode().strip()
+        if not line.startswith("data:"):
+            continue
+        note = json.loads(line[5:].strip())
+        if note.get("method") == "$/stream/data":
+            frames.append(note["params"]["message"])
+        elif note.get("method") == "$/stream/end":
+            return frames
+    raise AssertionError(f"the stream ended before $/stream/end; got {frames}")
+
+
+def _invoke_stream(port: int, stream_id: str) -> None:
+    _post(port, {"jsonrpc": "2.0", "id": 8, "method": "invokeStream",
+                 "params": {"streamId": stream_id, "serverUrl": "httpfake://x",
+                            "service": "Echo", "method": "Echo/echo", "jsonMessages": [],
+                            "showInternalServices": False, "metadata": {}}})
+
+
+def test_every_subscriber_gets_every_frame(server):
+    # The subscribers used to share one queue and take turns: with two of
+    # them, each frame reached only one, so a host lost frames to a stream
+    # it was not reading - one left behind by a host that had gone.
+    first = urllib.request.urlopen(f"http://127.0.0.1:{server.port}/", timeout=5)
+    second = urllib.request.urlopen(f"http://127.0.0.1:{server.port}/", timeout=5)
+    try:
+        _invoke_stream(server.port, "s1")
+        expected = ['{"tick":1}', '{"tick":2}', '{"tick":3}']
+        assert _stream_frames(first) == expected
+        assert _stream_frames(second) == expected
+    finally:
+        first.close()
+        second.close()
+
+
+def test_stopping_ends_the_open_sse_streams():
+    srv = _HttpServer(_Fake(), host="127.0.0.1", port=0)
+    t = threading.Thread(target=srv.serve_forever, daemon=True)
+    t.start()
+    sse = urllib.request.urlopen(f"http://127.0.0.1:{srv.port}/", timeout=5)
+    try:
+        srv.shutdown()
+        assert sse.read() == b""  # the stream ended rather than hanging
+        t.join()
+        assert not t.is_alive()
+    finally:
+        sse.close()

bowire_plugin-0.3.0/src/bowire_plugin/_http.py

@@ -1,127 +0,0 @@
-# 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