comet_backup_ruby_sdk 2.8.0 → 2.10.0

data/lib/comet/models/osinfo.rb

@@ -10,17 +10,31 @@ require 'json'
 module Comet
 
   # OSInfo is a typed class wrapper around the underlying Comet Server API data structure.
+  # OSInfo represents the common set of version information between all operating systems
   class OSInfo
 
+    # The primary version number (e.g. on Windows: 1703 / 2009, on Linux: 20.04 / 22.04)
     # @type [String] version
     attr_accessor :version
 
+    # The primary presentation name (e.g. "Windows 10 Pro", "debian", "Synology DSM")
     # @type [String] distribution
     attr_accessor :distribution
 
+    # The detailed build number (e.g. 19043)
     # @type [String] build
     attr_accessor :build
 
+    # The GOOS value
+    # This field is available in Comet 23.6.0 and later.
+    # @type [String] os
+    attr_accessor :os
+
+    # The GOARCH value
+    # This field is available in Comet 23.6.0 and later.
+    # @type [String] arch
+    attr_accessor :arch
+
     # @type [Hash] Hidden storage to preserve future properties for non-destructive roundtrip operations
     attr_accessor :unknown_json_fields
 
@@ -32,6 +46,8 @@ module Comet
       @version = ''
       @distribution = ''
       @build = ''
+      @os = ''
+      @arch = ''
       @unknown_json_fields = {}
     end
 
@@ -60,6 +76,14 @@ module Comet
           raise TypeError, "'v' expected String, got #{v.class}" unless v.is_a? String
 
           @build = v
+        when 'os'
+          raise TypeError, "'v' expected String, got #{v.class}" unless v.is_a? String
+
+          @os = v
+        when 'arch'
+          raise TypeError, "'v' expected String, got #{v.class}" unless v.is_a? String
+
+          @arch = v
         else
           @unknown_json_fields[k] = v
         end
@@ -78,6 +102,12 @@ module Comet
       unless @build.nil?
         ret['build'] = @build
       end
+      unless @os.nil?
+        ret['os'] = @os
+      end
+      unless @arch.nil?
+        ret['arch'] = @arch
+      end
       @unknown_json_fields.each do |k, v|
         ret[k] = v
       end

data/lib/comet/models/partition.rb

@@ -15,6 +15,7 @@ module Comet
     # @type [String] device_name
     attr_accessor :device_name
 
+    # The name of the filesystem used on this partition (e.g. "NTFS")
     # @type [String] filesystem
     attr_accessor :filesystem
 
@@ -30,12 +31,16 @@ module Comet
     # @type [Array<String>] mount_points
     attr_accessor :mount_points
 
+    # Bytes. The partition's offset within the DeviceName. It will be zero if this partition has a
+    # direct DeviceName handle.
     # @type [Number] read_offset
     attr_accessor :read_offset
 
+    # Bytes
     # @type [Number] size
     attr_accessor :size
 
+    # Bytes. Only present for supported filesystems that are currently mounted by the OS
     # @type [Number] used_size
     attr_accessor :used_size
 

data/lib/comet/models/private_branding_properties.rb

@@ -12,6 +12,7 @@ module Comet
   # PrivateBrandingProperties is a typed class wrapper around the underlying Comet Server API data structure.
   class PrivateBrandingProperties
 
+    # One of the CLIENTBRANDINGBUILD_ constants
     # @type [Number] build_mode
     attr_accessor :build_mode
 
@@ -39,12 +40,14 @@ module Comet
     # @type [String] package_identifier
     attr_accessor :package_identifier
 
+    # One of the WINDOWSCODESIGN_METHOD_ constants
     # @type [Number] windows_code_sign_method
     attr_accessor :windows_code_sign_method
 
     # @type [String] windows_code_sign_pkcs12file_path
     attr_accessor :windows_code_sign_pkcs12file_path
 
+    # One of the ENCRYPTIONMETHOD_ constants
     # @type [Number] windows_code_sign_pkcs12password_format
     attr_accessor :windows_code_sign_pkcs12password_format
 
