// Copyright 2026 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.lustre.v1;

import "google/api/field_behavior.proto";
import "google/api/field_info.proto";
import "google/api/resource.proto";
import "google/cloud/lustre/v1/transfer.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option go_package = "cloud.google.com/go/lustre/apiv1/lustrepb;lustrepb";
option java_multiple_files = true;
option java_outer_classname = "MirrorProto";
option java_package = "com.google.cloud.lustre.v1";

// Represents a Cloud Storage mirror.
message Mirror {
  option (google.api.resource) = {
    type: "lustre.googleapis.com/Mirror"
    pattern: "projects/{project}/locations/{location}/instances/{instance}/mirrors/{mirror}"
    plural: "mirrors"
    singular: "mirror"
  };

  // Represents the direction of the mirror.
  // This enum expects to be extended in future with new mirror types.
  enum Direction {
    // Invalid value.
    DIRECTION_UNSPECIFIED = 0;

    // Mirror from Cloud Storage to Lustre.
    FROM_CLOUD_STORAGE = 1;
  }

  // State of the mirror.
  enum State {
    // State is unspecified.
    STATE_UNSPECIFIED = 0;

    // The mirror resource is being created.
    CREATING = 1;

    // The initial sync is copying existing objects from Cloud Storage.
    INITIAL_SYNC = 2;

    // The mirror is being deleted.
    DELETING = 3;

    // The mirror is synchronizing changes as they occur.
    ACTIVE = 4;

    // Synchronization is paused because the file system is close to capacity.
    SUSPENDED = 5;
  }

  // Identifier. Name of the mirror.
  // Format:
  // `projects/{project}/locations/{location}/instances/{instance}/mirrors/{mirror}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Required. Immutable. The URI to a Cloud Storage bucket, or a path within a
  // bucket, using the format `gs://{BUCKET_NAME}/{OPTIONAL_PATH}/`. If a path
  // inside the bucket is specified, it must end with a forward slash (`/`).
  GcsPath gcs_path = 3 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Required. Immutable. The Managed Lustre directory to mirror to. Must be an
  // absolute path starting with `/`, for example `/data` or `/data/subdir`.
  // Defaults to the root directory, `/`. If the specified directory doesn't
  // exist, it is created.
  LustrePath lustre_path = 4 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Required. Immutable. Represents the direction of the mirror.
  Direction direction = 5 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.field_behavior) = IMMUTABLE
  ];

  // Optional. If `true`, files are not deleted from Managed Lustre when the
  // source files are deleted from Cloud Storage. Default is `false`.
  bool deleted_files_retained = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Description of the mirror.
  string description = 7 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Labels to apply to the mirror.
  map<string, string> labels = 8 [(google.api.field_behavior) = OPTIONAL];

  // Output only. [Output only] Create time stamp.
  google.protobuf.Timestamp create_time = 9
      [(google.api.field_behavior) = OUTPUT_ONLY];

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

  // Output only. Unique ID of the resource.
  string uid = 11 [
    (google.api.field_info).format = UUID4,
    (google.api.field_behavior) = OUTPUT_ONLY
  ];

  // Output only. [Output only] The current state of the mirror.
  State state = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Request for CreateMirror.
message CreateMirrorRequest {
  // Required. Parent instance resource where the mirror will be created, in the
  // format: `projects/{project}/locations/{location}/instances/{instance}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "lustre.googleapis.com/Mirror"
    }
  ];

  // Required. The ID to use for the mirror.
  //
  // * Must contain only lowercase letters, numbers, and hyphens.
  // * Must start with a letter.
  // * Must be between 1-63 characters.
  // * Must end with a number or a letter.
  //
  // The ID cannot be changed after the mirror is created.
  string mirror_id = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. The mirror to create.
  Mirror mirror = 3 [(google.api.field_behavior) = REQUIRED];

  // Optional. The unique ID to identify requests. Specify a unique request ID
  // so that if you must retry your request, the server will know to ignore
  // the request if it has already been completed. The server guarantees that a
  // request doesn't result in creation of duplicate mirrors for at least 60
  // minutes.
  //
  // For example, consider a situation where you make an initial request and the
  // request times out. If you make the request again with the same request
  // ID, the server can check if original operation with the same request ID
  // was received, and if so, will ignore the second request. This prevents
  // clients from accidentally creating duplicate mirrors.
  //
  // The request ID must be a valid UUID version 4 with the exception that zero
  // UUID is not supported (`00000000-0000-0000-0000-000000000000`).
  // This request is only idempotent if a `request_id` is provided.
  string request_id = 4 [
    (google.api.field_info).format = UUID4,
    (google.api.field_behavior) = OPTIONAL
  ];
}

