diff --git a/docs/source/developers/architecture.rst b/docs/source/developers/architecture.rst index 1a12078437..c3bbfe4ee5 100644 --- a/docs/source/developers/architecture.rst +++ b/docs/source/developers/architecture.rst @@ -14,7 +14,7 @@ open source tool to edit the png file. Jupyter Server Architecture --------------------------- -The Jupyter Server system can be seen in figure below: +The Jupyter Server system can be seen in the figure below: .. image:: ../images/jupyter-server-architecture.drawio.png :alt: Jupyter Server Architecture @@ -36,38 +36,145 @@ Jupyter Server contains the following components: ServerApp with extra request handlers. - **Gateway Server** is a web server that, when configured, provides access to - Jupyter Kernels running on other hosts. There are different ways to create a - gateway server. If your ServerApp needs to communicate with remote Kernels + Jupyter kernels running on other hosts. There are different ways to create a + gateway server. If your ServerApp needs to communicate with remote kernels residing within resource-managed clusters, you can use `Enterprise Gateway `_, otherwise, you can use `Kernel Gateway `_, where - Kernels run locally to the gateway server. + kernels run locally to the gateway server. - **Contents Manager and File Contents Manager** are responsible for serving Notebook on the file system. Session Manager uses Contents Manager to receive - Kernel path. Follow :ref:`the Contents API guide ` to learn + kernel path. Follow :ref:`the Contents API guide ` to learn about Contents Manager. -- **Session Manager** processes users' Sessions. When a user starts a new Kernel, - Session Manager starts a process to provision Kernel for the user and generates +- **Session Manager** processes users' Sessions. When a user starts a new kernel, + Session Manager starts a process to provision kernel for the user and generates a new Session ID. Each opened Notebook has a separate Session, but different - Notebook Kernels can use the same Session. That is useful if the user wants to + Notebook kernels can use the same Session. That is useful if the user wants to share data across various opened Notebooks. Session Manager uses SQLite3 - DataBase to store the Session information. The database is stored in memory by + database to store the Session information. The database is stored in memory by default, but can be configured to save to disk. - **Mapping Kernel Manager** is responsible for managing the lifecycles of the - Kernels running within the ServerApp. It starts a new Kernel for a user's Session - and facilitates interrupt, restart, and shutdown operations against the Kernel. + kernels running within the ServerApp. It starts a new kernel for a user's Session + and facilitates interrupt, restart, and shutdown operations against the kernel. - **Jupyter Client** library is used by Jupyter Server to work with the Notebook - Kernels. + kernels. - - **Kernel Manager** manages a single Kernel for the Notebook. To know more about + - **Kernel Manager** manages a single kernel for the Notebook. To know more about Kernel Manager, follow `the Jupyter Client APIs documentation `_. - - **Kernel Spec Manager** parses files with JSON specification for a Kernels, - and provides a list of available Kernel configurations. To learn about - Kernel Spec, check `the Jupyter Client guide `_. + - **Kernel Spec Manager** parses files with JSON specification for a kernels, + and provides a list of available kernel configurations. To learn about + Kernel Spec Manager, check `the Jupyter Client guide `_. + +Create Session Workflow +----------------------- + +The create Session workflow can be seen in the figure below: + +.. image:: ../images/session-create.drawio.png + :alt: Create Session Workflow + :width: 90% + :align: center + +When a user starts a new kernel, the following steps occur: + +#. The Notebook client sends |create_session|_ request to Jupyter Server. This + request has all necessary data, such as Notebook name, type, path, and kernel + name. + +#. **Session Manager** asks **Contents Manager** for the kernel file system path + based on the input data. + +#. **Session Manager** sends kernel path to **Mapping Kernel Manager**. + +#. **Mapping Kernel Manager** starts the kernel create process by using + **Multi Kernel Manager** and **Kernel Manager**. You can learn more about + **Multi Kernel Manager** in + `the Jupyter Client APIs `_. + +#. **Kernel Manager** uses the provisioner layer to launch a new kernel. + +#. **Kernel Provisioner** is responsible for launching kernels based on the + kernel specification. If the kernel specification doesn't define a provisioner, + it uses `Local Provisioner `_ + to launch the kernel. You can use + `Kernel Provisioner Base `_ + and + `Kernel Provisioner Factory `_ + to create custom provisioners. + +#. **Kernel Spec Manager** gets the kernel specification from the JSON file. + The specification is located in ``kernel.json`` file. + +#. Once **Kernel Provisioner** launches the kernel, + **Kernel Manager** generates the new kernel ID for **Session Manager**. + +#. **Session Manager** saves the new Session data to the SQLite3 database + (Session ID, Notebook path, Notebook name, Notebook type, and kernel ID). + +#. Notebook client receives the created Session data. + +.. _create_session: https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyter_server/master/jupyter_server/services/api/api.yaml#/sessions/post_api_sessions + +.. |create_session| replace:: the *POST /api/sessions* + +Delete Session Workflow +----------------------- + +The delete Session workflow can be seen in the figure below: + +.. image:: ../images/session-delete.drawio.png + :alt: Delete Session Workflow + :width: 80% + :align: center + +When a user stops a kernel, the following steps occur: + +#. The Notebook client sends |delete_session|_ request to Jupyter Server. This + request has the Session ID that kernel is currently using. + +#. **Session Manager** gets the Session data from the SQLite3 database and sends + the kernel ID to **Mapping Kernel Manager**. + +#. **Mapping Kernel Manager** starts the kernel shutdown process by using + **Multi Kernel Manager** and **Kernel Manager**. + +#. **Kernel Manager** determines the mode of interrupt from the + **Kernel Spec Manager**. It supports ``Signal`` and ``Message`` + interrupt modes. By default, the ``Signal`` interrupt mode is being used. + + - When the interrupt mode is ``Signal``, the **Kernel Provisioner** + interrupts the kernel with the ``SIGINT`` operating system signal + (although other provisioner implementations may use a different approach). + + - When interrupt mode is ``Message``, Session sends + the `"interrupt_request" `_ + message on the control channel. + +#. After interrupting kernel, Session sends the `"shutdown_request" `_ + message on the control channel. + +#. **Kernel Manager** waits for the kernel shutdown. After the timeout, and if + it detects the kernel process is still running, the **Kernel Manager** + terminates the kernel sending a ``SIGTERM`` operating system signal + (or provisioner equivalent). If it finds the kernel process has + not terminated, the **Kernel Manager** will follow up with a ``SIGKILL`` + operating system signal (or provisioner equivalent) to ensure the kernel's + termination. + +#. **Kernel Manager** cleans up the kernel resources. It removes kernel's interprocess + communication ports, closes control socket, and releases Shell, IOPub, StdIn, + Control, and Heartbeat ports. + +#. When shutdown is finished, **Session Manager** deletes the Session data from + the SQLite3 database and responses 204 status code to the Notebook client. + +.. _delete_session: https://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/jupyter_server/master/jupyter_server/services/api/api.yaml#/sessions/delete_api_sessions__session_ + +.. |delete_session| replace:: the *DELETE /api/sessions/{session_id}* diff --git a/docs/source/images/session-create.drawio.png b/docs/source/images/session-create.drawio.png new file mode 100644 index 0000000000..a344095ed6 Binary files /dev/null and b/docs/source/images/session-create.drawio.png differ diff --git a/docs/source/images/session-delete.drawio.png b/docs/source/images/session-delete.drawio.png new file mode 100644 index 0000000000..d2093fb1f3 Binary files /dev/null and b/docs/source/images/session-delete.drawio.png differ