syntax = "proto3";
package autoroll.rpc;
option go_package = "go.skia.org/infra/autoroll/go/rpc";

import "google/protobuf/timestamp.proto";

// AutoRollService provides interactions with the AutoRoll frontend.
service AutoRollService {
  // GetRollers retrieves AutoRollMiniStatuses for all known rollers.
  rpc GetRollers(GetRollersRequest) returns (GetRollersResponse);
  // GetMiniStatus retrieves the AutoRollMiniStatus for one roller.
  rpc GetMiniStatus(GetMiniStatusRequest) returns (GetMiniStatusResponse);
  // GetStatus retrieves the AutoRollStatus for one roller.
  rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);
  // SetMode sets the mode for a roller.
  rpc SetMode(SetModeRequest) returns (SetModeResponse);
  // SetStrategy sets the strategy for a roller.
  rpc SetStrategy(SetStrategyRequest) returns (SetStrategyResponse);
  // CreateManualRoll initiates the creation of a manual roll.
  rpc CreateManualRoll(CreateManualRollRequest) returns (CreateManualRollResponse);
  // Unthrottle clears any throttling of the roller, allowing it to roll again.
  rpc Unthrottle(UnthrottleRequest) returns (UnthrottleResponse);
}

// Mode describes the valid operating modes of an autoroller.
// These must be kept in sync with autoroll/go/modes/modes.go.
enum Mode {
  // RUNNING is the typical operating mode of the autoroller. It will upload and
  // land CLs as new revisions appear in the Child.
  RUNNING = 0;
  // STOPPED prevents the autoroller from uploading any CLs. The roller will
  // continue to update any local checkouts to prevent them from getting too far
  // out of date, and any requested manual rolls will be fulfilled.
  STOPPED = 1;
  // DRY_RUN is similar to RUNNING but does not land the roll CLs after the
  // commit queue finishes. Instead, the active roll is left open until new
  // revisions appear in the child, at which point the roll is closed and a new
  // one is uploaded.
  DRY_RUN = 2;
  // OFFLINE is similar to STOPPED, but the roller does not update its checkouts
  // and requests for manual rolls are ignored.
  OFFLINE = 3;
}

// Strategy describes the valid strategies for choosing the next revision to
// roll. These must be kept in sync with autoroll/go/strategy/strategies.go.
enum Strategy {
  // BATCH indicates that all not-yet-rolled revisions should be rolled in a
  // single CL.
  BATCH = 0;
  // N_BATCH is similar to BATCH but puts a limit on the number of revisions in
  // a single CL.
  N_BATCH = 1;
  // SINGLE indicates that a single revision is rolled in each CL.
  SINGLE = 2;
}

// AutoRollMiniStatus contains a subset of the information of AutoRollStatus.
message AutoRollMiniStatus {
  // roller_id is the unique ID for this roller.
  string roller_id = 1;
  // child_name is the display name of the child.
  string child_name = 2;
  // parent_name is the display name of the parent.
  string parent_name = 3;
  // mode is the currently-set operating mode of the roller.
  Mode mode = 4;
  // current_roll_rev is the ID of the child revision which is being rolled in
  // the active roll CL.
  string current_roll_rev = 5;
  // last_roll_rev is the ID of the child revision which is currently pinned by
  // the parent.
  string last_roll_rev = 6;
  // num_failed is the number of consecutive roll failures.
  int32 num_failed = 7;
  // num_behind is the number of not-yet-rolled revisions.
  int32 num_behind = 8;
}

message TryJob {
  // Result describes the possible results for a TryJob.
  // These must be kept in sync with go/autoroll/autoroll.go.
  enum Result {
    // UNKNOWN indicates that the result of the TryJob is unknown, ie. it has
    // not yet finished.
    UNKNOWN = 0;
    // SUCCESS indicates that that TryJob completed successfully.
    SUCCESS = 1;
    // FAILURE indicates that that TryJob failed.
    FAILURE = 2;
    // CANCELED indicates that that TryJob was canceled.
    CANCELED = 3;
  }

  // Status describes the lifecycle states of a TryJob.
  // These must be kept in sync with go/autoroll/autoroll.go.
  enum Status {
    // SCHEDULED indicates that the TryJob has been scheduled but has not yet
    // started.
    SCHEDULED = 0;
    // STARTED indicates that the TryJob is currently running.
    STARTED = 1;
    // COMPLETED indicates that the TryJob is finishes.
    COMPLETED = 2;
  }

  // name of the TryJob.
  string name = 1;
  // status of the TryJob.
  Status status = 2;
  // result of the TryJob.
  Result result = 3;
  // url where more details can be found about the TryJob.
  string url = 4;
  // category of the TryJob, eg. "cq".
  string category = 5;
}

