Skip to main content

Snakeway v0.14.0

Ethan Hann

Highlights​

Source-level config diagnostics​

Configuration errors now point to the exact file, line, and column where the problem is. Previously, validation errors were plain-text messages that named the offending field but left it to the operator to locate it. In v0.14.0, every error and warning includes source context so the problem is immediately visible.

Pretty output (snakeway config check):

error: invalid CIDR range
  --> ingress.d/api.hcl:3:11
   |
 3 |   allow = ["10.0.0.0/8", "bad"]
   |                          ^^^^^
   = help: expected a valid CIDR range (e.g. 10.0.0.0/8 or ::1/128)

Plain output (snakeway config check --format plain):

ingress.d/api.hcl:3:11: error: invalid CIDR range
  help: expected a valid CIDR range (e.g. 10.0.0.0/8 or ::1/128)

JSON output (snakeway config check --format json) also includes source locations, making it straightforward to integrate with editors or CI tooling.

When multiple files contain errors, all of them are reported in a single pass rather than stopping at the first failure.

Pingora 0.8.1​

The underlying proxy engine has been updated to Pingora 0.8.1. No configuration changes are required. This update includes upstream bug fixes and performance improvements.

Breaking Changes​

Two identity-device checks that were warnings in v0.13 are now hard validation errors. A config that triggers either one no longer loads: snakeway config check reports the problem and exits non-zero, and the proxy refuses to start until it is fixed.

Each check catches a configuration that enables a feature the proxy cannot actually deliver, thus it is a misconfiguration. Promoting them to errors surfaces the mistake at config time. Leaving it as a warning would let the proxy start in a state where the feature silently did nothing, which is harder to notice than a failed config check.

If neither of these applies to your config, nothing changes for you.

Enabling GeoIP with no database now fails validation​

The identity_device block accepts enable_geoip = true, but GeoIP enrichment needs at least one database to read from: geoip_city_db, geoip_isp_db, or geoip_connection_type_db. Enabling GeoIP without any of them is a no-op.

Before (v0.13): the config below loaded with a warning, and the proxy ran with GeoIP enabled but doing nothing.

After (v0.14.0): the same config is rejected.

# device.d/identity.hcl
identity_device {
  enable       = true
  enable_geoip = true
  # no geoip_*_db set
}
error: geoip enabled with no dbs specified
  help: At least one geoip db must be specified

What to do: point at least one of geoip_city_db, geoip_isp_db, or geoip_connection_type_db at a database file, or set enable_geoip = false.

An unrecognized ua-parser regexes file now fails validation​

When ua_parser_regexes points at a custom regexes file, Snakeway checks that the file looks like a uap-core regexes.yaml by looking for a user_agent_parsers section. A file without it is almost certainly the wrong file, and using it silently degrades user-agent parsing.

Before (v0.14.0): an unrecognized file produced a warning, and the proxy started using it anyway.

After (v0.14.0): the same config is rejected.

# device.d/identity.hcl
identity_device {
  enable            = true
  ua_parser_regexes = "regexes.yaml"
}
error: ua_parser_regexes file does not appear to be a valid ua-parser regexes.yaml: regexes.yaml
  help: Expected the file to contain a 'user_agent_parsers' section. See https://github.com/ua-parser/uap-core for the expected format.

What to do: point ua_parser_regexes at a valid uap-core regexes.yaml (one that contains a user_agent_parsers section), or remove the setting to use the bundled default.

note

This check is a content heuristic: it looks for the user_agent_parsers string, not a full YAML parse. An unusual but valid file that does not contain that literal section name will be rejected. If you hit that, removing the setting falls back to the bundled default.

Upgrade Notes​

Run snakeway config check before upgrading. The two new validation errors described above will surface any affected configurations. If the check passes on v0.13.1, the same config will load without issues on v0.14.0.