WebSocket and GraphQL

Two kinds of traffic get their own views in the inspector. WebSocket connections show every frame sent and received in a Messages tab, live as they arrive. GraphQL requests sent over HTTP get a GraphQL tab with the query formatted and the variables in a JSON tree, and the operation name shows in the traffic list.

WebSocket messages

Cloak Proxy recognizes a WebSocket when the request asks to upgrade the connection (an Upgrade: websocket header). It relays the frames between the app and the server and records each one.

1. Make sure the connection is decrypted. For wss:// connections, turn on SSL Proxying for the host or the app. Plain ws:// connections need nothing extra.

2. Click the WebSocket chip in the filter bar to find WebSocket connections quickly.

3. Select the connection in the traffic list.

   The response pane shows a Messages tab, with the frame count, in place of Body. The other response tabs are Header, Set-Cookie (when the handshake set cookies) and Raw.

4. Click a message to see its contents in the lower half of the pane.

12345

Frames on a WebSocket connection. Sent frames have a blue up arrow, received frames a green down arrow.

1. Show all frames, or only sent or received
2. Hide ping and pong frames (on by default)
3. Search text messages
4. How many frames are shown
5. The selected frame's contents

×

Messages table

Column	Shows
Direction	A blue up arrow for frames the app sent, a green down arrow for frames it received
Time	When the frame passed through, to the millisecond
Type	text, binary, ping, pong, close or continuation
Size	The payload size
Data	Text payloads on one line. Other frames show their type, such as <binary data> or <ping data>.

Filter and search messages

Control	What it does
All / Sent / Received	Shows every frame, or only one direction
Hide ping/pong	Hides keep-alive frames. On by default.
Search messages	Shows text frames that contain your text, ignoring case. Binary frames are skipped while searching.
Count	N messages, or N of M messages while filtering

Read a message

Select a frame and its payload opens in the body viewer below the table. JSON text opens as a tree you can filter and query with JSONPath or jq. Other text opens as Raw, and binary payloads that aren’t text open in Hex. Until you select one, the lower half says Select a message to see its contents.

While the connection is open but quiet, the tab shows Connected. Waiting for messages…. If it closed without any frames, it shows No messages were exchanged.

What Cloak Proxy changes

To keep frames readable, Cloak Proxy doesn’t pass on the app’s offer to compress WebSocket messages (the permessage-deflate extension), so the app and server talk uncompressed. Each connection keeps its most recent 5,000 frames. The connection’s Duration in the traffic list covers the whole time it was open.

To send your own WebSocket messages, use the WebSocket client in the API client.

GraphQL operations

Most GraphQL APIs send every operation to the same URL, often /graphql, which makes them hard to tell apart in a list. Cloak Proxy reads the request body and labels each one.

A request counts as GraphQL when:

• it’s a POST or GET request,
• its Content-Type contains json, or its path contains graphql, and
• its body is a JSON object with a query string (bodies up to 2 MB).

In the traffic list

The Path column starts with a pink badge naming the operation, such as query GetUser or mutation UpdateCart. The name comes from the body’s operationName, or from the query document itself (query GetUser(…)). Anonymous operations show only the type: query, mutation or subscription.

Click the GraphQL chip in the filter bar to show only GraphQL requests. GraphQL requests also count as JSON.

Tip

To find one operation, filter with Match in › Request Body and Contains set to its name, for example GetUser.

The GraphQL tab

The request pane gets a GraphQL tab with two parts.

12

The query, formatted, above its variables.

1. The query, re-indented
2. Variables in a JSON tree

×

Part	Shows
Query	The query document, re-indented with one field per line, as selectable text. Press ⌘ F inside it to search.
Variables	The variables object in a JSON tree, with filtering and JSONPath or jq queries. No variables when there are none.

Drag the line between the two parts to resize them. If the body can’t be read as JSON, the tab says The body isn’t valid GraphQL JSON.

The response is ordinary JSON, so it opens in the Body tab’s tree view, where you can filter for errors or query $.data.

To write and send GraphQL queries yourself, use the GraphQL client.

Related

Body viewersThe JSON tree, JSONPath and jq used by both views.

SSL ProxyingDecrypt wss:// and HTTPS GraphQL endpoints.

WebSocket clientConnect and send messages from the API client.

GraphQL clientWrite, run and save GraphQL operations.