Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

9.1 KB
Raw Blame

Lite Engine

Deprecated: This document describes the legacy engine model (chrome/lite/auto). The engine has been replaced by the browser provider model. Use browsers.default in your config with providers: chrome, cloak, or ghost-chrome. See terminology for details. None of the code below exists at HEAD: internal/engine (Router, rules, LiteEngine), the server.engine key (now a config validation error) and the X-Engine header were removed. The Gost-DOM static path now lives in internal/browsers/ghostchrome/staticfetch, used by the ghost-chrome provider before it escalates to Chrome.

PinchTab includes a Lite Engine that performs DOM capture — navigate, snapshot, text extraction, click, and type — without requiring Chrome or Chromium. It is powered by Gost-DOM (v0.11.0, MIT), a headless browser written in pure Go.

Issue: #201


Why a Lite Engine?

Chrome is the default execution backend for PinchTab. A real browser session handles JavaScript rendering, bot-detection bypass, screenshots, and PDF generation. For many workloads — static sites, wikis, news articles, APIs — none of these are needed.

Driver Chrome Lite
Memory per instance ~200 MB ~10 MB
Cold-start latency 1–6 seconds <100 ms
JavaScript rendering yes no
Screenshots / PDF yes no
No Chrome installation required no yes

Lite wins at DOM-only workloads (3–4× faster navigate, 3× faster snapshot) and is the right choice for containers, CI pipelines, and edge environments where Chrome is not available.


Architecture

Engine Interface

All engines implement a common interface defined in internal/engine/engine.go:

type Engine interface {
    Name() string
    Navigate(ctx context.Context, url string) (*NavigateResult, error)
    Snapshot(ctx context.Context, filter string) ([]SnapshotNode, error)
    Text(ctx context.Context) (string, error)
    Click(ctx context.Context, ref string) error
    Type(ctx context.Context, ref, text string) error
    Capabilities() []Capability
    Close() error
}

The Chrome engine wraps the existing CDP/chromedp pipeline. LiteEngine in internal/engine/lite.go implements the same interface using Gost-DOM.

Router (Strategy Pattern)

Request → Router → [Rule 1] → [Rule 2] → … → [Fallback Rule] → Engine

Router in internal/engine/router.go evaluates an ordered chain of RouteRule implementations. The first rule that returns a non-Undecided verdict wins. Rules are registered at startup and are hot-swappable via AddRule() / RemoveRule().

No handler, bridge, or config change is needed when adding new routing logic — only a RouteRule implementation and a single router.AddRule(myRule) call.

Built-in Rules

Rule File Behaviour
CapabilityRule rules.go Routes screenshot, pdf, evaluate, cookies → Chrome
ContentHintRule rules.go Routes URLs ending in .html/.htm/.xml/.txt/.md → Lite
DefaultLiteRule rules.go Catch-all: all remaining DOM ops → Lite (used in lite mode)
DefaultChromeRule rules.go Final fallback → Chrome (used in chrome and auto modes)

Three Modes

Mode Behaviour
chrome All requests go through Chrome. Backward-compatible default.
lite DOM operations (navigate, snapshot, text, click, type) use Gost-DOM. Screenshot / PDF / evaluate / cookies fall through to Chrome (501 if Chrome is unavailable).
auto Per-request routing via rules: capability and content-hint rules are evaluated first; unknown URLs fall back to Chrome.

Request Flow (Lite Mode)

POST /navigate   (server.engine=lite)
    │
    ▼
handlers/navigation.go — HandleNavigate()
    │
    ├─ useLite() == true
    │       │
    │       ▼
    │   LiteEngine.Navigate(ctx, url)
    │       ├─ HTTP GET url
    │       ├─ Strip <script> tags (x/net/html tokenizer)
    │       ├─ browser.NewWindowReader(reader)  [Gost-DOM]
    │       └─ return NavigateResult{TabID, URL, Title}
    │
    └─ w.Header().Set("X-Engine", "lite")
       JSON {"tabId": "lp-1", "url": "…", "title": "…"}

Snapshot then traverses the Gost-DOM document tree and maps HTML semantics to accessibility roles (heading, link, button, textbox, …). Text walks the same tree and collapses whitespace runs.


