proto/tracker_pb2.py

# Copyright 2016 The Chromium Authors. All rights reserved.
# Use of this source code is governed by a BSD-style
# license that can be found in the LICENSE file or at
# https://developers.google.com/open-source/licenses/bsd

"""The Monorail issue tracker uses ProtoRPC for storing business objects."""

from __future__ import print_function
from __future__ import division
from __future__ import absolute_import

from protorpc import messages


class FieldValue(messages.Message):
  """Holds a single custom field value in an issue.

  Multi-valued custom fields will have multiple such FieldValues on a given
  issue. Note that enumerated type custom fields are represented as key-value
  labels.
  """
  field_id = messages.IntegerField(1, required=True)
  # Only one of the following fields will hve any value.
  int_value = messages.IntegerField(2)
  str_value = messages.StringField(3)
  user_id = messages.IntegerField(4)
  date_value = messages.IntegerField(6)
  url_value = messages.StringField(7)

  derived = messages.BooleanField(5, default=False)

  # None if field is not a phse field.
  phase_id = messages.IntegerField(8)


class ApprovalStatus(messages.Enum):
  """Statuses that an approval field could be set to."""
  NEEDS_REVIEW = 1
  NA = 2
  REVIEW_REQUESTED = 3
  REVIEW_STARTED = 4
  NEED_INFO = 5
  APPROVED = 6
  NOT_APPROVED = 7
  NOT_SET = 8


class ApprovalValue(messages.Message):
  """Holds a single approval field value in an issue."""
  approval_id = messages.IntegerField(1)
  status = messages.EnumField(ApprovalStatus, 2, default='NOT_SET')
  setter_id = messages.IntegerField(3)
  set_on = messages.IntegerField(4)
  approver_ids = messages.IntegerField(5, repeated=True)
  phase_id = messages.IntegerField(7)


class ApprovalDelta(messages.Message):
  """In-memory representation of requested changes to an issue's approval."""
  status = messages.EnumField(ApprovalStatus, 1)
  set_on = messages.IntegerField(2)
  setter_id = messages.IntegerField(3)
  approver_ids_add = messages.IntegerField(4, repeated=True)
  approver_ids_remove = messages.IntegerField(5, repeated=True)
  subfield_vals_add = messages.MessageField(FieldValue, 6, repeated=True)
  subfield_vals_remove = messages.MessageField(FieldValue, 7, repeated=True)
  subfields_clear = messages.IntegerField(8, repeated=True)
  # Stores Approval's Enum subfield changes.
  labels_add = messages.StringField(9, repeated=True)
  labels_remove = messages.StringField(10, repeated=True)


class Phase(messages.Message):
  """Holds a single launch review phase."""
  phase_id = messages.IntegerField(1)
  name = messages.StringField(2)
  rank = messages.IntegerField(4)


class DanglingIssueRef(messages.Message):
  """Holds a reference to an issue on Codesite or an external tracker."""
  project = messages.StringField(1, required=True)
  issue_id = messages.IntegerField(2, required=True)
  ext_issue_identifier = messages.StringField(3, required=False)


