1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
//! A thin client for driving the [Chromeleon](https://chromeleon.dev) 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:
//!
//! ```text
//! 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](https://docs.rs/chromiumoxide), with `headless_chrome`, and
//! with a raw DevTools WebSocket.
//!
//! # Launch, then attach
//!
//! ```no_run
//! use chromeleon::launch::Launcher;
//!
//! let mut browser = Launcher::new("/opt/chromeleon/chrome")
//! .remote_debugging_port(9222)
//! .spawn()?; // WebRTC policy merged in, controller PROXY_* stripped
//! # let _ = browser.kill();
//! # Ok::<(), std::io::Error>(())
//! ```
//!
//! # The handshake
//!
//! With any async CDP connection, in one call:
//!
//! ```no_run
//! use chromeleon::adapters::new_proxy_context_raw;
//! # use chromeleon::Error;
//! # struct Cdp;
//! # impl Cdp { async fn call(&self, _m: &str, _p: serde_json::Value) -> Result<serde_json::Value, Error> { Ok(serde_json::json!({})) } }
//! # async fn demo(cdp: &Cdp, ws_url: &str) -> Result<(), Error> {
//! 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();
//! # let _ = context_id;
//! # Ok(())
//! # }
//! ```
//!
//! …or step by step, when your driver creates contexts its own way:
//!
//! ```no_run
//! use chromeleon::{check_registration, registration::proxy_registration, CREDENTIALS_METHOD};
//! # use chromeleon::Error;
//! # struct Browser;
//! # impl Browser {
//! # async fn send(&self, _m: &str, _p: serde_json::Value) -> Result<serde_json::Value, Error> { Ok(serde_json::json!({})) }
//! # async fn new_context(&self, _server: &str) -> Result<String, Error> { Ok(String::new()) }
//! # }
//! # async fn demo(browser: &Browser, ws_url: &str) -> Result<(), Error> {
//! 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);
//! # let _ = context;
//! # Ok(())
//! # }
//! ```
//!
//! # Captcha solving
//!
//! Launch with [`Launcher::captcha(true)`](launch::Launcher::captcha) 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.
//!
//! ```no_run
//! # use std::time::Duration;
//! # use serde_json::Value;
//! # use chromeleon::settle::{PageSession, SettleWatch, WaitOptions};
//! # struct Session;
//! # impl PageSession for Session {
//! # type Error = chromeleon::Error;
//! # async fn send(&self, _m: &'static str, _p: Value) -> Result<Value, Self::Error> { unimplemented!() }
//! # async fn next_event(&self, _t: Duration) -> Option<(String, Value)> { None }
//! # }
//! # async fn demo(session: Session) -> Result<(), chromeleon::Error> {
//! 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;
//! # Ok(()) }
//! ```
//!
//! # What this crate is held to
//!
//! `HANDSHAKE.md` in the [clients
//! repository](https://github.com/TrueCrawl/chromeleon-clients) is the spec all
//! three clients (Python, Node, Rust) implement, and a shared conformance
//! corpus pins them to the same parsing and normalization behaviour.
// Feature badges on docs.rs, which builds with nightly and passes --cfg docsrs.
pub use crate;
pub use crate;
pub use crate;
pub use crate;
pub use crate;
pub use crate;
pub use crate;
/// The `HANDSHAKE.md` spec version this client implements.
///
/// The handshake is versioned separately from the crate: when it changes, every
/// client's **major** moves together. A client whose `SPEC_VERSION` is behind
/// the browser's is a client that will fail quietly, not loudly.
pub const SPEC_VERSION: u32 = 1;