natsio-testing 0.1.0__tar.gz

natsio_testing-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: natsio-testing
+Version: 0.1.0
+Summary: nats-server process management for tests — start, stop, and fault-inject real servers
+Keywords: nats,nats.io,testing,pytest,nats-server
+Author: Corrupt Mane
+Author-email: Corrupt Mane <corruptmane@gmail.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: natsio
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/corruptmane/natsio
+Project-URL: Repository, https://github.com/corruptmane/natsio
+Project-URL: Changelog, https://github.com/corruptmane/natsio/blob/main/extensions/natsio-testing/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# natsio-testing
+
+Run real `nats-server` processes from your test suite: start/stop, temporary
+config files, free-port allocation, readiness probing (plaintext and
+TLS-handshake-first), and fault injection (`kill()`).
+
+```python
+from natsio.testing import NatsServerProcess
+
+async def test_against_a_real_server():
+    server = await NatsServerProcess(binary="nats-server").start()
+    try:
+        nc = await natsio.connect(server.url)
+        ...
+    finally:
+        await server.stop()
+```
+
+Binary discovery: pass `binary=` explicitly, or use `find_server_binary()`
+(checks `NATS_SERVER_BIN`, then `nats-server` on `PATH`).
+
+Part of the natsio extension tier: distribution `natsio-testing`, imported as
+`natsio.testing`. Pre-1.0, no API-stability promises.

natsio_testing-0.1.0/README.md

@@ -0,0 +1,23 @@
+# natsio-testing
+
+Run real `nats-server` processes from your test suite: start/stop, temporary
+config files, free-port allocation, readiness probing (plaintext and
+TLS-handshake-first), and fault injection (`kill()`).
+
+```python
+from natsio.testing import NatsServerProcess
+
+async def test_against_a_real_server():
+    server = await NatsServerProcess(binary="nats-server").start()
+    try:
+        nc = await natsio.connect(server.url)
+        ...
+    finally:
+        await server.stop()
+```
+
+Binary discovery: pass `binary=` explicitly, or use `find_server_binary()`
+(checks `NATS_SERVER_BIN`, then `nats-server` on `PATH`).
+
+Part of the natsio extension tier: distribution `natsio-testing`, imported as
+`natsio.testing`. Pre-1.0, no API-stability promises.

