Documentation
¶
Overview ¶
Package cdp is a minimal Chrome DevTools Protocol client.
It speaks raw JSON over a single WebSocket (no type generation, no event registry) — just enough to drive a Scrapfly-hosted Chromium through a small action vocabulary (open / snapshot / click / type / scroll / screenshot / eval). For heavier workloads, prefer chromedp + cdproto.
The client is goroutine-safe for Call. A single reader pump dispatches responses back to the caller via id-keyed channels; events are buffered and delivered through WaitEvent.
Index ¶
- type AXNode
- type AXVal
- type Client
- type Message
- type RPCError
- type Selector
- type Session
- func (s *Session) BackendIDForRef(ref string) (int64, bool)
- func (s *Session) Call(ctx context.Context, method string, params any) (json.RawMessage, error)
- func (s *Session) Click(ctx context.Context, locator string) (map[string]any, error)
- func (s *Session) ClickAndSlide(ctx context.Context, source Selector, opts SlideOptions) (map[string]any, error)
- func (s *Session) ClickAntibot(ctx context.Context, sel Selector, button string, clickCount int) (map[string]any, error)
- func (s *Session) Detach(ctx context.Context) error
- func (s *Session) Eval(ctx context.Context, js string) (any, error)
- func (s *Session) Fill(ctx context.Context, locator, text string) (map[string]any, error)
- func (s *Session) FillAntibot(ctx context.Context, sel Selector, text string, clear bool, wpm float64) (map[string]any, error)
- func (s *Session) Open(ctx context.Context, url string) (map[string]any, error)
- func (s *Session) RenderedContent(ctx context.Context, renderIframes bool) (content, contentType string, err error)
- func (s *Session) Screenshot(ctx context.Context, fullPage bool) ([]byte, error)
- func (s *Session) Scroll(ctx context.Context, direction string, amount float64, locator string) (map[string]any, error)
- func (s *Session) Snapshot(ctx context.Context) ([]AXNode, error)
- func (s *Session) WaitForElement(ctx context.Context, sel Selector, timeoutMs int, visible bool) (map[string]any, error)
- type SlideOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AXNode ¶
type AXNode struct {
Ref string `json:"ref"` // e1, e2, ...
AXNodeID string `json:"ax_node_id"` // raw CDP Accessibility.AXNodeId
Role string `json:"role,omitempty"`
Name string `json:"name,omitempty"`
Value string `json:"value,omitempty"`
Description string `json:"description,omitempty"`
BackendNodeID int64 `json:"backend_node_id,omitempty"`
ChildRefs []string `json:"children,omitempty"`
}
AXNode is a compact view over a single Accessibility node. Fields mirror the CDP `AXNode` shape but only what the model needs to reason.
AXNodeID is the raw CDP accessibility-tree node id. Pass it directly as {type:"axNodeId", query: ax_node_id} to Antibot commands to skip DOM resolution.
type AXVal ¶
type AXVal struct {
Type string `json:"type"`
Value json.RawMessage `json:"value,omitempty"`
}
AXVal mirrors CDP's AXValue — a typed wrapper around a string/number/bool.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a CDP session over a single WebSocket.
func Dial ¶
Dial connects to a CDP WebSocket URL (typically wss://browser.scrapfly.io/ ?api_key=...). Pass a derived ctx for dial cancellation.
func (*Client) Call ¶
func (c *Client) Call(ctx context.Context, method string, params any, sessionID string) (json.RawMessage, error)
Call sends method+params and waits for the matching response.
type Message ¶
type Message struct {
ID int `json:"id,omitempty"`
Method string `json:"method,omitempty"`
Params json.RawMessage `json:"params,omitempty"`
Result json.RawMessage `json:"result,omitempty"`
Error *RPCError `json:"error,omitempty"`
SessionID string `json:"sessionId,omitempty"`
}
Message is the on-wire envelope for both calls and events. Responses carry ID + Result (or Error). Events carry Method + Params (no ID).
type RPCError ¶
type RPCError struct {
Code int `json:"code"`
Message string `json:"message"`
Data string `json:"data,omitempty"`
}
RPCError mirrors the CDP error envelope.
type Selector ¶
type Selector struct {
Type string `json:"type"` // "css" | "xpath" | "axNodeId" | "coord"
Query string `json:"query"`
}
Selector is Antibot's element locator shape: {type, query}.
func CSSSelector ¶
CSSSelector returns a Selector for a CSS query.
func XPathSelector ¶
XPathSelector returns a Selector for an XPath query.
type Session ¶
type Session struct {
Client *Client
TargetID string
SessionID string
// RefTable maps model-facing refs ("e1", "e2", ...) to the backend DOM node
// IDs captured by the most recent Snapshot. Refs are stable only until the
// next Snapshot call.
RefTable map[string]int64
}
Session is a CDP page-level context: browser connection + attached target (tab) session id + a rolling AXTree ref table for action references.
func Attach ¶
Attach opens a fresh page target and attaches a flat session to it, ready for Page/DOM/Input/Accessibility calls. The caller must hold onto the returned Session for subsequent actions.
func (*Session) BackendIDForRef ¶
BackendIDForRef looks up the CDP backendNodeId previously captured for a snapshot ref. Returns (0, false) if the ref is unknown.
func (*Session) Click ¶
Click performs a left-button press+release at the locator's center. Locator is either an AXTree ref ("e3") or a CSS selector (e.g. "button[type=submit]").
CSS selectors go through Antibot.clickOn for human-like timing; refs use the raw Input.dispatchMouseEvent path (no Antibot axNodeId translation yet since our RefTable keys are DOM backend ids, not AX ids).
func (*Session) ClickAndSlide ¶
func (*Session) ClickAntibot ¶
func (s *Session) ClickAntibot(ctx context.Context, sel Selector, button string, clickCount int) (map[string]any, error)
ClickAntibot performs a human-like click on the matched element.
func (*Session) Detach ¶
Detach closes the tab. The browser session itself stays alive (stop it with `scrapfly browser close <session-id>`).
func (*Session) Fill ¶
Fill focuses the locator and inserts text. Locator is an AXTree ref ("e3") or a CSS selector.
CSS selectors use Antibot.fill (click + clear + char-by-char typing with human WPM). Refs fall back to Input.insertText.
func (*Session) FillAntibot ¶
func (s *Session) FillAntibot(ctx context.Context, sel Selector, text string, clear bool, wpm float64) (map[string]any, error)
FillAntibot types into the matched element with human-like WPM timing via the Scrapfly Antibot domain. Clears first when clear=true.
func (*Session) RenderedContent ¶
func (s *Session) RenderedContent(ctx context.Context, renderIframes bool) (content, contentType string, err error)
RenderedContent returns the fully rendered page content — HTML with iframes inlined for text types; base64 bytes for binaries. Default is renderIframe=true.
func (*Session) Screenshot ¶
Screenshot returns the PNG bytes of the viewport.
func (*Session) Scroll ¶
func (s *Session) Scroll(ctx context.Context, direction string, amount float64, locator string) (map[string]any, error)
Scroll dispatches a wheel event; direction "down"/"up"/"left"/"right", amount in CSS pixels. If ref is non-empty, scrolls with that element as anchor; otherwise uses the viewport center.
type SlideOptions ¶
type SlideOptions struct {
Target *Selector
Distance float64 // px, used if Target is nil
VerticalOffset float64
Button string
Overshoot bool
}
ClickAndSlide runs the "slider captcha" primitive: press-and-hold on the source element, slide to target, release. One of {Distance, Target} must be set.
Source Files