cv/internal/run/storage.proto

// Copyright 2020 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.run;

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

import "google/protobuf/timestamp.proto";

import "go.chromium.org/luci/cv/internal/tryjob/storage.proto";
import "go.chromium.org/luci/cv/internal/run/eventpb/submission.proto";

// Status describes the status of a CV Run.
enum Status {
  // Unspecified status.
  STATUS_UNSPECIFIED = 0;
  // Run is pending to start.
  //
  // It is either because Run Manager hasn't processed the StartEvent yet or
  // the RunOwner has exhausted all the quota and waiting for new quota to
  // be available.
  PENDING = 1;
  // Run is running.
  RUNNING = 2;
  // Run is waiting for submission.
  //
  // Run is in this status if one of the following scenario is true:
  //   1. Tree is closed at the time Run attempts to submit.
  //   2. There is another Run in the same LUCI Project that is currently
  //      submitting.
  //   3. The submission is rate limited according to the submit option in
  //      Project Config.
  //
  // This status is cancellable.
  WAITING_FOR_SUBMISSION = 4;
  // Run is submitting.
  //
  // A Run can't be cancelled while submitting. A Run may transition from
  // this status to either `WAITING_FOR_SUBMISSION` status or a non-cancelled
  // terminal status.
  SUBMITTING = 5;

  // End of non-terminal status; MUST have value less than `ENDED_MASK`.

  /////////////////////////////////////////////////////////////////////////////
  // Terminal Status

  // ENDED_MASK can be used as a bitmask to check if a Run has ended.
  // This MUST NOT be used as the status of a Run.
  ENDED_MASK = 64;
  // Run ends successfully.
  SUCCEEDED = 65;
  // Run ends unsuccessfully.
  FAILED = 66;
  // Run is cancelled.
  CANCELLED = 67;
}

// Trigger describes who/how CV was triggered on a specific CL.
message Trigger {
  google.protobuf.Timestamp time = 1;
  // Mode is string value of run.Mode.
  string mode = 2;
  // Additional label is recorded in case applicable ConfigGroup had additional
  // modes, e.g. for QUICK_DRY_RUN mode.
  string additional_label = 5;
  // Triggering user email if known.
  //
  // Gerrit doesn't guarantee that every user has set their preferred email,
  // but LUCI ACLs are based entirely on user emails. Thus, Runs with the email
  // unset are quickly aborted by CQDaemon.
  //
  // TODO(tandrii): once CQDaemon is deleted, require email to start a Run,
  // and remove Gerrit-specific gerrit_account_id.
  string email = 3;
  // Gerrit account ID. Always known.
  int64 gerrit_account_id = 4;
}

// Submission describes the state of Run submission.
message Submission {
  // The deadline of this submission.
  //
  // If the deadline is not set or has already expired, a RunManager task
  // can claim the exclusive privilege by setting the deadline to a future
  // timestamp (generally, end of task deadline).
  google.protobuf.Timestamp deadline = 1;
  // ID of the task that executes this submission.
  string task_id = 2;
  // IDs of all CLs that should be submitted in this submission.
  //
  // Must be ordered in submission order.
  repeated int64 cls = 3;
  // IDs of all CLs that have been submitted successfully already.
  repeated int64 submitted_cls = 4;
  // IDs of all CLs that fails to submit if any.
  //
  // CLs that are neither in this list nor in the `submitted_cls` should be
  // treated as if CV has never attempted to submit them.
  //
  // This could be empty even when the entire submission fails, which would be
  // typically caused by faulty infrastructure (e.g. Task Queue not executing
  // a Run Manager task before the whole submission timeout is reached).
  repeated int64 failed_cls = 5;
  // If True, Tree is currently in open state.
  bool tree_open = 10;
  // The timestamp when the Tree status was last fetched.
  google.protobuf.Timestamp last_tree_check_time = 11;
}

// Options are Run-specific additions on top of LUCI project config.
message Options {
  // If true, submitting the Run isn't blocked on open tree.
  //
  // If false (default), respects project configuration.
  bool skip_tree_checks = 1;

  // If true, `builders.equivalent_to{...}` sections are ignored when triggering
  // tryjobs.
  //
  // If false (default), respects project configuration.
  bool skip_equivalent_builders = 2;

  // If true, no longer useful tryjobs won't be cancelled.
  //
  // If false (default), respects project configuration.
  bool avoid_cancelling_tryjobs = 3;

  // If true, no tryjobs will be triggered except "presubmit" regardless of
  // project configuration.
  //
  // "presubmit" builders are legacy which are currently configured with
  // "disable_reuse: true" in project config. To skip triggering them,
  // skip_presubmit must be set to true.
  // TODO(https://crbug.com/950074): ignore.
  //
  // If false (default), respects project configuration.
  bool skip_tryjobs = 4;
  // Deprecated per https://crbug.com/950074.
  // See skip_tryjobs doc.
  bool skip_presubmit = 5;

  // TODO(tandrii): add CQ_INCLUDE_TRYBOTS / Cq-Include-Trybots.
}

