Designing Robust WebSocket Support in Hoppscotch: Architecture, Authentication, and Resilience

Problem Statement

Hoppscotch is a browser‑based API testing tool that traditionally focuses on HTTP/REST. Adding WebSocket support requires a lightweight, client‑side implementation that preserves the tool’s stateless nature while still offering secure authentication and reliable reconnection logic. The goal is to keep the architecture minimal, avoid server‑side proxies, and expose clear failure handling for end users.

Requirements

• Browser‑native WebSocket API usage – no external proxy or backend component.
• Stateless authentication: Bearer tokens or API keys must be sent without storing them in the application state.
• Connection lifecycle visibility: open, close, error, and message events must be logged and displayed.
• Automatic reconnection with exponential backoff to handle transient network loss.
• Graceful handling of malformed frames and server‑initiated disconnects.
• Cross‑origin compatibility: the server must expose appropriate CORS or Access‑Control-Allow-Origin headers.

Minimal Viable Design

The core of the WebSocket feature is a WebSocketManager service that lives inside the existing Vuex store. It exposes three main responsibilities:

1. Connection Control – a UI component (WsConnectionPanel) that lets the user enter the URL, choose authentication, and start/stop the connection.
2. Message Logging – a WsMessageLog module that records inbound and outbound frames, timestamps, and error details.
3. Reconnection Strategy – an internal exponential backoff algorithm that queues reconnect attempts and respects user‑initiated cancel requests.

All state is kept in Vuex, but sensitive tokens are never persisted. Instead, they are passed directly to the native WebSocket constructor via query parameters or the Sec-WebSocket-Protocol header.

WebSocketManager Service (excerpt)

export default class WebSocketManager {
  constructor(store) {
    this.store = store;
    this.ws = null;
    this.reconnectAttempts = 0;
  }

  connect(url, authToken) {
    // Append token as query param for stateless transmission
    const wsUrl = new URL(url);
    wsUrl.searchParams.set('token', authToken);

    this.ws = new WebSocket(wsUrl.toString());
    this.attachEventHandlers();
  }

  attachEventHandlers() {
    this.ws.onopen = () => this.store.commit('ws/OPEN');
    this.ws.onmessage = msg => this.store.commit('ws/RECEIVE', msg.data);
    this.ws.onclose = () => this.handleClose();
    this.ws.onerror = err => this.handleError(err);
  }

  handleClose() {
    this.store.commit('ws/CLOSE');
    this.scheduleReconnect();
  }

  scheduleReconnect() {
    if (this.reconnectAttempts > 5) return; // give up after 5 tries
    const delay = Math.pow(2, this.reconnectAttempts) * 1000; // exponential backoff
    setTimeout(() => {
      this.reconnectAttempts++;
      this.connect(this.store.state.ws.url, this.store.state.ws.token);
    }, delay);
  }
}

Trust/Data Boundaries

Because the WebSocket connection is created in the browser, the only trust boundary is between the Hoppscotch UI and the remote WebSocket server. Tokens are never stored in localStorage or Vuex state; they are passed as query parameters or headers and discarded afterward. This design keeps the tool stateless and mitigates accidental credential leakage.

Potential Exposure

• Tokens in URLs appear in browser history and server logs. If the server cannot accept headers, consider using a short‑lived token or rotating keys.
• Headers are preferred when the server supports Sec-WebSocket-Protocol or Authorization headers, but many browsers do not allow custom headers on WebSocket connections. In those cases, query parameters remain the fallback.

Operational Checks

• Connection Events – the onopen, onclose, and onerror callbacks update Vuex state and trigger UI feedback.
• Handshake Validation – after onopen, the tool verifies that the server sent the expected subprotocol or a welcome message. If not, it closes the socket and alerts the user.
• Reconnection Logic – the backoff timer is reset on a successful onopen event, preventing endless retry loops.
• Message Ordering – the message logger assigns a monotonically increasing sequence number to each inbound frame, allowing the UI to display out‑of‑order warnings.

Failure Modes & Conditions

When the connection fails, the tool must differentiate between user‑initiated closures, network outages, and server‑side errors.

1. Network Loss – onclose with code=1006 triggers the reconnection queue. The UI shows a “Reconnecting…” indicator.
2. Server Disconnect – a normal close (code=1000) stops reconnection attempts and informs the user that the session ended.
3. Malformed Frames – the onmessage handler catches JSON parse errors, logs them, and displays a non‑blocking alert.
4. Authentication Failure – if the server replies with an error frame (e.g., “401 Unauthorized”), the manager closes the socket and prompts the user to re‑enter credentials.

Under heavy load or when the server intentionally drops frames, the retry queue preserves order by buffering unsent messages and replaying them once the connection is re‑established.

When to Re‑evaluate the Design

• If the target WebSocket servers start requiring custom HTTP headers that browsers cannot set, a lightweight proxy would be needed.
• When token leakage becomes a compliance issue, moving to a server‑side authentication flow that issues short‑lived session tokens is advisable.
• If the tool must support legacy browsers lacking native WebSocket support, integrating a polyfill or a shim that falls back to long‑polling is required.

Verification Checklist

1. Open Hoppscotch in a modern browser (Chrome 80+, Firefox 75+).
2. Navigate to the WebSocket tab and enter wss://echo.websocket.org with a dummy token.
3. Click “Connect” and observe the console for open, message, and close events.
4. Manually close the connection and watch the reconnection backoff timer in the UI.
5. Inspect the Network panel to confirm the token appears only as a query parameter and is not logged elsewhere.
6. Simulate a server that drops frames (e.g., using a local Node.js echo server that intentionally discards messages) and verify that the message logger records the error and the UI shows an alert.

Conclusion

By leveraging the browser’s native WebSocket API, keeping authentication stateless, and implementing a robust reconnection strategy, Hoppscotch can offer reliable WebSocket testing without adding server‑side complexity. The minimal architecture—WebSocketManager, UI panel, and message logger—all encapsulated in Vuex, satisfies both functional and security requirements while remaining easy to maintain and extend.