| // Copyright 2019 The Chromium OS Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| syntax = "proto3"; |
| |
| package chromiumos.config.api.test.tls; |
| |
| option go_package = "go.chromium.org/chromiumos/config/go/api/test/tls"; |
| |
| import "google/protobuf/empty.proto"; |
| |
| import "dependencies/longrunning/operations.proto"; |
| |
| // Common lab services implemented on top of the wiring APIs. |
| // |
| // The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL |
| // NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and |
| // "OPTIONAL" in this document are to be interpreted as described in |
| // RFC 2119. |
| // |
| // All clients SHOULD pass the gRPC metadata key request_trace_id with one |
| // value. The value is a unique string that is associated with the method call |
| // in metrics. Clients that do not pass request_trace_id MAY be rejected so that |
| // they can be fixed. |
| service Common { |
| // ExecDutCommand runs a command on a DUT. |
| // |
| // The working directory is /. |
| // A tty is not spawned for the command. |
| // The user and group is root. |
| // All signals have their default dispositions and are not masked. |
| // The umask is set to 0. |
| // |
| // The environment contains: |
| // |
| // TERM=dumb |
| // PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/opt/bin |
| // LANG=en_US.UTF-8 |
| // USER=root |
| // HOME=/root |
| // |
| // The environment MAY also contain SSH client variables. |
| // The environment SHALL NOT contain variables not mentioned above. |
| // |
| // If the stream is interrupted, the implementation MAY attempt to |
| // stop the command by sending SIGINT, SIGHUP, SIGTERM, or SIGKILL. |
| rpc ExecDutCommand(ExecDutCommandRequest) |
| returns (stream ExecDutCommandResponse); |
| |
| // ProvisionDut installs a specified version of Chrome OS on the DUT, along |
| // with any specified DLCs. |
| // |
| // If the DUT is already on the specified version of Chrome OS, the OS will |
| // not be provisioned. |
| // |
| // If the DUT already has the specified list of DLCs, only the missing DLCs |
| // will be provisioned. |
| rpc ProvisionDut(ProvisionDutRequest) returns (google.longrunning.Operation) { |
| option (google.longrunning.operation_info) = { |
| response_type: "ProvisionDutResponse", |
| metadata_type: "ProvisionDutMetadata" |
| }; |
| } |
| |
| // ProvisionLacros installs a specified version of Lacros on the DUT. |
| // |
| // If the DUT already has the specified version of Lacros, Lacros will not be |
| // provisioned. |
| rpc ProvisionLacros(ProvisionLacrosRequest) returns (google.longrunning.Operation) { |
| option (google.longrunning.operation_info) = { |
| response_type: "ProvisionLacrosResponse", |
| metadata_type: "ProvisionLacrosMetadata" |
| }; |
| } |
| |
| // FetchCrashes gets a stream of all crash reports currently on the DUT. |
| // |
| // The stream returned may split up a crash over multiple |
| // `FetchCrashesResponse` protos. See the definition of that proto for |
| // details. |
| // |
| // This call is read-only: it doesn't delete the crashes that it reads. |
| rpc FetchCrashes(FetchCrashesRequest) returns (stream FetchCrashesResponse); |
| |
| // CreateFakeOmaha starts a fake Omaha service on TLS and exposes the |
| // listened port to the DUT. |
| rpc CreateFakeOmaha(CreateFakeOmahaRequest) returns (FakeOmaha); |
| // DeleteFakeOmaha deletes the specified fake Omaha resource created by |
| // CreateFakeOmaha. |
| rpc DeleteFakeOmaha(DeleteFakeOmahaRequest) returns (google.protobuf.Empty); |
| } |
| |
| message ExecDutCommandRequest { |
| // name is the resource name for the DUT. |
| // The DUT name is passed to the RTD when the RTD is started. |
| // It is not specified whether the name is the DUT hostname. |
| string name = 1; |
| // command is the command to run. |
| // If this contains no slashes, it is resolved using PATH. |
| // If this starts with /, it is used as an absolute path to the |
| // program to run. |
| // Otherwise, this is treated as a path relative to the working |
| // directory. |
| string command = 2; |
| // args are the arguments to pass to the command. |
| repeated string args = 3; |
| // stdin is passed to the command as the program's stdin. |
| // The stream does not support seeking. |
| // An empty bytes is not treated specially; if the command reads |
| // from stdin, it will receive zero bytes. |
| bytes stdin = 4; |
| // stdout indicates how to handle the command's stdout. |
| Output stdout = 5; |
| // stderr indicates how to handle the command's stderr. |
| Output stderr = 6; |
| } |
| message ExecDutCommandResponse { |
| message ExitInfo { |
| // status provides information about how the command process |
| // terminated. |
| // |
| // If the command failed to start, status is set to an arbitrary |
| // non-zero value. |
| // |
| // If signaled is set, status is set to the signal that caused |
| // the command to terminate. |
| // |
| // Otherwise, status is set to the exit status of the process. |
| // Exit statuses outside of 0 to 255 inclusive are not supported; |
| // they will be mapped to an arbitrary non-zero value. |
| // |
| // status is zero if and only if the process was successfully |
| // started and exited with a zero status. |
| int32 status = 1; |
| // signaled indicates whether the command exited due to a signal. |
| // If set, status contains the signal. |
| bool signaled = 2; |
| // started indicates whether the command was started. |
| bool started = 3; |
| // error_message provides a human readable explanation for some errors. |
| // This MUST NOT be inspected by programs. |
| string error_message = 4; |
| } |
| // exit_info contains exit information. |
| // This is set when the command has exited or failed to start. |
| // This is set on the last message in the response stream. |
| ExitInfo exit_info = 1; |
| // stdout contains the shell command's stdout output since the last |
| // response in the stream. |
| // The implementation MAY batch or delay output to later |
| // responses in the stream. |
| bytes stdout = 2; |
| // stderr contains the shell command's stderr output since the last |
| // response in the stream. |
| // The implementation MAY batch or delay output to later |
| // responses in the stream. |
| bytes stderr = 3; |
| } |
| |
| // Output enumeration for ExecDutCommandRequest. |
| enum Output { |
| // OUTPUT_PIPE means to collect output and return it. |
| OUTPUT_PIPE = 0; |
| // OUTPUT_STDOUT is a special value for stderr which means to merge stderr |
| // into stdout. |
| OUTPUT_STDOUT = 1; |
| } |
| |
| message ProvisionDutRequest { |
| // name is the resource name for the DUT. |
| // The DUT name is passed to the RTD when the RTD is started. |
| // It is not specified whether the name is the DUT hostname. |
| string name = 1; |
| |
| // TODO(crbug.com/1155247) Deprecate this nested message and replace with |
| // top level ChromeOsImage. |
| message ChromeOSImage { |
| option deprecated = true; |
| oneof path_oneof { |
| // gs_path_prefix is the GS path to where kernel, rootfs, and stateful |
| // images are located. If DLCs are to be provisioned, it must be a GS path |
| // that also has the dlc directory. |
| // Only gs://chromeos-image-archive bucket is supported. |
| // For example the format should be: |
| // - gs://chromeos-image-archive/eve-release/R86-13380.0.0 |
| string gs_path_prefix = 1; |
| } |
| } |
| // image specifies the Chrome OS image with which to provision the DUT. |
| ChromeOSImage image = 2 [deprecated = true]; |
| |
| // Reference DLCs developer documentation: |
| // https://source.corp.google.com/chromeos_public/src/platform2/dlcservice/docs/developer.md |
| message DLCSpec { |
| // id is the DLC ID which is a unique identifier. |
| // The DLC ID must follow a specific format that can be found in the DLC |
| // developer doc below. |
| string id = 1; |
| } |
| // dlc_specs specifies which DLCs to install on the DUT after provisioning. |
| repeated DLCSpec dlc_specs = 3; |
| // preserve_stateful specifies whether the stateful partition should be preserved during |
| // provisioning. If preserve_stateful is not set to true, the stateful partition is |
| // block-level wiped and reset during provisioning. |
| bool preserve_stateful = 4; |
| |
| // target_build is the ChromeOS build to provision to. |
| ChromeOsImage target_build = 5; |
| } |
| |
| message ProvisionDutResponse { |
| // When the status code is other than OK, details in Status message should be |
| // parsed for ErrorInfo message with the following Reasons as the reason. |
| enum Reason { |
| // status code: INVALID_ARGUMENT |
| REASON_INVALID_REQUEST = 0; |
| // status code: FAILED_PRECONDITION |
| REASON_DUT_UNREACHABLE_PRE_PROVISION = 1; |
| // status code: FAILED_PRECONDITION |
| REASON_DOWNLOADING_IMAGE_FAILED = 2; |
| // status code: DEADLINE_EXCEEDED |
| REASON_PROVISIONING_TIMEDOUT = 3; |
| // status code: ABORTED |
| REASON_PROVISIONING_FAILED = 4; |
| // status code: ABORTED |
| REASON_DUT_UNREACHABLE_POST_PROVISION = 5; |
| } |
| } |
| |
| message ProvisionDutMetadata { |
| } |
| |
| message ProvisionLacrosRequest { |
| // name is the resource name for the DUT. |
| // The DUT name is passed to the RTD when the RTD is started. |
| // It is not specified whether the name is the DUT hostname. |
| string name = 1; |
| |
| message LacrosImage { |
| oneof path_oneof { |
| // gs_path_prefix is the GS path prefix to where Lacros is located. |
| string gs_path_prefix = 1; |
| } |
| } |
| // image specifies the Lacros image with which to provision the DUT. |
| LacrosImage image = 2; |
| } |
| |
| message ProvisionLacrosResponse { |
| // When the status code is other than OK, details in Status message should be |
| // parsed for ErrorInfo message with the following Reasons as the reason. |
| enum Reason { |
| // Failed as the ProvisionLacros request is invalid. |
| REASON_INVALID_REQUEST = 0; |
| // Failed to connect to the DUT prior to provisioning Lacros. |
| REASON_DUT_UNREACHABLE_PRE_PROVISION = 1; |
| // Failed to download the Lacros image or a timeout during download. |
| REASON_DOWNLOADING_IMAGE_FAILED = 2; |
| // Failed due to a timeout during the main Lacros provisioning. |
| // Excludes timeout during other steps. |
| REASON_PROVISIONING_TIMEDOUT = 3; |
| // General failure in Lacros provisioning. |
| REASON_PROVISIONING_FAILED = 4; |
| } |
| } |
| |
| message ProvisionLacrosMetadata { |
| } |
| |
| message FetchCrashesRequest { |
| // dut is the resource name for the DUT from which to fetch crashes. |
| // The DUT name is passed to the RTD when the RTD is started. |
| // It is not specified whether the name is the DUT hostname. |
| string dut = 1; |
| // If true, fetch the core file. |
| // For uploads to the crash server, that should generally be false. |
| // If the crash file is likely to be used for manual debugging (e.g. on |
| // a manually-invoked test suite run), this might be true. |
| // Coredumps can be extremely large (even gigabytes), so if resource usage |
| // is a concern, this should probably be false. |
| bool fetch_core = 2; |
| } |
| |
| // When this response is streamed, the first proto with a given crash ID will |
| // always contain the CrashInfo. |
| // Files and core dumps (if present) may be streamed. If they are, |
| // subsequent protos with the same crash ID will follow, each containing a chunk |
| // of file/coredump. To reassemble these, concatenate the bytes received from |
| // each subsequent proto with a matching crash_id (concatenate blobs that have |
| // matching crash_ids and keys). |
| // Additional crashes may be reported in the same stream with a new crash ID. |
| message FetchCrashesResponse { |
| // Crash id. unique only within responses to a single FetchCrashes request. |
| // Used to assemble multiple streamed |FetchCrashesResponse| protos into a |
| // single crash report. |
| int64 crash_id = 1; |
| oneof data { |
| // Full details of crash report. |
| CrashInfo crash = 2; |
| // Misc file (e.g. minidump, large binary log, etc) |
| CrashBlob blob = 3; |
| // Coredump. Present iff fetch_core was true in FetchCrashesRequest and |
| // the crash has a coredump. (kernel warnings, for example, do not have |
| // one). |
| bytes core = 4; |
| } |
| } |
| |
| // The data in this proto matches the metadata from crash-reporter's meta files. |
| // Sender::CreateCrashFormData puts this data into crash upload POST requests. |
| // (See src/platform2/crash-reporter/crash_sender_util.cc.) |
| // The names in this proto MUST match the names that crash-reporter uses so |
| // that, when crashes are uploaded to the crash server, they are interpreted |
| // as they are when crash-reporter uploads them. |
| // Similarly, when this proto is converted into a POST request to send to the |
| // crash server, the names must not be altered. |
| message CrashInfo { |
| // Name of executable that crashed (e.g. "chrome") |
| string exec_name = 1; |
| // Product name (e.g. "Chrome_ChromeOS" or "ChromeOS") |
| string prod = 2; |
| // Product version (e.g. "12345.0.0") |
| string ver = 3; |
| // Crash signature (may not be populated for all crashes) |
| string sig = 4; |
| // The name of the integration test that was running when this crash |
| // happened, if any. |
| string in_progress_integration_test = 5; |
| // The name of the collector (e.g. chrome_collector, arc_collector) |
| string collector = 6; |
| // Additional key-value pairs of metadata (e.g. "crash_loop_mode = true"). |
| // These should be included in any POSTs to the crash server in a standard |
| // POST form, as seen in CreateCrashFormData. |
| // (despite the fact that this message is a subfield, it should be a flat |
| // structure in any POSTs). |
| repeated CrashMetadata fields = 7; |
| } |
| |
| // Arbitrary text-only key-value pair corresponding to the key-value pairs in |
| // crash report metadata files. |
| message CrashMetadata { |
| // This value is a UTF8, human-readable, description of the data. |
| string key = 1; |
| // The value will be a human-readable string (e.g. "12345.0.0"), which must |
| // be valid UTF-8. |
| string text = 2; |
| }; |
| |
| // Arbitrary non-UTF8 key-value pair from crash report metadata files. |
| message CrashBlob { |
| // This value is a UTF8, human-readable, description of the data. |
| // This should be passed as the 'name' to the crash server. |
| // For instance, upload_file_fake_payload |
| string key = 1; |
| // The value is a blob (e.g. a file from sysfs or a minidump), which need |
| // not be valid UTF-8, and may be large. |
| bytes blob = 2; |
| // The basename of the file. Must be specified as the filename in data |
| // uploaded to the crash server. |
| // e.g. foo_binary.20201027.102345.0.dmp |
| string filename = 3; |
| }; |
| |
| message ChromeOsImage { |
| oneof path_oneof { |
| // gs_path_prefix is the GS path to where the payloads are located. For |
| // example the format MAY be: |
| // gs://chromeos-image-archive/eve-release/R86-13380.0.0 |
| string gs_path_prefix = 1; |
| } |
| } |
| |
| message FakeOmaha { |
| // name is the resource name of the fake Omaha service. |
| // Format: fakeOmaha/{fake-omaha-id} |
| // The implementation MUST set it after creating the fake Omaha service. |
| // Clients SHOULD NOT set it. |
| string name = 1; |
| // dut is the resource name for the DUT. |
| // The DUT name is passed to the RTD when the RTD is started. |
| // It is not specified whether the name is the DUT hostname. |
| string dut = 2; |
| |
| // target_build is the ChromeOS build that the fake Omaha service will serve |
| // payloads for. |
| ChromeOsImage target_build = 3; |
| |
| message Payload { |
| enum Type { |
| TYPE_UNSPECIFIED = 0; |
| FULL = 1; |
| DELTA = 2; |
| } |
| // id is the id of the payload. It MAY be "ROOTFS" or a DLC id, etc. |
| string id = 1; |
| // type is the payload type, e.g. TYPE_FULL or TYPE_DELTA. |
| Type type = 2; |
| } |
| // payloads is the payloads can be served by the fake Omaha service. |
| repeated Payload payloads = 4; |
| // exposed_via_proxy indicates that the fake Omaha service is exposed to a |
| // DUT via a proxy server, instead of exposing to the DUT directly. So the |
| // service exposing won't be impacted by rebooting the DUT, disconnecting the |
| // DUT network, etc. |
| bool exposed_via_proxy = 5; |
| // critical_update instructs the fake Omaha created that the update is |
| // critical if set. |
| bool critical_update = 6; |
| // return_noupdate_starting indicates from which update check to start returning noupdate. |
| // It MUST be 0 or greater. |
| // When set to 0 (the default value), disables returning noupdate. |
| // If set to positive N, returns noupdate for the Nth check and for every |
| // check thereafter. |
| // For example, if set to 1, returns noupdate starting from the first check, |
| // i.e., always returns noupdate. |
| int32 return_noupdate_starting = 7; |
| // omaha_url is the current fake Omaha service URL which is reachable from |
| // the specified DUT. |
| // The URL can be used as input of the update engine client of the DUT. |
| // The implementation MUST set it after creating the fake Omaha service. |
| // Clients SHOULD NOT set it. |
| string omaha_url = 8; |
| } |
| |
| message CreateFakeOmahaRequest { |
| // fake_omaha is the fake omaha service to be created. |
| FakeOmaha fake_omaha = 1; |
| } |
| |
| message DeleteFakeOmahaRequest { |
| // The resource name of the fake Omaha service to stop. |
| // Format: fakeOmahaServices/{fake-omaha-id} |
| string name = 1; |
| } |