doc(ydbcp): add comments to proto files

pkg/proto/ydbcp/v1alpha1/backup.proto

@@ -24,29 +24,49 @@ message Backup {
         RUNNING = 6;
         DELETING = 7;
     }
+    // Unique identifier for the backup.
     string id = 1;
+    // An identifier of an external resource which holds the record about the backup
+    // (it can be the container id where the database is located).
     string container_id = 2;
+    // Name of the database for which the backup was created.
     string database_name = 3;
+    // GRPC endpoint of the database.
     string database_endpoint = 4;
+    // S3 location where the backup is stored.
     S3Location location = 5;
+    // Audit information for the backup.
     AuditInfo audit = 6;
+    // Size of the backup in bytes.
     int64 size = 7;
+    // Current status of the backup.
     Status status = 8;
+    // Message associated with the backup status.
     string message = 9;
+    // Timestamp when the backup will expire.
     google.protobuf.Timestamp expire_at = 10;
+    // Unique identifier for the schedule that initiated the backup.
     string schedule_id = 11;
-    repeated string source_paths = 12;
+    // List of source paths included in the backup (empty list means backup of root directory).
+    repeated string source_paths = 12;  // [(size) = "<=256"];
 }
 
 message S3Location {
+    // S3 endpoint.
     string endpoint = 1;
+    // S3 bucket name.
     string bucket = 2;
+    // S3 region.
     string region = 3;
+    // Path prefix in the S3 bucket.
     string path_prefix = 4;
 }
 
 message AuditInfo {
+    // Creator of the backup, YDBCP receives this info from the IAM.
     string creator = 1;
+    // Timestamp when the TakeBackup operation was created.
     google.protobuf.Timestamp created_at = 2;
+    // Timestamp when the TakeBackup operation was completed.
     google.protobuf.Timestamp completed_at = 3;
-}
+}

pkg/proto/ydbcp/v1alpha1/backup_schedule.proto

@@ -9,19 +9,30 @@ import "google/protobuf/timestamp.proto";
 
 
 message BackupSchedulePattern {
+    // Crontab expression defining the schedule.
     string crontab = 1;
 }
 
 message BackupScheduleSettings {
+    // Pattern for scheduling backups.
     BackupSchedulePattern schedule_pattern = 1;
+    // Time-to-live for the backups created by this schedule.
     google.protobuf.Duration ttl = 2;
+    // Recovery point objective duration (maximum length of time permitted, that data can be restored).
     google.protobuf.Duration recovery_point_objective = 3;
 }
 
 message ScheduledBackupInfo {
+    // Unique identifier for the backup.
     string backup_id = 1;
+    // Current recovery point
+    // (the datetime at which the last successful backup has been taken).
     google.protobuf.Timestamp recovery_point = 2;
+    // Margin interval for the last backup's rpo
+    // (how much time was left to break the rpo at the moment when the last backup completed,
+    // negative means is has been broken).
     google.protobuf.Duration last_backup_rpo_margin_interval = 3;
+    // Margin ratio for the last backup's rpo (the same as the previous as a share of the rpo).
     double last_backup_rpo_margin_ratio = 4;
 }
 
@@ -33,22 +44,29 @@ message BackupSchedule {
         DELETED = 3;
     }
 
-    //backup settings
+    // Unique identifier for the backup schedule.
     string id = 1;
+    // An identifier of an external resource which holds the record about the backup
+    // (it can be the container id where the database is located).
     string container_id = 2;
+    // Name of the database associated with the backup schedule.
     string database_name = 3;
+    // GRPC endpoint of the database.
     string endpoint = 4;
+    // List of source paths included in the backup (empty list means backup of root directory).
     repeated string source_paths = 5;  // [(size) = "<=256"];
+    // List of source paths to exclude from the backup.
     repeated string source_paths_to_exclude = 6;  // [(size) = "<=256"];
