// Copyright 2017 The Bazel Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package skylark_debugging;

option java_package = "com.google.devtools.build.lib.skylarkdebugging";
option java_outer_classname = "SkylarkDebuggingProtos";

// A request sent by the debug client to the debug server.
message DebugRequest {
  // A number (intended to be sequentially generated by the client) that
  // identifies the request. The response sent by the server will contain the
  // same sequence number so that the client can synchronize its activity if
  // desired.
  int64 sequence_number = 1;

  // The payload describes the type of the request and its arguments, if any.
  oneof payload {
    ListThreadsRequest list_threads = 100;
    SetBreakpointsRequest set_breakpoints = 101;
    ContinueExecutionRequest continue_execution = 102;
    EvaluateRequest evaluate = 103;
    ListFramesRequest list_frames = 104;
    StartDebuggingRequest start_debugging = 105;
    PauseThreadRequest pause_thread = 106;
  }
}

// A request to list the threads that are currently active running Skylark code.
message ListThreadsRequest {
}

// A request to update the breakpoints used by the debug server.
message SetBreakpointsRequest {
  // The breakpoints that describe where the debug server should pause
  // evaluation.
  repeated Breakpoint breakpoint = 1;
}

// A request to continue execution on a paused thread.
message ContinueExecutionRequest {
  // The identifier of the thread to continue.
  //
  // If this field is not set (i.e., zero), then execution of all threads will
  // be continued. This is typically used when the debugger disconnects from the
  // server. In this case, the stepping field is ignored.
  int64 thread_id = 1;

  // Describes the stepping behavior to use when continuing execution.
  Stepping stepping = 2;
}

// A request to evaluate a Skylark expression in a thread's current environment.
message EvaluateRequest {
  // The identifier of the thread in whose execution context the expression
  // should be evaluated.
  int64 thread_id = 1;

  // The Skylark expression to evaluate.
  string expression = 2;
}

// A request to list the stack frames of a thread.
message ListFramesRequest {
  // The identifier of the thread whose stack frames should be listed.
  int64 thread_id = 1;
}

// A request to begin the debugging session. Skylark execution will block until
// this request is made, to allow initial setup after the connection is
// established (e.g. setting breakpoints).
message StartDebuggingRequest {
}

// A request to pause execution of a thread, or all threads.
message PauseThreadRequest {
  // The identifier of the thread to be paused.
  //
  // If not set (i.e. zero), all current and future Skylark threads will be
  // paused until resumed via a ContinueExecutionRequest.
  int64 thread_id = 1;
}

// There are two kinds of events: "responses", which correspond to a
// DebugRequest sent by the client, and other asynchronous events that may be
// sent by the server to notify the client of activity in the Skylark code being
// debugged.
message DebugEvent {
  // If non-zero, this event is a response to a DebugRequest with the same
  // sequence number.
  int64 sequence_number = 1;

  // The payload describes the type of event and any additional information
  // about the event.
  oneof payload {
    Error error = 99;

    ListThreadsResponse list_threads = 100;
    SetBreakpointsResponse set_breakpoints = 101;
    ContinueExecutionResponse continue_execution = 102;
    EvaluateResponse evaluate = 103;
    ListFramesResponse list_frames = 104;
    StartDebuggingResponse start_debugging = 105;
    PauseThreadResponse pause_thread = 106;

    ThreadStartedEvent thread_started = 1000;
    ThreadEndedEvent thread_ended = 1001;
    ThreadPausedEvent thread_paused = 1002;
    ThreadContinuedEvent thread_continued = 1003;
  }
}

// A response that indicates that an error occurred while handling a debugging
// request.
message Error {
  // A message describing the error that occurred.
  string message = 1;
}

// The response to a ListThreadsRequest.
message ListThreadsResponse {
  // The threads that are currently active running Skylark code.
  repeated Thread thread = 1;
}

// The response to a SetBreakpointsRequest.
message SetBreakpointsResponse {
}

// The response to a ContinueExecutionRequest.
message ContinueExecutionResponse {
}

// The response to an EvaluateRequest.
message EvaluateResponse {
  // The result of evaluating an expression.
  Value result = 1;
}

