Using the jupyterlab services API
This page describes how the Jupyter extension uses the @jupyterlab/services npm module to connect and control Jupyter kernels.
Jupyter kernels are processes that handle a set of messages called the Jupyter Messaging Protocol (or JMP for short).
In this diagram below, those messages are sent over the 0MQ portion.
We (the Jupyter Extension) need to send these messages to and from a Jupyter kernel.
The Jupyter org has provided the @jupyterlab/services npm module to help us do just that.
This npm module:
- Opens a websocket to the notebook server (see raw zmq for what we do when not using a Jupyter server)
- Creates an IKernelConnection interface for talking to the kernel
- Translates calls on the IKernelConnection to message structures
- Serializes the message structures into a specific wire-protocol that all kernels must implement
- Sends the serialized message over the websocket to the server. The server will multiplex the message to the correct 0MQ socket.
- Deserializes result messages from the wire-protocol back into messages, which in turn get changed into events in javascript.
The npm module essentially handles all communication to and from a kernel so that javascript can treat the kernel like a local object.
We started with the @jupyterlab/services because the first version of the Jupyter extension always talked to a notebook server, either by us starting one or the user providing one.
There were frequent issues with that and we switched to a more direct approach.
The direct (or raw as it's called elsewhere) doesn't talk to a notebook server though. Instead it talks directly to the kernels over zmq:
This means we don't have a websocket to connect to. However, since we were using the @jupyterlab/services::IKernelConnection as the standard way of communicating with kernels, we tricked jupyterlab services into thinking it was still talking to a server.
Essentially this part here:
Raw changes the sequence diagram to look like so:
In the diagram, the Notebook Server has now been replaced by a RawSocket. The implementation for this can be found here.
Since the RawSocket is talking directly to the kernel, it needs to serialize/deserialize on its own. To facilitate this, we replace the serialization in the @jupyterlab/services with empty functions. That happens in an npm post install hook.