go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/cv/internal/tryjob/storage.proto

// Copyright 2021 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 cv.internal.tryjob;

option go_package = "go.chromium.org/luci/cv/internal/tryjob;tryjob";

import "google/protobuf/timestamp.proto";

import "go.chromium.org/luci/buildbucket/proto/build.proto";
import "go.chromium.org/luci/buildbucket/proto/builder_common.proto";
import "go.chromium.org/luci/buildbucket/proto/common.proto";

import "go.chromium.org/luci/cv/api/config/v2/config.proto";
import "go.chromium.org/luci/cv/api/recipe/v1/cq.proto";

// Definition defines what a Tryjob should do.
//
// It must be sufficient to trigger a new tryjob.
message Definition {
  reserved 7; // experimental

  oneof backend {
    // For buildbucket, it's just a builder.
    Buildbucket buildbucket = 1;
  }

  message Buildbucket {
    string host = 1;
    buildbucket.v2.BuilderID builder = 2;
  }

  // If set, existing tryjob matching this definition is deemed equivalent
  // to the primary Definition.
  //
  // Note that recursive `equivalent_to` is not supported. Also, this doesn't
  // affect triggering a new tryjob.
  Definition equivalent_to = 2;

  // If true, trigger a new tryjob using this Definition regardless of whether
  // reusable tryjobs exist.
  bool disable_reuse = 3;

  // If true, CV should let this Tryjob run even if it becomes stale,
  // e.g. by a new non-trivial patchset on one of this Tryjob's CLs.
  //
  // If the Tryjob is not triggered by CV, then this is value is ignored and in
  // effect it's assumed true. That is, we don't cancel tryjobs not triggered
  // by CV.
  bool skip_stale_check = 4;

  // If true, the Tryjob is deemed critical for the Run to succeed, i.e. the
  // Run will fail unless one of the attempts of this Tryjob is successful.
  bool critical = 5;

  // If true, the Tryjob will be marked as optional.
  //
  // Optional Tryjobs are generally not critical. However, an optional Tryjob
  // could be critical iff it is requested explicitly (i.e. via git footer).
  bool optional = 8;

  // If set to restricted, CV should only post generic messages such as
  //   "Build failed: https://ci.chromium.org/b/1234"
  // and no summary markdown about tryjobs with this definition.
  cv.config.CommentLevel result_visibility = 6;

  // Experiments to enable when launching Tryjob.
  repeated string experiments = 9;
}

// Requirement is what has to happen to verify a specific Run.
//
// It is computed based on the Project Config and specifics of the Run.
message Requirement {
  // Definitions is the definitions of all Tryjobs that should be triggered
  // to verify a specific Run.
  repeated Definition definitions = 1;
  // RetryConfig specifies retries allowed in case of Tryjob failure.
  //
  // No retry allowed if nil.
  cv.config.Verifiers.Tryjob.RetryConfig retry_config = 2;
}

// Status is a high level status of a Tryjob from CV implementation PoV.
enum Status {
  // STATUS_UNSPECIFIED is never used.
  STATUS_UNSPECIFIED = 0;

  // PENDING means Tryjob is being triggered by CV, i.e. it has not yet been
  // triggered, but CV will try to trigger it.
  //
  // *may* not yet have an external ID.
  // *must* have no Result.
  PENDING = 1;

  // TRIGGERED means Tryjob was triggered.
  //
  // *must* have an External ID.
  // *may* have been triggered not by CV, but by another user, service, etc.
  // *may* have a Result, which *may* still change.
  TRIGGERED = 2;

  // ENDED means the Tryjob completed. Final status.
  //
  // *must* have an External ID.
  // *must* have a Result, whose Status is not UNKNOWN.
  ENDED = 3;
  // CANCELLED means Tryjob was cancelled by CV. Final status.
  //
  // *must* have an External ID.
  // *must* have no Result.
  CANCELLED = 4;
  // UNTRIGGERED means Tryjob was never triggered. Final state.
  //
  // *must* have no External ID.
  // *must* have no Result.
  //
  // This status is an implementation detail of CV, used for Tryjobs which
  // weren't actually triggered.
  UNTRIGGERED = 5;
}

