nodalwire 0.1.0__tar.gz

nodalwire-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nitipit Nontasuwan
+
+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.

nodalwire-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: nodalwire
+Version: 0.1.0
+Summary: A bounded native ZeroMQ byte relay for trusted local Python applications.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: cyclopts>=4.11.1,<5
+Requires-Dist: pyzmq>=27.1.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/keenlycode/nodalwire
+Project-URL: Issues, https://github.com/keenlycode/nodalwire/issues
+Description-Content-Type: text/markdown
+
+# NodalWire
+
+A local byte relay, designed for AI agents to use and maintain.
+
+- Usage: [tests/usage/](tests/usage/)
+- Python: [src/nodalwire/](src/nodalwire/)
+- Node.js: [src/nodalwire/client/node/](src/nodalwire/client/node/)

nodalwire-0.1.0/README.md

@@ -0,0 +1,7 @@
+# NodalWire
+
+A local byte relay, designed for AI agents to use and maintain.
+
+- Usage: [tests/usage/](tests/usage/)
+- Python: [src/nodalwire/](src/nodalwire/)
+- Node.js: [src/nodalwire/client/node/](src/nodalwire/client/node/)

nodalwire-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "nodalwire"
+version = "0.1.0"
+description = "A bounded native ZeroMQ byte relay for trusted local Python applications."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = [
+    "cyclopts>=4.11.1,<5",
+    "pyzmq>=27.1.0",
+]
+
+[project.urls]
+Repository = "https://github.com/keenlycode/nodalwire"
+Issues = "https://github.com/keenlycode/nodalwire/issues"
+
+[project.scripts]
+nodalwire = "nodalwire.cli:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3,<9.1",
+    "ruff>=0.8.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "nodalwire"
+source-exclude = ["**/__pycache__/**", "src/nodalwire/client/node"]
+wheel-exclude = ["nodalwire/client/node"]
+
+[tool.ruff]
+extend-exclude = ["src/nodalwire/client/node"]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--import-mode=importlib"]

nodalwire-0.1.0/src/nodalwire/__init__.py

@@ -0,0 +1,16 @@
+"""NodalWire: a central byte relay for trusted local Python applications."""
+
+from .client import Message, Node
+from .config import RelayConfig, load_config
+from .protocol import ReceiptTimeout, RelayError
+from .server import Relay
+
+__all__ = [
+    "Message",
+    "Node",
+    "ReceiptTimeout",
+    "Relay",
+    "RelayConfig",
+    "RelayError",
+    "load_config",
+]

nodalwire-0.1.0/src/nodalwire/__main__.py

@@ -0,0 +1,3 @@
+from .cli import app
+
+app()

nodalwire-0.1.0/src/nodalwire/cli.py

@@ -0,0 +1,47 @@
+"""Small foreground service; configuration is loaded once at startup."""
+
+import asyncio
+import signal
+from pathlib import Path
+
+from cyclopts import App
+
+from .config import RelayConfig, load_config
+from .server import Relay
+
+app = App(help="Run the loopback-only byte relay for trusted local applications.")
+
+
+async def _serve(config: RelayConfig) -> None:
+    relay = Relay(config)
+    endpoint = await relay.start()
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, stop.set)
+    runner = asyncio.create_task(relay.run())
+    waiter = asyncio.create_task(stop.wait())
+    print(endpoint, flush=True)
+    try:
+        completed, _ = await asyncio.wait([runner, waiter], return_when=asyncio.FIRST_COMPLETED)
+        if runner in completed:
+            await runner  # Surface a service failure, not a false successful shutdown.
+    finally:
+        runner.cancel()
+        waiter.cancel()
+        await asyncio.gather(runner, waiter, return_exceptions=True)
+        await relay.close()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            loop.remove_signal_handler(sig)
+
+
+@app.default
+def main(*, config: Path | None = None) -> None:
+    """Start the relay; prints the bound endpoint after native bind succeeds.
+
+    Parameters
+    ----------
+    config
+        Startup cooperative TOML policy. Default: open admission on loopback.
+    """
+    asyncio.run(_serve(load_config(config) if config is not None else RelayConfig()))

