feat(iroh): integrate Python clients and workers

Author: rustyconover

docs/how-to/iroh.md

@@ -0,0 +1,91 @@
+# Serve and call a worker over Iroh
+
+VGI supports two authenticated Iroh endpoint forms:
+
+- `iroh://<endpoint-id>` keeps stream state on one connection.
+- `httpi://<endpoint-id>[/prefix]` preserves VGI's stateless HTTP exchanges,
+  continuation tokens, request/response budgets, authentication headers, and
+  externalized batches.
+
+Install the optional native client binding:
+
+```console
+pip install 'vgi-python[iroh]'
+```
+
+## Start a raw upstream
+
+The language-neutral `vgi-iroh-bridge` owns the public Iroh endpoint. The
+Python process binds only loopback and requires the bridge's PROXY-v2 identity
+preamble:
+
+```console
+vgi-serve my_worker.py \
+  --iroh-raw-upstream 127.0.0.1:9400 \
+  --iroh-issuer production
+```
+
+In another process:
+
+```console
+vgi-iroh-bridge \
+  --secret-key-file /run/secrets/vgi-iroh-key \
+  --raw-upstream tcp://127.0.0.1:9400
+```
+
+The bridge prints its EndpointId as the first stdout line. Development may use
+`--ephemeral`; a production endpoint must use a persistent secret key.
+The raw Iroh listener also enables standard RPC method description so
+standalone clients in other VGI languages can bootstrap directly.
+
+## Start an HTTP upstream
+
+HTTP-over-Iroh is the preferred mode for horizontally scaled workers:
+
+```console
+vgi-serve my_worker.py \
+  --http --host 127.0.0.1 --port 9401 \
+  --iroh-issuer production
+
+vgi-iroh-bridge \
+  --secret-key-file /run/secrets/vgi-iroh-key \
+  --http-upstream http://127.0.0.1:9401
+```
+
+`--iroh-issuer` makes the worker trust exactly `127.0.0.1` by default and
+promotes the bridge-verified EndpointId to `CallContext.auth`. Use repeated
+`--iroh-trusted-proxy <exact-ip>` when the immediate bridge address differs.
+Use `--iroh-observe` to expose evidence without authenticating from it.
+
+Never expose the bridge-facing listener as a general public HTTP or TCP
+listener. If another proxy sits between the bridge and worker, isolate that
+route, clear client-supplied `VGI-Forwarded-Iroh-Endpoint` fields on every other
+route, and configure the worker to trust only the intermediary's exact address.
+
+## Connect
+
+The same high-level client accepts both endpoint schemes:
+
+```python
+from vgi.client import Client
+
+with Client.from_iroh("iroh://<endpoint-id>") as client:
+    print(client.catalogs())
+
+with Client.from_iroh("httpi://<endpoint-id>/vgi") as client:
+    print(client.catalogs())
+```
+
+For a private relay:
+
+```python
+client = Client.from_iroh(
+    "httpi://<endpoint-id>/vgi",
+    relay_urls=["https://relay.example.com"],
+    remote_relay_url="https://relay.example.com",
+)
+```
+
+The local relay set and the remote relay hint are distinct. `no_relay=True`
+disables relays and requires a working direct path; it never falls back to the
+public relay network.

mkdocs.yml

@@ -126,6 +126,7 @@ nav:
     - Persist state across workers: how-to/state-storage.md
     - Serve over HTTP with auth: how-to/http-auth.md
     - Connect through a Tailnet: how-to/tailnet.md
+    - Serve and connect over Iroh: how-to/iroh.md
     - Integrate with the optimizer: how-to/pushdown-and-statistics.md
     - Function Metadata: metadata.md
     - CLI: cli.md

pyproject.toml

