googleapis/google/devtools/remoteworkers/v1test2/command.proto

// Copyright 2017 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.remoteworkers.v1test2;

import "google/protobuf/duration.proto";

option go_package = "google.golang.org/genproto/googleapis/devtools/remoteworkers/v1test2;remoteworkers";


// Describes a shell-style task to execute.
message CommandTask {
  // Describes the inputs to a shell-style task.
  message Inputs {
    // An environment variable required by this task.
    message EnvironmentVariable {
      // The envvar name.
      string name = 1;

      // The envvar value.
      string value = 2;
    }

    // The command itself to run (e.g., argv)
    repeated string arguments = 1;

    // The input filesystem to be set up prior to the task beginning. The
    // contents should be a repeated set of FileMetadata messages though other
    // formats are allowed if better for the implementation (eg, a LUCI-style
    // .isolated file).
    //
    // This field is repeated since implementations might want to cache the
    // metadata, in which case it may be useful to break up portions of the
    // filesystem that change frequently (eg, specific input files) from those
    // that don't (eg, standard header files).
    repeated Digest files = 2;

    // All environment variables required by the task.
    repeated EnvironmentVariable environment_variables = 3;
  }

  // Describes the expected outputs of the command.
  message Outputs {
    // A list of expected files, relative to the execution root.
    repeated string files = 1;

    // A list of expected directories, relative to the execution root.
    repeated string directories = 2;
  }

  // Describes the timeouts associated with this task.
  message Timeouts {
    // This specifies the maximum time that the task can run, excluding the
    // time required to download inputs or upload outputs. That is, the worker
    // will terminate the task if it runs longer than this.
    google.protobuf.Duration execution = 1;

    // This specifies the maximum amount of time the task can be idle - that is,
    // go without generating some output in either stdout or stderr. If the
    // process is silent for more than the specified time, the worker will
    // terminate the task.
    google.protobuf.Duration idle = 2;

    // If the execution or IO timeouts are exceeded, the worker will try to
    // gracefully terminate the task and return any existing logs. However,
    // tasks may be hard-frozen in which case this process will fail. This
    // timeout specifies how long to wait for a terminated task to shut down
    // gracefully (e.g. via SIGTERM) before we bring down the hammer (e.g.
    // SIGKILL on *nix, CTRL_BREAK_EVENT on Windows).
    google.protobuf.Duration shutdown = 3;
  }

  // The inputs to the task.
  Inputs inputs = 1;

  // The expected outputs from the task.
  Outputs expected_outputs = 4;

  // The timeouts of this task.
  Timeouts timeouts = 5;
}

// Describes the actual outputs from the task.
message CommandOutputs {
  // exit_code is only fully reliable if the status' code is OK. If the task
  // exceeded its deadline or was cancelled, the process may still produce an
  // exit code as it is cancelled, and this will be populated, but a successful
  // (zero) is unlikely to be correct unless the status code is OK.
  int32 exit_code = 1;

  // The output files. The blob referenced by the digest should contain
  // one of the following (implementation-dependent):
  //    * A marshalled DirectoryMetadata of the returned filesystem
  //    * A LUCI-style .isolated file
  Digest outputs = 2;
}

// Can be used as part of CompleteRequest.metadata, or are part of a more
// sophisticated message.
message CommandOverhead {
  // The elapsed time between calling Accept and Complete. The server will also
  // have its own idea of what this should be, but this excludes the overhead of
  // the RPCs and the bot response time.
  google.protobuf.Duration duration = 1;

  // The amount of time *not* spent executing the command (ie
  // uploading/downloading files).
  google.protobuf.Duration overhead = 2;
}

// The metadata for a file. Similar to the equivalent message in the Remote
// Execution API.
message FileMetadata {
  // The path of this file. If this message is part of the
  // CommandResult.output_files fields, the path is relative to the execution
  // root and must correspond to an entry in CommandTask.outputs.files. If this
  // message is part of a Directory message, then the path is relative to the
  // root of that directory.
  string path = 1;

  // A pointer to the contents of the file. The method by which a client
  // retrieves the contents from a CAS system is not defined here.
  Digest digest = 2;

  // If the file is small enough, its contents may also or alternatively be
  // listed here.
  bytes contents = 3;

  // Properties of the file
  bool is_executable = 4;
}

// The metadata for a directory. Similar to the equivalent message in the Remote
// Execution API.
message DirectoryMetadata {
  // The path of the directory, as in [FileMetadata.path][google.devtools.remoteworkers.v1test2.FileMetadata.path].
  string path = 1;

  // A pointer to the contents of the directory, in the form of a marshalled
  // Directory message.
  Digest digest = 2;
}

// A reference to the contents of a file or a directory. If the latter, the has
// refers to the hash of a marshalled Directory message. Similar to the
// equivalent message in the Remote Execution API.
message Digest {
  // A string-encoded hash (eg "1a2b3c", not the byte array [0x1a, 0x2b, 0x3c])
  // using an implementation-defined hash algorithm (eg SHA-256).
  string hash = 1;

  // The size of the contents. While this is not strictly required as part of an
  // identifier (after all, any given hash will have exactly one canonical
  // size), it's useful in almost all cases when one might want to send or
  // retrieve blobs of content and is included here for this reason.
  int64 size_bytes = 2;
}

// The contents of a directory. Similar to the equivalent message in the Remote
// Execution API.
message Directory {
  // The files in this directory
  repeated FileMetadata files = 1;

  // Any subdirectories
  repeated DirectoryMetadata directories = 2;
}