Skip to main content

Crate chromeleon

Crate chromeleon 

Source
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 Chromeleon CDP 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.
oxidechromiumoxide
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’s networkAlmostIdle as the fallback.

Structs§

BlockingSettleWatch
Blocking twin of SettleWatch, for synchronous drivers.
BrowserPool
Round-robin pool of warm connections to already-running CDP endpoints.
ConnKey
Identity of one CDP connection, for locking only.
CreateContextParams
Params for Target.createBrowserContext.
CredentialsParams
Params for Target.setProxyCredentials.
GeoResolution
A resolved proxy exit.
Launcher
A std::process::Command for Chromeleon, with the flags and environment a per-context proxy needs.
LifecycleTracker
The fallback’s bookkeeping, with no transport in it.
ProxySpec
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).
SettleState
The result of a wait.
SettleTuning
The optional --page-settle-* tuning switches.
SettleWatch
A page-completion watch: armed before the navigation, waited on after.
WaitOptions
Per-wait tuning, and the client-side bound.

Enums§

CaptchaEvent
A parsed Chromeleon domain event.
Error
Everything that can go wrong before a byte reaches the browser.
ProxyRotation
Whether the proxy’s exit is stable for the session.
SettleOutcome
What the browser (or the fallback) concluded.
SettleVia
Which signal actually produced the answer.
SolveMethod
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_METHOD call. Payload: {result}.
SPEC_VERSION
The HANDSHAKE.md spec 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§

BlockingPageSession
PageSession for a synchronous driver.
IntoProxySpec
Anything that can be read as a proxy: a URL string, a ProxySpec, or a (server, username, password) tuple.
PageSession
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_ARGS merged into args, 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 as headless_chrome.
normalize_server
Canonicalise a proxy server the way a WHATWG URL parser will.
parse_proxy
Parse anything IntoProxySpec accepts.
proxy_registration
Take the registration slot for proxy on conn from 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 body holding the registration slot, and release it after.
with_proxy_registration_blocking
Blocking form of with_proxy_registration.

Type Aliases§

Result
Result of anything in this crate that can only fail the ways Error does.