Documentation

Forward-proxy control headers.

Using the forward proxy

This listener also acts as a forward proxy. Point a client's HTTP proxy at it and send CONNECT host:port; it picks a healthy upstream proxy from the database, tunnels to the target through it, and splices the bytes both ways. Only CONNECT (HTTPS tunnelling) is handled.

Selection is filtered by the P-* headers below. Among the matches, one of the top-scoring proxies is chosen at random, with failover to the rest.

With curl these ride the CONNECT line, so they must be sent with --proxy-header, not -H — a plain -H header travels inside the TLS tunnel to the target and the proxy never sees it.

Control headers

Header Effect
P-Min-Score: 90 Only proxies whose latest score is ≥ 90.
P-Max-Score: 99 Only proxies whose latest score is ≤ 99.
P-Country: US Only proxies in this country (ISO code).
P-Protocol: socks5 Only this upstream protocol (http / https / socks5).
P-Proxy-Id: 42 Use exactly this proxy (bypasses the filters).
P-Proxy-Ids: 1,2,3 Restrict the pool to this id allowlist (bypasses the filters).
P-Session: abc Pin the chosen proxy to this session key for reuse (see below).
P-Session-Duration: 3600 Session pin lifetime in seconds (default 3600; set on first use).

Session pinning

The first request carrying a P-Session key records the proxy it selected and reuses it for subsequent requests with the same key, for a fixed window from first use. If the pinned proxy is gone or disabled by the time it's reused, a replacement is selected and pinned for the remainder of the window. Pins are in-memory (dropped on restart).

Error responses

  • 400 — malformed header.
  • 503 — no proxy matches the criteria.
  • 502 — every candidate failed to connect.

Examples

# Tunnel through any eligible proxy (prints the exit IP):
curl -x http://127.0.0.1:8080 https://api.ipify.org

# Require a score of at least 50, in the US (-v shows the CONNECT exchange):
curl -v -x http://127.0.0.1:8080 \
     --proxy-header 'P-Min-Score: 50' --proxy-header 'P-Country: US' \
     https://api.ipify.org

# Pin a session so repeated calls reuse the same exit:
curl -x http://127.0.0.1:8080 --proxy-header 'P-Session: abc' https://api.ipify.org