// Copyright 2025 Google LLC
//
// 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 google.cloud.chronicle.v1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.Chronicle.V1";
option go_package = "cloud.google.com/go/chronicle/apiv1/chroniclepb;chroniclepb";
option java_multiple_files = true;
option java_outer_classname = "ReferenceListProto";
option java_package = "com.google.cloud.chronicle.v1";
option php_namespace = "Google\\Cloud\\Chronicle\\V1";
option ruby_package = "Google::Cloud::Chronicle::V1";

// ReferenceListService provides an interface for managing reference lists.
service ReferenceListService {
  option (google.api.default_host) = "chronicle.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Gets a single reference list.
  rpc GetReferenceList(GetReferenceListRequest) returns (ReferenceList) {
    option (google.api.http) = {
      get: "/v1/{name=projects/*/locations/*/instances/*/referenceLists/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Lists a collection of reference lists.
  rpc ListReferenceLists(ListReferenceListsRequest)
      returns (ListReferenceListsResponse) {
    option (google.api.http) = {
      get: "/v1/{parent=projects/*/locations/*/instances/*}/referenceLists"
    };
    option (google.api.method_signature) = "parent";
  }

  // Creates a new reference list.
  rpc CreateReferenceList(CreateReferenceListRequest) returns (ReferenceList) {
    option (google.api.http) = {
      post: "/v1/{parent=projects/*/locations/*/instances/*}/referenceLists"
      body: "reference_list"
    };
    option (google.api.method_signature) =
        "parent,reference_list,reference_list_id";
  }

  // Updates an existing reference list.
  rpc UpdateReferenceList(UpdateReferenceListRequest) returns (ReferenceList) {
    option (google.api.http) = {
      patch: "/v1/{reference_list.name=projects/*/locations/*/instances/*/referenceLists/*}"
      body: "reference_list"
    };
    option (google.api.method_signature) = "reference_list,update_mask";
  }
}

// The syntax type indicating how list entries should be validated.
enum ReferenceListSyntaxType {
  // Defaults to REFERENCE_LIST_SYNTAX_TYPE_PLAIN_TEXT_STRING.
  REFERENCE_LIST_SYNTAX_TYPE_UNSPECIFIED = 0;

  // List contains plain text patterns.
  REFERENCE_LIST_SYNTAX_TYPE_PLAIN_TEXT_STRING = 1;

  // List contains only Regular Expression patterns.
  REFERENCE_LIST_SYNTAX_TYPE_REGEX = 2;

  // List contains only CIDR patterns.
  REFERENCE_LIST_SYNTAX_TYPE_CIDR = 3;
}

// ReferenceListView is a mechanism for viewing partial responses of the
// ReferenceList resource.
enum ReferenceListView {
  // The default / unset value.
  // The API will default to the BASIC view for ListReferenceLists.
  // The API will default to the FULL view for methods that return a single
  // ReferenceList resource.
  REFERENCE_LIST_VIEW_UNSPECIFIED = 0;

  // Include metadata about the ReferenceList.
  // This is the default view for ListReferenceLists.
  REFERENCE_LIST_VIEW_BASIC = 1;

  // Include all details about the ReferenceList: metadata, content lines,
  // associated rule counts. This is the default view for GetReferenceList.
  REFERENCE_LIST_VIEW_FULL = 2;
}

// ScopeInfo specifies the scope info of the reference list.
message ScopeInfo {
  // Required. The list of scope names of the reference list, if the list is
  // empty the reference list is treated as unscoped.
  ReferenceListScope reference_list_scope = 2
      [(google.api.field_behavior) = REQUIRED];
}

// ReferenceListScope specifies the list of scope names of the reference list.
message ReferenceListScope {
  // Optional. The list of scope names of the reference list. The scope names
  // should be full resource names and should be of the format:
  // `projects/{project}/locations/{location}/instances/{instance}/dataAccessScopes/{scope_name}`.
  repeated string scope_names = 1 [(google.api.field_behavior) = OPTIONAL];
}

// A request to get details about a reference list.
message GetReferenceListRequest {
  // Required. The resource name of the reference list to retrieve.
  // Format:
  // `projects/{project}/locations/{locations}/instances/{instance}/referenceLists/{reference_list}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "chronicle.googleapis.com/ReferenceList"
    }
  ];

  // How much of the ReferenceList to view. Defaults to
  // REFERENCE_LIST_VIEW_FULL.
  ReferenceListView view = 2;
}