class Issue(messages.Message):
  """Holds all the current metadata about an issue.

  The most frequent searches can work by consulting solely the issue metadata.
  Display of the issue list is done solely with this issue metadata.
  Displaying one issue in detail with description and comments requires
  more info from other objects.

  The issue_id field is the unique primary key for retrieving issues.  Local ID
  is a small integer that counts up in each project.

  Summary, Status, Owner, CC, reporter, and opened_timestamp are hard
  fields that are always there.  All other metadata is stored as
  labels or custom fields.
  Next available tag: 62.
  """
  # Globally unique issue ID.
  issue_id = messages.IntegerField(42)
  # project_name is not stored in the DB, only the project_id is stored.
  # project_name is used in RAM to simplify formatting logic in lots of places.
  project_name = messages.StringField(1, required=True)
  project_id = messages.IntegerField(50)
  local_id = messages.IntegerField(2, required=True)
  summary = messages.StringField(3, default='')
  status = messages.StringField(4, default='')
  owner_id = messages.IntegerField(5)
  cc_ids = messages.IntegerField(6, repeated=True)
  labels = messages.StringField(7, repeated=True)
  component_ids = messages.IntegerField(39, repeated=True)

  # Denormalized count of stars on this Issue.
  star_count = messages.IntegerField(8, required=True, default=0)
  reporter_id = messages.IntegerField(9, required=True, default=0)
  # Time that the issue was opened, in seconds since the Epoch.
  opened_timestamp = messages.IntegerField(10, required=True, default=0)

  # This should be set when an issue is closed and cleared when a
  # closed issue is reopened.  Measured in seconds since the Epoch.
  closed_timestamp = messages.IntegerField(12, default=0)

  # This should be updated every time an issue is modified.  Measured
  # in seconds since the Epoch.
  modified_timestamp = messages.IntegerField(13, default=0)

  # These timestamps are updated whenever owner, status, or components
  # change, including when altered by a filter rule.
  owner_modified_timestamp = messages.IntegerField(19, default=0)
  status_modified_timestamp = messages.IntegerField(20, default=0)
  component_modified_timestamp = messages.IntegerField(21, default=0)

  # Issue IDs of issues that this issue is blocked on.
  blocked_on_iids = messages.IntegerField(16, repeated=True)

  # Rank values of issue relations that are blocking this issue. The issue
  # with id blocked_on_iids[i] has rank value blocked_on_ranks[i]
  blocked_on_ranks = messages.IntegerField(54, repeated=True)

  # Issue IDs of issues that this issue is blocking.
  blocking_iids = messages.IntegerField(17, repeated=True)

  # References to 'dangling' (still in codesite) issue relations.
  dangling_blocked_on_refs = messages.MessageField(
      DanglingIssueRef, 52, repeated=True)
  dangling_blocking_refs = messages.MessageField(
      DanglingIssueRef, 53, repeated=True)

  # Issue ID of issue that this issue was merged into most recently.  When it
  # is missing or 0, it is considered to be not merged into any other issue.
  merged_into = messages.IntegerField(18)
  # Use this when an issue is a duplicate of an issue in an external tracker.
  merged_into_external = messages.StringField(61)

  # Default derived via rules, used iff status == ''.
  derived_status = messages.StringField(30, default='')
  # Default derived via rules, used iff owner_id == 0.
  derived_owner_id = messages.IntegerField(31, default=0)
  # Additional CCs derived via rules.
  derived_cc_ids = messages.IntegerField(32, repeated=True)
  # Additional labels derived via rules.
  derived_labels = messages.StringField(33, repeated=True)
  # Additional notification email addresses derived via rules.
  derived_notify_addrs = messages.StringField(34, repeated=True)
  # Additional components derived via rules.
  derived_component_ids = messages.IntegerField(40, repeated=True)
  # Software development process warnings and errors generated by filter rules.
  # TODO(jrobbins): these are not yet stored in the DB, they are only in RAM.
  derived_warnings = messages.StringField(55, repeated=True)
  derived_errors = messages.StringField(56, repeated=True)

  # Soft delete of the entire issue.
  deleted = messages.BooleanField(35, default=False)

  # Total number of attachments in the issue
  attachment_count = messages.IntegerField(36, default=0)

  # Total number of comments on the issue (not counting the initial comment
  # created when the issue is created).
  comment_count = messages.IntegerField(37, default=0)

  # Custom field values (other than enums)
  field_values = messages.MessageField(FieldValue, 41, repeated=True)

  is_spam = messages.BooleanField(51, default=False)
  # assume_stale is used in RAM to ensure that a value saved to the DB was
  # loaded from the DB in the same request handler (not via the cache).
  assume_stale = messages.BooleanField(57, default=True)

  phases = messages.MessageField(Phase, 59, repeated=True)
  approval_values = messages.MessageField(ApprovalValue, 60, repeated=True)


class FieldID(messages.Enum):
  """Possible fields that can be updated in an Amendment."""
  # The spelling of these names must match enum values in tracker.sql.
  SUMMARY = 1
  STATUS = 2
  OWNER = 3
  CC = 4
  LABELS = 5
  BLOCKEDON = 6
  BLOCKING = 7
  MERGEDINTO = 8
  PROJECT = 9
  COMPONENTS = 10
  CUSTOM = 11
  WARNING = 12
  ERROR = 13


