CDP Use (Rust)

Rust implementation of cdp-use -- a type-safe Chrome DevTools Protocol client with auto-generated bindings from the official CDP protocol specifications.

Features

• Type-safe commands & events -- Strongly typed structs for all 53 CDP domains, generated at build time via build.rs
• Async WebSocket client -- Built on tokio + tokio-tungstenite with proper timeout, close ordering, and concurrent event dispatch
• Typed event registration -- Register async closures for CDP events with full type safety
• Configurable connection -- Custom WebSocket frame size, headers, and command timeout via CdpClientConfig
• Zero manual maintenance -- Code generated directly from browser_protocol.json and js_protocol.json

Installation

Add to your Cargo.toml:

[dependencies]
cdp-use-rs = "0.1"

# or from git
cdp-use-rs = { git = "https://github.com/netkn001/cdp-use-rs" }

Quick Start

use cdp_use::page;

#[tokio::main]
async fn main() -> Result<(), cdp_use::CdpError> {
    // Connect to Chrome running with --remote-debugging-port=9222
    let cdp = cdp_use::CdpClient::connect("ws://127.0.0.1:9222/devtools/browser/...").await?;

    let send = cdp.send();
    let register = cdp.register();

    // List targets
    let targets = send.target.get_targets(Default::default(), None).await?;
    println!("Found {} targets", targets.target_infos.len());

    // Attach to a page target
    let page_target = targets.target_infos.iter()
        .find(|t| t.r#type == "page")
        .expect("No page target");

    let session = send.target.attach_to_target(
        cdp_use::target::commands::AttachToTargetParams {
            target_id: page_target.target_id.clone(),
            flatten: Some(true),
            ..Default::default()
        },
        None,
    ).await?;
    let sid = session.session_id;

    // Enable Page domain and register event handler
    send.page.enable(Default::default(), Some(&sid)).await?;

    register.page.frame_navigated(|event, _session_id| async move {
        println!("Navigated: {} -> {}", event.frame.id, event.frame.url);
    });

    // Navigate
    let nav = send.page.navigate(
        page::commands::NavigateParams {
            url: "https://example.com".into(),
            ..Default::default()
        },
        Some(&sid),
    ).await?;
    println!("Frame: {}", nav.frame_id);

    cdp.close().await?;
    Ok(())
}

Custom Configuration

use cdp_use::{CdpClient, CdpClientConfig};
use std::time::Duration;

let config = CdpClientConfig {
    max_message_size: Some(100 * 1024 * 1024), // 100 MiB (default)
    max_frame_size: Some(16 * 1024 * 1024),    // 16 MiB
    command_timeout: Duration::from_secs(60),    // default: 30s
    additional_headers: [("Authorization".into(), "Bearer token".into())].into(),
};

let cdp = CdpClient::connect_with_config("ws://...", config).await?;

Architecture

cdp-use-rs/
  build.rs              # Code generator -- reads protocol JSON, emits generated.rs
  protocols/
    browser_protocol.json
    js_protocol.json
  src/
    lib.rs              # Public API re-exports
    client.rs           # WebSocket client, event registry, CdpClientConfig
    error.rs            # CdpError enum
  examples/
    basic.rs            # Full usage example
  tests/
    codegen_test.rs     # Type/serialization/config tests
    integration_test.rs # Live browser integration tests

At build time, build.rs parses the CDP protocol JSON files and generates a generated.rs containing:

• Types -- Structs, enums, and type aliases for each domain (page::types::Frame, network::types::RequestId, ...)
• Commands -- *Params / *Returns structs and typed async methods on domain clients
• Events -- Event structs and typed registration methods
• CdpLibrary / CdpRegistrationLibrary -- Top-level accessors: cdp.send().page.navigate(...), cdp.register().page.frame_navigated(...)

Comparison with Other Browser Automation Tools

When to use cdp-use-rs

• You need direct access to all 53 CDP domains without abstraction layers getting in the way
• You're building AI browser agents or infrastructure that requires low-level protocol control
• You want compile-time type safety and zero-cost abstractions over the CDP protocol
• Performance matters -- Rust's async runtime and zero-overhead WebSocket handling
• You're integrating CDP into a larger Rust system (e.g., an agent framework, a proxy, or a custom browser controller)

When to use Playwright / Puppeteer / Selenium instead

• You need cross-browser support (Firefox, WebKit/Safari)
• You want high-level APIs with built-in auto-wait, selectors, and test assertions
• You're writing E2E tests for web applications
• You prefer a batteries-included approach with screenshots, tracing, and network interception out of the box

Comparison with Python cdp-use

Development

cargo build    # Generates CDP bindings and compiles
cargo test     # Run all tests
cargo doc      # Generate documentation

# Run the example (requires Chrome with --remote-debugging-port=9222)
cargo run --example basic -- "ws://127.0.0.1:9222/devtools/browser/GUID"

Related

• cdp-use -- Original Python implementation
• Chrome DevTools Protocol -- Official protocol documentation
• browser-use -- Browser automation framework

License

MIT