browser

package
v0.0.0-...-cd3ce49 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

README

Browser Package (pkg/browser)

The pkg/browser package provides an automated, high-level, and resilient controller for headless and kiosk Chromium/Chrome browser instances. Built on the Chrome DevTools Protocol (chromedp), it provides full lifecycle management, DOM navigation, type-safe JavaScript evaluation, mouse interaction, real-time console event streaming, and viewport/full-page screenshot capturing with image processing.


Key Features

  • Lifecycle & Context Safety:
    • Thread-safe initialization (Start), execution, and graceful teardown (Close).
    • Automatic isolation of user profile data (UserDataDir or temporary directories).
    • Explicit propagation of context.Context cancellation and deadlines to prevent leaked goroutines and hanging processes.
  • Navigation & DOM Synchronization:
    • High-level navigation (Navigate) with configurable selector synchronization (NavigateWait).
  • Type-Safe JavaScript Evaluation:
    • Generic evaluation helpers (EvaluateGeneric[T], EvaluateFunction[T]) with automatic JSON deserialization into Go structs and primitive types.
  • Viewport & Full-Page Screenshots:
    • Capture viewport or full scrollable page in PNG or JPEG format.
    • On-the-fly Lanczos downscaling and Gaussian sharpening via imaging.
  • Intelligent Mouse Interaction:
    • Click by CSS selector with visibility polling (WaitVisible).
    • Native coordinate-based clicks with configurable mouse buttons (left, middle, right) and click counts.
  • Real-Time Console Interception:
    • Non-blocking handler registration (SetConsoleHandler) capturing browser console.log, console.warn, console.error, and console.info events.

Architecture & Lifecycle

flowchart TD
    subgraph Host["Host Application"]
        App["Application / REST API"]
        Logger["zLogger (Structured Logs)"]
    end

    subgraph BrowserPkg["pkg/browser Controller"]
        B["Browser Instance (Thread-Safe Mutex)"]
        Nav["Navigation (navigate.go)"]
        Eval["JS Engine (evaluate.go)"]
        Shot["Screenshot & Image Pipeline (screenshot.go)"]
        Click["Interaction Engine (click.go)"]
        Console["Console Streamer (console.go)"]
    end

    subgraph CDP["Chromium / Chrome Process"]
        ExecAlloc["chromedp ExecAllocator"]
        Target["Page Target Context"]
        DevTools["Chrome DevTools Protocol (CDP)"]
    end

    App -->|Config & Logger| B
    B -->|Initializes| ExecAlloc
    ExecAlloc -->|Spawns & Monitors| Target
    Target -->|WebSocket| DevTools
    DevTools -->|Console Events| Console
    App -->|Navigate| Nav
    App -->|Evaluate| Eval
    App -->|Screenshot| Shot
    App -->|Click| Click
    Console -->|Callback| App
    B -->|Logs| Logger

Detailed Operation Flow

sequenceDiagram
    autonumber
    participant App as Application / Caller
    participant Browser as pkg/browser
    participant CDP as Chromium DevTools Protocol

    Note over App, CDP: Browser Initialization
    App->>Browser: New(Config, Logger)
    App->>Browser: Start(ctx)
    Browser->>CDP: Launch Chrome process & attach CDP listener
    CDP-->>Browser: Target ready & listening
    Browser-->>App: nil (Ready)

    Note over App, CDP: Page Navigation
    App->>Browser: Navigate(ctx, "https://example.com")
    Browser->>CDP: Page.navigate & WaitReady("body")
    CDP-->>Browser: Page loaded
    Browser-->>App: nil

    Note over App, CDP: Type-Safe JS Evaluation
    App->>Browser: EvaluateGeneric[int](ctx, "window.innerWidth")
    Browser->>CDP: Runtime.evaluate
    CDP-->>Browser: Result (1920)
    Browser-->>App: 1920, nil

    Note over App, CDP: Screenshot & Processing
    App->>Browser: Screenshot(ctx, ScreenshotOptions)
    Browser->>CDP: Page.captureScreenshot
    CDP-->>Browser: Raw binary payload
    Browser->>Browser: Resize & Apply Gaussian Sharpening
    Browser-->>App: Image bytes, "image/png", nil

    Note over App, CDP: Teardown
    App->>Browser: Close()
    Browser->>CDP: Terminate Chrome process & cancel context
    Browser->>Browser: Remove temporary user-data directory
    Browser-->>App: nil

