files.com 1.1.813 → 1.1.815

data/lib/files.com/models/file.rb

@@ -57,14 +57,70 @@ module Files
     # Downloads a remote file to a local file, replacing its contents.
     # @param path [String] remote file path.
     # @param local_path [String, nil] local destination; defaults to the remote basename.
+    # @param transfer [Boolean, Hash, Files::Transfer::Options, Files::Transfer::Job, nil] adaptive options or a shared job.
+    # @param progress [#call, nil] progress callback; requires transfer.
     # @return [void]
     # @raise [Files::InvalidParameterError] if the default name is unsafe on Windows; supply local_path explicitly.
     # @raise [StandardError] if the transfer or local write fails.
-    def self.download_file(path, local_path = nil)
+    # With transfer:, the download is adaptive, and can report progress (see #download_file).
+    def self.download_file(path, local_path = nil, progress: nil, transfer: nil)
       local_path ||= default_local_path(path)
+      return new(path).download_file(local_path, progress: progress, transfer: transfer) if transfer
+      raise InvalidParameterError, "Bad parameter: progress needs transfer" if progress
+
       new(path).download_file(local_path)
     end
 
+    # Continues a download a Files::Transfer::PausedError stopped, in the same process, from its checkpoint: into the
+    # local file it was writing, or into destination, the same IO it was writing. options are the API options, which a
+    # checkpoint never keeps; progress and transfer: are as for #download_file, transfer: true for the defaults, with
+    # written_bytes counting the bytes from before the pause. One resume at a time can use a checkpoint, and once a
+    # resume has started its transfer the checkpoint is spent, however it ends; a pause gives a new one. Raises
+    # Files::Transfer::CheckpointError, before anything is sent, written or truncated, when the destination or the bytes
+    # already written to it changed or cannot be read back, and Files::Transfer::VersionChangedError when the remote
+    # file did.
+    def self.resume_download(checkpoint, destination = nil, options = {}, progress: nil, transfer: true)
+      raise InvalidParameterError, "Bad parameter: checkpoint must be a Files::Transfer::Checkpoint" unless checkpoint.is_a?(Transfer::Checkpoint)
+
+      Transfer::Job.using(transfer) { |job| Transfer::DownloadCoordinator.resume(job, checkpoint, destination, options, progress: progress) }
+    end
+
+    # Continues an upload a Files::Transfer::PausedError stopped, in the same process, from its checkpoint, sending only
+    # the parts storage had not acknowledged. options are the API options, which a checkpoint never keeps; progress and
+    # transfer: are as for upload_file, with progress counting the acknowledged bytes from before the pause. One resume
+    # at a time can use a checkpoint, and once a resume has started its transfer the checkpoint is spent, however it
+    # ends; a pause gives a new one. Raises Files::Transfer::CheckpointError, before anything is sent, when the local
+    # file changed. Returns what upload_file returns.
+    def self.resume_upload(checkpoint, options = {}, progress: nil, transfer: true)
+      raise InvalidParameterError, "Bad parameter: checkpoint must be a Files::Transfer::Checkpoint" unless checkpoint.is_a?(Transfer::Checkpoint)
+
+      Transfer::Job.using(transfer) { |job| Transfer::UploadCoordinator.resume(job, checkpoint, options, progress: progress) }
+    end
+
+    # Uploads what io, a caller's IO or StringIO, holds from where it stands to destination, and returns what
+    # upload_file returns. With size, an Integer, and transfer: (as for upload_file), the upload is adaptive: exactly
+    # size bytes are read on this thread with read(length), part by part in order, through as many reads as it takes,
+    # each part only once buffer_bytes can hold it, and a copy of what each read returns, taken before the next read,
+    # is kept until storage acknowledges the part, so a retry sends the same bytes even when io's reads reuse one
+    # String; io's Strings are never changed. io ending before size bytes raises
+    # Files::Transfer::SourceChangedError, and nothing past them is read. Without size or transfer:, io is read to its
+    # end and uploaded a part at a time, as upload_chunks does. io is never rewound or closed. A paused stream upload
+    # cannot be resumed: its PausedError has no checkpoint. progress is as for upload_file, with total_bytes size (nil
+    # when it is not given).
+    def self.upload_io(io, destination, options = {}, size: nil, params: {}, progress: nil, transfer: nil)
+      raise InvalidParameterError, "Bad parameter: size must be a non-negative Integer" unless size.nil? || (size.is_a?(Integer) && size >= 0)
+
+      return Transfer::Job.using(transfer) { |job| Transfer::UploadCoordinator.upload_io(job, io, size, destination, options, params: params, progress: progress) } if transfer && size
+
+      params = params.dup
+      params[:size] ||= size if size
+      report = progress && ->(part) { progress.call(part.merge(total_bytes: size)) }
+      upload, etags, bytes = upload_chunks(io, destination, options, params: params, progress: report)
+      raise InvalidParameterError, "Bad parameter: io held #{bytes} bytes, not size #{size}" if size && bytes != size
+
+      create(destination, { action: "end", etags: etags, ref: upload.ref, size: bytes }, options)
+    end
+
     private_class_method def self.default_local_path(path)
       name = PathUtil.normalize(path).split("/").last.to_s
       # On Windows a colon makes the name a drive-relative path or an NTFS