@@ -64,6 +67,7 @@ module Comet
     # @type [String] windows_code_sign_pkcs11key_id
     attr_accessor :windows_code_sign_pkcs11key_id
 
+    # One of the ENCRYPTIONMETHOD_ constants
     # @type [Number] windows_code_sign_pkcs11password_format
     attr_accessor :windows_code_sign_pkcs11password_format
 
@@ -79,6 +83,7 @@ module Comet
     # @type [String] windows_code_sign_azure_app_id
     attr_accessor :windows_code_sign_azure_app_id
 
+    # One of the ENCRYPTIONMETHOD_ constants
     # @type [Number] windows_code_sign_azure_app_secret_format
     attr_accessor :windows_code_sign_azure_app_secret_format
 

data/lib/comet/models/psaconfig.rb

@@ -12,18 +12,22 @@ module Comet
   # PSAConfig is a typed class wrapper around the underlying Comet Server API data structure.
   class PSAConfig
 
+    # For PSA_TYPE_GRADIENT. Defaults to enabled
     # @type [Boolean] alerts_disabled
     attr_accessor :alerts_disabled
 
     # @type [Hash{String => String}] custom_headers
     attr_accessor :custom_headers
 
+    # Specified credentials for the target PSA
     # @type [String] partner_key
     attr_accessor :partner_key
 
+    # One of the PSA_TYPE_ constants
     # @type [Number] type
     attr_accessor :type
 
+    # For PSA_TYPE_GENERIC
     # @type [String] url
     attr_accessor :url
 

data/lib/comet/models/restore_job_advanced_options.rb

@@ -12,6 +12,7 @@ module Comet
   # RestoreJobAdvancedOptions is a typed class wrapper around the underlying Comet Server API data structure.
   class RestoreJobAdvancedOptions
 
+    # One of the RESTORETYPE_ constants
     # @type [Number] type
     attr_accessor :type
 
@@ -40,6 +41,16 @@ module Comet
     # @type [Number] archive_format
     attr_accessor :archive_format
 
+    # Corresponds to the "Allow partial file restores (zero-out unrecoverable data)" option
+    # This field is available in Comet 23.6.4 and later.
+    # @type [Boolean] skip_unreadable_chunks
+    attr_accessor :skip_unreadable_chunks
+
+    # Corresponds to the "Prefer temporary files instead of RAM (slower)" option
+    # This field is available in Comet 23.6.4 and later.
+    # @type [Boolean] on_disk_indexes_key
+    attr_accessor :on_disk_indexes_key
+
     # For RESTORETYPE_OFFICE365_CLOUD.
     # @type [Comet::Office365Credential] office_365credential
     attr_accessor :office_365credential
@@ -150,6 +161,10 @@ module Comet
           raise TypeError, "'v' expected Numeric, got #{v.class}" unless v.is_a? Numeric
 
           @archive_format = v
+        when 'SkipUnreadableChunks'
+          @skip_unreadable_chunks = v
+        when 'OnDiskIndexesKey'
+          @on_disk_indexes_key = v
         when 'Office365Credential'
           @office_365credential = Comet::Office365Credential.new
           @office_365credential.from_hash(v)
@@ -204,6 +219,8 @@ module Comet
       ret['DestPath'] = @dest_path
       ret['ExactDestPaths'] = @exact_dest_paths
       ret['ArchiveFormat'] = @archive_format
+      ret['SkipUnreadableChunks'] = @skip_unreadable_chunks
+      ret['OnDiskIndexesKey'] = @on_disk_indexes_key
       unless @office_365credential.nil?
         ret['Office365Credential'] = @office_365credential
       end

data/lib/comet/models/retention_range.rb

@@ -10,11 +10,15 @@ require 'json'
 module Comet
 
   # RetentionRange is a typed class wrapper around the underlying Comet Server API data structure.
+  # The Type field controls which fields of this data type are used. For additional information, see
+# the notes on the RETENTIONRANGE_ constants.
   class RetentionRange
 
+    # One of the RETENTIONRANGE_ constants
     # @type [Number] type
     attr_accessor :type
 
