What Is a Proxy Bridge? Protocol Translation Explained

A proxy bridge terminates one proxy protocol on its listening side, extracts the intent of the request (a destination host, a port, sometimes a set of credentials), and re-expresses that same intent in a different proxy protocol toward an upstream. The payload passes through untouched. Only the envelope changes.

Proxy bridge: one protocol in, a different protocol out

[ client ]              [ bridge ]                 [ upstream proxy ]     [ target ]
 speaks    -- SOCKS5 -->  parses the SOCKS5   -- HTTP CONNECT + -->  exit IP -->  :443
 SOCKS5                   request, emits an      Proxy-Authorization
 and nothing else         HTTP CONNECT

 payload bytes are spliced end to end and never inspected

Nothing about the exit IP changes because of the bridge. If the upstream hands you a residential exit in Berlin, you still get a residential exit in Berlin. The bridge only decides which handshake the two sides speak.

Be careful with the word itself. Vendors use "bridge" loosely: in marketing copy it can mean a rotating gateway, a desktop client that binds a local port, a WireGuard-to-proxy adapter, or a genuine protocol converter. The useful question when a vendor says "bridge" is which protocol goes in and which one comes out. If the answer is "the same one," you are looking at a relay or a gateway, not a translator. This article uses the strict definition, because that is the one that predicts behavior.

You need a bridge when the client library and the proxy you bought disagree, and you cannot change either one.

Proxy support in HTTP clients is uneven in three separate ways: which proxy protocols the client speaks, whether it can send credentials at all, and whether it can send them for the specific protocol you need. A client can pass the first test and fail the third.

Two rows on that table are the ones that generate most real bridge deployments.

Chromium's --proxy-server flag has no syntax for a username and password. Put credentials in the URL and Chromium ignores them, then throws an interactive auth dialog at a headless browser that has no one to answer it. The standard fix is a bridge on loopback that accepts unauthenticated connections and injects Proxy-Authorization on the way out.

Java is the other one, and its failure is quieter. Since JDK 8u111 the system property jdk.http.auth.tunneling.disabledSchemes defaults to Basic, which disables Basic authentication for HTTPS tunneled through a proxy. Your Authenticator gets called, the credentials look correct, and the CONNECT still comes back 407. You can clear the property, but on a locked-down runtime a loopback bridge that holds the credential is the faster path.

The last row matters more than people expect. A Postgres or Redis client has no concept of a proxy at all. Bridging a raw TCP listener onto an HTTP CONNECT upstream is the only way to get that traffic through without patching the client.

Almost every real bridge is one of four translations. The mechanics differ in each direction, and so do the things that break.

SOCKS5 in, HTTP out is the most common. SOCKS5 is a byte-stream protocol that knows nothing about HTTP: the client sends a greeting listing auth methods, receives a method selection, then sends a request carrying a command byte, an address type, an address, and a port. The bridge reads that address and port, opens CONNECT host:port HTTP/1.1 to the upstream, waits for 200 Connection established, and then answers the client with a SOCKS5 success reply. From that point it is a byte pipe.