class IssueDelta(messages.Message):
  """In-memory representation of requested changes to an issue.

  Next available tag: 23
  """
  status = messages.StringField(1)
  owner_id = messages.IntegerField(2)
  cc_ids_add = messages.IntegerField(3, repeated=True)
  cc_ids_remove = messages.IntegerField(4, repeated=True)
  comp_ids_add = messages.IntegerField(5, repeated=True)
  comp_ids_remove = messages.IntegerField(6, repeated=True)
  labels_add = messages.StringField(7, repeated=True)
  labels_remove = messages.StringField(8, repeated=True)
  field_vals_add = messages.MessageField(FieldValue, 9, repeated=True)
  field_vals_remove = messages.MessageField(FieldValue, 10, repeated=True)
  fields_clear = messages.IntegerField(11, repeated=True)
  blocked_on_add = messages.IntegerField(12, repeated=True)
  blocked_on_remove = messages.IntegerField(13, repeated=True)
  blocking_add = messages.IntegerField(14, repeated=True)
  blocking_remove = messages.IntegerField(15, repeated=True)
  merged_into = messages.IntegerField(16)
  merged_into_external = messages.StringField(22)
  summary = messages.StringField(17)
  ext_blocked_on_add = messages.StringField(18, repeated=True)
  ext_blocked_on_remove = messages.StringField(19, repeated=True)
  ext_blocking_add = messages.StringField(20, repeated=True)
  ext_blocking_remove = messages.StringField(21, repeated=True)


class Amendment(messages.Message):
  """Holds info about one issue field change."""
  field = messages.EnumField(FieldID, 11, required=True)
  # User-visible string describing the change
  newvalue = messages.StringField(12)
  # Newvalue could have + or - characters to indicate that labels and CCs
  # were added or removed
  # Users added to owner or cc field
  added_user_ids = messages.IntegerField(29, repeated=True)
  # Users removed from owner or cc
  removed_user_ids = messages.IntegerField(30, repeated=True)
  custom_field_name = messages.StringField(31)
  # When having newvalue be a +/- string doesn't make sense (e.g. status),
  # store the old value here so that it can still be displayed.
  oldvalue = messages.StringField(32)


class Attachment(messages.Message):
  """Holds info about one attachment."""
  attachment_id = messages.IntegerField(21, required=True)
  # Client-side filename
  filename = messages.StringField(22, required=True)
  filesize = messages.IntegerField(23, required=True)
  # File mime-type, or at least our best guess.
  mimetype = messages.StringField(24, required=True)
  deleted = messages.BooleanField(27, default=False)
  gcs_object_id = messages.StringField(29, required=False)


class IssueComment(messages.Message):
  # TODO(lukasperaza): update first comment to is_description=True
  """Holds one issue description or one additional comment on an issue.

  The IssueComment with the lowest timestamp is the issue description,
  if there is no IssueComment with is_description=True; otherwise, the
  IssueComment with is_description=True and the highest timestamp is
  the issue description.
  Next available tag: 56
  """
  id = messages.IntegerField(32)
  # Issue ID of the issue that was commented on.
  issue_id = messages.IntegerField(31, required=True)
  project_id = messages.IntegerField(50)
  # User who entered the comment
  user_id = messages.IntegerField(4, required=True, default=0)
  # id of the APPROVAL_TYPE fielddef, if this is an approval comment.
  approval_id = messages.IntegerField(54)
  # Time when comment was entered (seconds).
  timestamp = messages.IntegerField(5, required=True)
  # Text of the comment
  content = messages.StringField(6, required=True)
  # Audit trail of changes made w/ this comment
  amendments = messages.MessageField(Amendment, 10, repeated=True)

  # Soft delete that can be undeleted.
  # Deleted comments should not be shown to average users.
  # If deleted, deleted_by contains the user id of user who deleted.
  deleted_by = messages.IntegerField(13)

  attachments = messages.MessageField(Attachment, 20, repeated=True)

  # Sequence number of the comment
  # The field is optional for compatibility with code existing before
  # this field was added.
  # In practice, issue_svc sets this for all comments in GetCommentsForIssue.
  sequence = messages.IntegerField(26)

  # The body text of the inbound email that caused this issue comment
  # to be automatically entered.  If this field is non-empty, it means
  # that the comment was added via an inbound email.  Headers and attachments
  # are not included.
  inbound_message = messages.StringField(28)

  is_spam = messages.BooleanField(51, default=False)

  is_description = messages.BooleanField(52, default=False)
  description_num = messages.StringField(53)

  # User ID of script that imported the comment on behalf of a user.
  importer_id = messages.IntegerField(55, default=0)


