// 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.locationfinder.v1;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";

option csharp_namespace = "Google.Cloud.LocationFinder.V1";
option go_package = "cloud.google.com/go/locationfinder/apiv1/locationfinderpb;locationfinderpb";
option java_multiple_files = true;
option java_outer_classname = "CloudLocationProto";
option java_package = "com.google.cloud.locationfinder.v1";
option php_namespace = "Google\\Cloud\\LocationFinder\\V1";
option ruby_package = "Google::Cloud::LocationFinder::V1";

// Represents resource cloud locations.
message CloudLocation {
  option (google.api.resource) = {
    type: "cloudlocationfinder.googleapis.com/CloudLocation"
    pattern: "projects/{project}/locations/{location}/cloudLocations/{cloud_location}"
    plural: "cloudLocations"
    singular: "cloudLocation"
  };

  // The type of the cloud provider. This enum lists all possible providers of
  // cloud locations.
  enum CloudProvider {
    // Unspecified type.
    CLOUD_PROVIDER_UNSPECIFIED = 0;

    // Cloud provider type for Google Cloud.
    CLOUD_PROVIDER_GCP = 1;

    // Cloud provider type for AWS.
    CLOUD_PROVIDER_AWS = 2;

    // Cloud provider type for Azure.
    CLOUD_PROVIDER_AZURE = 3;

    // Cloud provider type for OCI.
    CLOUD_PROVIDER_OCI = 4;
  }

  // The type of the cloud location. This enum lists all possible categories of
  // cloud locations.
  enum CloudLocationType {
    // Unspecified type.
    CLOUD_LOCATION_TYPE_UNSPECIFIED = 0;

    // CloudLocation type for region.
    CLOUD_LOCATION_TYPE_REGION = 1;

    // CloudLocation type for zone.
    CLOUD_LOCATION_TYPE_ZONE = 2;

    // CloudLocation type for region extension.
    CLOUD_LOCATION_TYPE_REGION_EXTENSION = 3;

    // CloudLocation type for Google Distributed Cloud Connected Zone.
    CLOUD_LOCATION_TYPE_GDCC_ZONE = 4;
  }

  // Identifier. Name of the cloud location. Unique name of the cloud location
  // including project and location using the form:
  // `projects/{project_id}/locations/{location}/cloudLocations/{cloud_location}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. The containing cloud location in the strict nesting hierarchy.
  // For example, the containing cloud location of a zone is a region.
  string containing_cloud_location = 2 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {
      type: "cloudlocationfinder.googleapis.com/CloudLocation"
    }
  ];

  // Optional. The human-readable name of the cloud location. Example:
  // us-east-2, us-east1.
  string display_name = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The provider of the cloud location. Values can be Google Cloud or
  // third-party providers, including AWS, Azure, or Oracle Cloud
  // Infrastructure.
  CloudProvider cloud_provider = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The two-letter ISO 3166-1 alpha-2 code of the cloud location.
  // Examples: US, JP, KR.
  string territory_code = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The type of the cloud location.
  CloudLocationType cloud_location_type = 6
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The carbon free energy percentage of the cloud location. This
  // represents the average percentage of time customers' application will be
  // running on carbon-free energy. See
  // https://cloud.google.com/sustainability/region-carbon for more details.
  // There is a difference between default value 0 and unset value. 0 means the
  // carbon free energy percentage is 0%, while unset value means the carbon
  // footprint data is not available.
  optional float carbon_free_energy_percentage = 7
      [(google.api.field_behavior) = OPTIONAL];
}

// Message for requesting list of cloud locations..
message ListCloudLocationsRequest {
  // Required. The parent, which owns this collection of cloud locations.
  // Format: projects/{project}/locations/{location}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "cloudlocationfinder.googleapis.com/CloudLocation"
    }
  ];

  // Optional. The maximum number of cloud locations to return per page. The
  // service might return fewer cloud locations than this value. If unspecified,
  // server will pick an appropriate default.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A token identifying a page of results the server should return.
  // Provide page token returned by a previous 'ListCloudLocations' call to
  // retrieve the next page of results. When paginating, all other parameters
  // provided to 'ListCloudLocations' must match the call that provided the page
  // token.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A filter expression that filters resources listed in the
  // response. The expression is in the form of field=value. For example,
  // 'cloud_location_type=CLOUD_LOCATION_TYPE_REGION'. Multiple filter queries
  // are space-separated. For example,
  // 'cloud_location_type=CLOUD_LOCATION_TYPE_REGION territory_code="US"' By
  // default, each expression is an AND expression. However, you can include AND
  // and OR expressions explicitly.
  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Message for response to listing cloud locations.
message ListCloudLocationsResponse {
  // Output only. List of cloud locations.
  repeated CloudLocation cloud_locations = 1
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The continuation token, used to page through large result
  // sets. Provide this value in a subsequent request as page_token in
  // subsequent requests to retrieve the next page. If this field is not
  // present, there are no subsequent results.
  string next_page_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Message for getting a cloud location.
message GetCloudLocationRequest {
  // Required. Name of the resource.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudlocationfinder.googleapis.com/CloudLocation"
    }
  ];
}

// Message for searching cloud locations from a given source location.
message SearchCloudLocationsRequest {
  // Required. The parent, which owns this collection of cloud locations.
  // Format: projects/{project}/locations/{location}
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "cloudlocationfinder.googleapis.com/CloudLocation"
    }
  ];

  // Required. The source cloud location to search from.
  // Example search can be searching nearby cloud locations from the source
  // cloud location by latency.
  string source_cloud_location = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "cloudlocationfinder.googleapis.com/CloudLocation"
    }
  ];

  // Optional. The maximum number of cloud locations to return. The service
  // might return fewer cloud locations than this value. If unspecified, server
  // will pick an appropriate default.
  int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A token identifying a page of results the server should return.
  // Provide Page token returned by a previous 'ListCloudLocations' call to
  // retrieve the next page of results. When paginating, all other parameters
  // provided to 'ListCloudLocations' must match the call that provided the page
  // token.
  string page_token = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The query string in search query syntax. While filter is used to
  // filter the search results by attributes, query is used to specify the
  // search requirements.
  string query = 6 [(google.api.field_behavior) = OPTIONAL];
}

// Message for response to searching cloud locations.
message SearchCloudLocationsResponse {
  // Output only. List of cloud locations.
  repeated CloudLocation cloud_locations = 1
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The continuation token, used to page through large result
  // sets. Provide this value in a subsequent request as page_token in
  // subsequent requests to retrieve the next page. If this field is not
  // present, there are no subsequent results.
  string next_page_token = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}