enso/docs/debugger/protocol.md

layout	title	category	tags	order
developer-doc	Enso Debugger Protocol Message Specification	debugger	repl debugger protocol specification	1

Enso Debugger Protocol Message Specification

Binary Protocol for the Debugger is used in communication between the runtime and tools exploiting the REPL/debugger functionalities. It can be used to implement a simple REPL or add debugging capabilities to the editor.

• Types
  • ObjectRepr
  • StackTraceElement
  • Exception
  • Binding
• Messages
  • Session Start
  • Evaluation
  • List Bindings
  • Session Exit

Types

There are some helper types used within the debugger's protocol. These are specified here.

ObjectRepr

External representation of arbitrary values returned by the REPL (internally these are of type Object).

As these values are only used for presentation, they are represented by String.

interface ObjectRepr {
  representation: String;
}

StackTraceElement

Represents a line of the stack trace. Corresponds to java.lang.StackTraceElement.

interface StackTraceElement {
  declaringClass: String;
  methodName: String;
  fileName: String;
  lineNumber: Int;
}

Exception

Represents an exception that may have been raised during requested execution.

interface Exception {
  message: String;
  stackTrace: [StackTraceElement];
  cause: Exception;
}

Binding

Represents a single binding in the current scope.

interface Binding {
  name: String;
  value: ObjectRepr;
}

Messages

All endpoints accept messages of type Request and return a Response. These messages contain unions that contain the actual payload specified for each type of message.

namespace org.enso.polyglot.debugger.protocol;

union RequestPayload {
    EVALUATE: EvaluationRequest,
    LIST_BINDINGS: ListBindingsRequest,
    SESSION_EXIT: SessionExitRequest
}

table Request {
    payload: RequestPayload (required);
}

union ResponsePayload {
    EVALUATION_SUCCESS: EvaluationSuccess,
    EVALUATION_FAILURE: EvaluationFailure,
    LIST_BINDINGS: ListBindingsResult,
    SESSION_START: SessionStartNotification
}

table Response {
    payload: ResponsePayload (required);
}

Session Start

When a breakpoint is reached, the debugger sends a notification to the client indicating that a REPL session should be started.

The whole REPL session should live inside the endpoint's function handling this notification. This means that this function should not return before sending the session exit request.

Notification

namespace org.enso.polyglot.protocol.debugger;

table SessionStartNotification {}

Evaluation

Evaluates an arbitrary expression in the current execution context.

Responds with either a message with the value of successfully evaluated expression or a message with an exception that has been raised during evaluation.

Request

namespace org.enso.polyglot.protocol.debugger;

table ReplEvaluationRequest {
  expression: String (required);
}

Response

namespace org.enso.polyglot.protocol.debugger;

table ReplEvaluationSuccess {
  result: ObjectRepr (required);
}

table ReplEvaluationFailure {
  exception: Exception (required);
}

List Bindings

Lists all the bindings available in the current execution scope and sends them back.

Request

namespace org.enso.polyglot.protocol.debugger;

table ReplListBindingsRequest {}

Response

namespace org.enso.polyglot.protocol.debugger;

table ReplListBindingsResult {
  bindings: [Binding];
}

Session Exit

Terminates this REPL session (and resumes normal program execution).

The last result of Evaluation will be returned from the instrumented node or if no expressions have been evaluated, unit is returned.

This request must always be sent at the end of REPL session, as otherwise the program will never resume. It does not return any response. It is important to note that a thread calling sendBinary with this message will never return, as control will be passed to the interpreter.

Request

namespace org.enso.polyglot.protocol.debugger;

table ReplExitRequest {}