@@ -52,6 +52,7 @@ dependencies = [
 haybarn = ["haybarn>=1.5.5rc1"]
 duckdb = ["duckdb>=1.5.3"]
 http = ["vgi-rpc[http]"]
+iroh = ["vgi-rpc[iroh]"]
 # transport="launch": vgi_rpc.launcher imports filelock unconditionally at
 # module level, which lives behind vgi-rpc's own `cli` extra (alongside
 # typer, already a core dependency here, and httpx2, ditto) rather than in

tests/client/test_iroh_client.py

@@ -0,0 +1,66 @@
+"""High-level VGI client coverage for native Iroh endpoint routing."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any
+
+import pytest
+
+from vgi.client import Client
+
+ENDPOINT_ID = "01" * 32
+
+
+def test_from_iroh_selects_raw_and_http_semantics() -> None:
+    """The URI scheme selects stateful or HTTP continuation behavior."""
+    raw = Client.from_iroh(f"iroh://{ENDPOINT_ID}")
+    http = Client.from_iroh(f"httpi://{ENDPOINT_ID}/vgi")
+
+    assert raw._transport == "iroh"
+    assert not raw.supports_resumable_scan
+    assert http._transport == "httpi"
+    assert http.supports_resumable_scan
+    assert http._base_url == f"http://{ENDPOINT_ID}"
+    assert http._http_prefix == "/vgi"
+
+
+@pytest.mark.parametrize(
+    "endpoint",
+    [
+        f"https://{ENDPOINT_ID}",
+        f"iroh://{ENDPOINT_ID}/vgi",
+        f"httpi://{ENDPOINT_ID}/../vgi",
+    ],
+)
+def test_from_iroh_rejects_noncanonical_endpoints(endpoint: str) -> None:
+    """Non-Iroh and non-canonical endpoint strings fail before any I/O."""
+    with pytest.raises(ValueError):
+        Client.from_iroh(endpoint)
+
+
+def test_raw_iroh_connection_forwards_native_options(monkeypatch: pytest.MonkeyPatch) -> None:
+    """High-level options reach the official native RPC connector unchanged."""
+    captured: dict[str, Any] = {}
+    proxy = object()
+
+    @contextmanager
+    def fake_connect(protocol: Any, endpoint: str, **options: Any):  # type: ignore[no-untyped-def]
+        captured.update(protocol=protocol, endpoint=endpoint, **options)
+        yield proxy
+
+    monkeypatch.setattr("vgi_rpc.iroh.iroh_connect", fake_connect)
+    client = Client.from_iroh(
+        f"iroh://{ENDPOINT_ID}",
+        relay_urls=["https://relay.example"],
+        remote_relay_url="https://relay.example",
+        direct_addresses=["127.0.0.1:4433"],
+    )
+
+    connection = client._spawn_worker(3)
+    assert connection.proxy is proxy
+    assert captured["endpoint"] == f"iroh://{ENDPOINT_ID}"
+    assert captured["relay_urls"] == ("https://relay.example",)
+    assert captured["remote_relay_url"] == "https://relay.example"
+    assert captured["direct_addresses"] == ("127.0.0.1:4433",)
+    client._stop_worker(connection)

tests/test_serve.py

@@ -253,6 +253,17 @@ def test_returns_falcon_app(self) -> None:
         app = create_app(_SingleWorker)
         assert isinstance(app, falcon.App)
 
+    def test_accepts_trusted_iroh_bridge_identity(self) -> None:
+        """Iroh HTTP identity no longer requires a hand-built WSGI app."""
+        import falcon
+
+        app = create_app(
+            _SingleWorker,
+            iroh_bridge_issuer="test-mesh",
+            iroh_trusted_proxy_addresses=("127.0.0.1",),
+        )
+        assert isinstance(app, falcon.App)
+
     def test_custom_prefix(self) -> None:
         """Custom prefix is used in the app."""
         app = create_app(_SingleWorker, prefix="/api")

uv.lock

@@ -114,7 +114,9 @@ class CatalogClientMixin:
 
     # Type hints for attributes expected from Client
     server_path: str | Sequence[str]
-    _transport: Literal["subprocess", "http", "tcp", "launch"]
+    _transport: Literal["subprocess", "http", "tcp", "iroh", "httpi", "launch"]
+    _iroh_endpoint: str | None
+    _iroh_options: dict[str, Any]
     _base_url: str | None
     _tcp_host: str | None
     _tcp_port: int | None
@@ -165,16 +167,38 @@ def _catalog_connect(self) -> Iterator[VgiProtocol]:
         """
         try:
             transport = getattr(self, "_transport", "subprocess")
-            if transport == "http":
+            if transport in ("http", "httpi"):
                 from vgi_rpc.http import http_connect
 
                 httpx_client = self._get_or_create_httpx_client()
-                with http_connect(
+                if transport == "httpi":
+                    connection = http_connect(
+                        VgiProtocol,  # type: ignore[type-abstract]
+                        base_url=self._base_url,
+                        client=httpx_client,
+                        prefix=getattr(self, "_http_prefix", ""),
+                        external_location=getattr(self, "_external_location", None),
+                        accepted_max_response_bytes=self._accepted_max_response_bytes,
+                    )
+                else:
+                    connection = http_connect(
+                        VgiProtocol,  # type: ignore[type-abstract]
+                        base_url=self._base_url,
+                        client=httpx_client,
+                        external_location=getattr(self, "_external_location", None),
+                        accepted_max_response_bytes=self._accepted_max_response_bytes,
+                    )
+                with connection as proxy:
+                    yield proxy
+            elif transport == "iroh":
+                from vgi_rpc.iroh import iroh_connect
+
+                assert self._iroh_endpoint is not None
+                with iroh_connect(
                     VgiProtocol,  # type: ignore[type-abstract]
-                    base_url=self._base_url,
-                    client=httpx_client,
+                    self._iroh_endpoint,
                     external_location=getattr(self, "_external_location", None),
-                    accepted_max_response_bytes=self._accepted_max_response_bytes,
+                    **self._iroh_options,
                 ) as proxy:
                     yield proxy
             elif transport == "tcp":