-
+    // Audit information for the backup schedule.
     ydbcp.v1alpha1.AuditInfo audit = 7;
-
+    // Name of the backup schedule.
     string schedule_name = 8;
+    // Current status of the backup schedule.
     Status status = 9;
-
+    // Settings for the backup schedule.
     BackupScheduleSettings schedule_settings = 10;
-
+    // Timestamp for the next scheduled backup.
     google.protobuf.Timestamp next_launch = 11;
-
+    // Information about the last successful backup.
     ScheduledBackupInfo last_successful_backup_info = 12;
-}
+}

pkg/proto/ydbcp/v1alpha1/backup_schedule_service.proto

@@ -5,68 +5,104 @@ option go_package = "github.com/ydb-platform/ydbcp/pkg/proto/ydbcp/v1alpha1;ydbc
 
 import "ydbcp/v1alpha1/backup_schedule.proto";
 
+// Service for managing backup schedules.
+// YDB auth token can be passed via GRPC request metadata using authorization header.
 service BackupScheduleService {
+    // Creates a new backup schedule.
+    // Required YDB permissions: `ydb.databases.backup`
     rpc CreateBackupSchedule (CreateBackupScheduleRequest) returns (BackupSchedule);
+
+    // Updates an existing backup schedule by its ID.
+    // Required YDB permissions: `ydb.databases.backup`
     rpc UpdateBackupSchedule (UpdateBackupScheduleRequest) returns (BackupSchedule);
+
+    // Retrieves a backup schedule by its ID.
+    // Required YDB permissions: `ydb.databases.get`
     rpc GetBackupSchedule (GetBackupScheduleRequest) returns (BackupSchedule);
+
+    // Lists all backup schedules for a specified container.
+    // Required YDB permissions: `ydb.databases.list`
     rpc ListBackupSchedules (ListBackupSchedulesRequest) returns (ListBackupSchedulesResponse);
+
+    // Toggles the state of a backup schedule by its ID.
+    // Required YDB permissions: `ydb.databases.backup`
     rpc ToggleBackupSchedule (ToggleBackupScheduleRequest) returns (BackupSchedule);
+
+    // Deletes a backup schedule by its ID.
+    // Required YDB permissions: `ydb.databases.backup`
     rpc DeleteBackupSchedule (DeleteBackupScheduleRequest) returns (BackupSchedule);
 }
 
 message CreateBackupScheduleRequest {
-    //fields of MakeBackupRequest to schedule
+    // An identifier of an external resource which holds the record about the backup
+    // (it can be the container id where the database is located).
     string container_id = 1;
+    // The name of the database for which schedule will be created.
     string database_name = 2;
+    // GRPC endpoint of the database.
     string endpoint = 3;
+    // List of source paths included in the backup (empty list means backup of root directory).
     repeated string source_paths = 4;  // [(size) = "<=256"];
+    // List of source paths to exclude from the backup.
     repeated string source_paths_to_exclude = 5;  // [(size) = "<=256"];
-
+    // The name of the backup schedule.
     string schedule_name = 6;
+    // The settings for the backup schedule.
     BackupScheduleSettings schedule_settings = 7;
 }
 
 message UpdateBackupScheduleRequest {
+    // The ID of the backup schedule to update.
     string id = 1;
-    //fields of MakeBackupRequest to schedule
+    // List of source paths included in the backup (empty list means backup of root directory).
     repeated string source_paths = 2;  // [(size) = "<=256"];
+    // List of source paths to exclude from the backup.
     repeated string source_paths_to_exclude = 3;  // [(size) = "<=256"];
-
+    // The name of the backup schedule.
     string schedule_name = 4;
+    // The settings for the backup schedule.
     BackupScheduleSettings schedule_settings = 5;
 }
 
 
 message ListBackupSchedulesRequest {
+    // The ID of the container for which to list backup schedules.
     string container_id = 1;
+    // A mask to filter operations by database name using LIKE operator for pattern matching (ex.: "your_db_prefix%").
+    // For more information about LIKE operator, see the https://ydb.tech/docs/en/yql/reference/syntax/expressions#check-match.
     string database_name_mask = 2;
+    // A list of statuses to filter backup schedules.
     repeated BackupSchedule.Status display_status = 3;
-
     // The maximum number of results per page that should be returned. If the number of available
     // results is larger than `page_size`, the service returns a `next_page_token` that can be used
     // to get the next page of results in subsequent ListBackupSchedules requests.
     // Acceptable values are 0 to 1000, inclusive. Default value: 100.
-    uint32 page_size = 1000; // [(value) = "0-1000"];
-
+    uint32 page_size = 1000;
     // Page token. Set `page_token` to the `next_page_token` returned by a previous ListBackups
     // request to get the next page of results.
-    string page_token = 1001; // [(length) = "<=100"];
+    string page_token = 1001;
 }
 
 message ListBackupSchedulesResponse {
+    // The list of backup schedules.
     repeated BackupSchedule schedules = 1;
+    // The token for the next page of results.
     string next_page_token = 2;
 }
 
 message GetBackupScheduleRequest {
+    // The ID of the backup schedule to retrieve.
     string id = 1;
 }
 
 message ToggleBackupScheduleRequest {
+    // The ID of the backup schedule to toggle.
     string id = 1;
+    // The new state of the backup schedule (true - active, false - inactive).
     bool active_state = 2;
 }
 
 message DeleteBackupScheduleRequest {
+    // The ID of the backup schedule to delete.
     string id = 1;
-}
+}

