src/main/protobuf/command_server.proto

// Copyright 2016 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.
//
// This file contains the protocol used to communicate between the Bazel client
// and the server. At a high level clients may call the CommandServer.run rpc
// to initiates a Bazel command and CommandServer.cancel to cancel an in-flight
// command. CommandServer.ping may be used to check for server liveness without
// executing any commands. See documentation of individual messages for more
// details.
syntax = "proto3";

package command_server;

import "google/protobuf/any.proto";
import "src/main/protobuf/failure_details.proto";

option java_package = "com.google.devtools.build.lib.server";
option java_outer_classname = "CommandProtos";

// Passed to CommandServer.run to initiate execution of a Bazel command.
message RunRequest {
  // Request cookie from the output base of the server. This serves as a
  // rudimentary form of mutual authentication.
  string cookie = 1;

  // Command and command arguments. Does not include startup arguments.
  repeated bytes arg = 2;

  // Tells the server whether or not the client is willing to wait for any
  // concurrent in-flight request to complete (there are many commands which
  // may not run concurrently). If false and there are in-flight requests then
  // the server will return an error immediately.
  bool block_for_lock = 3;

  // Whether the server should restrict itself to emitting only errors on the
  // console.
  bool quiet = 9;

  // A simple description of the client for reporting purposes. This value is
  // required.
  string client_description = 4;

  // Invocation policy affects how command arguments are interpreted and should
  // be passed separately. This is a proto message, either a human readable
  // String or base64-encoded binary-serialized version of the message. It is
  // not typed directly as an InvocationPolicy message due to distinctions
  // between batch and server mode, so the parsing logic is only in the Java
  // code.
  string invocation_policy = 5;

  // Startup arguments, in the order they were applied, tagged with where they
  // came from. These options have already been parsed and already have had
  // their effect. This information should only be used for logging.
  repeated StartupOption startup_options = 6;

  // Whether the resulting command can be preempted if additional commands
  // are received.
  bool preemptible = 7;

  // Additional per-command information passed to the server in the form of
  // arbitrary messages which the server may be programmed to recognize and
  // consume. Unrecognized message types are ignored.
  repeated google.protobuf.Any command_extensions = 8;
}

// Contains the a startup option with its source file. Uses bytes to preserve
// the way the user inputted the arguments, like the args in RunRequest.
message StartupOption {
  // Startup option in --nullaryflag or --unaryflag=value form.
  bytes option = 1;
  // Where the option came from, such as an rc file or an empty string for the
  // command line.
  bytes source = 2;
}

// Description of an environment variable
message EnvironmentVariable {
  bytes name = 1;
  bytes value = 2;
}

// Description of a request by the server to the client to execute a binary
// after the command invocation finishes.
message ExecRequest {
  bytes working_directory = 1;
  repeated bytes argv = 2;
  repeated EnvironmentVariable environment_variable = 3;
  repeated bytes environment_variable_to_clear = 4;
  bool should_exec = 5;
  optional ScriptPath script_path = 6;
  repeated PathToReplace path_to_replace = 7;
}

// Represents the --script_path value and the run script contents for
// relevant run builds.
message ScriptPath {
  bytes script_path = 1;
  bytes script_contents = 2;
}

// Represents paths to replace to allow localization of an ExecRequest when the
// build takes place on a different filesystem from where executing the
// ExecRequest would occur.
message PathToReplace {
  enum Type {
    UNSPECIFIED = 0;
    OUTPUT_BASE = 1;
    BUILD_WORKING_DIRECTORY = 2;
    BUILD_WORKSPACE_DIRECTORY = 3;
    TEST_LOG_SUBDIR = 4;
  }
  Type type = 1;
  bytes value = 2;
}

// Contains metadata and result data for a command execution.
message RunResponse {
  // Request cookie from the output base of the server. This serves as a
  // rudimentary form of mutual authentication. Set on every response.
  string cookie = 1;

  // Standard out of the command, chunked. May be empty.
  bytes standard_output = 2;

  // Standard error of the command, chunked. May be empty.
  bytes standard_error = 3;

  // Whether this is the last message of the stream, signals that exit_code is
  // valid.
  bool finished = 4;

  // The exit code of the command, only valid when finished is set.
  int32 exit_code = 5;

  // Randomly generated command identifier, this may be used to cancel execution
  // of the command by issuing a cancel call. This should be sent to the client
  // as soon as possible. This is not required to be set (non-empty) on every
  // response.
  string command_id = 6;

  // Whether the command has shut down the server; if set, the client should
  // wait until the server process dies before finishing.
  bool termination_expected = 7;

  // A command to exec() after the command invocation finishes. Should only be
  // present if finished is set.
  ExecRequest exec_request = 8;

  // Fine-grained failure details. Should only be present if finished is set.
  // WARNING: This functionality is experimental and should not be relied on at
  // this time.
  // TODO(mschaller): remove experimental warning
  failure_details.FailureDetail failure_detail = 9;

  // Additional per-command information passed by the server in the form of
  // arbitrary messages.
  repeated google.protobuf.Any command_extensions = 10;
}

// Passed to CommandServer.cancel to initiate graceful cancellation of an
// in-flight command.
message CancelRequest {
  // The client request cookie (see RunRequest.cookie).
  string cookie = 1;

  // The id of the command to cancel.
  string command_id = 2;
}

message CancelResponse {
  // The server response cookie (see RunResponse.cookie).
  string cookie = 1;
}

// Passed to CommandServer.ping to initiate a ping request.
message PingRequest {
  // The client request cookie (see RunRequest.cookie).
  string cookie = 1;
}

message PingResponse {
  // The server response cookie (see RunResponse.cookie).
  string cookie = 1;
}

// Describes metadata necessary for connecting to and managing the server.
message ServerInfo {
  // The server process's pid.
  int32 pid = 1;

  // Address the CommandServer is listening on. Can be passed directly to grpc
  // to create a connection.
  string address = 2;

  // Client request cookie.
  string request_cookie = 3;

  // Server response cookie.
  string response_cookie = 4;
}

service CommandServer {
  // Run a Bazel command. See documentation of argument/return messages for
  // details.
  rpc Run(RunRequest) returns (stream RunResponse) {}

  // Cancel a currently running Bazel command. May return before the run command
  // actually terminates.
  rpc Cancel(CancelRequest) returns (CancelResponse) {}

  // Does not do anything. Used for liveness check.
  rpc Ping(PingRequest) returns (PingResponse) {}
}