cv/api/migration/migration.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 migration;

option go_package = "go.chromium.org/luci/cv/api/migration;migrationpb";


import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";

import "go.chromium.org/luci/common/proto/gerrit/gerrit.proto";
import "go.chromium.org/luci/cv/api/bigquery/v1/attempt.proto";


// Migration service is for INTERNAL LUCI CV USE ONLY.
// CAN AND WILL CHANGE WITHOUT NOTICE IN BACKWARDS INCOMPATIBLE WAY.
//
// This is temporary API to be called by CQDaemon, CV's predecessor, during the
// migration from CQDaemon to CV.
service Migration {

  // ReportRuns notifies CV of the Runs CQDaemon is currently working with.
  //
  // Used to determine whether CV's view of the world matches that of CQDaemon.
  // Initially, this is just FYI for CV.
  rpc ReportRuns(ReportRunsRequest) returns (google.protobuf.Empty);

  // ReportFinishedRun notifies CV of the Run CQDaemon has just finalized.
  //
  // The Run may not contain CV's id, but CV can figure out the the ID using
  // Run.Attempt.Key.
  //
  // Called by CQDaemon when CQDaemon is in charge of run management.
  rpc ReportFinishedRun(ReportFinishedRunRequest) returns (google.protobuf.Empty);

  // ReportVerifiedRun notifies CV of the Run CQDaemon has just finished
  // verifying.
  //
  // The Run may not contain CV's id, but CV can figure out the the ID using
  // Run.Attempt.Key.
  //
  // Called by CQDaemon when CV is in charge of run management.
  rpc ReportVerifiedRun(ReportVerifiedRunRequest) returns (google.protobuf.Empty);

  // FetchRunStatus provides to CQDaemon info about a completed Run in order to
  // send to CQ Status app.
  //
  // The Run may not contain CV's id, but CV can figure out the the ID using
  // Run.Attempt.Key.
  //
  // Called by CQDaemon when CV is in charge of run management.
  rpc FetchRunStatus(FetchRunStatusRequest) returns (FetchRunStatusResponse);

  // PostGerritMessage posts a unique per run message to Gerrit.
  //
  // Best effort, since Gerrit doesn't provide for idempotent or conditional
  // (etag like) updates.
  //
  // Use-cases:
  //  * CQDaemon linter posting a warning/error.
  //  * GerritCQAbility verifier posting error on each of Run's CL before
  //    failing entire attempt.
  //
  // Error handling:
  //  * If presumably transient Gerrit error, fails with Internal error (for
  //    simplicity). CQDaemon will have to retry.
  //  * If Gerrit error is 403, 404 or 412 (Precondition error), responds with
  //    corresponding gRPC code.
  rpc PostGerritMessage(PostGerritMessageRequest) returns (PostGerritMessageResponse);

  // FetchActiveRuns returns all currently RUNNING runs in CV for the given
  // project.
  rpc FetchActiveRuns(FetchActiveRunsRequest) returns (FetchActiveRunsResponse);

  // FetchExcludedCLs returns all CLs referenced by ReportVerifiedRuns but with
  // not yet ended Runs.
  //
  // CQDaemon uses this to avoid processing these CLs when computing its own
  // list of candidates.
  //
  // Called by CQDaemon when CQDaemon is in charge of run management.
  rpc FetchExcludedCLs(FetchExcludedCLsRequest) returns (FetchExcludedCLsResponse);

  // ReportUsedNetrc notifies CV of the legacy .netrc credentials used by
  // CQDaemon.
  rpc ReportUsedNetrc(ReportUsedNetrcRequest) returns (google.protobuf.Empty);

}

message ReportRunsRequest {
  repeated ReportedRun runs = 1;
}

message ReportFinishedRunRequest {
  ReportedRun run = 1;
}

message ReportVerifiedRunRequest {
  ReportedRun run = 1;

  // Action that CV SHOULD do on a Run.
  //
  // Should instead of must because CV may be already finalizing the Run.
  //
  // In pure CQDaemon, the action would have been done by CQDaemon itself.
  enum Action {
    ACTION_UNSPECIFIED = 0;
    ACTION_SUBMIT = 1; // requires a full run
    ACTION_DRY_RUN_OK = 2; // requires a dry run
    ACTION_FAIL = 3; // final_message must be set
  }
  Action action = 11;
  // Final message to post to Gerrit in case of ACTION_FAIL.
  string final_message = 12;
}

// ReportedRun as reported by the CQDaemon to CV.
message ReportedRun {
  // CV's run ID if known.
  string id = 2;
  bigquery.Attempt attempt = 1;
}

message PostGerritMessageRequest {
  // CV's run ID. May be not set iff CQDaemon does this before it takes Runs
  // from CV.
  string run_id = 1;
  // LUCI Project. If run_id is specified, this is redundant.
  string project = 2;
  // CQD native Run identifier.
  string attempt_key = 3;

  // Gerrit host.
  string host = 11;
  int64 change = 12;
  string revision = 15;
  // String comment to post.
  string comment = 13;
  // If true, send email to:
  //   * OWNER_REVIEWERS if full run
  //   * OWNER+all CQ voters if dry run
  bool send_email = 14;
}

message PostGerritMessageResponse {
}

message ReportUsedNetrcRequest {
  string gerrit_host = 1;
  string access_token = 2;
}

message FetchActiveRunsRequest {
  string luci_project = 1;
}

message FetchActiveRunsResponse {
  repeated ActiveRun active_runs = 2;
}

// ActiveRun.
message ActiveRun {
  // CV Run ID.
  string id = 1;
  repeated RunCL cls = 2;
}

message RunCL {
  // CV's CLID. Used to identify Deps.
  int64 id = 1;
  bigquery.GerritChange gc = 2;

  // The following are copy-pasted from CV's snapshot.
  // Info is guaranteed to have current revision with the same patchset as
  // as specified in bigquery.GerritChange.
  gerrit.ChangeInfo info = 3;
  repeated string files = 4;

  message Trigger {
    google.protobuf.Timestamp time = 1;
    // Gerrit account ID.
    int64 account_id = 3;
    // User email, if known.
    string email = 4;
  }
  Trigger trigger = 5;

  message Dep {
    // CV's CLID. Guaranteed to match one of the RunCL in the same Run.
    int64 id = 1;
    // True means Dep is the immediate git parent and must be submitted first.
    bool hard = 2;
  }
  repeated Dep deps = 6;
}

message FetchRunStatusRequest {
  string luci_project = 1;
  string cv_id = 2;
  string attempt_key = 3;
}

message FetchRunStatusResponse {
  // If event is not "", CQDaemon will call async_push's
  // `send_patch_event(..., event, extra)`.
  string event = 1;
  string extra = 2;
}

message FetchExcludedCLsRequest {
  string luci_project = 1;
}
message FetchExcludedCLsResponse {
  // Each CL has only host and change number set.
  repeated bigquery.GerritChange cls = 1;
}