pkg/proto/ydbcp/v1alpha1/backup_service.proto

@@ -7,31 +7,50 @@ import "ydbcp/v1alpha1/backup.proto";
 import "ydbcp/v1alpha1/operation.proto";
 import "google/protobuf/duration.proto";
 
-message ListBackupsOrder {
-    BackupField field = 1;
-    bool desc = 2;
-}
-
-// A set of methods for managing backups;.
+// A set of methods for managing backups.
+// YDB auth token can be passed via GRPC request metadata using authorization header.
 service BackupService {
+    // Returns the list of backups for the specified container.
+    // Required YDB permissions: `ydb.databases.list`
     rpc ListBackups(ListBackupsRequest) returns (ListBackupsResponse);
 
     // Returns the specified backup.
-    rpc GetBackup (GetBackupRequest) returns (Backup);
+    // Required YDB permissions: `ydb.databases.get`
+    rpc GetBackup(GetBackupRequest) returns (Backup);
 
+    // Creates a backup of the specified database.
+    // Required YDB permissions: `ydb.databases.backup`
     rpc MakeBackup(MakeBackupRequest) returns (Operation);
 
+    // Deletes the specified backup and returns DeleteBackup operation.
+    // Required YDB permissions: `ydb.databases.backup`
     rpc DeleteBackup(DeleteBackupRequest) returns (Operation);
 
+    // Restores the specified backup and returns MakeRestore operation.
+    // Required YDB permissions: `ydb.tables.create`
     rpc MakeRestore(MakeRestoreRequest) returns (Operation);
 
+    // Updates the TTL of the specified backup.
+    // Required YDB permissions: `ydb.databases.backup`
     rpc UpdateBackupTtl(UpdateBackupTtlRequest) returns (Backup);
 }
 
