cv/internal/run/eventpb/events.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.run.eventpb;

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

import "google/protobuf/timestamp.proto";

// Event is a container for all kinds of events a Run Manager can receive.
message Event {
  oneof event {
    // On Start event, Run Manager will start the Run.
    //
    // The Run entity must already exist.
    Start start = 1;
    // On Cancel event, Run Manager will cancel the Run.
    Cancel cancel = 2;
    // On Poke event, Run Manager will check the state of the Run and perform
    // any action if necessary.
    //
    // Sent periodically by Project Manager.
    Poke poke = 3;
    // On NewConfig event, Run Manager will update config the Run for the
    // given RunID.
    //
    // Sent by Project Manager, which guarantees these events are sent in order
    // of config updates. See also its `eversion` field.
    NewConfig new_config = 4;
    // On CLUpdated event, Run Manager will decide whether to cancel the Run
    // based on the current CL state.
    //
    // Sent by Gerrit Updater if Run is inside the `IncompleteRuns` list of
    // a CL.
    CLUpdated cl_updated = 5;
    // On ReadyForSubmission event, Run Manager will try to submit CLs in
    // this Run.
    ReadyForSubmission ready_for_submission = 6;
    // On CLSubmitted event, Run Manager will mark this CL as submitted.
    CLSubmitted cl_submitted = 7;
    // On SubmissionCompleted event, Run Manager will look at the submission
    // result and decide whether to retry this submission or succeed or fail
    // the Run.
    SubmissionCompleted submission_completed = 8;

    // TODO(yiwzhang): Define following events that Run Manager may receive:
    //  * TryjobUpdated

    // On CQDVerificationCompleted event, Run Manager will finalize the Run.
    //
    // This event is sent by migration api when CQDaemon reports a verified
    // Run back to CV.
    //
    // TODO(crbug/1141880): Remove this event after migration.
    CQDVerificationCompleted cqd_verification_completed = 30;
  }

  // Instructs Run Manager that this event can only be processed after
  // this timestamp.
  google.protobuf.Timestamp process_after = 20;
}

message Start {
}

message Cancel {
}

message Poke {
}

message NewConfig {
  // Hash identifying project config version to update to.
  string hash = 1;
  // Eversion of the project config version identify by hash.
  //
  // Provided for identifying the latest NewConfig message
  // if there are more than one outstanding NewConfig event.
  int64 eversion = 2;
}

message CLUpdated {
  // Internal ID of a CL that was updated.
  int64 clid = 1;
  // EVersion of the updated CL entity.
  int64 eVersion = 2;
}

message ReadyForSubmission {
}

message CLSubmitted {
  // Internal ID of a CL that was submitted successfully.
  int64 clid = 1;
}

message SubmissionCompleted {
  // Result of this submission.
  SubmissionResult result = 1;

  message CLSubmissionFailure {
    int64 clid = 1; // Required
    string message = 2; // Required
  }

  oneof failure_reason {
    // This Run submission fails because of an individual CL submission
    // failure.
    CLSubmissionFailure cl_failure = 2;
    bool timeout = 3;
  }
}

enum SubmissionResult {
  SUBMISSION_RESULT_UNSPECIFIED = 0;
  // All CLs have been submitted successfully.
  SUCCEEDED = 1;
  // Encountered transient failure.
  //
  // RM should retry if quota allows.
  FAILED_TRANSIENT = 2;
  // Encountered precondition failure which is transient in nature.
  //
  // For example, tree closure and submit queue is throttling.
  FAILED_PRECONDITION = 3;
  // Encountered permanent failure.
  //
  // For example, lack of submit permission or experienced merge conflict.
  FAILED_PERMANENT = 4;
}

message CQDVerificationCompleted {
}