aspera-cli 4.26.2 → 4.27.1

data/lib/aspera/ssh.rb

@@ -8,77 +8,110 @@ module Aspera
   # A simple wrapper around Net::SSH
   # executes one command and get its result from stdout
   class Ssh
+    # Raised when the remote command fails or cannot be started
     class Error < Aspera::Error
     end
+    # Regexp matching ecdsa/ecdh-sha2 algorithm names (JRuby workaround)
+    EXCLUDE_ECDSHA2 = /^ecd(sa|h)-sha2/
+
     class << self
-      # HACK: disable some key type
+      # Removes ed25519 keys from the default identity list used by Net::SSH.
+      # Called when the `ed25519` gem is absent or explicitly disabled via
+      # `ASCLI_ENABLE_ED25519=false`.
+      # @return [void]
       def disable_ed25519_keys
         Log.log.debug('Disabling SSH ed25519 user keys')
         old_verbose = $VERBOSE
         $VERBOSE = nil
         Net::SSH::Authentication::Session.class_eval do
           define_method(:default_keys) do
-            %w[.ssh .ssh2].product(%w[rsa dsa ecdsa]).map{"~/#{_1}/id_#{_2}"}.freeze
+            %w[.ssh .ssh2].product(%w[rsa dsa ecdsa]).map { "~/#{_1}/id_#{_2}" }.freeze
           end
           private(:default_keys)
-        end rescue nil
+        end
         $VERBOSE = old_verbose
       end
 
-      # HACK: disable some algorithms
+      # Returns Net::SSH option overrides that exclude all ecdsa/ecdh-sha2 algorithms.
+      # Merge the result into `ssh_options` passed to {Ssh#initialize} to avoid
+      # mutating Net::SSH internal constants.
+      # @return [Hash{Symbol => Array<String>}] `:host_key` and `:kex` filtered lists
+      def no_ecd_sha2_options
+        Log.log.debug('Building SSH options without ecdsa/ecdh-sha2')
+        {
+          host_key: Net::SSH::Transport::Algorithms::ALGORITHMS[:host_key].reject { |a| a.match?(EXCLUDE_ECDSHA2) },
+          kex:      Net::SSH::Transport::Algorithms::ALGORITHMS[:kex].reject {      |a| a.match?(EXCLUDE_ECDSHA2) }
+        }
+      end
+
+      # Mutates Net::SSH internal algorithm lists to remove ecdsa/ecdh-sha2 entries globally.
+      # Kept for backwards compatibility and JRuby usage; prefer {no_ecd_sha2_options} for new code.
+      # @return [void]
       def disable_ecd_sha2_algorithms
-        Log.log.debug('Disabling SSH ecdsa')
-        Net::SSH::Transport::Algorithms::ALGORITHMS.each_value{ |a| a.reject!{ |a| a =~ /^ecd(sa|h)-sha2/}}
-        Net::SSH::KnownHosts::SUPPORTED_TYPE.reject!{ |t| t =~ /^ecd(sa|h)-sha2/}
+        Log.log.debug('Disabling SSH ecdsa (global)')
+        Net::SSH::Transport::Algorithms::ALGORITHMS.each_value { |a| a.reject! { |a| a.match?(EXCLUDE_ECDSHA2) } }
+        Net::SSH::KnownHosts::SUPPORTED_TYPE.reject! { |t| t.match?(EXCLUDE_ECDSHA2) }
       end
     end
-    # ssh_options: same as Net::SSH.start
-    # see: https://net-ssh.github.io/net-ssh/classes/Net/SSH.html#method-c-start
+    # @param host        [String]            remote server address
+    # @param username    [String]            SSH user name
+    # @param ssh_options [Hash{Symbol => Object}] options forwarded to `Net::SSH.start`
+    #   (see {https://net-ssh.github.io/net-ssh/classes/Net/SSH.html#method-c-start Net::SSH.start}).
+    #   Defaults are injected for `:logger`, `:verbose`, and `:use_agent` if absent.
     def initialize(host, username, ssh_options)
       Aspera.assert_type(host, String)
       Aspera.assert_type(username, String)
       Aspera.assert_type(ssh_options, Hash)