HTTP in, SOCKS out has one subtlety the reverse direction does not. Tunneled requests are easy: a CONNECT maps cleanly onto a SOCKS5 CONNECT command. Plain HTTP requests are not, because an HTTP proxy receives the request in absolute-form (GET http://host/path HTTP/1.1) while an origin server expects origin-form (GET /path HTTP/1.1 with a Host header). SOCKS5 puts the bridge in direct contact with the origin, so the bridge must rewrite the request line. Bridges that forward the absolute-form request untouched work against tolerant servers and fail against strict ones, which produces a maddening intermittent 400.

Plain in, authenticated out is not a protocol translation in the strict sense, but the architecture and the failure surface are identical, so treat it as one. The bridge binds to 127.0.0.1, accepts anything, and is the only thing on the machine holding the credential.

IPv4 in, IPv6 out shows up when a v4-only client, container, or CI runner needs an upstream reachable only over IPv6, or when a library's connection logic mishandles AAAA records. The bridge listens on a v4 loopback address and dials the v6 upstream itself. Check first that the pool actually has IPv6 exits, because plenty do not, and a bridge cannot manufacture an address family the provider never offered.

Every SOCKS5-to-HTTP bridge, in any language, does the same six things in the same order:

1. Read the SOCKS5 greeting and answer with one selected authentication method.
2. Read the SOCKS5 request and pull out the command byte, address type, address, and port.
3. Refuse any command that is not CONNECT, because BIND and UDP ASSOCIATE have no HTTP equivalent.
4. Dial the upstream HTTP proxy and send CONNECT host:port HTTP/1.1 with a Proxy-Authorization header.
5. Read the upstream status line and map it onto a one-byte SOCKS5 reply code for the client.
6. Splice the two sockets and stop looking at the bytes.

That is about forty lines. Here is a complete SOCKS5 listener doing all six, the standard shape for putting a SOCKS-only client on an HTTP-only pool. Message layouts follow RFC 1928.

import asyncio, base64, socket, struct

UPSTREAM = ("gateway.sparkproxy.io", 11000)
AUTH = base64.b64encode(b"sp_user:sp_pass").decode()

async def pipe(reader, writer):
    try:
        while chunk := await reader.read(65536):
            writer.write(chunk)
            await writer.drain()
    finally:
        writer.close()

async def handle(cr, cw):
    # 1. SOCKS5 greeting: VER, NMETHODS, METHODS (RFC 1928)
    _, nmethods = await cr.readexactly(2)
    await cr.readexactly(nmethods)
    cw.write(b"\x05\x00")              # 0x00 = no auth on the loopback leg
    await cw.drain()

    # 2. SOCKS5 request: VER CMD RSV ATYP DST.ADDR DST.PORT
    _, cmd, _, atyp = await cr.readexactly(4)
    if cmd != 0x01:                    # BIND and UDP ASSOCIATE cannot cross to HTTP
        cw.write(b"\x05\x07\x00\x01" + b"\x00" * 6)
        await cw.drain(); cw.close(); return
    if atyp == 0x01:
        host = socket.inet_ntop(socket.AF_INET, await cr.readexactly(4))
    elif atyp == 0x03:
        length = (await cr.readexactly(1))[0]
        host = (await cr.readexactly(length)).decode()
    else:                              # 0x04 = IPv6 literal
        host = "[%s]" % socket.inet_ntop(socket.AF_INET6, await cr.readexactly(16))
    port = struct.unpack("!H", await cr.readexactly(2))[0]

    # 3. Re-emit the same intent as HTTP, attaching the upstream credential
    ur, uw = await asyncio.open_connection(*UPSTREAM)
    uw.write(
        f"CONNECT {host}:{port} HTTP/1.1\r\n"
        f"Host: {host}:{port}\r\n"
        f"Proxy-Authorization: Basic {AUTH}\r\n"
        f"Proxy-Connection: Keep-Alive\r\n\r\n".encode()
    )
    await uw.drain()
    status = await ur.readline()
    while (await ur.readline()) not in (b"\r\n", b""):
        pass                           # drain the upstream response headers

    # 4. Map the HTTP status back onto a SOCKS5 reply code
    ok = status.split()[1] == b"200"
    cw.write(b"\x05" + (b"\x00" if ok else b"\x01") + b"\x00\x01" + b"\x00" * 6)
    await cw.drain()
    if not ok:
        cw.close(); uw.close(); return

    # 5. Byte pipe. TLS is never parsed and never terminated.
    await asyncio.gather(pipe(cr, uw), pipe(ur, cw))

async def main():
    server = await asyncio.start_server(handle, "127.0.0.1", 1080)
    async with server:
        await server.serve_forever()

asyncio.run(main())

Verify it the way you would verify any proxy, with socks5h so the hostname travels to the bridge rather than being resolved locally:

curl -x socks5h://127.0.0.1:1080 -s -o /dev/null \
  -w "%{http_code} %{time_total}s\n" https://example.com

That mapping, step 4 in the code above, is where debugging usually stalls. SOCKS5 has nine reply codes (0x00 succeeded, then 0x01 general failure through 0x08 address type not supported) and HTTP has dozens of status codes, so any mapping is lossy. Most bridges, this one included, collapse everything that is not a 200 into 0x01. The client then reports a generic SOCKS failure whether the real cause was a 407 for bad credentials, a 403 for a blocked target, or a 502 from a dead exit.

Log status at the bridge. That single line turns an opaque failure into the actual upstream response, and it is the whole fix when you own the bridge and can read its logs. When you cannot, because the client runs in CI or on someone else's laptop, spend the reply codes you already have instead of collapsing them all into one:

Six lines replace step 4, and the failure stops being anonymous:

REPLY = {b"200": 0x00, b"407": 0x02, b"403": 0x02,
         b"502": 0x04, b"504": 0x04, b"503": 0x05}
code = REPLY.get(status.split()[1], 0x01)
cw.write(b"\x05" + bytes([code]) + b"\x00\x01" + b"\x00" * 6)
await cw.drain()
if code != 0x00:
    cw.close(); uw.close(); return

What the client does with a better code varies more than you would guess. Tested against a stub SOCKS5 server returning fixed replies: Python requests 2.32.5 with PySocks 1.7.1 raises 0x02: Connection not allowed by ruleset, which sends the ticket straight to billing. curl 8.15.0 prints curl: (97) cannot complete SOCKS5 connection to example.com. (2) and exits 97 for every non-zero code, so the only signal that survives is the bare number in parentheses. The mapping still earns its six lines, but write down what (2) and (4) mean for whoever reads the log at 3am.

Note the guard on cmd. SOCKS5 defines CONNECT (0x01), BIND (0x02), and UDP ASSOCIATE (0x03). HTTP CONNECT has no UDP equivalent, so the last two have no honest translation and must be refused with 0x07. For a fuller treatment of what a CONNECT tunnel is and is not, see what is an HTTP tunnel.

"A bridge is basically free" gets repeated constantly and measured almost never. So here is a measurement you can reproduce in an afternoon.

The rig is three asyncio servers on loopback: an origin, an HTTP proxy that demands Proxy-Authorization, and the bridge from the section above. The client uses blocking sockets, and each iteration opens a connection, completes every handshake on the path, sends one request, and reads the response. 600 iterations per path after a 60-iteration warmup, on CPython 3.14.2, an AMD Ryzen 9 7945HX, Windows Server 2022. Throughput is a separate 64 MiB transfer on one connection.

A second run reproduced the added latency to within 0.03 ms. Three things follow, and the third is the one that bites.

The latency cost is per connection, not per byte. That third of a millisecond buys the SOCKS5 greeting, the SOCKS5 request, and the upstream CONNECT round trip. Once the sockets are spliced, the bridge adds nothing per request. Against a residential exit at 40 ms to 200 ms RTT, 0.31 ms is 0.15% to 0.8% of a request and will never appear in a percentile chart. Against a datacenter exit 5 ms away it is 6%, still invisible next to normal jitter. Keep-alive removes it outright, because a reused connection pays the handshake once and then nothing.

Every userspace splice roughly halves loopback throughput, and it does not matter. 0.71 GiB/s is about 5.8 Gbps through a single-threaded Python relay copying 64 KiB at a time. No proxy egress you rent is within an order of magnitude of that. Worry about the splice only if the bridged traffic never leaves the machine.

Connection rate is the real ceiling. Under 8 concurrent workers opening short-lived connections, the same bridge sustained roughly 1,200 new connections per second, against roughly 2,080 for the HTTP proxy alone. A scraper opening 50 connections a second is fine forever. A scraper opening 3,000 is queued behind an event loop, and no amount of tuning fixes that: run a bridge written for concurrency such as gost, or run several bridge processes sharing a port. Both proxies here ran in one Python process on one event loop, so treat these as floors rather than ceilings.

The shape is what to remember. A bridge costs you a sub-millisecond handshake per connection and a connection-rate ceiling. It does not cost you bandwidth, and it never costs you an exit IP.

There are three separate TLS sessions in the neighborhood of a bridge, and confusing them is how people accidentally destroy their own success rate.

A correct bridge sees exactly two things about the encrypted traffic: the host and port from the CONNECT line or the SOCKS5 request, and whatever bytes it splices. It does not parse the ClientHello. It does not need to.

The moment you terminate the end-to-end session, with a local CA the way mitmproxy does, three things change on the wire and all three are detectable. The ClientHello the target receives is generated by your interception library, not by the client, so the JA3 and JA4 fingerprints no longer match the User-Agent you are sending. ALPN negotiation gets re-run by the interceptor, which frequently downgrades an HTTP/2 client to HTTP/1.1 and creates a second mismatch. And the cipher suite ordering, which is characteristic per client, is replaced wholesale.

The practical rule most explanations of bridging skip: a translation bridge and an inspection proxy are different tools that happen to sit in the same position on the path. Read the traffic and you are now shaping the fingerprint the target sees, so plan for it. Want the client's own TLS characteristics to arrive intact? The bridge stays a byte pipe. See what is TLS fingerprinting for what the target is actually measuring.

One more reason to keep the pipe dumb: any code path that buffers the ClientHello to peek at SNI adds a round trip and breaks on clients sending large hellos with post-quantum key shares. Read the address from the proxy protocol, where it belongs.

HTTP proxy authentication and SOCKS5 authentication are structurally different, and the difference decides where the secret has to live.

HTTP proxy auth is challenge-driven and per-request. The client sends a request, the proxy answers 407 Proxy Authentication Required with a Proxy-Authenticate header, and the client retries with Proxy-Authorization: Basic base64(user:pass). SOCKS5 auth is a sub-negotiation that happens once, before the connection request, using the username and password method from RFC 1929. Each field carries a single-byte length, so both are capped at 255 bytes.

Three consequences follow, and they explain most credential bugs at a bridge.

The bridge must hold the credential itself. A 407 challenge arriving from an HTTP upstream cannot be passed back through a SOCKS5 handshake whose auth phase already completed. There is no message for it. So an HTTP-out bridge stores the username and password and attaches them proactively, as the Python example does, rather than waiting to be challenged.

Proxy-Authorization is hop-by-hop and must be stripped. It authenticates the client to the next proxy, not to the origin. A bridge that copies an incoming Proxy-Authorization header into the request it forwards to the target leaks your proxy credentials to whatever server you are scraping. Consume it, then generate a fresh header for the upstream.

RFC 1929 sends the password in cleartext. There is no hashing and no challenge. A SOCKS5-listening bridge should bind to 127.0.0.1 or a private interface and nothing else. If you need it reachable across a network, put it behind an authenticated tunnel rather than exposing the SOCKS listener.

The 255-byte cap is worth checking if your provider encodes routing options into the username, which most rotating pools do. A username like sp_user-country-de-city-berlin-session-a1b2c3d4-ttl-10m is fine, but generated session tokens plus a long account prefix can approach the limit, and the failure mode is a truncated username that authenticates as a different session rather than an obvious error. Count the bytes before you ship. The mechanics of both schemes are covered in how proxy authentication works.

These four terms get used interchangeably and they describe genuinely different things. This table is the disambiguation.

Read it as three different verbs plus a container. A bridge translates. A gateway distributes. A chain hops. A tunnel is what all three carry traffic inside of.

Precision pays off because the wrong mental model sends you after the wrong fix. If your exit IP is not rotating, adding a bridge changes nothing, since bridges do not touch IP selection. That is a proxy gateway concern. If latency is high because traffic crosses three continents, a bridge is not the cause either: the loopback bridge measured above added 0.31 ms at p50, under half a percent of a transatlantic round trip. That is proxy chaining territory. Bridges fix exactly one class of problem, which is that your client and your proxy do not speak the same language.

The categories nest. A bridge whose upstream is a gateway is the most common deployment of all: your SOCKS-only client talks to a local bridge, and the bridge talks HTTP to a rotating gateway. Two roles, one path. What you should not call it is a chain, because there is only one remote hop and it does all the routing work.

Three tools, from the least code to the most control. All three assume an upstream on gateway.sparkproxy.io with HTTP on port 11000 and SOCKS5 on port 13000. Substitute the host and ports from your own dashboard.

gost v3 is the shortest path for any of the four directions. One command, no config file:

# SOCKS5 in, authenticated HTTP out
gost -L socks5://127.0.0.1:1080 -F http://sp_user:sp_pass@gateway.sparkproxy.io:11000

# HTTP in, authenticated SOCKS5 out
gost -L http://127.0.0.1:8080 -F socks5://sp_user:sp_pass@gateway.sparkproxy.io:13000

# Plain in, authenticated out (the Chromium and Java fix)
gost -L http://127.0.0.1:8080 -F http://sp_user:sp_pass@gateway.sparkproxy.io:11000

# IPv4 loopback in, IPv6 upstream out
gost -L socks5://127.0.0.1:1080 -F "http://sp_user:sp_pass@[2001:db8::5]:10000"

Then point the stubborn client at loopback and let it think it won:

chromium --headless=new --proxy-server="http://127.0.0.1:8080" \
  --dump-dom https://example.com

3proxy is the option when you want the bridge to run as a long-lived service with access control and logging. Its parent directive is where the translation is declared:

# /etc/3proxy/3proxy.cfg
nserver 1.1.1.1
nscache 65536
log /var/log/3proxy/bridge.log D
auth iponly
allow * 127.0.0.1

# Translate to an HTTP upstream. Use "connect" for a CONNECT-capable HTTP proxy,
# which is what you want for arbitrary TCP and for HTTPS. Use "http" only if the
# parent expects absolute-form HTTP requests instead.
parent 1000 connect gateway.sparkproxy.io 11000 sp_user sp_pass

# Listen as SOCKS5, loopback only
socks -p1080 -i127.0.0.1

The connect versus http choice on that parent line is this whole article compressed into one config value. connect tunnels arbitrary TCP through the parent's CONNECT method. http forwards absolute-form HTTP requests to a parent acting as an origin-facing HTTP proxy. Pick http when you needed connect and every HTTPS request dies at the handshake, with no useful error anywhere.

socat covers the case no proxy-aware tool does: a client with no proxy support at all, bridged onto a fixed destination. This is how you get a database driver or a legacy binary through an HTTP proxy.

# Local TCP port 8443 lands on target.sparkproxy.io:443 via HTTP CONNECT
socat TCP-LISTEN:8443,bind=127.0.0.1,fork,reuseaddr \
  PROXY:gateway.sparkproxy.io:target.sparkproxy.io:443,proxyport=11000,proxyauth=sp_user:sp_pass

socat's SOCKS4A: address does the same through a SOCKS4a parent on any 1.7.x build, and native SOCKS5: support landed in socat 1.8.0, so run socat -V before assuming it is there. The limitation is inherent: one listener maps to one destination, because raw TCP carries no target address for the bridge to read. That is precisely why SOCKS5 and CONNECT exist. If you find yourself running twelve socat listeners, you have rebuilt a worse SOCKS proxy and should switch to gost.

These are the ones that do not announce themselves.

socks5:// instead of socks5h://. With socks5://, curl and most libraries resolve the hostname locally and send an ATYP 0x01 IPv4 literal through the bridge. With socks5h://, the hostname travels as ATYP 0x03 and gets resolved at the far end. Two things go wrong when you get this backwards: your local resolver sees every target you touch, and geo-targeting quietly degrades because a CDN returns an edge IP near your machine rather than near your exit. Everything still returns 200, so nothing looks broken. Use socks5h.

A bridge that only handles ATYP 0x01. Naive implementations parse IPv4 literals and nothing else, which works perfectly until a client sends socks5h and passes a hostname. Handle 0x01, 0x03, and 0x04, or reject 0x04 explicitly with reply code 0x08.

UDP does not cross. UDP ASSOCIATE has no HTTP equivalent, so QUIC and HTTP/3, WebRTC media, and plain DNS all fail across a SOCKS-in, HTTP-out bridge. Pin browser clients to HTTP/1.1 or HTTP/2 over TCP rather than debugging why some requests vanish.

A silent 407 masquerading as a SOCKS failure. Log the upstream status line and map non-200 responses onto distinct reply codes, as above. Skip both and an expired invoice, a blocked target, and a dead exit all reach you as the same byte.

Absolute-form leakage in HTTP-in, SOCKS-out bridges. If the bridge does not rewrite GET http://host/path into GET /path plus a Host header before handing it to the origin, tolerant servers accept it and strict ones return 400. The bug looks site-specific, which sends people hunting for anti-bot behavior that is not there.

Assuming the bridge changed your anonymity posture. It did not. Header hygiene, TLS fingerprint, and exit IP reputation are all decided elsewhere. A bridge that adds Via or X-Forwarded-For on the client leg is misconfigured, and some HTTP proxy daemons add those by default, so check.

Most bridges exist to reconcile a mismatch. The other way to resolve a mismatch is to remove it.

The SparkProxy Scraping API takes a single authenticated HTTPS request and handles the exit IP, rotation, rendering, and anti-detection behind it, so the protocol your client speaks stops being a constraint. Any HTTP client works, including the ones with no proxy support at all. Authenticate with the X-API-Key header against https://scrape.sparkproxy.io/api/v1, documented at /docs/scraping-api:

import requests

resp = requests.get(
    "https://scrape.sparkproxy.io/api/v1",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={
        "url": "https://example.com/listing",
        "render_js": "true",
        "premium_proxy": "true",   # residential exit
        "country_code": "DE",      # geo-targeted exit
        "stealth": "true",         # requires render_js=true
    },
    timeout=60,
)
print(resp.status_code, len(resp.text))

If you genuinely need a specific hop under your own control, the API does the protocol translation for you. The own_proxy parameter accepts four formats, one of which is a socks5:// URL, which means the API itself acts as the bridge: your request arrives over HTTPS and leaves through your SOCKS5 proxy, with no local listener to run or supervise.

curl -G "https://scrape.sparkproxy.io/api/v1" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "own_proxy=socks5://sp_user:sp_pass@gateway.sparkproxy.io:13000" \
  --data-urlencode "render_js=true"

One documented constraint applies: a socks5:// value for own_proxy requires render_js=true. Set it, or the request will not take the SOCKS path. own_proxy also accepts ip:port, ip:port:user:pass, and http:// forms, and adds no extra credit cost.

If you would rather keep running your own proxies and only need to decide which protocol to buy in the first place, SOCKS5 vs HTTP proxies compares them on the axes that determine whether you will ever need a bridge at all.