nodalwire-0.1.0/src/nodalwire/client/__init__.py

@@ -0,0 +1,5 @@
+"""Language-specific clients; Python exports remain available here."""
+
+from .python import Message, Node
+
+__all__ = ["Message", "Node"]

nodalwire-0.1.0/src/nodalwire/client/python/__init__.py

@@ -0,0 +1,5 @@
+"""Async Python byte client."""
+
+from .node import Message, Node
+
+__all__ = ["Message", "Node"]

nodalwire-0.1.0/src/nodalwire/client/python/node.py

@@ -0,0 +1,275 @@
+"""Async DEALER node with one bounded inbox and transport-owned receipt correlation."""
+
+import asyncio
+import secrets
+from dataclasses import dataclass
+
+import zmq
+import zmq.asyncio
+
+from ...config import local_endpoint
+from ...protocol import (
+    CLOSE,
+    DATA,
+    ERROR,
+    HEARTBEAT,
+    HELLO,
+    OK,
+    SEND,
+    VERSION,
+    ReceiptTimeout,
+    RelayError,
+    valid_name,
+)
+
+
+@dataclass(frozen=True)
+class Message:
+    sender: str
+    payload: bytes
+
+
+class Node:
+    """Connect by logical name; send bytes, receive sender+bytes, and close.
+
+    Native queues, inbox and outstanding requests are bounded. When the inbox is
+    full, reading pauses (including receipts); drain it concurrently with sending.
+    Socket queue acceptance is not application delivery or execution.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        endpoint: str,
+        *,
+        timeout: float = 5.0,
+        send_hwm: int = 64,
+        receive_hwm: int = 64,
+        inbox_size: int = 64,
+        max_pending: int = 128,
+    ) -> None:
+        if not valid_name(name):
+            raise ValueError("invalid logical node name")
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        for value in (send_hwm, receive_hwm, inbox_size, max_pending):
+            if type(value) is not int or value <= 0:
+                raise ValueError("queue limits must be positive integers")
+        endpoint = local_endpoint(endpoint)
+        self.name = name
+        self.endpoint = endpoint
+        self.timeout = timeout
+        self.max_pending = max_pending
+        self.context = zmq.asyncio.Context()
+        self.socket = self.context.socket(zmq.DEALER)
+        self.socket.setsockopt(zmq.LINGER, 0)
+        self.socket.setsockopt(zmq.IPV6, int(endpoint.startswith("tcp://[")))
+        self.socket.setsockopt(zmq.IDENTITY, secrets.token_bytes(16))
+        self.socket.setsockopt(zmq.IMMEDIATE, 1)
+        self.socket.setsockopt(zmq.SNDHWM, send_hwm)
+        self.socket.setsockopt(zmq.RCVHWM, receive_hwm)
+        self._inbox: asyncio.Queue[Message] = asyncio.Queue(maxsize=inbox_size)
+        self._pending: dict[bytes, tuple[bytes, asyncio.Future[tuple[bytes, ...]]]] = {}
+        self._receiver: asyncio.Task[None] | None = None
+        self._heartbeat: asyncio.Task[None] | None = None
+        self._token: bytes | None = None
+        self._max_payload = 0
+        self._closed = asyncio.Event()
+        self._cleanup_done = asyncio.Event()
+        self._cleanup_task: asyncio.Task[None] | None = None
+        self._closing = False
+        try:
+            self.socket.connect(endpoint)
+        except BaseException:
+            self.socket.close(linger=0)
+            self.context.term()
+            raise
+
+    @classmethod
+    async def connect(cls, name: str, endpoint: str = "tcp://127.0.0.1:5555", **options) -> "Node":
+        """Await admission; failure closes owned resources. No reconnect or replay."""
+        node = cls(name, endpoint, **options)
+        node._receiver = asyncio.create_task(node._read(), name=f"relay-inbox-{name}")
+        try:
+            token, lease, payload_limit = await node._request(
+                HELLO, name.encode("ascii"), initial=True
+            )
+            node._token = token
+            node._max_payload = int(payload_limit)
+            node.socket.setsockopt(zmq.MAXMSGSIZE, node._max_payload + 4096)
+            node._heartbeat = asyncio.create_task(
+                node._beat(float(lease) / 3), name=f"relay-heartbeat-{name}"
+            )
+            return node
+        except BaseException:
+            await node._cleanup()
+            raise
+
+    async def _request(
+        self,
+        command: bytes,
+        *frames: bytes,
+        initial: bool = False,
+        timeout: float | None = None,
+    ) -> tuple[bytes, ...]:
+        if self._closed.is_set():
+            raise RelayError("closed")
+        if len(self._pending) >= self.max_pending:
+            raise RelayError("pending_full")
+        request = secrets.token_hex(16).encode("ascii")
+        token = b"" if initial else self._token
+        assert token is not None
+        future = asyncio.get_running_loop().create_future()
+        self._pending[request] = (token, future)
+        body = [VERSION, command]
+        if not initial:
+            body.append(token)
+        body.extend([request, *frames])
+        try:
+            async with asyncio.timeout(self.timeout if timeout is None else timeout):
+                try:
+                    await self.socket.send_multipart(body, flags=0 if initial else zmq.DONTWAIT)
+                except zmq.Again as exc:
+                    raise RelayError("local_queue_full") from exc
+                return await future
+        except TimeoutError as exc:
+            raise ReceiptTimeout("routing receipt timed out; effect uncertain") from exc
+        finally:
+            self._pending.pop(request, None)
+            if not future.done():
+                future.cancel()
+            elif not future.cancelled():
+                future.exception()  # Consume a concurrent close/receiver failure.
+
+    async def _read(self) -> None:
+        try:
+            while True:
+                frames = await self.socket.recv_multipart()
+                if len(frames) < 4 or frames[0] != VERSION:
+                    continue
+                command, token = frames[1:3]
+                if command == DATA and len(frames) == 5 and token == self._token:
+                    sender = frames[3].decode("ascii")
+                    if valid_name(sender) and len(frames[4]) <= self._max_payload:
+                        await self._inbox.put(Message(sender, frames[4]))
+                    continue
+                request = frames[3]
+                pending = self._pending.get(request)
+                if pending is None or pending[0] != token or pending[1].done():
+                    continue
+                future = pending[1]
+                if command == OK:
+                    extra = tuple(frames[4:])
+                    if token == b"" and len(extra) == 3:
+                        # Install incarnation before any DATA already behind HELLO's reply.
+                        self._token = extra[0]
+                        self._max_payload = int(extra[2])
+                    future.set_result(extra)
+                elif command == ERROR and len(frames) == 5:
+                    future.set_exception(RelayError(frames[4].decode("ascii")))
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            self._closed.set()
+            self._fail_pending("connection_failed")
+
+    def _fail_pending(self, code: str) -> None:
+        for _, future in self._pending.values():
+            if not future.done():
+                future.set_exception(RelayError(code))
+
+    async def _beat(self, interval: float) -> None:
+        assert self._token is not None
+        while True:
+            await asyncio.sleep(interval)
+            try:
+                await self.socket.send_multipart(
+                    [VERSION, HEARTBEAT, self._token], flags=zmq.DONTWAIT
+                )
+            except zmq.Again:
+                pass  # No heartbeat backlog; lease may expire under local congestion.
+
+    async def send(self, destination: str, payload: bytes, *, timeout: float | None = None) -> None:
+        """Wait for Router queue acceptance or status (never remote execution).
+
+        Timeout, cancellation and interrupted lifecycle have uncertain effects.
+        """
+        if self._closing or self._closed.is_set():
+            raise RelayError("closed")
+        if not valid_name(destination):
+            raise ValueError("invalid destination name")
+        if not isinstance(payload, bytes):
+            raise TypeError("payload must be bytes")
+        if len(payload) > self._max_payload:
+            raise RelayError("payload_too_large")
+        await self._request(SEND, destination.encode("ascii"), payload, timeout=timeout)
+
+    async def receive(self) -> Message:
+        """Read the single inbox; queued data remains readable after close."""
+        if not self._inbox.empty():
+            return self._inbox.get_nowait()
+        if self._closed.is_set():
+            raise RelayError("closed")
+        message = asyncio.create_task(self._inbox.get())
+        closed = asyncio.create_task(self._closed.wait())
+        try:
+            await asyncio.wait([message, closed], return_when=asyncio.FIRST_COMPLETED)
+            if message.done():
+                return message.result()
+            raise RelayError("closed")
+        finally:
+            for task in (message, closed):
+                task.cancel()
+            await asyncio.gather(message, closed, return_exceptions=True)
+
+    async def _cleanup(self) -> None:
+        # Cleanup has independent ownership: cancellation of a close/connect caller
+        # must not interrupt joins or leave native resources and tasks behind.
+        if self._cleanup_task is None:
+            self._cleanup_task = asyncio.create_task(
+                self._dispose(), name=f"relay-close-{self.name}"
+            )
+        cancelled = False
+        while True:
+            try:
+                await asyncio.shield(self._cleanup_task)
+                break
+            except asyncio.CancelledError:
+                cancelled = True
+        if cancelled:
+            raise asyncio.CancelledError
+
+    async def _dispose(self) -> None:
+        self._closed.set()
+        self._fail_pending("closed")
+        for task in (self._heartbeat, self._receiver):
+            if task is not None:
+                task.cancel()
+        try:
+            await asyncio.gather(
+                *(task for task in (self._heartbeat, self._receiver) if task is not None),
+                return_exceptions=True,
+            )
+        finally:
+            # A repeated close can return only after this native cleanup boundary.
+            self.socket.close(linger=0)
+            self.context.term()
+            self._cleanup_done.set()
+
+    async def close(self, *, timeout: float | None = None) -> None:
+        """Attempt registration release, always clean up; failed receipt stays uncertain."""
+        if self._closing:
+            await self._cleanup_done.wait()
+            return
+        self._closing = True
+        try:
+            if self._token is not None and not self._closed.is_set():
+                await self._request(CLOSE, timeout=timeout)
+        finally:
+            await self._cleanup()
+
+    async def __aenter__(self) -> "Node":
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()

nodalwire-0.1.0/src/nodalwire/config.py

@@ -0,0 +1,121 @@
+"""Startup-only relay policy and native transport limits (TOML configuration)."""
+
+import ipaddress
+import tomllib
+from dataclasses import dataclass, field, fields
+from pathlib import Path
+
+from .protocol import valid_name
+
+
+def _name_list(names: object) -> bool:
+    return isinstance(names, (tuple, list)) and all(valid_name(name) for name in names)
+
+
+def local_endpoint(endpoint: str, *, bind: bool = False) -> str:
+    """Validate before allocating resources; normalize localhost without DNS.
+
+    Only literal loopback addresses (or localhost) are supported. A wildcard
+    port is allowed for binds, never connects; wildcard/nonlocal hosts are not.
+    """
+    if not isinstance(endpoint, str) or not endpoint.startswith("tcp://"):
+        raise ValueError("local relay endpoint must use tcp://")
+    host, separator, port = endpoint[6:].rpartition(":")
+    if not separator or not (
+        (bind and port == "*")
+        or (port.isascii() and port.isdecimal() and 1 <= int(port) <= 65535)
+    ):
+        raise ValueError("invalid TCP endpoint port")
+    if host == "localhost":
+        host = "127.0.0.1"
+    try:
+        address = ipaddress.ip_address(host[1:-1] if host.startswith("[") else host)
+    except ValueError as exc:
+        raise ValueError("endpoint must use a literal loopback address or localhost") from exc
+    if not address.is_loopback or "%" in host:
+        raise ValueError("endpoint must be loopback-only")
+    expected = f"[{address}]" if address.version == 6 else str(address)
+    if host != expected:
+        raise ValueError("invalid TCP loopback address syntax")
+    return f"tcp://{expected}:{port}"
+
+
+@dataclass(frozen=True)
+class RelayConfig:
+    endpoint: str = "tcp://127.0.0.1:5555"
+    lease_seconds: float = 10.0
+    send_hwm: int = 64
+    receive_hwm: int = 64
+    max_payload_bytes: int = 1_048_576
+    allowed_names: tuple[str, ...] | None = None
+    networks: dict[str, tuple[str, ...]] = field(default_factory=dict)
+    deny: tuple[tuple[str, str], ...] = ()
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "endpoint", local_endpoint(self.endpoint, bind=True))
+        if type(self.lease_seconds) not in (float, int) or not 0.1 <= self.lease_seconds <= 3600:
+            raise ValueError("lease_seconds must be between 0.1 and 3600")
+        for name in ("send_hwm", "receive_hwm", "max_payload_bytes"):
+            value = getattr(self, name)
+            if type(value) is not int or value <= 0:
+                raise ValueError(f"{name} must be a positive integer")
+        if self.allowed_names is not None and not _name_list(self.allowed_names):
+            raise ValueError("allowed_names must be an array of valid names")
+        if not isinstance(self.networks, dict):
+            raise ValueError("networks must map group names to member arrays")
+        for group, members in self.networks.items():
+            if not valid_name(group) or not _name_list(members):
+                raise ValueError("invalid network or member name array")
+        if not isinstance(self.deny, (tuple, list)):
+            raise ValueError("deny must be an array of directional rules")
+        for rule in self.deny:
+            if (
+                not isinstance(rule, (tuple, list))
+                or len(rule) != 2
+                or any(not self._valid_selector(selector) for selector in rule)
+            ):
+                raise ValueError("deny entries need two name, @network or * selectors")
+
+    def _valid_selector(self, selector: str) -> bool:
+        return isinstance(selector, str) and (
+            selector == "*"
+            or valid_name(selector)
+            or (selector.startswith("@") and selector[1:] in self.networks)
+        )
+
+    def _matches(self, selector: str, name: str) -> bool:
+        if selector == "*":
+            return True
+        if selector.startswith("@"):
+            return name in self.networks[selector[1:]]
+        return selector == name
+
+    def permits(self, source: str, destination: str) -> bool:
+        return not any(
+            self._matches(left, source) and self._matches(right, destination)
+            for left, right in self.deny
+        )
+
+
+def load_config(path: Path) -> RelayConfig:
+    """Load cooperative local policy once; obsolete/unknown options are errors."""
+    with path.open("rb") as source:
+        data = tomllib.load(source)
+    obsolete = {"curve", "allow_nonlocal"}.intersection(data)
+    if obsolete:
+        raise ValueError(
+            f"unsupported local-only configuration: {', '.join(sorted(obsolete))}; "
+            "security mode and nonlocal endpoints have been removed"
+        )
+    unknown = data.keys() - {item.name for item in fields(RelayConfig)}
+    if unknown:
+        raise ValueError(f"unknown relay configuration: {', '.join(sorted(unknown))}")
+    config = RelayConfig(**data)  # Validate arrays before converting; strings aren't arrays.
+    return RelayConfig(
+        **{
+            **data,
+            "allowed_names": None if config.allowed_names is None else tuple(config.allowed_names),
+            "networks": {name: tuple(members) for name, members in config.networks.items()},
+            "deny": tuple(tuple(rule) for rule in config.deny),
+        }
+    )

nodalwire-0.1.0/src/nodalwire/protocol.py

@@ -0,0 +1,33 @@
+"""Private wire vocabulary; application payloads remain opaque bytes."""
+
+import re
+
+VERSION = b"AR1"
+HELLO = b"HELLO"
+SEND = b"SEND"
+HEARTBEAT = b"HEARTBEAT"
+CLOSE = b"CLOSE"
+OK = b"OK"
+ERROR = b"ERROR"
+DATA = b"DATA"
+_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}\Z")
+
+
+def valid_name(name: str) -> bool:
+    return isinstance(name, str) and _NAME.fullmatch(name) is not None
+
+
+class RelayError(Exception):
+    """Relay status: Router rejection, local rejection or lifecycle interruption.
+
+    Lifecycle codes closed/connection_failed can interrupt an already-sent request;
+    they do not prove no effect. No status is a remote execution result.
+    """
+
+    def __init__(self, code: str):
+        self.code = code
+        super().__init__(code)
+
+
+class ReceiptTimeout(TimeoutError):
+    """No receipt arrived in time; the route's effect is uncertain. Never retry blindly."""