+      Aspera.assert_hash_all(ssh_options, Symbol, nil)
       @host = host
       @username = username
       @ssh_options = ssh_options.dup
       @ssh_options[:logger] = Log.log unless @ssh_options.key?(:logger)
       @ssh_options[:verbose] = :warn unless @ssh_options.key?(:verbose)
+      # @ssh_options[:verbose] = :debug
       @ssh_options[:use_agent] = false unless @ssh_options.key?(:use_agent)
-      Log.log.debug{"ssh:#{@username}@#{@host}"}
+      Log.log.debug { "ssh:#{@username}@#{@host}" }
       Log.dump(:ssh_options, @ssh_options)
     end
 
-    # Anything on stderr raises an exception
-    def execute(cmd, input: nil, exception: false)
+    # Executes a single command on the remote host over a new SSH session.
+    # @param cmd   [String]      shell command to execute remotely
+    # @param input [String, nil] data written to the command's stdin, or `nil`
+    # @return [String] concatenated stdout of the remote command
+    # @raise [Error] if the channel cannot be opened or the remote command exits with a non-zero status
+    def execute(cmd, input: nil)
       Aspera.assert_type(cmd, String)
-      Log.log.debug{"cmd=#{cmd}"}
+      Log.log.debug { "cmd=#{cmd}" }
+      # @type response [Array<String>]
       response = []
+      # @type error [Array<String>]
       error = []
+      exit_code = nil
+      # @param session [Net::SSH::Connection::Session]
       Net::SSH.start(@host, @username, @ssh_options) do |session|
-        ssh_channel = session.open_channel do |channel|
-          # prepare stdout processing
-          channel.on_data{ |_chan, data| response.push(data)}
-          # prepare stderr processing, stderr if type = 1
-          channel.on_extended_data do |_chan, _type, data|
-            error.push(data)
-          end
-          channel.on_request('exit-status') do |_ch, data|
+        # @param channel [Net::SSH::Connection::Channel]
+        session.open_channel do |channel|
+          # Register stdout/stderr before exec so no data is missed (e.g. ForceCommand errors)
+          channel.on_data { |_ch, data| response.push(data) }
+          channel.on_extended_data { |_ch, type, data| error.push(data) if type.eql?(1) }
+          # @param data [Net::SSH::Buffer]
+          channel.on_request('exit-status') do |_channel, data|
+            Log.dump(:data, data, level: :trace1)
             exit_code = data.read_long
-            next if exit_code.zero?
-            error_message = "#{cmd}: exit #{exit_code}, #{error.join.chomp}"
-            raise Error, error_message if exception
-            # Happens when windows user hasn't logged in and created home account.
-            error_message += "\nHint: home not created in Windows?" if data.include?('Could not chdir to home directory')
-            Log.log.debug(error_message)
           end
           # send command to SSH channel (execute) cspell: disable-next-line
-          channel.send('cexe'.reverse, cmd){ |_ch, _success| channel.send_data(input) unless input.nil?}
+          channel.send('cexe'.reverse, cmd) do |_ch, success|
+            raise Error, "could not execute command: #{cmd}" unless success
+            channel.send_data(input) unless input.nil?
+          end
         end
-        # wait for channel to finish (command exit)
-        ssh_channel.wait
-        # main SSH session loop
+        # wait for channel to finish and flush the session
         session.loop
       end
+      error_text = error.join
+      hint = error_text.include?('Could not chdir to home directory') ? "\nHint: home not created in Windows?" : ''
+      raise Error, "#{cmd}: exit #{exit_code}, #{error_text.chomp}#{hint}" if exit_code&.nonzero?
+      Log.log.error { "#{error_text}#{hint}" } unless error_text.empty?
       # response as single string
       return response.join
     end

data/lib/aspera/ssl.rb

@@ -12,16 +12,16 @@ module Aspera
       @extra_options = OpenSSL::SSL::SSLContext::DEFAULT_PARAMS[:options]
       attr_reader :extra_options
 