+    # Unix timestamp, in seconds. Used by RETENTIONRANGE_NEWER_THAN_X.
     # @type [Number] timestamp
     attr_accessor :timestamp
 
@@ -34,6 +38,10 @@ module Comet
     # @type [Number] week_offset
     attr_accessor :week_offset
 
+    # 1: 1st, 31: 31st
+    # Prior to Comet version 23.6.2, 31 was treated as 30.
+    # For months that do not have a day equal to the specified offset, no backup will be retained.
+    # For example, if the offset is set to 30, no backup will be kept for February.
     # @type [Number] month_offset
     attr_accessor :month_offset
 

data/lib/comet/models/search_clause.rb

@@ -12,18 +12,34 @@ module Comet
   # SearchClause is a typed class wrapper around the underlying Comet Server API data structure.
   class SearchClause
 
+    # One of the SEARCHCLAUSE_ constants (e.g. empty-string if this is a rule, or "and"/"or" if there
+    # are ClauseChildren)
     # @type [String] clause_type
     attr_accessor :clause_type
 
+    # The field name to search. Check the specific API for more information about which fields are
+    # available for searching. For use with ClauseType = SEARCHCLAUSE_RULE.
     # @type [String] rule_field
     attr_accessor :rule_field
 
+    # One of the SEARCHOPERATOR_ constants. The operator must match the type of the particular field.
+    # For use with ClauseType = SEARCHCLAUSE_RULE.
     # @type [String] rule_operator
     attr_accessor :rule_operator
 
+    # The value to compare the field against.
+    # - If the field is a string, any string is permissable.
+    # - If the field is an integer, the integer should be cast to a base-10 string. There is currently
+    # no support for fractional or floating-point numbers.
+    # - If the field is a boolean, the following values can be used for true ("1", "t", "T", "true",
+    # "TRUE", "True") and the following values can be used for false ("0", "f", "F", "false", "FALSE",
+    # "False").
+    # For use with ClauseType = SEARCHCLAUSE_RULE.
     # @type [String] rule_value
     attr_accessor :rule_value
 
+    # If ClauseType is not SEARCHCLAUSE_RULE, the child rules will be applied according to the
+    # ClauseType (e.g. "and"/"or")
     # @type [Array<Comet::SearchClause>] clause_children
     attr_accessor :clause_children
 

data/lib/comet/models/search_result_file_info.rb

@@ -10,29 +10,41 @@ require 'json'
 module Comet
 
   # SearchResultFileInfo is a typed class wrapper around the underlying Comet Server API data structure.
+  # SearchResultFileInfo describes a single result entry when searching for files within a Storage
+# Vault snapshot.
   class SearchResultFileInfo
 
+    # Path to the file within the selected snapshot, using forwardslash (/) separators
     # @type [String] path
     attr_accessor :path
 
+    # Filename
     # @type [String] name
     attr_accessor :name
 
+    # One of the STOREDOBJECTTYPE_ constants
     # @type [String] type
     attr_accessor :type
 
     # @type [String] mode
     attr_accessor :mode
 
-    # @type [String] mtime
-    attr_accessor :mtime
+    # Timestamp in RFC3339 format with subsecond precision and time zone offset. See the Golang
+    # time.RFC3339Nano for more information.
+    # @type [String] mod_time
+    attr_accessor :mod_time
 
-    # @type [String] atime
-    attr_accessor :atime
+    # Timestamp in RFC3339 format with subsecond precision and time zone offset. See the Golang
+    # time.RFC3339Nano for more information.
+    # @type [String] access_time
+    attr_accessor :access_time
 
-    # @type [String] ctime
-    attr_accessor :ctime
+    # Timestamp in RFC3339 format with subsecond precision and time zone offset. See the Golang
+    # time.RFC3339Nano for more information.
+    # @type [String] change_time
+    attr_accessor :change_time
 
+    # Bytes
     # @type [Number] size
     attr_accessor :size
 
@@ -48,9 +60,9 @@ module Comet
       @name = ''
       @type = ''
       @mode = ''
-      @mtime = ''
-      @atime = ''
-      @ctime = ''
+      @mod_time = ''
+      @access_time = ''
+      @change_time = ''
       @size = 0
       @unknown_json_fields = {}
     end