File Structure

The pkg/browser package is modularized by functional domain:

File Primary Responsibility
config.go Browser configuration (Config) and defaults (DefaultConfig).
browser.go Core Browser struct, lifecycle (Start, Close, IsRunning), and CDP allocator context.
navigate.go Navigation helpers (Navigate, NavigateWait).
screenshot.go Viewport/full-page capture and image scaling/sharpening pipeline.
click.go DOM selector and coordinate-based mouse click dispatchers.
evaluate.go Type-safe generic JavaScript evaluation (EvaluateGeneric, EvaluateFunction).
console.go Asynchronous browser console log stream interception.
browser_test.go Unit and integration tests covering the complete browser lifecycle.

Configuration

type Config struct {
    Headless         bool          // Run Chrome without GUI window (default: true)
    Kiosk            bool          // Run Chrome in full-screen kiosk mode (default: false)
    WindowWidth      int           // Viewport and window width (default: 1920)
    WindowHeight     int           // Viewport and window height (default: 1080)
    UserDataDir      string        // Custom profile dir; empty = temporary directory auto-cleaned on Close
    IgnoreCertErrors bool          // Bypass TLS/SSL certificate validation errors (default: true)
    Timeout          time.Duration // Default timeout per operation (default: 30s)
    ExecPath         string        // Optional custom binary path for Chrome / Chromium
    CustomFlags      []string      // Additional command-line flags passed to Chrome
}

Usage Examples

1. Initialization and Lifecycle
package main

import (
    "context"
    "time"

    "github.com/je4/utils/v2/pkg/zLogger"
    "github.com/je4/wsbrokerdisplay/pkg/browser"
    "github.com/rs/zerolog"
)

func main() {
    var logger zLogger.ZLogger = &zerolog.Nop()

    conf := browser.DefaultConfig()
    conf.Headless = true
    conf.WindowWidth = 1920
    conf.WindowHeight = 1080

    b := browser.New(conf, logger)

    // Capture console output
    b.SetConsoleHandler(func(msg browser.ConsoleMessage) {
        println("[Browser Console]", msg.Level, msg.Message)
    })

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    if err := b.Start(ctx); err != nil {
        panic(err)
    }
    defer b.Close()
}
2. Navigation & JavaScript Evaluation
ctx := context.Background()

// Navigate to target URL
if err := b.Navigate(ctx, "https://example.org"); err != nil {
    panic(err)
}

// Evaluate primitive values
title, err := browser.EvaluateGeneric[string](ctx, b, "document.title")
if err != nil {
    panic(err)
}
println("Title:", title)

// Evaluate complex JSON objects into structs
type PageInfo struct {
    URL        string   `json:"url"`
    Paragraphs int      `json:"paragraphs"`
}

info, err := browser.EvaluateGeneric[PageInfo](ctx, b, `({
    url: window.location.href,
    paragraphs: document.querySelectorAll('p').length
})`)
if err != nil {
    panic(err)
}
println("Page URL:", info.URL, "Paragraph count:", info.Paragraphs)
3. Capturing & Resizing Screenshots
ctx := context.Background()

opts := browser.ScreenshotOptions{
    Format:       "jpeg",
    Quality:      85,
    FullPage:     false,
    Width:        800,  // Downscale to width 800px (aspect ratio preserved if Height is 0)
    SharpenSigma: 0.75, // Apply sharpening for high visual clarity
}

imageBytes, mimeType, err := b.Screenshot(ctx, opts)
if err != nil {
    panic(err)
}
println("Captured image size:", len(imageBytes), "bytes, MIME:", mimeType)
4. Mouse Clicks and Visibility Waiting
ctx := context.Background()

