oxibrowser는 뭘로 브라우저 흉내를 내는가

AGENTS.md가 정체성을 한 줄로 못박습니다 — "headless browser built in pure Rust, designed for AI agents and automation. No Chromium, no V8. Single static binary." 이 한 문장 안에 이미 이 프로젝트의 모든 트레이드오프가 예고돼 있어요. Chromium/V8을 빌려 쓰는 대신 html5ever·boa_engine·Blitz를 직접 갖다 붙였다는 건, 브라우저 엔진 하나를 통째로 재구현하는 대가를 치르더라도 단일 정적 바이너리라는 배포 형태를 포기하지 않겠다는 선언이거든요.

// 4-crate workspace, edition 2024, rust 1.96
[workspace]
resolver = "2"
members = [
    "crates/oxibrowser",       // CLI + lib facade
    "crates/oxibrowser-cdp",   // Chrome DevTools Protocol 서버
    "crates/oxibrowser-core",  // 엔진의 두뇌
    "crates/oxibrowser-render", // Blitz 렌더 파이프라인
]

그리고 workspace 의존성 목록을 보면 이 프로젝트가 안고 가는 짐이 얼마나 무거운지 감이 옵니다 — HTTP 클라이언트가 두 개(reqwest + wreq), JS/WASM 엔진이 두 개(boa_engine + wasmi), 거기에 Blitz 렌더 스택(Stylo CSS 엔진, html5ever 0.39, vello)까지 전부 한 워크스페이스 안에 들어 있어요. 이 페이지의 뒷부분 절반은 사실 "왜 이렇게 중복처럼 보이는 선택들을 했는가"를 설명하는 내용입니다.

reqwest = { version = "0.12", features = ["json", "rustls-tls"], default-features = false }
wreq    = { version = "=6.0.0-rc.29", features = ["json", "form", "stream"] }
boa_engine = "0.20"
wasmi = "1.1"

// Rendering stack — isolated to oxibrowser-render so the Stylo / html5ever 0.39
// / vello dependency trees stay out of the rest of the workspace.
blitz-dom = "0.3.0-beta.1"
blitz-paint = "0.3.0-beta.1"

답은 "회피하지 않고 정면으로 받아들인다"였습니다. Context를 전용 std::thread 하나에 영구히 고정시켜버리고, 그 스레드와는 오직 mpsc 채널로만 대화합니다. js/runtime.rs:7-10 주석이 이 설계를 정확히 요약합니다.

//! `boa_engine::Context` is `!Send` (internal GC pointers use `NonNull`).
//! To keep `JsRuntime: Send + Sync` for tokio, we run the `Context` on a
//! dedicated **std::thread** and communicate via `mpsc` channels.
//!
//! This means JS state (variables, functions, closures) **persists across
//! evaluate() calls** — exactly like a real browser.

이 구조가 낳는 결과가 네 가지 있습니다. 첫째, 영속 컨텍스트 — evaluate() 호출 사이에 변수·함수·클로저가 살아남아서 진짜 브라우저처럼 동작합니다. 둘째, 이벤트 리스너·pending fetch·pending WS 같은 상태가 전부 thread_local!입니다 — Context가 그 스레드를 절대 떠나지 않으니 !Send 값을 안전하게 보관할 수 있는 거예요. 셋째, 타이머와 async는 별도 트레이트 구현으로 지원합니다 — js/job_queue.rs가 boa의 JobQueue trait을 구현해서 setTimeout/Promise/마이크로태스크를 처리합니다. 넷째, WebAssembly(wasmi)도 굳이 별도 스레드를 안 만들고 같은 JS 스레드 위에서 돕니다 — wasmi의 핸들(Engine/Module/Store/Instance)도 Send가 아니라서, 정확히 같은 제약을 그대로 물려받았기 때문입니다.

wreq는 오직 oxibrowser-core의 HttpClient에서만 쓰입니다. 이유는 Chrome 149 TLS/HTTP2 핑거프린트 에뮬레이션이에요 — 페이지 로드는 실제 Chrome처럼 보여야 Cloudflare나 DataDome 같은 봇 탐지를 통과합니다.

use wreq::{Client, Response};
use wreq_util::Emulation;

let mut builder = Client::builder()
    .emulation(Emulation::Chrome149)
    .user_agent(&config.user_agent)
    .pool_max_idle_per_host(config.connection_pool_size)
    .timeout(config.default_timeout);

재밌는 디테일 하나 — User-Agent 기본값도 정확히 Emulation::Chrome149 프로필에 맞춰져 있습니다. config.rs:28-32 주석이 이유를 설명하는데, transport layer(wreq)와 JS layer(boa의 navigator.userAgent) 양쪽이 정확히 같은 값을 보여줘야 봇 탐지에 안 걸린다는 겁니다. 한쪽은 Chrome 149라고 하는데 다른 쪽은 다른 값을 말하면, 그 불일치 자체가 탐지 시그널이 되거든요.

반면 reqwest는 oxibrowser(CLI)의 검색 모듈 + dev-dependencies에만 등장합니다. 검색은 봇으로 위장할 이유가 없어요 — DDG/Wiki/Bing/GitHub에 정직하게 요청 하나 날리고 결과 받아오면 끝인 사용자 검색 에이전트일 뿐입니다.

/// Build a lightweight reqwest::Client for search (no SSRF filter, no cookies).
pub fn build_search_client(timeout_secs: u64) -> reqwest::Client {
    reqwest::Client::builder()
        .timeout(Duration::from_secs(timeout_secs))
        .user_agent("oxibrowser/x.y.z")
        .https_only(true)
        .build()
        .expect("reqwest::Client::builder() failed")
}

바이너리 레벨(oxios)은 오직 oxibrowser::search::dispatch()만 씁니다 — /api/search 핸들러가 이 함수를 직접 호출해서, 에이전트 루프를 하나도 거치지 않고 즉시 검색 결과를 반환합니다. 반면 커널 레벨(oxios-kernel, browser feature 뒤)은 oxibrowser-core를 통째로 끌어와 browse tool과 스크린샷 백엔드를 직접 짭니다. 즉 "가볍게 쓸 땐 파사드만, 무겁게 쓸 땐 core를 직접" — 04에서 본 feature 게이팅이 정확히 이 비대칭을 가능하게 만드는 겁니다.

//! Concrete browser engine — wraps `oxibrowser-core` directly.
//! No trait abstraction, no dyn dispatch. There is exactly one backend
//! (`oxibrowser-core` 0.21), so concrete types are simpler and faster.