proxy_float

This escaper reaches the target through remote proxies that are published at runtime.

The following remote proxy protocols are supported:

HTTP proxy
HTTPS proxy
SOCKS5 proxy

The following interfaces are supported:

tcp connect
udp relay (SOCKS5 peers only)
udp connect (SOCKS5 peers only)
http(s) forward

This escaper supports the Cap’n Proto RPC publish command. The published data must be either a single peer or an array of peers.

Published peers whose expire time is already in the past are ignored.

The following egress path selection values are supported:

string id

If matched, the peer with the same id is used.

Added in version 1.9.2.
json value

If matched, the JSON map value is parsed as a peer and used directly.

Added in version 1.9.2.

Config Keys

The following common keys are supported:

source

optional, type: url str | map | null

Set the source used to fetch peers.

Multiple source types are supported. The type is detected from the URL scheme or from the type key in the map. See sources for the supported formats.

If the selected source maintains local state, a cache file is strongly recommended so the escaper can continue serving requests before the next refresh completes.

default: passive

cache

recommend, type: file path

Set the cache file.

This is recommended because peer discovery at startup may complete only after the first requests arrive.

The file is created if it does not exist.

The cache path is resolved relative to the config file location.

default: not set

refresh_interval

optional, type: humanize duration

Set how often peers are refreshed from the configured source.

default: 1s

bind_ipv4

optional, type: ipv4 addr str

Set the bind IP address for IPv4 sockets.

default: not set

bind_ipv6

optional, type: ipv6 addr str

Set the bind IP address for IPv6 sockets.

default: not set

tls_client

optional, type: bool | openssl tls client config

Enable HTTPS peers and set TLS parameters for the local TLS client. If set to true or an empty map, the default TLS client configuration is used.

default: not set

tcp_connect_timeout

optional, type: humanize duration

Set the application-level TCP connect timeout.

default: 30s

tcp_keepalive

optional, type: tcp keepalive

Configure TCP keepalive.

User-level TCP keepalive settings are not applied.

default: 60s

expire_guard_duration

optional, type: humanize duration

If a peer has an expiration time, it is skipped when adding this guard duration would carry the connection past expiry.

default: 5s

Sources

For the map format, the type key is always required.

passive

Do not fetch peers. Only RPC publish is used.

The root value of source may be null to use the passive source.

Example:

source: null

redis

Fetch peers from a Redis database.

The keys used in the map format are:

sets_key

required, type: str

Set the key of the set that stores peers. Each string entry in the set represents one peer. See peers for the supported formats.
nested redis config map

For url str values, the format is:

redis://[username][:<password>@]<addr>/<db>?sets_key=<sets_key>

Examples:

source:
  type: redis
  addr: 127.0.0.1:6379
  db: 3
  sets_key: proxy_float:peers

source: redis://127.0.0.1:6379/3?sets_key=proxy_float:peers

Peers

Peers are represented as JSON strings whose root element is a map.

At runtime, a request fails if path selection references a peer ID that does not exist in the current peer set, or if the selected peer has already expired.

Common keys

type

required, type: str

Peer type.

id

optional, type: str

Identifier for this peer.

Added in version 1.7.23.
addr

required, type: sockaddr str

Set the socket address used to connect to the peer. Domain names are not allowed here.
isp

optional, type: str

ISP for the egress IP address.
eip

optional, type: ip addr str

Egress IP address as seen externally.
area

optional, type: egress area

Area associated with the egress IP address.
expire

optional, type: rfc3339 datetime str

Expiration time for this peer.
tcp_sock_speed_limit

optional, type: tcp socket speed limit

Set the speed limit for each TCP connection to this peer.

Example peer

{
  "type": "https",
  "id": "corp-edge-1",
  "addr": "203.0.113.30:3128",
  "tls_name": "proxy.example.net",
  "username": "u1",
  "password": "p1",
  "expire": "2026-03-28T08:00:00Z"
}

Example publish payload

[
  {
    "type": "http",
    "id": "edge-a",
    "addr": "203.0.113.20:3128"
  },
  {
    "type": "socks5",
    "id": "edge-b",
    "addr": "203.0.113.21:1080",
    "udp_sock_speed_limit": {
      "shift_millis": 1000,
      "max_north": "8MiB",
      "max_south": "8MiB"
    }
  }
]

The following types are supported:

http

host_name | tls_name

optional, type: host

Set the server host name for HTTP Upgrade request.

default: not set
username

optional, type: username

Username for HTTP Basic authentication.
password

optional, type: password

Password for HTTP Basic authentication.
http_connect_rsp_header_max_size

optional, type: humanize usize

Set the maximum header size accepted for CONNECT responses.

default: 4KiB
extra_append_headers

optional, type: map

Set extra headers appended to requests sent upstream. Keys are header names. Both keys and values must be ASCII strings.

Note

Duplicate headers are not checked. Use this carefully.

https

HTTPS peers support all HTTP peer keys and have no extra keys currently.

The host_name/tls_name key is also used for TLS certificate verification.

socks5

username

optional, type: username

Username for SOCKS5 username/password authentication.
password

optional, type: password

Password for SOCKS5 username/password authentication.
udp_sock_speed_limit

optional, type: udp socket speed limit

Set the speed limit for each UDP socket.

default: no limit

Added in version 1.7.22.
transmute_udp_peer_ip

optional, type: bool or map

Rewrite the UDP peer IP returned by the remote proxy when needed.

For a map value, each key is the returned IP and each value is the real IP to use. If the map is empty, the peer IP from the TCP connection is used.

For a boolean value, true behaves like an empty map and false disables this feature.

default: false

Added in version 1.7.22.
end_on_control_closed

optional, type: bool

End the UDP ASSOCIATE session whenever the peer closes the control TCP connection.

By default the session will be ended if:
- Any error occurs on the TCP control connection
- The TCP control connection closes cleanly after at least one UDP packet has been received
default: false

Added in version 1.9.9.

socks5s

SOCKS5-over-TLS peers support all SOCKS5 peer keys plus the following:

host_name | tls_name

optional, type: host

Set the server host name for TLS certificate verification.

default: not set

Added in version 1.9.9.