-      def option_list=(v)
-        Aspera.assert_type(v, Array){'ssl_options'}
-        v.each do |opt|
-          Aspera.assert_type(opt, String, Integer){'Expected String or Integer in ssl_options'}
+      def option_list=(options)
+        Aspera.assert_type(options, Array) { 'ssl_options' }
+        options.each do |opt|
+          Aspera.assert_type(opt, String, Integer) { 'Expected String or Integer in ssl_options' }
           case opt
           when Integer
             @extra_options = opt
           when String
             name = "OP_#{opt.start_with?('-') ? opt[1..] : opt}".upcase
-            raise Cli::BadArgument, "Unknown ssl_option: #{name}, use one of: #{OpenSSL::SSL.constants.grep(/^OP_/).map{ |c| c.to_s.sub(/^OP_/, '')}.join(', ')}" if !OpenSSL::SSL.const_defined?(name)
+            Aspera.assert(OpenSSL::SSL.const_defined?(name), type: Cli::BadArgument) { "Unknown ssl_option: #{name}, use one of: #{OpenSSL::SSL.constants.grep(/^OP_/).map { |c| c.to_s.sub(/^OP_/, '') }.join(', ')}" }
             if opt.start_with?('-')
               @extra_options &= ~OpenSSL::SSL.const_get(name)
             else

data/lib/aspera/sync/conf.schema.yaml

@@ -637,7 +637,7 @@ properties:
       Partial transfers may exist if communication disruptions caused the underlying ascp processes to terminate early.
       Note that transfer resumption can only happen if the `reset` option is disabled.
       If an async session starts with `reset` enabled and resume enabled, transfers interrupted during that
-      session will be resumeable, but only if async is then restarted with 'reset' disabled.
+      session will be resumable, but only if async is then restarted with 'reset' disabled.
     type: object
     properties:
       enabled:
