chromeleon (Rust)
A thin, driver-agnostic Rust client for Chromeleon's per-context proxy
handshake. No browser library is a dependency: it works with
chromiumoxide, with headless_chrome, and with
a raw DevTools WebSocket, in async or blocking code.
See HANDSHAKE.md
for the protocol this implements.
Install
[]
= "0.1"
# optional: the chromiumoxide adapter (needs rustc >= 1.85, chromiumoxide's own floor)
= { = "0.1", = ["chromiumoxide"] }
MSRV 1.75, and CI builds and tests on exactly that toolchain — but read the
caveat, because it is about your dependency resolution, not our code. Newer
releases in this tree require 1.85 (async-lock 3.4.2 declares it; url 2.5.4+
reaches idna_adapter, which is edition 2024 and will not even parse on an old
cargo), and a plain cargo build takes the newest. On 1.75 you therefore need
one of: the Cargo.lock committed here, [resolver] incompatible-rust-versions = "fallback" (cargo ≥ 1.84, so not the cargo that
ships with 1.75), or your own cargo update --precise pins. On any recent
toolchain none of this applies.
Launch, then attach
Rust drives browsers by spawning them and attaching over CDP, so that is the
shape of the launch helper. It merges the WebRTC policy flag a per-context proxy
needs and strips the controller's PROXY_* variables from the browser's
environment — the two things your driver has no way to know about.
use Launcher;
let = new
.remote_debugging_port
.arg
.fingerprint_os // ⚠️ see below — the default is Windows
.captcha // the built-in solver, on
.spawn_and_wait?; // returns the DevTools WebSocket URL
Two things that bite:
- Never pass proxy credentials at launch. The binary fails closed on an
unresolved exit IP, because that would unbind the persona's geo and disable
WebRTC masking. Per-context proxies are launched with no
--proxy-server. - The persona OS defaults to Windows. It is read from the browser's command
line when a context is created, so a launcher that never sets
--fingerprint-osships Windows personas from a Linux host, silently.Launcher::fingerprint_osis the switch.
The handshake
One call, for any async CDP connection:
use new_proxy_context_raw;
let created = new_proxy_context_raw.await?;
let context_id = created.as_str.unwrap;
…or step by step, when your driver creates contexts its own way:
use ;
let reg = proxy_registration.await?;
check_registration?;
let context = browser.create_context.await?; // same bytes, still under the guard
drop; // released only after the create
The guard is the API's whole point: the registration is single-use — consumed by
the create, and consumed even when that create then fails — so Registration is held
across both commands and serializes anything else that wants the same
(connection, server). Different servers on one connection run concurrently,
which is the throughput case:
let = join!;
Synchronous drivers use the same lock through
new_proxy_context_raw_blocking / proxy_registration_blocking.
chromiumoxide
use new_proxy_context;
let = connect.await?; // from Launcher, above
spawn;
let context = new_proxy_context.await?;
let mut target = new;
target.browser_context_id = Some;
let page = browser.new_page.await?;
Target.setProxyCredentials is not in chromiumoxide's generated protocol and it
has no untyped send; oxide::RawCommand is the escape hatch, and
oxide::send_raw / send_raw_page expose it. oxide::browser_config curates
chromiumoxide's own default flags (it adds --enable-automation and
--lang=en_US, neither of which belongs on this browser) — but note it cannot
strip the controller's PROXY_*, because BrowserConfig only adds
environment variables. That is why the example above launches with Launcher
and attaches. Full example: examples/chromiumoxide_proxy_context.rs.
Captcha solving
Launch with .captcha(true) and the built-in reCAPTCHA/hCaptcha solver handles
challenges by itself — you do not call it, and the release binary embeds the
models. The Chromeleon CDP domain only reports the lifecycle: enable it on a
page session and parse the events.
use ;
page_session.send.await?;
while let Some = events.next.await
solver_eval_params(expression, frame_url_contains) runs JS in the solver's
isolated world, which pierces closed shadow roots; its string result arrives
on the SOLVER_EVAL_RESULT event, not as the command's return value.
Three things the other clients get wrong or leave out, checked against the browser source:
methodisaudio(reCAPTCHA),checkbox(hCaptcha/Turnstile),slider(DataDome) orpress-hold(PerimeterX). There is no image mode — image grids and reCAPTCHA v3 are out of scope for the solver.sitekeycarries the embedder host, not a sitekey, for the hCaptcha-checkbox, DataDome and PerimeterX solvers.- The domain exists only when the browser was launched with
--captcha-solver; otherwiseChromeleon.enableis an unknown method. And its events are broadcast to every enabled session in the process, so asolverEvalresult cannot be correlated to the call that produced it.
API
Launcher |
the browser process: flags merged, PROXY_* stripped |
proxy_registration(conn, proxy) -> Registration |
hold the slot (also _blocking) |
with_proxy_registration(conn, proxy, body) |
the same, closure-shaped |
new_proxy_context_raw(conn, proxy, send) |
both commands over one send |
new_proxy_context_with(conn, proxy, send, create) |
when the driver owns context creation |
ProxySpec |
a parsed proxy; its server is always normalized |
normalize_server, parse_proxy, check_registration |
the pieces, if you want them |
captcha::* |
solver switches, CDP methods, typed events |
perf::sticky_geo_env, perf::BrowserPool |
launch-latency helpers |
oxide::* (feature) |
chromiumoxide adapter: contexts, raw commands, typed events |
proxy is anything IntoProxySpec accepts: a URL string
(http://user:pass@host:port), a ProxySpec, or a (server, username, password) tuple. URL credentials are percent-decoded; credentials you pass
separately are literal.
What this crate refuses to do
Each of these was a silent failure in a real session, which is why it is an error here and not a best effort:
- An unnormalized server.
ProxySpeccan only be built through a constructor that normalizes, so the string you register and the string the context is created with cannot drift apart. - A guessed host. An empty server, a bad port, or a forbidden character in
the host is an error. A driver's own fallback quietly turns
http://host:notaportinto the hosthttp, and the browser then proxies nowhere you meant. - A guessed credential. A URL credential whose escapes decode to non-UTF-8
bytes is
Error::UndecodableCredential, not a replacement character — authenticating with a secret that is nearly yours fails at the proxy, not here, and looks like a network problem. - Dropping credentials. If you pass a server that embeds
user:pass@and no separate credentials, they are taken from the URL rather than discarded.
Parity with the Python and Node clients
All three implement HANDSHAKE.md, and ../conformance/vectors.json holds 94
proxy inputs with the answer every client must give. This client passes all 91
that its types can express (the other three are dynamic-typing cases — a null
server, a non-string credential — that cannot be constructed here).
Twenty of those cases are ones where the Python and Node clients disagree
with each other. The corpus records who was right and why; this client follows
the ruling, so it deliberately differs from each of the older clients on some
inputs. The observed field of each case is the losing behaviour, kept visible
rather than flattened.
Version-dependent behaviour
Up to v151.4 (the binary published as latest) the browser rejects a second
registration for a (connection, server) while one is pending. From v151.5 it
queues, and accepts a credentialsId correlation token —
CredentialsParams::with_credentials_id, oxide::new_proxy_context_with_id,
opt-in because an older binary does not know the field. This client always takes
the lock either way: it cannot know which binary it is talking to, and the lock
costs nothing against a browser that would have queued.
Test
No browser is needed for any of it.