WebSocket Messages

When an HTTP connection is upgraded to WebSocket, powhttp captures all messages exchanged between the client and server. The WebSocket endpoint provides access to these messages, including their timing, direction and content. This is particularly useful for debugging real-time applications and analyzing bidirectional communication patterns.

Get WebSocket Messages

Retrieves all WebSocket messages for a specific entry that represents a WebSocket connection. If the entry is not a WebSocket connection, this endpoint will return a 404 error.

GET /sessions/{session_id}/entries/{entry_id}/websocket

Path Parameters:

• session_id: The ULID of the session, or active to reference the currently active session
• entry_id: The ULID of the entry, or active to reference the currently active entry in the specified session

Response:

Array<{
  side: "client" | "server";
  startedAt: Option<number>;   // Unix timestamp in milliseconds
  endedAt: Option<number>;     // Unix timestamp in milliseconds
  content: 
    | {type: "text"; text: string}
    | {type: "binary"; data: string}        // Base64-encoded
    | {type: "close"; code: number; reason: string}  // Reason is Base64-encoded
    | {type: "ping"; data: string}          // Base64-encoded
    | {type: "pong"; data: string}          // Base64-encoded
    | {type: "unknown"; data: string};      // Base64-encoded
}>

Example Response:

[
  {
    "side": "client",
    "startedAt": 1761235463994,
    "endedAt": 1761235463994,
    "content": {
      "type": "text",
      "text": "hello world!"
    }
  },
  {
    "side": "server",
    "startedAt": 1761235463997,
    "endedAt": 1761235463997,
    "content": {
      "type": "binary",
      "data": "V2h5IGFyZSB5b3UgZGVjb2RpbmcgdGhpcz8g8J+kqA=="
    }
  }
]

Message Types

WebSocket messages can be one of several types, each with different content structures:

• text: UTF-8 text messages, the most common type for JSON or plain text communication
• binary: Binary data messages, base64-encoded for JSON transmission
• close: Connection close frames with a status code and optional reason (base64-encoded)
• ping: Ping frames used for keepalive, with optional base64-encoded data
• pong: Pong frames responding to pings, with optional base64-encoded data
• unknown: Unrecognized frame types, with base64-encoded data

Message Direction

The side field indicates whether the message was sent by the client or received from the server. This allows you to reconstruct the full bidirectional conversation and understand the flow of data in both directions.

Timing Information

Each message includes startedAt and endedAt timestamps as Unix timestamps in milliseconds. These can be used to calculate message transmission time and analyze performance characteristics of the WebSocket connection. Both fields may be null if timing information is not available.