Skip to content

Automate browser based workflows with AI

Add the command-interception middleware seam for custom CDP-op implementations (SKY-12535) (#7537)

Aaron Perezeabfab955c4b
diff --git a/skyvern/proxy/__main__.py b/skyvern/proxy/__main__.py
index 6f7743c9e..600f1aa16 100644
--- a/skyvern/proxy/__main__.py
+++ b/skyvern/proxy/__main__.py
@@ -16,7 +16,8 @@ from skyvern.proxy.adapters.memory import (
)
from skyvern.proxy.adapters.websocket_server import CdpProxyServer
from skyvern.proxy.adapters.websocket_upstream import WebSocketUpstreamBrowser
-from skyvern.proxy.core.pipeline import MiddlewarePipeline
+from skyvern.proxy.core.interception_demo import demo_get_version_interceptor
+from skyvern.proxy.core.pipeline import CommandInterceptor, MiddlewarePipeline
from skyvern.proxy.core.policy import EventPolicyEngine
from skyvern.proxy.core.policy_pack import NOISY_EVENT_PACK_V1
from skyvern.proxy.core.screencast import SCREENCAST_PACK_V1, screencast_pipeline
@@ -53,7 +54,17 @@ def build_event_policy(kind: str) -> EventPolicyPort:
raise ValueError(f"unknown CDP_PROXY_EVENT_POLICY: {kind!r}")
-def build_pipeline(kind: str) -> MiddlewarePipeline:
+def build_interceptors(kind: str) -> tuple[CommandInterceptor, ...]:
+ """Config-only interceptor switch (SKY-12535). The default is none: with
+ interception disabled the command path is exactly the pre-seam pass-through."""
+ if kind == "":
+ return ()
+ if kind == "demo-get-version":
+ return (demo_get_version_interceptor,)
+ raise ValueError(f"unknown CDP_PROXY_INTERCEPTORS: {kind!r}")
+
+
+def build_pipeline(kind: str, interceptors_kind: str = "") -> MiddlewarePipeline:
"""The command half of the selected policy, keyed off the same switch.
Only the screencast policy has one: bounding what a client asks Page.startScreencast
@@ -61,10 +72,13 @@ def build_pipeline(kind: str) -> MiddlewarePipeline:
of that one policy reach the proxy through different seams and must be turned on
together. A pack combining screencast with noisy-v1 would have to select both halves
here too — the packs' rules do not overlap, so nothing but this switch prevents it.
+
+ Interceptors are orthogonal to the policy pack and compose into the same pipeline.
"""
+ interceptors = build_interceptors(interceptors_kind)
if kind == "screencast-v1":
- return screencast_pipeline()
- return MiddlewarePipeline()
+ return screencast_pipeline(interceptors)
+ return MiddlewarePipeline(interceptors=interceptors)
def main() -> None:
@@ -72,17 +86,18 @@ def main() -> None:
# injected here in follow-up issues.
upstream_kind = os.environ.get("CDP_PROXY_UPSTREAM", "websocket")
policy_kind = os.environ.get("CDP_PROXY_EVENT_POLICY", "forward-all")
+ interceptors_kind = os.environ.get("CDP_PROXY_INTERCEPTORS", "")
server = CdpProxyServer(
upstream=build_upstream(upstream_kind),
sessions=InMemorySessionRegistry(),
auth=AllowAllAuth(),
metrics=NoOpMetrics(),
event_policy=build_event_policy(policy_kind),
- pipeline=build_pipeline(policy_kind),
+ pipeline=build_pipeline(policy_kind, interceptors_kind),
host=os.environ.get("CDP_PROXY_HOST", "0.0.0.0"),
port=int(os.environ.get("CDP_PROXY_PORT", "9223")),
)
- LOG.info("starting CDP proxy", upstream=upstream_kind, event_policy=policy_kind)
+ LOG.info("starting CDP proxy", upstream=upstream_kind, event_policy=policy_kind, interceptors=interceptors_kind)
asyncio.run(server.serve_forever())
diff --git a/skyvern/proxy/adapters/websocket_server.py b/skyvern/proxy/adapters/websocket_server.py
index 8e6175275..78076c38a 100644
--- a/skyvern/proxy/adapters/websocket_server.py
+++ b/skyvern/proxy/adapters/websocket_server.py
@@ -45,7 +45,14 @@ from skyvern.proxy.core.frames import (
encode_frame,
params_session_id,
)
-from skyvern.proxy.core.pipeline import Direction, MiddlewarePipeline
+from skyvern.proxy.core.pipeline import (
+ INTERCEPTOR_FAILURE_REASON,
+ Direction,
+ InterceptContext,
+ MiddlewarePipeline,
+ SynthesizedResponse,
+ interceptor_failure_response,
+)
from skyvern.proxy.core.policy import Drop, Rewrite
from skyvern.proxy.core.policy_pack import POLICY_PACK_EVENT_METHODS
from skyvern.proxy.core.screencast import (
@@ -326,6 +333,7 @@ _METRIC_COMMAND_LATENCY = "skyvern.cdp_proxy.command_latency_seconds"
_METRIC_FRAMES_DROPPED = "skyvern.cdp_proxy.frames_dropped"
_METRIC_FRAME_DECODE_ERRORS = "skyvern.cdp_proxy.frame_decode_errors"
_METRIC_CLIENT_BACKPRESSURE_CLOSED = "skyvern.cdp_proxy.client_backpressure_closed"
+_METRIC_COMMANDS_INTERCEPTED = "skyvern.cdp_proxy.commands_intercepted"
def _org_tag(session: ProxySession) -> dict[str, str]:
@@ -1284,6 +1292,23 @@ class CdpProxyServer:
# shared is None only on the pinned single-client relay contract, where there
# is no co-tenant to steer another client's session or race its autoAttach.
direction = Direction.CLIENT_TO_UPSTREAM
+ context: InterceptContext | None = None
+ if self._pipeline.has_interceptors:
+
+ async def send_proxy_command(command: CdpCommand) -> None:
+ # The proxy's reserved id lane: the response is consumed by the
+ # upstream reader's PROXY_CLIENT_KEY branch, never sent to a client.
+ upstream_command = remapper.to_upstream_as_proxy(command)
+ try:
+ await connection.send(encode_frame(upstream_command))
+ except BaseException:
+ # ANY post-allocation failure (encode, send, cancellation) must
+ # free the mapping: proxy-lane entries are never evictable by
+ # clients, so a leaked one is a slot lost to co-tenants forever.
+ remapper.discard(upstream_command.id)
+ raise
+
+ context = InterceptContext(send_proxy_command=send_proxy_command)
async for raw in ws:
try:
frame = decode_frame(raw)
@@ -1304,6 +1329,16 @@ class CdpProxyServer:
if shared is not None and not _owns_addressed_sessions(shared, client_key, processed):
self._refuse_foreign_session(shared, session, client_key, processed)
continue
+ if context is not None:
+ # After the ownership refusal (an interceptor never sees a
+ # foreign-session command) and before remapping (a synthesized
+ # response reuses the client's own id; only a forwarded command
+ # ever allocates an upstream one).
+ verdict = await self._intercept_command(processed, session, context)
+ if isinstance(verdict, CdpResponse):
+ await self._deliver_intercept_response(ws, shared, session, client_key, verdict)
+ continue
+ processed = verdict
try:
upstream_command = remapper.to_upstream(client_key, processed)
except RemapperFullError:
@@ -1354,6 +1389,60 @@ class CdpProxyServer:
)
self._deliver_to_channel(shared, channel, refusal, encode_frame(refusal))
+ async def _intercept_command(
+ self, command: CdpCommand, session: ProxySession, context: InterceptContext
+ ) -> CdpCommand | CdpResponse:
+ """Run the interceptor chain over a client command, fail-closed: a raising
+ interceptor (or a contract violation) answers the client with a deterministic
+ internal error and forwards nothing — a policy hook that fails must never
+ fail open into the browser."""
+ try:
+ outcome = await self._pipeline.intercept(command, session, context)
+ except Exception as exc:
+ # Type only — a frame's content must never reach logs.
+ LOG.warning("command interceptor failed", error_type=type(exc).__name__, cdp_method=command.method)
+ self._record_intercepted(session, command, INTERCEPTOR_FAILURE_REASON)
+ return interceptor_failure_response(command)
+ if isinstance(outcome, SynthesizedResponse):
+ self._record_intercepted(session, command, outcome.reason)
+ return outcome.to_response(command)
+ return outcome
+
+ def _record_intercepted(self, session: ProxySession, command: CdpCommand, reason: str) -> None:
+ """The audit trail for a command answered at the proxy (SKY-12538): a counter
+ under bounded labels plus one structured line naming the exact method."""
+ cdp_method, cdp_domain = _cdp_method_tags(command.method)
+ self._metrics.increment(
+ _METRIC_COMMANDS_INTERCEPTED,
+ tags={**_org_tag(session), "reason": reason, "cdp_method": cdp_method, "cdp_domain": cdp_domain},
+ )
+ LOG.info(
+ "CDP command intercepted",
+ session_id=session.session_id,
+ cdp_method=command.method,
+ reason=reason,
+ **_org_tag(session),
+ )
+
+ async def _deliver_intercept_response(
+ self,
+ ws: websockets.ServerConnection,
+ shared: _SharedUpstream | None,
+ session: ProxySession,
+ client_key: str,
+ response: CdpResponse,
+ ) -> None:
+ wire = encode_frame(response)
+ if shared is not None:
+ channel = shared.channels.get(client_key)
+ if channel is not None:
+ # A response is non-droppable in _deliver_to_channel: a client too
+ # slow to take it is closed rather than left hanging on the command.
+ self._deliver_to_channel(shared, channel, response, wire)
+ return
+ await ws.send(wire)
+ self._record_relayed(session, Direction.UPSTREAM_TO_CLIENT, wire)
+
async def _pay_screencast_ack(
self,
upstream: UpstreamConnection | None,
diff --git a/skyvern/proxy/core/interception_demo.py b/skyvern/proxy/core/interception_demo.py
new file mode 100644
index 000000000..bf8d2ff13
--- /dev/null
+++ b/skyvern/proxy/core/interception_demo.py
@@ -0,0 +1,54 @@
+"""Flag-gated demonstrator for the command-interception seam (SKY-12535).
+
+One interceptor proving both halves of interception against a live upstream,
+without any behavior a real client depends on:
+
+- REQUEST synthesis: a proxy-originated Browser.getVersion is sent upstream on the
+ proxy's reserved id lane, so the upstream still sees the traffic and its reply is
+ consumed by the proxy — never delivered to any client, never colliding with a
+ client's in-flight ids.
+- RESPONSE synthesis: the client's own command is answered locally with the proxy's
+ identity (matching the /json/version discovery payload), under the client's own
+ request id and session scope.
+
+Enabled only by `CDP_PROXY_INTERCEPTORS=demo-get-version`; never a default. If the
+proxy-lane send fails (remapper full, upstream gone) the interceptor raises and the
+command fails closed — the deterministic behavior the seam guarantees.
+"""
+
+from __future__ import annotations
+
+from skyvern.proxy.core.frames import CdpCommand
+from skyvern.proxy.core.pipeline import InterceptContext, InterceptOutcome, SynthesizedResponse
+from skyvern.proxy.core.session import ProxySession
+
+GET_VERSION_METHOD = "Browser.getVersion"
+DEMO_INTERCEPT_REASON = "demo_get_version"
+
+# Mirrors the discovery endpoint's identity, so an intercepted response is
+# self-evidently the proxy's rather than a mangled browser reply.
+DEMO_GET_VERSION_RESULT = {
+ "protocolVersion": "1.3",
+ "product": "Skyvern-CDP-Proxy",
+ "revision": "@proxy",
+ "userAgent": "Skyvern-CDP-Proxy",
+ "jsVersion": "0",
+}
+
+
+async def demo_get_version_interceptor(
+ command: CdpCommand, session: ProxySession, context: InterceptContext
+) -> InterceptOutcome:
+ if command.method != GET_VERSION_METHOD:
+ return command
+ # id=0 is a placeholder: to_upstream_as_proxy allocates the real upstream id.
+ await context.send_proxy_command(CdpCommand(id=0, method=GET_VERSION_METHOD))
+ return SynthesizedResponse(result=dict(DEMO_GET_VERSION_RESULT), reason=DEMO_INTERCEPT_REASON)
+
+
+__all__ = [
+ "DEMO_GET_VERSION_RESULT",
+ "DEMO_INTERCEPT_REASON",
+ "GET_VERSION_METHOD",
+ "demo_get_version_interceptor",
+]
diff --git a/skyvern/proxy/core/pipeline.py b/skyvern/proxy/core/pipeline.py
index d58faa886..b64f5f9ba 100644
--- a/skyvern/proxy/core/pipeline.py
+++ b/skyvern/proxy/core/pipeline.py
@@ -1,9 +1,68 @@
+"""The command-side seam of the proxy core: an ordered middleware chain over frames,
+plus command interception (SKY-12535).
+
+Two hooks with different contracts, run in this order on the client→upstream leg:
+
+1. FRAME MIDDLEWARES (`Middleware`) — pure rewrites over any frame in either
+ direction, in registration order; returning None drops the frame. This is the
+ right hook for bounding or normalizing what rides through (see
+ `bound_screencast_middleware`).
+2. COMMAND INTERCEPTORS (`CommandInterceptor`) — client→upstream COMMANDS only,
+ after the middlewares and after the driving adapter's session-ownership refusal
+ (an interceptor never sees a command addressed to a session its client does not
+ own). This is the hook for implementing a CDP operation at the proxy: rewrite
+ it, delegate it, or answer it without the browser.
+
+Writing an interceptor — the composition and correlation rules:
+
+- Interceptors run in registration order; each receives the command as the
+ previous one left it.
+- Return the command (same or rewritten) to continue the chain; the final command
+ is forwarded upstream through request-id remapping exactly as an untouched one.
+- Return a `SynthesizedResponse` to answer the client at the proxy: the chain
+ short-circuits, nothing is forwarded, and the response is delivered carrying the
+ command's own id and sessionId — stamped by `SynthesizedResponse.to_response`,
+ never hand-built, so a synthesis cannot mis-correlate. Because the command never
+ reaches the remapper, no upstream id, latency record, or attach intent exists to
+ leak or leave dangling.
+- There is no drop verb. A silently dropped command hangs its client forever, so
+ blocking a command means synthesizing a deterministic error response (SKY-12538).
+- A rewrite must preserve the request id and the session addressing (the frame's
+ sessionId and a params-addressed sessionId): ownership was checked on what
+ arrived, and the response must reach the id the client is waiting on. Both are
+ enforced — a violation raises `InterceptorContractError`.
+- An interceptor that raises is FAIL-CLOSED: the driving adapter answers the client
+ with `interceptor_failure_response` (a deterministic internal error) and forwards
+ nothing. A policy hook that fails must never fail open into the browser.
+- `InterceptContext.send_proxy_command` synthesizes a REQUEST: a proxy-originated
+ command sent upstream on the proxy's reserved id lane
+ (`RequestIdRemapper.to_upstream_as_proxy`), whose response is consumed by the
+ proxy and can never collide with, or be delivered as, a client's. Fire-and-forget
+ in v1; awaiting the response (full delegation) is a planned extension of this
+ context and needs no interceptor signature change.
+- Upstream→client frames never reach interceptors; responses can be rewritten by a
+ frame middleware, and events belong to `EventPolicyPort`.
+
+A general plugin system is explicitly out of scope: interceptors are proxy-operator
+code selected by deployment configuration (see `skyvern.proxy.__main__`).
+"""
+
from __future__ import annotations
import enum
+import re
from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass
+from typing import Any, Union
-from skyvern.proxy.core.frames import CdpFrame
+from skyvern.proxy.core.frames import (
+ CdpCommand,
+ CdpFrame,
+ CdpResponse,
+ FrameDecodeError,
+ encode_frame,
+ params_session_id,
+)
from skyvern.proxy.core.session import ProxySession
@@ -15,15 +74,112 @@ class Direction(enum.Enum):
Middleware = Callable[[CdpFrame, Direction, ProxySession], Awaitable[CdpFrame | None]]
+class InterceptorContractError(RuntimeError):
+ """An interceptor broke a correlation invariant (changed the request id or the
+ session addressing, or returned something that is neither a command nor a
+ synthesis). Surfaced to the driving adapter, which fails the command closed."""
+
+
+# JSON-RPC internal error: the deterministic verdict for a command whose
+# interceptor failed. Distinct from CDP's own -32001 session-not-found.
+INTERCEPTOR_FAILURE_CODE = -32603
+_INTERCEPTOR_FAILURE_MESSAGE = "CDP command interception failed"
+
+# The audit reason for the fail-closed path; SynthesizedResponse reasons share the
+# same closed-set discipline (they become metric labels, never free-form).
+INTERCEPTOR_FAILURE_REASON = "interceptor_error"
+
+
+# Reasons become metric labels and log fields, so they are constrained to short
+# label-safe identifiers: a reason derived from request data (a URL, an id, error
+# text) cannot pass this, which is what bounds cardinality and rules out content
+# leakage without a central registry.
+_REASON_PATTERN = re.compile(r"[a-z0-9_]{1,64}")
+
+
+@dataclass(frozen=True, slots=True)
+class SynthesizedResponse:
+ """An interceptor's local answer to a command: exactly one of result/error,
+ validated eagerly — through the real frame encoder — so a malformed or
+ non-encodable synthesis fails at construction (inside the interceptor, where
+ the fail-closed rule applies) rather than at delivery, where it would tear the
+ relay down instead of answering the client.
+
+ `reason` is the audit tag for the decision trace — a label-safe identifier,
+ since it becomes a metric label.
+ """
+
+ result: dict[str, Any] | None = None
+ error: dict[str, Any] | None = None
+ reason: str = "intercepted"
+
+ def __post_init__(self) -> None:
+ if (self.result is None) == (self.error is None):
+ raise ValueError("synthesized response must carry exactly one of result or error")
+ try:
+ # The id is a placeholder; to_response stamps the real one. What this
+ # probes is everything else: error shape, and that every value in
+ # result/error (including error.data) survives CDP JSON encoding.
+ encode_frame(CdpResponse(id=0, result=self.result, error=self.error))
+ except FrameDecodeError as exc:
+ raise ValueError(f"synthesized response is not CDP-encodable: {exc}") from exc
+ if not isinstance(self.reason, str) or not _REASON_PATTERN.fullmatch(self.reason):
+ raise ValueError("reason must be a short lowercase identifier ([a-z0-9_]{1,64})")
+
+ def to_response(self, command: CdpCommand) -> CdpResponse:
+ """Stamp the synthesis with the intercepted command's own id and session
+ scope — the correlation guarantee, by construction rather than convention."""
+ return CdpResponse(id=command.id, result=self.result, error=self.error, session_id=command.session_id)
+
+
+@dataclass(frozen=True)
+class InterceptContext:
+ """Per-connection capabilities the driving adapter hands an interceptor.
+
+ `send_proxy_command` sends a proxy-originated command upstream on the reserved
+ proxy id lane; its response is consumed by the proxy and never reaches a
+ client. It raises (`RemapperFullError`, `UpstreamClosedError`) when the send
+ cannot happen — an interceptor that lets that propagate fails closed.
+ """
+
+ send_proxy_command: Callable[[CdpCommand], Awaitable[None]]
+
+
+InterceptOutcome = Union[CdpCommand, SynthesizedResponse]
+CommandInterceptor = Callable[[CdpCommand, ProxySession, InterceptContext], Awaitable[InterceptOutcome]]
+
+
+def interceptor_failure_response(command: CdpCommand) -> CdpResponse:
+ """The deterministic fail-closed answer for a command whose interceptor raised."""
+ return CdpResponse(
+ id=command.id,
+ error={"code": INTERCEPTOR_FAILURE_CODE, "message": _INTERCEPTOR_FAILURE_MESSAGE},
+ session_id=command.session_id,
+ )
+
+
class MiddlewarePipeline:
- """Runs each frame through an ordered middleware chain; returning None drops the frame."""
+ """Runs each frame through an ordered middleware chain; returning None drops the
+ frame. Command interceptors are a separate, stricter chain — see the module
+ docstring for the ordering and composition rules."""
- def __init__(self, middlewares: Iterable[Middleware] | None = None) -> None:
+ def __init__(
+ self,
+ middlewares: Iterable[Middleware] | None = None,
+ interceptors: Iterable[CommandInterceptor] | None = None,
+ ) -> None:
self._middlewares = list(middlewares or ())
+ self._interceptors = list(interceptors or ())
def add(self, middleware: Middleware) -> None:
self._middlewares.append(middleware)
+ @property
+ def has_interceptors(self) -> bool:
+ """False means the adapter's pass-through path runs with zero interception
+ overhead — disabled is byte-identical to the pipeline before the seam."""
+ return bool(self._interceptors)
+
async def process(self, frame: CdpFrame, direction: Direction, session: ProxySession) -> CdpFrame | None:
current: CdpFrame | None = frame
for middleware in self._middlewares:
@@ -31,3 +187,29 @@ class MiddlewarePipeline:
return None
current = await middleware(current, direction, session)
return current
+
+ async def intercept(
+ self, command: CdpCommand, session: ProxySession, context: InterceptContext
+ ) -> InterceptOutcome:
+ """Run a client→upstream command through the interceptor chain.
+
+ Returns the final command to forward, or the first SynthesizedResponse
+ (short-circuit). Contract violations raise InterceptorContractError; an
+ interceptor's own exception propagates — the caller fails the command
+ closed either way (`interceptor_failure_response`).
+ """
+ current = command
+ for interceptor in self._interceptors:
+ outcome = await interceptor(current, session, context)
+ if isinstance(outcome, SynthesizedResponse):
+ return outcome
+ if not isinstance(outcome, CdpCommand):
+ raise InterceptorContractError("interceptor must return a command or a synthesized response")
+ if (
+ outcome.id != command.id
+ or outcome.session_id != command.session_id
+ or params_session_id(outcome) != params_session_id(command)
+ ):
+ raise InterceptorContractError("interceptor must preserve the request id and session addressing")
+ current = outcome
+ return current
diff --git a/skyvern/proxy/core/screencast.py b/skyvern/proxy/core/screencast.py
index 585ac5e81..70935c3f7 100644
--- a/skyvern/proxy/core/screencast.py
+++ b/skyvern/proxy/core/screencast.py
@@ -25,8 +25,10 @@ proxy. Cloud live-view is VNC + Page.captureScreenshot and never touches this.
from __future__ import annotations
+from collections.abc import Iterable
+
from skyvern.proxy.core.frames import CdpCommand, CdpEvent, CdpFrame
-from skyvern.proxy.core.pipeline import Direction, MiddlewarePipeline
+from skyvern.proxy.core.pipeline import CommandInterceptor, Direction, MiddlewarePipeline
from skyvern.proxy.core.policy import EventPolicyConfig, RateRule
from skyvern.proxy.core.session import ProxySession
@@ -176,7 +178,7 @@ async def bound_screencast_middleware(frame: CdpFrame, direction: Direction, ses
return frame
-def screencast_pipeline() -> MiddlewarePipeline:
+def screencast_pipeline(interceptors: Iterable[CommandInterceptor] | None = None) -> MiddlewarePipeline:
"""The command half of the screencast policy.
Param bounding is a command rewrite, and EventPolicyPort decides events only, so the
@@ -184,7 +186,7 @@ def screencast_pipeline() -> MiddlewarePipeline:
turn both on together (see `skyvern.proxy.__main__`). Rewriting commands in general is
the interception seam's job (SKY-12535); this is the one rule that cannot wait for it.
"""
- return MiddlewarePipeline([bound_screencast_middleware])
+ return MiddlewarePipeline([bound_screencast_middleware], interceptors)
__all__ = [
diff --git a/tests/unit/proxy/test_interception.py b/tests/unit/proxy/test_interception.py
new file mode 100644
index 000000000..4f5b19471
--- /dev/null
+++ b/tests/unit/proxy/test_interception.py
@@ -0,0 +1,332 @@
+"""Command interception through the live relay (SKY-12535).
+
+The seam's promises, proven against the shared-connection server: disabled means
+byte-identical pass-through; a synthesized response answers the client under its
+own request id with nothing forwarded; a proxy-synthesized request rides the
+reserved id lane and its reply never reaches a client; rewrites forward through
+remapping; a failing interceptor fails the command closed; and an interceptor
+never sees a command the ownership check refuses.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from skyvern.proxy.__main__ import build_interceptors, build_pipeline
+from skyvern.proxy.adapters.memory import AllowAllAuth, ForwardAllEventPolicy, InMemorySessionRegistry, NoOpMetrics
+from skyvern.proxy.adapters.websocket_server import CdpProxyServer
+from skyvern.proxy.core.frames import CdpCommand, CdpResponse, decode_frame
+from skyvern.proxy.core.interception_demo import (
+ DEMO_GET_VERSION_RESULT,
+ DEMO_INTERCEPT_REASON,
+ GET_VERSION_METHOD,
+ demo_get_version_interceptor,
+)
+from skyvern.proxy.core.pipeline import (
+ INTERCEPTOR_FAILURE_CODE,
+ InterceptContext,
+ MiddlewarePipeline,
+ SynthesizedResponse,
+)
+from skyvern.proxy.core.session import ProxySession, ResolvedSession
+from tests.unit.proxy.test_metrics_contract import _RecordingMetrics
+from tests.unit.proxy.test_shared_connection import (
+ UPSTREAM_URL,
+ _command,
+ _ControllableUpstream,
+ _ScriptClient,
+ _SharedBrowser,
+ _until,
+)
+
+
+def _intercept_server(
+ browser: object, pipeline: MiddlewarePipeline | None = None, metrics: object | None = None
+) -> CdpProxyServer:
+ sessions = InMemorySessionRegistry()
+ sessions.put(ResolvedSession(session_id="s1", upstream_adapter="memory", upstream_ws_url=UPSTREAM_URL))
+ return CdpProxyServer(
+ upstream=browser, # type: ignore[arg-type]
+ sessions=sessions,
+ auth=AllowAllAuth(),
+ metrics=metrics or NoOpMetrics(), # type: ignore[arg-type]
+ event_policy=ForwardAllEventPolicy(),
+ pipeline=pipeline,
+ )
+
+
+def _demo_pipeline() -> MiddlewarePipeline:
+ return MiddlewarePipeline(interceptors=[demo_get_version_interceptor])
+
+
+def _upstream_methods(connection: _ControllableUpstream) -> list[str]:
+ return [f.method for f in map(decode_frame, connection.sent) if isinstance(f, CdpCommand)]
+
+
+def _responses(client: _ScriptClient) -> list[CdpResponse]:
+ return [f for f in map(decode_frame, client.sent) if isinstance(f, CdpResponse)]
+
+
+def test_build_interceptors_is_a_closed_switch() -> None:
+ assert build_interceptors("") == ()
+ assert build_interceptors("demo-get-version") == (demo_get_version_interceptor,)
+ assert build_pipeline("forward-all").has_interceptors is False
+ assert build_pipeline("forward-all", "demo-get-version").has_interceptors is True
+ assert build_pipeline("screencast-v1", "demo-get-version").has_interceptors is True
+ with pytest.raises(ValueError):
+ build_interceptors("bogus")
+
+
+async def test_demo_interceptor_passes_other_methods_untouched() -> None:
+ sent: list[CdpCommand] = []
+
+ async def send_proxy_command(command: CdpCommand) -> None:
+ sent.append(command)
+
+ command = CdpCommand(id=1, method="Page.enable")
+ session = ProxySession(session_id="s1", upstream_ws_url=UPSTREAM_URL)
+
+ outcome = await demo_get_version_interceptor(command, session, InterceptContext(send_proxy_command))
+
+ assert outcome is command
+ assert sent == []
+
+
+async def test_disabled_interception_forwards_get_version_upstream() -> None:
+ connection = _ControllableUpstream()
+ server = _intercept_server(_SharedBrowser(connection))
+ client = _ScriptClient([_command(1, GET_VERSION_METHOD)])
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: client.echoes())
+
+ # Pass-through unchanged: the browser answered, the proxy synthesized nothing.
+ assert client.echoes() == {GET_VERSION_METHOD}
+ assert _upstream_methods(connection) == [GET_VERSION_METHOD]
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
+
+
+async def test_demo_synthesizes_the_response_under_the_clients_own_id() -> None:
+ connection = _ControllableUpstream()
+ metrics = _RecordingMetrics()
+ server = _intercept_server(_SharedBrowser(connection), _demo_pipeline(), metrics)
+ client = _ScriptClient([_command(5, GET_VERSION_METHOD)])
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: client.sent)
+
+ # RESPONSE synthesis: answered locally, under the client's own id.
+ [response] = _responses(client)
+ assert response.id == 5
+ assert response.result == DEMO_GET_VERSION_RESULT
+ # REQUEST synthesis: the upstream still saw one getVersion — the proxy's own,
+ # whose echo reply was consumed on the proxy lane and never sent to the client.
+ assert _upstream_methods(connection) == [GET_VERSION_METHOD]
+ assert len(client.sent) == 1
+ # Remapping is unbroken: once the proxy-lane reply lands, no mapping dangles.
+ shared = server._shared_upstreams[UPSTREAM_URL]
+ assert await _until(lambda: shared.remapper.pending_count == 0)
+ # The audit trail names the interception.
+ reasons = [tags.get("reason") for op, name, _, tags in metrics.calls if name.endswith("commands_intercepted")]
+ assert reasons == [DEMO_INTERCEPT_REASON]
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
+
+
+async def test_interception_does_not_disturb_a_co_tenants_remapping() -> None:
+ connection = _ControllableUpstream()
+ server = _intercept_server(_SharedBrowser(connection), _demo_pipeline())
+ # Both clients use id 1: one is answered by the proxy, one by the browser.
+ client_a = _ScriptClient([_command(1, GET_VERSION_METHOD)])
+ client_b = _ScriptClient([_command(1, "Page.enable")])
+
+ task_a = asyncio.create_task(server._handle_client(client_a)) # type: ignore[arg-type]
+ task_b = asyncio.create_task(server._handle_client(client_b)) # type: ignore[arg-type]
+ assert await _until(lambda: client_a.sent and client_b.echoes())
+
+ [synthesized] = _responses(client_a)
+ assert synthesized.id == 1
+ assert synthesized.result == DEMO_GET_VERSION_RESULT
+ assert client_b.echoes() == {"Page.enable"}
+ assert all(decode_frame(wire).id == 1 for wire in client_b.sent)
+
+ client_a.release()
+ client_b.release()
+ await asyncio.wait_for(asyncio.gather(task_a, task_b), timeout=5)
+
+
+async def test_a_rewriting_interceptor_forwards_through_remapping() -> None:
+ async def bound_params(command: CdpCommand, session: ProxySession, context: InterceptContext) -> CdpCommand:
+ if command.method != "Page.navigate":
+ return command
+ return CdpCommand(id=command.id, method=command.method, params={**(command.params or {}), "bounded": True})
+
+ connection = _ControllableUpstream()
+ server = _intercept_server(_SharedBrowser(connection), MiddlewarePipeline(interceptors=[bound_params]))
+ client = _ScriptClient([_command(3, "Page.navigate", {"url": "about:blank"})])
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: client.echoes())
+
+ [forwarded] = [f for f in map(decode_frame, connection.sent) if isinstance(f, CdpCommand)]
+ assert forwarded.params == {"url": "about:blank", "bounded": True}
+ [response] = _responses(client)
+ assert response.id == 3
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
+
+
+async def test_a_failing_interceptor_fails_the_command_closed() -> None:
+ async def broken(command: CdpCommand, session: ProxySession, context: InterceptContext) -> CdpCommand:
+ raise RuntimeError("interceptor bug")
+
+ connection = _ControllableUpstream()
+ metrics = _RecordingMetrics()
+ server = _intercept_server(_SharedBrowser(connection), MiddlewarePipeline(interceptors=[broken]), metrics)
+ client = _ScriptClient([_command(4, "Page.enable")])
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: client.sent)
+
+ # Deterministic error to the client, nothing forwarded upstream.
+ [response] = _responses(client)
+ assert response.id == 4
+ assert response.error is not None
+ assert response.error["code"] == INTERCEPTOR_FAILURE_CODE
+ assert connection.sent == []
+ reasons = [tags.get("reason") for op, name, _, tags in metrics.calls if name.endswith("commands_intercepted")]
+ assert reasons == ["interceptor_error"]
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
+
+
+async def test_an_invalid_synthesis_fails_closed_without_killing_the_relay() -> None:
+ async def bad_synthesis(command: CdpCommand, session: ProxySession, context: InterceptContext) -> object:
+ if command.method == "Page.enable":
+ return SynthesizedResponse(result={"blob": b"not-json"})
+ return command
+
+ connection = _ControllableUpstream()
+ server = _intercept_server(_SharedBrowser(connection), MiddlewarePipeline(interceptors=[bad_synthesis]))
+ client = _ScriptClient([_command(1, "Page.enable"), _command(2, "Runtime.enable")])
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: len(client.sent) >= 2)
+
+ # The bad synthesis became the deterministic error, and the relay survived to
+ # serve the next command normally.
+ [failure] = [r for r in _responses(client) if r.error is not None]
+ assert failure.id == 1
+ assert failure.error["code"] == INTERCEPTOR_FAILURE_CODE
+ assert client.echoes() == {"Runtime.enable"}
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
+
+
+async def test_a_failed_proxy_lane_send_leaves_no_mapping_behind() -> None:
+ async def sends_unencodable(command: CdpCommand, session: ProxySession, context: InterceptContext) -> object:
+ if command.method == "Page.enable":
+ # Encoding fails after the mapping is allocated; the closure must
+ # discard it or repeated failures eat the shared table for good.
+ await context.send_proxy_command(CdpCommand(id=0, method="Proxy.probe", params={"blob": b"x"}))
+ return command
+
+ connection = _ControllableUpstream()
+ server = _intercept_server(_SharedBrowser(connection), MiddlewarePipeline(interceptors=[sends_unencodable]))
+ client = _ScriptClient([_command(1, "Page.enable")])
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: client.sent)
+
+ [failure] = _responses(client)
+ assert failure.id == 1
+ assert failure.error is not None
+ assert failure.error["code"] == INTERCEPTOR_FAILURE_CODE
+ shared = server._shared_upstreams[UPSTREAM_URL]
+ assert shared.remapper.pending_count == 0
+ assert connection.sent == []
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
+
+
+async def test_an_interceptor_never_sees_a_foreign_session_command() -> None:
+ seen: list[tuple[str, str | None]] = []
+
+ async def recorder(command: CdpCommand, session: ProxySession, context: InterceptContext) -> CdpCommand:
+ seen.append((command.method, command.session_id))
+ return command
+
+ connection = _ControllableUpstream()
+ server = _intercept_server(_SharedBrowser(connection), MiddlewarePipeline(interceptors=[recorder]))
+ client_a = _ScriptClient([_command(1, "Target.attachToTarget", {"targetId": "tA", "flatten": True})])
+ client_b = _ScriptClient([])
+
+ task_a = asyncio.create_task(server._handle_client(client_a)) # type: ignore[arg-type]
+ task_b = asyncio.create_task(server._handle_client(client_b)) # type: ignore[arg-type]
+ # Wait until A owns session tA (its attach response landed), then B intrudes.
+ assert await _until(lambda: client_a.sent)
+ client_b.feed(_command(2, "Runtime.evaluate", {"expression": "1"}))
+ # Give B's command a distinct marker frame so we know it was processed.
+ client_b.feed(_command(3, "Runtime.evaluate"))
+ shared = server._shared_upstreams[UPSTREAM_URL]
+ assert await _until(lambda: len(seen) >= 2)
+ seen.clear()
+
+ client_b.feed(
+ # Addressed to A's session: refused with CDP's own session-not-found,
+ # without the interceptor ever seeing it.
+ '{"id": 9, "method": "Runtime.evaluate", "sessionId": "tA"}'
+ )
+ assert await _until(lambda: any(r.id == 9 for r in _responses(client_b)))
+
+ [refusal] = [r for r in _responses(client_b) if r.id == 9]
+ assert refusal.error is not None
+ assert refusal.error["code"] == -32001
+ assert seen == []
+ assert shared.session_owner.get("tA") == "c1"
+
+ client_a.release()
+ client_b.release()
+ await asyncio.wait_for(asyncio.gather(task_a, task_b), timeout=5)
+
+
+async def test_a_synthesizing_interceptor_leaves_no_upstream_state_behind() -> None:
+ async def answer(command: CdpCommand, session: ProxySession, context: InterceptContext) -> SynthesizedResponse:
+ return SynthesizedResponse(result={"ok": True}, reason="test")
+
+ connection = _ControllableUpstream()
+ server = _intercept_server(_SharedBrowser(connection), MiddlewarePipeline(interceptors=[answer]))
+ client = _ScriptClient([_command(1, "Page.enable"), _command(2, "Page.enable")])
+
+ task = asyncio.create_task(server._handle_client(client)) # type: ignore[arg-type]
+ assert await _until(lambda: len(client.sent) == 2)
+
+ shared = server._shared_upstreams[UPSTREAM_URL]
+ # No forward, no remap entry, no latency start, no attach intent: the command
+ # was answered before any of those tables could learn about it.
+ assert connection.sent == []
+ assert shared.remapper.pending_count == 0
+ assert shared.command_starts == {}
+ assert shared.attach_intents == []
+
+ client.release()
+ await asyncio.wait_for(task, timeout=5)
diff --git a/tests/unit/proxy/test_pipeline.py b/tests/unit/proxy/test_pipeline.py
index 6a84d26f1..fff2d7707 100644
--- a/tests/unit/proxy/test_pipeline.py
+++ b/tests/unit/proxy/test_pipeline.py
@@ -3,7 +3,14 @@ from __future__ import annotations
import pytest
from skyvern.proxy.core.frames import CdpCommand, CdpFrame
-from skyvern.proxy.core.pipeline import Direction, MiddlewarePipeline
+from skyvern.proxy.core.pipeline import (
+ Direction,
+ InterceptContext,
+ InterceptorContractError,
+ MiddlewarePipeline,
+ SynthesizedResponse,
+ interceptor_failure_response,
+)
from skyvern.proxy.core.session import Principal, ProxySession
@@ -15,6 +22,14 @@ def make_session() -> ProxySession:
)
+def make_context(sent: list[CdpCommand] | None = None) -> InterceptContext:
+ async def send_proxy_command(command: CdpCommand) -> None:
+ if sent is not None:
+ sent.append(command)
+
+ return InterceptContext(send_proxy_command=send_proxy_command)
+
+
@pytest.mark.asyncio
async def test_pipeline_composes_middlewares_in_order() -> None:
calls: list[tuple[str, Direction, str]] = []
@@ -70,3 +85,162 @@ async def test_empty_pipeline_returns_original_frame() -> None:
frame = CdpCommand(id=1, method="Runtime.enable")
assert await MiddlewarePipeline().process(frame, Direction.CLIENT_TO_UPSTREAM, make_session()) == frame
+
+
+async def test_interceptors_run_in_order_and_rewrite_the_command() -> None:
+ calls: list[str] = []
+
+ async def first(command: CdpCommand, session: ProxySession, context: InterceptContext) -> CdpCommand:
+ calls.append("first")
+ return CdpCommand(id=command.id, method=command.method, params={"first": True})
+
+ async def second(command: CdpCommand, session: ProxySession, context: InterceptContext) -> CdpCommand:
+ calls.append("second")
+ return CdpCommand(id=command.id, method=command.method, params={**(command.params or {}), "second": True})
+
+ pipeline = MiddlewarePipeline(interceptors=[first, second])
+
+ result = await pipeline.intercept(CdpCommand(id=7, method="Page.navigate"), make_session(), make_context())
+
+ assert result == CdpCommand(id=7, method="Page.navigate", params={"first": True, "second": True})
+ assert calls == ["first", "second"]
+
+
+async def test_synthesized_response_short_circuits_later_interceptors() -> None:
+ calls: list[str] = []
+
+ async def answer(command: CdpCommand, session: ProxySession, context: InterceptContext) -> SynthesizedResponse:
+ calls.append("answer")
+ return SynthesizedResponse(result={"ok": True}, reason="test")
+
+ async def never_runs(command: CdpCommand, session: ProxySession, context: InterceptContext) -> CdpCommand:
+ calls.append("never")
+ return command
+
+ pipeline = MiddlewarePipeline(interceptors=[answer, never_runs])
+ command = CdpCommand(id=9, method="Page.navigate", session_id="sess-1")
+
+ outcome = await pipeline.intercept(command, make_session(), make_context())
+
+ assert isinstance(outcome, SynthesizedResponse)
+ assert calls == ["answer"]
+ # Stamping is the correlation guarantee: the response reuses the command's own
+ # id and session scope, so an interceptor cannot mis-correlate a synthesis.
+ response = outcome.to_response(command)
+ assert response.id == 9
+ assert response.session_id == "sess-1"
+ assert response.result == {"ok": True}
+ assert response.error is None
+
+
+def test_synthesized_response_requires_exactly_one_of_result_and_error() -> None:
+ with pytest.raises(ValueError):
+ SynthesizedResponse()
+ with pytest.raises(ValueError):
+ SynthesizedResponse(result={}, error={"code": 1, "message": "x"})
+
+
+def test_synthesized_error_must_be_a_valid_cdp_error() -> None:
+ with pytest.raises(ValueError):
+ SynthesizedResponse(error={"code": 1})
+ with pytest.raises(ValueError):
+ SynthesizedResponse(error={"message": "no code"})
+ with pytest.raises(ValueError):
+ SynthesizedResponse(error={"code": 1, "message": "x", "extra": True})
+
+
+def test_synthesized_response_requires_a_reason() -> None:
+ with pytest.raises(ValueError):
+ SynthesizedResponse(result={}, reason="")
+
+
+def test_synthesized_payloads_must_be_cdp_encodable() -> None:
+ # A synthesis that cannot be JSON-encoded must fail at construction — inside
+ # the interceptor, where the fail-closed rule converts it into a deterministic
+ # error — never at delivery, where it would tear the relay down instead.
+ with pytest.raises(ValueError):
+ SynthesizedResponse(result={"blob": b"bytes"})
+ with pytest.raises(ValueError):
+ SynthesizedResponse(result={"nan": float("nan")})
+ with pytest.raises(ValueError):
+ SynthesizedResponse(result={"obj": object()})
+ with pytest.raises(ValueError):
+ SynthesizedResponse(error={"code": 1, "message": "x", "data": {"blob": b"bytes"}})
+
+
+def test_reason_must_be_a_label_safe_identifier() -> None:
+ # The reason becomes a metric label: request-derived content (URLs, ids,
+ # error text) must be unrepresentable, which is what bounds cardinality.
+ for bad in ("has space", "https://example.com", "UPPER", "x" * 65, "dash-ed"):
+ with pytest.raises(ValueError):
+ SynthesizedResponse(result={}, reason=bad)
+ assert SynthesizedResponse(result={}, reason="org_denylist_v2").reason == "org_denylist_v2"
+
+
+async def test_interceptor_must_preserve_the_request_id() -> None:
+ async def renumber(command: CdpCommand, session: ProxySession, context: InterceptContext) -> CdpCommand:
+ return CdpCommand(id=command.id + 1, method=command.method)
+
+ pipeline = MiddlewarePipeline(interceptors=[renumber])
+
+ with pytest.raises(InterceptorContractError):
+ await pipeline.intercept(CdpCommand(id=1, method="Page.navigate"), make_session(), make_context())
+
+
+async def test_interceptor_must_preserve_session_addressing() -> None:
+ async def rescope(command: CdpCommand, session: ProxySession, context: InterceptContext) -> CdpCommand:
+ return CdpCommand(id=command.id, method=command.method, session_id="other-session")
+
+ async def readdress(command: CdpCommand, session: ProxySession, context: InterceptContext) -> CdpCommand:
+ return CdpCommand(id=command.id, method=command.method, params={"sessionId": "other-session"})
+
+ with pytest.raises(InterceptorContractError):
+ await MiddlewarePipeline(interceptors=[rescope]).intercept(
+ CdpCommand(id=1, method="Page.navigate", session_id="mine"), make_session(), make_context()
+ )
+ with pytest.raises(InterceptorContractError):
+ await MiddlewarePipeline(interceptors=[readdress]).intercept(
+ CdpCommand(id=1, method="Target.detachFromTarget", params={"sessionId": "mine"}),
+ make_session(),
+ make_context(),
+ )
+
+
+async def test_interceptor_must_return_a_command_or_a_synthesis() -> None:
+ async def drops(command: CdpCommand, session: ProxySession, context: InterceptContext) -> None:
+ return None
+
+ pipeline = MiddlewarePipeline(interceptors=[drops])
+
+ # A silently dropped command would hang its client forever, so an interceptor
+ # has no drop verb at all — blocking means synthesizing an error response.
+ with pytest.raises(InterceptorContractError):
+ await pipeline.intercept(CdpCommand(id=1, method="Page.navigate"), make_session(), make_context())
+
+
+async def test_no_interceptors_is_identity() -> None:
+ command = CdpCommand(id=1, method="Page.navigate")
+ pipeline = MiddlewarePipeline()
+
+ assert pipeline.has_interceptors is False
+ assert await pipeline.intercept(command, make_session(), make_context()) is command
+ assert MiddlewarePipeline(interceptors=[]).has_interceptors is False
+
+
+def test_interceptor_failure_response_is_deterministic() -> None:
+ command = CdpCommand(id=13, method="Page.navigate", session_id="sess-1")
+
+ response = interceptor_failure_response(command)
+
+ assert response.id == 13
+ assert response.session_id == "sess-1"
+ assert response.result is None
+ assert response.error is not None
+ assert response.error["code"] == -32603
+ assert response == interceptor_failure_response(command)