go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/analysis/proto/v1/rules.proto

// Copyright 2022 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 luci.analysis.v1;

import "google/api/field_behavior.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";
import "go.chromium.org/luci/analysis/proto/v1/common.proto";

option go_package = "go.chromium.org/luci/analysis/proto/v1;analysispb";

// Provides methods to manipulate rules in LUCI Analysis, used to associate
// failures with bugs.
service Rules {
  // Retrieves a rule.
  // Designed to conform to https://google.aip.dev/131.
  rpc Get(GetRuleRequest) returns (Rule) {};

  // Lists rules.
  // TODO: implement pagination to make this
  // RPC compliant with https://google.aip.dev/132.
  // This RPC is incomplete. Future breaking changes are
  // expressly flagged.
  rpc List(ListRulesRequest) returns (ListRulesResponse) {};

  // Creates a new rule.
  // Designed to conform to https://google.aip.dev/133.
  rpc Create(CreateRuleRequest) returns (Rule) {};

  // Updates a rule.
  // Designed to conform to https://google.aip.dev/134.
  rpc Update(UpdateRuleRequest) returns (Rule) {};

  // Looks up the rule associated with a given bug, without knowledge
  // of the LUCI project the rule is in.
  // Designed to conform to https://google.aip.dev/136.
  rpc LookupBug(LookupBugRequest) returns (LookupBugResponse) {};
}

// A rule associating failures with a bug.
message Rule {
  // The resource name of the failure association rule.
  // Can be used to refer to this rule, e.g. in Rules.Get RPC.
  // Format: projects/{project}/rules/{rule_id}.
  // See also https://google.aip.dev/122.
  string name = 1;

  // The LUCI Project for which this rule is defined.
  string project = 2
    [(google.api.field_behavior) = OUTPUT_ONLY];

  // The unique identifier for the failure association rule,
  // as 32 lowercase hexadecimal characters.
  string rule_id = 3
    [(google.api.field_behavior) = OUTPUT_ONLY];

  // The rule predicate, defining which failures are being associated.
  // For example, 'reason LIKE "Some error: %"'.
  //
  // analysis/internal/clustering/rules/lang/lang.go contains the
  // EBNF grammar for the language used to define rule predicates;
  // it is a subset of Google Standard SQL.
  //
  // The maximum allowed length is 65536 characters.
  string rule_definition = 4
    [(google.api.field_behavior) = REQUIRED];

  // The bug that the failures are associated with.
  luci.analysis.v1.AssociatedBug bug = 5
    [(google.api.field_behavior) = REQUIRED];

  // Whether the bug should be updated by LUCI Analysis, and whether
  // failures should still be matched against the rule.
  bool is_active = 6;

  // Whether LUCI Analysis should manage the priority and verified status
  // of the associated bug based on the impact established via this rule.
  bool is_managing_bug = 14;

  // Determines whether LUCI Analysis is managing the bug priority updates
  // of the bug.
  bool is_managing_bug_priority = 15;

  // Output Only. The time is_managing_bug_priority was last updated.
  google.protobuf.Timestamp is_managing_bug_priority_last_update_time = 16;

  // The suggested cluster this rule was created from (if any).
  // Until re-clustering is complete and has reduced the residual impact
  // of the source cluster, this cluster ID tells bug filing to ignore
  // the source cluster when determining whether new bugs need to be filed.
  // Immutable after creation.
  luci.analysis.v1.ClusterId source_cluster = 7;

  // Bug management state.
  // System controlled data, cannot be modified by the user.
  BugManagementState bug_management_state = 17
    [(google.api.field_behavior) = OUTPUT_ONLY];

  // The time the rule was created.
  google.protobuf.Timestamp create_time = 8
    [(google.api.field_behavior) = OUTPUT_ONLY];

  // The user which created the rule.
  // This could be an email address or the value 'system' (for rules
  // automaticatically created by LUCI Analysis itself).
  // This value may not be available, as its disclosure is limited
  // to Googlers only and is subject to automatic deletion after 30 days.
  string create_user = 9
    [(google.api.field_behavior) = OUTPUT_ONLY];

	// The last time an auditable field was updated. An auditable field
	// is any field other than a system controlled data field.
  google.protobuf.Timestamp last_auditable_update_time = 18
    [(google.api.field_behavior) = OUTPUT_ONLY];

	// The last user which updated an auditable field. An auditable field
	// is any field other than a system controlled data field.
  // This could be an email address or the value 'system' (for rules
  // automaticatically modified by LUCI Analysis itself).
  // This value may not be available, as its disclosure is limited
  // to Googlers only and is subject to automatic deletion after 30 days.
  string last_auditable_update_user = 19
    [(google.api.field_behavior) = OUTPUT_ONLY];

  // The time the rule was last updated.
  google.protobuf.Timestamp last_update_time = 10
    [(google.api.field_behavior) = OUTPUT_ONLY];

  reserved 11; // Removed.

  // The time the rule was last updated in a way that caused the
  // matched failures to change, i.e. because of a change to rule_definition
  // or is_active. (By contrast, updating the associated bug does NOT change
  // the matched failures, so does NOT update this field.)
  // Output only.
  google.protobuf.Timestamp predicate_last_update_time = 13
    [(google.api.field_behavior) = OUTPUT_ONLY];

  // This checksum is computed by the server based on the value of other
  // fields, and may be sent on update requests to ensure the client
  // has an up-to-date value before proceeding.
  // See also https://google.aip.dev/154.
  string etag = 12;

  // Next ID: 20
}

