api/v3/api_proto/issues.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 "google/protobuf/field_mask.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "api/v3/api_proto/issue_objects.proto";

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

// Issues service includes all methods needed for managing Issues.
service Issues {
  // status: ALPHA
  // Returns the requested Issue.
  //
  // Raises:
  //   INVALID_ARGUMENT if `name` is formatted incorrectly.
  //   NOT_FOUND if the issue does not exist.
  //   PERMISSION_DENIED if the requester is not allowed to view the issue.
  rpc GetIssue (GetIssueRequest) returns (Issue) {}

  // status: ALPHA
  // Returns the requested Issues.
  //
  // Raises:
  //   INVALID_ARGUMENT if `names` is formatted incorrectly. Or if a parent
  //       collection in `names` does not match the value in `parent`.
  //   NOT_FOUND if any of the given issues do not exist.
  //   PERMISSION_DENIED if the requester does not have permission to view one
  //       (or more) of the given issues.
  rpc BatchGetIssues(BatchGetIssuesRequest) returns (BatchGetIssuesResponse) {}

  // status: ALPHA
  // Searches over issues within the specified projects.
  //
  // Raises:
  //   INVALID_ARGUMENT if project names or search query are invalid.
  rpc SearchIssues (SearchIssuesRequest) returns (SearchIssuesResponse) {}

  // status: ALPHA
  // Lists comments for an issue.
  //
  // Raises:
  //   INVALID_ARGUMENT if `parent` is formatted incorrectly or `page_size` < 0.
  //   NOT_FOUND if `parent` does not exist.
  //   PERMISSION_DENIED if the requester is not allowed to view `parent`.
  rpc ListComments (ListCommentsRequest) returns (ListCommentsResponse) {}

  // status: ALPHA
  // Modifies Issues and creates a new Comment for each.
  // Issues with NOOP changes and no comment_content will not be updated
  // and will not be included in the response.
  // We do not offer a standard UpdateIssue because every issue change
  // must result in the side-effect of creating a new Comment, and may result in
  // the side effect of sending a notification. We also want to allow for any
  // combination of issue changes to be made at once in a monolithic method.
  //
  // Raises:
  //   INVALID_ARGUMENT required fields are missing or fields are formatted
  //     incorrectly.
  //   NOT_FOUND if any specified issues are not found.
  //   PERMISSION_DENIED if the requester is not allowed to make the
  //     requested change.
  rpc ModifyIssues (ModifyIssuesRequest) returns (ModifyIssuesResponse) {}

  // status: ALPHA
  // Modifies ApprovalValues and creates a new Comment for each delta.
  // We do not offer a standard UpdateApprovalValue because changes result
  // in creating Comments on the parent Issue, and may have the side effect of
  // sending notifications. We also want to allow for any combination of
  // approval changes to be made at once in a monolithic method.
  // To modify owner add 'owner' to update_mask, though 'owner.user' works too.
  //
  // Raises:
  //   INVALID_ARGUMENT required fields are missing or fields are formatted
  //     incorrectly.
  //   NOT_FOUND if any specified ApprovalValues are not found.
  //   PERMISSION_DENIED if the requester is not allowed to make any of the
  //     requested changes.
  rpc ModifyIssueApprovalValues (ModifyIssueApprovalValuesRequest) returns
      (ModifyIssueApprovalValuesResponse) {}

  // status: ALPHA
  // Lists approval values for an issue.
  //
  // Raises:
  //   INVALID_ARGUMENT if request `parent` is formatted incorrectly.
  //   NOT_FOUND if the parent issue does not exist.
  //   PERMISSION_DENIED if the requester is not allowed to view parent issue.
  rpc ListApprovalValues (ListApprovalValuesRequest) returns
      (ListApprovalValuesResponse) {}

  // status: NOT READY
  // Changes state for a comment. Supported state transitions:
  //   - ACTIVE -> DELETED
  //   - ACTIVE -> SPAM
  //   - DELETED -> ACTIVE
  //   - SPAM -> ACTIVE
  //
  // Raises:
  //   TODO(crbug/monorail/7867): Document errors when implemented
  rpc ModifyCommentState (ModifyCommentStateRequest) returns
      (ModifyCommentStateResponse) {}

  // status: NOT READY
  // Makes an issue from an IssueTemplate and deltas.
  //
  // Raises:
  //   TODO(crbug/monorail/7197): Document errors when implemented
  rpc MakeIssueFromTemplate (MakeIssueFromTemplateRequest) returns (Issue) {}

  // status: ALPHA
  // Makes a basic issue, does not support phases, approvals, or approval
  // fields.
  // We do not offer a standard CreateIssue because Issue descriptions are
  // required, but not included in the Issue proto.
  //
  // Raises:
  //   INVALID_ARGUMENT if any given names does not have a valid format, if any
  //     fields in the requested issue were invalid, or if proposed values
  //     violates filter rules that should error.
  //   NOT_FOUND if no project exists with the given name.
  //   PERMISSION_DENIED if user lacks sufficient permissions.
  rpc MakeIssue (MakeIssueRequest) returns (Issue) {}
}


