pytest-nats 0.0.2.dev1__py3-none-any.whl

pytest_nats/__init__.py

@@ -0,0 +1,16 @@
+"""Pytest helpers for running test NATS servers."""
+
+from ._provisioning import ExecutableErrorCategory, GitHub, Local, Mise, NatsExecutableError, Provision
+from ._runtime import NatsServer, NatsServerError, nats_server_fixture
+
+__all__ = [
+    "ExecutableErrorCategory",
+    "GitHub",
+    "Local",
+    "Mise",
+    "NatsExecutableError",
+    "NatsServer",
+    "NatsServerError",
+    "Provision",
+    "nats_server_fixture",
+]

pytest_nats/_provisioning.py

@@ -0,0 +1,496 @@
+"""NATS executable selection and provisioning."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import platform
+import re
+import shutil
+import subprocess
+import tarfile
+import tempfile
+import time
+import zipfile
+from dataclasses import dataclass
+from enum import Enum
+from functools import cache
+from pathlib import Path
+from typing import cast
+
+import httpx2
+from platformdirs import user_cache_path
+
+_SEMANTIC_VERSION = (
+    r"(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)"
+    r"(?:-(?:(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)"
+    r"(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*))?"
+    r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?"
+)
+_NATS_VERSION_PATTERN = re.compile(rf"nats-server: v(?P<version>{_SEMANTIC_VERSION})")
+_SELECTOR_PATTERN = re.compile(r"^(?:latest|(?:0|[1-9]\d*)(?:\.(?:0|[1-9]\d*))?(?:\.(?:0|[1-9]\d*))?)$")
+_STABLE_VERSION_PATTERN = re.compile(r"^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$")
+_RELEASE_DOWNLOAD_URL = "https://github.com/nats-io/nats-server/releases/download"
+_RELEASE_API_URL = "https://api.github.com/repos/nats-io/nats-server/releases"
+_LOGGER = logging.getLogger(__name__)
+
+
+class ExecutableErrorCategory(str, Enum):
+    """Stable categories for NATS executable acquisition failures."""
+
+    CONFIGURATION = "configuration"
+    LOCAL = "local"
+    VERSION_RESOLUTION = "version_resolution"
+    PROVISIONING = "provisioning"
+
+
+class NatsExecutableError(Exception):
+    """Failure to acquire a NATS command."""
+
+    def __init__(self, category: ExecutableErrorCategory, message: str) -> None:
+        super().__init__(message)
+        self.category = category
+
+
+def _configuration_error(message: str) -> NatsExecutableError:
+    return NatsExecutableError(ExecutableErrorCategory.CONFIGURATION, message)
+
+
+def _local_value(value: object) -> str:
+    if isinstance(value, str):
+        executable = value
+    elif isinstance(value, os.PathLike):
+        executable = cast(os.PathLike[str] | os.PathLike[bytes], value).__fspath__()
+    else:
+        raise _configuration_error("Local executable must be a string or string-compatible path")
+    if not isinstance(executable, str):
+        raise _configuration_error("Local executable must be a string or string-compatible path")
+    if executable == "" or Path(executable) == Path("."):
+        raise _configuration_error("Local executable cannot be empty or the current directory")
+    return executable
+
+
+def _selector(value: object) -> str:
+    if not isinstance(value, str) or _SELECTOR_PATTERN.fullmatch(value) is None:
+        raise _configuration_error(f"invalid NATS version selector: {value!r}")
+    if value != "latest" and value.split(".", 1)[0] != "2":
+        raise _configuration_error("provisioning supports only NATS major version 2")
+    if value in ("2.0", "2.1") or value.startswith(("2.0.", "2.1.")):
+        raise _configuration_error("the selector cannot select a supported NATS release (>=2.2.0,<3)")
+    return value
+
+
+def _cache_value(value: object | None) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        path = value
+    elif isinstance(value, os.PathLike):
+        path = cast(os.PathLike[str] | os.PathLike[bytes], value).__fspath__()
+    else:
+        raise _configuration_error("cache_dir must be a string-compatible path")
+    if not isinstance(path, str):
+        raise _configuration_error("cache_dir must be a string-compatible path")
+    return path
+
+
+@dataclass(frozen=True, slots=True)
+class Local:
+    """Select a local NATS executable by command name or filesystem path."""
+
+    executable: str = "nats-server"
+
+    def __init__(self, executable: object = "nats-server") -> None:
+        object.__setattr__(self, "executable", _local_value(executable))
+
+
+@dataclass(frozen=True, slots=True)
+class Provision:
+    """Provision NATS with Mise when available, otherwise GitHub."""
+
+    version: str = "latest"
+    cache_dir: str | None = None
+
+    def __init__(self, version: object = "latest", *, cache_dir: object | None = None) -> None:
+        object.__setattr__(self, "version", _selector(version))
+        object.__setattr__(self, "cache_dir", _cache_value(cache_dir))
+
+
+@dataclass(frozen=True, slots=True)
+class Mise:
+    """Provision NATS through Mise."""
+
+    version: str = "latest"
+
+    def __init__(self, version: object = "latest") -> None:
+        object.__setattr__(self, "version", _selector(version))
+
+
+@dataclass(frozen=True, slots=True)
+class GitHub:
+    """Provision NATS from an official GitHub release."""
+
+    version: str = "latest"
+    cache_dir: str | None = None
+
+    def __init__(self, version: object = "latest", *, cache_dir: object | None = None) -> None:
+        object.__setattr__(self, "version", _selector(version))
+        object.__setattr__(self, "cache_dir", _cache_value(cache_dir))
+
+
+NatsExecutableSource = Local | Provision | Mise | GitHub
+
+
+@dataclass(frozen=True, slots=True)
+class AcquiredNats:
+    """An acquired NATS command and its resolved NATS version."""
+
+    command: tuple[str, ...]
+    resolved_version: str
+
+
+@dataclass(frozen=True, slots=True)
+class _GitHubPlatform:
+    cache_system: str
+    cache_architecture: str
+    archive_system: str
+    archive_architecture: str
+
+    @property
+    def executable_name(self) -> str:
+        return "nats-server.exe" if self.cache_system == "windows" else "nats-server"
+
+
+def acquire_nats(source: NatsExecutableSource, root_path: Path) -> AcquiredNats:
+    """Acquire one NATS command during fixture setup."""
+    if isinstance(source, Local):
+        return _acquire_local(source, root_path)
+    if isinstance(source, Provision):
+        mise = shutil.which("mise")
+        if mise is not None:
+            return _acquire_mise(Mise(source.version), Path(mise))
+        return _acquire_github(GitHub(source.version, cache_dir=source.cache_dir), root_path)
+    if isinstance(source, Mise):
+        mise = shutil.which("mise")
+        if mise is None:
+            raise NatsExecutableError(
+                ExecutableErrorCategory.PROVISIONING,
+                "Mise was requested but the mise command is not available on PATH",
+            )
+        return _acquire_mise(source, Path(mise))
+    return _acquire_github(source, root_path)
+
+
+def _acquire_local(source: Local, root_path: Path) -> AcquiredNats:
+    value = os.path.expanduser(source.executable)
+    path = Path(value)
+    try:
+        if not path.is_absolute() and len(path.parts) == 1:
+            found = shutil.which(value)
+            if found is None:
+                raise FileNotFoundError(f"command not found on PATH: {value}")
+            path = Path(found)
+        elif not path.is_absolute():
+            path = root_path / path
+        executable = _resolved_path(path)
+        _validate_executable(executable)
+        version = _local_executable_version(executable)
+        if version.split(".", 1)[0] != "2":
+            raise ValueError(f"expected a NATS 2.x executable, got {version}")
+        return AcquiredNats((str(executable),), version)
+    except Exception as exc:
+        raise NatsExecutableError(
+            ExecutableErrorCategory.LOCAL,
+            f"failed to acquire local NATS executable {source.executable!r}",
+        ) from exc
+
+
+@cache
+def _cached_mise(source: Mise, mise: Path) -> AcquiredNats:
+    backend = f"github:nats-io/nats-server@{source.version}"
+    try:
+        subprocess.run([str(mise), "install", backend], check=True, capture_output=True, text=True, timeout=300)
+        location = subprocess.run(
+            [str(mise), "where", backend], check=True, capture_output=True, text=True, timeout=300
+        )
+        installation = _resolved_path(Path(location.stdout.strip()))
+        executable = installation / _host_executable_name()
+        _validate_executable(executable)
+        resolved_version = (
+            source.version if source.version.count(".") == 2 else _mise_resolved_version(mise, installation)
+        )
+        return AcquiredNats((str(executable),), resolved_version)
+    except Exception as exc:
+        details = ""
+        if isinstance(exc, subprocess.CalledProcessError):
+            output = (exc.stderr or exc.stdout or "").strip()
+            details = f": {output}" if output else ""
+        raise NatsExecutableError(
+            ExecutableErrorCategory.PROVISIONING,
+            f"Mise failed to provision NATS Server for selector {source.version!r}{details}",
+        ) from exc
+
+
+def _acquire_mise(source: Mise, mise: Path) -> AcquiredNats:
+    return _cached_mise(source, _resolved_path(mise))
+
+
+def _mise_resolved_version(mise: Path, installation: Path) -> str:
+    listing = subprocess.run([str(mise), "ls", "--json"], check=True, capture_output=True, text=True, timeout=30)
+    payload: object = json.loads(listing.stdout)
+    if not isinstance(payload, dict):
+        raise TypeError("Mise tool listing is not an object")
+    for installations in cast(dict[object, object], payload).values():
+        if not isinstance(installations, list):
+            continue
+        for item in cast(list[object], installations):
+            if not isinstance(item, dict):
+                continue
+            record = cast(dict[object, object], item)
+            version = record.get("version")
+            install_path = record.get("install_path")
+            if (
+                isinstance(version, str)
+                and isinstance(install_path, str)
+                and _resolved_path(Path(install_path)) == installation
+            ):
+                return version
+    raise ValueError(f"Mise did not report the resolved version for {installation}")
+
+
+def _acquire_github(source: GitHub, root_path: Path) -> AcquiredNats:
+    version = source.version if source.version.count(".") == 2 else _resolve_version(source.version)
+    platform_value = _github_platform()
+    cache_root = _cache_root(source.cache_dir, root_path)
+    return AcquiredNats(_provision_from_github(version, platform_value, cache_root), version)
+
+
+@cache
+def _resolve_version(selector: str) -> str:
+    matches: list[tuple[int, int, int]] = []
+    try:
+        with httpx2.Client(
+            timeout=30,
+            follow_redirects=True,
+            headers=_github_headers(os.environ.get("GITHUB_TOKEN")),
+        ) as client:
+            page = 1
+            while True:
+                response = client.get(f"{_RELEASE_API_URL}?per_page=100&page={page}")
+                response.raise_for_status()
+                payload_object: object = response.json()
+                if not isinstance(payload_object, list):
+                    raise TypeError("GitHub release response is not a list")
+                payload = cast(list[object], payload_object)
+                for item in payload:
+                    if not isinstance(item, dict):
+                        raise TypeError("GitHub release response contains a non-object")
+                    release = cast(dict[object, object], item)
+                    if release.get("draft") is not False or release.get("prerelease") is not False:
+                        continue
+                    tag_name = release.get("tag_name")
+                    if not isinstance(tag_name, str):
+                        raise TypeError("GitHub release has no string tag_name")
+                    match = _STABLE_VERSION_PATTERN.fullmatch(tag_name)
+                    if match is None:
+                        continue
+                    version = (int(match.group(1)), int(match.group(2)), int(match.group(3)))
+                    if version >= (2, 2, 0) and version[0] == 2 and _selector_matches(selector, version):
+                        matches.append(version)
+                if len(payload) < 100:
+                    break
+                page += 1
+    except Exception as exc:
+        raise NatsExecutableError(
+            ExecutableErrorCategory.VERSION_RESOLUTION,
+            f"failed to resolve NATS version selector {selector!r}",
+        ) from exc
+    if not matches:
+        raise NatsExecutableError(
+            ExecutableErrorCategory.VERSION_RESOLUTION,
+            f"no stable NATS 2.x release matches {selector!r}",
+        )
+    return ".".join(str(part) for part in max(matches))
+
+
+def _selector_matches(selector: str, version: tuple[int, int, int]) -> bool:
+    if selector == "latest":
+        return True
+    requested = tuple(int(part) for part in selector.split("."))
+    return version[: len(requested)] == requested
+
+
+def _github_platform() -> _GitHubPlatform:
+    systems = {"Linux": ("linux", "linux"), "Darwin": ("macos", "darwin"), "Windows": ("windows", "windows")}
+    architectures = {
+        "x86_64": ("amd64", "amd64"),
+        "AMD64": ("amd64", "amd64"),
+        "aarch64": ("arm64", "arm64"),
+        "arm64": ("arm64", "arm64"),
+        "ARM64": ("arm64", "arm64"),
+    }
+    system_name = platform.system()
+    machine_name = platform.machine()
+    try:
+        system, archive_system = systems[system_name]
+        architecture, archive_architecture = architectures[machine_name]
+    except KeyError as exc:
+        raise NatsExecutableError(
+            ExecutableErrorCategory.PROVISIONING,
+            f"GitHub provisioning is unsupported on {system_name} {machine_name}",
+        ) from exc
+    return _GitHubPlatform(system, architecture, archive_system, archive_architecture)
+
+
+def _cache_root(value: str | None, root_path: Path) -> Path:
+    if value is None:
+        return _resolved_path(user_cache_path("pytest-nats"))
+    path = Path(os.path.expanduser(value))
+    return _resolved_path(path if path.is_absolute() else root_path / path)
+
+
+def _provision_from_github(version: str, target_platform: _GitHubPlatform, cache_root: Path) -> tuple[str, ...]:
+    archive_path: Path | None = None
+    executable_path: Path | None = None
+    target = _resolved_path(
+        cache_root
+        / version
+        / target_platform.cache_system
+        / target_platform.cache_architecture
+        / target_platform.executable_name
+    )
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        if target.exists():
+            if target.is_file() and os.access(target, os.X_OK):
+                return (str(target),)
+            if not target.is_dir():
+                target.unlink()
+        extension = "zip" if target_platform.cache_system == "windows" else "tar.gz"
+        archive_name = f"nats-server-v{version}-{target_platform.archive_system}-{target_platform.archive_architecture}.{extension}"
+        release_url = f"{_RELEASE_DOWNLOAD_URL}/v{version}"
+        archive_path = _temporary_path(target.parent, ".archive-")
+        executable_path = _temporary_path(target.parent, ".executable-")
+        with httpx2.Client(
+            timeout=30, follow_redirects=True, headers=_github_headers(os.environ.get("GITHUB_TOKEN"))
+        ) as client:
+            _download(client, f"{release_url}/{archive_name}", archive_path)
+            checksum_response = client.get(f"{release_url}/SHA256SUMS")
+            checksum_response.raise_for_status()
+            _verify_checksum(archive_path, archive_name, checksum_response.content)
+        member_name = (
+            f"nats-server-v{version}-{target_platform.archive_system}-{target_platform.archive_architecture}/"
+            f"{target_platform.executable_name}"
+        )
+        _extract_executable(archive_path, member_name, executable_path, extension)
+        executable_path.chmod(executable_path.stat().st_mode | 0o755)
+        _validate_executable(executable_path)
+        _publish(executable_path, target)
+        return (str(target),)
+    except NatsExecutableError:
+        raise
+    except Exception as exc:
+        raise NatsExecutableError(
+            ExecutableErrorCategory.PROVISIONING,
+            f"failed to provision NATS Server {version} from GitHub",
+        ) from exc
+    finally:
+        if archive_path is not None:
+            archive_path.unlink(missing_ok=True)
+        if executable_path is not None:
+            executable_path.unlink(missing_ok=True)
+
+
+def _host_executable_name() -> str:
+    return "nats-server.exe" if os.name == "nt" else "nats-server"
+
+
+def _validate_executable(path: Path) -> None:
+    if not path.is_file():
+        raise FileNotFoundError(f"NATS executable is not a regular file: {path}")
+    if not os.access(path, os.X_OK):
+        raise PermissionError(f"NATS executable is not executable: {path}")
+
+
+def _local_executable_version(executable: Path) -> str:
+    result = subprocess.run([str(executable), "--version"], check=True, capture_output=True, text=True, timeout=5)
+    for line in (*result.stdout.splitlines(), *result.stderr.splitlines()):
+        match = _NATS_VERSION_PATTERN.fullmatch(line.strip())
+        if match is not None:
+            return match.group("version")
+    raise ValueError("unrecognized NATS Server version output")
+
+
+def _github_headers(token: str | None) -> dict[str, str]:
+    return {"Authorization": f"Bearer {token}"} if token else {}
+
+
+def _temporary_path(directory: Path, prefix: str) -> Path:
+    descriptor, name = tempfile.mkstemp(dir=directory, prefix=prefix)
+    os.close(descriptor)
+    return Path(name)
+
+
+def _resolved_path(path: Path) -> Path:
+    resolved = path.resolve()
+    text = str(resolved)
+    if text.startswith("\\\\?\\UNC\\"):
+        return Path("\\\\" + text[8:])
+    if text.startswith("\\\\?\\"):
+        return Path(text[4:])
+    return resolved
+
+
+def _publish(source: Path, target: Path) -> None:
+    for attempt in range(5):
+        try:
+            os.replace(source, target)
+            return
+        except PermissionError:
+            if attempt == 4:
+                raise
+            time.sleep(0.05 * 2**attempt)
+
+
+def _download(client: httpx2.Client, url: str, destination: Path) -> None:
+    with client.stream("GET", url) as response:
+        response.raise_for_status()
+        with destination.open("wb") as stream:
+            for chunk in response.iter_bytes():
+                stream.write(chunk)
+
+
+def _verify_checksum(archive_path: Path, archive_name: str, checksums: bytes) -> None:
+    expected = None
+    for line in checksums.decode("utf-8").splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[1] == archive_name and re.fullmatch(r"[0-9a-fA-F]{64}", parts[0]):
+            expected = parts[0].lower()
+            break
+    if expected is None:
+        raise ValueError(f"SHA256SUMS has no valid entry for {archive_name}")
+    actual = hashlib.sha256(archive_path.read_bytes()).hexdigest()
+    if actual != expected:
+        raise ValueError(f"checksum mismatch for {archive_name}")
+
+
+def _extract_executable(archive_path: Path, member_name: str, destination: Path, extension: str) -> None:
+    if extension == "zip":
+        with zipfile.ZipFile(archive_path) as archive:
+            member = archive.getinfo(member_name)
+            if member.is_dir():
+                raise ValueError(f"archive member is not a file: {member_name}")
+            with archive.open(member) as source, destination.open("wb") as target:
+                shutil.copyfileobj(source, target)
+        return
+    with tarfile.open(archive_path, mode="r:gz") as archive:
+        member = archive.getmember(member_name)
+        if not member.isfile():
+            raise ValueError(f"archive member is not a file: {member_name}")
+        source = archive.extractfile(member)
+        if source is None:
+            raise ValueError(f"could not read archive member: {member_name}")
+        with source, destination.open("wb") as target:
+            shutil.copyfileobj(source, target)

pytest_nats/_runtime.py

@@ -0,0 +1,422 @@
+"""Private lifecycle implementation for test NATS server fixtures."""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import socket
+import subprocess
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Iterator
+from pathlib import Path
+from types import TracebackType
+from typing import Literal, cast
+from urllib.parse import urlparse
+
+import pytest
+
+from ._provisioning import (
+    ExecutableErrorCategory,
+    GitHub,
+    Local,
+    Mise,
+    NatsExecutableError,
+    NatsExecutableSource,
+    Provision,
+    acquire_nats,
+)
+
+FixtureScope = Literal["function", "module", "session"]
+_HOST = "127.0.0.1"
+_DEFAULT_MAX_MEMORY_STORE = 256 * 1024 * 1024
+_DEFAULT_MAX_FILE_STORE = 1024 * 1024 * 1024
+_SHUTDOWN_TIMEOUT = 5.0
+_NO_PROXY_OPENER = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+
+class NatsServerError(Exception):
+    """A test NATS server startup or lifecycle failure."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        returncode: int | None = None,
+        stdout: str = "",
+        stderr: str = "",
+    ) -> None:
+        details = [message]
+        if returncode is not None:
+            details.append(f"return code: {returncode}")
+        if stdout:
+            details.append(f"stdout:\n{stdout}")
+        if stderr:
+            details.append(f"stderr:\n{stderr}")
+        super().__init__("\n".join(details))
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+
+
+class _OutputCapture:
+    def __init__(self) -> None:
+        self._chunks: list[str] = []
+        self._lock = threading.Lock()
+
+    def append(self, chunk: str) -> None:
+        with self._lock:
+            self._chunks.append(chunk)
+
+    def snapshot(self) -> str:
+        with self._lock:
+            return "".join(self._chunks)
+
+
+class NatsServer:
+    """Read-only connection metadata and diagnostics for a test NATS server."""
+
+    __slots__ = ("_host", "_jetstream_enabled", "_port", "_resolved_version", "_stderr", "_stdout")
+
+    def __init__(
+        self,
+        *,
+        host: str,
+        port: int,
+        resolved_version: str,
+        jetstream_enabled: bool,
+        stdout: _OutputCapture,
+        stderr: _OutputCapture,
+    ) -> None:
+        self._host = host
+        self._port = port
+        self._resolved_version = resolved_version
+        self._jetstream_enabled = jetstream_enabled
+        self._stdout = stdout
+        self._stderr = stderr
+
+    @property
+    def url(self) -> str:
+        """Return the client connection URL."""
+        return f"nats://{self._host}:{self._port}"
+
+    @property
+    def host(self) -> str:
+        """Return the IPv4 loopback host."""
+        return self._host
+
+    @property
+    def port(self) -> int:
+        """Return the dynamically selected client port."""
+        return self._port
+
+    @property
+    def resolved_version(self) -> str:
+        """Return the resolved NATS version."""
+        return self._resolved_version
+
+    @property
+    def jetstream_enabled(self) -> bool:
+        """Return whether JetStream is enabled."""
+        return self._jetstream_enabled
+
+    @property
+    def stdout(self) -> str:
+        """Return all server standard output captured so far."""
+        return self._stdout.snapshot()
+
+    @property
+    def stderr(self) -> str:
+        """Return all server standard error captured so far."""
+        return self._stderr.snapshot()
+
+
+class _ServerProcess:
+    def __init__(
+        self,
+        source: NatsExecutableSource,
+        root_path: Path,
+        *,
+        jetstream: bool,
+        max_memory_store: int,
+        max_file_store: int,
+        startup_timeout: float,
+    ) -> None:
+        self._source = source
+        self._root_path = root_path
+        self._jetstream = jetstream
+        self._max_memory_store = max_memory_store
+        self._max_file_store = max_file_store
+        self._startup_timeout = startup_timeout
+        self._temporary_directory: tempfile.TemporaryDirectory[str] | None = None
+        self._process: subprocess.Popen[str] | None = None
+        self._readers: list[threading.Thread] = []
+        self._stdout = _OutputCapture()
+        self._stderr = _OutputCapture()
+
+    def __enter__(self) -> NatsServer:
+        try:
+            provisioned = acquire_nats(self._source, self._root_path)
+            self._temporary_directory = tempfile.TemporaryDirectory(prefix="pytest-nats-")
+            temporary_path = Path(self._temporary_directory.name)
+            config_path = temporary_path / "nats.conf"
+            config_path.write_text(
+                _server_config(
+                    temporary_path / "jetstream",
+                    self._jetstream,
+                    self._max_memory_store,
+                    self._max_file_store,
+                ),
+                encoding="utf-8",
+            )
+            self._process = subprocess.Popen(
+                (*provisioned.command, "-c", str(config_path), "--ports_file_dir", str(temporary_path)),
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                creationflags=int(getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)) if os.name == "nt" else 0,
+            )
+            self._start_readers()
+            client_port = self._wait_until_ready(temporary_path)
+            return NatsServer(
+                host=_HOST,
+                port=client_port,
+                resolved_version=provisioned.resolved_version,
+                jetstream_enabled=self._jetstream,
+                stdout=self._stdout,
+                stderr=self._stderr,
+            )
+        except NatsExecutableError:
+            self._cleanup()
+            raise
+        except NatsServerError:
+            self._stop()
+            self._cleanup()
+            raise
+        except Exception as exc:
+            self._stop()
+            error = self._error("failed to start test NATS server")
+            self._cleanup()
+            raise error from exc
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> bool:
+        del exc_type, exc, traceback
+        process = self._process
+        unexpected_returncode = process.poll() if process is not None else None
+        self._stop()
+        error = (
+            self._error("test NATS server exited unexpectedly", returncode=unexpected_returncode)
+            if unexpected_returncode is not None
+            else None
+        )
+        self._cleanup()
+        if error is not None:
+            raise error
+        return False
+
+    def _start_readers(self) -> None:
+        assert self._process is not None
+        assert self._process.stdout is not None
+        assert self._process.stderr is not None
+        for stream, capture in ((self._process.stdout, self._stdout), (self._process.stderr, self._stderr)):
+            reader = threading.Thread(target=_drain, args=(stream.readline, capture), daemon=True)
+            reader.start()
+            self._readers.append(reader)
+
+    def _wait_until_ready(self, temporary_path: Path) -> int:
+        deadline = time.monotonic() + self._startup_timeout
+        last_error: Exception | None = None
+        while time.monotonic() < deadline:
+            assert self._process is not None
+            returncode = self._process.poll()
+            if returncode is not None:
+                self._join_readers()
+                raise self._error("test NATS server exited during startup", returncode=returncode)
+            try:
+                client_port, monitor_port = _read_ports(temporary_path)
+                _check_nats(client_port)
+                _check_health(monitor_port, self._jetstream)
+                return client_port
+            except (OSError, TypeError, ValueError, json.JSONDecodeError, urllib.error.URLError) as exc:
+                last_error = exc
+                time.sleep(min(0.05, max(0.0, deadline - time.monotonic())))
+        raise self._error(
+            f"test NATS server did not become ready within {self._startup_timeout:g} seconds"
+        ) from last_error
+
+    def _stop(self) -> None:
+        process = self._process
+        if process is not None and process.poll() is None:
+            if os.name == "nt":
+                process.send_signal(cast(int, getattr(signal, "CTRL_BREAK_EVENT")))  # noqa: B009 - Windows-only.
+            else:
+                process.terminate()
+            try:
+                process.wait(timeout=_SHUTDOWN_TIMEOUT)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+        self._join_readers()
+
+    def _join_readers(self) -> None:
+        for reader in self._readers:
+            reader.join(timeout=1)
+
+    def _cleanup(self) -> None:
+        if self._temporary_directory is not None:
+            for attempt in range(5):
+                try:
+                    self._temporary_directory.cleanup()
+                    break
+                except PermissionError:
+                    if attempt == 4:
+                        raise
+                    time.sleep(0.05 * 2**attempt)
+            self._temporary_directory = None
+
+    def _error(self, message: str, *, returncode: int | None = None) -> NatsServerError:
+        if returncode is None and self._process is not None:
+            returncode = self._process.poll()
+        return NatsServerError(
+            message,
+            returncode=returncode,
+            stdout=self._stdout.snapshot(),
+            stderr=self._stderr.snapshot(),
+        )
+
+
+def _drain(readline: Callable[[], str], capture: _OutputCapture) -> None:
+    while chunk := readline():
+        capture.append(chunk)
+
+
+def _server_config(
+    store_directory: Path,
+    jetstream: bool,
+    max_memory_store: int,
+    max_file_store: int,
+) -> str:
+    lines = [
+        f'host: "{_HOST}"',
+        "port: -1",
+        f'http: "{_HOST}:-1"',
+    ]
+    if jetstream:
+        lines.extend(
+            [
+                "jetstream {",
+                f"  store_dir: {json.dumps(str(store_directory))}",
+                f"  max_mem: {max_memory_store}",
+                f"  max_file: {max_file_store}",
+                "}",
+            ]
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _read_ports(directory: Path) -> tuple[int, int]:
+    ports_files = list(directory.glob("*.ports"))
+    if not ports_files:
+        raise FileNotFoundError("NATS ports file is not available")
+    payload: object = json.loads(ports_files[0].read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise TypeError("NATS ports file is not an object")
+    ports = cast(dict[object, object], payload)
+    return _port_from_urls(ports.get("nats")), _port_from_urls(ports.get("monitoring"))
+
+
+def _port_from_urls(value: object) -> int:
+    if not isinstance(value, list) or not value or not isinstance(value[0], str):
+        raise ValueError("NATS ports file has no listener URL")
+    parsed = urlparse(value[0])
+    if parsed.hostname != _HOST or parsed.port is None:
+        raise ValueError("NATS listener is not bound to IPv4 loopback")
+    return parsed.port
+
+
+def _check_nats(port: int) -> None:
+    with socket.create_connection((_HOST, port), timeout=0.2) as connection:
+        connection.settimeout(0.2)
+        info = connection.recv(65536)
+        if not info.startswith(b"INFO "):
+            raise ValueError("NATS server did not send INFO")
+        connection.sendall(b"PING\r\n")
+        response = connection.recv(65536)
+        if b"PONG\r\n" not in response:
+            raise ValueError("NATS server did not answer PING")
+
+
+def _check_health(port: int, jetstream: bool) -> None:
+    query = "?js-enabled-only=true" if jetstream else ""
+    with _NO_PROXY_OPENER.open(f"http://{_HOST}:{port}/healthz{query}", timeout=0.2) as response:
+        payload: object = json.load(response)
+    if not isinstance(payload, dict) or cast(dict[object, object], payload).get("status") != "ok":
+        raise ValueError("NATS health endpoint did not report ok")
+
+
+def nats_server_fixture(
+    binary: NatsExecutableSource | None = None,
+    *,
+    scope: FixtureScope = "function",
+    jetstream: bool = False,
+    max_memory_store: int = _DEFAULT_MAX_MEMORY_STORE,
+    max_file_store: int = _DEFAULT_MAX_FILE_STORE,
+    startup_timeout: float = 10.0,
+) -> Callable[[], Iterator[NatsServer]]:
+    """Return a pytest fixture definition owning one test NATS server."""
+    scope_value = cast(object, scope)
+    if scope_value not in ("function", "module", "session"):
+        raise ValueError(f"unsupported fixture scope: {scope!r}")
+    if not _is_boolean(jetstream):
+        raise ValueError("jetstream must be a boolean")
+    for name, value in cast(
+        tuple[tuple[str, object], ...],
+        (("max_memory_store", max_memory_store), ("max_file_store", max_file_store)),
+    ):
+        if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+            raise ValueError(f"{name} must be a positive integer byte count")
+    if not _is_positive_number(startup_timeout):
+        raise ValueError("startup_timeout must be a positive duration in seconds")
+    if binary is None:
+        source: NatsExecutableSource = Local()
+    elif isinstance(cast(object, binary), (Local, Provision, Mise, GitHub)):
+        source = binary
+    else:
+        raise NatsExecutableError(
+            ExecutableErrorCategory.CONFIGURATION,
+            "binary must be Local, Provision, Mise, GitHub, or None",
+        )
+
+    @pytest.fixture(scope=scope)
+    def fixture_definition(request: pytest.FixtureRequest) -> Iterator[NatsServer]:
+        with _ServerProcess(
+            source,
+            request.config.rootpath,
+            jetstream=jetstream,
+            max_memory_store=max_memory_store,
+            max_file_store=max_file_store,
+            startup_timeout=float(startup_timeout),
+        ) as server:
+            yield server
+
+    return fixture_definition
+
+
+def _is_boolean(value: object) -> bool:
+    return isinstance(value, bool)
+
+
+def _is_positive_number(value: object) -> bool:
+    return not isinstance(value, bool) and isinstance(value, (int, float)) and value > 0

pytest_nats-0.0.2.dev1.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: pytest-nats
+Version: 0.0.2.dev1
+Summary: Pytest helpers for running ad-hoc NATS servers
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Project-URL: Repository, https://github.com/m3nowak/pytest-nats
+Project-URL: Issues, https://github.com/m3nowak/pytest-nats/issues
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.12.0
+Requires-Dist: platformdirs>=4.11.5
+Requires-Dist: pytest>=8.4.2
+Description-Content-Type: text/markdown
+
+# pytest-nats
+
+Pytest helpers for starting isolated test NATS servers.
+
+## Installation
+
+```shell
+pip install pytest-nats
+```
+
+pytest-nats does not register a global pytest plugin. Declare each server fixture
+explicitly in `conftest.py`; the variable name becomes the fixture name:
+
+```python
+from pytest_nats import nats_server_fixture
+
+nats_server = nats_server_fixture()
+```
+
+Tests receive a read-only `NatsServer` with the client URL, host, dynamic port,
+resolved NATS version, JetStream state, and live `stdout` and `stderr` snapshots:
+
+```python
+from pytest_nats import NatsServer
+
+
+def test_messaging(nats_server: NatsServer) -> None:
+    assert nats_server.url == f"nats://127.0.0.1:{nats_server.port}"
+    assert not nats_server.jetstream_enabled
+```
+
+The fixture binds its unauthenticated client and internal monitoring listeners
+only to `127.0.0.1`, selects dynamic ports, and waits for both a NATS protocol
+exchange and the health endpoint before yielding. It terminates the server and
+removes generated configuration and data at the end of the selected scope.
+
+## JetStream
+
+Enable JetStream when declaring the fixture. One server supports both memory-
+and file-backed streams; client code remains responsible for creating streams
+and consumers.
+
+```python
+from pytest_nats import nats_server_fixture
+
+jetstream_server = nats_server_fixture(
+    jetstream=True,
+    max_memory_store=512 * 1024 * 1024,
+    max_file_store=2 * 1024 * 1024 * 1024,
+)
+```
+
+The default aggregate limits are 256 MiB of memory and 1 GiB of file storage.
+File data is isolated per server and removed during teardown.
+
+## Fixture Scope
+
+Function scope is the default. Module and session scopes retain server and
+JetStream state for their normal pytest lifetime:
+
+```python
+module_nats = nats_server_fixture(scope="module")
+session_nats = nats_server_fixture(scope="session", jetstream=True)
+```
+
+Supported scopes are `function`, `module`, and `session`.
+
+## NATS executable selection
+
+By default, pytest-nats finds `nats-server` on setup-time `PATH` and validates
+that it reports a NATS 2.x semantic version. Use `Local` to select another
+command name or path. Relative paths containing a directory are resolved from
+pytest's root path.
+
+```python
+from pathlib import Path
+
+from pytest_nats import GitHub, Local, Mise, Provision, nats_server_fixture
+
+default_local_nats = nats_server_fixture()
+alternate_local_nats = nats_server_fixture(Local("nats-server-another"))
+local_path_nats = nats_server_fixture(Local(Path("tools/nats-server")))
+latest_nats = nats_server_fixture(Provision())
+mise_nats = nats_server_fixture(Mise("2.12"))
+github_nats = nats_server_fixture(GitHub("2.12.15", cache_dir=Path(".cache/nats")))
+```
+
+`Local`, `Provision`, `Mise`, and `GitHub` are immutable source values. Raw
+strings and paths are not accepted as the fixture's `binary` argument.
+`Provision` prefers Mise when it is available on setup-time `PATH` and uses
+GitHub otherwise. Automatic provisioning accepts `latest`, major, major-minor,
+and exact stable NATS 2.x selectors that can select releases starting at 2.2.0.
+`startup_timeout` sets the positive setup deadline in seconds and defaults to
+10 seconds.
+
+### mise
+
+[mise](https://mise.jdx.dev/) is a development-tool version manager. `Mise`
+asks the `mise` executable on `PATH` to install and locate the selector through its
+[GitHub backend](https://mise.jdx.dev/dev-tools/backends/github.html). The
+selector is passed directly to Mise. Successful acquisition is reused for the
+rest of the pytest process, while failures remain retryable.
+
+### GitHub
+
+`GitHub` downloads official
+[NATS Server releases](https://github.com/nats-io/nats-server/releases),
+verifies their published checksums, and atomically stores executables in the
+selected cache directory. Existing regular executable cache entries are trusted
+without running or rehashing them. Set the optional `GITHUB_TOKEN` environment variable
+to authenticate GitHub API and download requests, which can avoid anonymous API
+rate limits. See GitHub's
+[personal access token documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+for token creation and handling guidance.
+
+Executable lookup, version resolution, and provisioning failures raise
+`NatsExecutableError`. Its `category` is an `ExecutableErrorCategory` value.
+Server startup and lifecycle failures raise `NatsServerError`; its `returncode`,
+`stdout`, and `stderr` attributes retain available diagnostics.
+
+## Development
+
+Install [mise](https://mise.jdx.dev/getting-started.html), then install the project
+tools and dependencies:
+
+```shell
+mise run install
+mise run setup
+```
+
+Run tests and checks:
+
+```shell
+mise run test
+mise run check
+```
+
+Apply automatic lint and formatting fixes:
+
+```shell
+mise run fix
+```
+
+## Releasing
+
+Releases run from `.github/workflows/release.yml`. The workflow accepts a stable,
+canonical PEP 440 version, runs the complete CI workflow, builds and validates
+the source distribution and wheel, publishes them to PyPI, then publishes the
+draft GitHub Release. Run it from the `main` branch in the GitHub Actions UI.
+The first intended version is `0.0.1`, which creates tag `v0.0.1`.
+
+Before the first release, create a pending Trusted Publisher on PyPI with these
+values:
+
+- PyPI project: `pytest-nats`
+- GitHub owner: `m3nowak`
+- GitHub repository: `pytest-nats`
+- Workflow filename: `release.yml`
+- Environment: `pypi`
+
+Create the `pypi` environment in the GitHub repository without required
+reviewers. The workflow requests an OIDC token only in the PyPI publication job;
+no PyPI API token is needed.

pytest_nats-0.0.2.dev1.dist-info/RECORD

@@ -0,0 +1,9 @@
+pytest_nats-0.0.2.dev1.dist-info/METADATA,sha256=P8m6LS0vqZ_WMrYDSojlMTaMiB7uJLZ0h7E31sPm8fY,6509
+pytest_nats-0.0.2.dev1.dist-info/WHEEL,sha256=VP-D4TPS230sME9Z3vb3INXvo1yt0924YRm5AOsk_dE,90
+pytest_nats-0.0.2.dev1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+pytest_nats-0.0.2.dev1.dist-info/licenses/LICENSE,sha256=g3vPTnVy-mf3J728OL78KVUBAqsuaRoqNA_ZkGQa8Dk,1071
+pytest_nats/__init__.py,sha256=4vnbo1LM2jzcOC1BPnvK2RCucZRHFYbVmP2svQhRyjA,425
+pytest_nats/_provisioning.py,sha256=wcjXLs0_S4WKSu2y2UfnypRdKQL5gkUgFtzBvU0uGPE,19532
+pytest_nats/_runtime.py,sha256=0-Arb7u7W5PVMYHyGk99HQmb8dllvS7JXFqOyw9x638,14399
+pytest_nats/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pytest_nats-0.0.2.dev1.dist-info/RECORD,,

pytest_nats-0.0.2.dev1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.9)
+Root-Is-Purelib: true
+Tag: py3-none-any

pytest_nats-0.0.2.dev1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+

pytest_nats-0.0.2.dev1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikołaj Nowak
+
+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.