singleserver 0.1.0__py3-none-any.whl

singleserver/server.py

@@ -0,0 +1,432 @@
+"""
+Main SingleServer class that ties together lock, process, and client.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import signal
+import threading
+from collections.abc import Callable
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+
+from .client import ServerClient
+from .lock import SocketLock
+from .process import ProcessOwner
+
+logger = logging.getLogger(__name__)
+
+
+class SingleServer:
+    """
+    Manages a singleton server process across multiple workers.
+
+    Uses atomic socket binding for coordination - only one process can become
+    the "owner" and run the server, others become clients.
+
+    Example:
+        # Define the server
+        datasette = SingleServer(
+            name="datasette",
+            command=["datasette", "serve", "data.db", "-p", "{port}"],
+            port=8765,
+        )
+
+        # Connect (starts if needed, connects if already running)
+        with datasette.connect() as client:
+            response = client.get("/data/my_table.json")
+    """
+
+    def __init__(
+        self,
+        name: str,
+        command: list[str],
+        port: int | None = None,
+        socket: str | Path | None = None,
+        lock_port: int | None = None,
+        lock_socket: str | Path | None = None,
+        health_check_url: str = "/",
+        health_check_interval: float = 5.0,
+        startup_timeout: float = 30.0,
+        restart_on_failure: bool = True,
+        max_restarts: int = 3,
+        restart_delay: float = 1.0,
+        env: dict[str, str] | None = None,
+        cwd: str | Path | None = None,
+        stdout: str | Path | None = None,
+        stderr: str | Path | None = None,
+        shutdown_timeout: float = 10.0,
+        shutdown_signal: int = signal.SIGTERM,
+    ):
+        """
+        Initialize the SingleServer.
+
+        Args:
+            name: Identifier for logging/debugging.
+            command: Command to run. Can include {port} placeholder.
+            port: TCP port the server will listen on.
+            socket: Unix socket path the server will listen on.
+            lock_port: Separate port for the coordination lock (defaults to port - 1).
+            lock_socket: Separate socket path for coordination lock.
+            health_check_url: URL path to check for server readiness.
+            health_check_interval: Seconds between health checks when running.
+            startup_timeout: Max seconds to wait for server to become ready.
+            restart_on_failure: Whether to restart if server dies unexpectedly.
+            max_restarts: Maximum restart attempts before giving up.
+            restart_delay: Seconds to wait between restart attempts.
+            env: Additional environment variables for the server process.
+            cwd: Working directory for the server process.
+            stdout: Where to redirect stdout ("inherit", "null", or file path).
+            stderr: Where to redirect stderr ("inherit", "null", "stdout", or file path).
+            shutdown_timeout: Seconds to wait for graceful shutdown.
+            shutdown_signal: Signal to send for shutdown.
+        """
+        if port is None and socket is None:
+            raise ValueError("Must provide either port or socket")
+
+        self.name = name
+        self._command_template = command
+        self.port = port
+        self.socket_path = Path(socket) if socket else None
+
+        # Determine lock address (separate from server address)
+        if lock_port is not None or lock_socket is not None:
+            self._lock_port = lock_port
+            self._lock_socket = Path(lock_socket) if lock_socket else None
+        elif port is not None:
+            # Use a separate lock port by default (ensure it stays within valid range)
+            self._lock_port = port + 10000 if port + 10000 <= 65535 else port - 10000
+            self._lock_socket = None
+        else:
+            # Use a separate lock socket
+            self._lock_port = None
+            self._lock_socket = Path(str(socket) + ".lock")
+
+        self.health_check_url = health_check_url
+        self.health_check_interval = health_check_interval
+        self.startup_timeout = startup_timeout
+        self.restart_on_failure = restart_on_failure
+        self.max_restarts = max_restarts
+        self.restart_delay = restart_delay
+        self.env = env
+        self.cwd = cwd
+        self.stdout = stdout
+        self.stderr = stderr
+        self.shutdown_timeout = shutdown_timeout
+        self.shutdown_signal = shutdown_signal
+
+        self._lock: SocketLock | None = None
+        self._owner: ProcessOwner | None = None
+        self._is_owner = False
+        self._client: ServerClient | None = None
+        self._cleanup_registered = False
+        self._state_lock = threading.Lock()
+
+    @property
+    def command(self) -> list[str]:
+        """Build the command with placeholders replaced."""
+        result = []
+        for part in self._command_template:
+            if "{port}" in part:
+                part = part.replace("{port}", str(self.port))
+            if "{socket}" in part:
+                part = part.replace("{socket}", str(self.socket_path))
+            result.append(part)
+        return result
+
+    @property
+    def is_owner(self) -> bool:
+        """Return True if this process owns the server."""
+        return self._is_owner
+
+    @property
+    def is_connected(self) -> bool:
+        """Return True if connected to the server (as owner or client)."""
+        return self._client is not None and self._client.is_ready
+
+    def _create_health_check(self) -> Callable[[], bool]:
+        """Create a health check function for the process owner."""
+
+        def check() -> bool:
+            try:
+                client = ServerClient(
+                    host="127.0.0.1",
+                    port=self.port,
+                    socket_path=self.socket_path,
+                    health_check_url=self.health_check_url,
+                    startup_timeout=2.0,
+                )
+                return bool(client.check_ready())
+            except Exception:
+                return False
+
+        return check
+
+    def _register_cleanup(self) -> None:
+        """Register cleanup handlers."""
+        if self._cleanup_registered:
+            return
+        self._cleanup_registered = True
+        atexit.register(self._cleanup)
+
+        # Also handle signals for clean shutdown
+        def signal_handler(signum: int, frame: Any) -> None:
+            self._cleanup()
+            # Re-raise signal for default handling
+            signal.signal(signum, signal.SIG_DFL)
+            signal.raise_signal(signum)
+
+        try:
+            signal.signal(signal.SIGTERM, signal_handler)
+            signal.signal(signal.SIGINT, signal_handler)
+        except ValueError:
+            # Can't set signal handlers from non-main thread
+            pass
+
+    def _cleanup(self) -> None:
+        """Clean up resources on exit."""
+        logger.debug(f"Cleaning up SingleServer {self.name}")
+
+        if self._owner:
+            try:
+                self._owner.stop()
+            except Exception as e:
+                logger.warning(f"Error stopping process: {e}")
+            self._owner = None
+
+        if self._lock:
+            try:
+                self._lock.release()
+            except Exception as e:
+                logger.warning(f"Error releasing lock: {e}")
+            self._lock = None
+
+        if self._client:
+            try:
+                self._client.close()
+            except Exception:
+                pass
+            self._client = None
+
+        self._is_owner = False
+
+    def connect(self, wait_ready: bool = True, timeout: float | None = None) -> ServerClient:
+        """
+        Connect to the server, starting it if necessary.
+
+        This is the main entry point. Multiple processes can call this concurrently:
+        - First process to acquire the lock becomes the owner and starts the server
+        - Other processes wait for the server to be ready and connect as clients
+
+        Args:
+            wait_ready: Whether to wait for the server to be ready.
+            timeout: Max seconds to wait for ready (uses startup_timeout if not specified).
+
+        Returns:
+            ServerClient instance for making requests to the server.
+
+        Raises:
+            ServerNotReady: If timeout is reached before server is ready.
+        """
+        with self._state_lock:
+            if self._client is not None:
+                return self._client
+
+            # Create the lock
+            self._lock = SocketLock(
+                port=self._lock_port,
+                socket_path=self._lock_socket,
+            )
+
+            # Try to become the owner
+            if self._lock.try_acquire():
+                logger.info(f"Acquired lock for {self.name}, becoming owner")
+                self._is_owner = True
+
+                # Start the server process
+                self._owner = ProcessOwner(
+                    command=self.command,
+                    env=self.env,
+                    cwd=self.cwd,
+                    stdout=self.stdout,
+                    stderr=self.stderr,
+                    health_check=self._create_health_check(),
+                    health_check_interval=self.health_check_interval,
+                    startup_timeout=self.startup_timeout,
+                    restart_on_failure=self.restart_on_failure,
+                    max_restarts=self.max_restarts,
+                    restart_delay=self.restart_delay,
+                    shutdown_timeout=self.shutdown_timeout,
+                    shutdown_signal=self.shutdown_signal,
+                )
+                self._owner.start()
+                self._register_cleanup()
+            else:
+                logger.info(f"Lock already held for {self.name}, connecting as client")
+                # Release the lock object since we don't own it
+                self._lock = None
+
+            # Create client
+            self._client = ServerClient(
+                host="127.0.0.1",
+                port=self.port,
+                socket_path=self.socket_path,
+                health_check_url=self.health_check_url,
+                startup_timeout=timeout or self.startup_timeout,
+            )
+
+        # Wait for ready outside the lock
+        if wait_ready:
+            self._client.wait_ready(timeout=timeout)
+
+        return self._client
+
+    def disconnect(self) -> None:
+        """
+        Disconnect from the server.
+
+        If this process is the owner, stops the server process.
+        """
+        self._cleanup()
+
+    def stop(self) -> None:
+        """Alias for disconnect()."""
+        self.disconnect()
+
+    def get_client(self) -> ServerClient | None:
+        """
+        Get the client without connecting.
+
+        Returns:
+            ServerClient if connected, None otherwise.
+        """
+        return self._client
+
+    def __enter__(self) -> ServerClient:
+        """Context manager entry - connects to the server."""
+        return self.connect()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        """Context manager exit - disconnects from the server."""
+        self.disconnect()
+
+
+class ManagedServer:
+    """
+    Alternative interface for servers that don't need the singleton pattern.
+
+    Use this when you just want process management (health checks, restarts)
+    without the distributed coordination.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        command: list[str],
+        port: int | None = None,
+        socket: str | Path | None = None,
+        **kwargs: Any,
+    ):
+        """
+        Initialize the managed server.
+
+        Takes the same arguments as SingleServer.
+        """
+        self.name = name
+        self._command_template = command
+        self.port = port
+        self.socket_path = Path(socket) if socket else None
+        self._kwargs = kwargs
+        self._owner: ProcessOwner | None = None
+        self._client: ServerClient | None = None
+
+    @property
+    def command(self) -> list[str]:
+        """Build the command with placeholders replaced."""
+        result = []
+        for part in self._command_template:
+            if "{port}" in part:
+                part = part.replace("{port}", str(self.port))
+            if "{socket}" in part:
+                part = part.replace("{socket}", str(self.socket_path))
+            result.append(part)
+        return result
+
+    def start(self) -> ServerClient:
+        """Start the server and return a client."""
+        if self._owner is not None:
+            raise RuntimeError("Server already started")
+
+        health_check_url = self._kwargs.get("health_check_url", "/")
+
+        def create_health_check() -> Callable[[], bool]:
+            def check() -> bool:
+                try:
+                    client = ServerClient(
+                        host="127.0.0.1",
+                        port=self.port,
+                        socket_path=self.socket_path,
+                        health_check_url=health_check_url,
+                        startup_timeout=2.0,
+                    )
+                    return bool(client.check_ready())
+                except Exception:
+                    return False
+
+            return check
+
+        self._owner = ProcessOwner(
+            command=self.command,
+            env=self._kwargs.get("env"),
+            cwd=self._kwargs.get("cwd"),
+            stdout=self._kwargs.get("stdout"),
+            stderr=self._kwargs.get("stderr"),
+            health_check=create_health_check(),
+            health_check_interval=self._kwargs.get("health_check_interval", 5.0),
+            startup_timeout=self._kwargs.get("startup_timeout", 30.0),
+            restart_on_failure=self._kwargs.get("restart_on_failure", True),
+            max_restarts=self._kwargs.get("max_restarts", 3),
+            restart_delay=self._kwargs.get("restart_delay", 1.0),
+            shutdown_timeout=self._kwargs.get("shutdown_timeout", 10.0),
+            shutdown_signal=self._kwargs.get("shutdown_signal", signal.SIGTERM),
+        )
+        self._owner.start()
+
+        self._client = ServerClient(
+            host="127.0.0.1",
+            port=self.port,
+            socket_path=self.socket_path,
+            health_check_url=health_check_url,
+            startup_timeout=self._kwargs.get("startup_timeout", 30.0),
+        )
+        self._client.wait_ready()
+
+        return self._client
+
+    def stop(self) -> None:
+        """Stop the server."""
+        if self._owner:
+            self._owner.stop()
+            self._owner = None
+        if self._client:
+            self._client.close()
+            self._client = None
+
+    def __enter__(self) -> ServerClient:
+        return self.start()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.stop()