// The request message for Issues.GetIssue.
// Next available tag: 2
message GetIssueRequest {
  // The name of the issue to request.
  string name = 1 [
      (google.api.resource_reference) = {type: "api.crbug.com/Issue"},
      (google.api.field_behavior) = REQUIRED ];
}

// The request message for Issues.BatchGetIssues.
// Next available tag: 3
message BatchGetIssuesRequest {
  // The project name from which to batch get issues. If included, the parent
  // of all the issues specified in `names` must match this field.
  string parent = 1 [
    (google.api.resource_reference) = {type: "api.crbug.com/Project"} ];
  // The issues to request. Maximum of 100 can be retrieved.
  repeated string names = 2 [
      (google.api.resource_reference) = {type: "api.crbug.com/Issue"} ];
}

// The response message for Issues.BatchGetIssues.
// Next available tag: 2
message BatchGetIssuesResponse {
  // Issues matching the given request.
  repeated Issue issues = 1;
}

// The request message for Issues.SearchIssues.
// Next available tag: 6
message SearchIssuesRequest {
  // The names of Projects in which to search issues.
  repeated string projects = 1 [
    (google.api.resource_reference) = {type: "api.crbug.com/Project"},
    (google.api.field_behavior) = REQUIRED ];
  // The query string can contain any number of free text and
  // field search expressions.
  // Please see https://bugs.chromium.org/p/chromium/issues/searchtips for more
  // details of how the query string works.
  //
  // Canned queries have been deprecated in v3 in favor of search scoping using
  // parentheses support.
  // For clients who previously used canned queries, we're providing the
  // mapping of legacy canned query IDs to Monorail search syntax:
  //   - Format: (can_id, description, query_string)
  //   - (1, 'All issues', '')
  //   - (2, 'Open issues', 'is:open')
  //   - (3, 'Open and owned by me', 'is:open owner:me')
  //   - (4, 'Open and reported by me', 'is:open reporter:me')
  //   - (5, 'Open and starred by me', 'is:open is:starred')
  //   - (6, 'New issues', 'status:new')
  //   - (7, 'Issues to verify', 'status=fixed,done')
  //   - (8, 'Open with comment by me', 'is:open commentby:me')
  string query = 2;
  // The maximum number of items to return. The service may return fewer than
  // this value.
  // If unspecified, at most 100 items will be returned.
  // The maximum value is 100; values above 100 will be coerced to 100.
  int32 page_size = 3;
  // A page token, received from a previous `SearchIssues` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `SearchIssues` must match
  // the call that provided the page token.
  string page_token = 4;
  // 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, high to low,
  // then by status, low to high.
  string order_by = 5;
}