@@ -87,15 +99,15 @@ module Comet
         when 'mtime'
           raise TypeError, "'v' expected String, got #{v.class}" unless v.is_a? String
 
-          @mtime = v
+          @mod_time = v
         when 'atime'
           raise TypeError, "'v' expected String, got #{v.class}" unless v.is_a? String
 
-          @atime = v
+          @access_time = v
         when 'ctime'
           raise TypeError, "'v' expected String, got #{v.class}" unless v.is_a? String
 
-          @ctime = v
+          @change_time = v
         when 'size'
           raise TypeError, "'v' expected Numeric, got #{v.class}" unless v.is_a? Numeric
 
@@ -112,11 +124,21 @@ module Comet
       ret['path'] = @path
       ret['name'] = @name
       ret['type'] = @type
-      ret['mode'] = @mode
-      ret['mtime'] = @mtime
-      ret['atime'] = @atime
-      ret['ctime'] = @ctime
-      ret['size'] = @size
+      unless @mode.nil?
+        ret['mode'] = @mode
+      end
+      unless @mod_time.nil?
+        ret['mtime'] = @mod_time
+      end
+      unless @access_time.nil?
+        ret['atime'] = @access_time
+      end
+      unless @change_time.nil?
+        ret['ctime'] = @change_time
+      end
+      unless @size.nil?
+        ret['size'] = @size
+      end
       @unknown_json_fields.each do |k, v|
         ret[k] = v
       end

data/lib/comet/models/self_backup_export_options.rb

@@ -18,12 +18,16 @@ module Comet
     # @type [String] encryption_key
     attr_accessor :encryption_key
 
+    # One of the ENCRYPTIONMETHOD_ constants
     # @type [Number] encryption_key_format
     attr_accessor :encryption_key_format
 
+    # One of the COMPRESS_LVL_ constants
     # @type [Number] compression
     attr_accessor :compression
 
+    # The jobs database is often the largest component of the Server Self-Backup archive. By excluding
+    # it, you could run the Server Self-Backup more often.
     # @type [Boolean] exclude_jobs_db
     attr_accessor :exclude_jobs_db
 

data/lib/comet/models/self_backup_target.rb

@@ -15,6 +15,7 @@ module Comet
     # @type [Array<Comet::ScheduleConfig>] schedule
     attr_accessor :schedule
 
+    # Timezone in IANA format
     # @type [String] schedule_timezone
     attr_accessor :schedule_timezone
 
@@ -27,12 +28,16 @@ module Comet
     # @type [String] encryption_key
     attr_accessor :encryption_key
 
+    # One of the ENCRYPTIONMETHOD_ constants
     # @type [Number] encryption_key_format
     attr_accessor :encryption_key_format
 
+    # One of the COMPRESS_LVL_ constants
     # @type [Number] compression
     attr_accessor :compression
 
+    # The jobs database is often the largest component of the Server Self-Backup archive. By excluding
+    # it, you could run the Server Self-Backup more often.
     # @type [Boolean] exclude_jobs_db
     attr_accessor :exclude_jobs_db
 

data/lib/comet/models/server_config_options.rb

@@ -35,30 +35,36 @@ module Comet
     # @type [Comet::EmailOptions] email
     attr_accessor :email
 
+    # An array of GUIDs that can enable additional early-access functionality
     # @type [Array<String>] experimental_options
     attr_accessor :experimental_options
 
     # @type [Hash{String => Comet::ExternalAuthenticationSource}] external_admin_user_sources
     attr_accessor :external_admin_user_sources
 
+    # The Comet Server can enforce a bandwidth limit based on the target IP address
     # @type [Comet::RatelimitOptions] iprate_limit
     attr_accessor :iprate_limit
 
     # @type [Comet::LicenseOptions] license
     attr_accessor :license
 
+    # Configure ip, port, and SSL settings for this self-hosted Comet Server.
     # @type [Array<Comet::HTTPConnectorOptions>] listen_addresses
     attr_accessor :listen_addresses
 
