ecdysis

The ecdysis library is a Rust tool designed for performing graceful restarts of network services. It allows you to update running code or configuration without disrupting existing client connections by starting a new process, transferring clients to it, and then exiting the old process.

Key design goals include:

• Ensuring no old code remains running after a successful upgrade.
• Providing a grace period for the new process to perform initialization.
• Allowing the process to crash safely during the initialization phase.
• Ensuring only a single upgrade runs in parallel at any time.

ecdysis is based on the Go library tableflip and is suitable for scenarios where socket inheritance and rebinding are prioritized.

When choosing between ecdysis and shellflip for graceful reloads, consider your primary use case:

Use shellflip if you need a user-friendly way to share complex state/data. Use ecdysis if your priority is managing network socket inheritance.

You can enable support for managing and persisting systemd-spawned named sockets by enabling the systemd_sockets crate feature. This is useful for passing network connections from a parent process to a child process via systemd.

Requirements:

1. Enable the systemd_sockets feature (this automatically enables tokio_ecdysis and requires the tokio crate).
2. Use named systemd sockets. ecdysis will ignore anonymous file descriptors or file descriptors with duplicate/special names as defined by sd_listen_fds.

Note: Failure to meet these requirements will cause ecdysis to fail during initialization.

You can integrate ecdysis with systemd's process status notification capabilities by enabling the systemd_notify crate feature. This enables automatic compatibility with systemd service status notifications.

Requirements:

1. Enable the systemd_notify feature (this automatically enables tokio_ecdysis and requires the tokio crate).
2. Use systemd version v253 or newer.
3. Set Type=notify-reload in your application's systemd service unit configuration file.

Note: Failure to meet these requirements will cause ecdysis to fail during initialization.

The ListenerRegistry manages file descriptors (FDs) used for socket listeners during Ecdysis process upgrades. It maintains two distinct collections of ListenerInfo to handle the handoff between parent and child processes:

1. used_fds: Tracks FDs opened by the parent via Ecdysis::listen_* methods. When adding a listener to this registry, the FD is duplicated (via dup) to ensure the original listener's semantics remain unchanged. These are serialized and sent to the child process.
2. inherited_fds: Stores FDs received from the parent during a child process upgrade. The child uses the inherit method to retrieve these FDs based on their socket information.

When a file descriptor is retrieved from inherited_fds via take, the registry automatically sets the CLOEXEC flag on it to ensure safe handling in subsequent executions.

To run the integration tests in a Docker container, use docker compose up.

If you are developing on a machine protected by Cloudflare WARP, you must provide the path to your WARP certificates via the CF_CERTS environment variable. This allows the container to mount the necessary root certificates to prevent network failures during tests. If this variable is not set, the container mounts /dev/null and the initial certificate setup commands will fail silently.

Note: The init: true setting in the configuration is used to ensure child processes do not become zombies.

# For Cloudflare employees on WARP-protected machines:
$ CF_CERTS=~/.local/share/cloudflare-warp-certs docker compose up

# For others (or non-WARP machines):
$ docker compose up

If the systemd_notify feature is enabled, TokioEcdysis can manage systemd lifecycle notifications.

Setup

1. Call enable_systemd_notifications() on the builder to initialize the notifier.
2. The lifecycle.await future will automatically send READY=1 when the process is ready and RELOADING=1 when an upgrade starts.

Extending Timeouts

Use extend_systemd_timeouts(duration) to tell systemd to extend the startup, runtime, or shutdown timeouts. This is useful if your post-Ecdysis shutdown logic is slow.

Partial Shutdowns

When a partial_stop_on_signal is triggered, the lifecycle.await future returns ExitMode::PartialStopWithSystemd(SystemdNotifier). This allows the caller to manually handle systemd notifications if desired.

The TokioEcdysisBuilder allows you to define what events trigger different lifecycle actions:

Upgrade Triggers

Triggers an upgrade (fork-exec to a new process) while attempting to hand over sockets.

• upgrade_on_socket(path): Triggers an upgrade when a connection is made to the specified Unix Domain Socket.
• (Default) The SignalKind passed to new() triggers an upgrade.

Stop (Full Shutdown) Triggers

Triggers a graceful shutdown of the process.

• stop_on_signal(signal_kind): Registers a Unix signal to trigger a full stop.
• stop_on_socket(path): Triggers a full stop when a connection is made to the specified Unix Domain Socket.

Partial Stop Triggers

Triggers a partial shutdown where Ecdysis stops monitoring triggers but skips other shutdown steps (like notifying systemd).

• partial_stop_on_signal(signal_kind)
• partial_stop_on_socket(path)

Use Ecdysis::new() to initialize the upgrade manager. This function automatically detects if the current process is a child process resulting from a previous upgrade attempt.

• If it is a child process, it inherits the listening sockets from the parent.
• If it is the parent process, it initializes a new registry for managing sockets.

If the environment is not correctly set up for an upgrade, the process will exit with code 1.

use ecdysis::Ecdysis;

let ecdysis = Ecdysis::new();

if ecdysis.is_child() {
    // Logic for the new version of your application
} else {
    // Logic for the current version of your application
}

The integration test environment uses the CF_CERTS environment variable to mount Cloudflare root certificates into the container at /opt/cf.

• Variable Name: CF_CERTS
• Default Value: /dev/null (if unset)
• Container Mount Path: /opt/cf
• Purpose: Provides CloudflareRootCertificate.pem to the container so it can be installed into the system trust store via update-ca-certificates.