Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

JEP for specifying the connectionfile #106

Merged
merged 4 commits into from
Jun 10, 2024
Merged

JEP for specifying the connectionfile #106

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2b3cd2d
JEP for specifying the connectionfile
JohanMabille Apr 22, 2023
9ba6a98
Update connectionfile-spec/connectionfile-spec.md
JohanMabille Feb 26, 2024
e8209ab
Added link to the Jupyter schema repo
JohanMabille Feb 26, 2024
f357187
Used enum instead of string for the signature scheme type
JohanMabille Feb 26, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions connectionfile-spec/connectionfile-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
---
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).

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

None, this JEP only specifies the current implementations.
64 changes: 64 additions & 0 deletions connectionfile-spec/connectionfile.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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": {
"enum": ["hmac-md5","hmac-sha256","hmac-sha512"],
"description": "scheme used to sign the messages"
minrk marked this conversation as resolved.
Show resolved Hide resolved
},
"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"],
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I realize I'm late to this discussion, but I just want to understand it fully before voting: Is the spec as proposed now consistent with https://github.com/jupyter/enhancement-proposals/pull/66/files ? If not, how would the schema evolve to support that? Would these fields no longer be required?

Copy link
Member

@SylvainCorlay SylvainCorlay Jun 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My understanding is that both #105 and #106 represent the current state of things, and that the implementation of #66 would require updating these specs.

Copy link
Contributor

@vidartf vidartf Jun 3, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. My main point was to do a sanity check on whether #66 would require any changes that the spec as it currently is would make harder to implement. It sounds like that isn't a concern, so I voted for.

"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": ["integer","string"],
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth using oneOf to distinguish tcp with integer ports from ipc/inproc where it's really a string suffix (that I believe implementation-wise accepts integers)? Essentially, signal that tcp doesn't accept strings for ports.

Fine if that's more schema complexity that folks want.

"description": "port used by the shell channel"
},
"control_port": {
"type": ["integer","string"],
"description": "port used by the control channel"
},
"stdin_port": {
"type": ["integer","string"],
"description": "port used by the stdin channel"
},
"hb_port": {
"type": ["integer","string"],
"description": "port used by the heartbeat channel"
},
"iopub_port": {
"type": ["ingerer","string"],
"description": "port used by the iopub channel"
}
}
}
},
"allOf": [
{ "$ref": "#/definitions/kernel_network" },
{ "$ref": "#/definitions/signature" }
]
}

Loading