Synchronize new proto/yaml changes.

PiperOrigin-RevId: 204768512

google/devtools/remoteworkers/v1test2/bots.proto

@@ -1,4 +1,4 @@
-// Copyright 2018 Google Inc.
+// Copyright 2018 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -166,26 +166,19 @@ message BotSession {
 // bot shouldn't report on them any more (the server will ignore superfluous
 // COMPLETED records).
 message Lease {
-  // The assignment, which is typically a resource that can be accessed through
-  // some other services. The assignment must be meaningful to the bot based
-  // solely on this name, either because the bot only understands one type of
-  // assignment (e.g., tasks served through the Tasks interface) or through some
-  // implementation-defined schema.
-  //
-  // For example, if the worker is executing a Task as defined by the Tasks
-  // interface, this field might be projects/{projectid}/tasks/{taskid}.
-  // However, it the worker is being assigned pull from a *queue* of tasks, the
-  // resource would be the name of the queue, something like
-  // projects/{projectid}/locations/{locationid}/queues/{queueid}. That queue
-  // may then provide the bot with tasks through another interface, which the
-  // bot then processes through the [Tasks]
-  // [google.devtools.remoteworkers.v1test2.Tasks] interface.
-  //
-  // Note that the assignment may be a [full resource name]
-  // [https://cloud.google.com/apis/design/resource_names#full_resource_name] if
-  // it should be accessed through an endpoint that is not already known to the
-  // bot.
-  string assignment = 1;
+  // A short string uniquely identifing the lease within this bot session.
+  string id = 7;
+
+  // The actual work to be performed, if any. May be omitted by the server if
+  // the lease is not in the `PENDING` state. The message must be meaningful to
+  // the bot. Output only (must only be set by the server).
+  google.protobuf.Any payload = 8;
+
+  // Any result the bot wishes to provide about the lease. Must not be changed
+  // after the first call with the lease in the `COMPLETED` or `CANCELLED`
+  // state. Input only (must only be set by the bot, will not be echoed by the
+  // server).
+  google.protobuf.Any result = 9;
 
   // The state of the lease. See LeaseState for more information.
   LeaseState state = 2;
@@ -196,7 +189,7 @@ message Lease {
   // asked for some resource the bot didn't have, this status will be
   // FAILED_PRECONDITION. But if the assignment in the lease didn't execute
   // correctly, this field will be `OK` while the failure of the assignment must
-  // be tracked elsewhere (e.g., through the Tasks interface).
+  // communicated via the `result` field.
   google.rpc.Status status = 3;
 
   // The requirements that are being claimed by this lease. This field may be
@@ -208,19 +201,14 @@ message Lease {
   // expiry date except the first one.
   google.protobuf.Timestamp expire_time = 5;
 
-  // While the `assignment` field is a resource name that allows the bot to
-  // get the actual assignment, the server can also optionally include the
-  // assignment itself inline in order to save a round trip to the server.
-  //
-  // This doesn't necessarily need to be the resource pointed to by
-  // `assignment`. For example, if the assignment is a task, this field could
-  // be task.description, not the entire task, since that's all the bot needs
-  // to know to get started. As with `assignment` itself, all that's necessary
-  // is that the bot knows how to handle the type of message received here.
-  //
-  // This field may be omitted by the server if the lease is not in the
-  // `PENDING` state.
-  google.protobuf.Any inline_assignment = 6;
+  // DEPRECATED. The assignment should be provided to the bot via the `payload`
+  // field. Clients that wish to use a simple name (such as a queue of work
+  // provided elsewhere) should define a custom message type and encode it into
+  // `payload`.
+  string assignment = 1 [deprecated = true];
+
+  // DEPRECATED. Use `payload` instead.
+  google.protobuf.Any inline_assignment = 6 [deprecated = true];
 }
 
 // AdminTemp is a prelimiary set of administration tasks. It's called "Temp"

google/devtools/remoteworkers/v1test2/command.proto

@@ -1,4 +1,4 @@
-// Copyright 2018 Google Inc.
+// Copyright 2018 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -16,7 +16,9 @@ syntax = "proto3";
 
 package google.devtools.remoteworkers.v1test2;
 
+import "google/protobuf/any.proto";
 import "google/protobuf/duration.proto";
+import "google/rpc/status.proto";
 
 option csharp_namespace = "Google.DevTools.RemoteWorkers.V1Test2";
 option go_package = "google.golang.org/genproto/googleapis/devtools/remoteworkers/v1test2;remoteworkers";
@@ -26,7 +28,8 @@ option java_package = "com.google.devtools.remoteworkers.v1test2";
 option objc_class_prefix = "RW";
 
 
-// Describes a shell-style task to execute.
+// Describes a shell-style task to execute, suitable for providing as the Bots
+// interface's `Lease.payload` field.
 message CommandTask {
   // Describes the inputs to a shell-style task.
   message Inputs {
@@ -39,7 +42,16 @@ message CommandTask {
       string value = 2;
     }
 
-    // The command itself to run (e.g., argv)
+    // The command itself to run (e.g., argv).
+    //
+    // This field should be passed directly to the underlying operating system,
+    // and so it must be sensible to that operating system. For example, on
+    // Windows, the first argument might be "C:\Windows\System32\ping.exe" -
+    // that is, using drive letters and backslashes. A command for a *nix
+    // system, on the other hand, would use forward slashes.
+    //
+    // All other fields in the RWAPI must consistently use forward slashes,
+    // since those fields may be interpretted by both the service and the bot.
     repeated string arguments = 1;
 
     // The input filesystem to be set up prior to the task beginning. The
@@ -59,11 +71,27 @@ message CommandTask {
 
   // Describes the expected outputs of the command.
   message Outputs {
-    // A list of expected files, relative to the execution root.
+    // A list of expected files, relative to the execution root. All paths
+    // MUST be delimited by forward slashes.
     repeated string files = 1;
 
-    // A list of expected directories, relative to the execution root.
+    // A list of expected directories, relative to the execution root. All paths
+    // MUST be delimited by forward slashes.
     repeated string directories = 2;
+
+    // The destination to which any stdout should be sent. The method by which
+    // the bot should send the stream contents to that destination is not
+    // defined in this API. As examples, the destination could be a file
+    // referenced in the `files` field in this message, or it could be a URI
+    // that must be written via the ByteStream API.
+    string stdout_destination = 3;
+
+    // The destination to which any stderr should be sent. The method by which
+    // the bot should send the stream contents to that destination is not
+    // defined in this API. As examples, the destination could be a file
+    // referenced in the `files` field in this message, or it could be a URI
+    // that must be written via the ByteStream API.
+    string stderr_destination = 4;
   }
 
   // Describes the timeouts associated with this task.
@@ -98,6 +126,7 @@ message CommandTask {
   Timeouts timeouts = 5;
 }
 
+// DEPRECATED - use CommandResult instead.
 // Describes the actual outputs from the task.
 message CommandOutputs {
   // exit_code is only fully reliable if the status' code is OK. If the task
@@ -113,6 +142,7 @@ message CommandOutputs {
   Digest outputs = 2;
 }
 
+// DEPRECATED - use CommandResult instead.
 // Can be used as part of CompleteRequest.metadata, or are part of a more
 // sophisticated message.
 message CommandOverhead {
@@ -126,14 +156,50 @@ message CommandOverhead {
   google.protobuf.Duration overhead = 2;
 }
 
+// All information about the execution of a command, suitable for providing as
+// the Bots interface's `Lease.result` field.
+message CommandResult {
+  // An overall status for the command. For example, if the command timed out,
+  // this might have a code of DEADLINE_EXCEEDED; if it was killed by the OS for
+  // memory exhaustion, it might have a code of RESOURCE_EXHAUSTED.
+  google.rpc.Status status = 1;
+
+  // The exit code of the process. An exit code of "0" should only be trusted if
+  // `status` has a code of OK (otherwise it may simply be unset).
+  int32 exit_code = 2;
+
+  // 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 = 3;
+
+  // 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 = 4 [deprecated = true];
+
+  // The amount of time *not* spent executing the command (ie
+  // uploading/downloading files).
+  google.protobuf.Duration overhead = 5 [deprecated = true];
+
+  // Implementation-dependent statistics about the task. Both servers and bots
+  // may define messages which can be encoded here; bots are free to provide
+  // statistics in multiple formats, and servers are free to choose one or more
+  // of the values to process and ignore others. In particular, it is *not*
+  // considered an error for the bot to provide the server with a field that it
+  // doesn't know about.
+  repeated google.protobuf.Any statistics = 6;
+}
+
 // 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
+  // CommandOutputs.outputs 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.
+  // root of that directory. All paths MUST be delimited by forward slashes.
   string path = 1;
 
   // A pointer to the contents of the file. The method by which a client
@@ -159,9 +225,15 @@ message DirectoryMetadata {
   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.
+// The CommandTask and CommandResult messages assume the existence of a service
+// that can serve blobs of content, identified by a hash and size known as a
+// "digest." The method by which these blobs may be retrieved is not specified
+// here, but a model implementation is in the Remote Execution API's
+// "ContentAddressibleStorage" interface.
+//
+// In the context of the RWAPI, a Digest will virtually always refer to the
+// contents of a file or a directory. The latter is represented by the
+// byte-encoded Directory message.
 message Digest {
   // A string-encoded hash (eg "1a2b3c", not the byte array [0x1a, 0x2b, 0x3c])
   // using an implementation-defined hash algorithm (eg SHA-256).

google/devtools/remoteworkers/v1test2/remote_workers.yaml

@@ -10,6 +10,7 @@ apis:
 types:
 - name: google.devtools.remoteworkers.v1test2.AdminTemp
 - name: google.devtools.remoteworkers.v1test2.CommandTask
+- name: google.devtools.remoteworkers.v1test2.CommandResult
 - name: google.devtools.remoteworkers.v1test2.CommandOutputs
 - name: google.devtools.remoteworkers.v1test2.CommandOverhead
 - name: google.devtools.remoteworkers.v1test2.FileMetadata

google/devtools/remoteworkers/v1test2/tasks.proto

@@ -1,4 +1,4 @@
-// Copyright 2018 Google Inc.
+// Copyright 2018 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -29,20 +29,11 @@ option java_package = "com.google.devtools.remoteworkers.v1test2";
 option objc_class_prefix = "RW";
 
 
-// Design doc: https://goo.gl/oojM5H
-//
-// The Tasks interface defines tasks to execute and the results of these tasks.
-// It does not include the metadata surrounding tasks; that is, the Task message
-// represents *what* to be executed and *what* was the result of that execution,
-// but not *how* to execute that task. For example this interface does not
-// explain what platform the task should be run on, what priority it may have in
-// any queue, etc.
-//
-// NB: we are not using google.rpc.batch since that's designed specifically for
-// batch execution of RPC methods, and so is semantically quite different from
-// our more general concept (though an RPC method could certainly be described
-// by a Task in this interface).
+// DEPRECATED. GetTask should be replaced by Lease.payload, UpdateTaskResult by
+// Lease.result and logs should be precreated prior to sending to the bot (eg,
+// via CommandTask.expected_outputs.stdout_destination).
 service Tasks {
+  // DEPRECATED - use Lease.payload instead.
   // GetTask reads the current state of the task. Tasks must be created through
   // some other interface, and should be immutable once created and exposed to
   // the bots.
@@ -52,6 +43,7 @@ service Tasks {
     };
   }
 
+  // DEPRECATED - use Lease.result instead.
   // UpdateTaskResult updates the result.
   rpc UpdateTaskResult(UpdateTaskResultRequest) returns (TaskResult) {
     option (google.api.http) = {
@@ -60,6 +52,7 @@ service Tasks {
     };
   }
 
+  // DEPRECATED - precreate logs prior to sending to bot.
   // AddTaskLog creates a new streaming log. The log is streamed and marked as
   // completed through other interfaces (i.e., ByteStream). This can be called
   // by the bot if it wants to create a new log; the server can also predefine
@@ -72,6 +65,7 @@ service Tasks {
   }
 }
 
+// DEPRECATED - use Lease.payload instead.
 // A Task represents a unit of work. Its result and logs are defined as
 // subresources.
 //
@@ -98,6 +92,7 @@ message Task {
   map<string, string> logs = 3;
 }
 
+// DEPRECATED - use Lease.assignment_result instead.
 // The result and metadata of the task.
 message TaskResult {
   // The name of the task result; must be a name of a `Task` followed by

google/devtools/remoteworkers/v1test2/worker.proto

@@ -1,4 +1,4 @@
-// Copyright 2018 Google Inc.
+// Copyright 2018 Google LLC
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -78,6 +78,24 @@ message Worker {
     string value = 2;
   }
 
+  // A configuration request or report; see the `configs` field for more
+  // information.
+  message Config {
+    // For general information on keys, see the documentation to `Worker`.
+    //
+    // The current set of standard keys are:
+    //
+    // * DockerImage: the image of the container. When being reported by the
+    // bot, the empty value should always be included if the bot is able to pull
+    // its own images; the bot may optionally *also* report images that are
+    // present in its cache. When being requested in a lease, the value is the
+    // URI of the image (eg `gcr.io/user/image@sha256:hash`).
+    string key = 1;
+
+    // The configuration's value.
+    string value = 2;
+  }
+
   // A list of devices; the first device is the primary device. See the `Device`
   // message for more information.
   repeated Device devices = 1;
@@ -90,6 +108,24 @@ message Worker {
   //
   // The behaviour of repeated keys is identical to that of Device.Property.
   repeated Property properties = 2;
+
+  // Bots can be configured in certain ways when accepting leases. For example,
+  // many leases are executed inside a Docker container. To support this, the
+  // bot needs to be able to report that it has Docker installed (and knows how
+  // to execute something inside a container), and the task submitter needs to
+  // specify which image should be used to start the container. Similarly, a
+  // lease may be able to run as one of several users on the worker; in such
+  // cases, the bot needs to report what users are available, and the submitter
+  // needs to choose one.
+  //
+  // Therefore, when this message is reported by the bot to the service, each
+  // key represents a *type* of configuration that the bot knows how to set,
+  // while each *value* represents a legal value for that configuration (the
+  // empty string is interpretted as a wildcard, such as for Docker images).
+  // When this message is sent by the server to the bot in the context of a
+  // lease, it represents a command to the bot to apply the setting. Keys may
+  // be repeated during reporting but not in a lease.
+  repeated Config configs = 3;
 }
 
 // Any device, including computers, phones, accelerators (e.g. GPUs), etc. All