hivellm-thunder 0.1.0__tar.gz

hivellm_thunder-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Rulebook - ignore runtime data, keep specs and tasks
+/.rulebook/*
+!/.rulebook/specs/
+!/.rulebook/tasks/
+!/.rulebook/tasks/**/*.md
+!/.rulebook/rulebook.json
+
+# Patterns added by @hivellm/rulebook
+# Added at: 2026-07-17T04:49:22.423Z
+
+*.log
+*.swo
+*.swp
+*~
+.DS_Store
+.cache/
+.env
+.env.*.local
+.env.local
+.idea/
+.vscode/
+Thumbs.db
+logs/
+temp/
+tmp/
+
+CLAUDE.local.md
+.rulebook/backup/
+
+# Build artifacts
+rust/target/
+target/
+node_modules/
+dist/
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+csharp/**/bin/
+csharp/**/obj/

hivellm_thunder-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: hivellm-thunder
+Version: 0.1.0
+Summary: HiveLLM binary RPC (Thunder) - wire v1 codec, family profiles, sync/async multiplexed clients
+Project-URL: Homepage, https://github.com/hivellm/thunder
+License-Expression: Apache-2.0
+Keywords: hivellm,messagepack,msgpack,rpc,thunder
+Requires-Python: >=3.10
+Requires-Dist: msgpack>=1.1
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# hivellm-thunder
+
+**⚡ The HiveLLM binary RPC protocol for Python — wire v1 (frozen), one configurable standard, sync + async multiplexed clients**
+
+Thunder is the shared home of the HiveLLM binary RPC standard: a length-prefixed
+MessagePack protocol (`u32 LE length` + body) multiplexing concurrent requests over one
+persistent TCP connection. This package is the Python implementation — import name
+`thunder_rpc`, one runtime dependency (`msgpack`), conformance-tested against the
+language-neutral golden-vector corpus in [`conformance/`](../conformance/).
+
+## Install
+
+```bash
+pip install hivellm-thunder
+```
+
+## Quickstart — sync
+
+```python
+from thunder_rpc import Client, ClientConfig, Config, Credentials, Value
+
+# Your application's identity on top of the family standard.
+config = Config.standard().with_scheme("myapp").with_port(9000)
+
+client_config = ClientConfig(credentials=Credentials.api_key("secret-key"))
+with Client.connect("myapp://localhost", config, client_config) as client:
+    pong = client.call("PING")
+    assert pong.as_str() == "PONG"
+
+    hits = client.call("SEARCH", [Value.str("docs"), Value.bytes(embedding)], timeout=5.0)
+```
+
+## Quickstart — async
+
+```python
+from thunder_rpc import AsyncClient, Config
+
+config = Config.standard().with_scheme("myapp").with_port(9000)
+
+async with await AsyncClient.connect("myapp://localhost", config) as client:
+    pong = await client.call("PING")
+    assert pong.as_str() == "PONG"
+```
+
+Both clients implement the identical SPEC-003 contract: pipelined out-of-order
+completion, monotonic u32 ids (skipping `PUSH_ID`), serialized writes, `max_in_flight`
+backpressure, per-call timeouts (default 30 s), lazy 2-attempt reconnect with
+re-handshake, typed errors, and push-frame routing. The asyncio client additionally
+honors task cancellation by removing the pending entry (CLT-021).
+
+## One standard, zero product knowledge
+
+Thunder is a protocol library, not a product catalogue: there is no registry of named
+configurations, because a library that must serve implementations which do not exist yet
+cannot ship a hardcoded list of the ones that did. Instead `Config.standard()` is **the**
+family standard (data, not behavior — SPEC-002), pinned to
+[`conformance/standard.yaml`](../conformance/standard.yaml) by the test suite so all four
+language implementations agree on what "standard" means:
+
+| Dimension | Standard | Why |
+|---|---|---|
+| `handshake` | `HELLO_MANDATORY` | the only shape that negotiates `proto` and advertises capabilities |
+| `hello_style` | `MAP_PAYLOAD` | `{version, token \| api_key, client_name}`; reply carries proto + capabilities |
+| `push` | `RESERVED` | emitting push is a capability an application opts into |
+| `max_frame_bytes` | 64 MiB | checked before allocation (WIRE-020) |
+| `max_in_flight` | 256 | per-connection request bound |
+| `error_codes` | `BOTH` | `"[code] message"` superset recognizing the RESP3 auth tokens — needs no negotiation |
+| `tls` | `OFF` | additive capability a deployment turns on, never a dialect |
+
+`scheme` and `default_port` are deliberately **not** part of the standard: identity is
+your application's, and Thunder has no opinion about it. An application that matches the
+standard writes its identity and nothing else:
+
+```python
+config = Config.standard().with_scheme("myapp").with_port(9000)
+```
+
+An application that still diverges says so in its own repository, where that knowledge
+belongs — every dimension is a `with_*` override returning a new frozen `Config`
+(plain `Config(...)` construction works too):
+
+```python
+config = (
+    Config.standard()
+    .with_scheme("legacy")
+    .with_port(15501)
+    .with_handshake(Handshake.AUTH_COMMAND)   # AUTH-command auth, no HELLO handler
+    .with_hello_style(HelloStyle.NOT_USED)
+    .with_push(PushPolicy.ENABLED)            # ships a push-producing command
+)
+```
+
+Convergence is then visible and per-application: delete overrides until only identity
+remains. Nobody waits on a Thunder release for a row in a registry (PRO-020).
+
+Endpoints accept `scheme://host[:port]` — where the scheme is **your** `config.scheme` —
+or bare `host:port`; `http(s)://` is rejected (Thunder is RPC-only).
+
+## Error classes
+
+All errors derive from `thunder_rpc.ThunderError`; branch on the class and `code`, never
+on message text (CLT-052):
+
+| Class | Meaning |
+|---|---|
+| `AuthError` | Handshake rejected, or `NOAUTH`/`WRONGPASS`/`NOPERM` reply |
+| `ServerError` | Server answered `Err` — raw `message` + optional bracket `code` |
+| `ConnectionError` | Dial/write failure, dead connection, invalid endpoint |
+| `TimeoutError` | Connect or per-call timeout elapsed |
+| `FrameTooLargeError` | Frame over the config's cap (checked before allocation) |
+| `DecodeError` | Malformed frame, or push frame while push is `RESERVED` |
+
+## Wire layer
+
+`thunder_rpc.wire` is pure (no sockets): `encode_frame`, `decode_request`,
+`decode_response` over the 8-variant `Value` model
+(`Null | Bool | Int | Float | Bytes | Str | Array | Map`). Canonical bytes are pinned by
+the corpus: `Bytes` emits as MessagePack bin, floats always pack as f64 bit-exact,
+structs are array-encoded; legacy int-array `Bytes` and map-shaped `Request` decode but
+are never re-emitted.
+
+## Development
+
+```bash
+pip install -e .[dev]
+python -m pytest          # includes the conformance corpus — never skipped
+ruff check .
+```
+
+## Specs
+
+- [SPEC-001 Wire format](../docs/specs/SPEC-001-wire-format.md)
+- [SPEC-002 Protocol configuration](../docs/specs/SPEC-002-configuration.md)
+- [SPEC-003 Client contract](../docs/specs/SPEC-003-client.md)
+- [SPEC-005 Conformance](../docs/specs/SPEC-005-conformance.md)
+- [SPEC-006 Packaging](../docs/specs/SPEC-006-packaging-release.md)
+
+Apache-2.0 — part of the [Thunder](../README.md) monorepo release train.