// Click a button by selector with visibility synchronization
err := b.Click(ctx, browser.ClickOptions{
    Selector:    "#submit-btn",
    WaitVisible: true,
    Button:      "left",
})
if err != nil {
    panic(err)
}

// Coordinate-based click (e.g. for canvas or fixed layouts)
err = b.Click(ctx, browser.ClickOptions{
    X:      350.0,
    Y:      120.0,
    Button: "left",
})
if err != nil {
    panic(err)
}

Concurrency & Thread-Safety

  • Browser is fully thread-safe for concurrent read/status calls (IsRunning).
  • Mutex locks and child context derivations ensure that concurrent or sequential actions (Navigate, Screenshot, Click, Evaluate) are serialized safely on the underlying CDP connection without interfering with allocator contexts.
  • Temporary user-data directories are tracked and guaranteed to be deleted on Close() or when re-starting an active instance.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EvaluateFunction

func EvaluateFunction[T any](ctx context.Context, b *Browser, fnName string, args ...any) (T, error)

EvaluateFunction evaluates a JavaScript function by name, automatically serializing arguments to JSON.

func EvaluateGeneric

func EvaluateGeneric[T any](ctx context.Context, b *Browser, script string) (T, error)

EvaluateGeneric is a type-safe generic helper function to evaluate a JavaScript expression and return type T.

Types

type Browser

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

Browser provides an automated headless/display browser controller based on Chrome DevTools Protocol (CDP).

func New

func New(conf Config, logger zLogger.ZLogger) *Browser

New creates a new Browser instance with the provided configuration and logger.

func (*Browser) Click

func (b *Browser) Click(ctx context.Context, opts ClickOptions) error

Click triggers a mouse click on an element located by selector or at specified (X, Y) coordinates.

func (*Browser) Close

func (b *Browser) Close() error

Close terminates the Chrome process, cancels context resources, and cleans up any temporary user-data directory.

func (*Browser) Evaluate

func (b *Browser) Evaluate(ctx context.Context, script string, target any) error

Evaluate runs a JavaScript expression and decodes the result into the target destination pointer.

func (*Browser) GetURL

func (b *Browser) GetURL(ctx context.Context) (string, error)

GetURL retrieves the current primary page URL.

func (*Browser) IsRunning

func (b *Browser) IsRunning() bool

IsRunning reports whether the browser process is currently active and accepting commands.

func (*Browser) Navigate

func (b *Browser) Navigate(ctx context.Context, targetURL string) error

Navigate loads the specified URL into the active browser page and waits for the body DOM ready state.

func (*Browser) NavigateWait

func (b *Browser) NavigateWait(ctx context.Context, targetURL string, waitSelector string) error

NavigateWait loads the specified URL into the active browser page and waits until waitSelector is ready.

func (*Browser) Run

func (b *Browser) Run(ctx context.Context, actions ...chromedp.Action[chromedp.Void]) error

Run executes custom chromedp actions within the browser context.

func (*Browser) Screenshot

func (b *Browser) Screenshot(ctx context.Context, opts ScreenshotOptions) ([]byte, string, error)

Screenshot captures an image of the current page based on the given ScreenshotOptions. Returns the image binary data, the MIME content type ("image/png" or "image/jpeg"), and any error.

func (*Browser) SetConsoleHandler

func (b *Browser) SetConsoleHandler(handler ConsoleHandler)

SetConsoleHandler registers a callback function to receive browser console events in real-time.

func (*Browser) Start

func (b *Browser) Start(ctx context.Context) error

Start launches the Chrome/Chromium browser process or connects to a remote CDP endpoint.

type ClickOptions

type ClickOptions struct {
	// Selector is an optional CSS query selector to locate and click an element.
	Selector string `json:"selector"`
	// WaitVisible instructs the engine to wait until the element is visible before clicking.
	WaitVisible bool `json:"wait_visible"`
	// X specifies the horizontal coordinate in pixels when clicking by coordinates (used when Selector is empty).
	X float64 `json:"x"`
	// Y specifies the vertical coordinate in pixels when clicking by coordinates (used when Selector is empty).
	Y float64 `json:"y"`
	// Button specifies the mouse button: "left" (default), "middle", or "right".
	Button string `json:"button"`
	// ClickCount specifies the number of clicks (default is 1; 2 for double-click).
	ClickCount int `json:"click_count"`
}

