syntax = "proto3";

package tidb_mgmt_service.v1;

import "google/api/annotations.proto";
import "google/api/field_behavior.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/timestamp.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
import "tidb_cloud_open_api/common/v1beta1/service_plan.proto";

/**
   All APIs here are for global control plane **internal** use only.
*/

option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
  swagger: "2.0"
  host: ""
  base_path: "/inner/mgmt/v1"
  info: {
    version: "v1"
    title: "Control Plane Internal API"
    description: "Control Plane Internal API."
  }
  schemes: HTTPS
};

/**
 * PrivateLinkServiceMigrationService is used to manage the private link service migration operations.
 * This service provides APIs for creating, monitoring, and managing private link service migration operations
 * between TiDB clusters.
 */
service PrivateLinkServiceMigrationService {
  // Create a new private link service migration operation
  // Require the source cluster and target cluster are in the same project and same region.
  rpc CreatePrivateLinkServiceMigration(CreatePrivateLinkServiceMigrationRequest) returns (PrivateLinkServiceMigration) {
    option (google.api.http) = {
      post: "/privateLinkServiceMigrations"
      body: "*"
    };
  }

  // Get a specific private link service migration operation by ID
  rpc GetPrivateLinkServiceMigration(GetPrivateLinkServiceMigrationRequest) returns (PrivateLinkServiceMigration) {
    option (google.api.http) = {get: "/privateLinkServiceMigrations/{id}"};
  }

  // List private link service migration operations with filtering and pagination
  rpc ListPrivateLinkServiceMigrations(ListPrivateLinkServiceMigrationsRequest) returns (ListPrivateLinkServiceMigrationsResponse) {
    option (google.api.http) = {get: "/privateLinkServiceMigrations"};
  }

  // Cancel a private link service migration operation
  // This cancel action just to stop the migration operation, but not to rollback the migration operation.
  rpc CancelPrivateLinkServiceMigration(CancelPrivateLinkServiceMigrationRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {post: "/privateLinkServiceMigrations/{id}:cancel"};
  }
}

/**
 * PrivateLinkServiceMigration represents a private link service migration operation between TiDB clusters.
 * This operation manages the migration of TiDB groups from a source cluster to a target cluster.
 */
