fix(deps): bundle socksio so httpx Client doesn't crash inside fence sandbox

[sohil-kshirsagar]

Adds socksio as a hard dep of tusk-drift-python-sdk so that any Python service constructing httpx.Client(...) at module load time doesn't crash during Tusk Drift replay with ImportError: Using SOCKS proxy, but the 'socksio' package is not installed.

Why

The replay sandbox is built on fence, which runs local SOCKS5 + HTTP proxies and injects these into the sandboxed service's environment so well-behaved HTTP libraries route through it:

ALL_PROXY=socks5h://localhost:1080
HTTP_PROXY=http://localhost:3128
HTTPS_PROXY=http://localhost:3128

httpx evaluates proxy config eagerly inside Client.__init__ — the moment it sees ALL_PROXY=socks5h://..., it tries to import socksio to construct a SOCKS5 transport. If socksio isn't installed, it raises ImportError at construction. So a perfectly normal Python pattern like:

import httpx

_client = httpx.Client(base_url=settings.INTERNAL_BASE_URL, ...)

…blows up at import time during replay (but not in prod, staging, or local dev, because none of those have ALL_PROXY=socks5h://... set). The traceback ends with:

ImportError: Using SOCKS proxy, but the 'socksio' package is not installed.
Make sure to install httpx using `pip install httpx[socks]`.

The WSGI/Flask/Django app never finishes loading, the drift CLI's readiness check fails, and the run errors out with service failed to become ready within 3m0s. From the customer's POV this looks like a bug in their code or our SDK — but the actual cause is an environmental side-effect of fence's proxy mechanism.

Why bundling here

Three options were considered:

Option	Where it lives	Trade-off
httpx.Client(..., trust_env=False) per Client	Customer code	Targeted, but per-Client and won't generalize
Add socksio to customer deps	Customer code	Project-wide, but customer needs to know about the issue first
Bundle socksio in the SDK	This PR	Auto-applies to every Python customer; +100KB unused for customers who don't use httpx + fence together

Bundling is the lowest-friction long-term fix. socksio is ~100KB, pure Python, MIT-licensed, with zero transitive deps — essentially free to ship. It eliminates the failure mode without any customer involvement.

What socksio does at runtime

Effectively nothing visible:

1. Replay (the only place fence engages): httpx.Client(...) reads ALL_PROXY=socks5h://..., imports socksio successfully, builds a SOCKS5 transport, attaches it to the Client's _mounts. The Client constructor returns normally; Flask/WSGI starts. When app code calls client.get(...), the SDK's monkey-patch on httpx.Client.send intercepts above the transport layer and returns a recorded mock — the SOCKS transport never actually serves a request.
2. Recording: fence isn't engaged, no proxy env vars set, socksio is dormant.
3. Customer prod / staging / local dev: same as recording.

The only behavior change is "Client constructor doesn't crash when the env happens to have a SOCKS proxy URL set."

Why only socksio and not also PySocks / aiohttp-socks

Considered bundling broader SOCKS support for requests / urllib3 / aiohttp, but:

• httpx is unique in that it eagerly evaluates proxy config inside Client.__init__. The SOCKS-related import fires at construction, before any monkey-patch can intercept.
• requests, urllib3, and aiohttp all evaluate proxy config lazily on .send() / .request(). The SDK's monkey-patches on Session.send / PoolManager.urlopen / ClientSession.send sit above proxy resolution, so a missing PySocks / aiohttp-socks would only matter for un-intercepted traffic — which generally indicates a bigger problem (replay isn't being mocked) and isn't worth a default dep.

Will document a per-case workaround (pip install requests[socks], etc.) if a request-time SOCKS failure ever shows up.

Risk / blast radius

• Pip install size: +~100KB.
• Lockfile churn: customers using uv / poetry / pip-tools see a new transitive package on next lock. socksio is stable on 1.x since 2020, pure Python, no transitive deps.
• Runtime behavior: only changes if ALL_PROXY / HTTPS_PROXY / HTTP_PROXY is set with a SOCKS scheme AND the process constructs an httpx Client. In every other case socksio is unused.
• License: socksio is MIT, compatible with the SDK's Apache-2.0 license.
• Python version support: socksio supports Python 3.6+, no compatibility floor change.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 5ead518. Configure here.}

[tusk-dev]

Tip

New to Tusk? Learn more here.

Code Review

Tusk Review: No issues found

---

Unit Tests

PR identified as a dependency upgrade

_{Last run on 0b50cf7. Comment @use-tusk generate to create a test suite on the latest commit. Configure here.}

View check history

Commit	Unit Tests	Created (UTC)
5ead518	PR identified as a dependency upgrade · Output	May 8, 2026 12:31AM
0b50cf7	PR identified as a dependency upgrade · Output	May 8, 2026 12:42AM