IKPdb Protocol

IKPdb communicates with debugging clients by exchanging JSON messages over a TCP socket. All exchanges between the debugger and clients are managed by the ikpdb.IKPdbConnectionHandler class.

Protocol overview

Here is a typical message flow between IKPdb and a client.

Client   IKPdb
  sends “welcome” message
sends “setBreakpoint” message  
sends “runScript” message  
  sends “programBreak” message
sends “setVariable” message  
sends “resume” message  
  sends “programEnd” message

Protocol description

As an overview, IKPdb waits for “command” messages from clients and reply with “response” messages. IKPdb also sends “event” messages to client when debugged program reach a breakpoint or raise an exception.

Packet description

IKpdb and remote client exchanges messages having this structure:

"length={{integer length of json_dump_of_message_body hereafter}}{{MAGIC_CODE}}{{json_dump_of_message_body}}"

Take a look at ikpdb.IKPdbConnectionHandler for details.

Please note that json_dump_of_message will soon be encoded.

Format of “command” messages sent by clients to IKPdb

Messages received by IKPdb follow this structure:

    "_id": an_integer, # Unique identifier of the command, used to link commands and replies
    "command": command_name_as_str,  # eg. "runScript"
    "args": {
        # a dict containing command's specific parameters

Format of “reply” messages sent by IKPdb

Replies sent by IKPdb follow this structure:

    "_id": an_integer,  # _id of the origin command
    "command": command_name_as_str,  # origin command eg. "runScript"
    "result": {
        # Updated status of debugged program when the reply is sent
        "executionStatus": "running" #  or "stopped" or "terminated",

    "commandExecStatus": "ok" or "error",  # depends on command execution success
    "info_messages": a_list_of_str,
    "warning_messages": another_list_of_str,
    "error_messages": yet_another_list_of_str,

Format of “event” messages sent by IKPdb

Event messages sent by IKPdb follow this structure:

    "_id": an_integer,  # _id of the origin command
    "command": "{{command_name}}",
    "result": {}
    "commandExecStatus": "ok"  # always "ok" for event
    "info_messages": a_list_of_str,
    "warning_messages": another_list_of_str,
    "error_messages": yet_another_list_of_str,
    "frames": [
        # Complete stack dump, see below.
    "exception": {
        "type": exception_name_as_str,
        "info": exception_message_as_str

For detail about frames and exception, take a look at dump_frames().

Messages string

IKPdp sends 3 king of messages to clients: warning, info and error. Usage of these messages is left to the client implementation. For example in Cloud9:

  • info_messages are displayed using console.log()
  • warning_messages are displayed using notification bubbles
  • error_messages are displayed in a red banner at the top of the window (using cloud9 showError API)

Debugged program execution status

All messages related to debugged program execution modifications add an executionStatus key in the result dict.

Possible values for executionStatus are:

  • “stopped” (break or exception)
  • “running”
  • “terminated”

IKPdb command list summary

Here is the list (in no particular order) of commands supported by IKPdb. For detailed parameters description, please look have a look at IKPdb code especially command_loop() and ikpdb.main().

In next table Way is expressed from IKPdb point of view. “in” means received by IKPdb (and sent by client).

Command Way Description Update executionStatus?
“changeBreakpointState” in Ask IKPdb to modify an existing breakpoint  
“clearBreakpoint” in Ask IKPdb to delete a breakpoint.  
“evaluate” in Evaluate an expression or statement in the context of debugged program and return result. Yes
“getBreakpoints” in Ask IKPdb to return a list of all defined breakpoints  
“getProperties” in Ask IKPdb to the properties or members of a compound variable. This allows client to lay load huge variables or dict Yes
“programBreak” out Sent by IKPdb when debugged program has reached a breakpoint or raised an exception. Yes: “stoped”
“programEnd” out Sent when debugged program exited contains the exit code if any. Yes: “Terminated”
“resume” in Sent by the client to resume execution of a paused debugged program. Yes: “Running”
“runScript” in Start execution of debugged program. Yes
“setVariable” in Ask IKPdb to modify value of a stack frame variable. Yes
“stepOver” in   Yes: “Running”
“setBreakpoints” in Ask IKPdb to set a breakpoint.  
“stepInto” in   Yes: “Running”
“stepOut” in   Yes: “Running”
“suspend” in Sent by the client, if user requests to pause debugged program. Yes: “Running”
“welcome” out A welcome message with IKPDb version sent at client connection.