Clarify reverse transport direction

Author: pirate

README.md

@@ -142,7 +142,7 @@ pnpm run proxy -- --launcher-mode=local --upstream-mode=nats --upstream-nats-url
 # ✨ All ModCDP commands now work through playwright! you can modify/extend playwright behavior to your heart's content
 ```
 
-The proxy uses the same `--launcher-*`, `--injector-*`, `--upstream-*`, `--client-config='{"client_cdp_send_timeout_ms": 10000}'`, `--router='{"router_routes": {...}}'`, and `--server-config='{"router": {"router_routes": {...}}}'` config groups as `ModCDPClient`. CLI flags use kebab case and map to the owner-prefixed config fields, for example `--launcher-local-executable-path` maps to `launcher.launcher_local_executable_path`. `ws` keeps a transparent websocket-to-websocket fast path; `pipe`, `nativemessaging`, `nats`, and launched `reversews` proxy downstream CDP-shaped messages through the selected `ModCDPClient` upstream transport.
+The proxy uses the same `--launcher-*`, `--injector-*`, `--upstream-*`, `--client-config='{"client_cdp_send_timeout_ms": 10000}'`, `--router='{"router_routes": {...}}'`, and `--server-config='{"router": {"router_routes": {...}}}'` config groups as `ModCDPClient`. CLI flags use kebab case and map to the owner-prefixed config fields, for example `--launcher-local-executable-path` maps to `launcher.launcher_local_executable_path`. `ws` keeps a transparent websocket-to-websocket fast path; `pipe`, `nativemessaging`, `nats`, and launched `reversews` proxy downstream CDP-shaped messages through the selected client-side `ModCDPClient` transport.
 
 Native messaging mode uses the configured browser native host name directly. The baked extension expects the default `com.modcdp.bridge` host, so changing `--upstream-nativemessaging-host-name` requires using an extension build that was baked for that host. Because Chrome owns native host process launch and stdio, native messaging is not a standalone `pnpm run proxy` mode.
 
@@ -157,7 +157,7 @@ pnpm run proxy -- --launcher-mode=local --upstream-mode=reversews --upstream-rev
 # const browser = await playwright.chromium.connectOverCDP("http://127.0.0.1:9223")
 ```
 
-Reverse mode is opt-in. The shipped extension auto-connects to the fixed local reverse connector at `ws://127.0.0.1:29292`; the proxy/client listens there and waits for that extension connection. Keep `--upstream-reversews-bind` when using a custom extension build whose compiled autoconnect URL points at a different host or port. `--upstream-reversews-wait-timeout-ms` controls how long the proxy/client waits. Once connected, the extension identifies itself as a ModCDP service worker and the proxy uses that reverse websocket as its upstream. `Mod.*`, expression-backed `Custom.*` commands, custom event fanout, middleware, and normal CDP commands all stay routed through `globalThis.ModCDP.handleCommand(...)` in the service worker.
+Reverse mode is opt-in. The shipped extension auto-connects to the fixed local reverse connector at `ws://127.0.0.1:29292`; the proxy/client listens there and waits for that extension connection. Keep `--upstream-reversews-bind` when using a custom extension build whose compiled autoconnect URL points at a different host or port. `--upstream-reversews-wait-timeout-ms` controls how long the proxy/client waits. Once connected, the extension identifies itself as a ModCDP service worker and the proxy uses that reverse websocket as its client-side transport. From the service worker server's perspective, reversews is a downstream client connection. `Mod.*`, expression-backed `Custom.*` commands, custom event fanout, middleware, and normal CDP commands all stay routed through `globalThis.ModCDP.handleCommand(...)` in the service worker.
 
 Reverse mode is intentionally scoped to one local browser and one reverse extension connection per proxy process. The browser may still have other extensions installed; ModCDP does not require `--disable-extensions-except`.
 

go/modcdp/transport/UpstreamTransport.go

@@ -43,9 +43,13 @@ func freePort() (int, error) {
 }
 
 type UpstreamMode string