@@ -90,6 +146,11 @@ module Files
       PathUtil.normalize("_", root, id.to_s, relative_path)
     end
 
+    # The transfer: keyword to pass on, only when the caller gave one.
+    private_class_method def self.transfer_keywords(transfer)
+      transfer ? { transfer: transfer } : {}
+    end
+
     # Uploads a local file into the RemoteServers destination namespace.
     # @param path [String] local file path.
     # @param remote_server_id [Integer] destination ID.
@@ -97,10 +158,11 @@ module Files
     # @param options [Hash] request configuration; see {Files::Api.send_request}.
     # @param params [Hash] upload API parameters.
     # @param progress [#call, nil] receives the acknowledged-part Hash described by {.upload_file}.
+    # @param transfer [Boolean, Hash, Files::Transfer::Options, Files::Transfer::Job, nil] adaptive options or a shared job.
     # @return [Files::File] the completed upload.
-    def self.upload_to_remote_server(path, remote_server_id, destination = nil, options = {}, params: {}, progress: nil)
+    def self.upload_to_remote_server(path, remote_server_id, destination = nil, options = {}, params: {}, progress: nil, transfer: nil)
       destination ||= ::File.basename(path)
-      upload_file(path, underscore_destination_path("RemoteServers", remote_server_id, destination), options, params: params, progress: progress)
+      upload_file(path, underscore_destination_path("RemoteServers", remote_server_id, destination), options, params: params, progress: progress, **transfer_keywords(transfer))
     end
 
     # Copies a remote file into the RemoteServers destination namespace.
@@ -132,10 +194,11 @@ module Files
     # @param options [Hash] request configuration; see {Files::Api.send_request}.
     # @param params [Hash] upload API parameters.
     # @param progress [#call, nil] receives the acknowledged-part Hash described by {.upload_file}.
+    # @param transfer [Boolean, Hash, Files::Transfer::Options, Files::Transfer::Job, nil] adaptive options or a shared job.
     # @return [Files::File] the completed upload.
-    def self.upload_to_snapshot(path, snapshot_id, destination = nil, options = {}, params: {}, progress: nil)
+    def self.upload_to_snapshot(path, snapshot_id, destination = nil, options = {}, params: {}, progress: nil, transfer: nil)
       destination ||= ::File.basename(path)
-      upload_file(path, underscore_destination_path("Snapshots", snapshot_id, destination), options, params: params, progress: progress)
+      upload_file(path, underscore_destination_path("Snapshots", snapshot_id, destination), options, params: params, progress: progress, **transfer_keywords(transfer))
     end
 
     # Copies a remote file into the Snapshots destination namespace.
@@ -167,10 +230,11 @@ module Files
     # @param options [Hash] request configuration; see {Files::Api.send_request}.
     # @param params [Hash] upload API parameters.
     # @param progress [#call, nil] receives the acknowledged-part Hash described by {.upload_file}.
+    # @param transfer [Boolean, Hash, Files::Transfer::Options, Files::Transfer::Job, nil] adaptive options or a shared job.
     # @return [Files::File] the completed upload.
-    def self.upload_to_child_site(path, site_id, destination = nil, options = {}, params: {}, progress: nil)
+    def self.upload_to_child_site(path, site_id, destination = nil, options = {}, params: {}, progress: nil, transfer: nil)
       destination ||= ::File.basename(path)
-      upload_file(path, underscore_destination_path("Sites", site_id, destination), options, params: params, progress: progress)
+      upload_file(path, underscore_destination_path("Sites", site_id, destination), options, params: params, progress: progress, **transfer_keywords(transfer))
     end
 
     # Copies a remote file into the Sites destination namespace.
@@ -336,10 +400,11 @@ module Files
     end
 
     # Uploads what io holds to path, a part at a time as the API grants each, and returns the last part, the parts'
-    # ETags and the bytes sent. Each part is filled from as many reads as it takes (read_part). With progress, a
-    # callable, each part's response must be a success (2xx) before the part counts as acknowledged; progress is then
-    # called with total_bytes (nil: unknown here), acknowledged_bytes (this call's bytes so far), part_number and
-    # part_bytes. Anything it raises ends the upload there, with no later part planned or sent.
+    # ETags and the bytes sent. Each part is filled from as many reads as it takes (read_part). Each part's response
+    # must be a success (2xx) before the part counts as acknowledged; any other status raises APIError before another
+    # part is planned or the upload is ended. With progress, a callable, progress is then called with total_bytes (nil:
+    # unknown here), acknowledged_bytes (this call's bytes so far), part_number and part_bytes. Anything it raises ends
+    # the upload there, with no later part planned or sent.
     # @param io [#read, #eof?] source, read from its current position.
     # @param path [String] remote destination path.
     # @param options [Hash] request configuration; see {Files::Api.send_request}.