// The response message for Issues.SearchIssues.
// Next available tag: 3
message SearchIssuesResponse {
  // Issues matching the given request.
  repeated Issue issues = 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 message for Issues.ListComments.
// Next available tag: 5
message ListCommentsRequest {
  // The name of the issue for which to list comments.
  string parent = 1 [
    (google.api.resource_reference) = {type: "api.crbug.com/Issue"},
    (google.api.field_behavior) = REQUIRED ];
  // The maximum number of items to return. The service may return fewer than
  // this value.
  // If unspecified, at most 100 items will be returned.
  // The maximum value is 100; values above 100 will be coerced to 100.
  int32 page_size = 2;
  // A page token, received from a previous `ListComments` call.
  // Provide this to retrieve the subsequent page.
  //
  // When paginating, all other parameters provided to `ListComments` must
  // match the call that provided the page token.
  string page_token = 3;
  // For our initial release this filter only supports filtering to comments
  // related to a specific approval.
  // For example `approval = "projects/monorail/approvalDefs/1"`,
  // Note that no further logical or comparison operators are supported
  string filter = 4;
}

// The response message for Issues.ListComments
// Next available tag: 3
message ListCommentsResponse {
  // The comments from the specified issue.
  repeated Comment comments = 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;
}

// An attachment to upload to a comment or description.
// Next available tag: 3
message AttachmentUpload {
  string filename = 1 [ (google.api.field_behavior) = REQUIRED ];
  bytes content = 2 [ (google.api.field_behavior) = REQUIRED ];
}

// Holds changes to one issue, used in ModifyIssuesRequest.
// Next available tag: 9
message IssueDelta {
  // The issue's `name` field is used to identify the issue to be
  // updated. `issue.name` must always be filled.
  //
  // Values with rule-based Derivation within `issue` and in `field_vals_remove`
  // will be ignored.
  Issue issue = 1 [
      (google.api.field_behavior) = REQUIRED ];
  // The list of fields in `issue` to be updated.
  //
  // Repeated fields set on `issue` will be appended to.
  //
  // Non-repeated fields (e.g. `owner`) can be set with `issue.owner` set and
  // either 'owner' or 'owner.user' added to `update_mask`.
  // To unset non-repeated fields back to their default value, `issue.owner`
  // must contain the default value and `update_mask` must include 'owner.user'
  // NOT 'owner'.
  //
  // Its `field_values`, however, are a special case. Fields can be specified as
  // single-value or multi-value in their FieldDef.
  //
  // Single-value Field: if there is preexisting FieldValue with the same
  // `field` and `phase`, it will be REPLACED.
  //
  // Multi-value Field: a new value will be appended, unless the same `field`,
  // `phase`, `value` combination already exists. In that case, the FieldValue
  // will be ignored. In other words, duplicate values are ignored.
  // (With the exception of crbug.com/monorail/8137 until it is fixed).
  google.protobuf.FieldMask update_mask = 2 [
      (google.api.field_behavior) = REQUIRED ];

  // Values to remove from the repeated fields of the issue.

  // Cc's to remove.
  repeated string ccs_remove = 3 [
      (google.api.resource_reference) = {type: "api.crbug.com/User"}];
  // Blocked_on issues to remove.
  repeated IssueRef blocked_on_issues_remove = 4;
  // Blocking issues to remove.
  repeated IssueRef blocking_issues_remove = 5;
  // Components to remove.
  repeated string components_remove = 6 [
      (google.api.resource_reference) = {type: "api.crbug.com/ComponentDef"}];
  // Labels to remove.
  repeated string labels_remove = 7;
  // FieldValues to remove. Any values that did not already exist will be
  // ignored e.g. if you append a FieldValue in issue and remove it here, it
  // will still be added.
  repeated FieldValue field_vals_remove = 8;

  // TODO(crbug.com/monorail/8019): add Attachment uploading and removing.
}

// Changes to make to an ApprovalValue. Used to ModifyIssueApprovalValues or
// to MakeIssueFromTemplate.
//
// NOTE: The same handling of FieldValues discussed in IssueDelta applies here.
// Next available tag: 6
message ApprovalDelta {
  // The ApprovalValue we want to update. `approval_value.name` must always be
  // set.
  ApprovalValue approval_value = 1;
  // Repeated fields found in `update_mask` will be appended to.
  google.protobuf.FieldMask update_mask = 2 [
      (google.api.field_behavior) = REQUIRED ];
  // Resource names of the approvers we want to remove.
  repeated string approvers_remove = 3 [
      (google.api.resource_reference) = { type: "api.crbug.com/User" }
  ];
  // FieldValues that do not belong to `approval_value` will trigger error.
  repeated FieldValue field_vals_remove = 5;
  // TODO(crbug.com/monorail/8019): add Attachment uploading and removing.
}


// The type of notification a change should trigger.
// See monorail/doc/userguide/email.md
// Next available tag: 2
enum NotifyType {
  // The default value. This value is unused.
  NOTIFY_TYPE_UNSPECIFIED = 0;
  // An email notification should be sent.
  EMAIL = 1;
  // No notifcation should be triggered at all.
  NO_NOTIFICATION = 2;
}


// The request message for Issues.ModifyIssues.
// Next available tag: 5
message ModifyIssuesRequest {
  // The issue changes to make. A maximum of 100 issue changes can be requested.
  // There is also a constraint of 50 additional 'impacted issues' per
  // ModifyIssuesRequest. 'Impacted issues' are issues that are adding/removing
  // `blocked_on`, `blocking`, or `merge`
  // If you encounter this error, consider significantly smaller batches.
  repeated IssueDelta deltas = 1;
  // The type of notification the modifications should trigger.
  NotifyType notify_type = 2;
  // The comment text that should be added to each issue in delta.
  // Max length is 51200 characters.
  string comment_content = 3;
  // The attachment that will be to each comment for each issue in delta.
  repeated AttachmentUpload uploads = 4;
}


// The response message for Issues.ModifyIssues.
// Next available tag: 2
message ModifyIssuesResponse {
  // The updated issues.
  repeated Issue issues = 1;
}

// The request message for Issues.ModifyIssueApprovalValues.
// Next available tag: 4
message ModifyIssueApprovalValuesRequest {
  // The ApprovalValue changes to make. Maximum of 100 deltas can be requested.
  repeated ApprovalDelta deltas = 1;
  // The type of notification the modifications should trigger.
  NotifyType notify_type = 2;
  // The `content` of the Comment created for each change in `deltas`.
  // Max length is 51200 characters.
  string comment_content = 3;
}

// The response message for Issues.ModifyIssueApprovalValuesRequest.
// Next available tag: 2
message ModifyIssueApprovalValuesResponse {
  // The updated ApprovalValues.
  repeated ApprovalValue approval_values = 1;
}

// The request message for Issue.ListApprovalValues.
// Next available tag: 2
message ListApprovalValuesRequest {
  // The name of the issue for which to list approval values.
  string parent = 1 [
    (google.api.resource_reference) = {type: "api.crbug.com/Issue"},
    (google.api.field_behavior) = REQUIRED ];
}

// The response message for Issues.ListApprovalValues.
// Next available tag: 2
message ListApprovalValuesResponse {
  // The approval values from the specified issue.
  repeated ApprovalValue approval_values = 1;
}

// The request message for Issues.ModifyCommentState.
// Next available tag: 3
message ModifyCommentStateRequest {
  // Resource name of the comment to modify state.
  string name = 1 [
    (google.api.resource_reference) = {type: "api.crbug.com/Comment"},
    (google.api.field_behavior) = REQUIRED ];
  // Requested state.
  IssueContentState state = 2;
}

// The response message for Issues.ModifyCommentState.
// Next available tag: 2
message ModifyCommentStateResponse {
  // The updated comment after modifying state.
  Comment comment = 1;
}

// The request message for MakeIssueFromTemplate.
// Next available tag: 5
message MakeIssueFromTemplateRequest {
  // Resource name of the template to use for filling in default values
  // and adding approvals and phases.
  string template = 1 [
      (google.api.resource_reference) = { type: "api.crbug.com/Template" }
  ];
  // The issue differences relative to the `template.issue` default.
  IssueDelta template_issue_delta = 2;
  // Changes to fields belonging to approvals relative to template default.
  // While ApprovalDelta can hold additional information, this method only
  // allows adding and removing field values, all other deltas will be ignored.
  repeated ApprovalDelta template_approval_deltas = 3;
  // The issue description, will be saved as the first comment.
  string description = 4;
}

// The request message for MakeIssue.
// Next available tag: 6
message MakeIssueRequest {
  // The name of the project the issue should belong to.
  string parent = 1 [
    (google.api.resource_reference) = {type: "api.crbug.com/Project"},
    (google.api.field_behavior) = REQUIRED ];
  // The issue to be created.
  Issue issue = 2;
  // The issue description.
  string description = 3;
  // The type of notification the creation should trigger.
  NotifyType notify_type = 4;
  // The attachment that will be attached to each new issue.
  repeated AttachmentUpload uploads = 5;
}