browsr_client/

lib.rs

use browsr_types::{
    AutomateResponse, BrowserContext, Commands, ObserveResponse, ScrapeOptions, SearchOptions,
    SearchResponse,
};
use reqwest::StatusCode;
use serde::{Deserialize, Serialize, de::DeserializeOwned};
use serde_json::{Value, json};
use thiserror::Error;
use tokio::process::Command;

#[derive(Debug, Clone)]
pub enum TransportConfig {
    Http { base_url: String },
    Stdout { command: String },
}

#[derive(Debug, Clone)]
pub struct BrowsrClient {
    transport: BrowsrTransport,
}

#[derive(Debug, Clone)]
enum BrowsrTransport {
    Http(HttpTransport),
    Stdout(StdoutTransport),
}

impl BrowsrClient {
    pub fn new_http(base_url: impl Into<String>) -> Self {
        Self {
            transport: BrowsrTransport::Http(HttpTransport::new(base_url)),
        }
    }

    pub fn new_stdout(command: impl Into<String>) -> Self {
        Self {
            transport: BrowsrTransport::Stdout(StdoutTransport::new(command)),
        }
    }

    pub fn from_config(cfg: TransportConfig) -> Self {
        match cfg {
            TransportConfig::Http { base_url } => Self::new_http(base_url),
            TransportConfig::Stdout { command } => Self::new_stdout(command),
        }
    }

