api/v3/api_proto/hotlists.proto

// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

syntax = "proto3";

package monorail.v3;

option go_package = "infra/monorailv2/api/v3/api_proto";

import "api/v3/api_proto/feature_objects.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/empty.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";

// ***ONLY CALL rpcs WITH `status: {ALPHA|STABLE}`***
// rpcs without `status` are not ready.

// Hotlists service includes all methods needed for managing Hotlists.
service Hotlists {
  // status: NOT READY
  // Creates a new hotlist.
  //
  // Raises:
  //   NOT_FOUND if some given hotlist editors do not exist.
  //   ALREADY_EXISTS if a hotlist with the same name owned by the user
  //   already exists.
  //   INVALID_ARGUMENT if a `hotlist.owner` is given.
  rpc CreateHotlist (CreateHotlistRequest) returns (Hotlist) {}

  // status: NOT READY
  // Returns the requested Hotlist.
  //
  // Raises:
  //   NOT_FOUND if the requested hotlist is not found.
  //   PERMISSION_DENIED if the requester is not allowed to view the hotlist.
  //   INVALID_ARGUMENT if the given resource name is not valid.
  rpc GetHotlist (GetHotlistRequest) returns (Hotlist) {}

  // status: NOT READY
  // Updates a hotlist.
  //
  // Raises:
  //   NOT_FOUND if the hotlist is not found.
  //   PERMISSION_DENIED if the requester is not allowed to update the hotlist.
  //   INVALID_ARGUMENT if required fields are missing.
  rpc UpdateHotlist (UpdateHotlistRequest) returns (Hotlist) {}

  // status: NOT READY
  // Deletes a hotlist.
  //
  // Raises:
  //   NOT_FOUND if the hotlist is not found.
  //   PERMISSION_DENIED if the requester is not allowed to delete the hotlist.
  rpc DeleteHotlist (GetHotlistRequest) returns (google.protobuf.Empty) {}

  // status: NOT READY
  // Returns a list of all HotlistItems in the hotlist.
  //
  // Raises:
  //   NOT_FOUND if the parent hotlist is not found.
  //   PERMISSION_DENIED if the requester is not allowed to view the hotlist.
  //   INVALID_ARGUMENT if the page_token or given hotlist resource name is not
  //   valid.
  rpc ListHotlistItems (ListHotlistItemsRequest) returns (ListHotlistItemsResponse) {}

  // status: NOT READY
  // Reranks a hotlist's items.
  //
  // Raises:
  //   NOT_FOUND if the hotlist or issues to rerank are not found.
  //   PERMISSION_DENIED if the requester is not allowed to rerank the hotlist
  //   or view issues they're trying to rerank.
  //   INVALID_ARGUMENT if the `target_position` is invalid or `hotlist_items`
  //   is empty or contains items not in the Hotlist.
  rpc RerankHotlistItems (RerankHotlistItemsRequest) returns (google.protobuf.Empty) {}

  // status: NOT READY
  // Adds new items associated with given issues to a hotlist.
  //
  // Raises:
  //   NOT_FOUND if the parent hotlist or issues are not found.
  //   PERMISSION_DENIED if the requester is not allowed to edit the hotlist or
  //   view issues they are trying to add.
  //   INVALID_ARGUMENT if the `target_position` is invalid or `hotlist_items`
  //   is empty or contains items not in the Hotlist.
  rpc AddHotlistItems (AddHotlistItemsRequest) returns (google.protobuf.Empty) {}

  // status: NOT READY
  // Removes items associated with given issues from a hotlist.
  //
  // Raises:
  //   NOT_FOUND if the parent hotlist or issues are not found.
  //   PERMISSION_DENIED if the requester is not allowed to edit the hotlist or
  //   view issues they are trying to remove.
  //   INVALID_ARGUMENT if the `target_position` is invalid or `hotlist_items`
  //   is empty or contains items not in the Hotlist.
  rpc RemoveHotlistItems (RemoveHotlistItemsRequest) returns (google.protobuf.Empty) {}

  // status: NOT READY
  // Removes editors assigned to a hotlist.
  //
  // Raises:
  //   NOT_FOUND if the hotlist is not found.
  //   PERMISSION_DENIED if the requester is not allowed to remove all specified
  //   editors from the hotlist.
  //   INVALID_ARGUMENT if any specified editors are not in the hotlist.
  rpc RemoveHotlistEditors (RemoveHotlistEditorsRequest) returns (google.protobuf.Empty) {}

  // status: NOT READY
  // Gathers all viewable hotlists that a user is a member of.
  //
  // Raises:
  //   NOT_FOUND if the user is not found.
  //   INVALID_ARGUMENT if the `user` is invalid.
  rpc GatherHotlistsForUser (GatherHotlistsForUserRequest) returns (GatherHotlistsForUserResponse) {}
}


