// 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 test.rtd.v1;

option go_package = "go.chromium.org/chromiumos/infra/proto/go/test/invocation";

import "google/protobuf/struct.proto";

// Configuration data needed by clients of ProgressSink.
message ProgressSinkClientConfig {
  // Local TCP port to be used by the Remote Test Driver to communicate with
  // InvocationProgressSink service.
  int32 port = 1;
}

// A service implemented by Remote Test Servers, used to report progress from a
// Remote Test Driver invocation.
//
// A simple implementation of Remote Test Driver may report progress at the
// end of the invocation for all requests together. Real implementations should
// report incremental progress during the invocation.
//
// A progress sink service instance is tied to a single Invocation. There must
// always be a single Remote Test Driver invocation inside a Remote Test Server.
// If a Test Lab Environment desires to share a ProgressSink instance across
// various Remote Test Servers, a way to dinstinguish the different Remote Test
// Driver clients must be determined, which is not supported directly by the
// following API.
service ProgressSink {
  // A Remote Test Driver invocation must call ReportResult exactly once per
  // request.
  rpc ReportResult(ReportResultRequest) returns (ReportResultResponse);

  // A log stream from the Remote Test Driver invocation.
  //
  // Each call to this method must stream logs for a single invocation request
  // and log file. Data for the same file may be split over multiple ReportLog
  // calls. Data received from concurrent methods calls for the same log file
  // may be interleved arbitrarily.
  rpc ReportLog(stream ReportLogRequest) returns (ReportLogResponse);

  // Archive test artifacts to non-ephemeral storage.
  //
  // Different Test Lab Environments may use very different non-ephemeral
  // storage technologies. Remote Test Servers must archive the artifacts to
  // final storage synchronously and return an error if the archival fails.
  //
  // Note: Remote Test Drivers should use ReportLog() to report logs.
  // ArchiveArtifact() should be used to report structured or binary data only.
  //
  // Remote Test Server may limit the size of artifacts that may be offloaded
  // per request and may fail further requests with RESOURCE_EXHAUSTED.
  rpc ArchiveArtifact(ArchiveArtifactRequest) returns (ArchiveArtifactResponse);
}

// Result for a single invocation request.
message Result {
  // Enum entries *may* be added to this enum in the future.
  enum State {
    // No end state specified. Must not be used.
    STATE_UNSPECIFIED = 0;
    // Test request succeeded. All was well.
    SUCCEEDED = 1;
    // Test request failed. See `error` for more information.
    FAILED = 2;
    // Test did not run because the Remote Test Driver decided to skip it.
    //
    // Common reasons a test may be skipped:
    //
    // * A runtime check by the Remote Test Driver concluded that the test is
    //   not applicable to the targeted device(s). The Remote Test Driver should
    //   include detailed reasons in `errors`.
    SKIPPED = 3;
  }
  // Final state of the test execution.
  //
  // Error details must be available in `errors` if state != SUCCEEDED.
  State state = 1;

  message Error {
    // Enum entries *may* be added in the future.
    enum Source {
      // No Source specified. Should not be used.
      //
      // If source is unspecified, the Test Lab Environment should assume the
      // source to be the Remote Test Driver.
      SOURCE_UNSPECIFIED = 0;
      // The test failed.
      TEST = 1;
      // There was an error in Remote Test Driver invocation.
      REMOTE_TEST_DRIVER = 2;
      // There was an error in a Test Lab Services API call.
      TEST_LAB_SERVICES = 3;
    }

    // Provenance of the detected error.
    Source source = 1;

    // Enum entries *may* be added in the future.
    enum Severity {
      // No Severity set. Should not be used.
      SEVERITY_UNSPECIFIED = 0;
      // Remote Test Server should validate that a Result contains a CRITICAL
      // message iff state == FAILED.
      CRITICAL = 1;
      // Must not, by itself, lead to a FAILED Result.state.
      WARNING = 2;
    }

    // Severity of reported error.
    Severity severity = 2;

    // Machine parseable details about the error.
    //
    // Test Lab Environments and Remote Test Servers must not interpret the
    // details.
    //
    // Remote Test Drivers should use uniform stable schema for `details` to
    // enable robust analytics.
    google.protobuf.Struct details = 3;
  }

  // errors must be set if state != SUCCEEDED.
  //
  // errors may be provided even if state == SUCCEEDED. Remote Test Drivers are
  // encouraged to provide multiple observed errors in Result to aid end-user
  // visibility of problems encountered.
  repeated Error errors = 2;
}

message ReportResultRequest {
  // The request to report results for, identified by the
  // Invocation.Request.name field.
  string request = 1;

  // Result to report.
  Result result = 2;
}

message ReportResultResponse {
  // If set, the invocation should immediately terminate, skipping remaining
  // requests.
  bool terminate = 1;
}

message ReportLogRequest {
  // Name of the log sink.
  //
  // name may be interpreted as a local file path or part of a URL. name must be
  // a valid resource name per https://aip.dev/122 and must be a valid POSIX
  // file path.
  string name = 1;

  // The request to report logs for, identified by the
  // Invocation.Request.name field.
  string request = 2;

  // Uninterpreted chunk of log-data.
  bytes data = 3;
}

message ReportLogResponse {}

message ArchiveArtifactRequest {
  // Name for the archived artifact.
  //
  // name may be interpreted as a local file path or part of a URL. name must be
  // a valid resource name per https://aip.dev/122 and must be a valid POSIX
  // file path.
  //
  // name must be unique across all artifacts archived from a single invocation
  // request.
  string name = 1;

  // The request to archive artifacts for, identified by the
  // Invocation.Request.name field.
  string request = 2;

  // Absolute path to a file or directory to archive.
  string local_path = 3;
}

message ArchiveArtifactResponse {}