Skip to main content

Snakeway v0.13.0

Ethan Hann

Highlights​

Graceful shutdown controls​

Snakeway now gives you explicit control over how the proxy shuts down. When the process receives SIGTERM (or systemctl stop), active connections get a configurable window to finish before being dropped:

server {
  shutdown {
    drain_seconds = 10  # default: 10
    force_timeout_seconds = 30
  }
}

Previously, a shutdown with long-lived connections (WebSocket, gRPC streams) could hang indefinitely. The new defaults give connections 10 seconds to complete, and force_timeout_seconds provides a hard ceiling when set.

Organized server configuration (breaking)​

Several server settings have been reorganized into logical groups. This makes the config file easier to read and reduces clutter at the top level of the server block.

Before (v0.12.0):

server {
  version       = 1
  threads       = 8
  work_stealing = true
  upgrade_sock  = "/var/run/snakeway_upgrade.sock"
}

After (v0.13.0):

server {
  version = 1
  threads = 8

  upgrade {
    sock = "/var/run/snakeway_upgrade.sock"
  }

  performance {
    work_stealing = true
  }
}

The following fields moved into sub-blocks:

  • work_stealing moved into performance {}
  • upgrade_sock and upgrade_max_retries moved into upgrade {} (renamed to sock and max_retries)

All sub-blocks are optional. When omitted, the defaults apply.

New performance tuning options​

Two new settings in the performance {} block let you tune connection handling:

performance {
  upstream_connection_pool_size = 256  # default: 128
  parallel_accepts_per_listener = 4    # default: 1
}

upstream_connection_pool_size controls how many idle connections are kept warm to upstream servers per worker thread. Increase this for high-traffic deployments with many backends.

parallel_accepts_per_listener controls how many accept tasks run per listener. Higher values reduce contention under bursty connection rates. Most deployments do not need to change this.

Upstream source address binding​

A new upstream_source_addresses block lets you pin outbound upstream connections to specific local IP addresses:

server {
  upstream_source_addresses {
    ipv4 = ["10.0.1.5", "10.0.1.6"]
    ipv6 = ["fd00::1"]
  }
}

This is useful when your server has multiple network interfaces and you need upstream traffic to exit through a specific one, or when upstream servers use IP-based access control. When multiple addresses are specified, Snakeway round-robins across them.

Default config directory​

The default config directory is now /etc/snakeway on all platforms. Previously, the --config flag was required unless SNAKEWAY_CONFIG was set. This aligns with the systemd unit and Docker image, both of which already used /etc/snakeway.

Improved systemd service​

The packaged systemd unit gained several fixes discovered during production testing:

  • SNAKEWAY_LOG_DIR is now set, so logs are written to /var/log/snakeway/.
  • LogsDirectory=snakeway ensures the log directory exists with correct ownership.
  • TimeoutStopSec=30 prevents the stop command from hanging indefinitely if connections do not drain within the configured shutdown window.

Validation warnings no longer block startup​

Configuration warnings (non-critical issues like unused TLS automation with no TLS listeners) no longer prevent the proxy from starting. Only errors block startup. Warnings are still printed to stderr so operators can address them at their convenience.

Documentation​

  • The Server block reference documents all new settings: shutdown, performance, upstream_source_addresses, and the reorganized upgrade block.
  • New confval page documents the validation primitives crate.
  • The Configuration Internals page reflects the updated validation architecture.

Upgrade Notes​

The work_stealing, upgrade_sock, and upgrade_max_retries fields have moved into sub-blocks. Update your snakeway.hcl before upgrading:

  • work_stealing = true becomes performance { work_stealing = true }
  • upgrade_sock = "..." becomes upgrade { sock = "..." }
  • upgrade_max_retries = 5 becomes upgrade { max_retries = 5 }

If you omit these blocks entirely, the defaults apply and no action is needed.