singleserver-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: singleserver
+Version: 0.1.0
+Summary: Manage singleton server processes across multiple workers using atomic socket binding
+Project-URL: Homepage, https://github.com/Technology-Company/singleserver
+Project-URL: Documentation, https://github.com/Technology-Company/singleserver#readme
+Project-URL: Repository, https://github.com/Technology-Company/singleserver
+Project-URL: Issues, https://github.com/Technology-Company/singleserver/issues
+Author-email: Johanna Mae Dimayuga <johanna@techco.fi>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: coordination,django,gunicorn,multiprocess,process,server,singleton
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-requests>=2.25.0; extra == 'dev'
+Provides-Extra: unix-sockets
+Requires-Dist: requests-unixsocket>=0.3.0; extra == 'unix-sockets'
+Description-Content-Type: text/markdown
+
+# singleserver
+
+Manage singleton server processes across multiple workers using atomic socket binding.
+
+## Problem
+
+When running web applications with multiple workers (e.g., gunicorn), you often need auxiliary services (API servers, background processors, caches) that should only run as a **single instance** shared by all workers.
+
+Current solutions like systemd unit files or separate containers require additional infrastructure and make local development different from production.
+
+## Solution
+
+`singleserver` uses the OS-level guarantee that **only one process can bind a socket at a time**. When multiple workers call `connect()`:
+
+1. First worker acquires the lock and starts the server
+2. Other workers detect the lock is held and connect as clients
+3. If the owner dies, another worker can take over
+
+```
+Worker 1: connect() → bind(:18765) → SUCCESS → starts server, returns client
+Worker 2: connect() → bind(:18765) → EADDRINUSE → waits for ready, returns client
+Worker 3: connect() → bind(:18765) → EADDRINUSE → waits for ready, returns client
+```
+
+## Installation
+
+```bash
+pip install singleserver
+```
+
+## Quick Start
+
+```python
+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")
+    print(response.json())
+```
+
+## Features
+
+- **Atomic coordination**: Uses socket binding for distributed locking
+- **Health monitoring**: Configurable health checks with automatic restarts
+- **Output handling**: Redirect stdout/stderr to files
+- **Graceful shutdown**: SIGTERM with timeout, then SIGKILL
+- **No external dependencies**: Pure Python, no Redis/etcd/etc needed
+- **Same code for dev and prod**: No systemd unit files required
+
+## Configuration
+
+```python
+SingleServer(
+    name="my-service",                    # Identifier for logging
+    command=["python", "server.py", ...], # Command to run ({port} is replaced)
+
+    # Server address
+    port=8765,                           # TCP port
+    # OR
+    socket="/tmp/my-service.sock",       # Unix socket (faster, more secure)
+
+    # Health checks
+    health_check_url="/",                # URL to poll for readiness
+    health_check_interval=5.0,           # Seconds between checks
+    startup_timeout=30.0,                # Max seconds to wait for startup
+
+    # Restart behavior
+    restart_on_failure=True,             # Auto-restart if process dies
+    max_restarts=3,                      # Give up after N restarts
+    restart_delay=1.0,                   # Seconds between restart attempts
+
+    # Process options
+    env={"DATABASE_URL": "..."},         # Environment variables
+    cwd="/app",                          # Working directory
+    stdout="/var/log/my-service.log",    # Log file
+    stderr="stdout",                     # Redirect stderr to stdout
+
+    # Shutdown
+    shutdown_timeout=10.0,               # Seconds for graceful stop
+)
+```
+
+## Use Cases
+
+### Internal API server
+
+```python
+from singleserver import SingleServer
+
+api = SingleServer(
+    name="internal-api",
+    command=["python", "-m", "internal_api", "-p", "{port}"],
+    port=8765,
+)
+
+def my_view(request):
+    with api.connect() as client:
+        data = client.get("/query").json()
+    return JsonResponse(data)
+```
+
+### Background service
+
+```python
+service = SingleServer(
+    name="background-service",
+    command=["python", "service.py", "--port", "{port}"],
+    port=8888,
+    health_check_url="/health",
+    restart_on_failure=True,
+)
+```
+
+## How It Works
+
+1. **Lock acquisition**: Uses a separate socket (port + 10000 by default) for coordination
+2. **Process management**: Owner spawns subprocess in new process group
+3. **Health monitoring**: Background thread polls health endpoint
+4. **Restart logic**: Configurable restart attempts with delay
+5. **Cleanup**: atexit handler and signal handlers for clean shutdown
+
+## Development
+
+```bash
+# Install dev dependencies
+uv sync --all-extras
+
+# Run tests
+uv run pytest
+
+# Type checking
+uv run mypy singleserver
+
+# Linting
+uv run ruff check singleserver tests
+```
+
+## License
+
+MIT

