runner

Documentation

Overview

Package runner provides a Chrome process runner.

Index

• Constants
• Variables
• func DisableGPU(m map[string]interface{}) error
• func ForceKill(m map[string]interface{}) error
• func Headless(m map[string]interface{}) error
• func KillProcessGroup(m map[string]interface{}) error
• func LookChromeNames(additional ...string) string
• func NoDefaultBrowserCheck(m map[string]interface{}) error
• func NoFirstRun(m map[string]interface{}) error
• func NoSandbox(m map[string]interface{}) error
• type ByteCount
• type CommandLineOption
  • func CmdOpt(o func(*exec.Cmd) error) CommandLineOption
  • func ExecPath(path string) CommandLineOption
  • func Flag(name string, value interface{}) CommandLineOption
  • func LimitCoreDump(sz ByteCount) CommandLineOption
  • func LimitMemory(mem ByteCount) CommandLineOption
  • func Path(path string) CommandLineOption
  • func ProcessOpt(o func(*os.Process) error) CommandLineOption
  • func ProxyServer(proxy string) CommandLineOption
  • func RemoteDebuggingPort(port int) CommandLineOption
  • func Rlimit(res int, cur, max uint64) CommandLineOption
  • func URL(urlstr string) CommandLineOption
  • func UserAgent(userAgent string) CommandLineOption
  • func UserDataDir(dir string) CommandLineOption
  • func WindowSize(width, height int) CommandLineOption
• type Error
  • func (err Error) Error() string
• type Runner
  • func New(opts ...CommandLineOption) (*Runner, error)
  • func Run(ctxt context.Context, opts ...CommandLineOption) (*Runner, error)
  • func (r *Runner) ChromePID() int
  • func (r *Runner) Client(opts ...client.Option) *client.Client
  • func (r *Runner) Port() int
  • func (r *Runner) Shutdown(ctxt context.Context, opts ...client.Option) error
  • func (r *Runner) Start(ctxt context.Context, opts ...string) error
  • func (r *Runner) Wait() error

Constants

const (
	// DefaultChromePath is the default path to use for Chrome if the
	// executable is not in $PATH.
	DefaultChromePath = "/usr/bin/google-chrome"
)

const (
	// DefaultUserDataDirPrefix is the default user data directory prefix.
	DefaultUserDataDirPrefix = "chromedp-runner.%d."
)

Variables

var DefaultChromeNames = []string{
	"google-chrome",
	"chromium-browser",
	"chromium",
	"google-chrome-beta",
	"google-chrome-unstable",
}

DefaultChromeNames are the default Chrome executable names to look for in $PATH.

Functions

func DisableGPU

func DisableGPU(m map[string]interface{}) error

DisableGPU is the command line option to disable the GPU process.

func ForceKill

func ForceKill(m map[string]interface{}) error

ForceKill is a Chrome command line option that forces Chrome to be killed when the parent is killed.

Note: sets exec.Cmd.SysProcAttr.Setpgid = true (only for Linux)

func Headless

func Headless(m map[string]interface{}) error

Headless is the command line option to run in headless mode.

func KillProcessGroup

func KillProcessGroup(m map[string]interface{}) error

KillProcessGroup is a Chrome command line option that will instruct the invoked child Chrome process to terminate when the parent process (ie, the Go application) dies.

Note: sets exec.Cmd.SysProcAttr.Setpgid = true and does nothing on Windows.

func LookChromeNames

func LookChromeNames(additional ...string) string

LookChromeNames looks for the platform's DefaultChromeNames and any additional names using exec.LookPath, returning the first encountered location or the platform's DefaultChromePath if no names are found on the path.

func NoDefaultBrowserCheck

func NoDefaultBrowserCheck(m map[string]interface{}) error

NoDefaultBrowserCheck is the Chrome comamnd line option to disable the default browser check.

func NoFirstRun

func NoFirstRun(m map[string]interface{}) error

NoFirstRun is the Chrome comamnd line option to disable the first run dialog.

func NoSandbox

func NoSandbox(m map[string]interface{}) error

NoSandbox is the Chrome comamnd line option to disable the sandbox.

Types

type ByteCount

type ByteCount uint64

ByteCount is a type byte count const.

const (
	Byte     ByteCount = 1
	Kilobyte ByteCount = 1024 * Byte
	Megabyte ByteCount = 1024 * Kilobyte
	Gigabyte ByteCount = 1024 * Megabyte
)

ByteCount values.

type CommandLineOption

type CommandLineOption func(map[string]interface{}) error

CommandLineOption is a runner command line option.

see: http://peter.sh/experiments/chromium-command-line-switches/

