capture

package
v0.0.0-...-39e32c1 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package capture owns explicit, bounded browser acquisition contracts. Production workflow execution remains downstream in Udon and Browserdriver.

Index

Constants

View Source 
const (
	DoctorVersion       = "browsertools.playwright-doctor.v1"
	PlaywrightGoVersion = "v0.6201.0"
	PlaywrightVersion   = "1.62.1"
)
View Source 
const (
	DefaultNavigationTimeout = 15 * time.Second
	DefaultTotalTimeout      = 30 * time.Second
	DefaultMaxRequests       = 128
	DefaultMaxResponseBytes  = int64(16 << 20)
	DefaultMaxEvidenceBytes  = int64(2 << 20)
	DefaultARIADepth         = 12
	MaxAllowedOrigins        = 16
	MaxRequests              = 1024
	MaxResponseBytes         = int64(64 << 20)
	MaxEvidenceBytes         = int64(8 << 20)
	MaxTotalTimeout          = 2 * time.Minute
	MaxNavigationTimeout     = time.Minute
	MaxStructuredDocuments   = 32
	DefaultPrivateRetention  = 24 * time.Hour
	MaxPrivateRetention      = 7 * 24 * time.Hour
)
View Source 
const (
	DefaultRichRetention        = time.Hour
	MaxRichRetention            = 24 * time.Hour
	DefaultMaxRichArtifactBytes = int64(16 << 20)
	MaxRichArtifactBytes        = int64(20 << 20)
	MaxRichTotalArtifactBytes   = int64(19 << 20)
	MaxRichBundleBytes          = int64(20 << 20)
	RichBundleVersion           = "browsertools.private-rich-evidence.v1"
)
View Source 
const ContractPressureVersion = "browsertools.browser-contract-pressure.v1"
View Source 
const (
	// LiveCheckVersion identifies the value-free live check report.
	LiveCheckVersion = "browsertools.live-check.v1"
)
View Source 
const PortabilityVersion = "browsertools.portability-check.v1"

Variables

This section is empty.

Functions

func IsEngineUnavailable 

func IsEngineUnavailable(err error) bool

IsEngineUnavailable identifies a typed installed-engine failure without exposing backend diagnostics in a durable report.

func NewPlaywrightAuthBrowser 

func NewPlaywrightAuthBrowser(driverDirectory string) authassist.Browser

NewPlaywrightAuthBrowser returns the A02 Chromium adapter. The adapter opens a visible, non-persistent context and exposes only the narrow authassist Session interface; it cannot receive credential values or execute clicks.

func NewPlaywrightAuthorBrowser 

func NewPlaywrightAuthorBrowser(driverDirectory string) authorsession.Browser

NewPlaywrightAuthorBrowser returns the A03 headed Chromium backend. One process owns one non-persistent context; no live handle is exported.

func NewPlaywrightRegistrationBrowser 

func NewPlaywrightRegistrationBrowser(driverDirectory string) registrationauthorsession.Browser

NewPlaywrightRegistrationBrowser returns the A08 no-submit headed Chromium backend. It exposes only the narrow registrationauthorsession.Browser interface and never exports a Playwright handle.

Types

type Acquirer 

type Acquirer interface {
	Acquire(context.Context, LiveRequest) (Observation, error)
}

Acquirer performs the browser-specific part of a validated live request. Default tests use a fake; NewPlaywrightAcquirer is the production adapter.

func NewPlaywrightAcquirer 

func NewPlaywrightAcquirer(driverDirectory string) Acquirer

NewPlaywrightAcquirer returns the live Chromium backend. It requires the pinned driver and Chromium to have been installed explicitly beforehand.

func NewPlaywrightEngineAcquirer 

func NewPlaywrightEngineAcquirer(driverDirectory string, engine Engine) Acquirer

NewPlaywrightEngineAcquirer returns a headless, read-only backend for one explicitly selected engine. It never falls back to another engine.

type AcquirerFactory 

type AcquirerFactory func(Engine) Acquirer

AcquirerFactory returns one independent acquirer for the selected engine. The caller must not return a shared browser context.

type Capability 

type Capability struct {
	Name        string                `json:"name"`
	Disposition CapabilityDisposition `json:"disposition"`
	Reason      string                `json:"reason"`
}

Capability is one maintained Browsertools decision about Playwright-Go.

func CapabilityMatrix 

func CapabilityMatrix() []Capability

CapabilityMatrix returns a stable inventory of the upstream surface that is adopted, kept private, deferred, or excluded at the authoring boundary.

type CapabilityDisposition 