@@ -360,7 +425,7 @@ module Files
         bytes_written += buf.length
         method = upload.http_method.downcase.to_sym
         response = client(options).remote_request(method, upload.upload_uri, { 'Content-Length': buf.length.to_s, 'Content-Type': 'application/octet-stream' }, buf)
-        raise APIError.new("Transfer request failed", http_status: response.status), cause: nil if progress && !response.status.between?(200, 299)
+        raise APIError.new("Transfer request failed", http_status: response.status), cause: nil unless response.status.between?(200, 299)
 
         etags << { etag: response.headers["ETag"], part: upload.part_number }
         progress&.call({ total_bytes: nil, acknowledged_bytes: bytes_written, part_number: upload.part_number, part_bytes: buf.length })
@@ -390,15 +455,27 @@ module Files
 
     # With progress, a callable, it is called after each part is acknowledged, as upload_chunks reports it, with
     # total_bytes the local file's size.
+    #
+    # With transfer: (true, a Hash of Files::Transfer::Options, an Options or a shared Files::Transfer::Job), the
+    # upload is adaptive: its parts are sent concurrently, as many at once as the link sustains within those options,
+    # and progress is called on this thread once for each part storage acknowledged, in the order they were. A
+    # Files::Transfer::Control in the options can cancel or pause it. Without transfer:, parts go one at a time, as
+    # they always have. See docs/file.md.
     # @param path [String] local file path.
     # @param destination [String, nil] remote path; defaults to the local basename.
     # @param options [Hash] request configuration; see {Files::Api.send_request}.
     # @param params [Hash] upload API parameters.
     # @param progress [#call, nil] called with total_bytes, acknowledged_bytes, part_number and part_bytes keys.
     #   Counts are bytes; part_number is the API part number. Raising stops the upload before any later part.
+    # @param transfer [Boolean, Hash, Files::Transfer::Options, Files::Transfer::Job, nil] adaptive options or a shared job.
     # @return [Files::File] the completed upload.
     # @raise [StandardError] if reading, a request or the progress callback fails; the local file is still closed.
-    def self.upload_file(path, destination = nil, options = {}, params: {}, progress: nil)
+    def self.upload_file(path, destination = nil, options = {}, params: {}, progress: nil, transfer: nil)
+      if transfer
+        destination ||= ::File.basename(path)
+        return Transfer::Job.using(transfer) { |job| Transfer::UploadCoordinator.upload(job, path, destination, options, params: params, progress: progress) }
+      end
+
       local_file = ::File.open(path, 'r')
       destination ||= File.basename(path)
       params[:size] ||= local_file.size
@@ -607,9 +684,18 @@ module Files
 
     # Downloads this remote file to a local file, replacing its contents.
     # @param output_file [String] local destination path.
+    # @param transfer [Boolean, Hash, Files::Transfer::Options, Files::Transfer::Job, nil] adaptive options or a shared job.
+    # @param progress [#call, nil] progress callback; requires transfer.
     # @return [void]
     # @raise [StandardError] if the transfer or local write fails.
-    def download_file(output_file)
+    # With transfer: (as for File.upload_file), the download is adaptive: when storage binds the file's version, its
+    # ranges are fetched concurrently and written in order, and progress, a callable, is called on this thread after
+    # each write with total_bytes (nil until known), written_bytes, elapsed_seconds and bytes_per_second. Anything it
+    # raises ends the download. progress needs transfer:. See docs/file.md.
+    def download_file(output_file, progress: nil, transfer: nil)
+      return Transfer::Job.using(transfer) { |job| Transfer::DownloadCoordinator.download_file(job, self, output_file, progress: progress) } if transfer
+      raise InvalidParameterError, "Bad parameter: progress needs transfer" if progress
+
       ::File.open(output_file, 'wb') do |file|
         download_content(file)
       end
@@ -619,9 +705,19 @@ module Files
     # @param io [#write, #<<] destination stream.
     # @param range [Array<Integer>] optional inclusive start and end byte offsets.
     #   Applied by the Net::HTTP adapter; other adapters fetch the whole response.
+    # @param transfer [Boolean, Hash, Files::Transfer::Options, Files::Transfer::Job, nil] adaptive options or a shared job.
+    # @param progress [#call, nil] progress callback; requires transfer.
     # @return [void]
     # @raise [StandardError] if the transfer or destination fails.
-    def download_content(io, range: [])
+    # With transfer:, as for #download_file, into io; it cannot be combined with range.
+    def download_content(io, range: [], progress: nil, transfer: nil)
+      if transfer
+        raise InvalidParameterError, "Bad parameter: range cannot be combined with transfer" unless range.nil? || range.empty?
+
+        return Transfer::Job.using(transfer) { |job| Transfer::DownloadCoordinator.download_content(job, self, io, progress: progress) }
+      end
+      raise InvalidParameterError, "Bad parameter: progress needs transfer" if progress
+
       Files::ApiClient.download_client.stream_download(download_uri_with_load, io, range)
     end
 
