cdp

README

Overview

This client is directly based on doc

You can treat it as a minimal example of how to use the DevTools Protocol, no complex abstraction.

The lib is thread-safe, and context first. The overhead of encoding API will never be the bottleneck as long as you use headless browser.

For a basic example, check this file.

For a detailed example, check this file.

Documentation

Overview

Package cdp for application layer communication with browser.

Index

• type Client
  • func New(websocketURL string) *Client
  • func (cdp *Client) Call(ctx context.Context, sessionID, method string, params interface{}) ([]byte, error)
  • func (cdp *Client) Connect(ctx context.Context) error
  • func (cdp *Client) Event() <-chan *Event
  • func (cdp *Client) Header(header http.Header) *Client
  • func (cdp *Client) Logger(l utils.Logger) *Client
  • func (cdp *Client) MustConnect(ctx context.Context) *Client
  • func (cdp *Client) Websocket(ws Websocketable) *Client
• type DefaultWsClient
  • func NewDefaultWsClient() *DefaultWsClient
  • func (c *DefaultWsClient) Connect(ctx context.Context, url string, header http.Header) (WebsocketableConn, error)
• type DefaultWsConn
  • func (c *DefaultWsConn) Read() (data []byte, err error)
  • func (c *DefaultWsConn) Send(data []byte) error
• type Error
  • func (e *Error) Error() string
• type Event
  • func (e Event) String() string
• type Request
  • func (req Request) String() string
• type Response
  • func (res Response) String() string
• type Websocketable
• type WebsocketableConn

Examples

• Client

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a devtools protocol connection instance.

Example

package main

import (
	"context"
	"fmt"

	"github.com/go-rod/rod/lib/cdp"
	"github.com/go-rod/rod/lib/launcher"
	"github.com/go-rod/rod/lib/proto"
	"github.com/go-rod/rod/lib/utils"
	"github.com/ysmood/gson"
)

func main() {
	ctx := context.Background()

	// launch a browser
	url := launcher.New().MustLaunch()

	// create a controller
	client := cdp.New(url).MustConnect(ctx)

	go func() {
		for range client.Event() {
			// you must consume the events
		}
	}()

	// Such as call this endpoint on the api doc:
	// https://chromedevtools.github.io/devtools-protocol/tot/Page#method-navigate
	// This will create a new tab and navigate to the test.com
	res, err := client.Call(ctx, "", "Target.createTarget", map[string]string{
		"url": "http://test.com",
	})
	utils.E(err)

	fmt.Println(len(gson.New(res).Get("targetId").Str()))

	// close browser by using the proto lib to encode json
	_ = proto.BrowserClose{}.Call(client)

}

Output:

32

func New

func New(websocketURL string) *Client

New creates a cdp connection, all messages from Client.Event must be received or they will block the client.

func (*Client) Call

func (cdp *Client) Call(ctx context.Context, sessionID, method string, params interface{}) ([]byte, error)

Call a method and get its response, if ctx is nil context.Background() will be used

func (*Client) Connect

func (cdp *Client) Connect(ctx context.Context) error

Connect to browser

func (*Client) Event

func (cdp *Client) Event() <-chan *Event

Event returns a channel that will emit browser devtools protocol events. Must be consumed or will block producer.

func (*Client) Header

func (cdp *Client) Header(header http.Header) *Client

Header set the header of the remote control websocket request

func (*Client) Logger

func (cdp *Client) Logger(l utils.Logger) *Client

Logger override for debugging

func (*Client) MustConnect

func (cdp *Client) MustConnect(ctx context.Context) *Client

MustConnect is similar to Connect

func (*Client) Websocket

func (cdp *Client) Websocket(ws Websocketable) *Client

Websocket set the websocket lib to use

type DefaultWsClient

type DefaultWsClient struct {
	WriteBufferSize int
}

DefaultWsClient is the default websocket client

func NewDefaultWsClient

func NewDefaultWsClient() *DefaultWsClient

NewDefaultWsClient instance

func (*DefaultWsClient) Connect

func (c *DefaultWsClient) Connect(ctx context.Context, url string, header http.Header) (WebsocketableConn, error)

Connect interface

type DefaultWsConn

type DefaultWsConn struct {
	// contains filtered or unexported fields
}

DefaultWsConn is the default websocket connection type

func (*DefaultWsConn) Read

func (c *DefaultWsConn) Read() (data []byte, err error)

Read a message

func (*DefaultWsConn) Send

func (c *DefaultWsConn) Send(data []byte) error

Send a message

type Error

type Error struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    string `json:"data"`
}

Error of the Response

func (*Error) Error

func (e *Error) Error() string

Error interface

type Event

type Event struct {
	SessionID string          `json:"sessionId,omitempty"`
	Method    string          `json:"method"`
	Params    json.RawMessage `json:"params,omitempty"`
}

Event from browser

func (Event) String

func (e Event) String() string

type Request

type Request struct {
	ID        int         `json:"id"`
	SessionID string      `json:"sessionId,omitempty"`
	Method    string      `json:"method"`
	Params    interface{} `json:"params,omitempty"`
}

Request to send to browser

func (Request) String

func (req Request) String() string

type Response

type Response struct {
	ID     int             `json:"id"`
	Result json.RawMessage `json:"result,omitempty"`
	Error  *Error          `json:"error,omitempty"`
}

Response from browser

func (Response) String

func (res Response) String() string

type Websocketable

type Websocketable interface {
	// Connect to server
	Connect(ctx context.Context, url string, header http.Header) (WebsocketableConn, error)
}

Websocketable enables you to choose the websocket lib you want to use. By default cdp use github.com/gorilla/websocket

type WebsocketableConn

type WebsocketableConn interface {
	// Send text message only
	Send([]byte) error
	// Read returns text message only
	Read() ([]byte, error)
}

WebsocketableConn represents a connection session