// BugManagementState is the state of bug management for a rule.
message BugManagementState {
  // The state of each bug management policy.
  repeated PolicyState policy_state = 1;

  // The state of a bug management policy for a rule.
  message PolicyState {
    // The identifier of the bug management policy.
    string policy_id = 1;

    // Whether the given policy is active for the rule.
    // Updated on every bug-filing run as follows:
    // - Set to true if the policy activation criteria was met.
    // - Set to false if the policy deactivation criteria was met.
    bool is_active = 2;

    // The last time the policy was made active.
    // Allows detecting if policy is made active for the first time (as a
    // zero last_activation_time indicates the policy was never active).
    // Allows UI to filter to showing policies that were at least once active.
    // Allows UI to sort which policy was most recently active.
    // Allows UI to show when a policy last activated.
    google.protobuf.Timestamp last_activation_time = 3;

    // The last time the policy was made inactive.
    // Allows UI to show when a policy last deactivated.
    google.protobuf.Timestamp last_deactivation_time = 4;
  }
}

message GetRuleRequest {
  // The name of the rule to retrieve.
  // Format: projects/{project}/rules/{rule_id}.
  string name = 1
    [(google.api.field_behavior) = REQUIRED];
}

message ListRulesRequest {
  // The parent, which owns this collection of rules.
  // Format: projects/{project}.
  string parent = 1
    [(google.api.field_behavior) = REQUIRED];
}

message ListRulesResponse {
  // The rules.
  repeated Rule rules = 1;
}

message CreateRuleRequest {
  // The parent resource where the rule will be created.
  // Format: projects/{project}.
  string parent = 1
    [(google.api.field_behavior) = REQUIRED];

  // The rule to create.
  Rule rule = 2
    [(google.api.field_behavior) = REQUIRED];
}

message UpdateRuleRequest {
  // The rule to update.
  //
  // The rule's `name` field is used to identify the book to update.
  // Format: projects/{project}/rules/{rule_id}.
  Rule rule = 1
    [(google.api.field_behavior) = REQUIRED];

  // The list of fields to update.
  google.protobuf.FieldMask update_mask = 2;

  // The current etag of the rule.
  // If an etag is provided and does not match the current etag of the rule,
  // update will be blocked and an ABORTED error will be returned.
  string etag = 3;
}

message LookupBugRequest {
  // System is the bug tracking system of the bug. This is either
  // "monorail" or "buganizer".
  string system = 1
    [(google.api.field_behavior) = REQUIRED];

  // Id is the bug tracking system-specific identity of the bug.
  // For monorail, the scheme is {project}/{numeric_id}, for
  // buganizer the scheme is {numeric_id}.
  string id = 2
    [(google.api.field_behavior) = REQUIRED];
}

message LookupBugResponse {
  // The rules corresponding to the requested bug.
  // Format: projects/{project}/rules/{rule_id}.
  repeated string rules = 2;
}