From 88b33efed00dfe7ea569a7281ea2ad718b333b0f Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Tue, 5 Jan 2021 16:10:16 +0100 Subject: [PATCH 01/14] Kernel handshaking pattern proposal --- jupyter-handshaking/jupyter-handshaking.md | 54 ++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 jupyter-handshaking/jupyter-handshaking.md diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md new file mode 100644 index 00000000..270dcded --- /dev/null +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -0,0 +1,54 @@ +# Kernel Handshaking pattern + +## Problem + +The current implementation of Jupyter client makes it responsible for finding available ports and pass them to a new starting kernel. The issue is that a new process can start using one of these ports before the kernel has started, resulting in a ZMQError when the kernel starts. This is even more problematic when spawning a lot of kernels in a short laps of time, because the client may find available ports that have already been assigned to another kernel. + +A workaround has been implemented for the latter case, but it does not solve the former one. + +## Proposed Enhancement + +We propose to implement a handshaking pattern: the client lets the kernel find free ports and communicate them back via a dedicated socket. It then connects to the kernel. More formely: + +- When the client starts, it opens a dedicated socket A for receiving connection information from kernels (channel ports). +- When launching a new kernel, the client passes its address and the port of this socket to the kernel. +- The kernel starts, find free ports to bind the shell, control, stdin, heartbeat and iopub sockets. It then connect to the A socket and send the connection information to the client. +- Upon reception of the connection information, the client connects to the kernel. + +The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for distant kernels (although this requires an intermediate actor such as a gateway). + +- A new field "kernel_handshake" would be added to the kernelspec specifying whether the said kernel supports the new mechanism. +- In this case, the connection file passed to the kernel will specify the handshake port instead of the ports for the different channels. +- The kernel adds the port numbers for the different channels to the connection file, so that other clients can connect to the kernel. + +If the new field "kernel_handshake" is missing from the kernelspec, the clients should emit a warning, and assume that the new mechanisms is not supported, and recommend that the key is added to the kernelspec. + +### Impact on existing implementations + +Although this enhancement requires changing all the existing kernels, the impact should be limited. Indeed, most of the kernels are based on the kernel wrapper approach, or on xeus. + +Most of the clients are based on `jupyter_client`. Therefore, the changes should be limited to this repository only. + +A transition period where clients and kernels support both mechanisms should allow kernels to gradually migrate to the new version of the protocol. The support of the handshaking pattern should be indicated in the kernelspec. + +## Relevant Resources (GitHub repositories, Issues, PRs) + +### GitHub repositories + +- Jupyter Client: https://github.com/jupyter/jupyter_client +The Jupyter protocol client APIs +- Voilà: https://github.com/voila-dashboards/voila +Voilà turns Jupyter notebooks into standalone web applications +- IPyKernel: https://github.com/ipython/ipykernel +IPython kernel for Jupyter +- Xeus: https://github.com/jupyter-xeus/xeus +The C++ implementation of the Jupyter kernel protocol + +### GitHub Issues + +- Spawning many kernels may result in ZMQError (https://github.com/jupyter/jupyter_client/issues/487) +- Spawning ~20 requests at a time results in a ZMQError (https://github.com/voila-dashboards/voila/issues/408#issuecomment-539968325) + +### GitHub Pull Requests + +- Prevent two kernels to have the same ports (https://github.com/jupyter/jupyter_client/pull/490) From 9ebe5b70ae849cb444c5b2b98e08f93080021f49 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Tue, 5 Jan 2021 21:26:36 +0100 Subject: [PATCH 02/14] Channel ports should be added to the connection file by the client, not the kernel --- jupyter-handshaking/jupyter-handshaking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index 270dcded..18704a42 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -19,7 +19,7 @@ The way the client passes its address and the port of the listening socket to th - A new field "kernel_handshake" would be added to the kernelspec specifying whether the said kernel supports the new mechanism. - In this case, the connection file passed to the kernel will specify the handshake port instead of the ports for the different channels. -- The kernel adds the port numbers for the different channels to the connection file, so that other clients can connect to the kernel. +- When the client receives the port numbers for the different channels from the kernel, it adds them the connection file, so that other clients can connect to the kernel. If the new field "kernel_handshake" is missing from the kernelspec, the clients should emit a warning, and assume that the new mechanisms is not supported, and recommend that the key is added to the kernelspec. From 93e61ca8bf3f4110c674b2866df21b293c0fccd4 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Sat, 9 Jan 2021 01:07:09 +0100 Subject: [PATCH 03/14] Updated JEP: added client address and kernel token to the connection file --- jupyter-handshaking/jupyter-handshaking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index 18704a42..cfb688c8 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -18,7 +18,7 @@ We propose to implement a handshaking pattern: the client lets the kernel find f The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for distant kernels (although this requires an intermediate actor such as a gateway). - A new field "kernel_handshake" would be added to the kernelspec specifying whether the said kernel supports the new mechanism. -- In this case, the connection file passed to the kernel will specify the handshake port instead of the ports for the different channels. +- In this case, the connection file passed to the kernel will specify the handshake port instead of the ports for the different channels. The connection file will also specify the address of the client, and a token used to identify the kernel. - When the client receives the port numbers for the different channels from the kernel, it adds them the connection file, so that other clients can connect to the kernel. If the new field "kernel_handshake" is missing from the kernelspec, the clients should emit a warning, and assume that the new mechanisms is not supported, and recommend that the key is added to the kernelspec. From ed24523665f4c367f4c9004146f569a834880695 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 11 Jan 2021 10:02:22 +0100 Subject: [PATCH 04/14] Added more precision regarding the kernelspec --- jupyter-handshaking/jupyter-handshaking.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index cfb688c8..c366e441 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -17,7 +17,10 @@ We propose to implement a handshaking pattern: the client lets the kernel find f The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for distant kernels (although this requires an intermediate actor such as a gateway). -- A new field "kernel_handshake" would be added to the kernelspec specifying whether the said kernel supports the new mechanism. +- A new field "kernel_startup_protocol_version" would be added to the metadata section of the kernelspec. It accepts the following values: + - `0`: supports passing ports only (assumed if unspecified) + - `1`: supports both handshake and passing ports + - `2`: supports handshake only (future value, if we decide to remove the current mechanism) - In this case, the connection file passed to the kernel will specify the handshake port instead of the ports for the different channels. The connection file will also specify the address of the client, and a token used to identify the kernel. - When the client receives the port numbers for the different channels from the kernel, it adds them the connection file, so that other clients can connect to the kernel. From 033118430a7bccfefd323c92656a7d52b6a28147 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 11 Jan 2021 22:14:07 +0100 Subject: [PATCH 05/14] Removed third value of kernel_startup_protocol_version --- jupyter-handshaking/jupyter-handshaking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index c366e441..66462a5b 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -20,7 +20,7 @@ The way the client passes its address and the port of the listening socket to th - A new field "kernel_startup_protocol_version" would be added to the metadata section of the kernelspec. It accepts the following values: - `0`: supports passing ports only (assumed if unspecified) - `1`: supports both handshake and passing ports - - `2`: supports handshake only (future value, if we decide to remove the current mechanism) + Enventually, a later version of the protocol (eg 2) may drop the support for passing the port numbers. - In this case, the connection file passed to the kernel will specify the handshake port instead of the ports for the different channels. The connection file will also specify the address of the client, and a token used to identify the kernel. - When the client receives the port numbers for the different channels from the kernel, it adds them the connection file, so that other clients can connect to the kernel. From 920c07f979128a5420087fb7bb68d95e210b5ddd Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Wed, 19 Apr 2023 11:32:36 +0200 Subject: [PATCH 06/14] Changed how kernels indicate which connection pattern they support --- jupyter-handshaking/jupyter-handshaking.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index 66462a5b..9181b627 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -17,14 +17,10 @@ We propose to implement a handshaking pattern: the client lets the kernel find f The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for distant kernels (although this requires an intermediate actor such as a gateway). -- A new field "kernel_startup_protocol_version" would be added to the metadata section of the kernelspec. It accepts the following values: - - `0`: supports passing ports only (assumed if unspecified) - - `1`: supports both handshake and passing ports - Enventually, a later version of the protocol (eg 2) may drop the support for passing the port numbers. -- In this case, the connection file passed to the kernel will specify the handshake port instead of the ports for the different channels. The connection file will also specify the address of the client, and a token used to identify the kernel. -- When the client receives the port numbers for the different channels from the kernel, it adds them the connection file, so that other clients can connect to the kernel. - -If the new field "kernel_handshake" is missing from the kernelspec, the clients should emit a warning, and assume that the new mechanisms is not supported, and recommend that the key is added to the kernelspec. +The kernel specifies whether it supports the handshake pattern via the "protocol_version" field in the kernelspec: +- if the field is missing, or if its value if less than 5.5, the kernel supports passing ports only. +- if the field value is >=5.5 and <6, the kernel supports both mechanisms. +- if the field value is >=6, the kernel supports the handshake pattern. Clients should not assume the kernel still supports the old mechanism. ### Impact on existing implementations From 2f13d4d4e3b1d26b6e0ceeadace580f1c5c2663f Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Wed, 19 Apr 2023 15:57:05 +0200 Subject: [PATCH 07/14] protocol_version => kernel_protocol_version --- jupyter-handshaking/jupyter-handshaking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index 9181b627..2ee1eb92 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -17,7 +17,7 @@ We propose to implement a handshaking pattern: the client lets the kernel find f The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for distant kernels (although this requires an intermediate actor such as a gateway). -The kernel specifies whether it supports the handshake pattern via the "protocol_version" field in the kernelspec: +The kernel specifies whether it supports the handshake pattern via the "kernel_protocol_version" field in the kernelspec: - if the field is missing, or if its value if less than 5.5, the kernel supports passing ports only. - if the field value is >=5.5 and <6, the kernel supports both mechanisms. - if the field value is >=6, the kernel supports the handshake pattern. Clients should not assume the kernel still supports the old mechanism. From a1fdffa08cfdcd0ff601780d004e2fb76e69771e Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Thu, 20 Apr 2023 22:09:32 +0200 Subject: [PATCH 08/14] Replaced gateway server with provisioner --- jupyter-handshaking/jupyter-handshaking.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index 2ee1eb92..7ed79dd2 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -15,7 +15,7 @@ We propose to implement a handshaking pattern: the client lets the kernel find f - The kernel starts, find free ports to bind the shell, control, stdin, heartbeat and iopub sockets. It then connect to the A socket and send the connection information to the client. - Upon reception of the connection information, the client connects to the kernel. -The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for distant kernels (although this requires an intermediate actor such as a gateway). +The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for remote kernels (although this requires a custom kernel provisioner or "nanny"). The kernel specifies whether it supports the handshake pattern via the "kernel_protocol_version" field in the kernelspec: - if the field is missing, or if its value if less than 5.5, the kernel supports passing ports only. @@ -26,9 +26,9 @@ The kernel specifies whether it supports the handshake pattern via the "kernel_p Although this enhancement requires changing all the existing kernels, the impact should be limited. Indeed, most of the kernels are based on the kernel wrapper approach, or on xeus. -Most of the clients are based on `jupyter_client`. Therefore, the changes should be limited to this repository only. +Most of the clients are based on `jupyter_client`. Therefore, the changes should only be limited to this repository or external kernel provisioners. -A transition period where clients and kernels support both mechanisms should allow kernels to gradually migrate to the new version of the protocol. The support of the handshaking pattern should be indicated in the kernelspec. +A transition period where clients and kernels support both mechanisms should allow kernels to gradually migrate to the new version of the protocol. Support for the handshaking pattern is indicated in the kernelspec via `kernel_protocol_version` as stated above. ## Relevant Resources (GitHub repositories, Issues, PRs) From 1bc2a7f1714fafe17cadc8486dbb5a27ad8bdc9a Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Sat, 22 Apr 2023 18:57:19 +0200 Subject: [PATCH 09/14] Updated JEP --- jupyter-handshaking/jupyter-handshaking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index 7ed79dd2..ec1c1c56 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -15,7 +15,7 @@ We propose to implement a handshaking pattern: the client lets the kernel find f - The kernel starts, find free ports to bind the shell, control, stdin, heartbeat and iopub sockets. It then connect to the A socket and send the connection information to the client. - Upon reception of the connection information, the client connects to the kernel. -The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for remote kernels (although this requires a custom kernel provisioner or "nanny"). +The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for remote kernels (although this requires a custom kernel provisioner or "nanny"). This connection file should also contain the signature scheme and the key. The kernel specifies whether it supports the handshake pattern via the "kernel_protocol_version" field in the kernelspec: - if the field is missing, or if its value if less than 5.5, the kernel supports passing ports only. From 6eb4ff5ba986b2a19648fb03312d4ab16f9fce0b Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Sat, 22 Apr 2023 23:12:51 +0200 Subject: [PATCH 10/14] Dropped the removal of the current connection pattern --- jupyter-handshaking/jupyter-handshaking.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index ec1c1c56..7305ee23 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -19,8 +19,7 @@ The way the client passes its address and the port of the listening socket to th The kernel specifies whether it supports the handshake pattern via the "kernel_protocol_version" field in the kernelspec: - if the field is missing, or if its value if less than 5.5, the kernel supports passing ports only. -- if the field value is >=5.5 and <6, the kernel supports both mechanisms. -- if the field value is >=6, the kernel supports the handshake pattern. Clients should not assume the kernel still supports the old mechanism. +- if the field value is >=5.5, the kernel supports both mechanisms. ### Impact on existing implementations @@ -28,8 +27,6 @@ Although this enhancement requires changing all the existing kernels, the impact Most of the clients are based on `jupyter_client`. Therefore, the changes should only be limited to this repository or external kernel provisioners. -A transition period where clients and kernels support both mechanisms should allow kernels to gradually migrate to the new version of the protocol. Support for the handshaking pattern is indicated in the kernelspec via `kernel_protocol_version` as stated above. - ## Relevant Resources (GitHub repositories, Issues, PRs) ### GitHub repositories From 5d4d257546b8d17e1b8e1fbfc77c9bc2816bcb7a Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Fri, 12 May 2023 16:03:07 +0200 Subject: [PATCH 11/14] Changes according last discussions and meetings --- jupyter-handshaking/jupyter-handshaking.md | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index 7305ee23..13ccd0bd 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -10,17 +10,26 @@ A workaround has been implemented for the latter case, but it does not solve the We propose to implement a handshaking pattern: the client lets the kernel find free ports and communicate them back via a dedicated socket. It then connects to the kernel. More formely: -- When the client starts, it opens a dedicated socket A for receiving connection information from kernels (channel ports). -- When launching a new kernel, the client passes its address and the port of this socket to the kernel. -- The kernel starts, find free ports to bind the shell, control, stdin, heartbeat and iopub sockets. It then connect to the A socket and send the connection information to the client. +- The kernel launcher is responsible for opening a dedicated socket for receiving connection information from kernels (channel ports). This socket will be refered as the registration socket. +- When starting a new kernel, the launcher passes the connection information for this socket to the kernel. +- The kernel starts, find free ports to bind the shell, control, stdin, heartbeat and iopub sockets. It then connect to the registration socket and send the connection information to the client. - Upon reception of the connection information, the client connects to the kernel. -The way the client passes its address and the port of the listening socket to the kernel should be similar to that of passing the ports of the kernel socket in the current implementation: a connection file that can be read by local kernels or sent over the network for remote kernels (although this requires a custom kernel provisioner or "nanny"). This connection file should also contain the signature scheme and the key. +The way the launcher passes the connection information for the registration socket to the kernel should be similar to that of passing the ports of the kernel socket in the current connection pattern: a connection file that can be read by local kernels or sent over the network for remote kernels (although this requires a custom kernel provisioner or "nanny"). This connection file should also contain the signature scheme and the key. + +The kernel should not expect the registration socket to exist after it has sent its registration (i.e. it can be closed). Therefore, the kernel should disconnect from the registration socket right after it has sent its connection information. The kernel specifies whether it supports the handshake pattern via the "kernel_protocol_version" field in the kernelspec: - if the field is missing, or if its value if less than 5.5, the kernel supports passing ports only. - if the field value is >=5.5, the kernel supports both mechanisms. +### Remarks + +This pattern is **NOT** a replacement for the current connection pattern. It is an additional one and kernels will have to implement both of them to be conformant to the Juyter Kernel Protocol specification. Which pattern should be used for the connection if decided by the kernel launcher, depending on the information passed in the initial connection file. + + +A recommended implementation for a multi-kernel client (i.e. jupyter-server) is to have a single long-lived registration socket. + ### Impact on existing implementations Although this enhancement requires changing all the existing kernels, the impact should be limited. Indeed, most of the kernels are based on the kernel wrapper approach, or on xeus. From aff6a5f419c47b351e308ccdffbf4b9fdad0b194 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Thu, 25 May 2023 21:25:09 +0200 Subject: [PATCH 12/14] Changes according to review --- jupyter-handshaking/jupyter-handshaking.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index 13ccd0bd..429558f5 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -8,16 +8,16 @@ A workaround has been implemented for the latter case, but it does not solve the ## Proposed Enhancement -We propose to implement a handshaking pattern: the client lets the kernel find free ports and communicate them back via a dedicated socket. It then connects to the kernel. More formely: +We propose to implement a handshaking pattern: the client lets the kernel find free ports and communicate them back via a dedicated socket. It then connects to the kernel. More formally: -- The kernel launcher is responsible for opening a dedicated socket for receiving connection information from kernels (channel ports). This socket will be refered as the registration socket. +- The kernel launcher is responsible for opening a dedicated socket for receiving connection information from kernels (channel ports). This socket will be referred as the **registration socket**. - When starting a new kernel, the launcher passes the connection information for this socket to the kernel. -- The kernel starts, find free ports to bind the shell, control, stdin, heartbeat and iopub sockets. It then connect to the registration socket and send the connection information to the client. -- Upon reception of the connection information, the client connects to the kernel. +- The kernel starts, finds free ports to bind the shell, control, stdin, heartbeat and iopub sockets. It then connects to the registration socket and sends the connection information to the registration socket. +- Upon reception of the connection information, the launcher sends an acknowledge receipt to the kernel, and the client connects to the kernel. The way the launcher passes the connection information for the registration socket to the kernel should be similar to that of passing the ports of the kernel socket in the current connection pattern: a connection file that can be read by local kernels or sent over the network for remote kernels (although this requires a custom kernel provisioner or "nanny"). This connection file should also contain the signature scheme and the key. -The kernel should not expect the registration socket to exist after it has sent its registration (i.e. it can be closed). Therefore, the kernel should disconnect from the registration socket right after it has sent its connection information. +The kernel should not expect the registration socket to exist after it has received the acknowledge receipt (i.e. it can be closed). Therefore, the kernel should disconnect from the registration socket right after it has received the acknowledge receipt. A kernel should shutdown itself if it does not receive an acknowledge receipt after some time (the value of the time limit is let to the implementation). The kernel specifies whether it supports the handshake pattern via the "kernel_protocol_version" field in the kernelspec: - if the field is missing, or if its value if less than 5.5, the kernel supports passing ports only. @@ -25,7 +25,7 @@ The kernel specifies whether it supports the handshake pattern via the "kernel_p ### Remarks -This pattern is **NOT** a replacement for the current connection pattern. It is an additional one and kernels will have to implement both of them to be conformant to the Juyter Kernel Protocol specification. Which pattern should be used for the connection if decided by the kernel launcher, depending on the information passed in the initial connection file. +This pattern is **NOT** a replacement for the current connection pattern. It is an additional one and kernels will have to implement both of them to be conformant to the Jupyter Kernel Protocol specification. Which pattern should be used for the connection is decided by the kernel launcher, depending on the information passed in the initial connection file. A recommended implementation for a multi-kernel client (i.e. jupyter-server) is to have a single long-lived registration socket. From 6cd6e7f3fceb30f842030f2860ac10ddf30028e2 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Thu, 15 Jun 2023 17:42:40 +0200 Subject: [PATCH 13/14] Kernel should dump its connection information --- jupyter-handshaking/jupyter-handshaking.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index 429558f5..fb66b30b 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -1,3 +1,11 @@ +--- +title: Kernel Handshaking pattern +authors: Johan Mabille (@JohanMabille) +issue-number: +pr-number: 66 +date-started: 2021-01-05 +--- + # Kernel Handshaking pattern ## Problem @@ -19,6 +27,8 @@ The way the launcher passes the connection information for the registration sock The kernel should not expect the registration socket to exist after it has received the acknowledge receipt (i.e. it can be closed). Therefore, the kernel should disconnect from the registration socket right after it has received the acknowledge receipt. A kernel should shutdown itself if it does not receive an acknowledge receipt after some time (the value of the time limit is let to the implementation). +The kernel should write its connection information in a connection file so that other clients can connect to it. + The kernel specifies whether it supports the handshake pattern via the "kernel_protocol_version" field in the kernelspec: - if the field is missing, or if its value if less than 5.5, the kernel supports passing ports only. - if the field value is >=5.5, the kernel supports both mechanisms. From 6619122ddcf14b3181feb70a4546180362d1b650 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 19 Jun 2023 14:31:43 +0200 Subject: [PATCH 14/14] Taking into account kernel restarts --- jupyter-handshaking/jupyter-handshaking.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/jupyter-handshaking/jupyter-handshaking.md b/jupyter-handshaking/jupyter-handshaking.md index fb66b30b..feb6f9d1 100644 --- a/jupyter-handshaking/jupyter-handshaking.md +++ b/jupyter-handshaking/jupyter-handshaking.md @@ -25,7 +25,10 @@ We propose to implement a handshaking pattern: the client lets the kernel find f The way the launcher passes the connection information for the registration socket to the kernel should be similar to that of passing the ports of the kernel socket in the current connection pattern: a connection file that can be read by local kernels or sent over the network for remote kernels (although this requires a custom kernel provisioner or "nanny"). This connection file should also contain the signature scheme and the key. -The kernel should not expect the registration socket to exist after it has received the acknowledge receipt (i.e. it can be closed). Therefore, the kernel should disconnect from the registration socket right after it has received the acknowledge receipt. A kernel should shutdown itself if it does not receive an acknowledge receipt after some time (the value of the time limit is let to the implementation). +Reagarding the registration socket lifetime: + +- The kernel launcher MAY close the registration socket after completing a kernel's registration. Therefore, the kernel should disconnect from the registration socket right after it has received the acknowledge receipt. A kernel should shutdown itself if it does not receive an acknowledge receipt after some time (the value of the time limit is let to the implementation). +- To restart a kernel will require the registration socket again, so the kernel launcher SHOULD keep the registration socket open if it expects restarts to be possible, or open a new socket and pass the new registration socket URL to the new process. The kernel should write its connection information in a connection file so that other clients can connect to it.