From 2584090f0fa305350ebc2df6c2c6f28e00b5c827 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Mon, 16 Jul 2018 10:51:13 -0700 Subject: [PATCH] Synchronize new proto/yaml changes. PiperOrigin-RevId: 204768512 --- .../devtools/remoteworkers/v1test2/bots.proto | 58 +++++------- .../remoteworkers/v1test2/command.proto | 94 ++++++++++++++++--- .../remoteworkers/v1test2/remote_workers.yaml | 1 + .../remoteworkers/v1test2/tasks.proto | 23 ++--- .../remoteworkers/v1test2/worker.proto | 38 +++++++- 5 files changed, 153 insertions(+), 61 deletions(-) diff --git a/google/devtools/remoteworkers/v1test2/bots.proto b/google/devtools/remoteworkers/v1test2/bots.proto index ad46f4cd..397a60d7 100644 --- a/google/devtools/remoteworkers/v1test2/bots.proto +++ b/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" diff --git a/google/devtools/remoteworkers/v1test2/command.proto b/google/devtools/remoteworkers/v1test2/command.proto index 544ca1d4..c16e950a 100644 --- a/google/devtools/remoteworkers/v1test2/command.proto +++ b/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). diff --git a/google/devtools/remoteworkers/v1test2/remote_workers.yaml b/google/devtools/remoteworkers/v1test2/remote_workers.yaml index 35ea414c..3c8494ef 100644 --- a/google/devtools/remoteworkers/v1test2/remote_workers.yaml +++ b/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 diff --git a/google/devtools/remoteworkers/v1test2/tasks.proto b/google/devtools/remoteworkers/v1test2/tasks.proto index 8f7f6de0..71eee3a8 100644 --- a/google/devtools/remoteworkers/v1test2/tasks.proto +++ b/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 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 diff --git a/google/devtools/remoteworkers/v1test2/worker.proto b/google/devtools/remoteworkers/v1test2/worker.proto index 0d6e16b7..c53f13d7 100644 --- a/google/devtools/remoteworkers/v1test2/worker.proto +++ b/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