ThwipHome

Configuration / Proxy

Upstreams

Groups give multiple proxy routes a reusable set of backend servers and a balancing policy.

Named group 

[upstreams.api]
policy = "weighted_round_robin"
servers = [
  { url = "http://127.0.0.1:9001", weight = 2 },
  { url = "http://127.0.0.1:9002", weight = 1 },
]

[[http.servers.locations]]
matcher = { type = "prefix", path = "/api" }
action = { type = "proxy", upstream_group = "api" }

The table key (api) is the group name. Names and endpoint URLs cannot be empty, every group needs at least one server, and each weight must exceed zero. An omitted weight is 1.

Policies

Policy Behavior Use case
round_robin Visits every configured endpoint in sequence. Backends with similar capacity.
weighted_round_robin Selects endpoints proportionally to their weights. Mixed-capacity backends or gradual traffic shifts.

weighted_round_robin is the default. A 2:1 pair targets the first endpoint approximately twice for each selection of the second.

Where state lives

Named routes referencing the same group share a selection cursor within a worker. Each worker process has its own cursor, so balancing is not a globally synchronized request counter. In practice, incoming TCP connections are first distributed across workers by the kernel, and each worker then selects an upstream.

DNS and failures

Endpoint selection happens before hostname resolution. If a selected hostname has several addresses, Thwip can try those addresses as connection fallbacks; it does not treat them as independently weighted upstreams. Configure independent endpoints when their traffic share must be explicit.

Choosing group scope