@@ -654,7 +654,7 @@ properties:
           Sets the age limit in days for temporary files that will be preserved
           on cleanup (usually at async's start and stop) for potential transfer resume.
           Temp files older than the given value will be removed
-          regardless of whether they might be resumeable.
+          regardless of whether they might be resumable.
         type: integer
         default: "5"
         x-cli-option: --resume-age-days

data/lib/aspera/sync/database.rb

@@ -25,7 +25,7 @@ class SqLite3Wrapper
     end
   else
     def execute(sql)
-      db = SQLite3::Database.new(@db_path).tap{ |d| d.results_as_hash = true}
+      db = SQLite3::Database.new(@db_path).tap { |d| d.results_as_hash = true }
       begin
         normalize_rows(db.execute(sql))
       ensure
@@ -46,7 +46,7 @@ class SqLite3Wrapper
   private
 
   def normalize_rows(rows)
-    rows.map{ |r| r.transform_keys(&:to_s)}
+    rows.map { |r| r.transform_keys(&:to_s) }
   end
 end
 

data/lib/aspera/sync/operations.rb

@@ -4,6 +4,7 @@
 
 require 'aspera/ascp/installation'
 require 'aspera/agent/direct'
+require 'aspera/exec_spec'
 require 'aspera/command_line_converter'
 require 'aspera/command_line_builder'
 require 'aspera/log'
@@ -89,17 +90,14 @@ module Aspera
         def start(sync_info, opt_ts = nil)
           Log.dump(:sync_params_initial, sync_info)
           Aspera.assert_type(sync_info, Hash)
-          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
-          env_args = {
-            args: [],
-            env:  {}
-          }
+          Aspera.assert(PARAM_KEYS.any? { |k| sync_info.key?(k) }, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
+          exec_spec = ExecSpec.new(exec: :async)
           if sync_info.key?('local')
             # `conf` format
-            Aspera.assert_type(sync_info['local'], Hash){'local'}
+            Aspera.assert_type(sync_info['local'], Hash) { 'local' }
             remote = sync_info['remote']
-            Aspera.assert_type(remote, Hash){'remote'}
-            Aspera.assert_type(remote['path'], String){'remote path'}
+            Aspera.assert_type(remote, Hash) { 'remote' }
+            Aspera.assert_type(remote['path'], String) { 'remote path' }
             # get transfer spec if possible, and feed back to new structure
             if block_given?
               transfer_spec = yield(direction_sym(sync_info), sync_info['local']['path'], remote['path'])
@@ -115,10 +113,10 @@ module Aspera
               remote['private_key_paths'].concat(add_certificates)
             end
             # '--exclusive-mgmt-port=12345', '--arg-err-path=-',
-            env_args[:args] = ["--conf64=#{Base64.strict_encode64(JSON.generate(sync_info))}"]
+            exec_spec.args = ["--conf64=#{Base64.strict_encode64(JSON.generate(sync_info))}"]
             Log.dump(:sync_conf, sync_info)
             agent = Agent::Direct.new
-            agent.start_and_monitor_process(session: {}, name: :async, **env_args)
+            agent.start_and_monitor_process(session: {}, exec_spec: exec_spec)
           else
             # `args` format
             raise StandardError, "Only 'sessions', and optionally 'instance' keys are allowed" unless
@@ -127,8 +125,8 @@ module Aspera
             Aspera.assert_type(sync_info['sessions'].first, Hash)
             if block_given?
               sync_info['sessions'].each do |session|
-                Aspera.assert_type(session['local_dir'], String){'local_dir'}
-                Aspera.assert_type(session['remote_dir'], String){'remote_dir'}
+                Aspera.assert_type(session['local_dir'], String) { 'local_dir' }
+                Aspera.assert_type(session['remote_dir'], String) { 'remote_dir' }
                 transfer_spec = yield(direction_sym(session), session['local_dir'], session['remote_dir'])
                 Log.dump(:auth_ts, transfer_spec)
                 transfer_spec.deep_merge!(opt_ts) unless opt_ts.nil?
@@ -141,23 +139,23 @@ module Aspera
               Aspera.assert_type(sync_info['instance'], Hash)
               instance_builder = CommandLineBuilder.new(sync_info['instance'], ARGS_INSTANCE_SCHEMA, CommandLineConverter)
               instance_builder.process_params
-              instance_builder.add_env_args(env_args)
+              instance_builder.add_to_exec_spec(exec_spec)
             end
             sync_info['sessions'].each do |session_params|
               Aspera.assert_type(session_params, Hash)
               Aspera.assert(session_params.key?('name'), 'session must contain at least: name')
               session_builder = CommandLineBuilder.new(session_params, ARGS_SESSION_SCHEMA, CommandLineConverter)
               session_builder.process_params
-              session_builder.add_env_args(env_args)
+              session_builder.add_to_exec_spec(exec_spec)
             end
-            Environment.secure_execute(Ascp::Installation.instance.path(:async), *env_args[:args], env: env_args[:env])
+            Environment.secure_execute(Ascp::Installation.instance.path(:async), *exec_spec.args, env: exec_spec.env)
           end
           return
         end
 
         # Parse output of asyncadmin
         def parse_status(stdout)
-          Log.log.trace1{"stdout=#{stdout}"}
+          Log.log.trace1 { "stdout=#{stdout}" }
           result = {}
           ids = nil
           stdout.split("\n").each do |line|
@@ -177,7 +175,7 @@ module Aspera
         # @param sync_info [Hash] sync parameters in conf or args format
         # @return [Hash] parsed output of asyncadmin
         def admin_status(sync_info)
-          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
+          Aspera.assert(PARAM_KEYS.any? { |k| sync_info.key?(k) }, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
           arguments = [ASYNC_ADMIN_EXECUTABLE, '--quiet']
           if sync_info.key?('local')
             # `conf` format
@@ -209,14 +207,14 @@ module Aspera
         # @param sync_info [Hash] sync parameters in conf or args format
         # @return [String, nil] Path to "local DB dir", i.e. folder that contains folders that contain `snap.db`
         def local_db_folder(sync_info)
-          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
+          Aspera.assert(PARAM_KEYS.any? { |k| sync_info.key?(k) }, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
           if sync_info.key?('local')
             # `conf` format
             if sync_info.key?('local_db_dir')
               return sync_info['local_db_dir']
             elsif (local_path = sync_info.dig('local', 'path'))
               return local_path
-            elsif exception
+            else
               raise Error, 'Missing either local_db_dir or local.path'
             end
           else
@@ -226,15 +224,14 @@ module Aspera
               return session['local_db_dir']
             elsif session.key?('local_dir')
               return session['local_dir']
-            elsif exception
+            else
               raise Error, 'Missing either local_db_dir or local_dir'
             end
           end
-          nil
         end
 
         def session_name(sync_info)
-          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
+          Aspera.assert(PARAM_KEYS.any? { |k| sync_info.key?(k) }, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
           if sync_info.key?('local')
             # `conf` format
             return sync_info['name']
@@ -246,7 +243,7 @@ module Aspera
 
         def session_db_file(sync_info)
           db_file = File.join(local_db_folder(sync_info), PRIVATE_FOLDER, session_name(sync_info), ASYNC_DB)
-          Aspera.assert(File.exist?(db_file)){"Database file #{db_file} does not exist"}
+          Aspera.assert(File.exist?(db_file)) { "Database file #{db_file} does not exist" }
           db_file
         end
 
@@ -287,7 +284,7 @@ module Aspera
         # @param option [String] Option to search
         # @return [Array,nil] with path/schema for that option
         def find_option(schema, path, option)
-          if %w[x-cli-option x-cli-short].any?{ |i| schema[i].eql?(option)}
+          if %w[x-cli-option x-cli-short].any? { |i| schema[i].eql?(option) }
             Log.log.debug('Special') if schema['x-cli-special']
             return [path, schema]
           end
@@ -325,7 +322,7 @@ module Aspera
               end
             end
             path, props = find_option(CONF_SCHEMA, [], option)
-            raise "Option not found: #{option}" if path.nil?
+            Aspera.assert(!path.nil?) { "Option not found: #{option}" }
             last_key = path.pop
             # navigate in the current result to insert the value
             current = result

data/lib/aspera/temp_file_manager.rb

@@ -3,6 +3,7 @@
 require 'singleton'
 require 'fileutils'
 require 'etc'
+require 'tempfile'
 
 module Aspera
   # create a temp file name for a given folder
@@ -40,7 +41,7 @@ module Aspera
     def delete_file(filepath)
       File.delete(filepath) if @cleanup_on_exit
     rescue => e
-      Log.log.warn{"Problem deleting file: #{filepath}: #{e.message}"}
+      Log.log.warn { "Problem deleting file: #{filepath}: #{e.message}" }
     end
 
     # Call this on process exit
@@ -51,11 +52,16 @@ module Aspera
       @created_files = []
     end
 
-    # Ensure that provided folder exists, or create it, generate a unique filename
-    # @return path to that unique file
+    # Ensure that provided folder exists, or create it, atomically create and reserve a unique file.
+    # The file is created immediately (O_EXCL) to prevent TOCTOU race conditions.
+    # @return [String] path to that unique file
     def new_file_path_in_folder(temp_folder, prefix: nil, suffix: nil)
       FileUtils.mkdir_p(temp_folder)
-      new_file = File.join(temp_folder, [prefix, SecureRandom.uuid, suffix].compact.join('-'))
+      basename = [prefix || 'aspera', SecureRandom.uuid].join('-')
+      # Tempfile.new creates the file atomically with O_EXCL; close keeps it on disk
+      tmp = Tempfile.new([basename, suffix ? "-#{suffix}" : ''], temp_folder)
+      tmp.close
+      new_file = tmp.path
       @created_files.push(new_file)
       new_file
     end
@@ -72,6 +78,20 @@ module Aspera
       new_file_path_in_folder(@global_temp, prefix: prefix, suffix: suffix)
     end
 
+    # Generate a unique directory path inside the global temp folder (does NOT create it).
+    # Unlike new_file_path_global, the caller is expected to use the path as a directory.
+    # @return [String] path to a unique (not yet existing) directory
+    def new_dir_path_global(prefix = nil)
+      username =
+        begin
+          Etc.getlogin || Etc.getpwuid(Process.uid).name || 'unknown_user'
+        rescue StandardError
+          'unknown_user'
+        end
+      dir_name = [prefix, username, SecureRandom.uuid].compact.join('-')
+      File.join(@global_temp, dir_name)
+    end
+
     # Garbage collect undeleted files
     def cleanup_expired(temp_folder)
       Dir.entries(temp_folder).each do |name|
@@ -79,7 +99,7 @@ module Aspera
         age_sec = (Time.now - File.stat(file_path).mtime).to_i
         # check age of file, delete too old
         if File.file?(file_path) && (age_sec > FILE_LIST_AGE_MAX_SEC)
-          Log.log.debug{"garbage collecting #{name}"}
+          Log.log.debug { "garbage collecting #{name}" }
           delete_file(file_path)
         end
       end

data/lib/aspera/timer_limiter.rb

@@ -3,7 +3,7 @@
 module Aspera
   # trigger returns true only if the delay has passed since the last trigger
   class TimerLimiter
-    # @param delay in seconds (float)
+    # @param delay [Float] delay in seconds
     def initialize(delay)
       @delay = delay
       @last_trigger_time = nil

data/lib/aspera/transfer/faux_file.rb

@@ -11,42 +11,55 @@ module Aspera
       SIZE_UNITS = %w[k m g t p e].freeze
       private_constant :SCHEME, :PREFIX, :SIZE_UNITS
       class << self
-        # @return nil if not a faux: scheme, else a FauxFile instance
+        # Parse a faux URI and return a `FauxFile` instance, or `nil` if the URI does not use the faux scheme.
+        # URI format: `faux:///<path>?<size>`, where `<size>` is a decimal integer with an optional
+        # case-insensitive unit suffix: `k`, `m`, `g`, `t`, `p`, `e` (powers of 1024).
+        # When no suffix is given, the size is interpreted as raw bytes.
+        # Examples: `faux:///file.bin?10` (10 bytes), `faux:///file.bin?10m` (10 MiB)
+        # @param name [String] source file name, possibly a faux URI
+        # @return [FauxFile, nil] `nil` if not a faux scheme, else a `FauxFile` instance
         def create(name)
           return unless name.start_with?(PREFIX)
           name_params = name.delete_prefix(PREFIX).split('?', 2)
-          raise Error, 'Format: #{PREFIX}<file path>?<size>' unless name_params.length.eql?(2)
-          raise Error, "Format: <integer>[#{SIZE_UNITS.join(',')}]" unless (m = name_params[1].downcase.match(/^(\d+)([#{SIZE_UNITS.join('')}])$/))
-          size = m[1].to_i
-          suffix = m[2]
-          SIZE_UNITS.each do |s|
-            size *= 1024
-            break if s.eql?(suffix)
-          end
+          Aspera.assert(name_params.length.eql?(2), type: Error) { "Format: #{PREFIX}<file path>?<size>" }
+          m = name_params[1].downcase.match(/^(\d+)([#{SIZE_UNITS.join('')}]?)$/)
+          Aspera.assert(m, type: Error) { "Format: <integer>[#{SIZE_UNITS.join(',')}]" }
+          size = m[2].empty? ? m[1].to_i : m[1].to_i * (1024**(SIZE_UNITS.index(m[2]) + 1))
           return FauxFile.new(name_params[0], size)
         end
       end
+      # @return [String]  virtual file path
+      # @return [Integer] total size in bytes
       attr_reader :path, :size
 
+      # @param path [String]  virtual file path (from the faux URI)
+      # @param size [Integer] total number of bytes to produce
       def initialize(path, size)
         @path = path
         @size = size
         @offset = 0
-        # we cache large chunks, anyway most of them will be the same size
+        # cache chunks by size so repeated reads of the same chunk length reuse the same buffer
         @chunk_by_size = {}
       end
 
+      # Read up to `chunk_size` bytes from the stream and advance the internal offset.
+      # Returns `nil` when the stream is exhausted.
+      # @param chunk_size [Integer] maximum number of bytes to read
+      # @return [String, nil] null-byte string of the bytes actually read, or `nil` at EOF
       def read(chunk_size)
         return if eof?
         bytes_to_read = [chunk_size, @size - @offset].min
         @offset += bytes_to_read
-        @chunk_by_size[bytes_to_read] = "\x00" * bytes_to_read unless @chunk_by_size.key?(bytes_to_read)
+        @chunk_by_size[bytes_to_read] ||= "\x00" * bytes_to_read
         return @chunk_by_size[bytes_to_read]
       end
 
+      # No-op: required to satisfy the IO-like interface used by transfer agents.
+      # @return [nil]
       def close
       end
 
+      # @return [Boolean] true when all bytes have been read
       def eof?
         return @offset >= @size
       end