// Result of a Tryjob.
//
// It's interpreted by the Run Manager.
message Result {
  // Next tag: 6.

  // Status of the Result.
  //
  // This is the verdict of verification of Run's CLs by this Tryjob.
  Status status = 1;
  enum Status {
    // RESULT_STATUS_UNSPECIFIED is never used.
    RESULT_STATUS_UNSPECIFIED = 0;
    // UNKNOWN means Tryjob didn't reach a conclusion.
    //
    // *must* be used only if Tryjob.Status is TRIGGERED and the Tryjob
    // hasn't made a decision yet.
    UNKNOWN = 1;
    // SUCCEEDED means that Run's CLs are considered OK by this Tryjob.
    SUCCEEDED = 2;
    // FAILED_PERMANENTLY means that Run's CLs are most likely not good.
    FAILED_PERMANENTLY = 3;
    // FAILED_TRANSIENTLY means that Run's CLs are most likely not to blame
    // for the failure.
    // TODO(crbug/1227363): consider removing transiency aspect if possible.
    FAILED_TRANSIENTLY = 4;
    // TIMEOUT means the Tryjob ran over some deadline and did not make a
    // decision about this Run's CLs.
    TIMEOUT = 5;
  }

  // Time when the Tryjob was created in the backend.
  //
  // This is used by CV to determine if the Tryjob is fresh enough to be used
  // to verify a Run.
  google.protobuf.Timestamp create_time = 2;
  // Time when the Tryjob was last updated in the backend.
  //
  // This is used by CV to determine if it needs to refresh Tryjob's Result by
  // querying its backend.
  google.protobuf.Timestamp update_time = 3;

  // Output is a rich result of a Tryjob.
  // This includes details related to retry and reuse.
  //
  // It's typically set by LUCI recipes.
  cq.recipe.Output output = 4;

  // Backend houses backend-specific output.
  oneof backend {
    Buildbucket buildbucket = 5;
  }

  message Buildbucket {
    int64 id = 1;
    buildbucket.v2.BuilderID builder = 4;
    buildbucket.v2.Status status = 2;
    // SummaryMarkdown is a field containing a human readable summary of the
    // build's result.
    string summary_markdown = 3;

    // Infra metadata from Buildbucket.
    //
    // NOTE: This ONLY supports ResultDB metadata and excludes the rest.
    // See go/src/go.chromium.org/luci/buildbucket/proto/build.proto.
    buildbucket.v2.BuildInfra infra = 5;
  }
}

