// Copyright (c) 2015, Google Inc.
//
// 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 google.devtools.clouddebugger.v2;

import "google/api/annotations.proto";
import "google/devtools/clouddebugger/v2/data.proto";
import "google/protobuf/empty.proto";

option java_multiple_files = true;
option java_outer_classname = "DebuggerProto";
option java_package = "com.google.devtools.clouddebugger.v2";


// The Debugger service provides the API that allows users to collect run-time
// information from a running application, without stopping or slowing it down
// and without modifying its state.  An application may include one or
// more replicated processes performing the same work.
//
// The application is represented using the Debuggee concept. The Debugger
// service provides a way to query for available Debuggees, but does not
// provide a way to create one.  A debuggee is created using the Controller
// service, usually by running a debugger agent with the application.
//
// The Debugger service enables the client to set one or more Breakpoints on a
// Debuggee and collect the results of the set Breakpoints.
service Debugger2 {
  // Sets the breakpoint to the debuggee.
  rpc SetBreakpoint(SetBreakpointRequest) returns (SetBreakpointResponse) {
    option (google.api.http) = { post: "/v2/debugger/debuggees/{debuggee_id}/breakpoints/set" body: "breakpoint" };
  }

  // Gets breakpoint information.
  rpc GetBreakpoint(GetBreakpointRequest) returns (GetBreakpointResponse) {
    option (google.api.http) = { get: "/v2/debugger/debuggees/{debuggee_id}/breakpoints/{breakpoint_id}" };
  }

  // Deletes the breakpoint from the debuggee.
  rpc DeleteBreakpoint(DeleteBreakpointRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = { delete: "/v2/debugger/debuggees/{debuggee_id}/breakpoints/{breakpoint_id}" };
  }

  // Lists all breakpoints for the debuggee.
  rpc ListBreakpoints(ListBreakpointsRequest) returns (ListBreakpointsResponse) {
    option (google.api.http) = { get: "/v2/debugger/debuggees/{debuggee_id}/breakpoints" };
  }

  // Lists all the debuggees that the user can set breakpoints to.
  rpc ListDebuggees(ListDebuggeesRequest) returns (ListDebuggeesResponse) {
    option (google.api.http) = { get: "/v2/debugger/debuggees" };
  }
}

// Request to set a breakpoint
message SetBreakpointRequest {
  // ID of the debuggee where the breakpoint is to be set.
  string debuggee_id = 1;

  // Breakpoint specification to set.
  // The field 'location' of the breakpoint must be set.
  Breakpoint breakpoint = 2;

  // The client version making the call.
  // Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
  string client_version = 4;
}

// Response for setting a breakpoint.
message SetBreakpointResponse {
  // Breakpoint resource.
  // The field `id` is guaranteed to be set (in addition to the echoed fileds).
  Breakpoint breakpoint = 1;
}

// Request to get breakpoint information.
message GetBreakpointRequest {
  // ID of the debuggee whose breakpoint to get.
  string debuggee_id = 1;

  // ID of the breakpoint to get.
  string breakpoint_id = 2;

  // The client version making the call.
  // Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
  string client_version = 4;
}

// Response for getting breakpoint information.
message GetBreakpointResponse {
  // Complete breakpoint state.
  // The fields `id` and `location` are guaranteed to be set.
  Breakpoint breakpoint = 1;
}

// Request to delete a breakpoint.
message DeleteBreakpointRequest {
  // ID of the debuggee whose breakpoint to delete.
  string debuggee_id = 1;

  // ID of the breakpoint to delete.
  string breakpoint_id = 2;

  // The client version making the call.
  // Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
  string client_version = 3;
}

// Request to list breakpoints.
message ListBreakpointsRequest {
  // Wrapper message for `Breakpoint.Action`. Defines a filter on the action
  // field of breakpoints.
  message BreakpointActionValue {
    // Only breakpoints with the specified action will pass the filter.
    Breakpoint.Action value = 1;
  }

  // ID of the debuggee whose breakpoints to list.
  string debuggee_id = 1;

  // When set to `true`, the response includes the list of breakpoints set by
  // any user. Otherwise, it includes only breakpoints set by the caller.
  bool include_all_users = 2;

  // When set to `true`, the response includes active and inactive
  // breakpoints. Otherwise, it includes only active breakpoints.
  bool include_inactive = 3;

  // When set, the response includes only breakpoints with the specified action.
  BreakpointActionValue action = 4;

  // When set to `true`, the response breakpoints are stripped of the
  // results fields: `stack_frames`, `evaluated_expressions` and
  // `variable_table`.
  bool strip_results = 5;

  // A wait token that, if specified, blocks the call until the breakpoints
  // list has changed, or a server selected timeout has expired.  The value
  // should be set from the last response. The error code
  // `google.rpc.Code.ABORTED` (RPC) is returned on wait timeout, which
  // should be called again with the same `wait_token`.
  string wait_token = 6;

  // The client version making the call.
  // Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
  string client_version = 8;
}

// Response for listing breakpoints.
message ListBreakpointsResponse {
  // List of all breakpoints with complete state.
  // The fields `id` and `location` are guaranteed to be set on each breakpoint.
  repeated Breakpoint breakpoints = 1;

  // A wait token that can be used in the next call to `list` (REST) or
  // `ListBreakpoints` (RPC) to block until the list of breakpoints has changes.
  string next_wait_token = 2;
}

// Request to list debuggees.
message ListDebuggeesRequest {
  // Project number of a Google Cloud project whose debuggees to list.
  string project = 2;

  // When set to `true`, the result includes all debuggees. Otherwise, the
  // result includes only debuggees that are active.
  bool include_inactive = 3;

  // The client version making the call.
  // Following: `domain/type/version` (e.g., `google.com/intellij/v1`).
  string client_version = 4;
}

// Response for listing debuggees.
message ListDebuggeesResponse {
  // List of debuggees accessible to the calling user.
  // Note that the `description` field is the only human readable field
  // that should be displayed to the user.
  // The fields `debuggee.id` and  `description` fields are guaranteed to be
  // set on each debuggee.
  repeated Debuggee debuggees = 1;
}