devtools

Documentation

Overview

Package devtools provides Go bindings for all the commands, events and types in the Chrome DevTools Protocol (CDP) - from the latest Chromium "tip-of-tree" (tot) definitions (see the details and API documentation in https://chromedevtools.github.io/devtools-protocol/tot, mirrored in https://github.com/ChromeDevTools/devtools-protocol). Each sub-package here corresponds to a single "domain" in the CDP.

Index

• Constants
• func Cancel(ctx context.Context)
• func Close(ctx context.Context)
• func DefaultBrowserFlags() map[string]interface{}
• func NewContext(parent context.Context, opts ...SessionOption) (context.Context, error)
• func Send(ctx context.Context, method string, params json.RawMessage) (chan *Message, error)
• func SubscribeEvent(ctx context.Context, name string) (chan *Message, error)
• func Wait(ctx context.Context)
• type Error
  • func (e *Error) Error() string
• type Message
  • func SendAndWait(ctx context.Context, method string, params json.RawMessage) (*Message, error)
• type SafeString
  • func (t *SafeString) Read() string
  • func (t *SafeString) Write(s string)
• type Session
  • func FromContext(ctx context.Context) (*Session, bool)
• type SessionOption
  • func BrowserFlags(flags map[string]interface{}) SessionOption
  • func BrowserPath(path string) SessionOption
  • func UserDataDir(path string) SessionOption

Examples

• BrowserFlags
• NewContext

Constants

const OutputRootEnv = "CDP_OUTPUT_ROOT"

OutputRootEnv is the name of an optional environment variable to override the default path for CDP output directories (Go's `os.TempDir()` - see https://golang.org/pkg/os/#TempDir)

const TargetTimeout = 1 * time.Minute

TargetTimeout is the maximum amount of time to wait for the browser to start using a new tab, when constructing a new session by calling `NewContext`.

const WebSocketTimeout = 1 * time.Minute

WebSocketTimeout is the maximum amount of time to wait for the browser to report its WebSocket address via STDERR, in order to perform a handshake.

Functions

func Cancel

func Cancel(ctx context.Context)

Cancel cancels the given context, if it was initialized with the `devtools.NewContext` function, and returns immediately.

This will kill the browser forcefully. If you want to close it gracefully, call the `devtools.Close` function instead. Either way, any resources associated with the CDP session will be released when the process ends.

Remember that this does not impact ancestor or parent contexts specified in the `devtools.NewContext` function call, only contexts returned by it. Context cancelation propagates only from ancestors to descendants.

func Close

func Close(ctx context.Context)

Close sends to the browser a command to close itself gracefully, and waits until this is done.

If you want to kill the browser forcefully, call `devtools.Cancel` instead. Either way, any resources associated with the CDP session will be released when the process ends.

func DefaultBrowserFlags

func DefaultBrowserFlags() map[string]interface{}

DefaultBrowserFlags returns a map of default command-line flags for starting the browser.

The caller may modify this map for their particular use-cases. For more information, see https://github.com/GoogleChrome/chrome-launcher/blob/master/docs/chrome-flags-for-tools.md and https://peter.sh/experiments/chromium-command-line-switches.

Examples of a few other common flags to consider:

flags := devtools.DefaultBrowserFlags()
flags["allow-running-insecure-content"] = true
flags["auto-open-devtools-for-tabs"] = true
flags["disable-device-discovery-notifications"] = true
flags["disable-gpu"] = true // https://crbug.com/765284
flags["disable-web-security"] = true
flags["enable-logging"] = "stderr"
flags["ignore-certificate-errors"] = true
flags["js-flags"] = "--random-seed=1157259157" // Initialize V8's RNG with a fixed seed.
flags["log-level"] = "0", // INFO = 0, WARNING = 1, LOG_ERROR = 2, LOG_FATAL = 3.
flags["proxy-server"] = "..."
flags["start-maximized"] = true
flags["use-fake-device-for-media-stream"] = true // Required for the next flag.
flags["use-file-for-fake-video-capture"] = "<path-to-file>" // .y4m or .mjpeg.
flags["user-agent"] = "..."
flags["windows-position"] = "x,y" // "x" and "y" are non-negative integers.
flags["window-size"] = "x,y" // "x" and "y" are positive integers.

func NewContext

func NewContext(parent context.Context, opts ...SessionOption) (context.Context, error)

NewContext constructs a new `devtools.Session`, and returns a copy of the parent context which carries this new session.

If the parent context already carries a CDP session, this function reuses that session's browser and opens a new tab in it. Otherwise, this function creates a new output directory and starts a new browser.

The output directory contains the browser's STDOUT and STDERR, user data directory (unless the caller overrides the browser flag "user-data-dir"), proxy logs, screenshots, etc.

The default path for output directories is Go's `os.TempDir()`, but it can be overridden with an optional environment variable (see `devtools.OutputRootEnv`).

Example

package main

import (
	"context"
	"log"
	"time"

	"github.com/daabr/chrome-vision/pkg/devtools"
)

func main() {
	// Set an idiomatic timeout (or deadline) for the entire session,
	// i.e. the browser will be killed immediately when the time comes.
	ctx1, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	// Start a new browser.
	ctx2, err := devtools.NewContext(ctx1)
	if err != nil {
		log.Fatal(err)
	}

	// Open a new tab in the existing browser.
	ctx3, err := devtools.NewContext(ctx2)
	if err != nil {
		log.Fatal(err)
	}

	// Close the browser.
	devtools.Close(ctx3)
}

func Send

func Send(ctx context.Context, method string, params json.RawMessage) (chan *Message, error)

Send constructs and sends a CDP message to the browser associated with the given context, and returns a channel to receive for the browser's response message. Callers should close the returned channel on their own, although closing unused channels isn't strictly required in Go. Multiple goroutines may call this function simultaneously.

func SubscribeEvent

func SubscribeEvent(ctx context.Context, name string) (chan *Message, error)

SubscribeEvent returns a channel to receive event messages of the given type from the browser associated with the given context.

func Wait

func Wait(ctx context.Context)

Wait waits for the browser associated with the given context (which was started by the `devtools.NewContext` function) to end - no matter how - and for any resources associated with the CDP session to be released.

Types

type Error

type Error struct {
	Code    int64  `json:"code"`
	Message string `json:"message"`
}

Error details passed within a CDP response message.

func (*Error) Error

func (e *Error) Error() string

Error satisfies the Go error interface (https://golang.org/pkg/builtin/#error).

type Message

type Message struct {
	ID        int64           `json:"id,omitempty"`
	SessionID string          `json:"sessionId,omitempty"`
	Method    string          `json:"method,omitempty"`
	Params    json.RawMessage `json:"params,omitempty"`
	Result    json.RawMessage `json:"result,omitempty"`
	Error     *Error          `json:"error,omitempty"`
}

Message is a generic CDP message sent to or received from a browser.

func SendAndWait

func SendAndWait(ctx context.Context, method string, params json.RawMessage) (*Message, error)

SendAndWait constructs and sends a CDP message to the browser associated with the given context, and returns the browser's response message when it arrives. Multiple goroutines may call this function simultaneously.

type SafeString

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

SafeString is a "thread-safe" string: multiple goroutines may read and write it simultaneously.

func (*SafeString) Read

func (t *SafeString) Read() string

func (*SafeString) Write

func (t *SafeString) Write(s string)

type Session

type Session struct {

	// Data directory per browser process. Created under Go's `os.TempDir()`,
	// or the path specified in the environment variable "CDP_OUTPUT_ROOT",
	// if set (see `devtools.OutputRootEnv`). Contains STDOUT and STDERR dumps,
	// logs, user profile data, screenshots, etc. Not deleted automatically!
	OutputDir string
	// User data directory per browser process, instead of the system's
	// default location. Contains data such as history, bookmarks and cookies
	// (https://chromium.googlesource.com/chromium/src/+/master/docs/user_data_dir.md).
	// Created by default under this session's `OutputDir`, unless the caller
	// of the `devtools.NewContext` function overrides this behavior by
	// specifying the `devtools.UserDataDir` session option.
	UserDataDir string

	// IDs for the attached browser tab. Not shared with descendant contexts
	// because they create their own tabs, targets and sessions IDs. See also:
	// https://github.com/aslushnikov/getting-started-with-cdp#targets--sessions.
	TargetID, SessionID *SafeString
	// contains filtered or unexported fields
}

Session contains CDP runtime details, stored in a `context.Context`, and retrievable with the `devtools.FromContext` function.

func FromContext

func FromContext(ctx context.Context) (*Session, bool)

FromContext returns the `devtools.Session` stored in the given `context.Context`, if that context was initialized with the `devtools.NewContext` function.

type SessionOption

type SessionOption = func(*Session)

SessionOption is used for customization in the `devtools.NewContext` function.

See https://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html.

func BrowserFlags

func BrowserFlags(flags map[string]interface{}) SessionOption

BrowserFlags allows the caller of the `devtools.NewContext` function to override this Go package's default browser flags, retrieved with the function `devtools.DefaultBrowserFlags`.

This is useful if you want to customize the browser's behavior.

Example

package main

import (
	"context"
	"log"
	"time"

	"github.com/daabr/chrome-vision/pkg/devtools"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	// Customize the browser command-line flags, before starting it.
	flags := devtools.DefaultBrowserFlags()
	flags["disable-gpu"] = true // https://crbug.com/765284
	flags["window-size"] = "1920,1080"
	delete(flags, "headless")

	ctx, err := devtools.NewContext(ctx, devtools.BrowserFlags(flags))
	if err != nil {
		log.Fatal(err)
	}

	devtools.Close(ctx)
}

func BrowserPath

func BrowserPath(path string) SessionOption

BrowserPath allows the caller of the `devtools.NewContext` function to force this Go package to run the browser from a specific path, instead of looking for the first available OS-specific default path.

This is useful if you want to run a non-default browser or build.

func UserDataDir

func UserDataDir(path string) SessionOption

UserDataDir allows the caller of the `devtools.NewContext` function to customize the browser's default user data directory.

This is useful if you want to customize or monitor the content of the user profile directory.