+    # Tenants
     # @type [Hash{String => Comet::Organization}] organizations
     attr_accessor :organizations
 
     # @type [Array<Comet::PSAConfig>] psaconfigs
     attr_accessor :psaconfigs
 
+    # Automatically create backup zip files of this Comet Server's configuration
     # @type [Comet::SelfBackupOptions] self_backup
     attr_accessor :self_backup
 
+    # Control how long admin accounts can remain logged in to the Comet Server web interface
     # @type [Comet::SessionOptions] session_settings
     attr_accessor :session_settings
 
@@ -68,12 +74,18 @@ module Comet
     # @type [Comet::StorageRoleOptions] storage_role
     attr_accessor :storage_role
 
+    # If true, the X-Forwarded-For header will be trusted for the purposes of IP allowlisting. This
+    # should only be enabled when you explicitly configure Comet Server behind a reverse proxy,
+    # otherwise it could allow malicious users to bypass the IP allowlist.
     # @type [Boolean] trust_xforwarded_for
     attr_accessor :trust_xforwarded_for
 
     # @type [Hash{String => Comet::WebhookOption}] webhook_options
     attr_accessor :webhook_options
 
+    # @type [Hash{String => Comet::FileOption}] audit_file_options
+    attr_accessor :audit_file_options
+
     # @type [Hash] Hidden storage to preserve future properties for non-destructive roundtrip operations
     attr_accessor :unknown_json_fields
 
@@ -100,6 +112,7 @@ module Comet
       @software_build_role = Comet::SoftwareBuildRoleOptions.new
       @storage_role = Comet::StorageRoleOptions.new
       @webhook_options = {}
+      @audit_file_options = {}
       @unknown_json_fields = {}
     end
 
@@ -222,6 +235,16 @@ module Comet
               @webhook_options[k1].from_hash(v1)
             end
           end
+        when 'AuditFileOptions'
+          @audit_file_options = {}
+          if v.nil?
+            @audit_file_options = {}
+          else
+            v.each do |k1, v1|
+              @audit_file_options[k1] = Comet::FileOption.new
+              @audit_file_options[k1].from_hash(v1)
+            end
+          end
         else
           @unknown_json_fields[k] = v
         end
@@ -254,6 +277,7 @@ module Comet
       ret['StorageRole'] = @storage_role
       ret['TrustXForwardedFor'] = @trust_xforwarded_for
       ret['WebhookOptions'] = @webhook_options
+      ret['AuditFileOptions'] = @audit_file_options
       @unknown_json_fields.each do |k, v|
         ret[k] = v
       end

data/lib/comet/models/server_meta_branding_properties.rb

@@ -28,9 +28,11 @@ module Comet
     # @type [String] image_etag
     attr_accessor :image_etag
 
+    # Colour in RGB hex format (e.g. "#FFFFFF")
     # @type [String] top_color
     attr_accessor :top_color
 
+    # Colour in RGB hex format (e.g. "#FFFFFF")
     # @type [String] accent_color
     attr_accessor :accent_color
 

data/lib/comet/models/server_meta_version_info.rb

@@ -62,6 +62,7 @@ module Comet
     # @type [Number] server_license_feature_set
     attr_accessor :server_license_feature_set
 
+    # Unix timestamp, in seconds.
     # @type [Number] license_valid_until
     attr_accessor :license_valid_until
 
@@ -89,6 +90,7 @@ module Comet
     # @type [Boolean] scheduled_email_thread_last_wake_sent_emails
     attr_accessor :scheduled_email_thread_last_wake_sent_emails
 
+    # This field is available in Comet 21.3.2 and later.
     # @type [Array<Comet::SelfBackupStatistics>] self_backup
     attr_accessor :self_backup
 

data/lib/comet/models/session_key_regenerated_response.rb

@@ -22,6 +22,8 @@ module Comet
     # @type [String] session_key
     attr_accessor :session_key
 
+    # e.g. "admin" or "user"
+    # This field is available in Comet 18.12.3 and later.
     # @type [String] session_type
     attr_accessor :session_type
 

data/lib/comet/models/session_options.rb