@@ -758,7 +854,11 @@ module Files
     # @param options [Hash] keyword arguments for {#download_content}, such as range.
     # @return [Files::SizableIO] the pipe reader; the caller owns closing it.
     # @raise [StandardError] if the download fails while the reader is being prepared.
+    # Never adaptive: transfer: and progress: are refused here, before any pipe or download thread exists.
     def read_io(**options)
+      raise InvalidParameterError, "Bad parameter: read_io cannot transfer adaptively; use #download_content with transfer:" if options[:transfer]
+      raise InvalidParameterError, "Bad parameter: progress needs transfer" if options[:progress]
+
       @read_io ||= begin
         r, w = SizableIO.pipe
         Thread.new do
@@ -994,8 +1094,15 @@ module Files
       raise NotImplementedError
     end
 
-    def upload_file(local_file)
-      File.upload_file(local_file.path, params: @attributes)
+    # Uploads local_file, an opened local file, to this record's path with this record's API options, and returns
+    # what File.upload_file returns. It reads local_file's path through its own handle and leaves local_file open.
+    # Only the record's mkdir_parents and with_rename go to begin_upload, never its other attributes, such as its size
+    # or download_uri. transfer: is as for File.upload_file.
+    def upload_file(local_file, transfer: nil)
+      params = @attributes.slice(:mkdir_parents, :with_rename)
+      return File.upload_file(local_file.path, path, @options, params: params, transfer: transfer) if transfer
+
+      File.upload_file(local_file.path, path, @options, params: params)
     end
 
     # Buffers bytes, or uses a readable IO as the upload source.

data/lib/files.com/models/site.rb

@@ -115,6 +115,12 @@ module Files
       @attributes[:allow_user_level_allowed_ip_override]
     end
 
+    # Allow per-user overrides of the FTP TLS session reuse requirement?
+    # @return [Boolean, nil] the field value, or nil when absent.
+    def allow_user_level_ftp_tls_session_reuse_override
+      @attributes[:allow_user_level_ftp_tls_session_reuse_override]
+    end
+
     # Allow the site-wide FTP SSL requirement to be overriden on a per-user-basis?
     # @return [Boolean, nil] the field value, or nil when absent.
     def allow_user_level_ssl_override
@@ -1012,6 +1018,12 @@ module Files
       @attributes[:snapshot_sharing_enabled]
     end
 
+    # Require TLS-protected FTP data connections to reuse the control connection TLS session? Applies to all workspaces.
+    # @return [Boolean, nil] the field value, or nil when absent.
+    def ftp_tls_session_reuse_required
+      @attributes[:ftp_tls_session_reuse_required]
+    end
+
     # Is SSL required?  Disabling this is insecure.
     # @return [Boolean, nil] the field value, or nil when absent.
     def ssl_required
@@ -1256,6 +1268,7 @@ module Files
     # @option params [Integer] session_expiry_minutes Session expiry in minutes
     # @option params [Boolean] legacy_pairing_enabled Allow legacy app pairing in all workspaces? Disabled for new sites; existing sites remain enabled until changed. Disabling blocks new pairing exchanges without revoking existing app credentials or affecting OAuth sign-in. Site administrators can re-enable it.
     # @option params [Boolean] ssl_required Is SSL required?  Disabling this is insecure.
+    # @option params [Boolean] ftp_tls_session_reuse_required Require TLS-protected FTP data connections to reuse the control connection TLS session? Applies to all workspaces.
     # @option params [Boolean] sftp_insecure_ciphers If true, we will allow weak and known insecure ciphers to be used for SFTP connections.  Enabling this setting severely weakens the security of your site and it is not recommend, except as a last resort for compatibility.
     # @option params [Boolean] sftp_insecure_diffie_hellman If true, we will allow weak Diffie Hellman parameters to be used within ciphers for SFTP that are otherwise on our secure list.  This has the effect of making the cipher weaker than our normal threshold for security, but is required to support certain legacy or broken SSH and MFT clients.  Enabling this weakens security, but not nearly as much as enabling the full `sftp_insecure_ciphers` option.
     # @option params [Boolean] disable_files_certificate_generation If set, Files.com will not set the CAA records required to generate future SSL certificates for this domain.
@@ -1270,6 +1283,7 @@ module Files
     # @option params [Boolean] allow_user_level_2fa_override Allow the site-wide two-factor authentication requirement to be overriden on a per-user-basis?
     # @option params [Boolean] allow_user_level_allowed_ip_override Allow the site-wide allowed IP restriction to be overriden on a per-user-basis?
     # @option params [Boolean] allow_user_level_ssl_override Allow the site-wide FTP SSL requirement to be overriden on a per-user-basis?
+    # @option params [Boolean] allow_user_level_ftp_tls_session_reuse_override Allow per-user overrides of the FTP TLS session reuse requirement?
     # @option params [Boolean] enforce_parent_site_user_ip_restrictions Require Parent Site users entering this Child Site to match its allowed IP addresses in addition to their existing IP restrictions. Applies to all Workspaces. Defaults to false.
     # @option params [String] disallowed_countries Comma separated list of disallowed Country codes
     # @option params [Integer] days_to_retain_backups Number of days to keep deleted files