nodalwire-0.1.0/src/nodalwire/server/__init__.py

@@ -0,0 +1,5 @@
+"""Local relay service."""
+
+from .relay import Relay
+
+__all__ = ["Relay"]

nodalwire-0.1.0/src/nodalwire/server/relay.py

@@ -0,0 +1,207 @@
+"""One ROUTER socket: admission, lease ownership and nonblocking opaque forwarding."""
+
+import secrets
+import time
+from dataclasses import dataclass
+
+import zmq
+import zmq.asyncio
+
+from ..config import RelayConfig
+from ..protocol import CLOSE, DATA, ERROR, HEARTBEAT, HELLO, OK, SEND, VERSION, valid_name
+
+
+@dataclass
+class _Registration:
+    name: str
+    address: bytes
+    token: bytes
+    expires: float
+
+
+class Relay:
+    """Owns a local context/socket; call start(), run(), and finally close().
+
+    Every destination send uses ROUTER_MANDATORY and DONTWAIT. A successful receipt
+    means native socket queue acceptance only. There is no Python outbound queue.
+    """
+
+    def __init__(self, config: RelayConfig | None = None) -> None:
+        self.config = config or RelayConfig()
+        self.context: zmq.Context | None = None
+        self.socket: zmq.asyncio.Socket | None = None
+        self.endpoint: str | None = None
+        self._names: dict[str, _Registration] = {}
+        self._addresses: dict[bytes, _Registration] = {}
+        self._running = False
+
+    async def start(self) -> str:
+        if self.context is not None:
+            raise RuntimeError("relay already started")
+        self.context = zmq.Context()
+        try:
+            self.socket = zmq.asyncio.Socket(self.context, zmq.ROUTER)
+            self.socket.setsockopt(zmq.LINGER, 0)
+            self.socket.setsockopt(zmq.IPV6, int(self.config.endpoint.startswith("tcp://[")))
+            self.socket.setsockopt(zmq.ROUTER_MANDATORY, 1)
+            self.socket.setsockopt(zmq.ROUTER_HANDOVER, 0)
+            self.socket.setsockopt(zmq.SNDHWM, self.config.send_hwm)
+            self.socket.setsockopt(zmq.RCVHWM, self.config.receive_hwm)
+            self.socket.setsockopt(zmq.MAXMSGSIZE, self.config.max_payload_bytes + 4096)
+            self.socket.bind(self.config.endpoint)
+            self.endpoint = self.socket.getsockopt(zmq.LAST_ENDPOINT).decode("utf-8")
+            return self.endpoint
+        except BaseException:
+            await self.close()
+            raise
+
+    def _remove(self, registration: _Registration) -> None:
+        # Fence removal by object identity even if a name/address was later reused.
+        if self._names.get(registration.name) is registration:
+            del self._names[registration.name]
+        if self._addresses.get(registration.address) is registration:
+            del self._addresses[registration.address]
+
+    def _expire(self) -> None:
+        now = time.monotonic()
+        for registration in tuple(self._names.values()):
+            if registration.expires <= now:
+                self._remove(registration)
+
+    async def _emit(self, address: bytes, *frames: bytes) -> str | None:
+        assert self.socket is not None
+        try:
+            await self.socket.send_multipart([address, VERSION, *frames], flags=zmq.DONTWAIT)
+        except zmq.Again:
+            return "destination_full"
+        except zmq.ZMQError as exc:
+            if exc.errno == zmq.EHOSTUNREACH:
+                return "destination_unavailable"
+            raise
+        return None
+
+    async def _error(self, address: bytes, token: bytes, request: bytes, code: str) -> None:
+        # If a control response cannot be queued, caller sees timeout/uncertain effect.
+        await self._emit(address, ERROR, token, request, code.encode("ascii"))
+
+    async def _hello(self, address: bytes, frames: list[bytes]) -> None:
+        if len(frames) != 2 or not 1 <= len(frames[0]) <= 64:
+            return
+        request, encoded_name = frames
+        try:
+            name = encoded_name.decode("ascii")
+        except UnicodeDecodeError:
+            name = ""
+        if not valid_name(name):
+            await self._error(address, b"", request, "invalid_name")
+            return
+        if self.config.allowed_names is not None and name not in self.config.allowed_names:
+            await self._error(address, b"", request, "admission_denied")
+            return
+        if name in self._names or address in self._addresses:
+            await self._error(address, b"", request, "duplicate_name")
+            return
+        registration = _Registration(
+            name,
+            address,
+            secrets.token_hex(16).encode("ascii"),
+            time.monotonic() + self.config.lease_seconds,
+        )
+        self._names[name] = registration
+        self._addresses[address] = registration
+        error = await self._emit(
+            address,
+            OK,
+            b"",
+            request,
+            registration.token,
+            str(self.config.lease_seconds).encode("ascii"),
+            str(self.config.max_payload_bytes).encode("ascii"),
+        )
+        if error is not None:
+            self._remove(registration)
+
+    async def _handle(self, packet: list[zmq.Frame]) -> None:
+        if len(packet) < 3 or bytes(packet[1]) != VERSION:
+            return
+        address, command = bytes(packet[0]), bytes(packet[2])
+        frames = [bytes(frame) for frame in packet[3:]]
+        if command == HELLO:
+            await self._hello(address, frames)
+            return
+        if not frames:
+            return
+        token = frames[0]
+        request = frames[1] if len(frames) > 1 and 1 <= len(frames[1]) <= 64 else b""
+        registration = self._addresses.get(address)
+        if registration is None or registration.token != token:
+            if request:
+                await self._error(address, token, request, "not_registered")
+            return
+        registration.expires = time.monotonic() + self.config.lease_seconds
+        if command == HEARTBEAT and len(frames) == 1:
+            return
+        if command == CLOSE and len(frames) == 2 and request:
+            self._remove(registration)
+            await self._emit(address, OK, token, request)
+            return
+        if command != SEND or len(frames) != 4 or not request:
+            if request:
+                await self._error(address, token, request, "invalid_command")
+            return
+        try:
+            destination = frames[2].decode("ascii")
+        except UnicodeDecodeError:
+            destination = ""
+        payload = frames[3]
+        if not valid_name(destination):
+            error = "invalid_destination"
+        elif len(payload) > self.config.max_payload_bytes:
+            error = "payload_too_large"
+        elif not self.config.permits(registration.name, destination):
+            error = "route_denied"
+        elif destination not in self._names:
+            error = "destination_unavailable"
+        else:
+            target = self._names[destination]
+            error = await self._emit(
+                target.address, DATA, target.token, registration.name.encode("ascii"), payload
+            )
+        if error is None:
+            await self._emit(address, OK, token, request)
+        else:
+            await self._error(address, token, request, error)
+
+    async def run(self) -> None:
+        if self.socket is None or self.socket.closed:
+            raise RuntimeError("start the relay before run()")
+        if self._running:
+            raise RuntimeError("relay is already running")
+        self._running = True
+        try:
+            while True:
+                self._expire()
+                if await self.socket.poll(timeout=max(1, int(self.config.lease_seconds * 100))):
+                    packet = await self.socket.recv_multipart(copy=False)
+                    self._expire()  # Expiry before handling, not after an old heartbeat.
+                    await self._handle(packet)
+        finally:
+            self._running = False
+
+    async def close(self) -> None:
+        """Stop run() before closing; no persistent service or native resources remain."""
+        if self._running:
+            raise RuntimeError("cancel and await run() before closing the relay")
+        if self.socket is not None:
+            self.socket.close(linger=0)
+        if self.context is not None:
+            self.context.term()
+        self._names.clear()
+        self._addresses.clear()
+
+    async def __aenter__(self) -> "Relay":
+        await self.start()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()