Skip to content

suspend_when_proxy_unhealthy

Since: Dev Builds Only

The functionality described in this section requires a dev build of KumoMTA. You can obtain a dev build by following the instructions in the Installation section.

Optional table.

Automatically suspend this egress source for the specified duration when the configured proxy server appears unreachable. The following kinds of failure count toward this rule:

  • The proxy is unreachable, refuses the connection, or times out (ConnectError with is_proxy = true).
  • The proxy server itself reports a bind failure for the requested source address (ProxyBindError).

See ha_proxy_server and socks5_proxy_server for the configuration that selects the proxy.

While a source is suspended, pool selection skips it, which allows other sources in the pool to be used instead of delaying the message. If every source in a pool is suspended, messages assigned to that pool are delayed until the earliest suspension expires.

The configuration is a table with the following fields:

  • trigger - when to fire the rule. Defaults to 'Immediate' — a single matching failure trips the rule. Use { Threshold = "N/period" } (the same syntax used by TSA shaping rules) to tolerate transient noise: the rule fires only after N matching failures within the rolling window.
  • duration - how long the source stays suspended once the rule fires. Required.
suspend_when_proxy_unhealthy = {
  trigger = { Threshold = '3/5m' }, -- optional; defaults to Immediate
  duration = '10m',
}

Suspension is process-local — there is no cluster coordination.

Observability:

A transition into the suspended state is also logged at WARN; the auto-clear is logged at INFO.

See also suspend_when_unplumbed.

Examples

Tolerate a few transient proxy hiccups by requiring N failures within a rolling window before suspending. This is the typical configuration for proxy-backed sources, since proxies sometimes flap briefly without warranting the source being removed from pool selection.

kumo.on('get_egress_source', function(source_name)
  return kumo.make_egress_source {
    name = source_name,
    socks5_proxy_server = 'proxy.example.com:1080',
    socks5_proxy_source_address = '10.0.0.1',
    suspend_when_proxy_unhealthy = {
      trigger = { Threshold = '3/5m' },
      duration = '10m',
    },
  }
end)

If you're using the sources helper, you can define the same source using the following syntax:

[source."ip-1"]
socks5_proxy_server = "proxy.example.com:1080"
socks5_proxy_source_address = "10.0.0.1"
suspend_when_proxy_unhealthy = { trigger = { Threshold = "3/5m" }, duration = "10m" }

{
  "source": {
    "ip-1": {
      "socks5_proxy_server": "proxy.example.com:1080",
      "socks5_proxy_source_address": "10.0.0.1",
      "suspend_when_proxy_unhealthy": {
        "trigger": {
          "Threshold": "3/5m"
        },
        "duration": "10m"
      }
    }
  }
}

If your proxy infrastructure is intended to be rock-solid and a single failure indicates a real outage worth acting on immediately, omit trigger (defaults to 'Immediate') so the first matching failure trips the rule and removes the source from pool selection.

kumo.on('get_egress_source', function(source_name)
  return kumo.make_egress_source {
    name = source_name,
    socks5_proxy_server = 'proxy.example.com:1080',
    socks5_proxy_source_address = '10.0.0.1',
    suspend_when_proxy_unhealthy = {
      -- trigger defaults to 'Immediate'
      duration = '10m',
    },
  }
end)

Or, in the sources-helper TOML form:

[source."ip-1"]
socks5_proxy_server = "proxy.example.com:1080"
socks5_proxy_source_address = "10.0.0.1"
suspend_when_proxy_unhealthy = { duration = "10m" }

{
  "source": {
    "ip-1": {
      "socks5_proxy_server": "proxy.example.com:1080",
      "socks5_proxy_source_address": "10.0.0.1",
      "suspend_when_proxy_unhealthy": {
        "duration": "10m"
      }
    }
  }
}