browser_control/cli/
curl.rs

1//! `browser-control curl` — invoke the system curl with browser credentials.
2//!
3//! Unlike [`crate::cli::fetch`], this request does not execute in a renderer.
4//! The selected browser supplies a snapshot of its cookie jar and User-Agent;
5//! the real curl process supplies transport, streaming, redirects, and every
6//! curl CLI option. Browser cookies are written to a mode-0600 temporary
7//! Netscape jar which is removed when the command finishes.
8
9use std::ffi::OsString;
10use std::io::Write;
11use std::process::Stdio;
12
13use anyhow::{anyhow, bail, Context, Result};
14use base64::Engine;
15use serde_json::{json, Value};
16use tokio::io::AsyncReadExt;
17
18use crate::cli::trace::CommandTrace;
19use crate::session::backend::{open_backend, TabBackend};
20
21/// Maximum raw curl stdout returned inside an MCP tool result. File output
22/// selected by curl's `-o`/`--output` does not pass through this buffer and is
23/// therefore unrestricted.
24pub const MCP_RESPONSE_LIMIT: usize = 8 * 1024 * 1024;
25
26/// Keep diagnostic stderr useful without allowing verbose curl traces to
27/// create another unbounded MCP response.
28const MCP_STDERR_LIMIT: usize = 256 * 1024;
29
30pub(crate) struct PreparedCurl {
31    cookie_jar: tempfile::NamedTempFile,
32    user_agent: String,
33    origin: Option<String>,
34    referer: Option<String>,
35}
36
37#[derive(Debug)]
38pub(crate) struct CurlOutput {
39    pub(crate) exit_code: Option<i32>,
40    pub(crate) stdout: Vec<u8>,
41    pub(crate) stderr: Vec<u8>,
42    pub(crate) stderr_truncated: bool,
43}
44
45impl PreparedCurl {
46    fn command<I, S>(&self, args: I) -> Result<tokio::process::Command>
47    where
48        I: IntoIterator<Item = S>,
49        S: AsRef<std::ffi::OsStr>,
50    {
51        let executable = which::which("curl").context("curl executable not found in PATH")?;
52        let mut command = tokio::process::Command::new(executable);
53        // Browser-derived values are defaults. User argv follows unchanged,
54        // so curl's normal last-option-wins behavior can override User-Agent
55        // and augment other cookie sources when explicitly requested.
56        command
57            .arg("--cookie")
58            .arg(self.cookie_jar.path())
59            .arg("--user-agent")
60            .arg(&self.user_agent);
61        if let Some(origin) = &self.origin {
62            command.arg("--header").arg(format!("Origin: {origin}"));
63        }
64        if let Some(referer) = &self.referer {
65            command.arg("--referer").arg(referer);
66        }
67        command.args(args);
68        Ok(command)
69    }
70}
71
72/// Snapshot browser credentials into the short-lived inputs consumed by
73/// curl. `target_id` is optional because cookies are browser-wide; when set it
74/// is used to read a target-specific `navigator.userAgent` override.
75pub(crate) async fn prepare(backend: &TabBackend, target_id: Option<&str>) -> Result<PreparedCurl> {
76    let cookies = backend.cookies().await?;
77    let live_targets = backend.live_targets().await?;
78    let context_target_id = target_id
79        .filter(|target_id| live_targets.iter().any(|target| target.id == *target_id))
80        .map(String::from)
81        .or_else(|| live_targets.first().map(|target| target.id.clone()));
82    let source_url = context_target_id.as_deref().and_then(|target_id| {
83        live_targets
84            .iter()
85            .find(|target| target.id == target_id)
86            .map(|target| target.url.clone())
87    });
88    let user_agent = backend.user_agent(context_target_id.as_deref()).await?;
89    let (origin, referer) = source_url
90        .as_deref()
91        .map(request_context_headers)
92        .unwrap_or((None, None));
93    let mut cookie_jar =
94        tempfile::NamedTempFile::new().context("creating temporary browser cookie jar for curl")?;
95    cookie_jar
96        .write_all(crate::cli::cookies::format_netscape(&cookies).as_bytes())
97        .context("writing temporary browser cookie jar for curl")?;
98    cookie_jar
99        .flush()
100        .context("flushing temporary browser cookie jar for curl")?;
101    Ok(PreparedCurl {
102        cookie_jar,
103        user_agent,
104        origin,
105        referer,
106    })
107}
108
109fn request_context_headers(source_url: &str) -> (Option<String>, Option<String>) {
110    let Ok(mut parsed) = url::Url::parse(source_url) else {
111        return (None, None);
112    };
113    if !matches!(parsed.scheme(), "http" | "https") {
114        return (None, None);
115    }
116    let origin = parsed.origin().ascii_serialization();
117    parsed.set_fragment(None);
118    (Some(origin), Some(parsed.to_string()))
119}
120
121/// CLI entry point. Curl owns stdin/stdout/stderr, so ordinary streaming and
122/// `-o` downloads behave exactly like invoking curl directly.
123pub async fn run(browser: Option<String>, args: Vec<OsString>) -> Result<()> {
124    if args.is_empty() {
125        bail!("curl requires arguments; pass curl options and at least one URL");
126    }
127    let mut trace = CommandTrace::new("curl");
128    let result = run_inner(browser, args, &mut trace).await;
129    trace.finish(result)
130}
131
132async fn run_inner(
133    browser: Option<String>,
134    args: Vec<OsString>,
135    trace: &mut CommandTrace,
136) -> Result<()> {
137    let route = crate::cli::route::preamble(browser, None, trace).await?;
138    let backend = open_backend(&route.resolved.endpoint, route.resolved.engine).await?;
139    let target_id = match route.tab_name.as_deref() {
140        Some(tab_name) => {
141            trace.route("named-tab").tab_name(tab_name);
142            let browser_name = match &route.resolved.source {
143                crate::cli::env_resolver::Source::Registered { name } => name.clone(),
144                crate::cli::env_resolver::Source::External => {
145                    bail!("named tabs (`<browser>/<name>`) require a registered browser")
146                }
147            };
148            let row =
149                crate::session::resolve_tab(&backend, &route.registry, &browser_name, tab_name)
150                    .await?
151                    .ok_or_else(|| crate::errors::SessionError::TabNotFound {
152                        browser: browser_name,
153                        name: tab_name.to_string(),
154                    })?;
155            trace.target_id(&row.target_id);
156            Some(row.target_id)
157        }
158        None => {
159            trace.route("browser-wide");
160            None
161        }
162    };
163
164    let prepared = prepare(&backend, target_id.as_deref()).await?;
165    // Curl no longer needs the browser protocol connection or registry lock.
166    // Release both before a potentially long download.
167    drop(backend);
168    drop(route);
169
170    let mut command = prepared.command(args.iter())?;
171    command
172        .stdin(Stdio::inherit())
173        .stdout(Stdio::inherit())
174        .stderr(Stdio::inherit());
175    let status = command.status().await.context("running curl")?;
176    if !status.success() {
177        bail!(
178            "curl exited with status {}",
179            status
180                .code()
181                .map(|code| code.to_string())
182                .unwrap_or_else(|| "terminated by signal".to_string())
183        );
184    }
185    Ok(())
186}
187
188/// Execute curl for MCP. Stdout is read incrementally and the child is killed
189/// as soon as the response would exceed `MCP_RESPONSE_LIMIT`; stderr is always
190/// drained concurrently and retained only up to `MCP_STDERR_LIMIT`.
191pub(crate) async fn execute_mcp(prepared: &PreparedCurl, args: &[String]) -> Result<CurlOutput> {
192    if args.is_empty() {
193        bail!("`args` must contain curl options and at least one URL");
194    }
195    let mut command = prepared.command(args)?;
196    command
197        .stdin(Stdio::null())
198        .stdout(Stdio::piped())
199        .stderr(Stdio::piped());
200    let mut child = command.spawn().context("running curl")?;
201    let mut stdout = child
202        .stdout
203        .take()
204        .ok_or_else(|| anyhow!("failed to capture curl stdout"))?;
205    let stderr = child
206        .stderr
207        .take()
208        .ok_or_else(|| anyhow!("failed to capture curl stderr"))?;
209    let stderr_task = tokio::spawn(read_bounded_and_drain(stderr, MCP_STDERR_LIMIT));
210
211    let mut body = Vec::new();
212    let mut chunk = [0_u8; 64 * 1024];
213    loop {
214        let n = stdout
215            .read(&mut chunk)
216            .await
217            .context("reading curl stdout")?;
218        if n == 0 {
219            break;
220        }
221        if body.len().saturating_add(n) > MCP_RESPONSE_LIMIT {
222            let _ = child.kill().await;
223            let _ = child.wait().await;
224            let _ = stderr_task.await;
225            bail!(
226                "curl response exceeded the 8 MiB MCP limit; retry with `-o <path>` or `--output <path>` to stream it directly to a file"
227            );
228        }
229        body.extend_from_slice(&chunk[..n]);
230    }
231
232    let status = child.wait().await.context("waiting for curl")?;
233    let (stderr, stderr_truncated) = stderr_task.await.context("joining curl stderr reader")??;
234    Ok(CurlOutput {
235        exit_code: status.code(),
236        stdout: body,
237        stderr,
238        stderr_truncated,
239    })
240}
241
242async fn read_bounded_and_drain<R>(mut reader: R, limit: usize) -> Result<(Vec<u8>, bool)>
243where
244    R: tokio::io::AsyncRead + Unpin,
245{
246    let mut kept = Vec::new();
247    let mut truncated = false;
248    let mut chunk = [0_u8; 16 * 1024];
249    loop {
250        let n = reader.read(&mut chunk).await?;
251        if n == 0 {
252            break;
253        }
254        let remaining = limit.saturating_sub(kept.len());
255        let take = remaining.min(n);
256        kept.extend_from_slice(&chunk[..take]);
257        truncated |= take < n;
258    }
259    Ok((kept, truncated))
260}
261
262/// Convert a completed curl invocation to an MCP tool result. Text is emitted
263/// directly; arbitrary bytes use the protocol's embedded-resource blob form.
264pub(crate) fn mcp_result(output: CurlOutput) -> Value {
265    let success = output.exit_code == Some(0);
266    let mut content = Vec::new();
267    if !output.stdout.is_empty() {
268        match std::str::from_utf8(&output.stdout) {
269            Ok(text) => content.push(json!({ "type": "text", "text": text })),
270            Err(_) => content.push(json!({
271                "type": "resource",
272                "resource": {
273                    "uri": "browser-control://curl/response",
274                    "mimeType": "application/octet-stream",
275                    "blob": base64::engine::general_purpose::STANDARD.encode(&output.stdout),
276                }
277            })),
278        }
279    }
280    let stderr = String::from_utf8_lossy(&output.stderr);
281    content.push(json!({
282        "type": "text",
283        "text": serde_json::to_string_pretty(&json!({
284            "exit_code": output.exit_code,
285            "stdout_bytes": output.stdout.len(),
286            "stderr": stderr,
287            "stderr_truncated": output.stderr_truncated,
288        })).expect("serializing curl metadata cannot fail")
289    }));
290    json!({
291        "content": content,
292        "isError": !success,
293    })
294}
295
296#[cfg(test)]
297mod tests {
298    use super::*;
299
300    #[test]
301    fn mcp_result_returns_utf8_as_text() {
302        let result = mcp_result(CurlOutput {
303            exit_code: Some(0),
304            stdout: b"hello".to_vec(),
305            stderr: Vec::new(),
306            stderr_truncated: false,
307        });
308        assert_eq!(result["isError"], false);
309        assert_eq!(result["content"][0]["type"], "text");
310        assert_eq!(result["content"][0]["text"], "hello");
311    }
312
313    #[test]
314    fn mcp_result_returns_binary_as_embedded_resource() {
315        let result = mcp_result(CurlOutput {
316            exit_code: Some(0),
317            stdout: vec![0, 159, 146, 150],
318            stderr: Vec::new(),
319            stderr_truncated: false,
320        });
321        assert_eq!(result["content"][0]["type"], "resource");
322        assert_eq!(result["content"][0]["resource"]["blob"], "AJ+Slg==");
323    }
324
325    #[test]
326    fn mcp_result_marks_nonzero_curl_exit_as_tool_error() {
327        let result = mcp_result(CurlOutput {
328            exit_code: Some(22),
329            stdout: b"not found".to_vec(),
330            stderr: b"curl: (22) HTTP response code said error".to_vec(),
331            stderr_truncated: false,
332        });
333        assert_eq!(result["isError"], true);
334        assert!(result["content"][1]["text"]
335            .as_str()
336            .unwrap()
337            .contains("\"exit_code\": 22"));
338    }
339
340    #[test]
341    fn request_context_headers_use_tab_origin_and_fragmentless_url() {
342        let (origin, referer) =
343            request_context_headers("https://app.example.com:8443/work?q=1#section");
344        assert_eq!(origin.as_deref(), Some("https://app.example.com:8443"));
345        assert_eq!(
346            referer.as_deref(),
347            Some("https://app.example.com:8443/work?q=1")
348        );
349    }
350
351    #[test]
352    fn request_context_headers_ignore_non_http_tabs() {
353        assert_eq!(request_context_headers("about:blank"), (None, None));
354    }
355}
browser_control/cli/curl.rs

browser_control/cli/
curl.rs