// AutoRoll CL describes a CL uploaded by the autoroller.
message AutoRollCL {
  // Result describes the possible results for an AutoRollCL.
  enum Result {
    // IN_PROGRESS indicates that the commit queue is still running for this
    // AutoRollCL.
    IN_PROGRESS = 0;
    // SUCCESS indicates that this AutoRollCL landed successfully.
    SUCCESS = 1;
    // FAILURE indicates that the commit queue failed for  this AutoRollCL.
    FAILURE = 2;
    // DRY_RUN_IN_PROGRESS indicates that the commit queue dry run is still
    // running for this AutoRollCL.
    DRY_RUN_IN_PROGRESS = 3;
    // DRY_RUN_SUCCESS indicates that the commit queue dry run succeeded for
    // this AutoRollCL.
    DRY_RUN_SUCCESS = 4;
    // DRY_RUN_FAILURE indicates that the commit queue dry run failed for this
    // AutoRollCL.
    DRY_RUN_FAILURE = 5;
  }

  // id is the unique identifier for the CL.
  string id = 1;
  // result of the AutoRollCL.
  Result result = 2;
  // subject line of the commit message of the AutoRollCL.
  string subject = 3;
  // rolling_to is the ID of the revision being rolled.
  string rolling_to = 4;
  // rolling_from is the ID of the currently-pinned revision.
  string rolling_from = 5;
  // created is the timestamp at which the AutoRollCL was created.
  google.protobuf.Timestamp created = 6;
  // created is the timestamp at which the AutoRollCL was last modified.
  google.protobuf.Timestamp modified = 7;
  // try_jobs contains results of any try jobs for the AutoRollCL.
  repeated TryJob try_jobs = 8;
}

// Revision describes a single revision in a given Child. This may be a Git
// commit, CIPD package instance, a file uploaded to GCS, etc.
message Revision {
  // id is the unique identifier for the Revision.
  string id = 1;
  // display is a human-friendly display name for the Revision.
  string display = 2;
  // description is a longer description of the Revision.
  string description = 3;
  // time is the timestamp at which the Revision was created.
  google.protobuf.Timestamp time = 4;
  // url where more details can be found about the Revision.
  string url = 5;
}

// AutoRollConfig describes the configuration for a roller.
message AutoRollConfig {
  // child_bug_link is a link to file a bug for the child project.
  string child_bug_link = 5;
  // parent_bug_link is a link to file a bug for the parent project.
  string parent_bug_link = 6;
  // parent_waterfall is the URL of the CI display for the parent repo.
  string parent_waterfall = 1;
  // roller_id is the unique identifier for the roller.
  string roller_id = 2;
  // supports_manual_rolls indicates whether this autoroller supports manually-
  // triggered rolls.
  bool supports_manual_rolls = 3;
  // time_window describes the limitations, if any, on when the autoroller is
  // allowed to upload roll CLs.
  string time_window = 4;
}

// ModeChange describes one instance of an autoroller's mode being changed.
message ModeChange {
  // roller_id is the unique identifier for the autoroller.
  string roller_id = 1;
  // mode is the operating mode of the autoroller which was set in this
  // ModeChange.
  Mode mode = 2;
  // user is the email address of the user who created this ModeChange.
  string user = 3;
  // time is the timestamp at which the ModeChange was created.
  google.protobuf.Timestamp time = 4;
  // message is a user-created message which describes the reason for changing
  // the mode.
  string message = 5;
}

// StrategyChange describes one instance of an autoroller's mode being changed.
message StrategyChange {
  // roller_id is the unique identifier for the autoroller.
  string roller_id = 1;
  // strategy is the strategy for choosing the next revision to roll which was
  // set in this StrategyChange.
  Strategy strategy = 2;
  // user is the email address of the user who created this StrategyChange.
  string user = 3;
  // time is the timestamp at which the StrategyChange was created.
  google.protobuf.Timestamp time = 4;
  // message is a user-created message which describes the reason for changing
  // the strategy.
  string message = 5;
}

// ManualRoll describes a manually-triggered roll and its results.
message ManualRoll {
  // Result describes the possible results for a manual roll.
  // These must be kept in sync with autoroll/go/manual/db.go.
  enum Result {
    // UNKNOWN indicates that the result of the ManualRoll is unknown, ie. it
    // has not yet finished.
    UNKNOWN = 0;
    // FAILURE indicates that the ManualRoll has failed.
    FAILURE = 1;
    // SUCCESS indicates that the ManualRoll landed successfully.
    SUCCESS = 2;
  }

  // Status describes the lifecycle states of a manual roll.
  // These must be kept in sync with autoroll/go/manual/db.go.
  enum Status {
    // PENDING indicates that the ManualRoll has been requested but no CL has
    // been uploaded.
    PENDING = 0;
    // STARTED indicates that a CL has been uploaded for this ManualRoll.
    STARTED = 1;
    // COMPLETED indicates that the ManualRoll has finished and either landed
    // successfully or failed.
    COMPLETED = 2;
  }

  // id is the unique identifier for this ManualRoll.
  string id = 1;
  // roller_id is the unique identifier for the autoroller on which this
  // ManualRoll was requested.
  string roller_id = 2;
  // revision is the ID of the revision to which this ManualRoll will roll.
  string revision = 3;
  // requester is the email address of the person who requested the ManualRoll.
  string requester = 4;
  // result of the ManualRoll.
  Result result = 5;
  // status of the ManualRoll.
  Status status = 6;
  // timestamp at which the ManualRoll was created.
  google.protobuf.Timestamp timestamp = 7;
  // url of the ManualRoll, if a roll has been uploaded.
  string url = 8;
  // dry_run indicates whether the ManualRoll should be performed as a dry run,
  // so that the commit queue runs but the CL is not landed.
  bool dry_run = 9;
  // no_email specifies that the requester and reviewers should not receive
  // email related to this ManualRoll.
  bool no_email = 10;
  // no_resolve_revision specifies that the autoroller should not attempt to
  // find the requested revision ID in the Child but should simply use it as
  // provided.
  bool no_resolve_revision = 11;
}

