Expand description
A thin client for driving the Chromeleon browser.
Chromeleon attaches an authenticated proxy per browser context with two browser-level CDP commands that must be issued in order, on one connection, with a byte-identical server string, and serialized against each other:
Target.setProxyCredentials {proxyServer, username, password}
Target.createBrowserContext {proxyServer}No driver has an API shaped like that, and the ways of getting it wrong are quiet: credentials passed at launch leave the exit IP unresolved, which unbinds the persona’s geo and disables WebRTC masking; credentials left percent-encoded authenticate with the wrong secret; a server string the driver re-normalizes no longer matches the one you registered, so the registration is never consumed and the context browses direct. This crate exists so none of that is the caller’s problem.
It is driver-agnostic: no browser library is a dependency, and the
handshake is expressed as “send this, then create the context with this
string, while holding this guard”. That works with
chromiumoxide, with headless_chrome, and
with a raw DevTools WebSocket.
§Launch, then attach
use chromeleon::launch::Launcher;
let mut browser = Launcher::new("/opt/chromeleon/chrome")
.remote_debugging_port(9222)
.spawn()?; // WebRTC policy merged in, controller PROXY_* stripped§The handshake
With any async CDP connection, in one call:
use chromeleon::adapters::new_proxy_context_raw;
let created = new_proxy_context_raw(
ws_url, // identifies the connection
"http://user:pass@gateway:12321", // credentials are decoded for you
|method, params| cdp.call(method, params),
).await?;
let context_id = created["browserContextId"].as_str().unwrap_or_default();…or step by step, when your driver creates contexts its own way:
use chromeleon::{check_registration, registration::proxy_registration, CREDENTIALS_METHOD};
let reg = proxy_registration(ws_url, "http://user:pass@gateway:12321").await?;
check_registration(&browser.send(CREDENTIALS_METHOD, reg.credentials_params().to_value()).await?)?;
let context = browser.new_context(reg.server()).await?; // same bytes, still under the guard
drop(reg);§Captcha solving
Launch with Launcher::captcha(true) and the
built-in solver handles reCAPTCHA/hCaptcha by itself. The captcha module
is only for watching it: enable the Chromeleon domain on a page session and
parse the lifecycle events with CaptchaEvent::parse.
§Page completion
“The page has finished” is settle: Chromeleon.waitForSettle settles on
the main frame’s rendered TEXT going quiet, with no JavaScript in the page,
and Blink’s networkAlmostIdle is the fallback for a browser launched
without --page-settle. Arm the watch BEFORE the navigation — a session
attached to an already-committed document cannot see the challenge header,
and degrades to status-code-only detection without saying so.
let mut watch = SettleWatch::arm(session).await?; // before the goto
// …navigate…
let state = watch.wait(WaitOptions::new().timeout_ms(30_000)).await?;
if state.blocked() { /* a bot wall, not a page */ }
watch.close().await;§What this crate is held to
HANDSHAKE.md in the clients
repository is the spec all
three clients (Python, Node, Rust) implement, and a shared conformance
corpus pins them to the same parsing and normalization behaviour.
Modules§
- adapters
- Driver adapters over the transport-agnostic core.
- captcha
- The built-in captcha solver, and the
ChromeleonCDP domain that observes it. - core
- The per-context proxy handshake, and nothing else.
- launch
- Launching the binary: the flags and the environment Chromeleon needs and a driver cannot know about.
- oxide
chromiumoxide - chromiumoxide adapter.
- perf
- Launch-latency helpers: pre-supply proxy geo, and pool warm connections.
- registration
- The lock the single-use registration requires.
- settle
- Page completion:
Chromeleon.waitForSettle, with Blink’snetworkAlmostIdleas the fallback.
Structs§
- Blocking
Settle Watch - Blocking twin of
SettleWatch, for synchronous drivers. - Browser
Pool - Round-robin pool of warm connections to already-running CDP endpoints.
- ConnKey
- Identity of one CDP connection, for locking only.
- Create
Context Params - Params for
Target.createBrowserContext. - Credentials
Params - Params for
Target.setProxyCredentials. - GeoResolution
- A resolved proxy exit.
- Launcher
- A
std::process::Commandfor Chromeleon, with the flags and environment a per-context proxy needs. - Lifecycle
Tracker - The fallback’s bookkeeping, with no transport in it.
- Proxy
Spec - A proxy split into the parts each command is allowed to see.
- Registration
- A held registration slot: the credentials may be registered and the context created while this is alive, and not after it is dropped.
- Registry
- The set of registration slots, one per
(connection, proxyServer). - Settle
State - The result of a wait.
- Settle
Tuning - The optional
--page-settle-*tuning switches. - Settle
Watch - A page-completion watch: armed before the navigation, waited on after.
- Wait
Options - Per-wait tuning, and the client-side bound.
Enums§
- Captcha
Event - A parsed
Chromeleondomain event. - Error
- Everything that can go wrong before a byte reaches the browser.
- Proxy
Rotation - Whether the proxy’s exit is stable for the session.
- Settle
Outcome - What the browser (or the fallback) concluded.
- Settle
Via - Which signal actually produced the answer.
- Solve
Method - Which challenge the solver is working, one per solver family.
Constants§
- CAPTCHA_
DETECTED - A challenge was found on the page. Payload:
{sitekey}. - CAPTCHA_
EVENTS - The four lifecycle events: detected → solving → solved | failed.
- CAPTCHA_
FAILED - A solve gave up. Payload:
{sitekey, attempts, reason}. - CAPTCHA_
SOLVED - A solve succeeded and the token was written. Payload:
{sitekey, attempts, timeMs}. - CAPTCHA_
SOLVER_ SWITCH - Launch switch that turns the solver on.
- CAPTCHA_
SOLVING - A solve started. Payload:
{sitekey, method}. - CREATE_
CONTEXT_ METHOD - The command the registration is consumed by.
- CREDENTIALS_
METHOD - The registration command. Paired with
ProxySpec::credentials_params. - DISABLE_
METHOD - Stop lifecycle notifications on a page CDP session.
- ENABLE_
METHOD - Start lifecycle notifications on a page CDP session.
- LAUNCH_
ARGS - Launch flags a per-context proxy needs.
- NETWORK_
ALMOST_ IDLE - Blink’s “at most 2 in-flight requests, sustained 500ms”.
- PAGE_
SETTLE_ SWITCH - Launch switch that registers the settle domain.
- SOLVER_
EVAL_ METHOD - Evaluate JS in the solver’s isolated world. See
solver_eval_params. - SOLVER_
EVAL_ RESULT - The result of a
SOLVER_EVAL_METHODcall. Payload:{result}. - SPEC_
VERSION - The
HANDSHAKE.mdspec version this client implements. - SUPPRESSED_
DEFAULT_ ARGS - Driver default switches worth not adding.
- WAIT_
FOR_ SETTLE_ METHOD - The command. Registered only under
PAGE_SETTLE_SWITCH.
Traits§
- Blocking
Page Session PageSessionfor a synchronous driver.- Into
Proxy Spec - Anything that can be read as a proxy: a URL string, a
ProxySpec, or a(server, username, password)tuple. - Page
Session - One CDP page session, as a settle watch needs to see it.
Functions§
- browser_
process_ env - The process environment with the controller’s proxy variables removed.
- captcha_
launch_ args - Launch flags that turn on the built-in captcha solver.
- check_
registration - Raise if the browser refused the registration.
- launch_
args LAUNCH_ARGSmerged intoargs, plus the captcha switches when asked.- new_
proxy_ context_ raw - The same handshake for a connection that only speaks raw CDP.
- new_
proxy_ context_ raw_ blocking - Blocking form of
new_proxy_context_raw. - new_
proxy_ context_ with - Run the two-command handshake with a driver that owns context creation.
- new_
proxy_ context_ with_ blocking - Blocking form of
new_proxy_context_with, for synchronous drivers such asheadless_chrome. - normalize_
server - Canonicalise a proxy server the way a WHATWG URL parser will.
- parse_
proxy - Parse anything
IntoProxySpecaccepts. - proxy_
registration - Take the registration slot for
proxyonconnfrom the global registry. - proxy_
registration_ blocking - Blocking form of
proxy_registration, for synchronous drivers. - settle_
launch_ args - Launch flags that register the settle domain.
- solver_
eval_ params - Params for
Chromeleon.solverEval. - sticky_
geo_ env - Environment variables that let the browser skip its own geo round trip.
- with_
proxy_ registration - Run
bodyholding the registration slot, and release it after. - with_
proxy_ registration_ blocking - Blocking form of
with_proxy_registration.