class SavedQuery(messages.Message):
  """Store a saved query, for either a project or a user."""
  query_id = messages.IntegerField(1)
  name = messages.StringField(2)
  base_query_id = messages.IntegerField(3)
  query = messages.StringField(4, required=True)

  # For personal cross-project queries.
  executes_in_project_ids = messages.IntegerField(5, repeated=True)

  # For user saved queries.
  subscription_mode = messages.StringField(6)


class NotifyTriggers(messages.Enum):
  """Issue tracker events that can trigger notification emails."""
  NEVER = 0
  ANY_COMMENT = 1
  # TODO(jrobbins): ANY_CHANGE, OPENED_CLOSED, ETC.


class FieldTypes(messages.Enum):
  """Types of custom fields that Monorail supports."""
  ENUM_TYPE = 1
  INT_TYPE = 2
  STR_TYPE = 3
  USER_TYPE = 4
  DATE_TYPE = 5
  BOOL_TYPE = 6
  URL_TYPE = 7
  APPROVAL_TYPE = 8
  # TODO(jrobbins): more types, see tracker.sql for all TODOs.


class DateAction(messages.Enum):
  """What to do when a date field value arrives."""
  NO_ACTION = 0
  PING_OWNER_ONLY = 1
  PING_PARTICIPANTS = 2


class FieldDef(messages.Message):
  """This PB stores info about one custom field definition."""
  field_id = messages.IntegerField(1, required=True)
  project_id = messages.IntegerField(2, required=True)
  field_name = messages.StringField(3, required=True)
  field_type = messages.EnumField(FieldTypes, 4, required=True)
  applicable_type = messages.StringField(11)
  applicable_predicate = messages.StringField(10)
  is_required = messages.BooleanField(5, default=False)
  is_niche = messages.BooleanField(19, default=False)
  is_multivalued = messages.BooleanField(6, default=False)
  docstring = messages.StringField(7)
  is_deleted = messages.BooleanField(8, default=False)
  admin_ids = messages.IntegerField(9, repeated=True)
  editor_ids = messages.IntegerField(24, repeated=True)

  # validation details for int_type
  min_value = messages.IntegerField(12)
  max_value = messages.IntegerField(13)
  # validation details for str_type
  regex = messages.StringField(14)
  # validation details for user_type
  needs_member = messages.BooleanField(15, default=False)
  needs_perm = messages.StringField(16)

  # semantics for user_type fields
  grants_perm = messages.StringField(17)
  notify_on = messages.EnumField(NotifyTriggers, 18)

  # semantics for date_type fields
  date_action = messages.EnumField(DateAction, 20)

  # field_id of the approval this FieldDef belongs to
  approval_id = messages.IntegerField(21)

  # These fields should only be associated with issue phases
  is_phase_field = messages.BooleanField(22, default=False)

  # boolean that indicates if this field is restricted
  is_restricted_field = messages.BooleanField(23, default=False)


class ComponentDef(messages.Message):
  """This stores info about a component in a project."""
  component_id = messages.IntegerField(1, required=True)
  project_id = messages.IntegerField(2, required=True)
  path = messages.StringField(3, required=True)
  docstring = messages.StringField(4)
  admin_ids = messages.IntegerField(5, repeated=True)
  cc_ids = messages.IntegerField(6, repeated=True)
  deprecated = messages.BooleanField(7, default=False)
  created = messages.IntegerField(8)
  creator_id = messages.IntegerField(9)
  modified = messages.IntegerField(10)
  modifier_id = messages.IntegerField(11)
  label_ids = messages.IntegerField(12, repeated=True)


class FilterRule(messages.Message):
  """Filter rules implement semantics as project-specific if-then rules."""
  predicate = messages.StringField(10, required=True)

  # If the predicate is satisfied, these actions set some of the derived_*
  # fields on the issue: labels, status, owner, or CCs.
  add_labels = messages.StringField(20, repeated=True)
  default_status = messages.StringField(21)
  default_owner_id = messages.IntegerField(22)
  add_cc_ids = messages.IntegerField(23, repeated=True)
  add_notify_addrs = messages.StringField(24, repeated=True)
  warning = messages.StringField(25)
  error = messages.StringField(26)