+message ListBackupsOrder {
+    // The field by which to order the backups.
+    BackupField field = 1;
+    // The order for the backups (true - descending, false - ascending).
+    bool desc = 2;
+}
+
 message ListBackupsRequest {
+    // The ID of the container for which to list backups.
     string container_id = 1;
+    // A mask to filter operations by database name using LIKE operator for pattern matching (ex.: "your_db_prefix%").
+    // For more information about LIKE operator, see the https://ydb.tech/docs/en/yql/reference/syntax/expressions#check-match.
     string database_name_mask = 2;
+    // A list of statuses to filter backups.
     repeated Backup.Status display_status = 3;
+    // The order in which to list the backups.
     ListBackupsOrder order = 4;
 
     // The maximum number of results per page that should be returned. If the number of available
@@ -47,40 +66,57 @@ message ListBackupsRequest {
 }
 
 message ListBackupsResponse {
+    // The list of backups.
     repeated Backup backups = 1;
+    // The token for the next page of results.
     string next_page_token = 2;
 }
 
 message GetBackupRequest {
+    // The ID of the backup to retrieve.
     string id = 1;
 }
 
 message MakeBackupRequest {
+    // An identifier of an external resource which holds the record about the backup
+    // (it can be the container id where the source database is located).
     string container_id = 1;
+    // The name of the database for which the backup will be created.
     string database_name = 2;
+    // GRPC endpoint of the database.
     string database_endpoint = 3;
-    // Full path to a table or directory. Empty source_paths means backup of root directory.
+    // List of source paths included in the backup (empty list means backup of root directory).
     repeated string source_paths = 4;  // [(size) = "<=256"];
     // Regexp for paths excluded from backup.
     repeated string source_paths_to_exclude = 5;  // [(size) = "<=256"];
+    // The time-to-live for the backup.
     google.protobuf.Duration ttl = 6;
 }
 
 message DeleteBackupRequest {
+    // The ID of the backup to delete.
     string backup_id = 1;
 }
 
 message MakeRestoreRequest {
+    // An identifier of an external resource which holds the record about the backup
+    // (it can be the container id where the target database is located).
     string container_id = 1;
+    // The ID of the backup to restore.
     string backup_id = 2;
+    // The name of the database to restore.
     string database_name = 3;
+    // GRPC endpoint of the database.
     string database_endpoint = 4;
+    // The prefix for the destination path.
     string destination_prefix = 5;
     // Paths to s3 objects to restore.
     repeated string source_paths = 6;
 }
 
 message UpdateBackupTtlRequest {
+    // The ID of the backup to update.
     string backup_id = 1;
+    // The new time-to-live for the backup.
     google.protobuf.Duration ttl = 2;
-}
+}

pkg/proto/ydbcp/v1alpha1/operation.proto

@@ -18,20 +18,38 @@ message Operation {
         START_CANCELLING = 6;
         RUNNING = 7;
     }
+
+    // Unique identifier for the operation.
     string id = 1;
+    // An identifier of an external resource which holds the record about the operation
+    // (it can be the container id where the database is located).
     string container_id = 2;
+    // Type of the operation (TB - TakeBackup, RB - RestoreBackup, DB - DeleteBackup, TBWR - TakeBackupWithRetries).
     string type = 3;
+    // Name of the database associated with the operation.
     string database_name = 4;
+    // GRPC endpoint of the database.
     string database_endpoint = 5;
+    // Identifier for the YDB server export/import operation.
     string ydb_server_operation_id = 6;
+    // Identifier for the backup associated with the operation.
     string backup_id = 7;
+    // List of source paths included in the backup (only for MakeBackup operation).
     repeated string source_paths = 8;  // [(size) = "<=256"];
+    // List of source paths to exclude from the backup (only for MakeBackup operation).
     repeated string source_paths_to_exclude = 9;  // [(size) = "<=256"];
+    // List of paths included in restore (only for MakeRestore operation).
     repeated string restore_paths = 10;  // [(size) = "<=256"];
+    // Audit information for the operation.
     AuditInfo audit = 11;
+    // Current status of the operation.
     Status status = 12;
+    // Message associated with the operation status.
     string message = 13;
+    // Timestamp when the operation was last updated.
     google.protobuf.Timestamp updated_at = 14;
+    // Identifier for the parent operation, if exist.
     string parent_operation_id = 15;
+    // Retry configuration for the operation.
     RetryConfig retry_config = 16;
-}
+}