type CapabilityDisposition string

CapabilityDisposition records Browsertools' policy for an upstream capability. It does not claim that the capability is installed or already implemented by the current milestone. 

const (
	CapabilityAdopted  CapabilityDisposition = "adopted"
	CapabilityPrivate  CapabilityDisposition = "private_opt_in"
	CapabilityDeferred CapabilityDisposition = "deferred"
	CapabilityExcluded CapabilityDisposition = "excluded"
)

type ContextPressure 

type ContextPressure struct {
	Capability  string `json:"capability"`
	Disposition string `json:"disposition"`
	Browser15   string `json:"browser15"`
	NextStep    string `json:"nextStep"`
}

ContextPressure records how an upstream browser surface presses on the portable browser.1.5 contract. This is Browsertools policy evidence, not an extension to that contract.

func ContractPressure 

func ContractPressure() []ContextPressure

ContractPressure returns the exact E04 inventory. New browser wire behavior must be proposed in UWS rather than smuggled into Browsertools artifacts.

type DoctorReport 

type DoctorReport struct {
	Version             string       `json:"version"`
	Engine              Engine       `json:"engine"`
	PlaywrightGoVersion string       `json:"playwright_go_version"`
	PlaywrightVersion   string       `json:"playwright_version"`
	DriverReady         bool         `json:"driver_ready"`
	BrowserReady        bool         `json:"browser_ready"`
	BrowserExecutable   string       `json:"browser_executable,omitempty"`
	CapabilityPolicy    []Capability `json:"capability_policy"`
	Error               string       `json:"error,omitempty"`
}

DoctorReport is a non-secret installation and capability report.

func Doctor 

func Doctor(ctx context.Context, browserRuntime Runtime, engine Engine) (report DoctorReport, err error)

Doctor verifies the installed driver and browser executable without launching a browser or contacting the network.

func (DoctorReport) UI 

func (report DoctorReport) UI() UIDoctorReport

UI returns a path-free report safe for HTTP storage, ETags, and UI output. DoctorReport remains the full local CLI contract.

type DriverPreflight 

type DriverPreflight struct {
	DriverDirectory string
	NodeExecutable  string
	CLIPath         string
	Version         string
}

DriverPreflight is a read-only identity check for the pinned Playwright Node/CLI driver. It never creates a cache directory, starts Node, invokes an installer, or contacts the network.

func PreflightPlaywrightDriver 

func PreflightPlaywrightDriver(driverDirectory string) (DriverPreflight, error)

PreflightPlaywrightDriver resolves the same installed-driver inputs used by Playwright-Go and verifies the exact pinned playwright-core version.

type Engine 

type Engine string

Engine identifies one Playwright browser engine. 

const (
	EngineChromium Engine = "chromium"
	EngineFirefox  Engine = "firefox"
	EngineWebKit   Engine = "webkit"
)

func ParseEngine 

func ParseEngine(value string) (Engine, error)

ParseEngine validates an engine name without silently selecting a fallback.

type EngineUnavailableError 

type EngineUnavailableError struct {
	Engine Engine
	// contains filtered or unexported fields
}

EngineUnavailableError reports that an explicitly selected installed engine could not be started. Its public text is deliberately value-free; portability reports never copy driver paths or backend error text.

func (*EngineUnavailableError) Error 

func (e *EngineUnavailableError) Error() string

func (*EngineUnavailableError) Unwrap 

func (e *EngineUnavailableError) Unwrap() error

type LiveCheckItem 

type LiveCheckItem struct {
	Kind         ProbeKind          `json:"kind"`
	Path         string             `json:"path"`
	OK           bool               `json:"ok"`
	Matches      int                `json:"matches,omitempty"`
	ExpectedType profile.OutputType `json:"expectedType,omitempty"`
	ObservedType profile.OutputType `json:"observedType,omitempty"`
	Message      string             `json:"message"`
}

LiveCheckItem is one deterministic value-free check.

type LiveCheckRequest 

type LiveCheckRequest struct {
	Profile *profile.Profile
	Actions []string
	Capture LiveRequest
}

LiveCheckRequest binds a validated profile and selected actions to the E03 exact-origin ephemeral acquisition request. Capture.Probes must be empty; Check derives them from the profile.

type LiveCheckResult 

type LiveCheckResult struct {
	Version       string          `json:"version"`
	ProfileDigest string          `json:"profileDigest"`
	CheckedAt     string          `json:"checkedAt"`
	Origin        string          `json:"origin"`
	Actions       []string        `json:"actions"`
	OK            bool            `json:"ok"`
	Checks        []LiveCheckItem `json:"checks"`
}

