viewpoint-cdp

Low-level Chrome DevTools Protocol (CDP) implementation over WebSocket for Rust.

This crate provides the foundational CDP communication layer for the Viewpoint browser automation framework. It handles the WebSocket connection, message serialization, and protocol domain definitions.

Features

Async WebSocket: Non-blocking WebSocket communication with Chromium
Type-safe Protocol: Strongly-typed CDP domains (Page, Runtime, Network, etc.)
Event Streaming: Subscribe to CDP events with async channels
Session Multiplexing: Handle multiple page sessions over a single connection
Error Handling: Comprehensive error types for CDP and transport errors

Installation

Add to your Cargo.toml:

[dependencies]
viewpoint-cdp = "0.2"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Quick Start

use viewpoint_cdp::{CdpConnection, protocol::target_domain::GetTargetsParams};

#[tokio::main]
async fn main() -> Result<(), viewpoint_cdp::CdpError> {
    // Connect to a running Chrome instance
    let conn = CdpConnection::connect("ws://localhost:9222/devtools/browser/...").await?;

    // Send a CDP command
    let result: viewpoint_cdp::protocol::target_domain::GetTargetsResult =
        conn.send_command("Target.getTargets", Some(GetTargetsParams::default()), None).await?;

    for target in result.target_infos {
        println!("Target: {} - {}", target.target_type, target.url);
    }
    Ok(())
}

Discovering Chrome WebSocket URL

Chrome exposes a JSON API for discovering the WebSocket URL:

use viewpoint_cdp::{discover_websocket_url, CdpConnectionOptions};

#[tokio::main]
async fn main() -> Result<(), viewpoint_cdp::CdpError> {
    let options = CdpConnectionOptions::default();
    let ws_url = discover_websocket_url("http://localhost:9222", &options).await?;
    println!("WebSocket URL: {}", ws_url);
    Ok(())
}

Sending Commands

Commands are sent with optional session IDs for page-specific operations:

use viewpoint_cdp::CdpConnection;
use viewpoint_cdp::protocol::page::NavigateParams;

async fn example(conn: &CdpConnection, session_id: &str) -> Result<(), viewpoint_cdp::CdpError> {
    // Browser-level command (no session)
    let version: viewpoint_cdp::BrowserVersion = conn.send_command(
        "Browser.getVersion",
        None::<()>,
        None  // No session ID for browser-level commands
    ).await?;

    // Page-level command (with session)
    let result: viewpoint_cdp::protocol::page::NavigateResult = conn.send_command(
        "Page.navigate",
        Some(NavigateParams {
            url: "https://example.com".to_string(),
            referrer: None,
            transition_type: None,
            frame_id: None,
        }),
        Some(session_id)  // Target a specific page
    ).await?;
    Ok(())
}

Subscribing to Events

Subscribe to CDP events using the event channel:

use viewpoint_cdp::CdpConnection;

async fn example(conn: &CdpConnection) -> Result<(), viewpoint_cdp::CdpError> {
    let mut events = conn.subscribe_events();

    // Process events in a loop
    while let Ok(event) = events.recv().await {
        match &event.method[..] {
            "Page.loadEventFired" => {
                println!("Page loaded!");
            }
            "Network.requestWillBeSent" => {
                println!("Network request: {:?}", event.params);
            }
            _ => {}
        }
    }
    Ok(())
}

Connection Options

Configure connection behavior with options:

use viewpoint_cdp::{CdpConnection, CdpConnectionOptions};
use std::time::Duration;

#[tokio::main]
async fn main() -> Result<(), viewpoint_cdp::CdpError> {
    let options = CdpConnectionOptions::new()
        .timeout(Duration::from_secs(30));

    let conn = CdpConnection::connect_with_options(
        "ws://localhost:9222/devtools/browser/...",
        &options
    ).await?;
    Ok(())
}

Protocol Domains

The protocol module contains typed definitions for CDP domains:

target_domain - Target management (pages, workers, service workers)
page - Page navigation and lifecycle
runtime - JavaScript execution
network - Network monitoring and interception
fetch - Network request interception
dom - DOM inspection and manipulation
input - Input device simulation
emulation - Device and media emulation
And many more...

Error Handling

The CdpError type covers all possible errors:

use viewpoint_cdp::{CdpConnection, CdpError};

async fn example() -> Result<(), CdpError> {
    let result = CdpConnection::connect("ws://invalid:9999/...").await;

    match result {
        Ok(_conn) => println!("Connected!"),
        Err(CdpError::ConnectionFailed(e)) => println!("Connection error: {}", e),
        Err(CdpError::Protocol { code, message }) => {
            println!("CDP error {}: {}", code, message);
        }
        Err(e) => println!("Other error: {}", e),
    }
    Ok(())
}

When to Use This Crate

This crate is primarily used internally by viewpoint-core. For browser automation, use viewpoint-test or viewpoint-core instead, which provide a higher-level, more ergonomic API.

Use this crate directly if you need:

Low-level CDP access
Custom CDP domain implementations
Direct WebSocket communication with Chrome

License

MIT

viewpoint-cdp 0.4.2