// A request for a list of reference lists.
message ListReferenceListsRequest {
  // Required. The parent, which owns this collection of reference lists.
  // Format:
  // `projects/{project}/locations/{location}/instances/{instance}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "chronicle.googleapis.com/ReferenceList"
    }
  ];

  // The maximum number of reference lists to return.
  // The service may return fewer than this value.
  // If unspecified, at most 100 reference lists will be returned.
  // The maximum value is 1000; values above 1000 will be coerced to 1000.
  int32 page_size = 2;

  // A page token, received from a previous `ListReferenceLists` call.
  // Provide this to retrieve the subsequent page.
  // When paginating, all other parameters provided to `ListReferenceLists` must
  // match the call that provided the page token.
  string page_token = 3;

  // How much of each ReferenceList to view. Defaults to
  // REFERENCE_LIST_VIEW_BASIC.
  ReferenceListView view = 4;
}

// A response to a request for a list of reference lists.
message ListReferenceListsResponse {
  // The reference lists.
  // Ordered in ascending alphabetical order by name.
  repeated ReferenceList reference_lists = 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;
}

// A request to create a reference list.
message CreateReferenceListRequest {
  // Required. The parent resource where this reference list will be created.
  // Format: `projects/{project}/locations/{location}/instances/{instance}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "chronicle.googleapis.com/ReferenceList"
    }
  ];

  // Required. The reference list to create.
  ReferenceList reference_list = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The ID to use for the reference list. This is also the display
  // name for the reference list. It must satisfy the following requirements:
  // - Starts with letter.
  // - Contains only letters, numbers and underscore.
  // - Has length less than 256.
  // - Must be unique.
  string reference_list_id = 3 [(google.api.field_behavior) = REQUIRED];
}

// A request to update a reference list.
message UpdateReferenceListRequest {
  // Required. The reference list to update.
  //
  // The reference list's `name` field is used to identify the reference list to
  // update.
  // Format:
  // `projects/{project}/locations/{locations}/instances/{instance}/referenceLists/{reference_list}`
  ReferenceList reference_list = 1 [(google.api.field_behavior) = REQUIRED];

  // The list of fields to update.
  // When no field mask is supplied, all non-empty fields will be updated.
  // A field mask of "*" will update all fields, whether empty or not.
  google.protobuf.FieldMask update_mask = 2;
}

// A reference list.
// Reference lists are user-defined lists of values which users can
// use in multiple Rules.
message ReferenceList {
  option (google.api.resource) = {
    type: "chronicle.googleapis.com/ReferenceList"
    pattern: "projects/{project}/locations/{location}/instances/{instance}/referenceLists/{reference_list}"
  };

  // Identifier. The resource name of the reference list.
  // Format:
  // `projects/{project}/locations/{location}/instances/{instance}/referenceLists/{reference_list}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. The unique display name of the reference list.
  string display_name = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The timestamp when the reference list was last updated.
  google.protobuf.Timestamp revision_create_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. A user-provided description of the reference list.
  string description = 4 [(google.api.field_behavior) = REQUIRED];

  // Required. The entries of the reference list.
  // When listed, they are returned in the order that was specified at creation
  // or update. The combined size of the values of the reference list may not
  // exceed 6MB.
  // This is returned only when the view is REFERENCE_LIST_VIEW_FULL.
  repeated ReferenceListEntry entries = 5
      [(google.api.field_behavior) = REQUIRED];

  // Output only. The resource names for the associated self-authored Rules that
  // use this reference list. This is returned only when the view is
  // REFERENCE_LIST_VIEW_FULL.
  repeated string rules = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The syntax type indicating how list entries should be validated.
  ReferenceListSyntaxType syntax_type = 8
      [(google.api.field_behavior) = REQUIRED];

  // Output only. The count of self-authored rules using the reference list.
  int32 rule_associations_count = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The scope info of the reference list.
  // During reference list creation, if this field is not set, the reference
  // list without scopes (an unscoped list) will be created for an unscoped
  // user. For a scoped user, this field must be set. During reference list
  // update, if scope_info is requested to be updated, this field must be set.
  ScopeInfo scope_info = 11;
}

// An entry in a reference list.
message ReferenceListEntry {
  // Required. The value of the entry. Maximum length is 512 characters.
  string value = 1 [(google.api.field_behavior) = REQUIRED];
}