files.com 1.1.813 → 1.1.814

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/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