// Copyright 2019 The ChromiumOS Authors
// 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.rtd.v1;

option go_package = "go.chromium.org/chromiumos/config/go/api/test/rtd/v1;rtd";

import "chromiumos/config/api/test/results/v2/result.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);
}

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

  // Result to report.
  chromiumos.config.api.test.results.v2.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 {}