// Request for UpdateMirror.
message UpdateMirrorRequest {
  // Required. Mirror to update. The mirror's `name` field is used to identify
  // the mirror to update, in the format:
  // `projects/{project}/locations/{location}/instances/{instance}/mirrors/{mirror}`
  Mirror mirror = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Fields specified in the update_mask are relative to the resource,
  // not the full request. A field will be overwritten if it is in the mask. If
  // no mask is provided then all fields present in the request are overwritten.
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The unique ID to identify requests. Specify a unique request ID
  // so that if you must retry your request, the server will know to ignore
  // the request if it has already been completed. The server guarantees that a
  // request doesn't result in the same update request being executed for at
  // least 60 minutes.
  //
  // For example, consider a situation where you make an initial request and the
  // request times out. If you make the request again with the same request
  // ID, the server can check if original operation with the same request ID
  // was received, and if so, will ignore the second request.
  //
  // The request ID must be a valid UUID version 4 with the exception that zero
  // UUID is not supported (`00000000-0000-0000-0000-000000000000`).
  // This request is only idempotent if a `request_id` is provided.
  string request_id = 3 [
    (google.api.field_info).format = UUID4,
    (google.api.field_behavior) = OPTIONAL
  ];
}

// Request for DeleteMirror.
message DeleteMirrorRequest {
  // Required. Name of the mirror to delete, in the format:
  // `projects/{project}/locations/{location}/instances/{instance}/mirrors/{mirror}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "lustre.googleapis.com/Mirror" }
  ];

  // Optional. The unique ID to identify requests. Specify a unique request ID
  // so that if you must retry your request, the server will know to ignore
  // the request if it has already been completed. The server guarantees that a
  // request doesn't result in the same delete request being executed for at
  // least 60 minutes.
  //
  // For example, consider a situation where you make an initial request and the
  // request times out. If you make the request again with the same request
  // ID, the server can check if original operation with the same request ID
  // was received, and if so, will ignore the second request.
  //
  // The request ID must be a valid UUID version 4 with the exception that zero
  // UUID is not supported (`00000000-0000-0000-0000-000000000000`).
  // This request is only idempotent if a `request_id` is provided.
  string request_id = 2 [
    (google.api.field_info).format = UUID4,
    (google.api.field_behavior) = OPTIONAL
  ];
}

// Request for GetMirror.
message GetMirrorRequest {
  // Required. Name of the mirror to retrieve, in the format:
  // `projects/{project}/locations/{location}/instances/{instance}/mirrors/{mirror}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = { type: "lustre.googleapis.com/Mirror" }
  ];
}

// Request for ListMirrors.
message ListMirrorsRequest {
  // Required. Parent instance resource where the mirrors will be listed, in the
  // format: `projects/{project}/locations/{location}/instances/{instance}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "lustre.googleapis.com/Mirror"
    }
  ];

  // Optional. Requested page size. The server might return fewer items than
  // requested. If unspecified, the default page size is 10. The maximum value
  // is 1000.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A page token, received from a previous `ListMirrors` call.
  // Provide this to retrieve the subsequent page.
  // When paginating, all other parameters provided to `ListMirrors` must match
  // the call that provided the page token.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Desired order of results.
  string order_by = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Filtering results.
  string filter = 5 [(google.api.field_behavior) = OPTIONAL];
}

// Response for ListMirrors.
message ListMirrorsResponse {
  // List of mirrors on the instance.
  repeated Mirror mirrors = 1;

  // A token identifying a page of results the server should return.
  string next_page_token = 2;

  // Unordered list. Locations that could not be reached.
  repeated string unreachable = 3
      [(google.api.field_behavior) = UNORDERED_LIST];
}

// Metadata of the create mirror operation.
message CreateMirrorMetadata {
  // Data transfer operation metadata.
  TransferOperationMetadata operation_metadata = 1;

  // Output only. The time the operation was created.
  google.protobuf.Timestamp create_time = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time the operation finished running.
  google.protobuf.Timestamp end_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Server-defined resource path for the target of the operation.
  string target = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Name of the verb executed by the operation.
  string verb = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Human-readable status of the operation, if any.
  string status_message = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Identifies whether the user has requested cancellation
  // of the operation. Operations that have successfully been cancelled
  // have
  // [google.longrunning.Operation.error][google.longrunning.Operation.error]
  // value with a [google.rpc.Status.code][google.rpc.Status.code] of 1,
  // corresponding to `Code.CANCELLED`.
  bool requested_cancellation = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. API version used to start the operation.
  string api_version = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
}