hivellm_thunder-0.1.0/README.md

@@ -0,0 +1,138 @@
+# hivellm-thunder
+
+**⚡ The HiveLLM binary RPC protocol for Python — wire v1 (frozen), one configurable standard, sync + async multiplexed clients**
+
+Thunder is the shared home of the HiveLLM binary RPC standard: a length-prefixed
+MessagePack protocol (`u32 LE length` + body) multiplexing concurrent requests over one
+persistent TCP connection. This package is the Python implementation — import name
+`thunder_rpc`, one runtime dependency (`msgpack`), conformance-tested against the
+language-neutral golden-vector corpus in [`conformance/`](../conformance/).
+
+## Install
+
+```bash
+pip install hivellm-thunder
+```
+
+## Quickstart — sync
+
+```python
+from thunder_rpc import Client, ClientConfig, Config, Credentials, Value
+
+# Your application's identity on top of the family standard.
+config = Config.standard().with_scheme("myapp").with_port(9000)
+
+client_config = ClientConfig(credentials=Credentials.api_key("secret-key"))
+with Client.connect("myapp://localhost", config, client_config) as client:
+    pong = client.call("PING")
+    assert pong.as_str() == "PONG"
+
+    hits = client.call("SEARCH", [Value.str("docs"), Value.bytes(embedding)], timeout=5.0)
+```
+
+## Quickstart — async
+
+```python
+from thunder_rpc import AsyncClient, Config
+
+config = Config.standard().with_scheme("myapp").with_port(9000)
+
+async with await AsyncClient.connect("myapp://localhost", config) as client:
+    pong = await client.call("PING")
+    assert pong.as_str() == "PONG"
+```
+
+Both clients implement the identical SPEC-003 contract: pipelined out-of-order
+completion, monotonic u32 ids (skipping `PUSH_ID`), serialized writes, `max_in_flight`
+backpressure, per-call timeouts (default 30 s), lazy 2-attempt reconnect with
+re-handshake, typed errors, and push-frame routing. The asyncio client additionally
+honors task cancellation by removing the pending entry (CLT-021).
+
+## One standard, zero product knowledge
+
+Thunder is a protocol library, not a product catalogue: there is no registry of named
+configurations, because a library that must serve implementations which do not exist yet
+cannot ship a hardcoded list of the ones that did. Instead `Config.standard()` is **the**
+family standard (data, not behavior — SPEC-002), pinned to
+[`conformance/standard.yaml`](../conformance/standard.yaml) by the test suite so all four
+language implementations agree on what "standard" means:
+
+| Dimension | Standard | Why |
+|---|---|---|
+| `handshake` | `HELLO_MANDATORY` | the only shape that negotiates `proto` and advertises capabilities |
+| `hello_style` | `MAP_PAYLOAD` | `{version, token \| api_key, client_name}`; reply carries proto + capabilities |
+| `push` | `RESERVED` | emitting push is a capability an application opts into |
+| `max_frame_bytes` | 64 MiB | checked before allocation (WIRE-020) |
+| `max_in_flight` | 256 | per-connection request bound |
+| `error_codes` | `BOTH` | `"[code] message"` superset recognizing the RESP3 auth tokens — needs no negotiation |
+| `tls` | `OFF` | additive capability a deployment turns on, never a dialect |
+
+`scheme` and `default_port` are deliberately **not** part of the standard: identity is
+your application's, and Thunder has no opinion about it. An application that matches the
+standard writes its identity and nothing else:
+
+```python
+config = Config.standard().with_scheme("myapp").with_port(9000)
+```
+
+An application that still diverges says so in its own repository, where that knowledge
+belongs — every dimension is a `with_*` override returning a new frozen `Config`
+(plain `Config(...)` construction works too):
+
+```python
+config = (
+    Config.standard()
+    .with_scheme("legacy")
+    .with_port(15501)
+    .with_handshake(Handshake.AUTH_COMMAND)   # AUTH-command auth, no HELLO handler
+    .with_hello_style(HelloStyle.NOT_USED)
+    .with_push(PushPolicy.ENABLED)            # ships a push-producing command
+)
+```
+
+Convergence is then visible and per-application: delete overrides until only identity
+remains. Nobody waits on a Thunder release for a row in a registry (PRO-020).
+
+Endpoints accept `scheme://host[:port]` — where the scheme is **your** `config.scheme` —
+or bare `host:port`; `http(s)://` is rejected (Thunder is RPC-only).
+
+## Error classes
+
+All errors derive from `thunder_rpc.ThunderError`; branch on the class and `code`, never
+on message text (CLT-052):
+
+| Class | Meaning |
+|---|---|
+| `AuthError` | Handshake rejected, or `NOAUTH`/`WRONGPASS`/`NOPERM` reply |
+| `ServerError` | Server answered `Err` — raw `message` + optional bracket `code` |
+| `ConnectionError` | Dial/write failure, dead connection, invalid endpoint |
+| `TimeoutError` | Connect or per-call timeout elapsed |
+| `FrameTooLargeError` | Frame over the config's cap (checked before allocation) |
+| `DecodeError` | Malformed frame, or push frame while push is `RESERVED` |
+
+## Wire layer
+
+`thunder_rpc.wire` is pure (no sockets): `encode_frame`, `decode_request`,
+`decode_response` over the 8-variant `Value` model
+(`Null | Bool | Int | Float | Bytes | Str | Array | Map`). Canonical bytes are pinned by
+the corpus: `Bytes` emits as MessagePack bin, floats always pack as f64 bit-exact,
+structs are array-encoded; legacy int-array `Bytes` and map-shaped `Request` decode but
+are never re-emitted.
+
+## Development
+
+```bash
+pip install -e .[dev]
+python -m pytest          # includes the conformance corpus — never skipped
+ruff check .
+```
+
+## Specs
+
+- [SPEC-001 Wire format](../docs/specs/SPEC-001-wire-format.md)
+- [SPEC-002 Protocol configuration](../docs/specs/SPEC-002-configuration.md)
+- [SPEC-003 Client contract](../docs/specs/SPEC-003-client.md)
+- [SPEC-005 Conformance](../docs/specs/SPEC-005-conformance.md)
+- [SPEC-006 Packaging](../docs/specs/SPEC-006-packaging-release.md)
+
+Apache-2.0 — part of the [Thunder](../README.md) monorepo release train.

