rustwright

README

Rustwright Go alpha binding

This package loads the exact Rustwright C ABI shared library at runtime with purego, so it does not require cgo or loader-path configuration. It binds all 19 rw_* functions from rustwright.h and exposes the Phase 0 Chromium, browser, and page API.

Commands

From the repository root on macOS:

go -C go build -o /tmp/rustwright-go-smoke ./cmd/smoke
/tmp/rustwright-go-smoke --lib target/release/librustwright_capi.dylib
go -C go build -o /tmp/rustwright-go-runner ./cmd/runner
/tmp/rustwright-go-runner --manifest bindings/cases/smoke.json --lib target/release/librustwright_capi.dylib --out /tmp/go-results.json
go -C go test ./...

On Linux, use the .so artifact. smoke defaults to target/release/librustwright_capi.dylib (or .so) when run from the repository root and also honors RUSTWRIGHT_LIB; an explicit --lib overrides the default. The runner requires --manifest, --lib, and --out; optional --cases id1,id2 preserves manifest order.

API sketch

chromium, err := rustwright.Open("target/release/librustwright_capi.dylib")
browser, err := chromium.Launch(rustwright.LaunchOptions{})
defer browser.Close()

page, err := browser.NewPage()
defer page.Close(nil)
_, err = page.Goto("data:text/html,hello", nil)
title, err := page.Title(nil)

LaunchOptions fields are converted from Go camel case to the core's snake_case JSON. ScreenshotOptions uses the Node wire names (fullPage, omitBackground, and so on). A nil timeout emits IEEE-754 NaN at the C boundary, meaning unspecified.

Every failed status is followed immediately, on the same locked OS thread, by copying rw_last_error(). Returned strings and screenshot buffers are copied before their Rust allocators are invoked, and Close closes then frees each opaque handle once.

Evaluation recursively unwraps the core array/object/reference wire tags. Dates become time.Time, URLs become *url.URL, regexps become RegExpValue, errors become JavaScriptError, and non-finite numbers become their Go math values. JavaScript undefined, symbols, and functions have no JSON-compatible Go value and intentionally fall back to nil. Passing nil as the evaluate argument means no argument; use json.RawMessage("null") to pass an explicit JavaScript null.

Documentation

Overview

Package rustwright provides a Go wrapper for the Rustwright C ABI.

Index

• func Bool(v bool) *bool
• func DefaultLibraryPath() string
• type ActionOptions
• type Browser
  • func (b *Browser) Close() error
  • func (b *Browser) NewPage() (*Page, error)
  • func (b *Browser) WSEndpoint() (string, error)
• type Chromium
  • func Open(path string) (*Chromium, error)
  • func (c *Chromium) ExecutablePath() (*string, error)
  • func (c *Chromium) Launch(options LaunchOptions) (*Browser, error)
• type Clip
• type CloseOptions
• type EvaluateOptions
• type GotoOptions
• type JavaScriptError
  • func (e JavaScriptError) Error() string
• type LaunchOptions
• type Page
  • func (p *Page) Click(selector string, options *ActionOptions) error
  • func (p *Page) Close(options *CloseOptions) error
  • func (p *Page) Evaluate(expression string, arg any, options *EvaluateOptions) (any, error)
  • func (p *Page) Fill(selector, value string, options *ActionOptions) error
  • func (p *Page) Goto(rawURL string, options *GotoOptions) (any, error)
  • func (p *Page) Screenshot(options *ScreenshotOptions) ([]byte, error)
  • func (p *Page) TargetID() (string, error)
  • func (p *Page) TextContent(selector string, options *ActionOptions) (*string, error)
  • func (p *Page) Title(options *ActionOptions) (string, error)
• type ProxyOptions
• type RegExpValue
• type ScreenshotOptions

Functions

func Bool

func Bool(v bool) *bool

Bool returns a pointer to v for optional boolean fields.

func DefaultLibraryPath

func DefaultLibraryPath() string

DefaultLibraryPath returns the default path relative to the repository root. Run from the repository root, set RUSTWRIGHT_LIB, or pass a path to Open to choose another exact library.

Types

