go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/resultdb/proto/v1/resultdb.proto

// Copyright 2019 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package luci.resultdb.v1;

import "google/api/field_behavior.proto";
import "google/protobuf/field_mask.proto";
import "go.chromium.org/luci/resultdb/proto/v1/artifact.proto";
import "go.chromium.org/luci/resultdb/proto/v1/invocation.proto";
import "go.chromium.org/luci/resultdb/proto/v1/predicate.proto";
import "go.chromium.org/luci/resultdb/proto/v1/test_result.proto";
import "go.chromium.org/luci/resultdb/proto/v1/test_variant.proto";
import "go.chromium.org/luci/resultdb/proto/v1/test_metadata.proto";

option go_package = "go.chromium.org/luci/resultdb/proto/v1;resultpb";

// Service to read test results.
service ResultDB {
  // Retrieves an invocation.
  rpc GetInvocation(GetInvocationRequest) returns (Invocation) {};

  // == Test results ===========================================================

  // Retrieves a test result.
  rpc GetTestResult(GetTestResultRequest) returns (TestResult) {};

  // Retrieves test results for a parent invocation.
  //
  // Note: response does not contain test results of included invocations.
  // Use QueryTestResults instead.
  rpc ListTestResults(ListTestResultsRequest)
      returns (ListTestResultsResponse) {};

  // Retrieves a test exoneration.
  rpc GetTestExoneration(GetTestExonerationRequest) returns (TestExoneration) {
  };

  // Retrieves test exonerations for a parent invocation.
  //
  // Note: response does not contain test results of included invocations.
  // Use QueryTestExonerations instead.
  rpc ListTestExonerations(ListTestExonerationsRequest)
      returns (ListTestExonerationsResponse) {};

  // Retrieves test results from an invocation, recursively.
  // Supports invocation inclusions.
  // Supports advanced filtering.
  // Examples: go/resultdb-rpc#querytestresults
  rpc QueryTestResults(QueryTestResultsRequest)
      returns (QueryTestResultsResponse) {};

  // Retrieves test exonerations from an invocation.
  // Supports invocation inclusions.
  // Supports advanced filtering.
  rpc QueryTestExonerations(QueryTestExonerationsRequest)
      returns (QueryTestExonerationsResponse) {};

  // Retrieves the test result statistics of an invocation.
  // Currently supports total number of test results belong to the invocation,
  // directly and indirectly.
  rpc QueryTestResultStatistics(QueryTestResultStatisticsRequest)
      returns (QueryTestResultStatisticsResponse) {};

  // Calculate new test variants by running the difference between the tests
  // run in the given invocation against the submitted test history for the
  // source.
  rpc QueryNewTestVariants(QueryNewTestVariantsRequest)
      returns (QueryNewTestVariantsResponse) {};

  // == Artifacts =============================================================

  // Retrieves an artifact.
  rpc GetArtifact(GetArtifactRequest) returns (Artifact) {};

  // Retrieves artifacts for a parent invocation/testResult.
  //
  // Note: if the parent is an invocation, the response does not contain
  // artifacts of included invocations. Use QueryArtifacts instead.
  rpc ListArtifacts(ListArtifactsRequest) returns (ListArtifactsResponse) {};

  // Retrieves artifacts from an invocation, recursively.
  // Can retrieve artifacts of test results included in the invocation
  // directly or indirectly.
  // Supports invocation inclusions.
  rpc QueryArtifacts(QueryArtifactsRequest) returns (QueryArtifactsResponse) {};

  // Retrieves test variants from an invocation, recursively.
  // Supports invocation inclusions.
  rpc QueryTestVariants(QueryTestVariantsRequest) returns (QueryTestVariantsResponse) {};

  // Retrieves test variants from a single invocation, matching the specified
  // test IDs and hashes.
  rpc BatchGetTestVariants(BatchGetTestVariantsRequest) returns (BatchGetTestVariantsResponse) {};

  // Retrieves test metadata from a LUCI project, matching the predicate.
  rpc QueryTestMetadata(QueryTestMetadataRequest) returns (QueryTestMetadataResponse) {};
}

// A request message for GetInvocation RPC.
message GetInvocationRequest {
  // The name of the invocation to request, see Invocation.name.
  string name = 1 [ (google.api.field_behavior) = REQUIRED ];
}