hivellm_thunder-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hivellm-thunder"
+version = "0.1.0"
+description = "HiveLLM binary RPC (Thunder) - wire v1 codec, family profiles, sync/async multiplexed clients"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = ["msgpack>=1.1"]
+keywords = ["rpc", "messagepack", "msgpack", "hivellm", "thunder"]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.24",
+  "PyYAML>=6",
+  "ruff>=0.6",
+]
+
+[project.urls]
+Homepage = "https://github.com/hivellm/thunder"
+
+[tool.hatch.build.targets.wheel]
+packages = ["thunder_rpc"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

hivellm_thunder-0.1.0/requirements.txt

@@ -0,0 +1,4 @@
+msgpack>=1.1
+PyYAML>=6
+pytest>=8
+pytest-asyncio>=0.24

hivellm_thunder-0.1.0/tests/conftest.py

@@ -0,0 +1,12 @@
+"""Test-suite plumbing: guarantees the tests directory is importable
+(``mockserver``) and the package resolves from a source checkout."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+for path in (str(_HERE), str(_HERE.parent)):
+    if path not in sys.path:
+        sys.path.insert(0, path)

hivellm_thunder-0.1.0/tests/mockserver.py

@@ -0,0 +1,121 @@
+"""Scripted loopback TCP responders for the behavioral floor tests
+(SPEC-003 / CLT-090) — the Python mirror of the tokio responders in
+``rust/thunder-client/tests/behavior.rs``. Built on the thunder_rpc wire
+codec; serves both the sync and the asyncio client (the server side is
+always a plain thread)."""
+
+from __future__ import annotations
+
+import socket
+import threading
+from typing import Callable
+
+from thunder_rpc import PUSH_ID, Request, Response, Value, wire
+
+#: Frame cap the loopback responders read with.
+SRV_CAP = 1024 * 1024
+
+#: Generous safety timeout so a broken test fails instead of hanging.
+IO_TIMEOUT = 10.0
+
+
+class PeerClosed(Exception):
+    """The client closed the connection while the script was reading."""
+
+
+class ServerConn:
+    """One accepted connection, with frame-level helpers."""
+
+    def __init__(self, sock: socket.socket) -> None:
+        self.sock = sock
+        sock.settimeout(IO_TIMEOUT)
+
+    def read_request(self) -> Request:
+        header = self._read_exact(4)
+        length = int.from_bytes(header, "little")
+        assert length <= SRV_CAP, f"client sent an over-cap frame ({length} bytes)"
+        body = self._read_exact(length)
+        return wire.decode_request_body(body)
+
+    def send_ok(self, frame_id: int, value: Value) -> None:
+        self.send_raw(wire.encode_frame(Response(id=frame_id, ok=value)))
+
+    def send_err(self, frame_id: int, message: str) -> None:
+        self.send_raw(wire.encode_frame(Response(id=frame_id, err=message)))
+
+    def send_push(self, value: Value) -> None:
+        self.send_raw(wire.encode_frame(Response(id=PUSH_ID, ok=value)))
+
+    def send_raw(self, data: bytes) -> None:
+        self.sock.sendall(data)
+
+    def close(self) -> None:
+        try:
+            self.sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+        try:
+            self.sock.close()
+        except OSError:
+            pass
+
+    def _read_exact(self, size: int) -> bytes:
+        buf = bytearray(size)
+        view = memoryview(buf)
+        got = 0
+        while got < size:
+            read = self.sock.recv_into(view[got:], size - got)
+            if read == 0:
+                raise PeerClosed()
+            got += read
+        return bytes(buf)
+
+
+class MockServer:
+    """Runs ``script(server)`` on a background thread; the script drives
+    ``accept()`` / frame helpers. Use as a context manager — exit joins the
+    script and re-raises anything it tripped on."""
+
+    def __init__(self, script: Callable[["MockServer"], None]) -> None:
+        self._script = script
+        self._listener = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        self._listener.bind(("127.0.0.1", 0))
+        self._listener.listen(8)
+        self._listener.settimeout(IO_TIMEOUT)
+        self.port = self._listener.getsockname()[1]
+        #: Endpoint string the clients dial (bare host:port, CLT-070).
+        self.address = f"127.0.0.1:{self.port}"
+        #: How many connections the script accepted (reconnect assertions).
+        self.accepts = 0
+        self._conns: list[ServerConn] = []
+        self._error: BaseException | None = None
+        self._thread = threading.Thread(
+            target=self._run, name="mock-server", daemon=True
+        )
+
+    def accept(self) -> ServerConn:
+        sock, _ = self._listener.accept()
+        self.accepts += 1
+        conn = ServerConn(sock)
+        self._conns.append(conn)
+        return conn
+
+    def _run(self) -> None:
+        try:
+            self._script(self)
+        except BaseException as exc:  # surface script failures on __exit__
+            self._error = exc
+
+    def __enter__(self) -> "MockServer":
+        self._thread.start()
+        return self
+
+    def __exit__(self, exc_type: object, *_exc: object) -> None:
+        self._thread.join(timeout=IO_TIMEOUT + 5)
+        for conn in self._conns:
+            conn.close()
+        self._listener.close()
+        if exc_type is None:
+            assert not self._thread.is_alive(), "mock server script did not finish"
+            if self._error is not None:
+                raise self._error