    pub async fn list_sessions(&self) -> Result<Vec<String>, ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => {
                let response: SessionList = inner.get("/sessions").await?;
                Ok(response.sessions)
            }
            BrowsrTransport::Stdout(inner) => inner.list_sessions().await,
        }
    }

    pub async fn create_session(&self) -> Result<String, ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => {
                let response: SessionCreated = inner.post("/sessions", &Value::Null).await?;
                Ok(response.session_id)
            }
            BrowsrTransport::Stdout(inner) => inner.create_session().await,
        }
    }

    pub async fn destroy_session(&self, session_id: &str) -> Result<(), ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => inner
                .delete(&format!("/sessions/{}", session_id))
                .await
                .map(|_: Value| ()),
            BrowsrTransport::Stdout(inner) => inner.destroy_session(session_id).await,
        }
    }

    pub async fn execute_commands(
        &self,
        commands: Vec<Commands>,
        session_id: Option<String>,
        headless: Option<bool>,
        context: Option<BrowserContext>,
    ) -> Result<AutomateResponse, ClientError> {
        let payload = CommandsPayload {
            commands,
            session_id,
            headless,
            context,
        };

        match &self.transport {
            BrowsrTransport::Http(inner) => inner.post("/commands", &payload).await,
            BrowsrTransport::Stdout(inner) => inner.execute_commands(&payload).await,
        }
    }

    pub async fn observe(
        &self,
        session_id: Option<String>,
        headless: Option<bool>,
        opts: ObserveOptions,
    ) -> Result<ObserveResponse, ClientError> {
        let payload = ObservePayload {
            session_id,
            headless,
            use_image: opts.use_image,
            full_page: opts.full_page,
            wait_ms: opts.wait_ms,
            include_content: opts.include_content,
        };

        match &self.transport {
            BrowsrTransport::Http(inner) => {
                let envelope: ObserveEnvelope = inner.post("/observe", &payload).await?;
                Ok(envelope.observation)
            }
            BrowsrTransport::Stdout(inner) => inner.observe(&payload).await,
        }
    }

    pub async fn scrape(&self, options: ScrapeOptions) -> Result<Value, ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => inner.post("/scrape", &options).await,
            BrowsrTransport::Stdout(inner) => inner.scrape(&options).await,
        }
    }

    pub async fn search(&self, options: SearchOptions) -> Result<SearchResponse, ClientError> {
        match &self.transport {
            BrowsrTransport::Http(inner) => inner.post("/search", &options).await,
            BrowsrTransport::Stdout(inner) => inner.search(&options).await,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct SessionList {
    sessions: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct SessionCreated {
    session_id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct CommandsPayload {
    commands: Vec<Commands>,
    #[serde(skip_serializing_if = "Option::is_none")]
    session_id: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    headless: Option<bool>,
    #[serde(skip_serializing_if = "Option::is_none")]
    context: Option<BrowserContext>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ObserveOptions {
    pub use_image: Option<bool>,
    pub full_page: Option<bool>,
    pub wait_ms: Option<u64>,
    pub include_content: Option<bool>,
}

impl Default for ObserveOptions {
    fn default() -> Self {
        Self {
            use_image: Some(true),
            full_page: None,
            wait_ms: None,
            include_content: Some(true),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct ObservePayload {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub session_id: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub headless: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub use_image: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub full_page: Option<bool>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub wait_ms: Option<u64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub include_content: Option<bool>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct ObserveEnvelope {
    pub session_id: String,
    pub observation: ObserveResponse,
}

#[derive(Debug, Error)]
pub enum ClientError {
    #[error("http request failed: {0}")]
    Http(#[from] reqwest::Error),
    #[error("stdout transport failed: {0}")]
    Stdout(String),
    #[error("invalid response: {0}")]
    InvalidResponse(String),
    #[error("serialization error: {0}")]
    Serialization(#[from] serde_json::Error),
    #[error("io error: {0}")]
    Io(#[from] std::io::Error),
}

#[derive(Debug, Clone)]
struct HttpTransport {
    base_url: String,
    client: reqwest::Client,
}

impl HttpTransport {
    fn new(base_url: impl Into<String>) -> Self {
        Self {
            base_url: base_url.into(),
            client: reqwest::Client::new(),
        }
    }

    fn url(&self, path: &str) -> String {
        let base = self.base_url.trim_end_matches('/');
        let suffix = path.trim_start_matches('/');
        format!("{}/{}", base, suffix)
    }

    async fn get<T: DeserializeOwned>(&self, path: &str) -> Result<T, ClientError> {
        let resp = self.client.get(self.url(path)).send().await?;
        Self::handle_response(resp).await
    }

    async fn delete<T: DeserializeOwned>(&self, path: &str) -> Result<T, ClientError> {
        let resp = self.client.delete(self.url(path)).send().await?;
        Self::handle_response(resp).await
    }

    async fn post<T: DeserializeOwned, B: Serialize + ?Sized>(
        &self,
        path: &str,
        body: &B,
    ) -> Result<T, ClientError> {
        let resp = self.client.post(self.url(path)).json(body).send().await?;
        Self::handle_response(resp).await
    }

    async fn handle_response<T: DeserializeOwned>(
        resp: reqwest::Response,
    ) -> Result<T, ClientError> {
        let status = resp.status();
        if status == StatusCode::NO_CONTENT {
            let empty: Value = Value::Null;
            let value: T = serde_json::from_value(empty).map_err(ClientError::Serialization)?;
            return Ok(value);
        }

        let text = resp.text().await?;
        if !status.is_success() {
            return Err(ClientError::InvalidResponse(format!(
                "{}: {}",
                status, text
            )));
        }

        serde_json::from_str(&text).map_err(ClientError::Serialization)
    }
}

#[derive(Debug, Clone)]
struct StdoutTransport {
    command: String,
}

impl StdoutTransport {
    fn new(command: impl Into<String>) -> Self {
        Self {
            command: command.into(),
        }
    }

    async fn list_sessions(&self) -> Result<Vec<String>, ClientError> {
        let envelope: SessionList = self.request("sessions", &Value::Null).await?;
        Ok(envelope.sessions)
    }

    async fn create_session(&self) -> Result<String, ClientError> {
        let created: SessionCreated = self.request("create_session", &Value::Null).await?;
        Ok(created.session_id)
    }

    async fn destroy_session(&self, session_id: &str) -> Result<(), ClientError> {
        let payload = json!({ "session_id": session_id });
        let _: Value = self.request("destroy_session", &payload).await?;
        Ok(())
    }

    async fn execute_commands(
        &self,
        payload: &CommandsPayload,
    ) -> Result<AutomateResponse, ClientError> {
        self.request("execute", payload).await
    }

    async fn observe(&self, payload: &ObservePayload) -> Result<ObserveResponse, ClientError> {
        let envelope: ObserveEnvelope = self.request("observe", payload).await?;
        Ok(envelope.observation)
    }

    async fn scrape(&self, options: &ScrapeOptions) -> Result<Value, ClientError> {
        self.request("scrape", options).await
    }

    async fn search(&self, options: &SearchOptions) -> Result<SearchResponse, ClientError> {
        self.request("search", options).await
    }

    async fn request<T: DeserializeOwned, B: Serialize>(
        &self,
        operation: &str,
        payload: &B,
    ) -> Result<T, ClientError> {
        let mut cmd = Command::new(&self.command);
        cmd.arg("client").arg(operation);

        let payload_str = serde_json::to_string(&payload).map_err(ClientError::Serialization)?;
        cmd.env("BROWSR_CLIENT_PAYLOAD", &payload_str);

        let output = cmd.output().await?;
        if !output.status.success() {
            let stderr = String::from_utf8_lossy(&output.stderr).to_string();
            return Err(ClientError::Stdout(format!(
                "browsr command failed ({}): {}",
                output.status, stderr
            )));
        }

        let stdout = String::from_utf8_lossy(&output.stdout);
        if stdout.trim().is_empty() {
            return Err(ClientError::InvalidResponse(
                "empty stdout from browsr".to_string(),
            ));
        }

        serde_json::from_str(stdout.trim()).map_err(ClientError::Serialization)
    }
}

/// Derive a default base URL for HTTP transport from standard env vars.
pub fn default_base_url() -> Option<String> {
    if let Ok(url) = std::env::var("BROWSR_API_URL") {
        return Some(url);
    }
    if let Ok(port) = std::env::var("BROWSR_PORT") {
        let host = std::env::var("BROWSR_HOST").unwrap_or_else(|_| "127.0.0.1".to_string());
        return Some(format!("http://{}:{}", host, port));
    }
    // Fallback to the common local default so we avoid the unusable stdout transport when not configured.
    Some("http://127.0.0.1:8082".to_string())
}

pub fn default_transport() -> TransportConfig {
    TransportConfig::Http {
        base_url: default_base_url().unwrap_or_else(|| "http://127.0.0.1:8082".to_string()),
    }
}