Skip to main content

Snakeway v0.9.0

Ethan Hann

Breaking Changes​

TLS configuration now requires a mode​

The tls block inside bind and bind_admin now requires an explicit mode field.

Before (v0.8.0):

bind = {
  tls = {
    cert = "/path/to/certs/server.pem"
    key  = "/path/to/certs/server.key"
  }
}

After (v0.9.0):

bind = {
  tls = {
    mode = "manual"
    cert = "/path/to/certs/server.pem"
    key  = "/path/to/certs/server.key"
  }
}

Set mode = "manual" to preserve the existing behavior. The new "acme" mode enables automatic certificate issuance and renewal.

Routes now require a hosts field​

Service routes and static file routes now require a hosts list. This enables virtual hosting — multiple domains can be served from a single Snakeway instance.

Before (v0.8.0):

routes = [
  { path = "/api" }
]

After (v0.9.0):

routes = [
  {
    hosts = ["example.com"]
    path  = "/api"
  }
]

Use ["*"] to match all hostnames and preserve previous behavior when upgrading:

routes = [
  {
    hosts = ["*"]
    path  = "/api"
  }
]

New Features​

Automatic TLS Certificate Renewal (ACME)​

Snakeway now supports automatic TLS certificate issuance and renewal via the ACME protocol (Let's Encrypt).

Configure tls_automation in snakeway.hcl:

server {
  tls_automation = {
    renew_within_days = 30
    acme = {
      directory_url = "https://acme-v02.api.letsencrypt.org/directory"
      data_dir      = "/var/lib/snakeway/acme"
      contact_email = ["admin@example.com"]
    }
    cert_store = {
      type     = "filesystem"
      cert_dir = "/var/lib/snakeway/acme/certs"
    }
  }
}

Then set mode = "acme" on any bind block you want managed automatically:

bind = {
  tls = {
    mode      = "acme"
    domains   = ["example.com", "api.example.com"]
    challenge = "http01"
  }
}

Certificates are renewed automatically in the background. No restart or reload is required.

See the TLS Cert Management guide for full details.

Virtual Hosting (SNI / host-based routing)​

Routes now accept a hosts list, allowing a single Snakeway instance to serve multiple domains. Incoming requests are matched against the Host header before path matching is applied.

See the Routes reference for full details.

Upstream TLS​

Upstream connections can now be made over TLS. Configure this per endpoint:

endpoint = {
  host = "backend.internal"
  port = 8443
  tls = {
    sni    = "backend.internal"
    verify = true
    // ca_file = "/path/to/ca.pem"  // optional; falls back to server.ca_file
  }
}

See the Upstream TLS reference for the full field reference.

route solve CLI Command​

Debug routing decisions without starting the proxy. The command runs the same config loading, lowering, and routing logic used by the live proxy:

snakeway route solve http://example.com/api/v1/users --config /etc/snakeway

Supports --trace, --verbose, --format=json, and deterministic upstream selection via --lb-index / --lb-key.

See route solve for full documentation.