class StatusDef(messages.Message):
  """Definition of one well-known issue status."""
  status = messages.StringField(11, required=True)
  means_open = messages.BooleanField(12, default=False)
  status_docstring = messages.StringField(13)
  deprecated = messages.BooleanField(14, default=False)


class LabelDef(messages.Message):
  """Definition of one well-known issue label."""
  label = messages.StringField(21, required=True)
  label_docstring = messages.StringField(22)
  deprecated = messages.BooleanField(23, default=False)


class ApprovalDef(messages.Message):
  """Definition of an approval type field def."""
  # Note: approval_id is semantically required
  approval_id = messages.IntegerField(1)
  approver_ids = messages.IntegerField(4, repeated=True)
  survey = messages.StringField(5)

# Next available tag: 48
class TemplateDef(messages.Message):
  """Definition of one issue template."""
  template_id = messages.IntegerField(57)
  name = messages.StringField(31, required=True)
  content = messages.StringField(32, required=True)
  summary = messages.StringField(33)
  summary_must_be_edited = messages.BooleanField(34, default=False)
  owner_id = messages.IntegerField(35)
  status = messages.StringField(36)
  # Note: labels field is considered to have been set iff summary was set.
  labels = messages.StringField(37, repeated=True)
  # This controls what is listed in the template drop-down menu. Users
  # could still select any template by editing the URL, and that's OK.
  members_only = messages.BooleanField(38, default=False)
  # If no owner_id is specified, and owner_defaults_to_member is
  # true, then when an issue is entered by a member, fill in the initial
  # owner field with the signed in user's name.
  owner_defaults_to_member = messages.BooleanField(39, default=True)
  admin_ids = messages.IntegerField(41, repeated=True)

  # Custom field values (other than enums)
  field_values = messages.MessageField(FieldValue, 42, repeated=True)
  # Components.
  component_ids = messages.IntegerField(43, repeated=True)
  component_required = messages.BooleanField(44, default=False)
  phases = messages.MessageField(Phase, 46, repeated=True)
  approval_values = messages.MessageField(ApprovalValue, 47, repeated=True)


class ProjectIssueConfig(messages.Message):
  """This holds all configuration info for one project.

  That includes canned queries, well-known issue statuses,
  and well-known issue labels.

  "Well-known" means that they are always offered to the user in
  drop-downs, even if there are currently no open issues that have
  that label or status value.  Deleting a well-known value from the
  configuration does not change any issues that may still reference
  that old label, and users are still free to use it.

  Exclusive label prefixes mean that a given issue may only have one
  label that begins with that prefix.  E.g., Priority should be
  exclusive so that no issue can be labeled with both Priority-High
  and Priority-Low.
  Next available tag: 62
  """

  project_id = messages.IntegerField(60)
  well_known_statuses = messages.MessageField(StatusDef, 10, repeated=True)
  # If an issue's status is being set to one of these, show "Merge with:".
  statuses_offer_merge = messages.StringField(14, repeated=True)

  well_known_labels = messages.MessageField(LabelDef, 20, repeated=True)
  exclusive_label_prefixes = messages.StringField(2, repeated=True)

  approval_defs = messages.MessageField(ApprovalDef, 61, repeated=True)

  field_defs = messages.MessageField(FieldDef, 5, repeated=True)
  component_defs = messages.MessageField(ComponentDef, 6, repeated=True)

  default_template_for_developers = messages.IntegerField(3, required=True)
  default_template_for_users = messages.IntegerField(4, required=True)

  # These options control the default appearance of the issue list or grid
  # for non-members.
  default_col_spec = messages.StringField(50, default='')
  default_sort_spec = messages.StringField(51, default='')
  default_x_attr = messages.StringField(52, default='')
  default_y_attr = messages.StringField(53, default='')

  # These options control the default appearance of the issue list or grid
  # for project members.
  member_default_query = messages.StringField(57, default='')

  # This bool controls whether users are able to enter odd-ball
  # labels and status values, or whether they are limited to only the
  # well-known labels and status values defined on the admin subtab.
  restrict_to_known = messages.BooleanField(16, default=False)

  # Allow special projects to have a custom URL for the "New issue" link.
  custom_issue_entry_url = messages.StringField(56)