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
//! 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`].
//!
//! # 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;
/// 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;