LiveCheckResult is safe to write as a review artifact: it contains only the selected action names, declared profile paths, type/count facts, and fixed messages. Raw page content remains transient and is discarded.

func Check 

func Check(ctx context.Context, acquirer Acquirer, request LiveCheckRequest) (LiveCheckResult, error)

Check performs read-only observations against the explicitly supplied URL. It never executes the profile's sequence macros, including navigate steps.

type LiveRequest 

type LiveRequest struct {
	URL               string
	AllowedOrigins    []string
	ActionHint        string
	ObservedAt        time.Time
	NavigationTimeout time.Duration
	TotalTimeout      time.Duration
	MaxRequests       int
	MaxResponseBytes  int64
	MaxEvidenceBytes  int64
	ARIADepth         int
	// Probes are populated only by Check. They are a closed, read-only set of
	// locator, wait, and output-shape observations; capture CLI callers cannot
	// provide them.
	Probes []Probe
}

LiveRequest defines one explicit, bounded authoring acquisition. It contains no credentials, headers, cookies, storage state, scripts, or actions.

type LiveResult 

type LiveResult struct {
	Origin       string
	Fixture      playwrightadapter.Fixture
	JSON         []byte
	ProbeResults []ProbeResult
}

LiveResult is a validated private capture ready for KindPrivateRaw cache storage. JSON always ends with one newline.

func Acquire 

func Acquire(ctx context.Context, acquirer Acquirer, request LiveRequest) (LiveResult, error)

Acquire validates a request, applies its total deadline, invokes the browser-specific acquirer, and validates the result before serialization.

type Observation 

type Observation struct {
	FinalURL       string
	ARIASnapshot   string
	StructuredData []json.RawMessage
	Network        playwrightadapter.NetworkSummary
	ProbeResults   []ProbeResult
}

Observation is the minimal private result returned by an acquisition backend before Browsertools validates and serializes it.

type PortabilityEngineResult 

type PortabilityEngineResult struct {
	Engine     Engine            `json:"engine"`
	Status     PortabilityStatus `json:"status"`
	Diagnostic string            `json:"diagnostic,omitempty"`
	Checks     []LiveCheckItem   `json:"checks"`
}

PortabilityEngineResult contains only declared profile paths and value-free count/type facts. Backend errors, page values, and locator rewrites are not part of this artifact.

type PortabilityReport 

type PortabilityReport struct {
	Version          string                    `json:"version"`
	ProfileDigest    string                    `json:"profileDigest"`
	CheckedAt        string                    `json:"checkedAt"`
	Origin           string                    `json:"origin"`
	Actions          []string                  `json:"actions"`
	OK               bool                      `json:"ok"`
	Engines          []PortabilityEngineResult `json:"engines"`
	ContractPressure []ContextPressure         `json:"contractPressure"`
}

PortabilityReport compares the same closed profile-derived probe plan in fresh engine contexts, using Chromium as the explicit baseline.

func ComparePortability 

func ComparePortability(ctx context.Context, factory AcquirerFactory, engines []Engine, request LiveCheckRequest) (PortabilityReport, error)

ComparePortability runs the same read-only live check in Chromium and at least one alternate engine. Every engine is attempted so missing installs become value-free diagnostics rather than silently reducing coverage.

type PortabilityStatus 

type PortabilityStatus string
const (
	PortabilityPassed      PortabilityStatus = "passed"
	PortabilityFailed      PortabilityStatus = "failed"
	PortabilityUnavailable PortabilityStatus = "unavailable"
)

type PrivateArtifact 

type PrivateArtifact struct {
	Kind      PrivateArtifactKind
	MediaType string
	Bytes     []byte
}

type PrivateArtifactKind 

type PrivateArtifactKind string

PrivateArtifactKind is a closed rich-evidence opt-in. These artifacts never become portable profile fields or publication-eligible cache entries. 

const (
	PrivateArtifactScreenshot PrivateArtifactKind = "screenshot"
	PrivateArtifactTrace      PrivateArtifactKind = "trace"
	PrivateArtifactHAR        PrivateArtifactKind = "har"
)

func ParsePrivateArtifactKind 

func ParsePrivateArtifactKind(raw string) (PrivateArtifactKind, error)

ParsePrivateArtifactKind validates a CLI artifact name without fallback.

type Probe 

type Probe struct {
	ID         string
	Kind       ProbeKind
	Locator    *profile.Locator
	Navigation *profile.NavigationWait
	Output     *profile.Output
	OutputKey  string
}

