tableflip 0.1.0__tar.gz

tableflip-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.3
+Name: tableflip
+Version: 0.1.0
+Summary: Zero-downtime process upgrades for Python, inspired by cloudflare/tableflip
+Author: Bernardo Vale
+Author-email: Bernardo Vale <bernardo@kentik.com>
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# tableflip — Graceful process restarts in Python
+
+Zero-downtime upgrades for Python network services. Update running code or configuration without dropping existing connections.
+
+This is a Python port of Cloudflare's [tableflip](https://github.com/cloudflare/tableflip) Go library. The core design — fd inheritance, IPC protocol, and state machine — follows the original closely, adapted to Python's `asyncio` runtime.
+
+**Works on Linux and macOS.** Raises `NotSupportedError` on Windows (use `tableflip.testing` stubs instead).
+
+## How it works
+
+1. On `SIGHUP`, the running process spawns a new copy of itself
+2. TCP listener sockets are passed to the new process via fd inheritance
+3. The new process signals readiness after initialization
+4. The old process stops accepting new connections and exits
+
+Only one upgrade runs at a time. If the new process crashes during init, the old one keeps serving.
+
+## Installation
+
+```bash
+uv add tableflip
+# or
+pip install tableflip
+```
+
+Requires Python 3.13+.
+
+## Usage
+
+```python
+import asyncio
+import signal
+from tableflip import Upgrader, Options
+
+
+async def main():
+    upg = await Upgrader.new(Options(pid_file="/tmp/myapp.pid"))
+
+    # Trigger upgrade on SIGHUP
+    loop = asyncio.get_running_loop()
+    loop.add_signal_handler(signal.SIGHUP, lambda: asyncio.create_task(do_upgrade(upg)))
+
+    # Listen must be called before ready()
+    sock = await upg.fds.listen("127.0.0.1", 8080)
+
+    server = await asyncio.start_server(handle_conn, sock=sock)
+
+    await upg.ready()
+
+    # Block until an upgrade completes or stop() is called
+    await upg.exit().wait()
+
+    # Graceful shutdown
+    server.close()
+    await server.wait_closed()
+    await upg.wait_for_parent()
+    upg.stop()
+
+
+async def do_upgrade(upg: Upgrader):
+    try:
+        await upg.upgrade()
+    except Exception as e:
+        print(f"Upgrade failed: {e}")
+
+
+async def handle_conn(reader, writer):
+    writer.write(b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nok")
+    await writer.drain()
+    writer.close()
+
+
+asyncio.run(main())
+```
+
+Trigger an upgrade:
+
+```bash
+kill -HUP $(cat /tmp/myapp.pid)
+```
+
+## Integration with systemd
+
+```ini
+[Unit]
+Description=My Python service
+
+[Service]
+ExecStart=/path/to/venv/bin/python app.py
+ExecReload=/bin/kill -HUP $MAINPID
+PIDFile=/tmp/myapp.pid
+```
+
+## Testing
+
+Use the `tableflip.testing` module for unit tests or unsupported platforms:
+
+```python
+from tableflip.testing import Upgrader, Fds
+
+upg = Upgrader()          # never upgrades, upgrade() raises NotSupportedError
+await upg.ready()          # no-op
+assert not upg.has_parent()
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `await Upgrader.new(opts)` | Create an upgrader (one per process) |
+| `await upg.fds.listen(addr, port)` | Get an inherited or new TCP listener |
+| `await upg.ready()` | Signal readiness, notify parent, write PID file |
+| `await upg.upgrade()` | Spawn new process and wait for it to become ready |
+| `upg.exit()` | Returns `asyncio.Event` set when the process should exit |
+| `upg.stop()` | Prevent further upgrades and trigger exit |
+| `await upg.wait_for_parent()` | Block until parent process exits |
+| `upg.has_parent()` | `True` if spawned by a tableflip upgrade |
+
+## Acknowledgments
+
+This is a Python port of [cloudflare/tableflip](https://github.com/cloudflare/tableflip) by Cloudflare. The Go library was created by Lorenz Bauer and the Cloudflare team. All credit for the design and protocol goes to them.
+
+## License
+
+See [LICENSE](LICENSE) (BSD 3-Clause, same as the original Go library).

tableflip-0.1.0/README.md

@@ -0,0 +1,125 @@
+# tableflip — Graceful process restarts in Python
+
+Zero-downtime upgrades for Python network services. Update running code or configuration without dropping existing connections.
+
+This is a Python port of Cloudflare's [tableflip](https://github.com/cloudflare/tableflip) Go library. The core design — fd inheritance, IPC protocol, and state machine — follows the original closely, adapted to Python's `asyncio` runtime.
+
+**Works on Linux and macOS.** Raises `NotSupportedError` on Windows (use `tableflip.testing` stubs instead).
+
+## How it works
+
+1. On `SIGHUP`, the running process spawns a new copy of itself
+2. TCP listener sockets are passed to the new process via fd inheritance
+3. The new process signals readiness after initialization
+4. The old process stops accepting new connections and exits
+
+Only one upgrade runs at a time. If the new process crashes during init, the old one keeps serving.
+
+## Installation
+
+```bash
+uv add tableflip
+# or
+pip install tableflip
+```
+
+Requires Python 3.13+.
+
+## Usage
+
+```python
+import asyncio
+import signal
+from tableflip import Upgrader, Options
+
+
+async def main():
+    upg = await Upgrader.new(Options(pid_file="/tmp/myapp.pid"))
+
+    # Trigger upgrade on SIGHUP
+    loop = asyncio.get_running_loop()
+    loop.add_signal_handler(signal.SIGHUP, lambda: asyncio.create_task(do_upgrade(upg)))
+
+    # Listen must be called before ready()
+    sock = await upg.fds.listen("127.0.0.1", 8080)
+
+    server = await asyncio.start_server(handle_conn, sock=sock)
+
+    await upg.ready()
+
+    # Block until an upgrade completes or stop() is called
+    await upg.exit().wait()
+
+    # Graceful shutdown
+    server.close()
+    await server.wait_closed()
+    await upg.wait_for_parent()
+    upg.stop()
+
+
+async def do_upgrade(upg: Upgrader):
+    try:
+        await upg.upgrade()
+    except Exception as e:
+        print(f"Upgrade failed: {e}")
+
+
+async def handle_conn(reader, writer):
+    writer.write(b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nok")
+    await writer.drain()
+    writer.close()
+
+
+asyncio.run(main())
+```
+
+Trigger an upgrade:
+
+```bash
+kill -HUP $(cat /tmp/myapp.pid)
+```
+
+## Integration with systemd
+
+```ini
+[Unit]
+Description=My Python service
+
+[Service]
+ExecStart=/path/to/venv/bin/python app.py
+ExecReload=/bin/kill -HUP $MAINPID
+PIDFile=/tmp/myapp.pid
+```
+
+## Testing
+
+Use the `tableflip.testing` module for unit tests or unsupported platforms:
+
+```python
+from tableflip.testing import Upgrader, Fds
+
+upg = Upgrader()          # never upgrades, upgrade() raises NotSupportedError
+await upg.ready()          # no-op
+assert not upg.has_parent()
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `await Upgrader.new(opts)` | Create an upgrader (one per process) |
+| `await upg.fds.listen(addr, port)` | Get an inherited or new TCP listener |
+| `await upg.ready()` | Signal readiness, notify parent, write PID file |
+| `await upg.upgrade()` | Spawn new process and wait for it to become ready |
+| `upg.exit()` | Returns `asyncio.Event` set when the process should exit |
+| `upg.stop()` | Prevent further upgrades and trigger exit |
+| `await upg.wait_for_parent()` | Block until parent process exits |
+| `upg.has_parent()` | `True` if spawned by a tableflip upgrade |
+
+## Acknowledgments
+
+This is a Python port of [cloudflare/tableflip](https://github.com/cloudflare/tableflip) by Cloudflare. The Go library was created by Lorenz Bauer and the Cloudflare team. All credit for the design and protocol goes to them.
+
+## License
+
+See [LICENSE](LICENSE) (BSD 3-Clause, same as the original Go library).

tableflip-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "tableflip"
+version = "0.1.0"
+description = "Zero-downtime process upgrades for Python, inspired by cloudflare/tableflip"
+readme = "README.md"
+authors = [
+    { name = "Bernardo Vale", email = "bernardo@kentik.com" }
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.2,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+markers = [
+    "integration: integration tests that spawn real processes (slow, Unix-only)",
+]
+addopts = "-m 'not integration'"

tableflip-0.1.0/src/tableflip/__init__.py

@@ -0,0 +1,24 @@
+"""tableflip: zero-downtime process upgrades for Python."""
+
+from tableflip._errors import (
+    AlreadyUpgradedError,
+    NotReadyError,
+    NotSupportedError,
+    TableflipError,
+    TerminatingError,
+    UpgradeInProgressError,
+)
+from tableflip._fds import Fds
+from tableflip._upgrader import Options, Upgrader
+
+__all__ = [
+    "AlreadyUpgradedError",
+    "Fds",
+    "NotReadyError",
+    "NotSupportedError",
+    "Options",
+    "TableflipError",
+    "TerminatingError",
+    "Upgrader",
+    "UpgradeInProgressError",
+]

tableflip-0.1.0/src/tableflip/_child.py

@@ -0,0 +1,133 @@
+"""Parent-side IPC: spawn a child process and wait for it to become ready."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import struct
+import sys
+
+from tableflip._fds import FdName, encode_fd_names
+from tableflip._process import NOTIFY_READY, SENTINEL_ENV_VAR, Env, Process
+
+logger = logging.getLogger(__name__)
+
+
+class Child:
+    """Represents a spawned child process from the parent's perspective."""
+
+    def __init__(
+        self,
+        proc: Process,
+        ready: asyncio.Future[int],
+        result: asyncio.Future[Exception | None],
+        exited: asyncio.Event,
+        names_w: int,
+    ) -> None:
+        self._proc = proc
+        self.ready = ready
+        self.result = result
+        self.exited = exited
+        self._names_w = names_w
+
+    def kill(self) -> None:
+        self._proc.signal(signal.SIGKILL)
+
+    def __str__(self) -> str:
+        return str(self._proc)
+
+
+async def start_child(
+    env: Env,
+    passed_fds: dict[FdName, int],
+) -> Child:
+    """Spawn a child process, passing inherited fds and setting up IPC pipes.
+
+    Fd layout in child: [stdin=0, stdout=1, stderr=2, readyW=3, namesR=4, ...passed].
+    The Env.new_proc() implementation is responsible for fd placement.
+    """
+    ready_r, ready_w = os.pipe()
+    names_r, names_w = os.pipe()
+
+    inherited_fds: list[int] = []
+    fd_names_list: list[list[str]] = []
+    for name, fd in passed_fds.items():
+        inherited_fds.append(fd)
+        fd_names_list.append(list(name))
+
+    child_environ = env.environ()
+    child_environ[SENTINEL_ENV_VAR] = "yes"
+
+    try:
+        proc = env.new_proc(
+            sys.executable,
+            sys.argv,
+            [ready_w, names_r, *inherited_fds],
+            child_environ,
+        )
+    except Exception:
+        for fd in (ready_r, ready_w, names_r, names_w):
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        raise
+
+    # Close the child-side pipe ends in the parent
+    os.close(ready_w)
+    os.close(names_r)
+
+    loop = asyncio.get_running_loop()
+    ready_future: asyncio.Future[int] = loop.create_future()
+    result_future: asyncio.Future[Exception | None] = loop.create_future()
+    exited_event = asyncio.Event()
+
+    async def write_names() -> None:
+        data = encode_fd_names(fd_names_list)
+        # Length-prefix: 4-byte big-endian length then JSON payload.
+        # Go uses gob (self-delimiting), Python uses JSON which is not,
+        # so we frame the message so the child can read exactly one message
+        # then continue reading the same pipe for parent-exit detection.
+        framed = struct.pack("!I", len(data)) + data
+        await loop.run_in_executor(None, os.write, names_w, framed)
+
+    async def wait_exit() -> None:
+        try:
+            exit_code = await proc.wait()
+            if exit_code == 0:
+                result_future.set_result(None)
+            else:
+                result_future.set_result(Exception(f"exit code {exit_code}"))
+        except Exception as e:
+            result_future.set_result(e)
+        finally:
+            exited_event.set()
+            # Unblock wait_ready and close names_w if ready was never received
+            for fd in (ready_r, names_w):
+                try:
+                    os.close(fd)
+                except OSError:
+                    pass
+
+    async def wait_ready() -> None:
+        try:
+            data = await loop.run_in_executor(None, os.read, ready_r, 1)
+            if data and data[0] == NOTIFY_READY:
+                ready_future.set_result(names_w)
+            os.close(ready_r)
+        except OSError:
+            pass
+
+    asyncio.create_task(write_names())
+    asyncio.create_task(wait_exit())
+    asyncio.create_task(wait_ready())
+
+    return Child(
+        proc=proc,
+        ready=ready_future,
+        result=result_future,
+        exited=exited_event,
+        names_w=names_w,
+    )

tableflip-0.1.0/src/tableflip/_errors.py

@@ -0,0 +1,22 @@
+class TableflipError(Exception):
+    """Base exception for tableflip."""
+
+
+class NotSupportedError(TableflipError):
+    """Platform does not support graceful restart."""
+
+
+class NotReadyError(TableflipError):
+    """Process is not ready yet."""
+
+
+class UpgradeInProgressError(TableflipError):
+    """An upgrade is already in progress."""
+
+
+class AlreadyUpgradedError(TableflipError):
+    """Process has already been upgraded."""
+
+
+class TerminatingError(TableflipError):
+    """Process is terminating, no more upgrades allowed."""

tableflip-0.1.0/src/tableflip/_fds.py

@@ -0,0 +1,150 @@
+"""File descriptor manager for passing TCP listeners between processes."""
+
+from __future__ import annotations
+
+import fcntl
+import json
+import logging
+import os
+import socket
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+logger = logging.getLogger(__name__)
+
+LISTENER_KIND = "listener"
+
+FdName = tuple[str, str, str]  # (kind, network, addr)
+
+
+def _fd_name_to_list(name: FdName) -> list[str]:
+    return list(name)
+
+
+def _list_to_fd_name(parts: list[str]) -> FdName:
+    return (parts[0], parts[1], parts[2])
+
+
+class _InheritedFd:
+    """Wraps an inherited file descriptor."""
+
+    def __init__(self, fd: int, name: FdName) -> None:
+        self.fd = fd
+        self.name = name
+
+    def close(self) -> None:
+        try:
+            os.close(self.fd)
+        except OSError:
+            pass
+
+
+def dup_fd(fd: int) -> int:
+    """Duplicate a file descriptor with CLOEXEC flag."""
+    return fcntl.fcntl(fd, fcntl.F_DUPFD_CLOEXEC, 0)
+
+
+def _socket_from_fd(fd: int) -> socket.socket:
+    """Create a socket from a file descriptor without closing the original."""
+    new_fd = dup_fd(fd)
+    return socket.socket(fileno=new_fd)
+
+
+class Fds:
+    """Manages file descriptors inherited from parent and used by current process.
+
+    File descriptors move from 'inherited' to 'used' when retrieved.
+    Only 'used' fds are passed to the child on upgrade.
+    """
+
+    def __init__(
+        self,
+        inherited: dict[FdName, _InheritedFd] | None = None,
+    ) -> None:
+        self._inherited: dict[FdName, _InheritedFd] = inherited or {}
+        self._used: dict[FdName, _InheritedFd] = {}
+
+    async def listen(
+        self,
+        addr: str,
+        port: int,
+        *,
+        callback: Callable[[str, int], socket.socket] | None = None,
+    ) -> socket.socket:
+        """Return an inherited TCP listener or create a new one.
+
+        If port is 0 (dynamic), always creates a new listener.
+        """
+        if port != 0:
+            sock = self._get_inherited_listener(addr, port)
+            if sock is not None:
+                return sock
+
+        if callback is not None:
+            new_sock = callback(addr, port)
+        else:
+            new_sock = _create_tcp_listener(addr, port)
+
+        actual_addr, actual_port = new_sock.getsockname()[:2]
+        self._add_listener_locked(actual_addr, actual_port, new_sock)
+        return new_sock
+
+    def get_listener(self, addr: str, port: int) -> socket.socket | None:
+        """Return an inherited listener or None. Does not create new listeners."""
+        return self._get_inherited_listener(addr, port)
+
+    def add_listener(self, addr: str, port: int, sock: socket.socket) -> None:
+        """Register a listener socket for passing to child on upgrade."""
+        self._add_listener_locked(addr, port, sock)
+
+    def _get_inherited_listener(self, addr: str, port: int) -> socket.socket | None:
+        key: FdName = (LISTENER_KIND, "tcp", f"{addr}:{port}")
+        ifd = self._inherited.pop(key, None)
+        if ifd is None:
+            return None
+
+        sock = _socket_from_fd(ifd.fd)
+        self._used[key] = ifd
+        return sock
+
+    def _add_listener_locked(self, addr: str, port: int, sock: socket.socket) -> None:
+        key: FdName = (LISTENER_KIND, "tcp", f"{addr}:{port}")
+        new_fd = dup_fd(sock.fileno())
+        self._used[key] = _InheritedFd(new_fd, key)
+
+    def copy_used(self) -> dict[FdName, int]:
+        """Return a snapshot of used fds (name -> fd) for passing to child."""
+        return {name: ifd.fd for name, ifd in self._used.items()}
+
+    def close_inherited(self) -> None:
+        """Close all inherited fds that were not claimed."""
+        for ifd in self._inherited.values():
+            ifd.close()
+        self._inherited.clear()
+
+    def close_used(self) -> None:
+        """Close all used fds."""
+        for ifd in self._used.values():
+            ifd.close()
+        self._used.clear()
+
+
+def _create_tcp_listener(addr: str, port: int) -> socket.socket:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.setblocking(False)
+    sock.bind((addr, port))
+    sock.listen(128)
+    return sock
+
+
+def encode_fd_names(names: list[list[str]]) -> bytes:
+    """Encode fd names as JSON for the IPC pipe."""
+    return json.dumps(names).encode()
+
+
+def decode_fd_names(data: bytes) -> list[list[str]]:
+    """Decode fd names from JSON received from the IPC pipe."""
+    return json.loads(data.decode())

tableflip-0.1.0/src/tableflip/_parent.py

@@ -0,0 +1,115 @@
+"""Child-side IPC: communicate with the parent process that spawned us."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import struct
+
+from tableflip._fds import FdName, decode_fd_names
+from tableflip._process import FD_ENV_VAR, NOTIFY_READY, SENTINEL_ENV_VAR, Env
+
+logger = logging.getLogger(__name__)
+
+
+def _read_exact(fd: int, n: int) -> bytes:
+    """Read exactly n bytes from a file descriptor."""
+    buf = b""
+    while len(buf) < n:
+        chunk = os.read(fd, n - len(buf))
+        if not chunk:
+            return buf
+        buf += chunk
+    return buf
+
+
+class Parent:
+    """Represents the parent process from the child's perspective.
+
+    Created by new_parent() when a child detects it was spawned by tableflip.
+    Holds fd 3 (ready write pipe) and fd 4 (names read pipe).
+    """
+
+    def __init__(
+        self,
+        ready_w: int,
+        result: asyncio.Future[Exception | None],
+        exited: asyncio.Event,
+    ) -> None:
+        self._ready_w = ready_w
+        self.result = result
+        self.exited = exited
+
+    def send_ready(self) -> None:
+        """Write the ready byte to fd 3, then close it."""
+        try:
+            os.write(self._ready_w, bytes([NOTIFY_READY]))
+        finally:
+            os.close(self._ready_w)
+
+
+def new_parent(env: Env) -> tuple[Parent | None, dict[FdName, int]]:
+    """Decode inherited fds and create a Parent if we were spawned by tableflip.
+
+    Returns (None, {}) on first invocation (no parent).
+    Returns (Parent, inherited_fds) when spawned by a tableflip upgrade.
+    """
+    if not env.getenv(SENTINEL_ENV_VAR):
+        return None, {}
+
+    # Read fd numbers from environment. Layout: ready_w, names_r, ...inherited.
+    fd_str = env.getenv(FD_ENV_VAR)
+    if not fd_str:
+        return None, {}
+
+    fd_nums = [int(x) for x in fd_str.split(",")]
+    ready_w = env.new_file(fd_nums[0], "ready_w")
+    names_r = env.new_file(fd_nums[1], "names_r")
+
+    # Read length-prefixed fd names: 4-byte big-endian length then JSON payload.
+    length_buf = _read_exact(names_r, 4)
+    if length_buf:
+        (length,) = struct.unpack("!I", length_buf)
+        data = _read_exact(names_r, length) if length > 0 else b""
+        names = decode_fd_names(data) if data else []
+    else:
+        names = []
+
+    # Fds after the first two (ready_w, names_r) are inherited listeners.
+    files: dict[FdName, int] = {}
+    for i, parts in enumerate(names):
+        fd = fd_nums[2 + i]
+        env.close_on_exec(fd)
+        key: FdName = (parts[0], parts[1], parts[2])
+        files[key] = fd
+
+    loop = asyncio.get_running_loop()
+    result: asyncio.Future[Exception | None] = loop.create_future()
+    exited = asyncio.Event()
+
+    # The names pipe (fd 4) serves double duty: after delivering fd names,
+    # the parent holds the write end open. When the parent exits, EOF arrives.
+    async def watch_parent_exit() -> None:
+        try:
+            reader = asyncio.StreamReader()
+            transport, _ = await loop.connect_read_pipe(
+                lambda: asyncio.StreamReaderProtocol(reader),
+                os.fdopen(names_r, "rb", closefd=False),
+            )
+            remaining = await reader.read()
+            if remaining:
+                result.set_result(Exception("unexpected data from parent process"))
+            else:
+                result.set_result(None)
+        except Exception as e:
+            result.set_result(
+                Exception(f"unexpected error while waiting for parent to exit: {e}")
+            )
+        finally:
+            os.close(names_r)
+            exited.set()
+
+    asyncio.create_task(watch_parent_exit())
+
+    return Parent(ready_w, result, exited), files

tableflip-0.1.0/src/tableflip/_process.py

@@ -0,0 +1,111 @@
+"""Process spawning and environment abstraction for dependency injection."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+from typing import Protocol, runtime_checkable
+
+initial_wd: str = os.getcwd()
+
+SENTINEL_ENV_VAR = "TABLEFLIP_HAS_PARENT_7DIU3"
+FD_ENV_VAR = "TABLEFLIP_FDS"
+NOTIFY_READY = 42
+
+
+@runtime_checkable
+class Process(Protocol):
+    def signal(self, sig: int) -> None: ...
+    async def wait(self) -> int: ...
+    def __str__(self) -> str: ...
+
+
+class OsProcess:
+    """Wraps subprocess.Popen to implement the Process protocol."""
+
+    def __init__(self, proc: subprocess.Popen[bytes]) -> None:
+        self._proc = proc
+
+    def signal(self, sig: int) -> None:
+        self._proc.send_signal(sig)
+
+    async def wait(self) -> int:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self._proc.wait)
+
+    def __str__(self) -> str:
+        return f"pid={self._proc.pid}"
+
+
+@runtime_checkable
+class Env(Protocol):
+    """DI seam for OS interactions, mirroring Go's env struct."""
+
+    def new_proc(
+        self,
+        executable: str,
+        args: list[str],
+        fds: list[int],
+        environ: dict[str, str],
+    ) -> Process: ...
+
+    def new_file(self, fd: int, name: str) -> int: ...
+
+    def environ(self) -> dict[str, str]: ...
+
+    def getenv(self, key: str) -> str: ...
+
+    def close_on_exec(self, fd: int) -> None: ...
+
+
+class OsEnv:
+    """Production Env implementation using real OS calls."""
+
+    def new_proc(
+        self,
+        executable: str,
+        args: list[str],
+        fds: list[int],
+        environ: dict[str, str],
+    ) -> Process:
+        # Pass fds at their natural positions and communicate the fd numbers
+        # to the child via an environment variable. The child reads
+        # FD_ENV_VAR to discover which fds to use (ready_w, names_r, ...).
+        #
+        # We avoid remapping fds in the parent because dup2 temporarily
+        # clobbers fds used by asyncio's event loop (kqueue, self-pipe),
+        # and restoring them isn't enough — kqueue event registrations
+        # are lost when the fd is closed/replaced.
+        for fd in fds:
+            os.set_inheritable(fd, True)
+
+        environ[FD_ENV_VAR] = ",".join(str(fd) for fd in fds)
+
+        proc = subprocess.Popen(
+            [executable, *args],
+            pass_fds=tuple(fds),
+            env=environ,
+            cwd=initial_wd,
+        )
+
+        # Restore source fds to non-inheritable in the parent
+        for fd in fds:
+            try:
+                os.set_inheritable(fd, False)
+            except OSError:
+                pass
+
+        return OsProcess(proc)
+
+    def new_file(self, fd: int, name: str) -> int:
+        return fd
+
+    def environ(self) -> dict[str, str]:
+        return dict(os.environ)
+
+    def getenv(self, key: str) -> str:
+        return os.environ.get(key, "")
+
+    def close_on_exec(self, fd: int) -> None:
+        os.set_inheritable(fd, False)

tableflip-0.1.0/src/tableflip/_upgrader.py

@@ -0,0 +1,322 @@
+"""Main Upgrader class — orchestrates zero-downtime process upgrades."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import sys
+import tempfile
+from dataclasses import dataclass
+
+from tableflip._child import Child, start_child
+from tableflip._errors import (
+    AlreadyUpgradedError,
+    NotReadyError,
+    NotSupportedError,
+    TerminatingError,
+    UpgradeInProgressError,
+)
+from tableflip._fds import Fds, _InheritedFd
+from tableflip._parent import Parent, new_parent
+from tableflip._process import Env, OsEnv, initial_wd
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_UPGRADE_TIMEOUT: float = 60.0
+
+
+@dataclass
+class Options:
+    upgrade_timeout: float = DEFAULT_UPGRADE_TIMEOUT
+    pid_file: str | None = None
+
+
+_std_env_upgrader: Upgrader | None = None
+
+
+class Upgrader:
+    """Handles zero-downtime upgrades and passing files between processes."""
+
+    def __init__(
+        self,
+        *,
+        env: Env,
+        opts: Options,
+        parent: Parent | None,
+        fds: Fds,
+    ) -> None:
+        self._env = env
+        self._opts = opts
+        self._parent = parent
+        self.fds = fds
+        self._ready_event = asyncio.Event()
+        self._ready_called = False
+        self._stop_event = asyncio.Event()
+        self._exit_event = asyncio.Event()
+        self._upgrade_queue: asyncio.Queue[asyncio.Future[None]] = asyncio.Queue()
+        self._exit_fd: int | None = None  # prevent GC from closing the exit-detection pipe
+        self._parent_err: Exception | None = None
+        self._parent_err_set = False
+        self._run_task: asyncio.Task[None] | None = None
+
+    @classmethod
+    async def new(cls, opts: Options | None = None) -> Upgrader:
+        """Create a new Upgrader. Only one per process.
+
+        Raises NotSupportedError on Windows.
+        """
+        global _std_env_upgrader
+
+        if sys.platform == "win32":
+            raise NotSupportedError(
+                "tableflip: platform does not support graceful restart"
+            )
+
+        if _std_env_upgrader is not None:
+            raise RuntimeError("tableflip: only a single Upgrader allowed")
+
+        if opts is None:
+            opts = Options()
+
+        env = OsEnv()
+        upg = await new_upgrader(env, opts)
+        _std_env_upgrader = upg
+        return upg
+
+    async def ready(self) -> None:
+        """Signal that the current process is ready to accept connections.
+
+        Closes unused inherited fds and notifies the parent via pipe.
+        """
+        if not self._ready_called:
+            self._ready_called = True
+            self.fds.close_inherited()
+            self._ready_event.set()
+
+        if self._opts.pid_file:
+            write_pid_file(self._opts.pid_file)
+
+        if self._parent is not None:
+            self._parent.send_ready()
+
+    def exit(self) -> asyncio.Event:
+        """Return event that is set when the process should exit."""
+        return self._exit_event
+
+    def stop(self) -> None:
+        """Prevent further upgrades and signal exit."""
+        if not self._stop_event.is_set():
+            self._stop_event.set()
+
+    async def wait_for_parent(self) -> None:
+        """Block until the parent has exited.
+
+        Raises if the parent misbehaved during shutdown.
+        """
+        if self._parent is None:
+            return
+
+        if not self._parent_err_set:
+            await self._parent.exited.wait()
+            err = self._parent.result.result()
+            self._parent_err = err
+            self._parent_err_set = True
+
+        if self._parent_err is not None:
+            raise self._parent_err
+
+    def has_parent(self) -> bool:
+        return self._parent is not None
+
+    async def upgrade(self) -> None:
+        """Trigger an upgrade. Blocks until the new process is ready or fails."""
+        if self._stop_event.is_set():
+            raise TerminatingError("terminating")
+        if self._exit_event.is_set():
+            raise AlreadyUpgradedError("already upgraded")
+
+        response: asyncio.Future[None] = asyncio.get_running_loop().create_future()
+        await self._upgrade_queue.put(response)
+        await response
+
+    async def _run(self) -> None:
+        """Main event loop — mirrors Go's run() select loop.
+
+        Tracks parent exit, process readiness, stop requests, and upgrade requests.
+        Uses asyncio.wait with FIRST_COMPLETED to mimic Go's select.
+        """
+        parent_exited = self._parent is None
+        process_ready = False
+
+        while True:
+            tasks: dict[str, asyncio.Task[object]] = {}
+
+            if not parent_exited and self._parent is not None:
+                tasks["parent"] = asyncio.create_task(self._parent.exited.wait())
+            if not process_ready:
+                tasks["ready"] = asyncio.create_task(self._ready_event.wait())
+
+            tasks["stop"] = asyncio.create_task(self._stop_event.wait())
+            tasks["upgrade"] = asyncio.create_task(self._upgrade_queue.get())
+
+            done, _ = await asyncio.wait(
+                tasks.values(),
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            for task in tasks.values():
+                if task not in done:
+                    task.cancel()
+
+            # Suppress CancelledError from cancelled tasks
+            for task in tasks.values():
+                if task not in done:
+                    try:
+                        await task
+                    except (asyncio.CancelledError, Exception):
+                        pass
+
+            for task in done:
+                result = task.result()
+
+                # Identify which event completed by checking task identity
+                if tasks.get("parent") is task:
+                    parent_exited = True
+                    continue
+
+                if tasks.get("ready") is task:
+                    process_ready = True
+                    continue
+
+                if tasks.get("stop") is task:
+                    self.fds.close_used()
+                    self._exit_event.set()
+                    return
+
+                if tasks.get("upgrade") is task:
+                    request: asyncio.Future[None] = result  # type: ignore[assignment]
+                    if not process_ready:
+                        request.set_exception(
+                            NotReadyError("process is not ready yet")
+                        )
+                        continue
+                    if not parent_exited:
+                        request.set_exception(RuntimeError("parent hasn't exited"))
+                        continue
+
+                    try:
+                        exit_fd = await self._do_upgrade()
+                        self._exit_fd = exit_fd
+                        self.fds.close_used()
+                        request.set_result(None)
+                        self._exit_event.set()
+                        return
+                    except Exception as e:
+                        request.set_exception(e)
+
+    async def _do_upgrade(self) -> int:
+        """Fork a child and wait for it to become ready. Returns the exit fd."""
+        child = await start_child(self._env, self.fds.copy_used())
+
+        try:
+            return await asyncio.wait_for(
+                self._wait_for_child(child),
+                timeout=self._opts.upgrade_timeout,
+            )
+        except asyncio.TimeoutError:
+            child.kill()
+            raise TimeoutError(f"new child {child} timed out") from None
+
+    async def _wait_for_child(self, child: Child) -> int:
+        """Wait for child ready or exit, handling concurrent upgrade requests."""
+        ready_task = asyncio.create_task(self._wrap_ready(child))
+        result_task = asyncio.create_task(self._wrap_result(child))
+        upgrade_task = asyncio.create_task(self._drain_upgrades())
+        stop_task = asyncio.create_task(self._wrap_stop(child))
+
+        try:
+            done, _ = await asyncio.wait(
+                [ready_task, result_task, stop_task],
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            for task in done:
+                return task.result()
+
+        finally:
+            for t in [ready_task, result_task, upgrade_task, stop_task]:
+                t.cancel()
+                try:
+                    await t
+                except (asyncio.CancelledError, Exception):
+                    pass
+
+        raise RuntimeError("unreachable")  # pragma: no cover
+
+    async def _wrap_ready(self, child: Child) -> int:
+        return await child.ready
+
+    async def _wrap_result(self, child: Child) -> int:
+        err = await child.result
+        if err is None:
+            raise RuntimeError(f"child {child} exited")
+        raise RuntimeError(f"child {child} exited: {err}")
+
+    async def _wrap_stop(self, child: Child) -> int:
+        await self._stop_event.wait()
+        child.kill()
+        raise TerminatingError("terminating")
+
+    async def _drain_upgrades(self) -> None:
+        """Reject any concurrent upgrade requests while one is in progress."""
+        while True:
+            request = await self._upgrade_queue.get()
+            request.set_exception(UpgradeInProgressError("upgrade in progress"))
+
+
+async def new_upgrader(env: Env, opts: Options) -> Upgrader:
+    """Internal constructor — mirrors Go's newUpgrader."""
+    if not initial_wd:
+        raise RuntimeError("couldn't determine initial working directory")
+
+    parent, files = new_parent(env)
+
+    if opts.upgrade_timeout <= 0:
+        opts.upgrade_timeout = DEFAULT_UPGRADE_TIMEOUT
+
+    inherited = {}
+    for name, fd in files.items():
+        inherited[name] = _InheritedFd(fd, name)
+
+    fds = Fds(inherited=inherited)
+    upg = Upgrader(env=env, opts=opts, parent=parent, fds=fds)
+    upg._run_task = asyncio.create_task(upg._run())
+    return upg
+
+
+def write_pid_file(path: str) -> None:
+    """Atomically write the current PID to a file."""
+    dir_path, file_name = os.path.split(path)
+    if not dir_path:
+        dir_path = initial_wd
+    if not dir_path:
+        raise RuntimeError("empty initial working directory")
+
+    fd = -1
+    tmp_path = ""
+    try:
+        fd, tmp_path = tempfile.mkstemp(prefix=file_name, dir=dir_path)
+        os.write(fd, str(os.getpid()).encode())
+        os.close(fd)
+        fd = -1
+        os.rename(tmp_path, path)
+    except BaseException:
+        if fd >= 0:
+            os.close(fd)
+        if tmp_path:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+        raise

tableflip-0.1.0/src/tableflip/testing.py

@@ -0,0 +1,48 @@
+"""Stub implementations for testing and unsupported platforms."""
+
+from __future__ import annotations
+
+import asyncio
+import socket
+
+from tableflip._errors import NotSupportedError
+from tableflip._fds import _create_tcp_listener
+
+
+class Fds:
+    """Stub Fds that creates listeners directly (no inheritance)."""
+
+    async def listen(self, addr: str, port: int) -> socket.socket:
+        return _create_tcp_listener(addr, port)
+
+    def get_listener(self, addr: str, port: int) -> socket.socket | None:
+        return None
+
+    def add_listener(self, addr: str, port: int, sock: socket.socket) -> None:
+        pass
+
+
+class Upgrader:
+    """Stub Upgrader that never actually upgrades."""
+
+    def __init__(self) -> None:
+        self.fds = Fds()
+        self._exit_event = asyncio.Event()
+
+    async def ready(self) -> None:
+        pass
+
+    def exit(self) -> asyncio.Event:
+        return self._exit_event
+
+    def stop(self) -> None:
+        pass
+
+    async def wait_for_parent(self) -> None:
+        pass
+
+    def has_parent(self) -> bool:
+        return False
+
+    async def upgrade(self) -> None:
+        raise NotSupportedError("stub upgrader does not support upgrades")