Capability Boundaries

Operation Lite Chrome
Navigate ✅ (HTTP fetch + DOM parse) ✅
Snapshot ✅ ✅
Text extraction ✅ ✅
Click ✅ (DOM event dispatch) ✅
Type ✅ (DOM input events) ✅
Screenshot ❌ → 501 Not Implemented ✅
PDF ❌ → 501 Not Implemented ✅
Evaluate (JS) ❌ → 501 Not Implemented ✅
Cookies ❌ → 501 Not Implemented ✅
JavaScript-rendered SPAs ❌ ✅
Bot-detection bypass ❌ ✅

CapabilityRule ensures screenshot/pdf/evaluate/cookies are always routed to Chrome even in lite mode.


Known Limitations

Limitation Detail
<script> tags Gost-DOM panics on an un-initialized ScriptHost. Scripts are stripped before parse via x/net/html tokenizer.
<a href> click Gost-DOM navigates on anchor click and may encounter scripts. Click() wraps execution in defer recover() and returns an error instead of panicking.
CSS display:none Lite has no CSS engine so hidden elements still appear in the snapshot.
JavaScript-rendered content Only the initial HTML is captured. SPAs (React, Next.js etc.) should use Chrome.
Sites that block HTTP bots Stack Overflow and similar sites return 4xx/5xx to plain HTTP clients. Chrome bypasses this via a real browser session.

Configuration

Set the engine in your config file:

{
  "server": {
    "engine": "lite"
  }
}

The engine field is also forwarded to child bridge instances so every managed instance in a multi-instance deployment uses the same mode.

Response Header

Responses served by the Lite engine include:

X-Engine: lite

This header is present on navigate, snapshot, and text responses when the lite path was taken and is useful for observability and debugging.


Performance

Benchmark across 8 real-world websites (Navigate → Snapshot → Text pipeline, 7 sites where both engines completed successfully):

Metric Lite Chrome Speedup
Navigate total 4,580 ms 17,981 ms 3.9× faster
Snapshot total 1,739 ms 5,155 ms 3.0× faster
Text total 925 ms 500 ms 0.5× (Chrome faster)
Grand total 7,244 ms 23,636 ms 3.3× faster

Chrome is faster at text extraction because it runs Mozilla Readability.js in-browser. Lite performs a raw DOM text walk which is slower for very large pages (e.g. Wikipedia CS: 687 ms vs 130 ms).

When to use each engine

Workload Recommendation
Static sites, wikis, news, blogs Lite — 3–12× faster, no Chrome overhead
JavaScript-rendered SPAs Chrome — Lite captures pre-JS HTML only
Sites that block HTTP clients Chrome — real browser bypasses bot detection
Large-page snapshot / traversal Lite — 3× faster snapshot
Text extraction on large articles Chrome — Readability.js is more accurate
Screenshots, PDF, evaluate, cookies Chrome — not supported in Lite

Code Layout

File Purpose
internal/engine/engine.go Engine interface, Capability constants, Mode enum, NavigateResult / SnapshotNode types
internal/engine/lite.go LiteEngine — HTTP fetch, script stripping, Gost-DOM parse, role mapping
internal/engine/router.go Router — ordered rule chain, AddRule / RemoveRule
internal/engine/rules.go CapabilityRule, ContentHintRule, DefaultLiteRule, DefaultChromeRule
internal/handlers/navigation.go useLite() fast path, X-Engine header
internal/handlers/snapshot.go SnapshotNode → A11yNode conversion for lite path
internal/handlers/text.go Lite text fast path
cmd/pinchtab/cmd_bridge.go Resolves the engine mode string from CLI flag / config (resolveBridgeEngine)
internal/server/bridge.go Wires the engine.Router (engine.NewRouter(mode, lite)) into the handler at startup
internal/config/config_types.go RuntimeConfig.Engine / ServerConfig.Engine fields

Dependency

Package Version License Purpose
github.com/gost-dom/browser v0.11.0 MIT Headless browser: HTML parsing, DOM traversal, event dispatch
github.com/gost-dom/css v0.1.0 MIT CSS selector evaluation
golang.org/x/net existing BSD-3 HTML tokenizer used for script stripping