@@ -1442,6 +1456,7 @@ module Files
       raise InvalidParameterError.new("Bad parameter: session_expiry_minutes must be an Integer") if !params[:session_expiry_minutes].nil? and !params[:session_expiry_minutes].is_a?(Integer)
       raise InvalidParameterError.new("Bad parameter: legacy_pairing_enabled must be a single value, not #{params[:legacy_pairing_enabled].class}") if [ Array, Hash ].any? { |klass| params[:legacy_pairing_enabled].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: ssl_required must be a single value, not #{params[:ssl_required].class}") if [ Array, Hash ].any? { |klass| params[:ssl_required].is_a?(klass) }
+      raise InvalidParameterError.new("Bad parameter: ftp_tls_session_reuse_required must be a single value, not #{params[:ftp_tls_session_reuse_required].class}") if [ Array, Hash ].any? { |klass| params[:ftp_tls_session_reuse_required].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: sftp_insecure_ciphers must be a single value, not #{params[:sftp_insecure_ciphers].class}") if [ Array, Hash ].any? { |klass| params[:sftp_insecure_ciphers].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: sftp_insecure_diffie_hellman must be a single value, not #{params[:sftp_insecure_diffie_hellman].class}") if [ Array, Hash ].any? { |klass| params[:sftp_insecure_diffie_hellman].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: disable_files_certificate_generation must be a single value, not #{params[:disable_files_certificate_generation].class}") if [ Array, Hash ].any? { |klass| params[:disable_files_certificate_generation].is_a?(klass) }
@@ -1456,6 +1471,7 @@ module Files
       raise InvalidParameterError.new("Bad parameter: allow_user_level_2fa_override must be a single value, not #{params[:allow_user_level_2fa_override].class}") if [ Array, Hash ].any? { |klass| params[:allow_user_level_2fa_override].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: allow_user_level_allowed_ip_override must be a single value, not #{params[:allow_user_level_allowed_ip_override].class}") if [ Array, Hash ].any? { |klass| params[:allow_user_level_allowed_ip_override].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: allow_user_level_ssl_override must be a single value, not #{params[:allow_user_level_ssl_override].class}") if [ Array, Hash ].any? { |klass| params[:allow_user_level_ssl_override].is_a?(klass) }
+      raise InvalidParameterError.new("Bad parameter: allow_user_level_ftp_tls_session_reuse_override must be a single value, not #{params[:allow_user_level_ftp_tls_session_reuse_override].class}") if [ Array, Hash ].any? { |klass| params[:allow_user_level_ftp_tls_session_reuse_override].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: enforce_parent_site_user_ip_restrictions must be a single value, not #{params[:enforce_parent_site_user_ip_restrictions].class}") if [ Array, Hash ].any? { |klass| params[:enforce_parent_site_user_ip_restrictions].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: disallowed_countries must be an String") if !params[:disallowed_countries].nil? and !params[:disallowed_countries].is_a?(String)
       raise InvalidParameterError.new("Bad parameter: days_to_retain_backups must be an Integer") if !params[:days_to_retain_backups].nil? and !params[:days_to_retain_backups].is_a?(Integer)

data/lib/files.com/models/user.rb

@@ -1011,6 +1011,19 @@ module Files
       @attributes[:skip_welcome_screen] = value
     end
 
+    # FTP TLS session reuse requirement: use_system_setting, always_require, or never_require
+    # @return [String, nil] the field value, or nil when absent.
+    def ftp_tls_session_reuse_required
+      @attributes[:ftp_tls_session_reuse_required]
+    end
+
+    # Changes the local field value. Call {#save} to persist changes.
+    # @param value [String, nil] the new field value.
+    # @return [String, nil] the assigned value.
+    def ftp_tls_session_reuse_required=(value)
+      @attributes[:ftp_tls_session_reuse_required] = value
+    end
+
     # SSL required setting
     # @return [String, nil] the field value, or nil when absent.
     def ssl_required
@@ -1429,6 +1442,7 @@ module Files
     # @option params [Boolean] site_admin Is the user an administrator for this site?
     # @option params [Boolean] skip_welcome_screen Skip Welcome page in the UI?
     # @option params [String] ssl_required SSL required setting
+    # @option params [String] ftp_tls_session_reuse_required FTP TLS session reuse requirement: use_system_setting, always_require, or never_require
     # @option params [Integer] sso_strategy_id SSO (Single Sign On) strategy ID for the user, if applicable.
     # @option params [String] require_2fa 2FA required setting. `use_system_setting` uses the site-wide setting, including SSO exemptions. `always_require` and `never_require` override the site-wide setting when user-level overrides are allowed.
     # @option params [String] tags Comma-separated list of Tags for this user. Tags are used for other features, such as UserLifecycleRules, which can target specific tags.  Tags must only contain lowercase letters, numbers, and hyphens.
@@ -1507,6 +1521,7 @@ module Files
       raise InvalidParameterError.new("Bad parameter: site_admin must be a single value, not #{params[:site_admin].class}") if [ Array, Hash ].any? { |klass| params[:site_admin].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: skip_welcome_screen must be a single value, not #{params[:skip_welcome_screen].class}") if [ Array, Hash ].any? { |klass| params[:skip_welcome_screen].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: ssl_required must be an String") if !params[:ssl_required].nil? and !params[:ssl_required].is_a?(String)
+      raise InvalidParameterError.new("Bad parameter: ftp_tls_session_reuse_required must be an String") if !params[:ftp_tls_session_reuse_required].nil? and !params[:ftp_tls_session_reuse_required].is_a?(String)
       raise InvalidParameterError.new("Bad parameter: sso_strategy_id must be an Integer") if !params[:sso_strategy_id].nil? and !params[:sso_strategy_id].is_a?(Integer)
       raise InvalidParameterError.new("Bad parameter: require_2fa must be an String") if !params[:require_2fa].nil? and !params[:require_2fa].is_a?(String)
       raise InvalidParameterError.new("Bad parameter: tags must be an String") if !params[:tags].nil? and !params[:tags].is_a?(String)
@@ -1707,6 +1722,7 @@ module Files
     # @option params [Boolean] site_admin Is the user an administrator for this site?
     # @option params [Boolean] skip_welcome_screen Skip Welcome page in the UI?
     # @option params [String] ssl_required SSL required setting
+    # @option params [String] ftp_tls_session_reuse_required FTP TLS session reuse requirement: use_system_setting, always_require, or never_require
     # @option params [Integer] sso_strategy_id SSO (Single Sign On) strategy ID for the user, if applicable.
     # @option params [String] require_2fa 2FA required setting. `use_system_setting` uses the site-wide setting, including SSO exemptions. `always_require` and `never_require` override the site-wide setting when user-level overrides are allowed.
     # @option params [String] tags Comma-separated list of Tags for this user. Tags are used for other features, such as UserLifecycleRules, which can target specific tags.  Tags must only contain lowercase letters, numbers, and hyphens.
@@ -1780,6 +1796,7 @@ module Files
       raise InvalidParameterError.new("Bad parameter: site_admin must be a single value, not #{params[:site_admin].class}") if [ Array, Hash ].any? { |klass| params[:site_admin].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: skip_welcome_screen must be a single value, not #{params[:skip_welcome_screen].class}") if [ Array, Hash ].any? { |klass| params[:skip_welcome_screen].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: ssl_required must be an String") if !params[:ssl_required].nil? and !params[:ssl_required].is_a?(String)
+      raise InvalidParameterError.new("Bad parameter: ftp_tls_session_reuse_required must be an String") if !params[:ftp_tls_session_reuse_required].nil? and !params[:ftp_tls_session_reuse_required].is_a?(String)
       raise InvalidParameterError.new("Bad parameter: sso_strategy_id must be an Integer") if !params[:sso_strategy_id].nil? and !params[:sso_strategy_id].is_a?(Integer)
       raise InvalidParameterError.new("Bad parameter: require_2fa must be an String") if !params[:require_2fa].nil? and !params[:require_2fa].is_a?(String)
       raise InvalidParameterError.new("Bad parameter: tags must be an String") if !params[:tags].nil? and !params[:tags].is_a?(String)
@@ -1915,6 +1932,7 @@ module Files
     # @option params [Boolean] site_admin Is the user an administrator for this site?
     # @option params [Boolean] skip_welcome_screen Skip Welcome page in the UI?
     # @option params [String] ssl_required SSL required setting
+    # @option params [String] ftp_tls_session_reuse_required FTP TLS session reuse requirement: use_system_setting, always_require, or never_require
     # @option params [Integer] sso_strategy_id SSO (Single Sign On) strategy ID for the user, if applicable.
     # @option params [String] require_2fa 2FA required setting. `use_system_setting` uses the site-wide setting, including SSO exemptions. `always_require` and `never_require` override the site-wide setting when user-level overrides are allowed.
     # @option params [String] tags Comma-separated list of Tags for this user. Tags are used for other features, such as UserLifecycleRules, which can target specific tags.  Tags must only contain lowercase letters, numbers, and hyphens.
@@ -1993,6 +2011,7 @@ module Files
       raise InvalidParameterError.new("Bad parameter: site_admin must be a single value, not #{params[:site_admin].class}") if [ Array, Hash ].any? { |klass| params[:site_admin].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: skip_welcome_screen must be a single value, not #{params[:skip_welcome_screen].class}") if [ Array, Hash ].any? { |klass| params[:skip_welcome_screen].is_a?(klass) }
       raise InvalidParameterError.new("Bad parameter: ssl_required must be an String") if !params[:ssl_required].nil? and !params[:ssl_required].is_a?(String)
+      raise InvalidParameterError.new("Bad parameter: ftp_tls_session_reuse_required must be an String") if !params[:ftp_tls_session_reuse_required].nil? and !params[:ftp_tls_session_reuse_required].is_a?(String)
       raise InvalidParameterError.new("Bad parameter: sso_strategy_id must be an Integer") if !params[:sso_strategy_id].nil? and !params[:sso_strategy_id].is_a?(Integer)
       raise InvalidParameterError.new("Bad parameter: require_2fa must be an String") if !params[:require_2fa].nil? and !params[:require_2fa].is_a?(String)
       raise InvalidParameterError.new("Bad parameter: tags must be an String") if !params[:tags].nil? and !params[:tags].is_a?(String)

data/lib/files.com/transfer/budgets.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Files
+  module Transfer
+    # The bytes a job may hold in memory at once, for parts waiting to be sent or written. A part reserves its bytes
+    # before anything is read for it, keeps them through its retries and gives them back once it is acknowledged,
+    # written, abandoned or stopped. A part larger than the whole budget is refused before it reads anything, even when
+    # nothing else is held. Its methods run under the job's lock.
+    class ByteBudget
+      Reservation = Struct.new(:bytes, :released)
+
+      attr_reader :limit, :held
+
+      def initialize(limit)
+        @limit = limit
+        @held = 0
+      end
+
+      def check!(bytes)
+        return if bytes <= @limit
+
+        raise BufferLimitError, "A #{bytes}-byte part needs more memory than the transfer's buffer_bytes of #{@limit}"
+      end
+
+      def available?(bytes)
+        check!(bytes)
+        @held + bytes <= @limit
+      end
+
+      def reserve(bytes)
+        raise ArgumentError, "the transfer buffer cannot hold #{bytes} more bytes" unless available?(bytes)
+
+        @held += bytes
+        Reservation.new(bytes, false)
+      end
+
+      # Gives back what reservation holds, once however often it is called.
+      def release(reservation)
+        return if reservation.nil? || reservation.released
+
+        reservation.released = true
+        @held -= reservation.bytes
+      end
+
+      # Gives back all but bytes of what reservation holds, which holds bytes from then on. Nothing changes for a
+      # reservation released already or holding no more than bytes.
+      def shrink(reservation, bytes)
+        return if reservation.nil? || reservation.released || bytes >= reservation.bytes
+
+        @held -= reservation.bytes - bytes
+        reservation.bytes = bytes
+      end
+    end
+
+    # How many files a job transfers at once. Its methods run under the job's lock.
+    class FileSlots
+      attr_reader :limit, :used
+
+      def initialize(limit)
+        @limit = limit
+        @used = 0
+      end
+
+      def take
+        return false if @used >= @limit
+
+        @used += 1
+        true
+      end
+
+      def give
+        @used -= 1 if @used.positive?
+      end
+    end
+
+    # How many content requests a job has in flight at once, across all its transfers and destinations: heads, whole
+    # responses, parts and ranges alike. A request holds its permit from just before it is sent until its response is
+    # read or it fails, never while it waits to be retried. Its methods run under the job's lock.
+    class RequestPermits < FileSlots; end
+
+    # How long each destination is held back after a throttle: no new content request or retry of a job's, from any of
+    # its transfers and through whichever transport or controller, goes to it until the latest Retry-After any of them
+    # got from it has passed. A later Retry-After can extend that, never shorten it, and requests already sent finish. A
+    # destination is an origin: its scheme, host and port. Its methods run under the job's lock.
+    class Holds
+      # The destination url names, or nil when it names none.
+      def self.destination(url)
+        uri = ::URI.parse(url.to_s)
+        [ uri.scheme.to_s.downcase, uri.host.downcase, uri.port ].freeze if uri.host
+      rescue ::URI::InvalidURIError
+        nil
+      end
+
+      def initialize(clock: Clock)
+        @clock = clock
+        @until = {}
+      end
+
+      # Holds destination back for seconds from now, unless it already is for longer.
+      def hold(destination, seconds)
+        return unless destination && seconds.to_f.positive?
+
+        deadline = @clock.now + seconds.to_f
+        @until[destination] = [ @until[destination] || deadline, deadline ].max
+      end
+
+      # The monotonic time until which destination is held back, or nil once that has passed.
+      def deadline(destination)
+        deadline = @until[destination]
+        return deadline if deadline && deadline > @clock.now
+
+        @until.delete(destination)
+        nil
+      end
+
+      # Each destination held back now, as its origin, with the seconds left.
+      def to_h
+        now = @clock.now
+        @until.select { |_, deadline| deadline > now }.to_h { |(scheme, host, port), deadline| [ "#{scheme}://#{host}:#{port}", deadline - now ] }
+      end
+    end
+  end
+end

data/lib/files.com/transfer/checkpoint.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Files
+  module Transfer
+    # Where a paused transfer stopped, for Files::File.resume_upload or Files::File.resume_download in the same process.
+    #
+    # It holds no credentials, signed URLs, API options or API response fields; resuming takes the options again. It
+    # records, frozen, what it must find unchanged: an upload's local file (device, inode, size and modification
+    # time), its reference, the upload parameters it began with (only mkdir_parents, with_rename and size), a
+    # fingerprint of each part's instructions (a SHA-256 digest of their method, headers, size and retry rules, never
+    # their URL) and the parts storage acknowledged; a download's destination (a local file's device and inode, or the
+    # caller's IO object itself), the number of bytes written to it with a SHA-256 digest of them, and the remote
+    # file's version. Resuming refuses with CheckpointError, before it sends, writes or truncates anything, when any of
+    # them changed; a renewed part whose instructions differ stops the upload, and a download stops with
+    # VersionChangedError when storage no longer has that version.
+    #
+    # One resume at a time holds it. Once that resume has checked the local file or destination and starts its
+    # transfer, the checkpoint is spent for good, however the transfer ends: a pause then gives a new checkpoint. Only a
+    # resume refused before it started, as above, or paused or cancelled before its turn or before it finished those
+    # checks, leaves it usable. It cannot be dumped or resumed in another process.
+    class Checkpoint
+      # One resume's hold on a checkpoint, which only that resume's transfer has. start! spends the checkpoint.
+      class Lease
+        def initialize
+          @started = false
+        end
+
+        def start!
+          @started = true
+        end
+
+        def started?
+          @started
+        end
+      end
+      private_constant :Lease
+
+      attr_reader :direction, :path, :local_path, :total_bytes, :completed_bytes, :source, :sink, :version, :state
+
+      # The identity of an opened local file, from its stat: [device, inode], with size and modification time unless
+      # contents is false.
+      def self.identity(stat, contents: true)
+        contents ? [ stat.dev, stat.ino, stat.size, stat.mtime.to_r ] : [ stat.dev, stat.ino ]
+      end
+
+      # A frozen copy of value's Hashes, Arrays and Strings, all the way down. Anything else, such as a caller's IO, is
+      # kept as it is.
+      def self.frozen(value)
+        case value
+        when Hash then value.to_h { |key, item| [ frozen(key), frozen(item) ] }.freeze
+        when Array then value.map { |item| frozen(item) }.freeze
+        when String then value.frozen? ? value : value.dup.freeze
+        else value
+        end
+      end
+
+      def initialize(direction:, path:, total_bytes:, completed_bytes:, local_path: nil, source: nil, sink: nil, version: nil, state: {})
+        @process = Process.pid
+        @direction = direction
+        @path = path.dup.freeze
+        @local_path = local_path&.dup&.freeze
+        @total_bytes = total_bytes
+        @completed_bytes = completed_bytes
+        @source = Checkpoint.frozen(source)
+        @sink = Checkpoint.frozen(sink)
+        @version = version&.dup&.freeze
+        @state = Checkpoint.frozen(state)
+        @hold_lock = Mutex.new
+        @hold = [ :ready ]
+        freeze
+      end
+
+      # Raises CheckpointError unless this checkpoint can resume a transfer in direction (:upload or :download).
+      def verify!(direction)
+        raise CheckpointError, "Bad parameter: a transfer checkpoint resumes only in the process that paused it" unless @process == Process.pid
+        raise CheckpointError, "Bad parameter: this checkpoint resumes #{@direction == :upload ? 'an upload' : 'a download'}" unless @direction == direction
+      end
+
+      # Runs the block, which resumes the transfer in direction, as the one resume holding this checkpoint, and returns
+      # what it returns. The block gets the resume's lease and calls its start! once its checks pass, before it sends,
+      # writes or truncates anything; from then on the checkpoint is spent, whatever happens. Raises CheckpointError as
+      # verify! does, while another resume holds it, and once it is spent.
+      def resuming(direction)
+        verify!(direction)
+        lease = Lease.new
+        @hold_lock.synchronize do
+          case @hold[0]
+          when Lease then raise CheckpointError, "Bad parameter: another resume is already using this checkpoint"
+          when :spent then raise CheckpointError, "Bad parameter: this checkpoint has already been used to resume its transfer; resume from the checkpoint its own pause gave"
+          end
+          @hold[0] = lease
+        end
+        begin
+          yield lease
+        ensure
+          @hold_lock.synchronize { @hold[0] = lease.started? ? :spent : :ready }
+        end
+      end
+
+      def inspect
+        "#<#{self.class.name} #{@direction} #{@path.inspect} #{@completed_bytes} of #{@total_bytes.inspect} bytes>"
+      end
+
+      def to_s
+        inspect
+      end
+
+      def marshal_dump
+        raise TypeError, "a Files::Transfer::Checkpoint resumes only in the process that paused it, so it cannot be dumped"
+      end
+    end
+  end
+end

data/lib/files.com/transfer/clock.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Files
+  module Transfer
+    # Seconds on the monotonic clock, which changes to the system time never move. Measurements, retry delays and
+    # cooldowns use it; only a signed URL's expiry, which storage states in wall-clock time, is compared with Time.now.
+    # Anything with the same now method can stand in for it, as a test's controlled clock does.
+    module Clock
+      def self.now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end