// AutoRollStatus describes the overall status of an autoroller.
message AutoRollStatus {
  // mini_status contains a subset of status information for the autoroller.
  AutoRollMiniStatus mini_status = 1;
  // status is the current status of the autoroller, as provided by the state
  // machine.
  string status = 2;
  // config provides configuration information for the autoroller.
  AutoRollConfig config = 3;
  // full_history_url is the URL where the autoroller's history may be viewed.
  string full_history_url = 4;
  // issue_url_base provides a base URL which can be used to construct URLs for
  // individual AutoRollCLs.
  string issue_url_base = 5;
  // mode is the current operating mode of the autoroller.
  ModeChange mode = 6;
  // strategy for choosing the next revision to roll.
  StrategyChange strategy = 7;
  // not_rolled_revisions are the revisions of the Child which have not yet been
  // rolled.
  repeated Revision not_rolled_revisions = 8;
  // current_roll is the active roll CL, if any.
  AutoRollCL current_roll = 9;
  // last_roll is the previous roll CL.
  AutoRollCL last_roll = 10;
  // recent_rolls contains a list of recent roll CLs.
  repeated AutoRollCL recent_rolls = 11;
  // manual_rolls contains a list of recent ManualRolls.
  repeated ManualRoll manual_rolls = 12;
  // error contains a detailed message if the autoroller is in an error state.
  string error = 13;
  // throttled_until is the timestamp at which the autoroller will no longer be
  // throttled, if the autoroller is currently throttled.
  google.protobuf.Timestamp throttled_until = 14;
}

// GetRollersRequest is a request to GetRollers.
message GetRollersRequest {}

// GetRollersResponse is a response returned by GetRollers.
message GetRollersResponse {
  // rollers contains status information for all known autorollers.
  repeated AutoRollMiniStatus rollers = 1;
}

// GetMiniStatusRequest is a request to GetMiniStatus.
message GetMiniStatusRequest {
  // roller_id is the unique identifier of the autoroller whose MiniStatus is to
  // be retrieved.
  string roller_id = 1;
}

// GetMiniStatusResponse is a response returned by GetMiniStatus.
message GetMiniStatusResponse {
  // status is a subset of status information for the autoroller in question.
  AutoRollMiniStatus status = 1;
}

// GetStatusRequest is a request to GetStatus.
message GetStatusRequest {
  // roller_id is the unique identifier of the autoroller whose Status is to be
  // retrieved.
  string roller_id = 1;
}

// GetStatusResponse is a response returned by GetStatus.
message GetStatusResponse {
  // status information about the autoroller in question.
  AutoRollStatus status = 1;
}

// SetModeRequest is a request to SetMode.
message SetModeRequest {
  // roller_id is the unique identifier of the autoroller whose mode is to be
  // changed.
  string roller_id = 1;
  // mode is the desired mode to set for the given autoroller.
  Mode mode = 2;
  // message describes the reason for changing the mode.
  string message = 4;
}

// SetModeResponse is a response returned by SetMode.
message SetModeResponse {
  // status is the updated status of the autoroller after changing its mode.
  AutoRollStatus status = 1;
}

// SetStrategyRequest is a request to SetStrategy.
message SetStrategyRequest {
  // roller_id is the unique identifier of the autoroller whose strategy is to
  // be changed.
  string roller_id = 1;
  // strategy is the desired strategy to set for the given autoroller.
  Strategy strategy = 2;
  // message describes the reason for changing the strategy.
  string message = 4;
}

// SetStrategyResponse is a response returned by SetStrategy.
message SetStrategyResponse {
  // status is the updated status of the autoroller after changing its strategy.
  AutoRollStatus status = 1;
}

// CreateManualRollRequest is a request to CreateManualRoll.
message CreateManualRollRequest {
  // roller_id is the unique identifier of the autoroller which should create
  // the manual roll.
  string roller_id = 1;
  // revision is the ID of the revision to be rolled.
  string revision = 2;
  // dry_run flag controls whether the roll is a dry-run.
  bool dry_run = 3;
}

// CreateManualRollResponse is a response returned by CreateManualRoll.
message CreateManualRollResponse {
  // roll is the manual roll which was created.
  ManualRoll roll = 1;
}

// UnthrottleRequest is a request to Unthrottle.
message UnthrottleRequest {
  // roller_id is the unique identifier of the autoroller which should be
  // unthrottled.
  string roller_id = 1;
}

// UnthrottleResponse is a response returned by Unthrottle.
message UnthrottleResponse {}