ADR 0008.1: Browser Backend Evaluation

ADR 0008.1: Browser Backend Evaluation & Selection (Phase 5.1)¶

Status¶

Implemented (v0.0.5)

Context¶

As part of the v0.0.5 initiative, we replaced the Node.js/Playwright dependency with a Rust-native solution for diagram rendering (Mermaid, BPMN).

Performance and stability benchmarks were conducted in a standalone experiment (experiments/browser-eval).

Capability Testing Methodology¶

The following capabilities were tested to verify production readiness:

1. Cold-Start Launch: Measuring the time from process start to a responsive DevTools Protocol (CDP) session.

2. Secure Navigation: Verifying HTTPS handshaking and certificate handling during page load.

3. Headless Detection Bypass: Ensuring the browser instance can render complex JavaScript (Mermaid.js) without being blocked by basic headless detection scripts.

4. Synchronous vs. Async Threading: Testing how the library handles long-running renders within a shared thread pool (merging the “Playwright Pooling” concept from ADR 0004).

5. Memory Pressure/Dangling Resources: Verifying that closing the high-level Browser object correctly terminates underlying chrome child processes.

6. Error Propagation: Capturing and normalizing CDP-level errors (e.g., TargetClosed, NavigationTimeout) into meaningful Rust Result types.

Evaluation Results¶

Note 1: fantoccini requires a standalone chromedriver process, which contradicts our goal of reducing external runtime dependencies and binary footprint. Note 2: While fantoccini’s direct binary footprint is negligible (+28 KB), the required chromedriver binary adds ~15-20 MB of hidden external dependency weight.

Decision¶

We adopted headless_chrome as the primary browser backend for kroki-rs.

Rationale¶

1. Performance: headless_chrome demonstrated a extremely fast cold-start and navigation cycle (under 4s for a full external page load and screenshot).

2. Simplicity: The synchronous API of headless_chrome simplifies local thread management and pooling without the “oneshot canceled” hazards observed in chromiumoxide’s async handler lifecycle.

3. Deployment: It works directly with any installed Google Chrome, Chromium, or Brave binary, matching the current user-level requirements while eliminating Node.js.

Consequences¶

• The BrowserBackend trait in v0.0.5 will be modeled around headless_chrome capabilities.

• We will implement a connection-pooling strategy (similar to ADR 0004) to further reduce the 400ms launch latency for sub-sequential requests.

• Node.js and Playwright will be removed from the CI and build pipelines once the migration is complete.