func CmdOpt

func CmdOpt(o func(*exec.Cmd) error) CommandLineOption

CmdOpt is a command line option to modify the underlying exec.Cmd prior to the call to exec.Cmd.Start in Run.

func ExecPath

func ExecPath(path string) CommandLineOption

ExecPath is a command line option to set the exec path.

func Flag

func Flag(name string, value interface{}) CommandLineOption

Flag is a generic command line option to pass a name=value flag to Chrome.

func LimitCoreDump

func LimitCoreDump(sz ByteCount) CommandLineOption

LimitCoreDump is a Chrome command line option to set the soft core dump limit for a running Chrome process.

Note: uses Linux prlimit system call, and is invoked after the child process has been started.

func LimitMemory

func LimitMemory(mem ByteCount) CommandLineOption

LimitMemory is a Chrome command line option to set the soft memory limit for a running Chrome process.

Note: uses Linux prlimit system call, and is invoked after the child process has been started.

func Path

func Path(path string) CommandLineOption

Path sets the path to the Chrome executable and sets default run options for Chrome. This will also set the remote debugging port to 9222, and disable the first run / default browser check.

Note: use ExecPath if you do not want to set other options.

func ProcessOpt

func ProcessOpt(o func(*os.Process) error) CommandLineOption

ProcessOpt is a command line option to modify the child os.Process after the call to exec.Cmd.Start in Run.

func ProxyServer

func ProxyServer(proxy string) CommandLineOption

ProxyServer is the command line option to set the outbound proxy server.

func RemoteDebuggingPort

func RemoteDebuggingPort(port int) CommandLineOption

RemoteDebuggingPort is the command line option to set the remote debugging port.

func Rlimit

func Rlimit(res int, cur, max uint64) CommandLineOption

Rlimit is a Chrome command line option to set the soft rlimit value for res on a running Chrome process.

Note: uses Linux prlimit system call, and is invoked after the child process has been started.

see: man 2 prlimit

func URL

func URL(urlstr string) CommandLineOption

URL is the command line option to add a URL to open on process start.

Note: this can be specified multiple times, and each URL will be opened in a new tab.

func UserAgent

func UserAgent(userAgent string) CommandLineOption

UserAgent is the command line option to set the default User-Agent header.

func UserDataDir

func UserDataDir(dir string) CommandLineOption

UserDataDir is the command line option to set the user data dir.

Note: set this option to manually set the profile directory used by Chrome. When this is not set, then a default path will be created in the /tmp directory.

func WindowSize

func WindowSize(width, height int) CommandLineOption

WindowSize is the command line option to set the initial window size.

type Error

type Error string

Error is a runner error.

const (
	// ErrAlreadyStarted is the already started error.
	ErrAlreadyStarted Error = "already started"

	// ErrAlreadyWaiting is the already waiting error.
	ErrAlreadyWaiting Error = "already waiting"

	// ErrInvalidURLs is the invalid url-opts error.
	ErrInvalidURLOpts Error = "invalid url-opts"

	// ErrInvalidCmdOpts is the invalid cmd-opts error.
	ErrInvalidCmdOpts Error = "invalid cmd-opts"

	// ErrInvalidProcessOpts is the invalid process-opts error.
	ErrInvalidProcessOpts Error = "invalid process-opts"

	// ErrInvalidExecPath is the invalid exec-path error.
	ErrInvalidExecPath Error = "invalid exec-path"
)

Error values.

func (Error) Error

func (err Error) Error() string

Error satisfies the error interface.

type Runner

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

Runner holds information about a running Chrome process.

func New

func New(opts ...CommandLineOption) (*Runner, error)

New creates a new Chrome process using the supplied command line options.

func Run

func Run(ctxt context.Context, opts ...CommandLineOption) (*Runner, error)

Run starts a new Chrome process runner, using the provided context and command line options.

func (*Runner) ChromePID

func (r *Runner) ChromePID() int

func (*Runner) Client

func (r *Runner) Client(opts ...client.Option) *client.Client

Client returns a Chrome DevTools Protocol client for the running Chrome process.

func (*Runner) Port

func (r *Runner) Port() int

Port returns the port the process was launched with.

func (*Runner) Shutdown

func (r *Runner) Shutdown(ctxt context.Context, opts ...client.Option) error

Shutdown shuts down the Chrome process.

func (*Runner) Start

func (r *Runner) Start(ctxt context.Context, opts ...string) error

Start starts a Chrome process using the specified context. The Chrome process can be terminated by closing the passed context.

func (*Runner) Wait

func (r *Runner) Wait() error

Wait waits for the previously started Chrome process to terminate, returning any encountered error.