// The response to a ListFramesRequest.
message ListFramesResponse {
  // The list of stack frames. The first element in the list represents the
  // topmost frame (that is, the current innermost function).
  repeated Frame frame = 1;
}

// The response to a StartDebuggingRequest.
message StartDebuggingResponse {
}

// The response to a PauseThreadRequest. This is an acknowledgement that the
// request was received. Actual pausing of individual threads happens
// asynchronously, and will be communicated via ThreadPausedEvent(s).
message PauseThreadResponse {
}

// An event indicating that a thread has begun executing Skylark code.
message ThreadStartedEvent {
  // The thread that began.
  Thread thread = 1;
}

// An event indicating that a thread that was executed Skylark code has ended.
message ThreadEndedEvent {
  // The thread that ended.
  Thread thread = 1;
}

// An event indicating that a thread was paused during execution.
message ThreadPausedEvent {
  // The thread that was paused.
  Thread thread = 1;
}

// An event indicating that a thread has continued execution after being paused.
message ThreadContinuedEvent {
  // The thread that continued executing.
  Thread thread = 1;
}

// A location or condition where the debug server will pause execution.
message Breakpoint {
  oneof condition {
    // A breakpoint that is triggered when a particular line is reached.
    Location location = 1;
  }
  // An optional condition for the breakpoint. When present, the breakpoint will
  // be triggered iff both the primary condition holds and this expression
  // evaluates to True.
  string expression = 2;
}

// A single frame in a thread's stack trace.
message Frame {
  // The name of the function that this frame represents.
  string function_name = 1;

  // The scopes that contain value bindings accessible in this frame.
  repeated Scope scope = 2;

  // The source location where the frame is currently paused.
  Location location = 3;
}

// A location in Skylark source code.
message Location {
  // The path of the Skylark source file.
  string path = 1;

  // A 0-based line index in the file denoted by path.
  uint32 line_index = 2;

  // A 0-based column index in the file denoted by path.
  uint32 column_index = 3;
}

// A scope that contains value bindings accessible in a frame.
message Scope {
  // A human-readable name of the scope, such as "global" or "local".
  string name = 1;

  // The variable bindings that are defined in this scope.
  repeated Value binding = 2;
}

// Describes the stepping behavior that should occur when execution of a thread
// is continued.
enum Stepping {
  // Do not step; continue execution until it completes or is paused for some
  // other reason (such as hitting another breakpoint).
  NONE = 0;

  // If the thread is paused on a statement that contains a function call,
  // step into that function. Otherwise, this is the same as OVER.
  INTO = 1;

  // Step over the next statement and any functions that it may call.
  OVER = 2;

  // Continue execution until the current function has been exited and then
  // pause.
  OUT = 3;
}

// Information about a thread that is running Skylark code.
message Thread {
  // The identifier of the thread.
  int64 id = 1;

  // Indicates whether the thread is paused (if true) or running (if false).
  bool is_paused = 2;

  // If the thread is paused, this field contains the location in Skylark code
  // of the next statement or expression that will be executed.
  Location location = 3;

  // A descriptive name for the thread that can be displayed in the debugger's
  // UI.
  string name = 4;
}

// The debugger representation of a Skylark value.
message Value {
  // A label that describes this value's location or source in a value
  // hierarchy.
  //
  // For example, in a stack frame, the label would be the name of the variable
  // to which the value is bound. For a value that is an element of a list, its
  // its label would be its subscript, such as "[4]". A value that is a field in
  // a struct would use the field's name as its label, and so forth.
  string label = 1;

  // A string description of the value.
  string description = 2;

  // A string describing the type of the value.
  //
  // This field may be omitted if the value does not correspond to a "real" type
  // as far as the debugging view is concerned; for example, dictionaries will
  // be rendered as sequences of key/value pairs ("entries") but the entries
  // themselves do not have a meaningful type with respect to our rendering.
  string type = 3;

  // Any child values associated with this value, such as its elements (for a
  // list or dictionary), its fields (for a struct), and so forth.
  repeated Value child = 4;
}