syntax = "proto3";

package tidb_cloud_open_api.fs.v1beta2;

import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
// buf:lint:ignore IMPORT_USED
import "google/rpc/status.proto"; // This is used by `responses.value.schema.json_schema.ref` in the swagger definition.
import "protoc-gen-openapiv2/options/annotations.proto";
import "tidb_cloud_open_api/common/v1beta1/region.proto";

option go_package = "tidb_cloud_open_api/fs/v1beta2";
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  swagger: "2.0"
  host: "fs.tidbapi.com"
  base_path: "/v1beta2"
  info: {
    version: "v1beta2"
    title: "TiDB Cloud FS API"
    description: "TiDB Cloud FS API"
  }
  schemes: HTTPS
  consumes: "application/json"
  produces: "application/json"

  responses: {
    key: "400"
    value: {
      description: "A request field is invalid."
      schema: {
        json_schema: {ref: ".google.rpc.Status"}
      }
    }
  }
  responses: {
    key: "401"
    value: {
      description: "The API key cannot be authenticated."
      schema: {
        json_schema: {ref: ".google.rpc.Status"}
      }
    }
  }
  responses: {
    key: "403"
    value: {
      description: "The API key does not have permission to access the resource."
      schema: {
        json_schema: {ref: ".google.rpc.Status"}
      }
    }
  }
  responses: {
    key: "429"
    value: {
      description: "You have exceeded the rate limit."
      schema: {
        json_schema: {ref: ".google.rpc.Status"}
      }
    }
  }
  responses: {
    key: "500"
    value: {
      description: "Internal server error."
      schema: {
        json_schema: {ref: ".google.rpc.Status"}
      }
    }
  }
};

service RegionService {
  // List all fs regions.
  rpc ListRegions(ListRegionsRequest) returns (ListRegionsResponse) {
    option (google.api.http) = {get: "/regions"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "List regions"
      tags: "Region"
      description: "Lists the regions where the fs service is available. Each region contains the endpoint address of the fs regional server. Use the endpoint address to call the fs regional server directly."
    };
  }

  // Get a fs region.
  rpc GetRegion(GetRegionRequest) returns (Region) {
    option (google.api.http) = {get: "/regions/{region_id}"};
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
      summary: "Get a region"
      tags: "Region"
      description: "Retrieves details of a specific fs region, including the endpoint address of the fs regional server. Use the endpoint address to call the fs regional server directly."
    };
  }
}

message ListRegionsRequest {
  // The cloud provider. If specified, only regions belonging to the specified cloud provider are returned.
  string cloud_provider = 1 [(google.api.field_behavior) = OPTIONAL];

  // The maximum number of regions to return. If not specified, at most 10 regions will be returned. The maximum value is `100`. Values greater than `100` are set to `100`.
  int32 page_size = 100 [
    (google.api.field_behavior) = OPTIONAL,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "10"
      default: "10"
      minimum: 1
      maximum: 100
    }
  ];

  // The pagination token received from a previous [List regions](#tag/Region/operation/RegionService_ListRegions) request. Use this token to retrieve the next page of results.
  //
  // **Note**: When paginating, all other parameters must match the original request.
  string page_token = 101 [(google.api.field_behavior) = OPTIONAL];

  // The number of regions to skip before returning results. If the value exceeds the total number of regions, the response is `200` with an empty list and no `nextPageToken`.
  int32 skip = 102 [(google.api.field_behavior) = OPTIONAL];
}

message ListRegionsResponse {
  // A list of regions that match the query.
  repeated Region regions = 1;

  // The total number of regions that match the query.
  int32 total_size = 100;

  // The token to retrieve the next page of results. Use this value as the `pageToken` parameter in the next request. This field is empty when there are no more pages.
  string next_page_token = 101;
}

message GetRegionRequest {
  // The ID of the region to retrieve, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-west-2`.
  string region_id = 1 [(google.api.field_behavior) = REQUIRED];
}

// A representation of an fs region.
message Region {
  option (google.api.resource) = {
    type: "tidb_cloud_open_api.fs.v1beta2/Region"
    pattern: "regions/{region}"
    singular: "region"
    plural: "regions"
  };

  string name = 1 [
    (google.api.field_behavior) = IDENTIFIER,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      pattern: "^regions/(aws|gcp|azure|alicloud)-(.+)$"
      example: "\"regions/aws-us-west-2\""
      description: "The unique name of the region, in the format of `regions/{region_id}`. For example, `regions/aws-us-west-2`."
    }
  ];

  string region_id = 2 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      pattern: "^(aws|gcp|azure|alicloud)-[a-z0-9-]+$"
      example: "\"aws-us-west-2\""
      description: "The unique identifier for the region, in the format of `{cloud_provider}-{region_code}`. For example, `aws-us-west-2`."
    }
  ];

  common.v1beta1.Region.CloudProvider cloud_provider = 3 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"aws\""
      description: "The cloud provider that offers the region.\n\n- `\"aws\"`: Amazon Web Services\n\n- `\"gcp\"`: Google Cloud\n\n- `\"azure\"`: Microsoft Azure\n\n- `\"alicloud\"`: Alibaba Cloud"
    }
  ];

  string display_name = 4 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"Oregon (us-west-2)\""
      description: "A human-readable name for the region. For example, `Oregon (us-west-2)`."
    }
  ];

  string service_address = 5 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      example: "\"https://fs-us-west-2.tidbcloud.com\""
      description: "The endpoint address of the fs regional server in this region. Call the fs regional server at this address directly for business requests."
    }
  ];

  State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The lifecycle state of the region.
  enum State {
    STATE_UNSPECIFIED = 0;
    // The region is available for business requests.
    ACTIVE = 1;
    // The region is not available yet.
    INACTIVE = 2;
  }
}