// Request message for CreateHotlist method.
// Next available tag: 2
message CreateHotlistRequest {
  // The hotlist to create.
  // `hotlist.owner` must be empty. The owner of the new hotlist will be
  // set to the requester.
  Hotlist hotlist = 1 [ (google.api.field_behavior) = REQUIRED ];
}


// Request message for GetHotlist method.
// Next available tag: 2
message GetHotlistRequest {
  // The name of the hotlist to retrieve.
  string name = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/Hotlist"}];
}


// Request message for UpdateHotlist method.
// Next available tag: 2
message UpdateHotlistRequest {
  // The hotlist's `name` field is used to identify the hotlist to be updated.
  Hotlist hotlist = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
  // The list of fields to be updated.
  google.protobuf.FieldMask update_mask = 2 [ (google.api.field_behavior) = REQUIRED ];
}


// Request message for ListHotlistItems method.
// Next available tag: 5
message ListHotlistItemsRequest {
  // The parent hotlist, which owns this collection of items.
  string parent = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
  // The maximum number of items to return. The service may return fewer than
  // this value.
  // If unspecified, at most 1000 items will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 2;
  // The string of comma separated field names used to order the items.
  // Adding '-' before a field, reverses the sort order.
  // E.g. 'stars,-status' sorts the items by number of stars low to high, then
  // status high to low.
  // If unspecified, items will be ordered by their rank in the parent.
  string order_by = 3;
  // A page token, received from a previous `ListHotlistItems` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListHotlistItems` must
  // match the call that provided the page token.
  string page_token = 4;
}


// Response to ListHotlistItems call.
// Next available tag: 3
message ListHotlistItemsResponse {
  // The items from the specified hotlist.
  repeated HotlistItem items = 1;
  // A token, which can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  string next_page_token = 2;
}


// The request used to rerank a Hotlist.
// Next available tag: 4
message RerankHotlistItemsRequest {
  // Resource name of the Hotlist to rerank.
  string name = 1 [
      (google.api.resource_reference) = {type: "api.crbug.com/Hotlist"},
      (google.api.field_behavior) = REQUIRED ];
  // HotlistItems to be moved. The order of `hotlist_items` will
  // determine the order of these items after they have been moved.
  // E.g. With items [a, b, c, d, e], moving [d, c] to `target_position` 3, will
  // result in items [a, b, e, d, c].
  repeated string hotlist_items = 2 [
      (google.api.resource_reference) = {type: "api.crbug.com/HotlistItem"},
      (google.api.field_behavior) = REQUIRED ];
  // Target starting position of the moved items.
  // `target_position` must be between 0 and (# hotlist items - # items being moved).
  uint32 target_position = 3 [ (google.api.field_behavior) = REQUIRED ];
}


// Request message for an AddHotlistItems call.
// Next available tag: 4
message AddHotlistItemsRequest {
  // Resource name of the Hotlist to add new items to.
  string parent = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
  // Resource names of Issues to associate with new HotlistItems added to `parent`.
  repeated string issues = 2 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/Issue"} ];
  // Target starting position of the new items.
  // `target_position` must be between [0 and # of items that currently exist in
  // `parent`]. The request will fail if a specified `target_position` is outside
  // of this range.
  // New HotlistItems added to a non-last position of the hotlist will
  // cause ranks of existing HotlistItems below `target_position` to be adjusted.
  // If no `target_position` is given, new items will be added to the end of
  // `parent`.
  uint32 target_position = 3;
}


// Request message for a RemoveHotlistItems call.
// Next available tag: 3
message RemoveHotlistItemsRequest {
  // Resource name of the Hotlist to remove items from.
  string parent = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
  // Resource names of Issues associated with HotlistItems that should be removed.
  repeated string issues = 2 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/Issue"} ];
}


// Request message for a RemoveHotlistEditors call.
// Next available tag: 3
message RemoveHotlistEditorsRequest {
  // Resource name of the Hotlist to remove editors from.
  string name = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/Hotlist"} ];
  // Resource names of Users associated with the hotlist that should be removed.
  repeated string editors = 2 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/User"} ];
}


// Request message for a GatherHotlistsForUser call.
// Next available tag: 2
message GatherHotlistsForUserRequest {
  // Resource name of the user whose hotlists we want to fetch.
  string user = 1 [ (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {type: "api.crbug.com/User"} ];
}


// Response message for a GatherHotlistsForUser call.
// Next available tag: 2
message GatherHotlistsForUserResponse {
  repeated Hotlist hotlists = 1;
}