+type UpstreamPeerKind string
 
 const (
 	UpstreamModeWS UpstreamMode = "ws"
+
+	UpstreamPeerKindBrowserCDP   UpstreamPeerKind = "browser_cdp"
+	UpstreamPeerKindModCDPServer UpstreamPeerKind = "modcdp_server"
 )
 
 type HostPort struct {
@@ -54,17 +58,17 @@ type HostPort struct {
 }
 
 type UpstreamTransport struct {
-	Config                 UpstreamTransportConfig
-	UpstreamIsModCDPServer bool
-	recvListeners          []recvListener
-	closeListeners         []closeListener
-	eventListeners         map[string][]upstreamEventListener
-	listenerMu             sync.Mutex
-	nextListenerID         int64
-	nextID                 int64
-	pending                map[int64]chan map[string]any
-	pendingMu              sync.Mutex
-	writeCommand           func(map[string]any) error
+	Config         UpstreamTransportConfig
+	PeerKind       UpstreamPeerKind
+	recvListeners  []recvListener
+	closeListeners []closeListener
+	eventListeners map[string][]upstreamEventListener
+	listenerMu     sync.Mutex
+	nextListenerID int64
+	nextID         int64
+	pending        map[int64]chan map[string]any
+	pendingMu      sync.Mutex
+	writeCommand   func(map[string]any) error
 }
 
 type recvListener struct {
@@ -94,6 +98,7 @@ func NewUpstreamTransport(config UpstreamTransportConfig) UpstreamTransport {
 	}
 	return UpstreamTransport{
 		Config:         config,
+		PeerKind:       UpstreamPeerKindBrowserCDP,
 		eventListeners: map[string][]upstreamEventListener{},
 		pending:        map[int64]chan map[string]any{},
 		writeCommand: func(map[string]any) error {

js/src/client/ModCDPClient.ts

@@ -323,7 +323,7 @@ export class ModCDPClient<
       return this;
     }
 
-    if (this.upstream.upstream_is_modcdp_server) {
+    if (this.upstream.peer_kind === "modcdp_server") {
       const configure_started_at = Date.now();
       if (this.server_config !== null) await this.upstream.send("Mod.configure", this._serverConfigureParams());
       const configure_completed_at = Date.now();
@@ -395,7 +395,7 @@ export class ModCDPClient<
   async send(method: string, params: unknown = {}, session_id: string | null = null): Promise<Record<string, unknown>> {
     const started_at = Date.now();
     const can_register_locally =
-      !this.upstream.upstream_is_modcdp_server &&
+      this.upstream.peer_kind !== "modcdp_server" &&
       (method === "Mod.addCustomCommand" ||
         (method === "Mod.addCustomEvent" && !this.injector?.session_id) ||
         (method === "Mod.addMiddleware" && !this.injector?.session_id));
@@ -416,7 +416,7 @@ export class ModCDPClient<
       };
       return this.types.parseCommandResult(method, prepared.local_result);
     }
-    if (this.upstream.upstream_is_modcdp_server) {
+    if (this.upstream.peer_kind === "modcdp_server") {
       const result = await this.upstream.send(method, command_params as ProtocolPayload, session_id, {
         timeout_ms: this.config.client_cdp_send_timeout_ms,
       });

js/src/transport/NATSUpstreamTransport.ts

@@ -37,7 +37,7 @@ type NatsSocket = WebSocket | NatsTcpSocket;
 
 class NATSUpstreamTransport extends UpstreamTransport {
   declare config: NATSUpstreamTransportConfig;
-  override upstream_is_modcdp_server = true;
+  override peer_kind = "modcdp_server" as const;
   private socket: NatsSocket | null = null;
   private tcp_buffer = Buffer.alloc(0);
   private ws_buffer = "";

js/src/transport/NativeMessagingUpstreamTransport.ts

@@ -17,7 +17,7 @@ type NativeMessagingUpstreamTransportConfig = z.infer<typeof NativeMessagingUpst
 
 class NativeMessagingUpstreamTransport extends UpstreamTransport {
   declare config: NativeMessagingUpstreamTransportConfig;
-  override upstream_is_modcdp_server = true;
+  override peer_kind = "modcdp_server" as const;
   private buffer: Buffer<ArrayBufferLike> = Buffer.alloc(0);
   private read_native_message: ((chunk: Buffer) => void) | null = null;
 

js/src/transport/ReverseWSDownstreamTransport.ts

@@ -14,7 +14,7 @@ const DEFAULT_REVERSE_BRIDGE_URL = "ws://127.0.0.1:29292";
 
 const ReverseWSDownstreamTransportConfigSchema = z
   .object({
-    upstream_reversews_url: z.string().default(DEFAULT_REVERSE_BRIDGE_URL),
+    downstream_reversews_url: z.string().default(DEFAULT_REVERSE_BRIDGE_URL),
     reconnect_interval_ms: z.number().positive().default(DEFAULT_REVERSE_BRIDGE_RECONNECT_INTERVAL_MS),
   })
   .strict();
@@ -69,19 +69,19 @@ class ReverseWSDownstreamTransport extends DownstreamTransport {
   start(endpoint?: string, config: z.input<typeof ReverseWSDownstreamTransportConfigSchema> = {}) {
     this.config = ReverseWSDownstreamTransportConfigSchema.parse({
       ...config,
-      upstream_reversews_url: endpoint,
+      downstream_reversews_url: endpoint,
     });
-    if (!/^wss?:\/\//i.test(this.config.upstream_reversews_url)) {
+    if (!/^wss?:\/\//i.test(this.config.downstream_reversews_url)) {
       throw new Error(
-        `reverse proxy endpoint must be a ws:// or wss:// URL, got ${this.config.upstream_reversews_url}.`,
+        `reverse proxy endpoint must be a ws:// or wss:// URL, got ${this.config.downstream_reversews_url}.`,
       );
     }
     this.started = true;
-    void this.connect(this.config.upstream_reversews_url).catch(() => {
+    void this.connect(this.config.downstream_reversews_url).catch(() => {
       this.scheduleReconnect();
     });
     return {
-      upstream_reversews_url: this.config.upstream_reversews_url,
+      downstream_reversews_url: this.config.downstream_reversews_url,
       reconnect_interval_ms: this.config.reconnect_interval_ms,
       connecting: true,
     };
@@ -94,7 +94,7 @@ class ReverseWSDownstreamTransport extends DownstreamTransport {
 
   /** Stop reconnecting and close the active reversews socket. */
   stop(reason = "stopped") {
-    const upstream_reversews_url = this.started ? this.config.upstream_reversews_url : null;
+    const downstream_reversews_url = this.started ? this.config.downstream_reversews_url : null;
     this.started = false;
     if (this.reconnect_timer) {
       clearTimeout(this.reconnect_timer);
@@ -105,7 +105,7 @@ class ReverseWSDownstreamTransport extends DownstreamTransport {
     if (socket?.readyState === WebSocket.OPEN || socket?.readyState === WebSocket.CONNECTING) {
       socket.close(1000, reason);
     }
-    return { upstream_reversews_url, stopped: true, reason };
+    return { downstream_reversews_url, stopped: true, reason };
   }
 
   /** Send one CDP response to the reversews client that sent the request. */
@@ -138,14 +138,14 @@ class ReverseWSDownstreamTransport extends DownstreamTransport {
     this.reconnect_timer = setTimeout(() => {
       this.reconnect_timer = null;
       if (!this.started) return;
-      void this.connect(this.config.upstream_reversews_url).catch(() => {});
+      void this.connect(this.config.downstream_reversews_url).catch(() => {});
     }, this.config.reconnect_interval_ms);
   }
 
   private async connect(endpoint: string) {
     if (this.socket?.readyState === WebSocket.OPEN || this.socket?.readyState === WebSocket.CONNECTING) {
       return {
-        upstream_reversews_url: endpoint,
+        downstream_reversews_url: endpoint,
         connected: this.socket.readyState === WebSocket.OPEN,
       };
     }
@@ -173,7 +173,7 @@ class ReverseWSDownstreamTransport extends DownstreamTransport {
       if (this.socket === ws) this.socket = null;
       this.scheduleReconnect();
     });
-    return { upstream_reversews_url: endpoint, connected: false };
+    return { downstream_reversews_url: endpoint, connected: false };
   }
 
   private async handleMessage(ws: WebSocket, data: unknown) {

js/src/transport/ReverseWSUpstreamTransport.ts

@@ -28,7 +28,7 @@ type ReverseHello = {
 
 class ReverseWSUpstreamTransport extends UpstreamTransport {
   declare config: ReverseWSUpstreamTransportConfig;
-  override upstream_is_modcdp_server = true;
+  override peer_kind = "modcdp_server" as const;
   endpoint_url: string;
   private reversews_listener: WsServer | null = null;
   private socket: WsSocket | null = null;

js/src/transport/UpstreamTransport.ts

@@ -33,6 +33,7 @@ type TargetRoute = {
   sessionId?: cdp.types.ts.Target.SessionID | null;
 };
 type UpstreamPeerWaitConfig = { connected_after_ms?: number | null };
+type UpstreamPeerKind = "browser_cdp" | "modcdp_server";
 
 type UpstreamEventListener = (
   payload: ProtocolPayload,
@@ -42,10 +43,11 @@ type UpstreamEventListener = (
 
 class UpstreamTransport {
   config: UpstreamTransportBaseConfig;
-  // True when this transport terminates at a ModCDPServer peer instead of a
-  // raw browser CDP endpoint. ModCDPClient reads this to skip local
-  // target/session bootstrap and send CDP-shaped commands directly upstream.
-  upstream_is_modcdp_server = false;
+  // The kind of remote peer this client-side transport talks to. Most
+  // transports talk to raw browser CDP. Reverse client transports talk to a
+  // ModCDPServer downstream connection and therefore do not use the local
+  // AutoSessionRouter bootstrap path.
+  peer_kind: UpstreamPeerKind = "browser_cdp";
   private next_id = 1;
   private pending = new Map<
     number,
@@ -278,5 +280,6 @@ export type {
   UpstreamTransportConfig,
   TargetRoute,
   UpstreamPeerWaitConfig,
+  UpstreamPeerKind,
   UpstreamEventListener,
 };

js/test/test.ReverseWSUpstreamTransport.ts

@@ -11,7 +11,7 @@ import { test } from "vitest";
 import { LocalBrowserLauncher } from "../src/launcher/LocalBrowserLauncher.js";
 import { ReverseWSUpstreamTransport } from "../src/transport/ReverseWSUpstreamTransport.js";
 
-test("reversews upstream config owns bind updates and wait timeout", async () => {
+test("reversews client transport config owns bind updates and wait timeout", async () => {
   const transport = new ReverseWSUpstreamTransport({
     upstream_reversews_bind: "127.0.0.1:29292",
     upstream_reversews_wait_timeout_ms: 10,
@@ -32,7 +32,7 @@ test("reversews upstream config owns bind updates and wait timeout", async () =>
   await assert.rejects(() => transport.waitForPeer(), /Timed out waiting 5ms/);
 });
 
-test("reversews upstream close rejects pending peer waits", async () => {
+test("reversews client transport close rejects pending peer waits", async () => {
   const reverse_port = await LocalBrowserLauncher.freePort();
   const transport = new ReverseWSUpstreamTransport({
     upstream_reversews_bind: `127.0.0.1:${reverse_port}`,
@@ -48,7 +48,7 @@ test("reversews upstream close rejects pending peer waits", async () => {
   );
 });
 
-test("reversews upstream close resets peer wait state", async () => {
+test("reversews client transport close resets peer wait state", async () => {
   const reverse_port = await LocalBrowserLauncher.freePort();
   const transport = new ReverseWSUpstreamTransport({
     upstream_reversews_bind: `127.0.0.1:${reverse_port}`,
@@ -72,7 +72,7 @@ test("reversews upstream close resets peer wait state", async () => {
   }
 });
 
-test("reversews upstream waits again after a peer disconnects", async () => {
+test("reversews client transport waits again after a peer disconnects", async () => {
   const reverse_port = await LocalBrowserLauncher.freePort();
   const transport = new ReverseWSUpstreamTransport({
     upstream_reversews_bind: `127.0.0.1:${reverse_port}`,
@@ -95,7 +95,7 @@ test("reversews upstream waits again after a peer disconnects", async () => {
   }
 });
 
-test("reversews upstream accepts a replacement peer after disconnect", async () => {
+test("reversews client transport accepts a replacement peer after disconnect", async () => {
   const reverse_port = await LocalBrowserLauncher.freePort();
   const transport = new ReverseWSUpstreamTransport({
     upstream_reversews_bind: `127.0.0.1:${reverse_port}`,

js/test/test.proxy.ts

@@ -330,7 +330,7 @@ test("proxy CLI maps user-facing flags into a real reversews browser session", a
   }
 }, 90_000);
 
-test("proxy upgrades a vanilla CDP websocket to ModCDP against a real browser over reversews upstream", async () => {
+test("proxy upgrades a vanilla CDP websocket to ModCDP against a real browser over reversews client transport", async () => {
   const proxy_port = await LocalBrowserLauncher.freePort();
   const proxy = await startProxy({
     proxy_listen_port: proxy_port,