type ActionOptions

type ActionOptions struct {
	Timeout *float64
}

type Browser

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

func (*Browser) Close

func (b *Browser) Close() error

Close closes Chromium and then frees its opaque handle exactly once.

func (*Browser) NewPage

func (b *Browser) NewPage() (*Page, error)

func (*Browser) WSEndpoint

func (b *Browser) WSEndpoint() (string, error)

type Chromium

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

Chromium is a loaded Rustwright library and its Chromium entrypoint.

func Open

func Open(path string) (*Chromium, error)

Open loads the exact dynamic library at path and binds every rw_* symbol.

func (*Chromium) ExecutablePath

func (c *Chromium) ExecutablePath() (*string, error)

func (*Chromium) Launch

func (c *Chromium) Launch(options LaunchOptions) (*Browser, error)

type Clip

type Clip struct {
	X      float64 `json:"x"`
	Y      float64 `json:"y"`
	Width  float64 `json:"width"`
	Height float64 `json:"height"`
}

type CloseOptions

type CloseOptions struct {
	Timeout         *float64
	RunBeforeUnload bool
}

type EvaluateOptions

type EvaluateOptions struct {
	Timeout *float64
}

type GotoOptions

type GotoOptions struct {
	WaitUntil string
	Timeout   *float64
	Referer   string
}

type JavaScriptError

type JavaScriptError struct {
	Name    string `json:"name,omitempty"`
	Message string `json:"message,omitempty"`
	Stack   string `json:"stack,omitempty"`
}

JavaScriptError is the native representation of an evaluated Error object.

func (JavaScriptError) Error

func (e JavaScriptError) Error() string

type LaunchOptions

type LaunchOptions struct {
	Headless             *bool
	ExecutablePath       string
	Channel              string
	Args                 []string
	IgnoreAllDefaultArgs bool
	IgnoreDefaultArgs    []string
	Timeout              *float64
	UserDataDir          string
	Env                  map[string]string
	ChromiumSandbox      bool
	Proxy                *ProxyOptions
}

LaunchOptions uses idiomatic camel-case Go fields and is normalized to the C core's snake_case JSON wire format.

type Page

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

func (*Page) Click

func (p *Page) Click(selector string, options *ActionOptions) error

func (*Page) Close

func (p *Page) Close(options *CloseOptions) error

Close closes the page and then frees its opaque handle exactly once.

func (*Page) Evaluate

func (p *Page) Evaluate(expression string, arg any, options *EvaluateOptions) (any, error)

Evaluate encodes arg as one JSON value. A nil arg means the optional ABI argument is absent; JavaScript null can be sent with json.RawMessage("null").

func (*Page) Fill

func (p *Page) Fill(selector, value string, options *ActionOptions) error

func (*Page) Goto

func (p *Page) Goto(rawURL string, options *GotoOptions) (any, error)

func (*Page) Screenshot

func (p *Page) Screenshot(options *ScreenshotOptions) ([]byte, error)

func (*Page) TargetID

func (p *Page) TargetID() (string, error)

func (*Page) TextContent

func (p *Page) TextContent(selector string, options *ActionOptions) (*string, error)

func (*Page) Title

func (p *Page) Title(options *ActionOptions) (string, error)

type ProxyOptions

type ProxyOptions struct {
	Server   string `json:"server"`
	Bypass   string `json:"bypass,omitempty"`
	Username string `json:"username,omitempty"`
	Password string `json:"password,omitempty"`
}

type RegExpValue

type RegExpValue struct {
	Pattern string `json:"pattern"`
	Flags   string `json:"flags"`
}

RegExpValue preserves a JavaScript regular expression's source and flags.

type ScreenshotOptions

type ScreenshotOptions struct {
	Path           string   `json:"path,omitempty"`
	FullPage       bool     `json:"fullPage,omitempty"`
	Clip           *Clip    `json:"clip,omitempty"`
	Timeout        *float64 `json:"timeout,omitempty"`
	Type           string   `json:"type,omitempty"`
	Quality        *int     `json:"quality,omitempty"`
	OmitBackground bool     `json:"omitBackground,omitempty"`
}