ClickOptions specifies target selection, coordinates, and behavior for mouse click operations.

type Config

type Config struct {
	// Address specifies the remote Chrome DevTools Protocol debugging endpoint (<host>:<port> or ws:// / http:// URL).
	// When non-empty, Browser connects to the remote endpoint instead of launching a local Chrome process.
	Address string `toml:"address"`

	// StartURL specifies the initial landing page URL navigated to on browser startup and restart.
	StartURL string `toml:"start_url"`

	// DefaultURL is an alias for StartURL.
	DefaultURL string `toml:"default_url"`

	// Headless determines whether Chrome/Chromium runs without a graphical user interface.
	Headless bool `toml:"headless"`

	// Kiosk enables full-screen kiosk mode for dedicated display environments.
	Kiosk bool `toml:"kiosk"`

	// WindowWidth specifies the initial viewport and window width in pixels.
	WindowWidth int `toml:"window_width"`

	// WindowHeight specifies the initial viewport and window height in pixels.
	WindowHeight int `toml:"window_height"`

	// UserDataDir specifies the profile/user data directory path.
	// If left empty, a temporary directory is created on startup and removed on close.
	UserDataDir string `toml:"user_data_dir"`

	// IgnoreCertErrors allows ignoring TLS certificate validation errors (useful for development/self-signed certs).
	IgnoreCertErrors bool `toml:"ignore_cert_errors"`

	// Timeout specifies the default timeout duration for browser operations.
	Timeout time.Duration `toml:"timeout"`

	// ExecPath allows providing a custom path to the Chrome/Chromium executable binary.
	ExecPath string `toml:"exec_path"`

	// CustomFlags allows passing additional custom command-line flags to the Chrome process.
	CustomFlags []string `toml:"custom_flags"`
}

Config contains configuration options for initializing and running the browser instance.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a Config struct populated with recommended default settings.

func (Config) GetStartURL

func (c Config) GetStartURL() string

GetStartURL returns the configured startup URL, prioritizing StartURL over DefaultURL.

type ConsoleHandler

type ConsoleHandler func(msg ConsoleMessage)

ConsoleHandler is a callback function invoked when a console message is received from the browser.

type ConsoleMessage

type ConsoleMessage struct {
	// Level indicates the severity level of the console entry (e.g. "log", "warn", "error", "info").
	Level string `json:"level"`
	// Message contains the concatenated text arguments of the console call.
	Message string `json:"message"`
	// Timestamp records the time when the console event occurred.
	Timestamp time.Time `json:"timestamp"`
}

ConsoleMessage represents a browser console log event captured from JavaScript execution.

type ScreenshotOptions

type ScreenshotOptions struct {
	// Format specifies the image encoding ("png" or "jpeg"). Defaults to "png" if empty and Quality is 0.
	Format string `json:"format"`
	// Quality defines the compression quality for JPEG output (1-100).
	Quality int `json:"quality"`
	// FullPage determines whether to capture the full scrollable document height or only current viewport.
	FullPage bool `json:"full_page"`
	// Width defines an optional target width for image downscaling/resizing.
	Width int `json:"width"`
	// Height defines an optional target height for image downscaling/resizing.
	Height int `json:"height"`
	// MaxWidth defines an optional maximum bounding width for aspect-ratio preserving fit.
	MaxWidth int `json:"max_width"`
	// MaxHeight defines an optional maximum bounding height for aspect-ratio preserving fit.
	MaxHeight int `json:"max_height"`
	// SharpenSigma defines the Gaussian sharpening sigma factor applied after resizing (e.g. 0.5 - 1.5).
	SharpenSigma float64 `json:"sharpen_sigma"`
}

ScreenshotOptions configures screenshot capture format, dimensions, and image processing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址