Snakeway v0.12.0

Highlights

Zero-drop hot reload of listeners

Snakeway can now reload listener-level configuration without dropping connections. Previously, changes to listener address, port, TLS termination, HTTP/2, connection filters, or worker thread count required a full restart with a brief interruption. These now apply through a zero-drop upgrade that preserves the TCP accept queue and lets in-flight requests drain to completion.

The reload loop picks the right path automatically. SIGHUP and POST /admin/reload continue to work for both runtime-swappable changes (routes, services, devices, TLS certs) and listener-level changes; operators do not need to choose between them.

A new snakeway upgrade command is available for manual control, but most operators will not need it. See the Hot Reload page for details, including the Linux-only caveat for the underlying file-descriptor transfer.

Admin API authentication (breaking)

The Admin API now requires bearer token authentication. Every admin request must present an Authorization: Bearer <token> header; requests without one (or with an unknown token) receive 401 Unauthorized.

Tokens are configured via a token file referenced from the bind_admin block:

bind_admin = {
  interface = "127.0.0.1"
  port      = 8440
  tls = {
    mode = "manual"
    cert = "/etc/snakeway/admin.crt"
    key  = "/etc/snakeway/admin.key"
  }
  auth = {
    bearer = {
      token_file = "/etc/snakeway/admin.tokens"
    }
  }
}

The token file holds one token per line, each at least 32 bytes. Multiple tokens are accepted concurrently to support rotation: append the new token, reload, migrate callers, remove the old token, reload again. There is no window where a caller must choose between the old and new token.

Authentication is the innermost of three layers and does not replace network-level restriction or TLS. The bind_admin listener still rejects wildcard interfaces and still requires manual TLS. See the Admin API guide for the full reference and rotation workflow.

Configurable config directory via environment variable

A new SNAKEWAY_CONFIG environment variable sets the config directory for all CLI commands. This removes the need to repeat --config /etc/snakeway on every invocation when working with a non-default config path.

export SNAKEWAY_CONFIG=/etc/snakeway

snakeway config check
snakeway config dump
snakeway route solve ...
snakeway run

An explicit --config flag always takes precedence. The packaged systemd unit and Docker image both set this variable to /etc/snakeway, so operators who SSH into a production host can run diagnostic commands without specifying the path.

Secret zeroize-on-drop

Bearer token digests and TLS private keys are now zeroed in memory when dropped, narrowing the window during which a process memory dump could expose long-lived secrets.

Everything else

CLI

• New snakeway upgrade command for manually triggering a zero-drop upgrade. Like reload, it requires a configured pid_file. The automatic upgrade path triggered by reload is sufficient for most workflows.
• New --test flag on snakeway run validates the configuration and exits with code 0 if valid or 1 if not. Useful for verifying a new binary or config before committing to an upgrade.

Server block

Two new fields support the zero-drop upgrade path:

• upgrade_sock (default /tmp/pingora_upgrade.sock): set a unique value when running multiple Snakeway instances on the same host.
• upgrade_max_retries (default 5): retry budget for the cross-process handoff.

Packaging

• The Docker image and systemd unit both set SNAKEWAY_CONFIG=/etc/snakeway.

Documentation

• New Hot Reload page covering both reload paths and platform constraints.
• The Admin API guide gained a full Authentication section.
• The Server block reference documents the new upgrade_sock and upgrade_max_retries fields.
• The CLI reference documents the new upgrade command, the run --test flag, and the SNAKEWAY_CONFIG environment variable.
• Added an Ubuntu/Debian install note pointing to the .deb package on the releases page.
• Roadmap milestones reorganized.

Upgrade Notes

If you have a bind_admin block in your config, add an auth.bearer.token_file entry and create the token file before upgrading. Existing configs without admin auth will fail validation on the new release. See the Admin API authentication guide for the token file format.

If you intend to use the zero-drop upgrade path, ensure pid_file is set in your server block, and set upgrade_sock to a host-unique path if you run multiple Snakeway instances on the same machine.