Probe is a private acquisition instruction built only from a validated browser profile. It can count/query existing page state but cannot click, type, submit, upload, evaluate JavaScript, or change storage.

type ProbeKind 

type ProbeKind string

ProbeKind is one member of the closed read-only acquisition probe set. 

const (
	ProbeLocator        ProbeKind = "locator"
	ProbeNavigationWait ProbeKind = "navigation_wait"
	ProbeOutput         ProbeKind = "output"
)

type ProbeResult 

type ProbeResult struct {
	ID           string
	Matches      int
	ObservedType profile.OutputType
	Reached      bool
	FailureCode  string
}

ProbeResult contains shape facts only. It deliberately has no page value, text, URL, selector, or browser error detail.

type RichAcquirer 

type RichAcquirer interface {
	AcquireRich(context.Context, RichBackendRequest) (RichObservation, error)
}

RichAcquirer is separate from Acquirer so a generic E03 backend cannot accidentally begin retaining rich page material.

func NewPlaywrightEngineRichAcquirer 

func NewPlaywrightEngineRichAcquirer(driverDirectory string, engine Engine) RichAcquirer

NewPlaywrightEngineRichAcquirer does not imply that rich cross-engine artifacts are portable. The E04 CLI deliberately exposes Chromium only; this constructor keeps installed-engine integration independently testable.

func NewPlaywrightRichAcquirer 

func NewPlaywrightRichAcquirer(driverDirectory string) RichAcquirer

NewPlaywrightRichAcquirer returns the Chromium-only E04 rich backend.

type RichBackendRequest 

type RichBackendRequest struct {
	Capture          LiveRequest
	Artifacts        []PrivateArtifactKind
	MaxArtifactBytes int64
}

type RichBundleArtifact 

type RichBundleArtifact struct {
	Kind      PrivateArtifactKind `json:"kind"`
	Name      string              `json:"name"`
	MediaType string              `json:"mediaType"`
	SizeBytes int64               `json:"sizeBytes"`
	Digest    string              `json:"digest"`
}

type RichBundleManifest 

type RichBundleManifest struct {
	Version    string               `json:"version"`
	Engine     Engine               `json:"engine"`
	CapturedAt string               `json:"capturedAt"`
	Origin     string               `json:"origin"`
	Artifacts  []RichBundleArtifact `json:"artifacts"`
}

func MarshalRichBundle 

func MarshalRichBundle(result RichResult, engine Engine, capturedAt time.Time) ([]byte, RichBundleManifest, error)

MarshalRichBundle packages one already validated capture as a deterministic private ZIP. A single cache entry makes storage and exact-ID deletion transactional at the artifact-set boundary.

type RichObservation 

type RichObservation struct {
	FinalURL  string
	Network   playwrightadapter.NetworkSummary
	Artifacts []PrivateArtifact
}

type RichRequest 

type RichRequest struct {
	Capture          LiveRequest
	Artifacts        []PrivateArtifactKind
	MaxArtifactBytes int64
}

type RichResult 

type RichResult struct {
	Origin    string
	Artifacts []PrivateArtifact
}

func AcquireRich 

func AcquireRich(ctx context.Context, acquirer RichAcquirer, request RichRequest) (RichResult, error)

AcquireRich performs one bounded, non-interactive, read-only capture and validates all raw artifacts after the ephemeral context has closed.

type Runtime 

type Runtime interface {
	Open(context.Context, Engine) (Session, error)
}

Runtime starts the installed Playwright driver without installing software. Tests use a fake implementation so default verification stays offline.

func NewPlaywrightRuntime 

func NewPlaywrightRuntime(driverDirectory string) Runtime

NewPlaywrightRuntime returns the installed Playwright-Go runtime. An empty driverDirectory uses Playwright-Go's documented cache/environment lookup.

type Session 

type Session interface {
	BrowserExecutable() string
	Close() error
}

Session is the smallest lifecycle needed to inspect an installed engine.

type UIDoctorReport 

type UIDoctorReport struct {
	Version             string       `json:"version"`
	Engine              Engine       `json:"engine"`
	PlaywrightGoVersion string       `json:"playwright_go_version"`
	PlaywrightVersion   string       `json:"playwright_version"`
	DriverReady         bool         `json:"driver_ready"`
	BrowserReady        bool         `json:"browser_ready"`
	CapabilityPolicy    []Capability `json:"capability_policy"`
	Error               string       `json:"error,omitempty"`
}

UIDoctorReport is the separate UI-safe doctor shape. It deliberately omits BrowserExecutable and replaces backend/path-bearing errors with fixed text.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.