singleserver-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+singleserver/__init__.py,sha256=EgSpurqe2RhhGvvKghb74xU9lOsGQexoXP0mMmP4fu8,1052
+singleserver/client.py,sha256=6OG9l10xUXG_wLoJOVocy8jRM4f4JItm0A6yr1Rtd0Q,9560
+singleserver/lock.py,sha256=e0AWDnYk3I6_4dYSCwxz4H2FCkb9ItJLinU3palZ2ak,9100
+singleserver/process.py,sha256=GqUyGWZXy85biwiShuU95tMOQXAmbiBBDeXrTEikq-o,17062
+singleserver/server.py,sha256=otrSQVQVNXEpVosG4GuCJk_Iozuqnbwmkt77c0D9cMI,14978
+singleserver-0.1.0.dist-info/METADATA,sha256=oZeiUEhP_NpZXtRuaHkO1v0Cml6DJUCn9hXmI6b5KeY,6013
+singleserver-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+singleserver-0.1.0.dist-info/licenses/LICENSE,sha256=x6w9qzvmsY6V3iRykNoiSWD0NqCZeV6VejFT4kVi6Fg,1075
+singleserver-0.1.0.dist-info/RECORD,,

singleserver-0.1.0.dist-info/WHEEL

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

singleserver-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Technology Company
+
+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.