How go-rod/rod works
Purpose and public surface
Rod is a Go library for Chrome/Chromium web automation and scraping, layered over the Chrome DevTools Protocol (CDP). Its primary user-facing API is the root package: browser lifecycle in browser.go, page operations in page.go and page_eval.go, DOM selection/actions in element.go and query.go, and cancellation/deadlines in context.go.
Browser lifecycle and attachment
A Browser represents a DevTools-connected browser and creates/manages pages. It can connect to an externally launched browser or work with the launcher subsystem. Browser startup, endpoint discovery, process ownership, and revision/download management are separated under lib/launcher/launcher.go, lib/launcher/browser.go, and lib/launcher/manager.go. This is the boundary between Rod’s API and the local browser process/remote debugging endpoint.
CDP transport and protocol model
lib/cdp/client.go provides the transport-facing CDP client, with WebSocket communication in lib/cdp/websocket.go. lib/proto/ is the typed representation of CDP domains and commands, including lib/proto/page.go, lib/proto/network.go, and lib/proto/runtime.go. Root-level high-level operations ultimately issue these protocol requests and consume CDP events; advanced consumers can use these lower-level layers directly.
Page, frame, and DOM automation
Page is the main automation unit, coordinating navigation, evaluation, waits, events, and frame context. Core behavior is in page.go, states.go, and page_eval.go. DOM-facing abstractions in element.go and query.go resolve selectors and operate across nested iframes and shadow DOMs. The control flow is generally: caller configures a contextual Page → queries/evaluates through CDP Runtime/DOM/Page domains → waits for browser events or state transitions → returns typed page/element results.
Interaction and execution helpers
Input synthesis is exposed at the root through input.go and implemented against CDP through lib/input/keyboard.go and lib/input/mouse.go. JavaScript evaluation and injected helper code are supported by page_eval.go and generated assets in lib/js/js.go. These form the browser-execution boundary: Go values and commands are serialized to CDP; page JavaScript, rendered DOM state, and input events remain in Chromium.
Network interception and observability
hijack.go implements request interception/manipulation over CDP Fetch/Network functionality, enabling request inspection, replacement, or blocking during page execution. Debug/monitoring assets are embedded in lib/assets/assets.go and lib/assets/monitor.html. This keeps network control and diagnostic UI separate from the normal page-automation API.
Runtime, infrastructure, and distribution
The runtime is Go plus a Chromium-family browser reachable via DevTools WebSocket. Browser acquisition and cross-platform launch logic are in lib/launcher/; Docker packaging is defined by lib/docker/Dockerfile and lib/docker/main.go. Generated protocol, JavaScript, device, and asset packages (lib/proto/generate/main.go, lib/js/generate/main.go, lib/devices/generate/main.go) maintain typed/runtime artifacts derived from external browser protocol data.
Main entry points: client.go CDP client · page.go Page operations · browser.go Browser lifecycle · page_eval.go Evaluation & context
Components 17
Rod API
User-facing Go automation surface.
- Browser lifecycle · Connects to DevTools and manages pages.
browser.go - Page operations · Navigation, waits, events, and frame context.
page.go - Evaluation & context · Evaluation plus cancellation and deadline control.
page_eval.go - Element queries · Selector-based DOM actions across frames and shadow DOM.
element.go
Browser Runtime
Browser process lifecycle and DevTools attachment.
- Launcher subsystem · Discovers endpoints, owns processes, and manages browser revisions.
lib/launcher/launcher.go - Chromium browser · Exposes a remote debugging WebSocket endpoint.
CDP Stack
Transport and typed Chrome DevTools Protocol model.
- CDP client · Issues commands and routes protocol events.
lib/cdp/client.go - DevTools WebSocket
lib/cdp/websocket.go - Typed CDP domains · Page, Network, Runtime, and other typed commands/events.
Browser Execution
DOM, JavaScript, input, and network control.
- DOM & frame control · Resolves DOM state through Page, DOM, and Runtime protocol domains.
query.go - Injected JS helpers
lib/js/js.go - Input synthesis · Keyboard and mouse commands sent through CDP.
input.go - Network interception · Inspects, replaces, or blocks requests via Fetch/Network.
hijack.go - Monitor assets · Embedded diagnostic interface.
lib/assets/monitor.html
Tooling & Distribution
Generated artifacts and container packaging.
- Artifact generators · Maintains protocol, JavaScript, device, and asset artifacts.
lib/proto/generate/main.go - Docker packaging · Packages Rod with its browser runtime.
lib/docker/Dockerfile
Other components
- Go caller
Connections 20
- Go caller → Browser lifecycle: creates/connects
- Go caller → Page operations: automates
- Browser lifecycle → Launcher subsystem: launches or attaches via
- Launcher subsystem → Chromium browser: starts/manages
- Browser lifecycle → CDP client: uses
- Page operations → Evaluation & context: evaluates through
- Page operations → Element queries: queries and acts through
- Element queries → CDP client: issues CDP commands
- Evaluation & context → CDP client: issues Runtime/Page commands
- Evaluation & context → Injected JS helpers: injects
- Input synthesis → CDP client: sends input via
- Network interception → CDP client: uses Fetch/Network
- CDP client → Typed CDP domains: serializes typed messages
- CDP client → DevTools WebSocket: communicates over
- DevTools WebSocket → Chromium browser: DevTools endpoint
- Monitor assets → Page operations: observes
- Artifact generators → Typed CDP domains: generates
- Artifact generators → Injected JS helpers: generates
- Docker packaging → Launcher subsystem: packages runtime for
- Docker packaging → Chromium browser: includes