// ExecutionState is the state of executing Tryjobs requirement.
message ExecutionState {
  reserved 4; // failure_reason
  reserved 7; // failure_reason_tmpl
  // Execution tracks the execution state of each individual Tryjob requirement.
  message Execution {
    // Attempt represents each attempt to complete an execution.
    //
    // Failed attempt will trigger a retry attempt if quota allows.
    message Attempt {
      // TryjobId is the ID of this attempt of the Tryjob.
      int64 tryjob_id = 1;
      // ExternalID is the external ID of this attempt of the Tryjob
      string external_id = 2;
      // Status is the status of this attempt of the Tryjob.
      cv.internal.tryjob.Status status = 3;
      // Result of this attempt of the Tryjob.
      cv.internal.tryjob.Result result = 4;
      // Reused indicates the current attempt of the Tryjob wasn't triggered
      // by CV for this Run specifically.
      //
      // In other words, either:
      //  * the Tryjob was triggered by CV for a previous Run, or
      //  * the Tryjob was triggered by non-CV (e.g. `git cl try`).
      bool reused = 5;
    }
    // Attempts records all attempts (including retries) to verify the Run with
    // this Tryjob Execution.
    repeated Attempt attempts = 2;
    // UsedQuota is the quota consumed for retrying the execution of this
    // Tryjob.
    int32 used_quota = 3;
  }
   // Status describes the summarized status of the overall Tryjob execution.
  enum Status {
    // Unspecified is never used.
    STATUS_UNSPECIFIED = 0;
    // At least one critical Tryjob is not yet finished so its result is
    // unknown.
    RUNNING = 1;
    // At least one critical Tryjob in the state failed and cannot be retried.
    FAILED = 2;
    // All the critical Tryjobs in the execution state succeeded.
    SUCCEEDED = 3;
  }
  // Failures describe why the Tryjobs execution fails.
  message Failures {
    // LaunchFailure describes why a Tryjob fails to launch. For example, CV
    // doesn't have the permission to launch the Tryjob.
    message LaunchFailure {
      Definition definition = 1;
      string reason = 2;
    }
    // UnsuccessfulResult contains the ID of the tryjob that ends with
    // non-successful result status (i.e. Build failure).
    message UnsuccessfulResult {
      int64 tryjob_id = 1;
    }
    repeated LaunchFailure launch_failures = 1;
    repeated UnsuccessfulResult unsuccessful_results = 2;
  }
  // Executions track the execution state of all required Tryjobs.
  //
  // It is one to one mapped to `requirement.definitions`
  repeated Execution executions = 1;
  // Requirement is the requirement that is currently being worked on.
  Requirement requirement = 2;
  // The version of the requirement that is currently being worked on.
  int32 requirement_version = 5;
  // Status will be set to SUCCEEDED if all Tryjobs succeed,
  // FAILED if at least one Tryjob fails and cannot be retried,
  // or RUNNING otherwise.
  Status status = 3;
  // Failures describe why the Tryjob execution has failed.
  //
  // Must set if status == FAILED.
  Failures failures = 8;
  // The time when the executions end with a terminal status
  google.protobuf.Timestamp end_time = 6;
}

// ExecutionLogEntries contains a list of log entries ordered by time.
message ExecutionLogEntries {
  repeated ExecutionLogEntry entries = 1;
}

// ExecutionLogEntry records what happened during Tryjob Execution.
message ExecutionLogEntry {
  reserved 6;
  // Time is when the event occurs.
  google.protobuf.Timestamp time = 1;
  oneof kind {
    RequirementChanged requirement_changed = 2;
    TryjobsLaunched tryjobs_launched = 3;
    TryjobsLaunchFailed tryjobs_launch_failed = 4;
    TryjobsReused tryjobs_reused = 5;
    TryjobsEnded tryjobs_ended = 8;
    TryjobDiscarded tryjob_discarded = 7;
    RetryDenied retry_denied = 9;
  }

  message RequirementChanged {
    // TODO(yiwzhang): provide more detail on the config revision change
    // that cause the requirement change.
  }

  message TryjobSnapshot {
    int64 id = 1;
    string external_id = 2;
    Definition definition = 3;
    Status status = 4;
    Result result = 5;
    bool reused = 6;
  }

  message TryjobsLaunched {
    reserved 1;
    repeated TryjobSnapshot tryjobs = 2;
  }

  message TryjobsLaunchFailed {
    repeated TryjobLaunchFailed tryjobs = 1;
  }

  message TryjobLaunchFailed {
    Definition definition = 1;
    string reason = 2;
  }

  message TryjobsReused {
    reserved 1;
    repeated TryjobSnapshot tryjobs = 2;
  }

  message TryjobsEnded {
    reserved 1;
    repeated TryjobSnapshot tryjobs = 2;
  }

  message TryjobDiscarded{
    TryjobSnapshot snapshot = 1;
    string reason = 2;
  }

  message RetryDenied {
    repeated TryjobSnapshot tryjobs =1;
    string reason = 2;
  }
}

// TryjobUpdatedEvent describes which Tryjob entity is updated.
message TryjobUpdatedEvent {
  int64 tryjob_id = 1;
}

// TryjobUpdatedEvents is a batch of TryjobUpdatedEvent.
message TryjobUpdatedEvents {
  repeated TryjobUpdatedEvent events = 1;
}