// A request message for GetTestResult RPC.
message GetTestResultRequest {
  // The name of the test result to request, see TestResult.name.
  string name = 1 [ (google.api.field_behavior) = REQUIRED ];
}

// A request message for ListTestResults RPC.
message ListTestResultsRequest {
  // Name of the invocation, e.g. "invocations/{id}".
  string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

  // The maximum number of test results to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 test results will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 2;

  // A page token, received from a previous `ListTestResults` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListTestResults` MUST
  // match the call that provided the page token.
  string page_token = 3;

  // Fields to include in the response.
  // If not set, the default mask is used where summary_html and tags are
  // excluded.
  // Test result names will always be included even if "name" is not a part of
  // the mask.
  google.protobuf.FieldMask read_mask = 4;
}

// A response message for ListTestResults RPC.
message ListTestResultsResponse {
  // The test results from the specified invocation.
  repeated TestResult test_results = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  // If the invocation is not finalized, more results may appear later.
  string next_page_token = 2;
}

// A request message for GetTestExoneration RPC.
message GetTestExonerationRequest {
  // The name of the test exoneration to request, see TestExoneration.name.
  string name = 1;
}

// A request message for ListTestExonerations RPC.
message ListTestExonerationsRequest {
  // Name of the invocation, e.g. "invocations/{id}".
  string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

  // The maximum number of test exonerations to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 test exonerations will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 2;

  // A page token, received from a previous `ListTestExonerations` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListTestExonerations`
  // MUST match the call that provided the page token.
  string page_token = 3;
}

// A response message for ListTestExonerations RPC.
message ListTestExonerationsResponse {
  // The test exonerations from the specified invocation.
  repeated TestExoneration test_exonerations = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  // If the invocation is not finalized, more results may appear later.
  string next_page_token = 2;
}

// A request message for QueryTestResults RPC.
message QueryTestResultsRequest {
  // Retrieve test results included in these invocations, directly or indirectly
  // (via Invocation.included_invocations).
  //
  // Specifying multiple invocations is equivalent to querying one invocation
  // that includes these.
  repeated string invocations = 1;

  // A test result in the response must satisfy this predicate.
  TestResultPredicate predicate = 2;

  // The maximum number of test results to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 test results will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 4;

  // A page token, received from a previous `QueryTestResults` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `QueryTestResults` MUST
  // match the call that provided the page token.
  string page_token = 5;

  // Fields to include in the response.
  // If not set, the default mask is used where summary_html and tags are
  // excluded.
  // Test result names will always be included even if "name" is not a part of
  // the mask.
  google.protobuf.FieldMask read_mask = 6;
}

// A response message for QueryTestResults RPC.
message QueryTestResultsResponse {
  // Matched test results.
  // Ordered by parent invocation ID, test ID and result ID.
  repeated TestResult test_results = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  string next_page_token = 2;
}

// A request message for QueryTestExonerations RPC.
message QueryTestExonerationsRequest {
  // Retrieve test exonerations included in these invocations, directly or
  // indirectly (via Invocation.included_invocations).
  //
  // Specifying multiple invocations is equivalent to querying one invocation
  // that includes these.
  repeated string invocations = 1;

  // A test exoneration in the response must satisfy this predicate.
  TestExonerationPredicate predicate = 2
      [ (google.api.field_behavior) = REQUIRED ];

  // The maximum number of test exonerations to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 test exonerations will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 4;

  // A page token, received from a previous `QueryTestExonerations` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `QueryTestExonerations`
  // MUST match the call that provided the page token.
  string page_token = 5;
}

// A response message for QueryTestExonerations RPC.
message QueryTestExonerationsResponse {
  // The test exonerations matching the predicate.
  // Ordered by parent invocation ID, test ID and exoneration ID.
  repeated TestExoneration test_exonerations = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  string next_page_token = 2;
}

// A request message for QueryTestResultStatistics RPC.
message QueryTestResultStatisticsRequest {
  // Retrieve statistics of test result belong to these invocations,
  // directly or indirectly (via Invocation.included_invocations).
  //
  // Specifying multiple invocations is equivalent to requesting one invocation
  // that includes these.
  repeated string invocations = 1;
}