message PrivateLinkServiceMigration {
  // Unique identifier for the migration operation
  uint64 id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // ID of the source cluster
  uint64 source_cluster_id = 2 [(google.api.field_behavior) = REQUIRED];

  // ID of the target cluster
  uint64 target_cluster_id = 3 [(google.api.field_behavior) = REQUIRED];

  // Service plan of the target cluster
  tidb_cloud_open_api.common.v1beta1.ServicePlan target_service_plan = 11 [(google.api.field_behavior) = OUTPUT_ONLY];

  // List of TiDB groups to be migrated (must contain at least one group)
  repeated MigrationTidbGroup migration_tidb_groups = 4 [(google.api.field_behavior) = REQUIRED];

  // Execution mode for the migration operation (default: PARALLEL)
  RunMode run_mode = 5 [(google.api.field_behavior) = OPTIONAL];

  // Overall state of the migration operation
  State state = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Overall status message for the operation
  string message = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Migration plan configuration
  MigrationPlan migration_plan = 8 [(google.api.field_behavior) = OPTIONAL];

  // Metadata fields
  uint64 organization_id = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
  uint64 project_id = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Timestamps
  google.protobuf.Timestamp create_time = 100 [(google.api.field_behavior) = OUTPUT_ONLY];
  google.protobuf.Timestamp update_time = 101 [(google.api.field_behavior) = OUTPUT_ONLY];
  optional google.protobuf.Timestamp delete_time = 102 [(google.api.field_behavior) = OUTPUT_ONLY];

  /**
   * MigrationTidbGroup represents a pair of TiDB groups to be migrated.
   */
  message MigrationTidbGroup {
    // ID of the source TiDB group
    string source_tidb_group_id = 1 [(google.api.field_behavior) = REQUIRED];

    // ID of the target TiDB group
    string target_tidb_group_id = 2 [(google.api.field_behavior) = REQUIRED];

    // State of this specific migration pair
    State state = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Last status message for this pair
    string message = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Timestamp when this group migration started
    optional google.protobuf.Timestamp start_time = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Timestamp when this group migration completed
    optional google.protobuf.Timestamp complete_time = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  /**
   * State represents the current state of a migration operation or group.
   */
  enum State {
    STATE_UNSPECIFIED = 0;
    PENDING = 1; // Operation is queued and waiting to start
    RUNNING = 2; // Operation is currently executing
    SUCCEEDED = 3; // Operation completed successfully
    FAILED = 4; // Operation failed
    CANCELLED = 5; // Operation was cancelled
  }

  /**
   * RunMode defines how the migration operation should be executed.
   * @deprecated This field is deprecated and will be removed in future versions.
   */
  enum RunMode {
    RUN_MODE_UNSPECIFIED = 0;
    PARALLEL = 1; // Execute all group migrations in parallel (default)
    SEQUENTIAL = 2; // Execute group migrations one by one
  }
}

/**
 * MigrationPlan defines the configuration for a private link service migration operation.
 */
message MigrationPlan {
  // If true, the private link service for the source TiDB group will not be recreated (default: false)
  bool disable_recreate_private_link_service_for_source_tidb_group = 1 [(google.api.field_behavior) = OPTIONAL];

  // Maximum time to wait for the migration to complete (in seconds)
  // If not set, uses the default timeout
  optional int32 timeout_seconds = 2 [(google.api.field_behavior) = OPTIONAL];
}

/**
 * Request to create a new private link service migration operation.
 */
message CreatePrivateLinkServiceMigrationRequest {
  // The migration operation to create
  PrivateLinkServiceMigration migration = 1 [(google.api.field_behavior) = REQUIRED];

  // If true, only validates the request and returns INVALID_ARGUMENT on failure,
  // without creating or starting the operation
  bool validate_only = 2 [(google.api.field_behavior) = OPTIONAL];
}

/**
 * Request to get a specific private link service migration operation.
 */
message GetPrivateLinkServiceMigrationRequest {
  // ID of the migration operation to retrieve
  uint64 id = 1 [(google.api.field_behavior) = REQUIRED];

  // Service plan of the target cluster. Unique identifier for the private link service migration: target_service_plan + id.
  tidb_cloud_open_api.common.v1beta1.ServicePlan target_service_plan = 2 [(google.api.field_behavior) = REQUIRED];
}

/**
 * Request to list private link service migration operations with filtering and pagination.
 */
message ListPrivateLinkServiceMigrationsRequest {
  // Filter by source cluster ID
  uint64 source_cluster_id = 1 [(google.api.field_behavior) = OPTIONAL];
  uint64 target_cluster_id = 2 [(google.api.field_behavior) = OPTIONAL];

  // Service plan of the target cluster. Unique identifier for the private link service migration: target_service_plan + id.
  tidb_cloud_open_api.common.v1beta1.ServicePlan target_service_plan = 8 [(google.api.field_behavior) = REQUIRED];

  // Filter by organization ID
  uint64 organization_id = 3 [(google.api.field_behavior) = OPTIONAL];

  // Filter by project ID
  uint64 project_id = 4 [(google.api.field_behavior) = OPTIONAL];

  // Filter by operation state
  repeated PrivateLinkServiceMigration.State states = 5 [(google.api.field_behavior) = OPTIONAL];

  // Filter by creation time range
  optional google.protobuf.Timestamp create_time_from = 6 [(google.api.field_behavior) = OPTIONAL];
  optional google.protobuf.Timestamp create_time_to = 7 [(google.api.field_behavior) = OPTIONAL];

  // The maximum number of private link service migration operations to return in each response.
  // The server may return fewer than this at its discretion.
  // If no value is specified, a default value of 100 will be used.
  uint32 page_size = 100 [(google.api.field_behavior) = OPTIONAL];
  uint32 page = 101 [(google.api.field_behavior) = OPTIONAL];
}

/**
 * Response containing a list of private link service migration operations.
 */
message ListPrivateLinkServiceMigrationsResponse {
  // List of migration operations
  repeated PrivateLinkServiceMigration migrations = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

/**
 * Request to cancel a private link service migration operation.
 */
message CancelPrivateLinkServiceMigrationRequest {
  // ID of the migration operation to cancel
  uint64 id = 1 [(google.api.field_behavior) = REQUIRED];

  // Service plan of the target cluster. Unique identifier for the private link service migration: target_service_plan + id.
  tidb_cloud_open_api.common.v1beta1.ServicePlan target_service_plan = 2 [(google.api.field_behavior) = REQUIRED];
}