From 2b3cd2d1380096e564b7dc782e6a9846de405183 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Sat, 22 Apr 2023 22:20:25 +0200 Subject: [PATCH 1/4] JEP for specifying the connectionfile --- connectionfile-spec/connectionfile-spec.md | 25 ++++++++ .../connectionfile.schema.json | 64 +++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 connectionfile-spec/connectionfile-spec.md create mode 100644 connectionfile-spec/connectionfile.schema.json diff --git a/connectionfile-spec/connectionfile-spec.md b/connectionfile-spec/connectionfile-spec.md new file mode 100644 index 00000000..fedc7387 --- /dev/null +++ b/connectionfile-spec/connectionfile-spec.md @@ -0,0 +1,25 @@ +--- +title: connection file specification +authors: Johan Mabille +issue-number: XX +pr-number: XX +date-started: "2023-04-19" +--- + +# Specification of the connection file + +## Problem + +The connection file is [documented](https://github.com/jupyter/jupyter_client/blob/main/docs/kernels.rst) aside the kernel protocol documentation, but it is not *specified*. + +## Proposed Enhancement + +We propose to specify the connection file with the JSON schema joined in this PR. The specification would reflect +[the current description of the connection file](https://jupyter-client.readthedocs.io/en/stable/kernels.html#connection-files), +and adds an optional `kernel_protocol_version` field. + +The specification and the documentation of the connectio filewill be stored aside [those of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol) + +### Impact on existing implementations + +None, this JEP only specifies the current implementations. diff --git a/connectionfile-spec/connectionfile.schema.json b/connectionfile-spec/connectionfile.schema.json new file mode 100644 index 00000000..25db0481 --- /dev/null +++ b/connectionfile-spec/connectionfile.schema.json @@ -0,0 +1,64 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schema.jupyter.org/connectionfile-v1.0.schema.json", + "title": "Jupyter Connection File", + "description": "A description of the data required to connect and send messages to a Jupyter Kernel", + "type": "object", + + "definitions": { + "signature": { + "type": "object", + "required": ["signature_scheme", "key"], + "properties": { + "signature_scheme": { + "type": "string", + "description": "scheme used to sign the messages" + }, + "key": { + "type": "string", + "description": "key used to sign the messages" + } + } + }, + "kernel_network": { + "type": "object", + "required": ["transport", "ip", "shell_port", "control_port", "stdin_port", "hb_port", "iopub_port"], + "properties": { + "transport": { + "type": "string", + "description": "transport protocol", + "enum": ["tcp", "ipc", "inproc"] + }, + "ip": { + "type": "string", + "description": "ip of the machine where the kernel runs" + }, + "shell_port": { + "type": "string", + "description": "port used by the shell channel" + }, + "control_port": { + "type": "string", + "description": "port used by the control channel" + }, + "stdin_port": { + "type": "string", + "description": "port used by the stdin channel" + }, + "hb_port": { + "type": "string", + "description": "port used by the heartbeat channel" + }, + "iopub_port": { + "type": "string", + "description": "port used by the iopub channel" + } + } + } + }, + "allOf": [ + { "$ref": "#/definitions/kernel_network" }, + { "$ref": "#/definitions/signature" } + ] +} + From 9ba6a98fa780e9de0a44db270e0986cb47990b0b Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 26 Feb 2024 21:51:18 +0100 Subject: [PATCH 2/4] Update connectionfile-spec/connectionfile-spec.md Co-authored-by: Min RK --- connectionfile-spec/connectionfile-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/connectionfile-spec/connectionfile-spec.md b/connectionfile-spec/connectionfile-spec.md index fedc7387..96126c2f 100644 --- a/connectionfile-spec/connectionfile-spec.md +++ b/connectionfile-spec/connectionfile-spec.md @@ -18,7 +18,7 @@ We propose to specify the connection file with the JSON schema joined in this PR [the current description of the connection file](https://jupyter-client.readthedocs.io/en/stable/kernels.html#connection-files), and adds an optional `kernel_protocol_version` field. -The specification and the documentation of the connectio filewill be stored aside [those of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol) +The specification and the documentation of the connection file will be stored along side [those of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol) ### Impact on existing implementations From e8209abadeb3d9aab49c9416781085d323824371 Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 26 Feb 2024 21:55:15 +0100 Subject: [PATCH 3/4] Added link to the Jupyter schema repo --- connectionfile-spec/connectionfile-spec.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/connectionfile-spec/connectionfile-spec.md b/connectionfile-spec/connectionfile-spec.md index 96126c2f..657371a4 100644 --- a/connectionfile-spec/connectionfile-spec.md +++ b/connectionfile-spec/connectionfile-spec.md @@ -15,10 +15,9 @@ The connection file is [documented](https://github.com/jupyter/jupyter_client/bl ## Proposed Enhancement We propose to specify the connection file with the JSON schema joined in this PR. The specification would reflect -[the current description of the connection file](https://jupyter-client.readthedocs.io/en/stable/kernels.html#connection-files), -and adds an optional `kernel_protocol_version` field. +[the current description of the connection file](https://jupyter-client.readthedocs.io/en/stable/kernels.html#connection-files). -The specification and the documentation of the connection file will be stored along side [those of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol) +The documentation of the connection file will be stored along side [those of the kernel protocol](https://github.com/jupyter-standards/kernel-protocol) while its specification will be stored in the [Jupyter schema repo](https://github.com/jupyter/schema). ### Impact on existing implementations From f357187f6cea3bd412e16c4fb3b3c45d5334ec2a Mon Sep 17 00:00:00 2001 From: Johan Mabille Date: Mon, 26 Feb 2024 22:30:22 +0100 Subject: [PATCH 4/4] Used enum instead of string for the signature scheme type --- connectionfile-spec/connectionfile.schema.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/connectionfile-spec/connectionfile.schema.json b/connectionfile-spec/connectionfile.schema.json index 25db0481..3cc818cc 100644 --- a/connectionfile-spec/connectionfile.schema.json +++ b/connectionfile-spec/connectionfile.schema.json @@ -11,7 +11,7 @@ "required": ["signature_scheme", "key"], "properties": { "signature_scheme": { - "type": "string", + "enum": ["hmac-md5","hmac-sha256","hmac-sha512"], "description": "scheme used to sign the messages" }, "key": { @@ -34,23 +34,23 @@ "description": "ip of the machine where the kernel runs" }, "shell_port": { - "type": "string", + "type": ["integer","string"], "description": "port used by the shell channel" }, "control_port": { - "type": "string", + "type": ["integer","string"], "description": "port used by the control channel" }, "stdin_port": { - "type": "string", + "type": ["integer","string"], "description": "port used by the stdin channel" }, "hb_port": { - "type": "string", + "type": ["integer","string"], "description": "port used by the heartbeat channel" }, "iopub_port": { - "type": "string", + "type": ["ingerer","string"], "description": "port used by the iopub channel" } }