Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
feat(browser): OSS browser-engine registry/adapter foundation (SKY-12007) (#7511)
LawyZheng6086909ab323
diff --git a/skyvern/webeye/browser_engine.py b/skyvern/webeye/browser_engine.pynew file mode 100644index 000000000..f870d2eca--- /dev/null+++ b/skyvern/webeye/browser_engine.py@@ -0,0 +1,295 @@+"""Per-run browser-engine selection seam (OSS foundation).++Model: one worker image can ship more than one browser-driver engine (stock Playwright always;+Rustwright when the image installs it; a cloud-private engine registered by the cloud layer). The+engine is chosen PER RUN — resolved once at the run's browser-ownership boundary and pinned to that+run's browser resources for their whole lifetime (create -> reconnect). There is no process-global+"active engine": two concurrent runs in one process can pin different engines with no shared mutable+state, so one run's engine (or its exception identity) can never change underneath another.++The same image holds a small registry of engine *specs*; a resolver picks one spec per run and+materializes it into an immutable ``BrowserEngineSelection`` that carries the driver factory, the+driver's public exception identity, and its capability metadata. Constructing a spec never imports+the driver package, so a spec for an engine this image does not ship is inert until a run selects+it; selecting an engine whose package is absent fails closed (``BrowserEngineUnavailable``) rather+than silently falling back.++This is the neutral foundation only. The cloud resolver, the cloud-private engine, and the+deployment/image changes that would let one image and one queue interleave all engines live in+later, stacked changes; the legacy build-time source rewrite (``scripts/patch_browser.sh``) still+ships until that slice lands.+"""++from __future__ import annotations++import importlib.metadata+from dataclasses import dataclass, field+from typing import Awaitable, Callable++from playwright.async_api import Error as _PlaywrightError+from playwright.async_api import Playwright+from playwright.async_api import TimeoutError as _PlaywrightTimeoutError+from playwright.async_api import async_playwright++from skyvern.exceptions import SkyvernException++BrowserDriverStarter = Callable[[], Awaitable[Playwright]]+BrowserEngineErrorLoader = Callable[[], "tuple[type[BaseException], type[BaseException]]"]++STOCK_ENGINE_NAME = "playwright"+RUSTWRIGHT_ENGINE_NAME = "rustwright"++# Rustwright is registered so the adapter contract exists, but it is DENY-ALL (empty capability set)+# and thus not rollout-capable: no production browser source may select it. Paths it would serve+# still carry stock-Playwright ``except`` clauses (e.g. the cloud browser factory), so a Rustwright+# error would bypass those recovery branches; every source stays denied until per-run exception+# normalization and concrete source attribution land. Pinned by a test (SKY-12007 follow-up).+RUSTWRIGHT_ALLOWED_BROWSER_SOURCES: frozenset[str] = frozenset()+++def resolve_engine_version(package_name: str) -> str | None:+ """Best-effort installed version of a driver package, or None when its metadata is absent."""+ try:+ return importlib.metadata.version(package_name)+ except importlib.metadata.PackageNotFoundError:+ return None+++class UnknownBrowserEngine(SkyvernException):+ """Raised when a run selects an engine name that is not in the registry (fail closed)."""++ def __init__(self, name: str, known: tuple[str, ...]) -> None:+ self.name = name+ super().__init__(f"Unknown browser engine {name!r}; registered engines are {sorted(known)!r}")+++class BrowserEngineUnavailable(SkyvernException):+ """Raised when a selected engine's driver package is not installed in this image (fail closed)."""++ def __init__(self, name: str) -> None:+ self.name = name+ super().__init__(f"Browser engine {name!r} is registered but its driver package is not installed")+++class BrowserSourceNotSupportedByEngine(SkyvernException):+ """Raised when a resolved browser source is outside the selected engine's capability set."""++ def __init__(self, *, browser_source: str | None, engine: str) -> None:+ self.browser_source = browser_source+ self.engine = engine+ described = repr(browser_source) if browser_source is not None else "an unattributed browser source (None)"+ super().__init__(f"Browser source {described} is not supported by the selected browser engine {engine!r}")+++@dataclass(frozen=True)+class BrowserEngineMetadata:+ """Attribution + capability for a selected engine.++ ``allowed_browser_sources`` is the fail-closed capability: ``None`` means unrestricted (every+ source allowed — the unchanged default), a set restricts the engine to exactly those neutral+ browser-source strings, and the empty set denies every source (a registered-but-not-rollout-able+ engine).+ """++ name: str+ version: str | None = None+ allowed_browser_sources: frozenset[str] | None = None++ def allows(self, browser_source: str | None) -> bool:+ return self.allowed_browser_sources is None or browser_source in self.allowed_browser_sources+++@dataclass(frozen=True)+class BrowserEngineSelection:+ """A single run's pinned engine. Immutable; created once and carried through the browser+ resource's whole lifetime. Concurrent runs hold distinct selections with no shared state, so+ an engine — and its exception identity — cannot change underneath a live browser resource.+ """++ name: str+ start_driver: BrowserDriverStarter+ error_type: type[BaseException]+ timeout_error_type: type[BaseException]+ metadata: BrowserEngineMetadata+ selection_reason: str++ def is_engine_error(self, exc: BaseException) -> bool:+ """True if ``exc`` is a driver-family error from THIS run's engine (adapter-bound identity)."""+ return isinstance(exc, self.error_type)++ def is_engine_timeout_error(self, exc: BaseException) -> bool:+ return isinstance(exc, self.timeout_error_type)++ def ensure_supports(self, browser_source: str | None) -> None:+ """Fail closed before any provisioning if this engine cannot serve ``browser_source``.++ A restricted engine (non-``None`` ``allowed_browser_sources``, including the deny-all empty+ set) also rejects an unattributed (``None``) source: the fail-closed capability treats an+ unknown source as the most suspicious input, never as implicitly allowed.+ """+ if not self.metadata.allows(browser_source):+ raise BrowserSourceNotSupportedByEngine(browser_source=browser_source, engine=self.name)++ def attribution(self) -> dict[str, str | None]:+ """Structured attribution for logging every run/browser creation — no hidden fallback."""+ return {+ "browser_engine": self.name,+ "browser_engine_version": self.metadata.version,+ "browser_engine_selection_reason": self.selection_reason,+ }+++@dataclass(frozen=True)+class BrowserEngineSpec:+ """Immutable registry entry describing how to materialize one engine.++ Constructing a spec never imports the driver package, so a spec for an engine this image does+ not ship is inert until a run actually selects it. ``select()`` is the only place the driver's+ error classes are imported; an absent package fails closed there.+ """++ name: str+ _start_driver: BrowserDriverStarter+ _load_error_types: BrowserEngineErrorLoader+ allowed_browser_sources: frozenset[str] | None = None++ def is_installed(self) -> bool:+ try:+ self._load_error_types()+ return True+ except ImportError:+ return False++ def select(self, *, selection_reason: str) -> BrowserEngineSelection:+ try:+ error_type, timeout_error_type = self._load_error_types()+ except ImportError as exc:+ raise BrowserEngineUnavailable(self.name) from exc+ return BrowserEngineSelection(+ name=self.name,+ start_driver=self._start_driver,+ error_type=error_type,+ timeout_error_type=timeout_error_type,+ metadata=BrowserEngineMetadata(+ name=self.name,+ version=resolve_engine_version(self.name),+ allowed_browser_sources=self.allowed_browser_sources,+ ),+ selection_reason=selection_reason,+ )+++@dataclass+class BrowserEngineRegistry:+ """Catalog of engine specs, populated once at startup (import time for OSS engines; cloud+ registers its private engine when ``cloud`` is imported). It holds no *active* engine — there is+ none — so a run reads it but nothing here is per-run mutable state. Registration is not+ thread-safe and is expected to complete during single-threaded startup before any run resolves.+ """++ _specs: dict[str, BrowserEngineSpec] = field(default_factory=dict)++ def register(self, spec: BrowserEngineSpec) -> None:+ if spec.name in self._specs:+ raise ValueError(f"Browser engine {spec.name!r} is already registered")+ self._specs[spec.name] = spec++ def get(self, name: str) -> BrowserEngineSpec:+ try:+ return self._specs[name]+ except KeyError:+ raise UnknownBrowserEngine(name, tuple(self._specs)) from None++ def names(self) -> frozenset[str]:+ return frozenset(self._specs)+++async def _start_stock_driver() -> Playwright:+ return await async_playwright().start()+++def _stock_error_types() -> tuple[type[BaseException], type[BaseException]]:+ return _PlaywrightError, _PlaywrightTimeoutError+++async def _start_rustwright_driver() -> Playwright:+ from rustwright.async_api import async_playwright as rustwright_async_playwright++ return await rustwright_async_playwright().start()+++def _rustwright_error_types() -> tuple[type[BaseException], type[BaseException]]:+ from rustwright.async_api import Error as RustwrightError+ from rustwright.async_api import TimeoutError as RustwrightTimeoutError++ return RustwrightError, RustwrightTimeoutError+++PLAYWRIGHT_SPEC = BrowserEngineSpec(+ name=STOCK_ENGINE_NAME,+ _start_driver=_start_stock_driver,+ _load_error_types=_stock_error_types,+ allowed_browser_sources=None,+)++RUSTWRIGHT_SPEC = BrowserEngineSpec(+ name=RUSTWRIGHT_ENGINE_NAME,+ _start_driver=_start_rustwright_driver,+ _load_error_types=_rustwright_error_types,+ allowed_browser_sources=RUSTWRIGHT_ALLOWED_BROWSER_SOURCES,+)++REGISTRY = BrowserEngineRegistry()+REGISTRY.register(PLAYWRIGHT_SPEC)+REGISTRY.register(RUSTWRIGHT_SPEC)+++@dataclass(frozen=True)+class BrowserEngineContext:+ """Per-run inputs a resolver may use to pick and validate an engine. Available at the browser+ resource's creation site; ``browser_source`` is the neutral provider/source string the resolver+ validates against the engine's capability set."""++ organization_id: str | None = None+ workflow_run_id: str | None = None+ workflow_permanent_id: str | None = None+ task_id: str | None = None+ browser_source: str | None = None+++BrowserEngineResolver = Callable[[BrowserEngineContext], Awaitable[BrowserEngineSelection]]+++async def _default_resolver(context: BrowserEngineContext) -> BrowserEngineSelection:+ """OSS default: stock Playwright, unconditionally. Cloud overrides this to read the multivariate+ engine flag (see ``cloud.webeye.browser_engine``)."""+ return REGISTRY.get(STOCK_ENGINE_NAME).select(selection_reason="oss-default-playwright")+++_resolver: BrowserEngineResolver = _default_resolver+++def set_browser_engine_resolver(resolver: BrowserEngineResolver) -> None:+ """Install the per-run resolver strategy (cloud does this at startup). This injects HOW an engine+ is chosen; it does not hold a chosen engine, so it is not process-global active-engine state."""+ global _resolver+ _resolver = resolver+++def reset_browser_engine_resolver() -> None:+ """Restore the OSS default resolver (used by tests)."""+ global _resolver+ _resolver = _default_resolver+++async def resolve_browser_engine(context: BrowserEngineContext) -> BrowserEngineSelection:+ """Resolve an engine for ``context`` via the installed resolver, then validate the run's browser+ source against the engine's capability set (fail closed before any provisioning). Callers that+ own a logical run resolve once and reuse the returned selection for every browser resource in+ that run (see ``RealBrowserManager``), so the engine is pinned per run, not per resource.++ An unrestricted engine (``allowed_browser_sources is None``) may resolve with no attributed+ source; a restricted engine fails closed on an unattributed source rather than passing the gate."""+ selection = await _resolver(context)+ selection.ensure_supports(context.browser_source)+ return selectiondiff --git a/tests/unit/test_browser_engine.py b/tests/unit/test_browser_engine.pynew file mode 100644index 000000000..582032931--- /dev/null+++ b/tests/unit/test_browser_engine.py@@ -0,0 +1,277 @@+"""Per-run browser-engine selection (OSS seam).++These tests stay driver-agnostic: they exercise the registry, per-run selection, capability gate,+and exception-identity classification with fake engine specs, so they hold on an image that ships+only stock Playwright. Cloud-only concerns (the cloud-private engine, the multivariate flag) are+left to the cloud wiring slice that introduces them.+"""++from __future__ import annotations++import asyncio+import dataclasses+import re+from pathlib import Path++import pytest+from playwright.async_api import Error as PlaywrightError+from playwright.async_api import TimeoutError as PlaywrightTimeoutError++from skyvern.webeye import browser_engine+from skyvern.webeye.browser_engine import (+ RUSTWRIGHT_ALLOWED_BROWSER_SOURCES,+ STOCK_ENGINE_NAME,+ BrowserEngineContext,+ BrowserEngineMetadata,+ BrowserEngineRegistry,+ BrowserEngineSelection,+ BrowserEngineSpec,+ BrowserSourceNotSupportedByEngine,+ UnknownBrowserEngine,+ resolve_browser_engine,+)+++class _EngineAError(Exception):+ pass+++class _EngineATimeout(_EngineAError):+ pass+++class _EngineBError(Exception):+ pass+++class _EngineBTimeout(_EngineBError):+ pass+++async def _never_start(): # pragma: no cover - must never be awaited in gate tests+ raise AssertionError("start_driver must not be called when a capability gate rejects the source")+++def _selection(+ name: str,+ error_type: type[BaseException],+ timeout_type: type[BaseException],+ *,+ allowed_sources: frozenset[str] | None = None,+ start=_never_start,+) -> BrowserEngineSelection:+ return BrowserEngineSelection(+ name=name,+ start_driver=start,+ error_type=error_type,+ timeout_error_type=timeout_type,+ metadata=BrowserEngineMetadata(name=name, version="0.0.0", allowed_browser_sources=allowed_sources),+ selection_reason="test",+ )++[email protected](autouse=True)+def _restore_resolver():+ yield+ browser_engine.reset_browser_engine_resolver()+++def test_registry_has_stock_and_rustwright_and_rejects_unknown():+ names = browser_engine.REGISTRY.names()+ assert STOCK_ENGINE_NAME in names+ assert browser_engine.RUSTWRIGHT_ENGINE_NAME in names+ with pytest.raises(UnknownBrowserEngine):+ browser_engine.REGISTRY.get("no-such-engine")+++def test_registry_rejects_duplicate_registration():+ registry = BrowserEngineRegistry()+ spec = BrowserEngineSpec(+ name="dup", _start_driver=_never_start, _load_error_types=lambda: (_EngineAError, _EngineATimeout)+ )+ registry.register(spec)+ with pytest.raises(ValueError):+ registry.register(spec)+++def test_selection_is_frozen():+ sel = _selection("playwright", PlaywrightError, PlaywrightTimeoutError)+ with pytest.raises(dataclasses.FrozenInstanceError):+ sel.name = "mutated" # type: ignore[misc]+++def test_stock_spec_selects_with_playwright_identity():+ sel = browser_engine.REGISTRY.get(STOCK_ENGINE_NAME).select(selection_reason="test")+ assert sel.name == STOCK_ENGINE_NAME+ assert sel.metadata.allowed_browser_sources is None+ assert sel.is_engine_error(PlaywrightError("boom"))+ assert sel.is_engine_timeout_error(PlaywrightTimeoutError("slow"))+ assert not sel.is_engine_error(ValueError("unrelated"))+++def test_rustwright_spec_fails_closed_when_driver_absent():+ # rustwright is not installed in the OSS test image: selecting it must fail closed, never fall back.+ spec = browser_engine.REGISTRY.get(browser_engine.RUSTWRIGHT_ENGINE_NAME)+ assert spec.is_installed() is False+ with pytest.raises(browser_engine.BrowserEngineUnavailable):+ spec.select(selection_reason="explicit-rustwright")+++# Representative neutral source strings (not a canonical source registry — that belongs to the cloud+# wiring slice). Deny-all is source-independent: it must reject whatever source it is handed, so the+# sample only needs to be varied, including the ``None`` unattributed case.+SAMPLE_BROWSER_SOURCES = ("chromium-headful", "chromium-headless", "cdp-connect", None)+++async def test_rustwright_deny_all_fails_before_provisioning_regardless_of_source():+ # Empty capability set = deny-all: the adapter contract exists but no source may select it. Each+ # source must raise BEFORE start_driver (_never_start) runs, so explicit Rustwright cannot start a+ # driver in production today — it stays rollout-incapable until exception normalization lands.+ assert RUSTWRIGHT_ALLOWED_BROWSER_SOURCES == frozenset()+ denied = _selection(+ "rustwright", _EngineAError, _EngineATimeout, allowed_sources=RUSTWRIGHT_ALLOWED_BROWSER_SOURCES+ )+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(denied))+ for source in SAMPLE_BROWSER_SOURCES:+ with pytest.raises(BrowserSourceNotSupportedByEngine):+ await resolve_browser_engine(BrowserEngineContext(browser_source=source))+++async def test_unrestricted_engine_allows_unattributed_source():+ # allowed_browser_sources is None => unrestricted: a run with no attributed source is served.+ unrestricted = _selection("engine-a", _EngineAError, _EngineATimeout, allowed_sources=None, start=_ok_start)+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(unrestricted))+ sel = await resolve_browser_engine(BrowserEngineContext(browser_source=None))+ assert sel.name == "engine-a"+++async def test_restricted_engine_rejects_unattributed_source():+ # A restricted engine must fail closed on an unattributed source, and attribute it honestly (None),+ # not as the misleading string "None".+ restricted = _selection("engine-a", _EngineAError, _EngineATimeout, allowed_sources=frozenset({"cdp-connect"}))+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(restricted))+ with pytest.raises(BrowserSourceNotSupportedByEngine) as excinfo:+ await resolve_browser_engine(BrowserEngineContext(browser_source=None))+ assert excinfo.value.browser_source is None+++async def test_deny_all_rejects_unattributed_source():+ denied = _selection(+ "rustwright", _EngineAError, _EngineATimeout, allowed_sources=RUSTWRIGHT_ALLOWED_BROWSER_SOURCES+ )+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(denied))+ with pytest.raises(BrowserSourceNotSupportedByEngine):+ await resolve_browser_engine(BrowserEngineContext(browser_source=None))+++async def test_restricted_engine_allows_known_source():+ restricted = _selection(+ "engine-a", _EngineAError, _EngineATimeout, allowed_sources=frozenset({"cdp-connect"}), start=_ok_start+ )+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(restricted))+ sel = await resolve_browser_engine(BrowserEngineContext(browser_source="cdp-connect"))+ assert sel.name == "engine-a"+++async def test_restricted_engine_rejects_disallowed_known_source():+ restricted = _selection("engine-a", _EngineAError, _EngineATimeout, allowed_sources=frozenset({"cdp-connect"}))+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(restricted))+ with pytest.raises(BrowserSourceNotSupportedByEngine) as excinfo:+ await resolve_browser_engine(BrowserEngineContext(browser_source="chromium-headful"))+ assert excinfo.value.browser_source == "chromium-headful"+++async def test_rejected_unattributed_source_does_not_start_driver():+ started = False++ async def _spy_start():+ nonlocal started+ started = True+ return object()++ denied = _selection(+ "rustwright",+ _EngineAError,+ _EngineATimeout,+ allowed_sources=RUSTWRIGHT_ALLOWED_BROWSER_SOURCES,+ start=_spy_start,+ )+ browser_engine.set_browser_engine_resolver(lambda ctx: _async(denied))+ with pytest.raises(BrowserSourceNotSupportedByEngine):+ await resolve_browser_engine(BrowserEngineContext(browser_source=None))+ assert started is False+++async def test_default_resolver_is_stock_playwright():+ sel = await resolve_browser_engine(BrowserEngineContext(browser_source="local-browser"))+ assert sel.name == STOCK_ENGINE_NAME+++async def test_unknown_engine_selection_fails_closed():+ browser_engine.set_browser_engine_resolver(+ lambda ctx: browser_engine.REGISTRY.get("phantom").select(selection_reason="x") # type: ignore[return-value]+ )+ with pytest.raises(UnknownBrowserEngine):+ await resolve_browser_engine(BrowserEngineContext(browser_source="local-browser"))+++async def test_concurrent_runs_pin_distinct_engines_without_global_rebinding():+ a = _selection("engine-a", _EngineAError, _EngineATimeout, start=_ok_start)+ b = _selection("engine-b", _EngineBError, _EngineBTimeout, start=_ok_start)++ async def resolver(ctx: BrowserEngineContext) -> BrowserEngineSelection:+ # Simulate interleaving: yield so the two runs overlap inside the resolver.+ await asyncio.sleep(0)+ return a if ctx.workflow_run_id == "run-a" else b++ browser_engine.set_browser_engine_resolver(resolver)+ sel_a, sel_b = await asyncio.gather(+ resolve_browser_engine(BrowserEngineContext(workflow_run_id="run-a", browser_source="local-browser")),+ resolve_browser_engine(BrowserEngineContext(workflow_run_id="run-b", browser_source="local-browser")),+ )+ assert sel_a.name == "engine-a" and sel_b.name == "engine-b"+ # Each run's exception identity is its own and cannot be invalidated by the other run.+ assert sel_a.is_engine_error(_EngineAError()) and not sel_a.is_engine_error(_EngineBError())+ assert sel_b.is_engine_error(_EngineBError()) and not sel_b.is_engine_error(_EngineAError())+++def test_selection_pinning_survives_resolver_change_midrun():+ # Once resolved, a selection object holds its own engine; later resolver swaps cannot mutate it.+ pinned = _selection("engine-a", _EngineAError, _EngineATimeout)+ browser_engine.set_browser_engine_resolver(+ lambda ctx: _async(_selection("engine-b", _EngineBError, _EngineBTimeout))+ )+ assert pinned.name == "engine-a"+ assert pinned.is_engine_error(_EngineAError())+ assert not pinned.is_engine_error(_EngineBError())+++def test_oss_module_only_references_oss_safe_driver_packages():+ # The OSS seam must not name any cloud-private driver package. Assert positively — every+ # driver import in the module targets an OSS-safe package — so this test file never has to+ # embed a cloud-private identifier itself (tests/unit/ is synced to the public repo).+ source = Path(browser_engine.__file__).read_text()+ driver_packages = set(re.findall(r"from (\w+)\.async_api", source))+ assert driver_packages <= {"playwright", "rustwright"}, driver_packages+ assert browser_engine.REGISTRY.names() >= {STOCK_ENGINE_NAME, browser_engine.RUSTWRIGHT_ENGINE_NAME}+++async def _ok_start():+ return object()+++def _async(value):+ async def _coro(ctx=None):+ return value++ return _coro()