natsio_testing-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["uv_build>=0.10,<0.11"]
+build-backend = "uv_build"
+
+[project]
+name = "natsio-testing"
+version = "0.1.0"
+description = "nats-server process management for tests — start, stop, and fault-inject real servers"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.13"
+authors = [{ name = "Corrupt Mane", email = "corruptmane@gmail.com" }]
+keywords = ["nats", "nats.io", "testing", "pytest", "nats-server"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Framework :: Pytest",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["natsio"]
+
+[project.urls]
+Homepage = "https://github.com/corruptmane/natsio"
+Repository = "https://github.com/corruptmane/natsio"
+Changelog = "https://github.com/corruptmane/natsio/blob/main/extensions/natsio-testing/CHANGELOG.md"
+
+[tool.uv.sources]
+natsio = { workspace = true }
+
+[tool.uv.build-backend]
+module-name = "natsio.testing"
+namespace = true

natsio_testing-0.1.0/src/natsio/testing/__init__.py

@@ -0,0 +1,10 @@
+"""Run real ``nats-server`` processes from a test suite.
+
+Start/stop, temporary config files, free-port allocation, readiness probing
+(plaintext and TLS-handshake-first servers), JetStream mode with an isolated
+store directory, and fault injection.
+"""
+
+from .server import NatsServerProcess, find_server_binary, free_port
+
+__all__ = ["NatsServerProcess", "find_server_binary", "free_port"]

natsio_testing-0.1.0/src/natsio/testing/server.py

@@ -0,0 +1,128 @@
+import asyncio
+import os
+import shutil
+import socket
+import tempfile
+from pathlib import Path
+from typing import Self
+
+__all__ = ["NatsServerProcess", "find_server_binary", "free_port"]
+
+
+def find_server_binary() -> str | None:
+    """The ``NATS_SERVER_BIN`` env var if set, else ``nats-server`` on PATH."""
+    candidate = os.environ.get("NATS_SERVER_BIN")
+    if candidate and Path(candidate).is_file():
+        return candidate
+    return shutil.which("nats-server")
+
+
+def free_port() -> int:
+    with socket.socket() as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+class NatsServerProcess:
+    """One managed ``nats-server`` subprocess.
+
+    ``config`` is written to a temporary file and passed via ``-c``.
+    ``jetstream=True`` enables JetStream with an isolated, auto-removed store
+    directory. ``kill()`` is SIGKILL — an abrupt loss with no FIN niceties —
+    for exercising reconnect and leadership-change paths.
+    """
+
+    def __init__(
+        self,
+        binary: str,
+        *,
+        port: int | None = None,
+        config: str | None = None,
+        jetstream: bool = False,
+        store_dir: str | os.PathLike[str] | None = None,
+    ) -> None:
+        self.binary = binary
+        self.port = port if port is not None else free_port()
+        self.config = config
+        self.jetstream = jetstream
+        # An explicit store_dir survives this instance — restart a "new" server
+        # on the same directory to simulate a server bounce that keeps its data.
+        self.store_dir = Path(store_dir) if store_dir is not None else None
+        self.process: asyncio.subprocess.Process | None = None
+        self._tmpdir: tempfile.TemporaryDirectory[str] | None = None
+
+    @property
+    def url(self) -> str:
+        return f"nats://127.0.0.1:{self.port}"
+
+    def _workdir(self) -> Path:
+        if self._tmpdir is None:
+            self._tmpdir = tempfile.TemporaryDirectory(prefix="natsio-test-server-")
+        return Path(self._tmpdir.name)
+
+    async def start(self, *, ready_timeout: float = 10.0) -> Self:
+        args = [self.binary, "-a", "127.0.0.1", "-p", str(self.port)]
+        if self.jetstream:
+            store = self.store_dir if self.store_dir is not None else self._workdir() / "jetstream"
+            args += ["-js", "-sd", str(store)]
+        if self.config is not None:
+            config_path = self._workdir() / "server.conf"
+            config_path.write_text(self.config)
+            args += ["-c", str(config_path)]
+        self.process = await asyncio.create_subprocess_exec(
+            *args,
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        await self._wait_ready(deadline=ready_timeout)
+        return self
+
+    async def _wait_ready(self, *, deadline: float) -> None:
+        async with asyncio.timeout(deadline):
+            while True:
+                assert self.process is not None
+                if self.process.returncode is not None:
+                    raise RuntimeError(f"nats-server exited with code {self.process.returncode} during startup")
+                try:
+                    reader, writer = await asyncio.open_connection("127.0.0.1", self.port)
+                except OSError:
+                    await asyncio.sleep(0.05)
+                    continue
+                try:
+                    # A TLS-handshake-first server accepts but stays silent until
+                    # the ClientHello — an accepted, open connection is "ready".
+                    banner = await asyncio.wait_for(reader.readline(), 0.25)
+                except TimeoutError:
+                    writer.close()
+                    return
+                except OSError:
+                    # Kill-and-restart on the same port: Linux can accept the
+                    # probe on the dead predecessor's socket and then RST it
+                    # mid-read. Not ready yet — keep probing. (TimeoutError is
+                    # an OSError subclass, so its clause must come first.)
+                    writer.close()
+                    await asyncio.sleep(0.05)
+                    continue
+                finally:
+                    writer.close()
+                if banner.startswith(b"INFO "):
+                    return
+                await asyncio.sleep(0.05)
+
+    async def stop(self) -> None:
+        if self.process is not None and self.process.returncode is None:
+            self.process.terminate()
+            try:
+                async with asyncio.timeout(5):
+                    await self.process.wait()
+            except TimeoutError:
+                self.process.kill()
+                await self.process.wait()
+        if self._tmpdir is not None:
+            self._tmpdir.cleanup()
+            self._tmpdir = None
+
+    def kill(self) -> None:
+        """SIGKILL the server (abrupt loss; the store directory is kept)."""
+        if self.process is not None and self.process.returncode is None:
+            self.process.kill()