// Copyright 2021 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.resourcemanager.v3;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/iam/v1/iam_policy.proto";
import "google/iam/v1/policy.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.ResourceManager.V3";
option go_package = "google.golang.org/genproto/googleapis/cloud/resourcemanager/v3;resourcemanager";
option java_multiple_files = true;
option java_outer_classname = "TagKeysProto";
option java_package = "com.google.cloud.resourcemanager.v3";
option php_namespace = "Google\\Cloud\\ResourceManager\\V3";
option ruby_package = "Google::Cloud::ResourceManager::V3";

// Allow users to create and manage tag keys.
service TagKeys {
  option (google.api.default_host) = "cloudresourcemanager.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/cloud-platform.read-only";

  // Lists all TagKeys for a parent resource.
  rpc ListTagKeys(ListTagKeysRequest) returns (ListTagKeysResponse) {
    option (google.api.http) = {
      get: "/v3/tagKeys"
    };
    option (google.api.method_signature) = "parent";
  }

  // Retrieves a TagKey. This method will return `PERMISSION_DENIED` if the
  // key does not exist or the user does not have permission to view it.
  rpc GetTagKey(GetTagKeyRequest) returns (TagKey) {
    option (google.api.http) = {
      get: "/v3/{name=tagKeys/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Creates a new TagKey. If another request with the same parameters is
  // sent while the original request is in process, the second request
  // will receive an error. A maximum of 300 TagKeys can exist under a parent at
  // any given time.
  rpc CreateTagKey(CreateTagKeyRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v3/tagKeys"
      body: "tag_key"
    };
    option (google.api.method_signature) = "tag_key";
    option (google.longrunning.operation_info) = {
      response_type: "TagKey"
      metadata_type: "CreateTagKeyMetadata"
    };
  }

  // Updates the attributes of the TagKey resource.
  rpc UpdateTagKey(UpdateTagKeyRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      patch: "/v3/{tag_key.name=tagKeys/*}"
      body: "tag_key"
    };
    option (google.api.method_signature) = "tag_key,update_mask";
    option (google.longrunning.operation_info) = {
      response_type: "TagKey"
      metadata_type: "UpdateTagKeyMetadata"
    };
  }

  // Deletes a TagKey. The TagKey cannot be deleted if it has any child
  // TagValues.
  rpc DeleteTagKey(DeleteTagKeyRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v3/{name=tagKeys/*}"
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "TagKey"
      metadata_type: "DeleteTagKeyMetadata"
    };
  }

  // Gets the access control policy for a TagKey. The returned policy may be
  // empty if no such policy or resource exists. The `resource` field should
  // be the TagKey's resource name. For example, "tagKeys/1234".
  // The caller must have
  // `cloudresourcemanager.googleapis.com/tagKeys.getIamPolicy` permission on
  // the specified TagKey.
  rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      post: "/v3/{resource=tagKeys/*}:getIamPolicy"
      body: "*"
    };
    option (google.api.method_signature) = "resource";
  }

  // Sets the access control policy on a TagKey, replacing any existing
  // policy. The `resource` field should be the TagKey's resource name.
  // For example, "tagKeys/1234".
  // The caller must have `resourcemanager.tagKeys.setIamPolicy` permission
  // on the identified tagValue.
  rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) {
    option (google.api.http) = {
      post: "/v3/{resource=tagKeys/*}:setIamPolicy"
      body: "*"
    };
    option (google.api.method_signature) = "resource,policy";
  }

  // Returns permissions that a caller has on the specified TagKey.
  // The `resource` field should be the TagKey's resource name.
  // For example, "tagKeys/1234".
  //
  // There are no permissions required for making this API call.
  rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) {
    option (google.api.http) = {
      post: "/v3/{resource=tagKeys/*}:testIamPermissions"
      body: "*"
    };
    option (google.api.method_signature) = "resource,permissions";
  }
}

// A TagKey, used to group a set of TagValues.
message TagKey {
  option (google.api.resource) = {
    type: "cloudresourcemanager.googleapis.com/TagKey"
    pattern: "tagKeys/{tag_key}"
    style: DECLARATIVE_FRIENDLY
  };

  // Immutable. The resource name for a TagKey. Must be in the format
  // `tagKeys/{tag_key_id}`, where `tag_key_id` is the generated numeric id for
  // the TagKey.
  string name = 1 [(google.api.field_behavior) = IMMUTABLE];

  // Immutable. The resource name of the new TagKey's parent.
  // Must be of the form `organizations/{org_id}`.
  string parent = 2 [(google.api.field_behavior) = IMMUTABLE];

  // Required. Immutable. The user friendly name for a TagKey. The short name should be
  // unique for TagKeys within the same tag namespace.
  //
  // The short name must be 1-63 characters, beginning and ending with
  // an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_),
  // dots (.), and alphanumerics between.
  string short_name = 3 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Output only. Immutable. Namespaced name of the TagKey.
  string namespaced_name = 4 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Optional. User-assigned description of the TagKey. Must not exceed 256 characters.
  //
  // Read-write.
  string description = 5 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Creation time.
  google.protobuf.Timestamp create_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Update time.
  google.protobuf.Timestamp update_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Entity tag which users can pass to prevent race conditions. This field is
  // always set in server responses. See UpdateTagKeyRequest for details.
  string etag = 8 [(google.api.field_behavior) = OPTIONAL];
}

// The request message for listing all TagKeys under a parent resource.
message ListTagKeysRequest {
  // Required. The resource name of the new TagKey's parent.
  // Must be of the form `folders/{folder_id}` or `organizations/{org_id}`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "*"
    }
  ];

  // Optional. The maximum number of TagKeys to return in the response. The server allows
  // a maximum of 300 TagKeys to return. If unspecified, the server will use 100
  // as the default.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A pagination token returned from a previous call to `ListTagKey`
  // that indicates where this listing should continue from.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// The ListTagKeys response message.
message ListTagKeysResponse {
  // List of TagKeys that live under the specified parent in the request.
  repeated TagKey tag_keys = 1;

  // A pagination token returned from a previous call to `ListTagKeys`
  // that indicates from where listing should continue.
  string next_page_token = 2;
}

// The request message for getting a TagKey.
message GetTagKeyRequest {
  // Required. A resource name in the format `tagKeys/{id}`, such as
  // `tagKeys/123`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/TagKey"
    }
  ];
}

// The request message for creating a TagKey.
message CreateTagKeyRequest {
  // Required. The TagKey to be created. Only fields `short_name`, `description`,
  // and `parent` are considered during the creation request.
  TagKey tag_key = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Set to true to perform validations necessary for creating the resource, but
  // not actually perform the action.
  bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Runtime operation information for creating a TagKey.
message CreateTagKeyMetadata {

}

// The request message for updating a TagKey.
message UpdateTagKeyRequest {
  // Required. The new definition of the TagKey. Only the `description` and `etag` fields
  // can be updated by this request. If the `etag` field is not empty, it
  // must match the `etag` field of the existing tag key. Otherwise,
  // `FAILED_PRECONDITION` will be returned.
  TagKey tag_key = 1 [(google.api.field_behavior) = REQUIRED];

  // Fields to be updated. The mask may only contain `description` or
  // `etag`. If omitted entirely, both `description` and `etag` are assumed to
  // be significant.
  google.protobuf.FieldMask update_mask = 2;

  // Set as true to perform validations necessary for updating the resource, but
  // not actually perform the action.
  bool validate_only = 3;
}

// Runtime operation information for updating a TagKey.
message UpdateTagKeyMetadata {

}

// The request message for deleting a TagKey.
message DeleteTagKeyRequest {
  // Required. The resource name of a TagKey to be deleted in the format `tagKeys/123`.
  // The TagKey cannot be a parent of any existing TagValues or it will not be
  // deleted successfully.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudresourcemanager.googleapis.com/TagKey"
    }
  ];

  // Optional. Set as true to perform validations necessary for deletion, but not actually
  // perform the action.
  bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The etag known to the client for the expected state of the TagKey. This is
  // to be used for optimistic concurrency.
  string etag = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Runtime operation information for deleting a TagKey.
message DeleteTagKeyMetadata {

}