// LogEntries contains 1+ LogEntry ordered from logically oldest to newest.
message LogEntries {
  repeated LogEntry entries = 1;
}

// LogEntry records what changed in a Run.
message LogEntry {
  // Next tag: 7.

  // Time is when something was changed.
  google.protobuf.Timestamp time = 1;
  oneof kind {
    // Run was created.
    Created created = 2;
    // Run was started.
    Started started = 6;
    // Run updated to a new project config version.
    ConfigChanged config_changed = 3;
    // Tryjobs requirement was (re-)computed.
    TryjobsRequirementUpdated tryjobs_requirement_updated = 4;
    // Applicable tryjobs were updated.
    TryjobsUpdated tryjobs_updated = 5;
    // TODO(crbug/1232158): add & implement events related to Submission and
    // ending of the Run.

    // Intended for informational logs (E.g. temporary/during migration)
    Info info = 7;
    // The tree is configured and was checked.
    TreeChecked tree_checked = 8;
    // The run has been added to the submit queue's waitlist.
    Waitlisted waitlisted = 9;
    // The run is current on the queue.
    AcquiredSubmitQueue acquired_submit_queue = 10;
    ReleasedSubmitQueue released_submit_queue = 11;
    // CL(s) submitted successfully.
    CLSubmitted cl_submitted = 12;
    // Submission failed.
    SubmissionFailure submission_failure = 13;
    RunEnded run_ended = 14;
  }

  message Created {
    string config_group_id = 1;
  }
  message Started {
  }
  message ConfigChanged {
    string config_group_id = 1;
  }
  message TryjobsRequirementUpdated {
    // TODO(crbug/1227363): define a Tryjobs.Requirement diff.
  }
  message Info {
    // If you have the need to add fields here, consider instead adding a new
    // dedicated kind
    string label = 1;
    string message = 2;
  }
  message TryjobsUpdated {
    // Which tryjobs had a meaningful change (e.g. change of status).
    repeated Tryjob tryjobs = 2;
  }
  message TreeChecked{
    bool open = 1;
  }
  message Waitlisted{
  }
  message AcquiredSubmitQueue{
  }
  message ReleasedSubmitQueue{
  }
  message CLSubmitted{
    // The CLs that were submitted in this event.
    repeated int64 newly_submitted_cls = 1;
    // The number of CLs submitted for this run, so far.
    int64 total_submitted = 2;
  }
  message SubmissionFailure{
    cv.internal.run.eventpb.SubmissionCompleted event = 1;
  }
  message RunEnded{
  }
}

// Tryjobs is the state of Run's tryjobs.
message Tryjobs {

  // Requirement is what has to happen to verify a given Run.
  Requirement requirement = 1;

  // Tryjobs tracks tryjobs of a Run.
  //
  // It may contain Tryjobs which are no longer required.
  // It does contain all Tryjobs which weren't reused even if no longer required.
  //
  // TODO(crbug/1227523): delete ExternalID from sorted order.
  // Sorted by ID, then by ExternalID (for migration from CQD purpose).
  repeated Tryjob tryjobs = 2;

  // The timestamp of the CQDaemon report last incorporated into `tryjobs`.
  //
  // TODO(crbug/1227523): delete this field.
  google.protobuf.Timestamp cqd_update_time = 3;

  // TODO(crbug/1227363): add quota.


  // Requirement is what has to happen to verify a given Run,
  // computed based on LUCI project config and specifics of the Run.
  message Requirement {
    // TODO(crbug/1227363): define.
  }
}

// Tryjob represents a Run's view of a tryjob.
message Tryjob {
  cv.internal.tryjob.Definition definition = 1;

  // ID is a CV internal Tryjob ID, correponding to a Datastore entity.
  //
  // During migration from CQDaemon, the ID may be not set but then ExternalID
  // is set.
  // TODO(crbug/1227523): make this field required.
  int64 id = 2;

  // EVersion of the Tryjob entity last observed by this Run.
  int64 eversion = 3;

  // ExternalID is the external job ID.
  //
  // It's kept here for ease of URL generation and to ease migration from
  // CQDaemon.
  // TODO(crbug/1227523): update comment above after CQDaemon migration.
  string external_id = 4;

  // Status of the Tryjob.
  cv.internal.tryjob.Status status = 5;

  // Reused is true, if this tryjob wasn't triggered by CV for this Run.
  //
  // In other words, either:
  //  * tryjob was triggered by CV for a previous Run
  //  * tryjob was triggered by non-CV.
  bool reused = 6;

  // Result of the tryjob.
  cv.internal.tryjob.Result result = 7;

  // If true, this Tryjob was computed based on CQDaemon's input.
  //
  // TODO(crbug/1227523): delete after CQDaemon migration.
  bool cqd_derived = 8;
}