[RFC] Websocket support

[SamC-Apadmi]

RFC: WebSocket Support

Feature Name: websocket-mock-endpoints

Type: feature

Start Date: 2026-06-01

Author: Sam

Related components: :mockzilla, :mockzilla-common, :mockzilla-management, :mockzilla-management-ui

---

Summary

Add first-class WebSocket mocking to Mockzilla, allowing developers to configure mock WebSocket endpoints with the same builder-style API used today for HTTP endpoints. The server would handle connection lifecycle events, respond to incoming frames, and support scripted server-push scenarios selectable from management ui.

Motivation

Mockzilla currently supports only HTTP request/response mocking. We're eventually going to have an app that uses WebSocket connections for real-time features and it's a gap in Mockzilla — and there is no way to mock these. Developers working on these features must either run a real backend or write custom test doubles outside Mockzilla, which isn't ideal.

Detailed design

A new WebSocketEndpointConfiguration type would be introduced in :mockzilla-common, mirroring the existing EndpointConfiguration builder API:

This is just made up for now but could look something like this:

MockzillaConfig.Builder()
    .addWebSocketEndpoint(
        WebSocketEndpointConfiguration.Builder("live-prices")
            .setPatternMatcher { uri.endsWith("/prices/ws") }
            .setOnMessage { session, incoming ->
                session.send("ack: $incoming")
            }
            .setDashboardConfig(
                WebSocketDashboardOptionsConfig(
                    presets = listOf(
                        WebSocketPreset(
                            name = "Steady stream",
                            frames = listOf(
                                WebSocketFrame.Text("""{"price": 1.23}"""),
                                WebSocketFrame.Delay(100.milliseconds),
                                WebSocketFrame.Text("""{"price": 1.25}"""),
                            ),
                            loop = true
                        ),
                        WebSocketPreset(
                            name = "Connection error",
                            frames = listOf(WebSocketFrame.Close(reason = "Server unavailable"))
                        )
                    )
                )
            )
    )
    .build()

Server side: Ktor has native webSocket { } route support, so the infrastructure is already present. A new route would be registered alongside /local-mock/{...} for matched WebSocket upgrade requests. Basically just wrapping up ktor websockets.

Dashboard presets: When a preset is active it replaces onMessage, replaying the named frame sequence instead — matching how HTTP presets override defaultHandler today. The management dashboard would expose:

• A preset picker per WebSocket endpoint (like the existing ones)
• A live frame log (sent and received)
• A text input for manually injecting a one-off frame at runtime

Drawbacks

• The management dashboard requires non-trivial new UI work to surface live frame traffic.
• It's a big change and adds a fair bit more surface area to the Mockzilla API for a feature no active project currently uses. (I just don't want to rush this implementation when we inevitably get an App that needs it)

Alternatives

• Leave it to application code — developers can already write custom Ktor WebSocket servers in tests. This keeps Mockzilla simpler but means WebSocket mocking lives outside the unified mock configuration.

[TomHa-Apadmi]

Don't really have any problems with the principle of this