snmp-query-engine 0.1.0__py3-none-any.whl

snmp_query_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: snmp-query-engine
+Version: 0.1.0
+Summary: Client library for the snmp-query-engine SNMP query daemon
+Project-URL: Homepage, https://github.com/tobez/sqe-python
+Project-URL: Changelog, https://github.com/tobez/sqe-python/blob/main/CHANGELOG.md
+Author-email: Anton Berezin <tobez@tobez.org>
+License-Expression: BSD-2-Clause
+License-File: LICENSE
+Keywords: monitoring,msgpack,snmp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: msgpack>=1.0
+Description-Content-Type: text/markdown
+
+# snmp-query-engine (Python client)
+
+Python client library for the
+[snmp-query-engine](https://github.com/tobez/snmp-query-engine) daemon — a
+multiplexing SNMP query engine that performs throttled SNMP queries towards
+many destinations on behalf of its clients.
+
+Distribution name `snmp-query-engine`, import name `sqe`.
+
+```sh
+pip install snmp-query-engine        # or: uv add snmp-query-engine
+```
+
+## Synchronous client
+
+```python
+import sqe
+
+with sqe.Client() as c:  # daemon on 127.0.0.1:7667
+    c.setopt("10.0.0.1", 161, {"community": "secret", "version": 2})
+    for vb in c.get("10.0.0.1", 161, ["1.3.6.1.2.1.1.5.0"]):
+        print(vb.oid, vb.value if vb.ok else f"error: {vb.error}")
+    for vb in c.gettable("10.0.0.1", 161, "1.3.6.1.2.1.2.2.1.2"):
+        print(vb.oid, vb.value)
+```
+
+The client is thread-safe; call it from a thread pool for concurrency.
+
+## asyncio client
+
+```python
+import asyncio
+import sqe
+
+async def main():
+    async with sqe.AsyncClient() as c:
+        vbs = await c.get("10.0.0.1", 161, ["1.3.6.1.2.1.1.5.0"])
+        print(vbs[0].value)
+
+asyncio.run(main())
+```
+
+Both clients expose the same six methods: `setopt`, `getopt`, `get`,
+`gettable`, `info`, `dest_info`. See the
+[daemon manual](https://github.com/tobez/snmp-query-engine/blob/main/manual.mdwn)
+for the available options and the semantics behind them.
+
+## Semantics worth knowing
+
+- **Values are msgpack-native.** SNMP string values arrive as `bytes`
+  (they are genuinely binary); OIDs, map keys, and error strings are `str`.
+- **Per-OID errors are values, not exceptions**: check `VarBind.ok` /
+  `VarBind.error`. Request-level daemon errors raise `sqe.RequestError`.
+- **Reconnect is automatic by default**: on connection loss, in-flight
+  requests fail with `sqe.ConnectionLost`, the client reconnects with
+  capped exponential backoff, replays your accumulated `setopt` options,
+  and only then releases new traffic. Opt out with `reconnect=False`.
+- **Per-call safety timeout**: every method takes `timeout=` (seconds) as a
+  guard against a wedged daemon; `None` (default) trusts the daemon's own
+  timeout/retry machinery, which always answers eventually.
+- **SETOPT options pass through verbatim** as a dict, named exactly as in
+  the daemon manual. Convenience: `bytes` values for the hexstring options
+  (`engineid`, `authkul`, `privkul`) are hex-encoded automatically.
+
+## Development
+
+```sh
+uv sync
+uv run pytest                  # unit + transport tiers
+uv run pytest -m integration   # live tier: needs a daemon binary
+                               # ($SQE_BINARY, PATH, or ../snmp-query-engine)
+uv run ruff check . && uv run mypy
+```
+
+The sans-I/O protocol core lives in `sqe/protocol.py`; alternative event
+loops (trio, ...) can drive it directly.
+
+## License
+
+BSD 2-clause, matching the daemon and the Perl client
+[Net::SNMP::QueryEngine::AnyEvent](https://metacpan.org/pod/Net::SNMP::QueryEngine::AnyEvent).

snmp_query_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sqe/__init__.py,sha256=mnX-SzZ5lAm-H368EycnKaUhqFjmSgwmoHdnV5uSe54,556
+sqe/aio.py,sha256=F7cOMzvYlOT5rgtFhSRtP-JrMVHJYS0dQ5pvH_WAhJg,10601
+sqe/client.py,sha256=JA99EMESryaMUSMj8eEx-1PMD8W3gmXusQOXCC9nfUA,11311
+sqe/errors.py,sha256=ogBaR_U08WAkG_5_RcXboIRQNZbSwnU3Hobpjh8fVBQ,503
+sqe/protocol.py,sha256=HFMWu6wmx-rp0rpTLpolCM7pVcfi2pLkI3S2oo0DP_A,9884
+sqe/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+snmp_query_engine-0.1.0.dist-info/METADATA,sha256=HCF0cH2kO2veru0TSTJaVjwTw93li7TySLBp4N0jpkI,4005
+snmp_query_engine-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+snmp_query_engine-0.1.0.dist-info/licenses/LICENSE,sha256=cf3WfBUmWJd03HzbCYBKMjbzS-Ts-_inalDQWRRyWwU,1319
+snmp_query_engine-0.1.0.dist-info/RECORD,,

snmp_query_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

snmp_query_engine-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2026, Anton Berezin <tobez@tobez.org>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

sqe/__init__.py

@@ -0,0 +1,21 @@
+# ABOUTME: Public package surface for the snmp-query-engine client library.
+# ABOUTME: Re-exports the clients, VarBind, and the exception hierarchy.
+"""Python client library for the snmp-query-engine daemon."""
+
+from .aio import AsyncClient
+from .client import Client
+from .errors import ConnectionLost, ProtocolError, RequestError, SqeError
+from .protocol import VarBind
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncClient",
+    "Client",
+    "ConnectionLost",
+    "ProtocolError",
+    "RequestError",
+    "SqeError",
+    "VarBind",
+    "__version__",
+]

sqe/aio.py

@@ -0,0 +1,284 @@
+# ABOUTME: asyncio client for the snmp-query-engine daemon: a reader task
+# ABOUTME: dispatches responses to per-request futures; auto-reconnect built in.
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import Callable
+from typing import Any, cast
+
+from . import protocol
+from .errors import ConnectionLost, ProtocolError
+
+_Encoder = Callable[[protocol.Connection], "tuple[int, bytes]"]
+
+
+class AsyncClient:
+    """asyncio client; safe for concurrent use from many tasks of one loop.
+
+    Construction does no I/O; the connection is established on first use
+    (or by an explicit await connect()).
+    """
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 7667,
+        *,
+        reconnect: bool = True,
+        reconnect_initial_delay: float = 0.1,
+        reconnect_max_delay: float = 5.0,
+        connect_timeout: float = 5.0,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._reconnect = reconnect
+        self._reconnect_initial_delay = reconnect_initial_delay
+        self._reconnect_max_delay = reconnect_max_delay
+        self._connect_timeout = connect_timeout
+        self._conn = protocol.Connection()
+        self._stream: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._reader_task: asyncio.Task[None] | None = None
+        self._futures: dict[int, asyncio.Future[protocol.Response]] = {}
+        self._connected = asyncio.Event()
+        self._connect_lock = asyncio.Lock()
+        self._closed = False
+        self._broken = False
+
+    # -- lifecycle --
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    async def connect(self) -> None:
+        """Connect now; after a drop with reconnect=False this revives the client."""
+        async with self._connect_lock:
+            if self._closed:
+                raise ConnectionLost("client is closed")
+            self._broken = False
+            if self._writer is None and self._reader_task is None:
+                await self._establish()
+
+    async def close(self) -> None:
+        """Close the connection; every in-flight request fails with ConnectionLost."""
+        if self._closed:
+            return
+        self._closed = True
+        task, self._reader_task = self._reader_task, None
+        writer, self._writer = self._writer, None
+        for response in self._conn.connection_lost():
+            self._dispatch(response)
+        self._connected.set()  # wake reconnect waiters; they re-check _closed
+        if task is not None and task is not asyncio.current_task():
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        if writer is not None:
+            writer.close()
+            with contextlib.suppress(OSError):
+                await writer.wait_closed()
+
+    # -- requests --
+
+    async def setopt(
+        self, host: str, port: int, options: dict[str, Any], *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        opts = dict(options)
+        return cast(
+            "dict[str, Any]",
+            await self._request(lambda c: c.send_setopt(host, port, opts), timeout),
+        )
+
+    async def getopt(self, host: str, port: int, *, timeout: float | None = None) -> dict[str, Any]:
+        return cast(
+            "dict[str, Any]",
+            await self._request(lambda c: c.send_getopt(host, port), timeout),
+        )
+
+    async def info(self, *, timeout: float | None = None) -> dict[str, Any]:
+        return cast("dict[str, Any]", await self._request(lambda c: c.send_info(), timeout))
+
+    async def get(
+        self, host: str, port: int, oids: list[str], *, timeout: float | None = None
+    ) -> list[protocol.VarBind]:
+        oid_list = list(oids)
+        return cast(
+            "list[protocol.VarBind]",
+            await self._request(lambda c: c.send_get(host, port, oid_list), timeout),
+        )
+
+    async def gettable(
+        self,
+        host: str,
+        port: int,
+        oid: str,
+        max_repetitions: int | None = None,
+        *,
+        timeout: float | None = None,
+    ) -> list[protocol.VarBind]:
+        return cast(
+            "list[protocol.VarBind]",
+            await self._request(
+                lambda c: c.send_gettable(host, port, oid, max_repetitions), timeout
+            ),
+        )
+
+    async def dest_info(
+        self, host: str, port: int, *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        return cast(
+            "dict[str, Any]",
+            await self._request(lambda c: c.send_dest_info(host, port), timeout),
+        )
+
+    # -- plumbing --
+
+    async def _request(self, encode: _Encoder, timeout: float | None) -> Any:
+        loop = asyncio.get_running_loop()
+        deadline = None if timeout is None else loop.time() + timeout
+        while True:
+            await self._await_link(deadline)
+            if self._closed:
+                raise ConnectionLost("client is closed")
+            if self._writer is None:
+                continue  # link dropped between checks; wait again
+            request_id, data = encode(self._conn)
+            future: asyncio.Future[protocol.Response] = loop.create_future()
+            self._futures[request_id] = future
+            # No drain(): requests are small and the daemon reads promptly,
+            # so relying on StreamWriter's own buffering keeps writes off the
+            # per-call deadline.
+            self._writer.write(data)
+            break
+        try:
+            remaining = None if deadline is None else max(0.0, deadline - loop.time())
+            response = await asyncio.wait_for(future, remaining)
+        except asyncio.TimeoutError:
+            self._abandon(request_id)
+            raise TimeoutError(f"no response from daemon within {timeout} seconds") from None
+        except asyncio.CancelledError:
+            self._abandon(request_id)
+            raise
+        if response.error is not None:
+            raise response.error
+        return response.value
+
+    def _abandon(self, request_id: int) -> None:
+        self._conn.abandon(request_id)
+        self._futures.pop(request_id, None)
+
+    async def _await_link(self, deadline: float | None) -> None:
+        if self._closed:
+            raise ConnectionLost("client is closed")
+        if self._broken:
+            raise ConnectionLost("connection lost; call connect() to retry")
+        if self._writer is not None:
+            return
+        if self._reader_task is None:
+            async with self._connect_lock:
+                if self._closed:
+                    raise ConnectionLost("client is closed")
+                if self._writer is None and self._reader_task is None:
+                    await self._establish()  # lazy first connect; errors propagate
+            return
+        loop = asyncio.get_running_loop()
+        remaining = None if deadline is None else max(0.0, deadline - loop.time())
+        try:
+            await asyncio.wait_for(self._connected.wait(), remaining)
+        except asyncio.TimeoutError:
+            raise TimeoutError("daemon connection was not restored in time") from None
+        if self._closed:
+            raise ConnectionLost("client is closed")
+        if self._broken:
+            raise ConnectionLost("connection lost; call connect() to retry")
+
+    async def _establish(self) -> None:
+        try:
+            reader, writer = await asyncio.wait_for(
+                asyncio.open_connection(self._host, self._port), self._connect_timeout
+            )
+        except asyncio.TimeoutError:
+            raise TimeoutError(
+                f"connection to {self._host}:{self._port} timed out after "
+                f"{self._connect_timeout} seconds"
+            ) from None
+        if self._closed:
+            writer.close()
+            return
+        self._stream = reader
+        self._attach(writer)
+        self._reader_task = asyncio.get_running_loop().create_task(self._reader_main())
+
+    def _attach(self, writer: asyncio.StreamWriter) -> None:
+        self._writer = writer
+        for _request_id, data in self._conn.replay_requests():
+            writer.write(data)
+        self._connected.set()
+
+    async def _reader_main(self) -> None:
+        while True:
+            await self._read_until_drop()
+            if not await self._handle_drop():
+                return
+
+    async def _read_until_drop(self) -> None:
+        stream = self._stream
+        assert stream is not None
+        while True:
+            try:
+                data = await stream.read(65536)
+            except OSError:
+                return
+            if not data:
+                return
+            try:
+                self._conn.feed(data)
+                while (response := self._conn.next_response()) is not None:
+                    self._dispatch(response)
+            except ProtocolError:
+                return  # connection-fatal; treated exactly like a drop
+
+    async def _handle_drop(self) -> bool:
+        if self._closed:
+            return False
+        self._connected.clear()
+        old_writer, self._writer = self._writer, None
+        if old_writer is not None:
+            old_writer.close()
+            with contextlib.suppress(OSError):
+                await old_writer.wait_closed()
+        for response in self._conn.connection_lost():
+            self._dispatch(response)
+        if not self._reconnect:
+            self._broken = True
+            self._reader_task = None
+            return False
+        delay = self._reconnect_initial_delay
+        while True:
+            try:
+                reader, writer = await asyncio.wait_for(
+                    asyncio.open_connection(self._host, self._port), self._connect_timeout
+                )
+            except (OSError, asyncio.TimeoutError):
+                await asyncio.sleep(delay)
+                delay = min(delay * 2, self._reconnect_max_delay)
+                if self._closed:
+                    return False
+                continue
+            if self._closed:
+                writer.close()
+                return False
+            self._stream = reader
+            self._attach(writer)
+            return True
+
+    def _dispatch(self, response: protocol.Response) -> None:
+        future = self._futures.pop(response.request_id, None)
+        if future is not None and not future.done():
+            future.set_result(response)
+        # responses with no future (replayed SETOPTs, abandoned calls) drop here

sqe/client.py

@@ -0,0 +1,301 @@
+# ABOUTME: Synchronous, thread-safe client for the snmp-query-engine daemon.
+# ABOUTME: A background reader thread dispatches responses to blocked callers.
+
+from __future__ import annotations
+
+import socket
+import threading
+import time
+from collections.abc import Callable
+from typing import Any, cast
+
+from . import protocol
+from .errors import ConnectionLost, ProtocolError
+
+_Encoder = Callable[[protocol.Connection], "tuple[int, bytes]"]
+
+
+def _close_quietly(sock: socket.socket) -> None:
+    try:
+        sock.close()
+    except OSError:
+        pass
+
+
+class _Waiter:
+    __slots__ = ("event", "response")
+
+    def __init__(self) -> None:
+        self.event = threading.Event()
+        self.response: protocol.Response | None = None
+
+
+class Client:
+    """Synchronous client; safe for concurrent use from multiple threads.
+
+    Construction does no I/O; the connection is established on first use
+    (or by an explicit connect()).
+    """
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int = 7667,
+        *,
+        reconnect: bool = True,
+        reconnect_initial_delay: float = 0.1,
+        reconnect_max_delay: float = 5.0,
+        connect_timeout: float = 5.0,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._reconnect = reconnect
+        self._reconnect_initial_delay = reconnect_initial_delay
+        self._reconnect_max_delay = reconnect_max_delay
+        self._connect_timeout = connect_timeout
+        self._lock = threading.Lock()
+        self._send_lock = threading.Lock()
+        self._conn = protocol.Connection()
+        self._sock: socket.socket | None = None
+        self._reader: threading.Thread | None = None
+        self._waiters: dict[int, _Waiter] = {}
+        self._connected = threading.Event()
+        self._wake = threading.Event()  # interrupts reconnect backoff on close
+        self._closed = False
+        self._broken = False
+
+    # -- lifecycle --
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def connect(self) -> None:
+        """Connect now; after a drop with reconnect=False this revives the client."""
+        with self._lock:
+            if self._closed:
+                raise ConnectionLost("client is closed")
+            self._broken = False
+            if self._sock is None and self._reader is None:
+                self._connect_locked()
+
+    def close(self) -> None:
+        """Close the connection; every in-flight request fails with ConnectionLost."""
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            self._wake.set()
+            sock, self._sock = self._sock, None
+            reader, self._reader = self._reader, None
+            if sock is not None:
+                _close_quietly(sock)
+            for response in self._conn.connection_lost():
+                self._dispatch_locked(response)
+            self._connected.set()  # wake reconnect waiters; they re-check _closed
+        if reader is not None and reader is not threading.current_thread():
+            reader.join(timeout=5)
+
+    # -- requests --
+
+    def setopt(
+        self, host: str, port: int, options: dict[str, Any], *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        opts = dict(options)
+        return cast(
+            "dict[str, Any]",
+            self._request(lambda c: c.send_setopt(host, port, opts), timeout),
+        )
+
+    def getopt(self, host: str, port: int, *, timeout: float | None = None) -> dict[str, Any]:
+        return cast("dict[str, Any]", self._request(lambda c: c.send_getopt(host, port), timeout))
+
+    def info(self, *, timeout: float | None = None) -> dict[str, Any]:
+        return cast("dict[str, Any]", self._request(lambda c: c.send_info(), timeout))
+
+    def get(
+        self, host: str, port: int, oids: list[str], *, timeout: float | None = None
+    ) -> list[protocol.VarBind]:
+        oid_list = list(oids)
+        return cast(
+            "list[protocol.VarBind]",
+            self._request(lambda c: c.send_get(host, port, oid_list), timeout),
+        )
+
+    def gettable(
+        self,
+        host: str,
+        port: int,
+        oid: str,
+        max_repetitions: int | None = None,
+        *,
+        timeout: float | None = None,
+    ) -> list[protocol.VarBind]:
+        return cast(
+            "list[protocol.VarBind]",
+            self._request(lambda c: c.send_gettable(host, port, oid, max_repetitions), timeout),
+        )
+
+    def dest_info(self, host: str, port: int, *, timeout: float | None = None) -> dict[str, Any]:
+        return cast(
+            "dict[str, Any]", self._request(lambda c: c.send_dest_info(host, port), timeout)
+        )
+
+    # -- plumbing --
+
+    def _request(self, encode: _Encoder, timeout: float | None) -> Any:
+        deadline = None if timeout is None else time.monotonic() + timeout
+        waiter = _Waiter()
+        while True:
+            self._await_link(deadline)
+            with self._lock:
+                if self._closed:
+                    raise ConnectionLost("client is closed")
+                if self._sock is None:
+                    continue  # link dropped between checks; wait again
+                request_id, data = encode(self._conn)
+                self._waiters[request_id] = waiter
+                sock = self._sock
+            try:
+                with self._send_lock:
+                    sock.sendall(data)
+            except OSError:
+                pass  # the reader observes the drop and fails this waiter
+            break
+        remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
+        if not waiter.event.wait(remaining):
+            with self._lock:
+                self._conn.abandon(request_id)
+                self._waiters.pop(request_id, None)
+            raise TimeoutError(f"no response from daemon within {timeout} seconds")
+        response = waiter.response
+        assert response is not None
+        if response.error is not None:
+            raise response.error
+        return response.value
+
+    def _await_link(self, deadline: float | None) -> None:
+        with self._lock:
+            if self._closed:
+                raise ConnectionLost("client is closed")
+            if self._broken:
+                raise ConnectionLost("connection lost; call connect() to retry")
+            if self._sock is not None:
+                return
+            if self._reader is None:
+                self._connect_locked()  # lazy first connect; errors propagate
+                return
+        # a reconnect is in progress; wait for the reader thread to restore it
+        remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
+        if not self._connected.wait(remaining):
+            raise TimeoutError("daemon connection was not restored in time")
+        with self._lock:
+            if self._closed:
+                raise ConnectionLost("client is closed")
+            if self._broken:
+                raise ConnectionLost("connection lost; call connect() to retry")
+
+    def _connect_locked(self) -> None:
+        sock = socket.create_connection((self._host, self._port), timeout=self._connect_timeout)
+        sock.settimeout(None)
+        self._attach_locked(sock)
+        self._reader = threading.Thread(target=self._reader_main, args=(sock,), daemon=True)
+        self._reader.start()
+
+    def _attach_locked(self, sock: socket.socket) -> None:
+        sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        self._sock = sock
+        # Safe under _lock: the reader for this socket starts only after we return,
+        # so no concurrent reader can starve waiting for the lock while this send happens.
+        self._send_payloads(sock, self._conn.replay_requests())
+        self._connected.set()
+
+    def _send_payloads(self, sock: socket.socket, payloads: list[tuple[int, bytes]]) -> None:
+        """Send pre-encoded payloads, serialized against concurrent senders."""
+        with self._send_lock:
+            for _request_id, data in payloads:
+                try:
+                    sock.sendall(data)
+                except OSError:
+                    break  # the reader observes the drop
+
+    def _reader_main(self, sock: socket.socket) -> None:
+        while True:
+            self._read_until_drop(sock)
+            next_sock = self._handle_drop(sock)
+            if next_sock is None:
+                return
+            sock = next_sock
+
+    def _read_until_drop(self, sock: socket.socket) -> None:
+        while True:
+            try:
+                data = sock.recv(65536)
+            except OSError:
+                return
+            if not data:
+                return
+            with self._lock:
+                try:
+                    self._conn.feed(data)
+                    while (response := self._conn.next_response()) is not None:
+                        self._dispatch_locked(response)
+                except ProtocolError:
+                    return  # connection-fatal; treated exactly like a drop
+
+    def _handle_drop(self, sock: socket.socket) -> socket.socket | None:
+        with self._lock:
+            if self._closed or sock is not self._sock:
+                return None
+            self._connected.clear()
+            self._sock = None
+            _close_quietly(sock)
+            for response in self._conn.connection_lost():
+                self._dispatch_locked(response)
+            if not self._reconnect:
+                self._broken = True
+                self._reader = None
+                return None
+        return self._reconnect_link()
+
+    def _reconnect_link(self) -> socket.socket | None:
+        delay = self._reconnect_initial_delay
+        while True:
+            with self._lock:
+                if self._closed:
+                    return None
+            try:
+                sock = socket.create_connection(
+                    (self._host, self._port), timeout=self._connect_timeout
+                )
+                sock.settimeout(None)
+            except OSError:
+                if self._wake.wait(delay):
+                    return None  # close() interrupted the backoff
+                delay = min(delay * 2, self._reconnect_max_delay)
+                continue
+            with self._lock:
+                if self._closed:
+                    _close_quietly(sock)
+                    return None
+                sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+                payloads = self._conn.replay_requests()
+            # send outside self._lock: a full send buffer must not block the
+            # reader (or any other caller) out of the lock while replaying
+            self._send_payloads(sock, payloads)
+            with self._lock:
+                if self._closed:
+                    _close_quietly(sock)
+                    return None
+                self._sock = sock
+                self._connected.set()
+            return sock
+
+    def _dispatch_locked(self, response: protocol.Response) -> None:
+        waiter = self._waiters.pop(response.request_id, None)
+        if waiter is not None:
+            waiter.response = response
+            waiter.event.set()
+        # responses with no waiter (replayed SETOPTs, abandoned calls) drop here

sqe/errors.py

@@ -0,0 +1,18 @@
+# ABOUTME: Exception hierarchy for the sqe client library.
+# ABOUTME: All sqe exceptions derive from SqeError.
+
+
+class SqeError(Exception):
+    """Base class for all sqe errors."""
+
+
+class RequestError(SqeError):
+    """The daemon rejected a request; carries the daemon's error message."""
+
+
+class ConnectionLost(SqeError):
+    """The connection to the daemon was lost while the request was in flight."""
+
+
+class ProtocolError(SqeError):
+    """The daemon sent something the protocol does not allow."""

sqe/protocol.py

@@ -0,0 +1,261 @@
+# ABOUTME: Sans-I/O protocol core for the snmp-query-engine client protocol:
+# ABOUTME: request encoding, response decoding and matching, SETOPT replay cache.
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any
+
+import msgpack
+
+from .errors import ConnectionLost, ProtocolError, RequestError, SqeError
+
+SETOPT = 1
+GETOPT = 2
+INFO = 3
+GET = 4
+GETTABLE = 5
+DEST_INFO = 6
+
+
+@dataclass(frozen=True)
+class VarBind:
+    """One OID/value pair from a GET or GETTABLE reply.
+
+    Per-OID wire errors ("timeout", "no-such-object", ...) land in `error`;
+    they never raise.
+    """
+
+    oid: str
+    value: Any = None
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+
+@dataclass(frozen=True)
+class Response:
+    """A decoded daemon reply, matched to the request id that caused it."""
+
+    request_id: int
+    value: Any = None
+    error: SqeError | None = None
+
+
+_REPLY_OK = 0x10
+_REPLY_ERROR = 0x20
+
+_HEXSTRING_OPTIONS = ("engineid", "authkul", "privkul")
+_V3_OPTIONS = frozenset(
+    {
+        "engineid",
+        "username",
+        "authprotocol",
+        "authpassword",
+        "authkul",
+        "privprotocol",
+        "privpassword",
+        "privkul",
+    }
+)
+
+
+def _text(value: bytes | str) -> str:
+    """Decode bytes to string, mirroring daemon's bin-everything strategy."""
+    if isinstance(value, str):
+        return value
+    try:
+        return value.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise ProtocolError(f"undecodable string from daemon: {value!r}") from exc
+
+
+@dataclass
+class _Pending:
+    """Bookkeeping for one request awaiting its reply."""
+
+    rtype: int
+    host: str | None = None
+    port: int | None = None
+    options: dict[str, Any] | None = None
+
+
+class Connection:
+    """Sans-I/O protocol state machine.
+
+    Encodes requests to wire bytes and decodes/matches wire bytes fed back
+    in; never touches a socket. Transports own all I/O.
+    """
+
+    def __init__(self) -> None:
+        self._next_id = 1
+        self._pending: dict[int, _Pending] = {}
+        self._tombstones: set[int] = set()
+        self._option_cache: dict[tuple[str, int], dict[str, Any]] = {}
+        self._unpacker = msgpack.Unpacker()
+
+    def _send(self, pending: _Pending, tail: list[Any]) -> tuple[int, bytes]:
+        request_id = self._next_id
+        self._next_id += 1
+        self._pending[request_id] = pending
+        data: bytes = msgpack.packb([pending.rtype, request_id, *tail])
+        return request_id, data
+
+    def send_setopt(self, host: str, port: int, options: dict[str, Any]) -> tuple[int, bytes]:
+        encoded = dict(options)
+        for name in _HEXSTRING_OPTIONS:
+            value = encoded.get(name)
+            if isinstance(value, bytes):
+                encoded[name] = value.hex()
+        pending = _Pending(SETOPT, host, port, options=encoded)
+        return self._send(pending, [host, port, encoded])
+
+    def send_getopt(self, host: str, port: int) -> tuple[int, bytes]:
+        return self._send(_Pending(GETOPT, host, port), [host, port])
+
+    def send_info(self) -> tuple[int, bytes]:
+        return self._send(_Pending(INFO), [])
+
+    def send_get(self, host: str, port: int, oids: Iterable[str]) -> tuple[int, bytes]:
+        return self._send(_Pending(GET, host, port), [host, port, list(oids)])
+
+    def send_gettable(
+        self, host: str, port: int, oid: str, max_repetitions: int | None = None
+    ) -> tuple[int, bytes]:
+        tail: list[Any] = [host, port, oid]
+        if max_repetitions is not None:
+            tail.append(max_repetitions)
+        return self._send(_Pending(GETTABLE, host, port), tail)
+
+    def send_dest_info(self, host: str, port: int) -> tuple[int, bytes]:
+        return self._send(_Pending(DEST_INFO, host, port), [host, port])
+
+    def feed(self, data: bytes) -> None:
+        """Give the connection bytes read from the wire."""
+        self._unpacker.feed(data)
+
+    def next_response(self) -> Response | None:
+        """Return the next decoded response, or None if more bytes are needed.
+
+        Call repeatedly after each feed(): one feed can complete zero or
+        more responses. Raises ProtocolError on anything malformed;
+        transports must treat that as connection-fatal.
+        """
+        while True:
+            try:
+                obj = self._unpacker.unpack()
+            except msgpack.exceptions.OutOfData:
+                return None
+            except (msgpack.exceptions.UnpackException, ValueError) as exc:
+                raise ProtocolError(f"malformed msgpack from daemon: {exc}") from exc
+            response = self._handle(obj)
+            if response is not None:
+                return response
+
+    def _handle(self, obj: Any) -> Response | None:
+        """Process a decoded msgpack object, returning a Response or None if skipped."""
+        if not isinstance(obj, list) or len(obj) < 2:
+            raise ProtocolError(f"response is not a well-formed array: {obj!r}")
+        rtype, request_id = obj[0], obj[1]
+        if not isinstance(rtype, int) or not isinstance(request_id, int):
+            raise ProtocolError(f"response type/id are not integers: {obj!r}")
+        if request_id in self._tombstones:
+            self._tombstones.discard(request_id)
+            return None
+        pending = self._pending.get(request_id)
+        if pending is None:
+            raise ProtocolError(f"response for unknown request id {request_id}")
+        if rtype == pending.rtype | _REPLY_ERROR:
+            del self._pending[request_id]
+            if len(obj) != 3 or not isinstance(obj[2], (bytes, str)):
+                raise ProtocolError(f"malformed error reply: {obj!r}")
+            return Response(request_id, error=RequestError(_text(obj[2])))
+        if rtype != pending.rtype | _REPLY_OK:
+            raise ProtocolError(
+                f"reply type 0x{rtype:x} does not match request type {pending.rtype}"
+            )
+        del self._pending[request_id]
+        if len(obj) != 3:
+            raise ProtocolError(f"success reply is not a 3-element array: {obj!r}")
+        value = self._decode_payload(pending.rtype, obj[2])
+        if pending.rtype == SETOPT:
+            self._cache_setopt(pending)
+        return Response(request_id, value=value)
+
+    def _decode_payload(self, rtype: int, payload: Any) -> Any:
+        """Decode a payload based on response type."""
+        if rtype in (GET, GETTABLE):
+            return self._decode_varbinds(payload)
+        return self._decode_map(payload)
+
+    def _decode_map(self, payload: Any) -> dict[str, Any]:
+        """Decode a map, normalizing all keys to strings recursively."""
+        if not isinstance(payload, dict):
+            raise ProtocolError(f"reply payload is not a map: {payload!r}")
+        out: dict[str, Any] = {}
+        for key, value in payload.items():
+            if not isinstance(key, (bytes, str)):
+                raise ProtocolError(f"non-string map key in reply: {key!r}")
+            # Values are scalars or nested maps; the daemon never nests maps inside lists.
+            out[_text(key)] = self._decode_map(value) if isinstance(value, dict) else value
+        return out
+
+    def _decode_varbinds(self, payload: Any) -> list[VarBind]:
+        """Decode a list of OID/value pairs (GET/GETTABLE result)."""
+        if not isinstance(payload, list):
+            raise ProtocolError(f"oid reply payload is not an array: {payload!r}")
+        out: list[VarBind] = []
+        for row in payload:
+            if not isinstance(row, list) or len(row) != 2 or not isinstance(row[0], (bytes, str)):
+                raise ProtocolError(f"malformed varbind row: {row!r}")
+            oid, value = _text(row[0]), row[1]
+            if isinstance(value, list):
+                if len(value) != 1 or not isinstance(value[0], (bytes, str)):
+                    raise ProtocolError(f"malformed per-oid error for {oid}: {value!r}")
+                out.append(VarBind(oid, error=_text(value[0])))
+            else:
+                out.append(VarBind(oid, value=value))
+        return out
+
+    def _cache_setopt(self, pending: _Pending) -> None:
+        """Cache SETOPT options for this host/port pair."""
+        assert pending.host is not None and pending.port is not None
+        assert pending.options is not None
+        cache = self._option_cache.setdefault((pending.host, pending.port), {})
+        if _V3_OPTIONS & pending.options.keys():
+            for name in _V3_OPTIONS:
+                cache.pop(name, None)
+        cache.update(pending.options)
+
+    def connection_lost(self) -> list[Response]:
+        """The transport lost the TCP connection.
+
+        Every pending request drains as a ConnectionLost-carrying response
+        for the transport to dispatch. Tombstones and any partially received
+        frame are discarded; the option cache survives (it is per-client
+        state, not per-TCP-connection state).
+        """
+        drained = [
+            Response(request_id, error=ConnectionLost("connection to daemon lost"))
+            for request_id in self._pending
+        ]
+        self._pending.clear()
+        self._tombstones.clear()
+        self._unpacker = msgpack.Unpacker()
+        return drained
+
+    def replay_requests(self) -> list[tuple[int, bytes]]:
+        """Encode a SETOPT per cached destination, for replay after reconnect."""
+        out: list[tuple[int, bytes]] = []
+        for (host, port), options in self._option_cache.items():
+            if options:
+                out.append(self.send_setopt(host, port, options))
+        return out
+
+    def abandon(self, request_id: int) -> None:
+        """Forget a pending request; its eventual response is dropped silently."""
+        if self._pending.pop(request_id, None) is not None:
+            self._tombstones.add(request_id)