// A response message for QueryTestResultStatistics RPC.
message QueryTestResultStatisticsResponse {
  // Total number of test results.
  int64 total_test_results = 1;
}

// A request message for GetArtifact RPC.
message GetArtifactRequest {
  // The name of the artifact to request, see Artifact.name.
  string name = 1 [ (google.api.field_behavior) = REQUIRED ];
}

// A request message for ListArtifacts RPC.
message ListArtifactsRequest {
  // Name of the parent, e.g. an invocation (see Invocation.name) or
  // a test result (see TestResult.name).
  string parent = 1 [ (google.api.field_behavior) = REQUIRED ];

  // The maximum number of artifacts to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 artifacts will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 2;

  // A page token, received from a previous `ListArtifacts` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListArtifacts` MUST
  // match the call that provided the page token.
  string page_token = 3;
}

// A response message for ListArtifacts RPC.
message ListArtifactsResponse {
  // The artifacts from the specified parent.
  repeated Artifact artifacts = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  // If the invocation is not finalized, more results may appear later.
  string next_page_token = 2;
}

// A request message for QueryArtifacts RPC.
message QueryArtifactsRequest {
  // Retrieve artifacts included in these invocations, directly or indirectly
  // (via Invocation.included_invocations and via contained test results).
  //
  // Specifying multiple invocations is equivalent to querying one invocation
  // that includes these.
  repeated string invocations = 1;

  // An artifact in the response must satisfy this predicate.
  ArtifactPredicate predicate = 2;

  // The maximum number of artifacts to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 artifacts will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 4;

  // A page token, received from a previous `QueryArtifacts` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `QueryArtifacts` MUST
  // match the call that provided the page token.
  string page_token = 5;
}

// A response message for QueryArtifacts RPC.
message QueryArtifactsResponse {
  // Matched artifacts.
  // First invocation-level artifacts, then test-result-level artifacts
  // ordered by parent invocation ID, test ID and artifact ID.
  repeated Artifact artifacts = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  string next_page_token = 2;
}

// A request message for QueryTestVariants RPC.
// Next id: 9.
message QueryTestVariantsRequest {
  // Retrieve test variants included in these invocations, directly or indirectly
  // (via Invocation.included_invocations).
  //
  // Specifying multiple invocations is equivalent to querying one invocation
  // that includes these.
  repeated string invocations = 2;

  // A test variant must satisfy this predicate.
  TestVariantPredicate predicate = 6;

  // The maximum number of test results to be included in a test variant.
  //
  // If a test variant has more results than the limit, the remaining results
  // will not be returned.
  // If unspecified, at most 10 results will be included in a test variant.
  // The maximum value is 100; values above 100 will be coerced to 100.
  int32 result_limit = 8;

  // The maximum number of test variants to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 100 test variants will be returned.
  // The maximum value is 10,000; values above 10,000 will be coerced to 10,000.
  int32 page_size = 4;

  // A page token, received from a previous `QueryTestVariants` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `QueryTestVariants` MUST
  // match the call that provided the page token.
  string page_token = 5;

  // Fields to include in the response.
  // If not set, the default mask is used where all fields are included.
  //
  // The following fields in results.*.result will NEVER be included even when
  // specified:
  // * test_id
  // * variant_hash
  // * variant
  // * test_metadata
  // Those values can be found in the parent test variant objects.
  //
  // The following fields will ALWAYS be included even when NOT specified:
  // * test_id
  // * variant_hash
  // * status
  google.protobuf.FieldMask read_mask = 7;
}

// A response message for QueryTestVariants RPC.
message QueryTestVariantsResponse {
  // Matched test variants.
  // Ordered by TestVariantStatus, test_id, then variant_hash
  repeated TestVariant test_variants = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  string next_page_token = 2;

  // The code sources tested by the returned test variants. The sources are keyed
  // by an ID which allows them to be cross-referenced from TestVariant.sources_id.
  //
  // The sources are returned via this map instead of directly on the TestVariant
  // to avoid excessive response size. Each source message could be up to a few
  // kilobytes and there are usually no more than a handful of different sources
  // tested in an invocation, so deduplicating them here reduces response size.
  map<string, Sources> sources = 3;
}