@@ -12,6 +12,8 @@ module Comet
   # SessionOptions is a typed class wrapper around the underlying Comet Server API data structure.
   class SessionOptions
 
+    # The number of seconds, after which an administrator should be automatically logged out of the
+    # Comet Server web interface. If zero, will be replaced with DEFAULT_SESSIONTIMEOUT.
     # @type [Number] expired_in_seconds
     attr_accessor :expired_in_seconds
 

data/lib/comet/models/sftpdestination_location.rb

@@ -18,6 +18,7 @@ module Comet
     # @type [String] sftpusername
     attr_accessor :sftpusername
 
+    # The directory on the SFTP server in which data is stored.
     # @type [String] sftpremote_path
     attr_accessor :sftpremote_path
 
@@ -25,15 +26,21 @@ module Comet
     # @type [Number] sftpauth_mode
     attr_accessor :sftpauth_mode
 
+    # For use with DESTINATION_SFTP_AUTHMODE_PASSWORD only: the SSH password to connect with
     # @type [String] sftppassword
     attr_accessor :sftppassword
 
+    # For use with DESTINATION_SFTP_AUTHMODE_PRIVATEKEY only: the SSH private key to connect with, in
+    # OpenSSH format.
     # @type [String] sftpprivate_key
     attr_accessor :sftpprivate_key
 
+    # If true, then the SFTPCustomAuth_KnownHostsFile will be used to verify the remote SSH server's
+    # host key, using Trust On First Use (TOFU).
     # @type [Boolean] sftpcustom_auth__use_known_hosts_file
     attr_accessor :sftpcustom_auth__use_known_hosts_file
 
+    # If SFTPCustomAuth_UseKnownHostFile is true, the path to the SSH known_hosts file.
     # @type [String] sftpcustom_auth__known_hosts_file
     attr_accessor :sftpcustom_auth__known_hosts_file
 

data/lib/comet/models/single_field_source.rb

@@ -15,6 +15,7 @@ module Comet
     # @type [String] field_name
     attr_accessor :field_name
 
+    # One of "bool" / "int" / "string"
     # @type [String] field_type
     attr_accessor :field_type
 

data/lib/comet/models/size_measurement.rb

@@ -12,12 +12,15 @@ module Comet
   # SizeMeasurement is a typed class wrapper around the underlying Comet Server API data structure.
   class SizeMeasurement
 
+    # Bytes
     # @type [Number] size
     attr_accessor :size
 
+    # Unix timestamp in seconds
     # @type [Number] measure_started
     attr_accessor :measure_started
 
+    # Unix timestamp in seconds
     # @type [Number] measure_completed
     attr_accessor :measure_completed
 

data/lib/comet/models/software_update_news_response.rb

@@ -12,15 +12,19 @@ module Comet
   # SoftwareUpdateNewsResponse is a typed class wrapper around the underlying Comet Server API data structure.
   class SoftwareUpdateNewsResponse
 
+    # The latest "Quarterly" release version of Comet known to the account.cometbackup.com system.
     # @type [String] latest_stable
     attr_accessor :latest_stable
 
+    # The latest "Voyager" release version of Comet known to the account.cometbackup.com system.
     # @type [String] latest_prerelease
     attr_accessor :latest_prerelease
 
+    # A URL linking to the Comet Server downloads page.
     # @type [String] downloads_url
     attr_accessor :downloads_url
 
+    # An array of recent news items written by Comet Backup staff. Entries are english plaintext.
     # @type [Array<String>] whats_new
     attr_accessor :whats_new
 

data/lib/comet/models/source_basic_info.rb

@@ -10,6 +10,8 @@ require 'json'
 module Comet
 
   # SourceBasicInfo is a typed class wrapper around the underlying Comet Server API data structure.
+  # SourceBasicInfo is the minimal amount of information one device knows about another device's
+# Protected Items, in order to safely perform retention passes on their behalf.
   class SourceBasicInfo
 
     # @type [String] description
@@ -18,6 +20,7 @@ module Comet
     # @type [Number] o365account_count
     attr_accessor :o365account_count
 
+    # Bytes
     # @type [Number] size
     attr_accessor :size