cloudflare/tableflip
Tableflip
Tableflip is a zero-downtime restart library and system utility designed to transfer network sockets and open file descriptors between process instances. It serves as a process lifecycle manager that coordinates the handoff of TCP, UDP, and Unix domain sockets from a parent process to a child process to maintain active sessions during service upgrades.
The tool facilitates seamless restarts by utilizing file-based process ID tracking and system signals to trigger the spawning of new process instances. It ensures continuous service availability by handing over network listeners and using readiness signaling to notify parent processes when a new instance is prepared to take over.
The library also manages the transition phase through graceful shutdown coordination, which includes draining existing connections and synchronizing process exits. This is supported by low-level primitives for managing file descriptor transitions and signal-driven lifecycle events.
Features
- Socket Handoffs - Passes open TCP or UDP listeners from a parent process to a child process to maintain continuous service availability.
- Zero-Downtime Socket Handovers - Provides a mechanism to transfer listening TCP, UDP, and Unix domain sockets between processes to ensure continuous service availability during restarts.
- Process Lifecycle Managers - Acts as a coordinator for graceful shutdowns and process synchronization using file-based tracking and system signals.
- Graceful Shutdowns - Ensures clean termination of services by allowing in-flight requests to complete before shutting down.
- Zero-Downtime Upgrades - Updates application code without dropping active network connections by transferring file descriptors between processes.
- Listener Handoffs - Hands over TCP, UDP, and Unix domain socket listeners to a child process to maintain connectivity.
- Descriptor Passing - Provides a mechanism for passing network sockets and open files between process instances to maintain active sessions.
- File Descriptor Restoration - Allows the transfer of open file descriptors from a parent process to a child process to maintain active connections.
- Process Handoff Synchronization - Coordinates process shutdown by waiting for the parent process to exit or acknowledge the resource transfer.
- Process Lifecycle Management - Coordinates the handoff and graceful shutdown of system processes during version upgrades or configuration changes.
- Signal-Driven Process Spawning - Triggers the creation of a new process instance and resource transfer upon receiving specific system signals.
- Upgrade Signaling - Triggers a new process instance and transfer of file descriptors upon receiving a specific system signal.
- Connection Draining - Implements a mechanism to stop accepting new connections while allowing existing requests to complete before process exit.
- Socket Transfer Utilities - Provides a system for handing over Unix domain sockets and network listeners between processes during service upgrades.
- Non-Blocking File Descriptor Transitions - Sets inherited file descriptors to non-blocking mode to prevent the child process from hanging during execution.
- Process Shutdown Synchronization - Synchronizes process shutdown by waiting for a parent process to exit or responding to system signals.
- Readiness Notifiers - Notifies a parent process that a new instance is ready to take over and clean up inherited descriptors.
- PID-Based Process Tracking - Uses a persistent file to store the process ID for coordinating transitions between old and new versions.
