cdp

README

Overview

This client is directly based on this doc.

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

It's thread-safe, and context first.

For basic usage, check this file.

For more info, check the unit tests.

Documentation

Overview

Package cdp for application layer communication with browser.

Index

• Variables
• 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 Dialer
• type ErrBadHandshake
  • func (e *ErrBadHandshake) Error() string
• type Error
  • func (e *Error) Error() string
  • func (e Error) Is(target error) bool
• type Event
  • func (e Event) String() string
• type Request
  • func (req Request) String() string
• type Response
  • func (res Response) String() string
• type WebSocket
  • func (ws *WebSocket) Connect(ctx context.Context, wsURL string, header http.Header) error
  • func (ws *WebSocket) Read() ([]byte, error)
  • func (ws *WebSocket) Send(msg []byte) error
• type WebSocketable

Examples

• Client

Variables

var ErrConnClosed = &errConnClosed{}

ErrConnClosed type

var ErrCtxDestroyed = &Error{
	Code:    -32000,
	Message: "Execution context was destroyed.",
}

ErrCtxDestroyed type

var ErrCtxNotFound = &Error{
	Code:    -32000,
	Message: "Cannot find context with specified id",
}

ErrCtxNotFound type

var ErrObjNotFound = &Error{
	Code:    -32000,
	Message: "Could not find object with given id",
}

ErrObjNotFound type

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 Dialer

type Dialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

Dialer interface for WebSocket connection

type ErrBadHandshake

type ErrBadHandshake struct {
	*http.Response
}

ErrBadHandshake type

func (*ErrBadHandshake) Error

func (e *ErrBadHandshake) Error() string

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 stdlib interface

func (Error) Is

func (e Error) Is(target error) bool

Is stdlib 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 WebSocket

type WebSocket struct {
	// Dialer is usually used for proxy
	Dialer Dialer
	// contains filtered or unexported fields
}

WebSocket client for chromium. It only implements a subset of WebSocket protocol. Limitation: https://bugs.chromium.org/p/chromium/issues/detail?id=1069431 Ref: https://tools.ietf.org/html/rfc6455

func (*WebSocket) Connect

func (ws *WebSocket) Connect(ctx context.Context, wsURL string, header http.Header) error

Connect to browser

func (*WebSocket) Read

func (ws *WebSocket) Read() ([]byte, error)

Read a message from browser

func (*WebSocket) Send

func (ws *WebSocket) Send(msg []byte) error

Send a message to browser. Because we use zero-copy design, it will modify the content of the msg. It won't allocate new memory.

type WebSocketable

type WebSocketable interface {
	// Connect to server
	Connect(ctx context.Context, url string, header http.Header) error
	// Send text message only
	Send([]byte) error
	// Read returns text message only
	Read() ([]byte, error)
}

WebSocketable enables you to choose the websocket lib you want to use. Such as you can easily wrap gorilla/websocket and use it as the transport layer.