How to structure debug events

[DinoV]

We're proposing that we use the VS debugger protocol as a starting point. There's at least a few different options on how we can embed this.

Generally speaking the messages are in these forms:

{'seq': 1, 'type': 'request', command:'name', 'arguments':{}}
{'seq': 2, 'request_seq': 1, type: 'response', command:'name', arguments:{}}
{'seq': 2, 'type': 'event', success:false, command:'name', message:'error', body:{}}

There are a couple of key differences from the Jupyter message protocol:

• The sequences are incrementing numbers instead of GUIDs
• Jupyter has a 'content' field which is the body of the message
• request/reply are implied by the message type
• The equivalent of "events" are sent on the IOPub channel, and request/reply are on the shell channel

Another key difference between the two protocols is that the Python protocol uses more Pythonic conventions for naming fields and the VS Code protocol uses more JavaScript style naming conventions.

No matter what it's rather obvious that events should be mapped onto IO Pub, and request/reply will be mapped onto channel.

The next question is what to do with the messages themselves. One option would be to simply take the VS Code messages and embed them as content. This would end up looking like:

{
  'header' : {'msg_type':'debug_request'},
  'msg_id' : str,
  'msg_type' : str,
  'parent_header' : dict,
  'content' : {'seq': 1, 'type': 'request', command:'name', 'arguments':{}},
  'metadata' : dict,
}
{
  'header' : {'msg_type':'debug_reply'},
  'msg_id' : str,
  'msg_type' : str,
  'parent_header' : dict,
  'content' : {'seq': 2, 'request_seq': 1, type: 'response', command:'name', arguments:{}},
  'metadata' : dict,
}
{
  'header' : {'msg_type':'debug_event'},
  'msg_id' : str,
  'msg_type' : str,
  'parent_header' : dict,
  'content' : {'seq': 2, 'type': 'event', success:false, command:'name', message:'error', body:{}},,
  'metadata' : dict,
}

This approach would have the advantage of allowing the least amount of work to adapt existing VS Code debuggers into Jupyter. But it ends up with redundancy and isn't the cleanest looking protocol.

The next possibility would be to keep the messages largely unchanged, but to drop the VS Code's sequence and type fields:

{
  'header' : {'msg_type':'debug_request'},
  'msg_id' : str,
  'msg_type' : str,
  'parent_header' : dict,
  'content' : {command:'name', 'arguments':{}},
  'metadata' : dict,
}
{
  'header' : {'msg_type':'debug_reply'},
  'msg_id' : str,
  'msg_type' : str,
  'parent_header' : dict,
  'content' : {command:'name', arguments:{}},
  'metadata' : dict,
}
{
  'header' : {'msg_type':'debug_event'},
  'msg_id' : str,
  'msg_type' : str,
  'parent_header' : dict,
  'content' : {success:false, command:'name', message:'error', body:{}},,
  'metadata' : dict,
}

This would require small changes to existing debugger implementations, but should be relatively straight forward. Another possibility which would require more changes would be breaking out the VS Code commands into their own commands. So instead of having a "debug_event" message there would be a "debug_continued_event" who's content would be:

  'content' : {success:false, message:'error', body:{}},,

Finally there's the question of whether or not the field names should be changed. For example VS Code's process event looks like:

{
'name': 'blah';
'systemProcessId': 1;
'isLocalProcess': true;
'startMethod': 'launch'
};

Should this turn into:

{
'name': string;
'system_process_id': 1;
'is_local_process': true;
'start_method': 'launch'
};

This would probably drastically reduce the amount of code sharing that can be done for existing VS code debuggers.

[jasongrout]

@DinoV - just wanted to say thanks for working on this, and that I think a lot of people are watching this repo with great interest. I often get asked about debugging in JupyterLab, and I redirect people to subscribe to this repo, since it's the first step in getting debugging working.