/*
 * Copyright (C) 2024 The Android Open Source Project
 *
 * 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/protobuf/timestamp.proto";

option go_package = "go.chromium.org/luci/resultdb/proto/v1;resultpb";
option java_package = "com.android.resultdb.proto";
option java_multiple_files = true;

// A key-value map describing one variant of a test case.
//
// The same test case can be executed in different ways, for example on
// different OS, GPUs, with different compile options or runtime flags.
// A variant definition captures one variant.
// A test case with a specific variant definition is called test variant.
//
// Guidelines for variant definition design:
// - This rule guides what keys MUST be present in the definition.
//   A single expected result of a given test variant is enough to consider it
//   passing (potentially flakily). If it is important to differentiate across
//   a certain dimension (e.g. whether web tests are executed with or without
//   site per process isolation), then there MUST be a key that captures the
//   dimension (e.g. a name from test_suites.pyl).
//   Otherwise, a pass in one variant will hide a failure of another one.
//
// - This rule guides what keys MUST NOT be present in the definition.
//   A change in the key-value set essentially resets the test result history.
//   For example, if GN args are among variant key-value pairs, then adding a
//   new GN arg changes the identity of the test variant and resets its history.
//
// In Chromium, variant keys are:
// - bucket: the LUCI bucket, e.g. "ci"
// - builder: the LUCI builder, e.g. "linux-rel"
// - test_suite: a name from
//   https://cs.chromium.org/chromium/src/testing/buildbot/test_suites.pyl
message Variant {
  // The definition of the variant.
  // Key and values must be valid StringPair keys and values, see their
  // constraints.
  map<string, string> def = 1;
}

// A string key-value pair. Typically used for tagging, see Invocation.tags
message StringPair {
  // Regex: ^[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)*$
  // Max length: 64.
  string key = 1;

  // Max length: 256.
  string value = 2;
}

// GitilesCommit specifies the position of the gitiles commit an invocation
// ran against, in a repository's commit log. More specifically, a ref's commit
// log.
//
// It also specifies the host/project/ref combination that the commit
// exists in, to provide context.
message GitilesCommit {
  // The identity of the gitiles host, e.g. "chromium.googlesource.com".
  // Mandatory.
  string host = 1;

  // Repository name on the host, e.g. "chromium/src". Mandatory.
  string project = 2;

  // Commit ref, e.g. "refs/heads/main" from which the commit was fetched.
  // Not the branch name, use "refs/heads/branch"
  // Mandatory.
  string ref = 3;

  // Commit HEX SHA1. All lowercase. Mandatory.
  string commit_hash = 4;

  // Defines a total order of commits on the ref.
  // A positive, monotonically increasing integer. The recommended
  // way of obtaining this is by using the goto.google.com/git-numberer
  // Gerrit plugin. Other solutions can be used as well, so long
  // as the same scheme is used consistently for a ref.
  // Mandatory.
  int64 position = 5;
}

// A Gerrit patchset.
message GerritChange {
  // Gerrit hostname, e.g. "chromium-review.googlesource.com".
  string host = 1;
  // Gerrit project, e.g. "chromium/src".
  string project = 2;
  // Change number, e.g. 12345.
  int64 change = 3;
  // Patch set number, e.g. 1.
  int64 patchset = 4;
}

// Deprecated: Use GitilesCommit instead.
message CommitPosition {
  // The following fields identify a git repository and a ref within which the
  // numerical position below identifies a single commit.
  string host = 1;
  string project = 2;
  string ref = 3;

  // The numerical position of the commit in the log for the host/project/ref
  // above.
  int64 position = 4;
}

// Deprecated: Do not use.
message CommitPositionRange {
  // The lowest commit position to include in the range.
  CommitPosition earliest = 1;

  // Include only commit positions that that are strictly lower than this.
  CommitPosition latest = 2;
}

// A range of timestamps.
//
// Currently unused.
message TimeRange {
  // The oldest timestamp to include in the range.
  google.protobuf.Timestamp earliest = 1;

  // Include only timestamps that are strictly older than this.
  google.protobuf.Timestamp latest = 2;
}


// Represents a reference in a source control system.
message SourceRef {
  // The source control system used.
  // Only gitiles is supported at this moment. If other systems need to be
  // supported in future (e.g. non-gitiles git, subversion, google storage
  // buckets), they can be added here
  oneof system {
    // A branch in gitiles repository.
    GitilesRef gitiles = 1;
  }
}

// Represents a branch in a gitiles repository.
message GitilesRef {
  // The gitiles host, e.g. "chromium.googlesource.com".
  string host = 1;

  // The project on the gitiles host, e.g. "chromium/src".
  string project = 2;

  // Commit ref, e.g. "refs/heads/main" from which the commit was fetched.
  // Not the branch name, use "refs/heads/branch"
  string ref = 3;
}