pkg/proto/runner/runner.proto

syntax = "proto3";

package buildbarn.runner;

import "google/protobuf/any.proto";
import "google/protobuf/empty.proto";

option go_package = "github.com/buildbarn/bb-remote-execution/pkg/proto/runner";

// In order to make the execution strategy of bb_worker pluggable and
// capable of supporting privilege separation, bb_worker calls into a
// runner service to invoke the desired command after setting up inputs
// accordingly. This service needs to be implemented by the runner.
//
// Using separate runner processes also prevents bb_worker from
// forking. This is good, as UNIX systems (without native support for
// spawning processes without forking) have an inherent race condition
// that effectively prevents bb_worker from both writing executables to
// disk and executing them. More details:
//
//     https://github.com/golang/go/issues/22315
service Runner {
  rpc CheckReadiness(CheckReadinessRequest) returns (google.protobuf.Empty);
  rpc Run(RunRequest) returns (RunResponse);
}

message CheckReadinessRequest {
  // A path, relative to the build directory, that the runner process
  // should validate exists.
  string path = 1;
}

message RunRequest {
  // Command line arguments that need to be set.
  repeated string arguments = 1;

  // Environment variables that need to be set.
  map<string, string> environment_variables = 2;

  // Working directory, relative to the input root directory.
  string working_directory = 3;

  // Path where data written over stdout should be stored, relative to
  // the build directory.
  string stdout_path = 4;

  // Path where data written over stderr should be stored, relative to
  // the build directory.
  string stderr_path = 5;

  // Path of the input root, relative to the build directory.
  string input_root_directory = 6;

  // Path of a scratch space directory that may be used by the build
  // action, relative to the build directory.
  string temporary_directory = 7;

  // Path where files may be stored that are attached to the REv2
  // ExecuteResponse in the form of server logs.
  string server_logs_directory = 8;
}

message RunResponse {
  // Exit code generated by the process.
  int64 exit_code = 1;

  // Runner-specific information on the amount of resources used during
  // execution.
  repeated google.protobuf.Any resource_usage = 2;
}