singleserver 0.1.0__py3-none-any.whl

singleserver/__init__.py

@@ -0,0 +1,42 @@
+"""
+singleserver - Manage singleton server processes across multiple workers.
+
+A Python library for coordinating a single instance of a server process
+across multiple workers/processes using atomic socket binding.
+
+Example:
+    from singleserver import SingleServer
+
+    # Define the server
+    api_server = SingleServer(
+        name="api-server",
+        command=["python", "-m", "my_api", "--port", "{port}"],
+        port=8765,
+    )
+
+    # Connect (starts if needed, connects if already running)
+    with api_server.connect() as client:
+        response = client.get("/data.json")
+"""
+
+from .client import ServerClient, ServerNotReady
+from .lock import LockFile, SocketLock
+from .process import ProcessOwner, ProcessState
+from .server import ManagedServer, SingleServer
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main classes
+    "SingleServer",
+    "ManagedServer",
+    # Supporting classes
+    "ServerClient",
+    "ProcessOwner",
+    "ProcessState",
+    # Lock utilities
+    "SocketLock",
+    "LockFile",
+    # Exceptions
+    "ServerNotReady",
+]

singleserver/client.py

@@ -0,0 +1,305 @@
+"""
+Client for connecting to managed servers.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import time
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+from urllib.parse import urljoin
+
+try:
+    import requests
+    from requests.adapters import HTTPAdapter
+    from urllib3.util.retry import Retry
+
+    REQUESTS_AVAILABLE = True
+except ImportError:
+    REQUESTS_AVAILABLE = False
+
+try:
+    import httpx  # noqa: F401
+
+    HTTPX_AVAILABLE = True
+except ImportError:
+    HTTPX_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+
+class ServerNotReady(Exception):
+    """Raised when the server is not ready within the timeout."""
+
+    pass
+
+
+class ServerClient:
+    """
+    Client for connecting to a managed server.
+
+    Provides:
+    - wait_ready() to block until the server is accepting connections
+    - HTTP request methods (get, post, etc.) if requests library is available
+    - Base URL construction for manual HTTP client usage
+    """
+
+    def __init__(
+        self,
+        host: str = "127.0.0.1",
+        port: int | None = None,
+        socket_path: str | Path | None = None,
+        health_check_url: str = "/",
+        startup_timeout: float = 30.0,
+    ):
+        """
+        Initialize the client.
+
+        Args:
+            host: Host to connect to (for TCP connections).
+            port: TCP port to connect to.
+            socket_path: Unix socket path to connect to.
+            health_check_url: URL path to use for readiness checks.
+            startup_timeout: Max seconds to wait for server to be ready.
+        """
+        if port is None and socket_path is None:
+            raise ValueError("Must provide either port or socket_path")
+
+        self.host = host
+        self.port = port
+        self.socket_path = Path(socket_path) if socket_path else None
+        self.health_check_url = health_check_url
+        self.startup_timeout = startup_timeout
+        self._session: Any | None = None  # requests.Session or httpx.Client
+        self._ready = False
+
+    @property
+    def base_url(self) -> str:
+        """Base URL for making requests to the server."""
+        if self.socket_path:
+            # For Unix sockets, use http+unix:// scheme
+            return f"http+unix://{self.socket_path}"
+        return f"http://{self.host}:{self.port}"
+
+    @property
+    def is_ready(self) -> bool:
+        """Return True if the server is confirmed ready."""
+        return self._ready
+
+    def _check_tcp_connection(self) -> bool:
+        """Check if we can establish a TCP connection."""
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.settimeout(1.0)
+            result = sock.connect_ex((self.host, self.port))
+            sock.close()
+            return result == 0
+        except OSError:
+            return False
+
+    def _check_unix_connection(self) -> bool:
+        """Check if we can establish a Unix socket connection."""
+        if not self.socket_path or not self.socket_path.exists():
+            return False
+        try:
+            sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+            sock.settimeout(1.0)
+            sock.connect(str(self.socket_path))
+            sock.close()
+            return True
+        except OSError:
+            return False
+
+    def _check_http_health(self) -> bool:
+        """Check if the HTTP health endpoint is responding."""
+        if not REQUESTS_AVAILABLE:
+            # Fall back to socket check
+            if self.socket_path:
+                return self._check_unix_connection()
+            return self._check_tcp_connection()
+
+        try:
+            if self.socket_path:
+                # Use requests-unixsocket for Unix sockets if available
+                try:
+                    import requests_unixsocket
+
+                    session = requests_unixsocket.Session()
+                    url = f"http+unix://{str(self.socket_path).replace('/', '%2F')}{self.health_check_url}"
+                    response = session.get(url, timeout=2.0)
+                    return bool(response.ok)
+                except ImportError:
+                    # Fall back to socket check
+                    return self._check_unix_connection()
+            else:
+                response = requests.get(
+                    f"http://{self.host}:{self.port}{self.health_check_url}",
+                    timeout=2.0,
+                )
+                return bool(response.ok)
+        except Exception:
+            return False
+
+    def wait_ready(self, timeout: float | None = None) -> bool:
+        """
+        Wait for the server to be ready.
+
+        Args:
+            timeout: Max seconds to wait. Uses startup_timeout if not specified.
+
+        Returns:
+            True if server is ready.
+
+        Raises:
+            ServerNotReady: If timeout is reached before server is ready.
+        """
+        if timeout is None:
+            timeout = self.startup_timeout
+
+        deadline = time.time() + timeout
+        check_interval = 0.1  # Start with fast checks
+        max_interval = 1.0
+
+        while time.time() < deadline:
+            if self._check_http_health():
+                self._ready = True
+                logger.debug("Server is ready")
+                return True
+
+            time.sleep(check_interval)
+            # Exponential backoff up to max_interval
+            check_interval = min(check_interval * 1.5, max_interval)
+
+        raise ServerNotReady(f"Server did not become ready within {timeout} seconds")
+
+    def check_ready(self) -> bool:
+        """
+        Check if the server is ready without waiting.
+
+        Returns:
+            True if server is ready, False otherwise.
+        """
+        ready = self._check_http_health()
+        self._ready = ready
+        return ready
+
+    def _get_session(self) -> Any:
+        """Get or create the HTTP session."""
+        if self._session is not None:
+            return self._session
+
+        if REQUESTS_AVAILABLE:
+            self._session = requests.Session()
+
+            # Configure retry logic
+            retry_strategy = Retry(
+                total=3,
+                backoff_factor=0.5,
+                status_forcelist=[500, 502, 503, 504],
+            )
+            adapter = HTTPAdapter(max_retries=retry_strategy)
+            self._session.mount("http://", adapter)
+            self._session.mount("https://", adapter)
+            return self._session
+
+        raise ImportError(
+            "requests library is required for HTTP methods. Install with: pip install requests"
+        )
+
+    def _make_url(self, path: str) -> str:
+        """Construct full URL from path."""
+        if self.socket_path:
+            # Can't use requests for Unix sockets without requests-unixsocket
+            raise NotImplementedError("HTTP methods with Unix sockets require requests-unixsocket")
+        return urljoin(f"http://{self.host}:{self.port}/", path.lstrip("/"))
+
+    def get(self, path: str, **kwargs: Any) -> Any:
+        """
+        Make a GET request to the server.
+
+        Args:
+            path: URL path (will be joined with base URL).
+            **kwargs: Additional arguments passed to requests.get().
+
+        Returns:
+            requests.Response object.
+        """
+        session = self._get_session()
+        return session.get(self._make_url(path), **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> Any:
+        """
+        Make a POST request to the server.
+
+        Args:
+            path: URL path (will be joined with base URL).
+            **kwargs: Additional arguments passed to requests.post().
+
+        Returns:
+            requests.Response object.
+        """
+        session = self._get_session()
+        return session.post(self._make_url(path), **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> Any:
+        """
+        Make a PUT request to the server.
+
+        Args:
+            path: URL path (will be joined with base URL).
+            **kwargs: Additional arguments passed to requests.put().
+
+        Returns:
+            requests.Response object.
+        """
+        session = self._get_session()
+        return session.put(self._make_url(path), **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> Any:
+        """
+        Make a DELETE request to the server.
+
+        Args:
+            path: URL path (will be joined with base URL).
+            **kwargs: Additional arguments passed to requests.delete().
+
+        Returns:
+            requests.Response object.
+        """
+        session = self._get_session()
+        return session.delete(self._make_url(path), **kwargs)
+
+    def request(self, method: str, path: str, **kwargs: Any) -> Any:
+        """
+        Make an arbitrary HTTP request to the server.
+
+        Args:
+            method: HTTP method (GET, POST, etc.).
+            path: URL path (will be joined with base URL).
+            **kwargs: Additional arguments passed to requests.request().
+
+        Returns:
+            requests.Response object.
+        """
+        session = self._get_session()
+        return session.request(method, self._make_url(path), **kwargs)
+
+    def close(self) -> None:
+        """Close the client session."""
+        if self._session is not None:
+            self._session.close()
+            self._session = None
+
+    def __enter__(self) -> ServerClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()

singleserver/lock.py

@@ -0,0 +1,282 @@
+"""
+Atomic lock using socket binding.
+
+Socket binding is atomic at the OS level - two processes cannot bind the same
+port/socket simultaneously. This provides a distributed lock mechanism without
+needing external coordination services.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import socket
+from pathlib import Path
+from types import TracebackType
+
+
+class SocketLock:
+    """
+    Atomic lock using socket binding.
+
+    Uses the OS-level guarantee that only one process can bind a socket at a time.
+    This works for both TCP ports and Unix domain sockets.
+
+    Example:
+        lock = SocketLock(port=8765)
+        if lock.try_acquire():
+            # We're the owner
+            try:
+                run_server()
+            finally:
+                lock.release()
+        else:
+            # Someone else owns it
+            connect_to_existing_server()
+    """
+
+    def __init__(
+        self,
+        port: int | None = None,
+        socket_path: str | Path | None = None,
+        host: str = "127.0.0.1",
+    ):
+        """
+        Initialize the lock.
+
+        Args:
+            port: TCP port to bind for locking. Mutually exclusive with socket_path.
+            socket_path: Unix socket path for locking. Mutually exclusive with port.
+            host: Host to bind to when using TCP port. Defaults to localhost.
+
+        Raises:
+            ValueError: If neither port nor socket_path is provided, or both are.
+        """
+        # Initialize all attributes first so __del__ doesn't fail if validation raises
+        self._socket: socket.socket | None = None
+        self._acquired = False
+        self.port = port
+        self.socket_path = Path(socket_path) if socket_path else None
+        self.host = host
+
+        if port is None and socket_path is None:
+            raise ValueError("Must provide either port or socket_path")
+        if port is not None and socket_path is not None:
+            raise ValueError("Cannot provide both port and socket_path")
+
+    @property
+    def is_acquired(self) -> bool:
+        """Return True if this lock instance has acquired the lock."""
+        return self._acquired
+
+    @property
+    def address(self) -> tuple[str, int] | str:
+        """Return the address this lock binds to."""
+        if self.socket_path:
+            return str(self.socket_path)
+        assert self.port is not None  # Guaranteed by __init__ validation
+        return (self.host, self.port)
+
+    def try_acquire(self) -> bool:
+        """
+        Try to acquire the lock.
+
+        Returns:
+            True if the lock was acquired, False if already held by another process.
+
+        Raises:
+            OSError: For socket errors other than address-in-use.
+            RuntimeError: If called when lock is already acquired.
+        """
+        if self._acquired:
+            raise RuntimeError("Lock already acquired by this instance")
+
+        try:
+            if self.socket_path:
+                # Clean up stale socket file if it exists
+                # This handles the case where a previous process crashed without cleanup
+                if self.socket_path.exists():
+                    # Try to connect first to see if someone is actually listening
+                    test_sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+                    try:
+                        test_sock.connect(str(self.socket_path))
+                        # Connection succeeded, someone else has the lock
+                        test_sock.close()
+                        return False
+                    except (ConnectionRefusedError, FileNotFoundError):
+                        # No one is listening, safe to remove stale socket
+                        try:
+                            self.socket_path.unlink()
+                        except FileNotFoundError:
+                            pass
+                    finally:
+                        test_sock.close()
+
+                self._socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+                self._socket.bind(str(self.socket_path))
+                # Start listening so others can detect the socket is in use
+                self._socket.listen(1)
+            else:
+                self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+                self._socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+                self._socket.bind((self.host, self.port))
+                # Start listening so others can detect the socket is in use
+                self._socket.listen(1)
+
+            self._acquired = True
+            return True
+
+        except OSError as e:
+            if e.errno in (errno.EADDRINUSE, errno.EADDRNOTAVAIL):
+                if self._socket:
+                    self._socket.close()
+                    self._socket = None
+                return False
+            # Re-raise unexpected errors
+            if self._socket:
+                self._socket.close()
+                self._socket = None
+            raise
+
+    def release(self) -> None:
+        """
+        Release the lock.
+
+        Safe to call even if lock was not acquired.
+        """
+        if self._socket:
+            try:
+                self._socket.close()
+            except OSError:
+                pass
+            self._socket = None
+
+        if self.socket_path and self.socket_path.exists():
+            try:
+                self.socket_path.unlink()
+            except (FileNotFoundError, OSError):
+                pass
+
+        self._acquired = False
+
+    def __enter__(self) -> SocketLock:
+        """Context manager entry - tries to acquire but doesn't raise if fails."""
+        self.try_acquire()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Context manager exit - releases the lock."""
+        self.release()
+
+    def __del__(self) -> None:
+        """Destructor - ensure lock is released."""
+        self.release()
+
+
+class LockFile:
+    """
+    Alternative lock implementation using a lock file with PID.
+
+    This is useful as a secondary coordination mechanism alongside SocketLock,
+    particularly for detecting stale locks and storing metadata about the lock owner.
+    """
+
+    def __init__(self, path: str | Path):
+        """
+        Initialize the lock file.
+
+        Args:
+            path: Path to the lock file.
+        """
+        self.path = Path(path)
+        self._acquired = False
+
+    @property
+    def is_acquired(self) -> bool:
+        """Return True if this instance holds the lock."""
+        return self._acquired
+
+    def try_acquire(self) -> bool:
+        """
+        Try to acquire the lock by creating a lock file with our PID.
+
+        Returns:
+            True if acquired, False if another process holds it.
+        """
+        if self._acquired:
+            raise RuntimeError("Lock already acquired by this instance")
+
+        try:
+            # Use O_EXCL for atomic file creation
+            fd = os.open(
+                self.path,
+                os.O_CREAT | os.O_EXCL | os.O_WRONLY,
+                0o644,
+            )
+            try:
+                os.write(fd, f"{os.getpid()}\n".encode())
+            finally:
+                os.close(fd)
+            self._acquired = True
+            return True
+
+        except FileExistsError:
+            # Lock file exists, check if the owning process is still alive
+            try:
+                with open(self.path) as f:
+                    pid = int(f.read().strip())
+                # Check if process is alive
+                os.kill(pid, 0)
+                # Process is alive, lock is held
+                return False
+            except (ValueError, ProcessLookupError, PermissionError):
+                # Invalid PID or process is dead, try to clean up
+                try:
+                    self.path.unlink()
+                    return self.try_acquire()
+                except FileNotFoundError:
+                    return self.try_acquire()
+                except OSError:
+                    return False
+
+    def release(self) -> None:
+        """Release the lock by removing the lock file."""
+        if self._acquired:
+            try:
+                self.path.unlink()
+            except FileNotFoundError:
+                pass
+            self._acquired = False
+
+    def get_owner_pid(self) -> int | None:
+        """
+        Get the PID of the process that holds the lock.
+
+        Returns:
+            PID if lock file exists and is valid, None otherwise.
+        """
+        try:
+            with open(self.path) as f:
+                return int(f.read().strip())
+        except (FileNotFoundError, ValueError):
+            return None
+
+    def __enter__(self) -> LockFile:
+        self.try_acquire()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.release()
+
+    def __del__(self) -> None:
+        self.release()