browser_commander/browser/
node_bridge.rs

1//! Node.js CLI bridge for Playwright and Puppeteer engines.
2//!
3//! Rust does not have official Playwright or Puppeteer bindings. This adapter
4//! keeps those engine names available by delegating browser operations to the
5//! official Node.js packages over a line-delimited JSON protocol.
6
7use std::path::{Path, PathBuf};
8use std::process::Stdio;
9use std::sync::Arc;
10
11use async_trait::async_trait;
12use base64::Engine as _;
13use serde::Deserialize;
14use serde_json::{json, Value};
15use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
16use tokio::process::{Child, ChildStdin, ChildStdout, Command};
17use tokio::sync::Mutex;
18use tokio::task::JoinHandle;
19
20use crate::browser::connector::ConnectOptions;
21use crate::browser::launcher::LaunchOptions;
22use crate::core::engine::{ElementInfo, EngineAdapter, EngineError, EngineType, PdfOptions};
23
24const BRIDGE_SCRIPT: &str = include_str!("node_engine_bridge.js");
25
26/// [`EngineAdapter`] backed by a Node.js Playwright or Puppeteer subprocess.
27pub struct NodeBridgePage {
28    engine: EngineType,
29    inner: Arc<Mutex<NodeBridgeProcess>>,
30    stderr_task: Arc<Mutex<Option<JoinHandle<()>>>>,
31}
32
33struct NodeBridgeProcess {
34    child: Child,
35    stdin: ChildStdin,
36    stdout: BufReader<ChildStdout>,
37    next_id: u64,
38}
39
40#[derive(Debug, Deserialize)]
41struct BridgeResponse {
42    id: u64,
43    ok: bool,
44    #[serde(default)]
45    result: Value,
46    #[serde(default)]
47    error: Option<String>,
48}
49
50impl NodeBridgePage {
51    pub(crate) async fn launch(
52        options: LaunchOptions,
53        user_data_dir: PathBuf,
54    ) -> Result<Self, anyhow::Error> {
55        let page = Self::start(
56            options.engine,
57            options.node_executable.as_deref(),
58            options.node_working_dir.as_deref(),
59        )
60        .await?;
61
62        page.request("launch", launch_params(&options, &user_data_dir))
63            .await
64            .map_err(|err| anyhow::anyhow!("{}", err))?;
65
66        Ok(page)
67    }
68
69    pub(crate) async fn connect(options: ConnectOptions) -> Result<Self, anyhow::Error> {
70        let page = Self::start(
71            options.engine,
72            options.node_executable.as_deref(),
73            options.node_working_dir.as_deref(),
74        )
75        .await?;
76
77        page.request("connect", connect_params(&options))
78            .await
79            .map_err(|err| anyhow::anyhow!("{}", err))?;
80
81        Ok(page)
82    }
83
84    async fn start(
85        engine: EngineType,
86        node_executable: Option<&Path>,
87        node_working_dir: Option<&Path>,
88    ) -> Result<Self, anyhow::Error> {
89        if !matches!(engine, EngineType::Playwright | EngineType::Puppeteer) {
90            return Err(anyhow::anyhow!(
91                "Node bridge only supports playwright and puppeteer engines"
92            ));
93        }
94
95        let node = node_executable
96            .map(Path::to_path_buf)
97            .unwrap_or_else(|| PathBuf::from("node"));
98        let mut command = Command::new(node);
99        command
100            .arg("--input-type=module")
101            .arg("-e")
102            .arg(BRIDGE_SCRIPT)
103            .stdin(Stdio::piped())
104            .stdout(Stdio::piped())
105            .stderr(Stdio::piped());
106
107        if let Some(working_dir) = node_working_dir {
108            command.current_dir(working_dir);
109        }
110
111        let mut child = command
112            .spawn()
113            .map_err(|err| anyhow::anyhow!("failed to start Node.js bridge: {}", err))?;
114
115        let stdin = child
116            .stdin
117            .take()
118            .ok_or_else(|| anyhow::anyhow!("Node.js bridge stdin was not captured"))?;
119        let stdout = child
120            .stdout
121            .take()
122            .ok_or_else(|| anyhow::anyhow!("Node.js bridge stdout was not captured"))?;
123        let stderr = child.stderr.take();
124
125        let stderr_task = stderr.map(|stderr| {
126            tokio::spawn(async move {
127                let mut lines = BufReader::new(stderr).lines();
128                while let Ok(Some(line)) = lines.next_line().await {
129                    tracing::debug!(target: "browser_commander::node_bridge", "{line}");
130                }
131            })
132        });
133
134        Ok(Self {
135            engine,
136            inner: Arc::new(Mutex::new(NodeBridgeProcess {
137                child,
138                stdin,
139                stdout: BufReader::new(stdout),
140                next_id: 0,
141            })),
142            stderr_task: Arc::new(Mutex::new(stderr_task)),
143        })
144    }
145
146    /// Close the browser subprocess. Dropping the adapter also terminates it.
147    pub async fn close(&self) -> Result<(), EngineError> {
148        let close_result = self.request("close", json!({})).await;
149        let mut inner = self.inner.lock().await;
150        let _ = inner.child.start_kill();
151        if let Some(task) = self.stderr_task.lock().await.take() {
152            task.abort();
153        }
154        close_result.map(|_| ())
155    }
156
157    async fn request(&self, method: &str, params: Value) -> Result<Value, EngineError> {
158        let mut inner = self.inner.lock().await;
159        inner.next_id = inner.next_id.saturating_add(1);
160        let id = inner.next_id;
161        let request = json!({
162            "id": id,
163            "method": method,
164            "params": params,
165        });
166
167        let mut encoded = serde_json::to_vec(&request).map_err(|err| {
168            EngineError::Browser(format!("bridge request encoding failed: {err}"))
169        })?;
170        encoded.push(b'\n');
171
172        inner
173            .stdin
174            .write_all(&encoded)
175            .await
176            .map_err(|err| EngineError::Browser(format!("bridge write failed: {err}")))?;
177        inner
178            .stdin
179            .flush()
180            .await
181            .map_err(|err| EngineError::Browser(format!("bridge flush failed: {err}")))?;
182
183        let mut line = String::new();
184        loop {
185            line.clear();
186            let bytes = inner
187                .stdout
188                .read_line(&mut line)
189                .await
190                .map_err(|err| EngineError::Browser(format!("bridge read failed: {err}")))?;
191            if bytes == 0 {
192                return Err(EngineError::Browser(
193                    "Node.js bridge exited before responding".to_string(),
194                ));
195            }
196
197            let response: BridgeResponse =
198                serde_json::from_str(line.trim_end()).map_err(|err| {
199                    EngineError::Browser(format!(
200                        "bridge returned invalid JSON: {err}; line={}",
201                        line.trim_end()
202                    ))
203                })?;
204
205            if response.id != id {
206                tracing::debug!(
207                    expected_id = id,
208                    actual_id = response.id,
209                    "ignoring out-of-order bridge response"
210                );
211                continue;
212            }
213
214            if response.ok {
215                return Ok(response.result);
216            }
217
218            return Err(EngineError::Browser(
219                response
220                    .error
221                    .unwrap_or_else(|| "Node.js bridge command failed".to_string()),
222            ));
223        }
224    }
225
226    async fn string_request(&self, method: &str, params: Value) -> Result<String, EngineError> {
227        let value = self.request(method, params).await?;
228        Ok(value.as_str().unwrap_or_default().to_string())
229    }
230
231    async fn bool_request(&self, method: &str, params: Value) -> Result<bool, EngineError> {
232        let value = self.request(method, params).await?;
233        Ok(value.as_bool().unwrap_or(false))
234    }
235}
236
237fn launch_params(options: &LaunchOptions, user_data_dir: &Path) -> Value {
238    json!({
239        "engine": options.engine.to_string(),
240        "userDataDir": path_to_string(user_data_dir),
241        "headless": options.headless,
242        "slowMo": options.slow_mo,
243        "verbose": options.verbose,
244        "args": options.all_chrome_args(),
245        "colorScheme": options.color_scheme.as_ref().map(|cs| cs.as_str()),
246        "sandbox": options.sandbox,
247        "channel": options.channel,
248        "executablePath": options.executable_path.as_deref().map(path_to_string),
249    })
250}
251
252fn connect_params(options: &ConnectOptions) -> Value {
253    json!({
254        "engine": options.engine.to_string(),
255        "cdpEndpoint": options.cdp_endpoint,
256        "wsEndpoint": options.ws_endpoint,
257        "slowMo": options.slow_mo,
258        "timeout": duration_millis(options.timeout),
259        "protocolTimeout": duration_millis(options.protocol_timeout),
260        "seedCookies": options.seed_cookies,
261        "verbose": options.verbose,
262    })
263}
264
265fn duration_millis(duration: Option<std::time::Duration>) -> Option<u64> {
266    duration.map(|value| value.as_millis().min(u64::MAX as u128) as u64)
267}
268
269impl std::fmt::Debug for NodeBridgePage {
270    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
271        f.debug_struct("NodeBridgePage")
272            .field("engine", &self.engine)
273            .finish()
274    }
275}
276
277impl Drop for NodeBridgePage {
278    fn drop(&mut self) {
279        if let Ok(mut inner) = self.inner.try_lock() {
280            let _ = inner.child.start_kill();
281        }
282        if let Ok(mut task) = self.stderr_task.try_lock() {
283            if let Some(handle) = task.take() {
284                handle.abort();
285            }
286        }
287    }
288}
289
290#[async_trait]
291impl EngineAdapter for NodeBridgePage {
292    fn engine_type(&self) -> EngineType {
293        self.engine
294    }
295
296    async fn url(&self) -> Result<String, EngineError> {
297        self.string_request("url", json!({})).await
298    }
299
300    async fn goto(&self, url: &str) -> Result<(), EngineError> {
301        self.request("goto", json!({ "url": url })).await?;
302        Ok(())
303    }
304
305    async fn query_selector(&self, selector: &str) -> Result<Option<ElementInfo>, EngineError> {
306        let value = self
307            .request("querySelector", json!({ "selector": selector }))
308            .await?;
309        element_info_from_value(&value)
310    }
311
312    async fn query_selector_all(&self, selector: &str) -> Result<Vec<ElementInfo>, EngineError> {
313        let value = self
314            .request("querySelectorAll", json!({ "selector": selector }))
315            .await?;
316        let Some(items) = value.as_array() else {
317            return Ok(Vec::new());
318        };
319        let mut infos = Vec::with_capacity(items.len());
320        for item in items {
321            if let Some(info) = element_info_from_value(item)? {
322                infos.push(info);
323            }
324        }
325        Ok(infos)
326    }
327
328    async fn count(&self, selector: &str) -> Result<usize, EngineError> {
329        let value = self
330            .request("count", json!({ "selector": selector }))
331            .await?;
332        Ok(value.as_u64().unwrap_or(0) as usize)
333    }
334
335    async fn click(&self, selector: &str) -> Result<(), EngineError> {
336        self.request("click", json!({ "selector": selector }))
337            .await?;
338        Ok(())
339    }
340
341    async fn fill(&self, selector: &str, text: &str) -> Result<(), EngineError> {
342        self.request("fill", json!({ "selector": selector, "text": text }))
343            .await?;
344        Ok(())
345    }
346
347    async fn type_text(&self, selector: &str, text: &str) -> Result<(), EngineError> {
348        self.request("typeText", json!({ "selector": selector, "text": text }))
349            .await?;
350        Ok(())
351    }
352
353    async fn text_content(&self, selector: &str) -> Result<Option<String>, EngineError> {
354        let value = self
355            .request("textContent", json!({ "selector": selector }))
356            .await?;
357        Ok(value.as_str().map(ToString::to_string))
358    }
359
360    async fn input_value(&self, selector: &str) -> Result<Option<String>, EngineError> {
361        let value = self
362            .request("inputValue", json!({ "selector": selector }))
363            .await?;
364        Ok(value.as_str().map(ToString::to_string))
365    }
366
367    async fn get_attribute(
368        &self,
369        selector: &str,
370        attribute: &str,
371    ) -> Result<Option<String>, EngineError> {
372        let value = self
373            .request(
374                "getAttribute",
375                json!({ "selector": selector, "attribute": attribute }),
376            )
377            .await?;
378        Ok(value.as_str().map(ToString::to_string))
379    }
380
381    async fn is_visible(&self, selector: &str) -> Result<bool, EngineError> {
382        self.bool_request("isVisible", json!({ "selector": selector }))
383            .await
384    }
385
386    async fn is_enabled(&self, selector: &str) -> Result<bool, EngineError> {
387        self.bool_request("isEnabled", json!({ "selector": selector }))
388            .await
389    }
390
391    async fn wait_for_selector(&self, selector: &str, timeout_ms: u64) -> Result<(), EngineError> {
392        self.request(
393            "waitForSelector",
394            json!({ "selector": selector, "timeoutMs": timeout_ms }),
395        )
396        .await?;
397        Ok(())
398    }
399
400    async fn scroll_into_view(&self, selector: &str) -> Result<(), EngineError> {
401        self.request("scrollIntoView", json!({ "selector": selector }))
402            .await?;
403        Ok(())
404    }
405
406    async fn evaluate(&self, script: &str) -> Result<Value, EngineError> {
407        self.request("evaluate", json!({ "script": script })).await
408    }
409
410    async fn screenshot(&self) -> Result<Vec<u8>, EngineError> {
411        decode_base64(self.string_request("screenshot", json!({})).await?)
412    }
413
414    async fn pdf(&self, options: PdfOptions) -> Result<Vec<u8>, EngineError> {
415        let pdf_options = json!({
416            "format": options.format,
417            "printBackground": options.print_background,
418            "margin": {
419                "top": options.margin_top,
420                "right": options.margin_right,
421                "bottom": options.margin_bottom,
422                "left": options.margin_left,
423            },
424            "scale": options.scale,
425            "path": options.path,
426        });
427        let encoded = self
428            .request("pdf", pdf_options)
429            .await?
430            .as_str()
431            .unwrap_or_default()
432            .to_string();
433        decode_base64(encoded)
434    }
435
436    async fn bring_to_front(&self) -> Result<(), EngineError> {
437        self.request("bringToFront", json!({})).await?;
438        Ok(())
439    }
440
441    async fn wait_for_navigation(&self, timeout_ms: u64) -> Result<(), EngineError> {
442        self.request("waitForNavigation", json!({ "timeoutMs": timeout_ms }))
443            .await?;
444        Ok(())
445    }
446
447    async fn keyboard_press(&self, key: &str) -> Result<(), EngineError> {
448        self.request("keyboardPress", json!({ "key": key })).await?;
449        Ok(())
450    }
451
452    async fn keyboard_type(&self, text: &str) -> Result<(), EngineError> {
453        self.request("keyboardType", json!({ "text": text }))
454            .await?;
455        Ok(())
456    }
457
458    async fn keyboard_down(&self, key: &str) -> Result<(), EngineError> {
459        self.request("keyboardDown", json!({ "key": key })).await?;
460        Ok(())
461    }
462
463    async fn keyboard_up(&self, key: &str) -> Result<(), EngineError> {
464        self.request("keyboardUp", json!({ "key": key })).await?;
465        Ok(())
466    }
467}
468
469fn path_to_string(path: &Path) -> String {
470    path.to_string_lossy().into_owned()
471}
472
473fn decode_base64(value: impl AsRef<str>) -> Result<Vec<u8>, EngineError> {
474    base64::engine::general_purpose::STANDARD
475        .decode(value.as_ref())
476        .map_err(|err| EngineError::Browser(format!("bridge returned invalid base64: {err}")))
477}
478
479fn element_info_from_value(value: &Value) -> Result<Option<ElementInfo>, EngineError> {
480    if value.is_null() {
481        return Ok(None);
482    }
483
484    let bounding_box = value.get("boundingBox").and_then(|box_value| {
485        let items = box_value.as_array()?;
486        if items.len() != 4 {
487            return None;
488        }
489        Some((
490            items[0].as_f64().unwrap_or_default(),
491            items[1].as_f64().unwrap_or_default(),
492            items[2].as_f64().unwrap_or_default(),
493            items[3].as_f64().unwrap_or_default(),
494        ))
495    });
496
497    Ok(Some(ElementInfo {
498        tag_name: value
499            .get("tagName")
500            .and_then(Value::as_str)
501            .unwrap_or("UNKNOWN")
502            .to_string(),
503        text_content: value
504            .get("textContent")
505            .and_then(Value::as_str)
506            .map(ToString::to_string),
507        is_visible: value
508            .get("isVisible")
509            .and_then(Value::as_bool)
510            .unwrap_or(false),
511        is_enabled: value
512            .get("isEnabled")
513            .and_then(Value::as_bool)
514            .unwrap_or(true),
515        bounding_box,
516    }))
517}
518
519#[cfg(test)]
520mod tests {
521    use super::*;
522
523    #[test]
524    fn launch_params_forward_browser_selection() {
525        let options = LaunchOptions::playwright()
526            .channel("chrome-beta")
527            .executable_path("/opt/google/chrome-beta");
528
529        let params = launch_params(&options, Path::new("/tmp/browser-data"));
530
531        assert_eq!(params["channel"], "chrome-beta");
532        assert_eq!(params["executablePath"], "/opt/google/chrome-beta");
533    }
534
535    #[test]
536    fn launch_params_default_browser_selection_is_null() {
537        let params = launch_params(&LaunchOptions::puppeteer(), Path::new("/tmp/browser-data"));
538
539        assert!(params["channel"].is_null());
540        assert!(params["executablePath"].is_null());
541    }
542
543    #[test]
544    fn connect_params_forward_endpoint_timeouts_and_cookies() {
545        let options = ConnectOptions::puppeteer()
546            .ws_endpoint("ws://127.0.0.1:9222/devtools/browser/id")
547            .timeout(std::time::Duration::from_millis(1_500))
548            .protocol_timeout(std::time::Duration::from_secs(2))
549            .seed_cookies(vec![json!({"name": "SID", "value": "saved"})]);
550
551        let params = connect_params(&options);
552
553        assert_eq!(params["wsEndpoint"], options.ws_endpoint.unwrap());
554        assert_eq!(params["timeout"], 1_500);
555        assert_eq!(params["protocolTimeout"], 2_000);
556        assert_eq!(params["seedCookies"][0]["name"], "SID");
557    }
558}
browser_commander/browser/node_bridge.rs

browser_commander/browser/
node_bridge.rs