// A request message for BatchGetTestVariants RPC.
message BatchGetTestVariantsRequest {
  message TestVariantIdentifier {
    // The unique identifier of the test in a LUCI project. See the comment on
    // TestResult.test_id for full documentation.
    string test_id = 1 [ (google.api.field_behavior) = REQUIRED ];

    // Hash of the variant. See the comment on TestResult.variant_hash for full
    // documentation.
    string variant_hash = 2 [ (google.api.field_behavior) = REQUIRED ];
  }

  // Name of the invocation that the test variants are in.
   string invocation = 1;

  // A list of test IDs and variant hashes, identifying the requested test
  // variants. Size is limited to 500. Any request for more than 500 variants
  // will return an error.
  repeated TestVariantIdentifier test_variants = 2;

  // The maximum number of test results to be included in a test variant.
  //
  // If a test variant has more results than the limit, the remaining results
  // will not be returned.
  // If unspecified, at most 10 results will be included in a test variant.
  // The maximum value is 100; values above 100 will be coerced to 100.
  int32 result_limit = 3;
}

// A response message for BatchGetTestVariants RPC.
message BatchGetTestVariantsResponse {
  // Test variants matching the requests. Any variants that weren't found are
  // omitted from the response. Clients shouldn't rely on the ordering of this
  // field, as no particular order is guaranteed.
  repeated TestVariant test_variants = 1;

  // The code sources tested by the returned test variants. The sources are keyed
  // by an ID which allows them to be cross-referenced from TestVariant.sources_id.
  //
  // The sources are returned via this map instead of directly on the TestVariant
  // to avoid excessive response size. Each source message could be up to a few
  // kilobytes and there are usually no more than a handful of different sources
  // tested in an invocation, so deduplicating them here reduces response size.
  map<string, Sources> sources = 2;
}

// A request message for QueryTestMetadata RPC.
message QueryTestMetadataRequest {
  // The LUCI Project to query.
  string project = 1 [(google.api.field_behavior) = REQUIRED];

  // Filters to apply to the returned test metadata.
  TestMetadataPredicate predicate = 2;

  // The maximum number of test metadata entries to return.
  //
  // The service may return fewer than this value.
  // If unspecified, at most 1000 test metadata entries will be returned.
  // The maximum value is 100K; values above 100K will be coerced to 100K.
  int32 page_size = 3;

  // A page token, received from a previous `QueryTestMetadata` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `QueryTestMetadata` MUST
  // match the call that provided the page token.
  string page_token = 4;
}

// A response message for QueryTestMetadata RPC.
message QueryTestMetadataResponse {
  // The matched testMetadata.
  repeated TestMetadataDetail testMetadata = 1;

  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there were no subsequent pages at the time of
  // request.
  string next_page_token = 2;
}

// A request message for QueryNewTestVariants RPC.
// To use this RPC, callers need:
// - resultdb.baselines.get in the realm the <baseline_project>:@project, where
//   baseline_project is the LUCI project that contains the baseline.
// - resultdb.testResults.list in the realm of the invocation which is being
//   queried.
message QueryNewTestVariantsRequest {
  // Name of the invocation, e.g. "invocations/{id}".
  string invocation = 1 [ (google.api.field_behavior) = REQUIRED ];

  // The baseline to compare test variants against, to determine if they are new.
  // e.g. “projects/{project}/baselines/{baseline_id}”.
  // For example, in the project "chromium", the baseline_id may be
  // "try:linux-rel".
  string baseline = 2 [ (google.api.field_behavior) = REQUIRED ];
}

// A response message for QueryNewTestVariants RPC.
message QueryNewTestVariantsResponse {

  // Represents a new test, which contains minimal information to uniquely identify a TestVariant.
  message NewTestVariant {
    // A unique identifier of the test in a LUCI project.
    // Regex: ^[[::print::]]{1,256}$
    //
    // Refer to TestResult.test_id for details.
    string test_id = 1;

    // Hash of the variant.
    // hex(sha256(sorted(''.join('%s:%s\n' for k, v in variant.items())))).
    string variant_hash = 2;
  }

  // Indicates whether the baseline has been populated with at least 72 hours
  // of data and the results can be relied upon.
  bool is_baseline_ready = 1;


  // Test variants that are new, meaning that they have not been part of
  // a submitted run prior.
  repeated NewTestVariant new_test_variants = 2;
}