Skip to main content
`Ctrl`+`K`

# WebSocket kernel wire protocols

The Jupyter Server needs to pass messages between kernels and the Jupyter web application. Kernels use ZeroMQ sockets, and the web application uses a WebSocket.

## ZeroMQ wire protocol

The kernel wire protocol over ZeroMQ takes advantage of multipart messages, allowing to decompose a message into parts and to send and receive them unmerged. The following table shows the message format (the beginning has been omitted for clarity):

Format of a kernel message over ZeroMQ socket (indices refer to parts, not bytes)
… | 0 | 1 | 2 | 3 | 4 | 5 | …
--- | --- | --- | --- | --- | --- | --- | ---
… | header | parent_header | metadata | content | buffer_0 | buffer_1 | …

See also the Jupyter Client documentation.

Note that a set of ZeroMQ sockets, one for each channel (shell, iopub, etc.), are multiplexed into one WebSocket. Thus, the channel name must be encoded in WebSocket messages.

## WebSocket protocol negotiation

When opening a WebSocket, the Jupyter web application can optionally provide a list of subprotocols it supports (see e.g. the MDN documentation). If nothing is provided (empty list), then the Jupyter Server assumes the default protocol will be used. Otherwise, the Jupyter Server must select one of the provided subprotocols, or none of them. If none of them is selected, the Jupyter Server must reply with an empty string, which means that the default protocol will be used.

## Default WebSocket protocol

The Jupyter Server must support the default protocol, in which a kernel message is serialized over WebSocket as follows:

Format of a kernel message over WebSocket (indices refer to bytes)
0 | 4 | 8 | 12 | … | offset_0 | offset_1 | offset_2 | …
--- | --- | --- | --- | --- | --- | --- | --- | ---
offset_number | offset_0 | offset_1 | offset_2 | … | msg | buffer_0 | buffer_1 | …

Where:

- `offset_number` is the number of the following offsets (is equal to the number of binary buffers plus one).

- `offset_0` is the position of the kernel message (`msg`) from the beginning of this message, in bytes.

- `offset_1` is the position of the first binary buffer (`buffer_0`) from the beginning of this message, in bytes (optional).

- `offset_2` is the position of the second binary buffer (`buffer_1`) from the beginning of this message, in bytes (optional).

- `msg` is the kernel message, excluding binary buffers and including the channel name, as a UTF8-encoded stringified JSON.

- `buffer_0` is the first binary buffer (optional).

- `buffer_1` is the second binary buffer (optional).

The message can be deserialized by parsing `msg` as a JSON object (after decoding it to a string):

    msg = {
        "channel": channel,
        "header": header,
        "parent_header": parent_header,
        "metadata": metadata,
        "content": content,
    }

Then retrieving the channel name, and updating with the buffers, if any:

    buffers = {
        [
            buffer_0,
            buffer_1
            # ...
        ]
    }

## `v1.kernel.websocket.jupyter.org` protocol

The Jupyter Server can optionally support the `v1.kernel.websocket.jupyter.org` protocol, in which a kernel message is serialized over WebSocket as follows:

Format of a kernel message over WebSocket (indices refer to bytes)
0 | 8 | 16 | … | 8*offset_number | offset_0 | offset_1 | offset_2 | offset_3 | offset_4 | offset_5 | offset_6 | …
--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
offset_number | offset_0 | offset_1 | … | offset_n | channel | header | parent_header | metadata | content | buffer_0 | buffer_1 | …

Where:

- `offset_number` is a 64-bit (little endian) unsigned integer.

- `offset_0` to `offset_n` are 64-bit (little endian) unsigned integers (with `n=offset_number-1`).

- `channel` is a UTF-8 encoded string containing the channel for the message (shell, iopub, etc.).

- `header`, `parent_header`, `metadata`, and `content` are UTF-8 encoded JSON text representing the given part of a message in the Jupyter message protocol.

- `offset_n` is the number of bytes in the message.

- The message can be deserialized from the `bin_msg` serialized message as follows (Python code):

    import json

    channel = bin_msg[offset_0:offset_1].decode("utf-8")
    header = json.loads(bin_msg[offset_1:offset_2])
    parent_header = json.loads(bin_msg[offset_2:offset_3])
    metadata = json.loads(bin_msg[offset_3:offset_4])
    content = json.loads(bin_msg[offset_4:offset_5])
    buffer_0 = bin_msg[offset_5:offset_6]
    buffer_1 = bin_msg[offset_6:offset_7]
    # ...
    last_buffer = bin_msg[offset_n_minus_1:offset_n]