Support intercepting and simulating WebSocket traffic

[waldekmastykarz]

Feature request

Description

Dev Proxy currently intercepts and simulates HTTP request/response traffic. It would be valuable to extend this capability to WebSocket connections, enabling developers to:

• Intercept WebSocket observe and log WebSocket handshake, messages (both text and binary frames), and connection lifecycle eventsconnections
• Simulate WebSocket mock WebSocket servers to return predefined messages, simulate delays, inject errors (e.g., unexpected disconnects, malformed frames), and test reconnection logicbehavior
• Apply chaos testing to WebSocket randomly drop messages, introduce latency, or close connections to test application resiliencetraffic

Use cases

• Testing real-time applications (chat, notifications, live dashboards) that rely on WebSocket connections
• Simulating WebSocket API failures and edge cases without needing a live server
• Validating client-side reconnection and error-handling logic

Considerations

• Evaluate support in the underlying proxy engine (unobtanium-web-proxy) for WebSocket interception
• Determine plugin API surface for WebSocket events (connect, message, close, error)
• Consider configuration schema for defining WebSocket mock responses and chaos scenarios

[waldekmastykarz]

Research: WebSocket interception viability

Did some initial research into what it would take to support WebSocket interception and simulation in Dev Proxy. Here is a summary of findings.

What we have today

• Proxy library: We use Unobtanium.Web.Proxy v0.1.5, which already detects WebSocket upgrades (Request.UpgradeToWebSocket) and handles the bidirectional frame relay internally via HandleWebSocketUpgrade. It also has WebSocketFrame, WebSocketDecoder, and WebsocketOpCode types for frame-level processing.
  101 Switching Protocols) is visible to plugins through the existing BeforeRequest/BeforeResponse lifecycle. After the upgrade completes, the library takes over and relays frames Dev Proxy never sees individual WebSocket messages.transparently
• Existing WebSocket code: We already have a WebSocketServer in the inspection plugin (for Chrome DevTools Protocol transport) and ApiKind.WebSocket in the API Center models, but neither is related to proxy interception.

Key blockers

1. Proxy library does not expose frame-level events. HandleWebSocketUpgrade is internal and does a direct bidirectional relay with no public hooks for intercepting individual frames. This is the primary blocker. We would need to either contribute events upstream to svrooij/unobtanium-web-proxy, fork the library, or replace the WebSocket handling entirely in Dev Proxy.

2. Plugin pipeline is designed for request/response pairs. WebSocket messages are high-frequency and bidirectional. Running each message through the current sequential plugin pipeline could introduce latency. We may need a different invocation model for WebSocket plugins.

Architectural gaps

• No long-lived connection model. Plugin data (_pluginData) is scoped to individual request/response cycles and cleaned up in OnAfterResponseAsync. WebSocket connections can persist for hours. We would need a connection-scoped data store.
• No WebSocket plugin interface. We would need a new IWebSocketPlugin interface (following the pattern of IStdioPlugin) with methods like OnWebSocketMessageFromClientAsync, OnWebSocketMessageFromServerAsync, OnWebSocketConnectionOpenedAsync, and OnWebSocketConnectionClosedAsync.
• New abstractions needed. WebSocketConnectionArgs, WebSocketMessageArgs (with direction, message type, payload, ability to block/modify), and a WebSocketSession type for long-lived connection tracking.
• Recording/logging. The current RequestLog model captures discrete request/response pairs. WebSocket sessions would need a different log capturing the upgrade handshake plus a stream of timestamped messages.format
• Inactivity timer. ProxyEngine has an inactivity timer that resets on HTTP requests. Long-lived WebSocket connections with sporadic messages could trigger it incorrectly.

Path forward

1. Start with the proxy contribute OnWebSocketFrame-style events upstream or fork.library
2. Add IWebSocketPlugin interface in DevProxy.Abstractions.
3. Add WebSocket event args and session types.
4. Wire up ProxyEngine to detect UpgradeToWebSocket, hook into frame events, and invoke WebSocket plugins.
5. Build initial plugins: WebSocket logger, latency injection, message modification, mock server.

Verdict

Feasible but high effort, primarily gated on the proxy library lacking frame-level interception hooks. With that resolved, the rest of the architecture has clear patterns to follow.