iostreams 2.1.0 → 2.2.0

data/lib/io_streams/paths/s3.rb

@@ -5,6 +5,10 @@ module IOStreams
     class S3 < IOStreams::Path
       attr_reader :bucket_name, :options
 
+      # The secret access key, also within `client:`, and the customer encryption keys, see
+      # IOStreams::Path.redact_options. A session token and credentials are always sensitive by name.
+      def self.sensitive_option_names = %i[secret_access_key sse_customer_key copy_source_sse_customer_key]
+
       # Largest file size supported by the S3 copy object api.
       S3_COPY_OBJECT_SIZE_LIMIT = 5 * 1024 * 1024 * 1024
 
@@ -178,14 +182,55 @@ module IOStreams
           @client_options[:region]            = region if region
         end
 
-        @options = args
-        @options.merge!(uri.query.transform_keys(&:to_sym)) if uri.query
+        @options = uri.query ? args.merge(uri.query.transform_keys(&:to_sym)) : args
 
         super(key)
+        # Each child that #each_child yields is a new path too, so nothing is checked while deprecation warnings are off.
+        return unless Warning[:deprecated]
+
+        warn_unusable_url(uri)
+        warn_client_arguments(client, access_key_id: access_key_id, secret_access_key: secret_access_key, region: region)
+        warn_unusable_options(args.keys) unless args.empty?
+        warn_unusable_query(uri.query) if uri.query
+      end
+
+      # The S3 requests whose parameters IOStreams 3.0 takes as the options of a path, see .known_option_names.
+      OPTION_OPERATIONS = %i[get_object head_object put_object copy_object delete_object delete_objects list_objects_v2].freeze
+      private_constant :OPTION_OPERATIONS
+
+      # The parameters of the S3 requests that a path sets itself, such as `key`, which it overrides, and those of a
+      # listing that would change which keys it returns, or how, which IOStreams 3.0 does not take as the options of a
+      # path, see .known_option_names.
+      PATH_PARAMETERS = %i[
+        bucket key body response_target copy_source prefix continuation_token delimiter delete encoding_type start_after
+      ].freeze
+      private_constant :PATH_PARAMETERS
+
+      # Returns [Array<Symbol>] the options of a path that IOStreams 3.0 takes, which raises ArgumentError for any other
+      # when the path is created: the parameters of its S3 requests, see OPTION_OPERATIONS, as the AWS SDK names them,
+      # other than those that the path sets itself, see PATH_PARAMETERS. Load the AWS SDK first.
+      def self.known_option_names
+        @known_option_names ||=
+          (OPTION_OPERATIONS.flat_map { |operation| ::Aws::S3::Client.api.operation(operation).input.shape.member_names }.uniq -
+            PATH_PARAMETERS).freeze
       end
 
       def to_s
-        ::File.join("s3://", bucket_name, path)
+        Utils::PathName.join("s3://", bucket_name, path)
+      end
+
+      # Joining a name that starts with `/` to the bucket itself, see `IOStreams::Path#join`, gives the key that starts
+      # with `/`, such as `/exports/a.csv`, while IOStreams v3.0 joins it as a key within the bucket, `exports/a.csv`, as
+      # a name joined to the local directory `/` is within it. So it is deprecated, and reports a deprecation warning,
+      # see `IOStreams::Deprecation`.
+      def join(*elements)
+        joined = super
+        if path.empty? && joined.path.start_with?("/")
+          Deprecation.warn("joining a name that starts with / to an S3 bucket is deprecated, since v3.0 joins it as " \
+                           "a key within the bucket, such as exports/a.csv for /exports/a.csv: remove the leading /, " \
+                           "or name a key that starts with / in the url, such as s3://bucket//exports/a.csv")
+        end
+        joined
       end
 
       # Does not support relative file names since there is no concept of current working directory
@@ -227,9 +272,10 @@ module IOStreams
         target = IOStreams.new(target_path)
         return super(target, convert: convert, **args) unless target.is_a?(self.class)
 
+        warn_unconverted_copy_options(args[:mode], args.except(:mode))
         authorize!
         target.authorize!
-        source_name = ::File.join(bucket_name, path)
+        source_name = Utils::PathName.join(bucket_name, path)
         client.copy_object(options.merge(bucket: target.bucket_name, key: target.path, copy_source: source_name))
         target
       end
@@ -243,9 +289,10 @@ module IOStreams
           return super(source, convert: convert, **args)
         end
 
+        warn_unconverted_copy_options(args[:mode], args.except(:mode))
         authorize!
         source.authorize!
-        source_name = ::File.join(source.bucket_name, source.path)
+        source_name = Utils::PathName.join(source.bucket_name, source.path)
         client.copy_object(options.merge(bucket: bucket_name, key: path, copy_source: source_name))
       end
 
@@ -339,7 +386,7 @@ module IOStreams
         each_object(prefix) do |name, object|
           next if !directories && object.key.end_with?("/")
 
-          file_name = ::File.join("s3://", name, object.key)
+          file_name = Utils::PathName.join("s3://", name, object.key)
           next unless matcher.match?(file_name)
 
           child = child_path(name, object.key)
@@ -362,6 +409,131 @@ module IOStreams
 
       private
 
+      # Reports a deprecation warning for each part of the url that this path cannot use, which IOStreams 3.0 raises
+      # ArgumentError for when the path is created, so that a mistake in a configured url is reported wherever the
+      # code runs: a url without a bucket, a fragment, which an unencoded `#` starts, and which is not part of the key, a
+      # port, and a user name or password, which are ignored.
+      def warn_unusable_url(uri)
+        warn_url("it names no bucket, name one, such as 's3://bucket/#{path}'") if bucket_name.to_s.empty?
+        if uri.fragment
+          warn_url("it has a fragment, which a '#' starts, and which is not part of the key, percent-encode a '#' in a " \
+                   "key as '%23'")
+        end
+        if uri.port
+          warn_url("its port is ignored, supply the endpoint of another service that implements the S3 API with " \
+                   "client: {endpoint: \"https://host:port\"}")
+        end
+        return unless uri.user || uri.password
+
+        warn_url("its user name and password are ignored, supply the credentials with access_key_id: and " \
+                 "secret_access_key:")
+      end
+
+      # Reports that the S3 url of this path is deprecated, since IOStreams 3.0 raises ArgumentError for it, for the
+      # supplied reason.
+      def warn_url(reason)
+        Deprecation.warn("the S3 url #{warning_url} is deprecated, since #{reason}")
+      end
+
+      # Returns [String] the url of this path as a deprecation warning names it, quoted: its bucket and its key, without
+      # the parts of the url that the path cannot use, such as a user name, and with an empty bucket kept, unlike #to_s,
+      # such as `"s3:///a.csv"`.
+      def warning_url
+        Utils.display_text("s3://#{bucket_name}/#{path}").inspect
+      end
+
+      # Reports a deprecation warning for the region and credentials supplied with an `Aws::S3::Client`, which ignores
+      # them, since it has its own, and which IOStreams 3.0 raises ArgumentError for when the path is created.
+      def warn_client_arguments(client, **arguments)
+        return if client.nil? || client.is_a?(Hash)
+
+        names = arguments.compact.keys
+        return if names.empty?
+
+        words = Deprecation::Words.new(names)
+        Deprecation.warn("#{words.keywords} #{words.are} deprecated with an Aws::S3::Client as client:, which ignores " \
+                         "#{words.them}, since it has its own, supply #{words.them} to Aws::S3::Client.new instead, or " \
+                         "supply client: as a Hash of its options")
+      end
+
+      # Reports a deprecation warning for the options of this path that IOStreams 3.0 raises ArgumentError for when the
+      # path is created, see #unusable_option_names: one that the path sets itself, such as `key:`, which it overrides,
+      # and one that no S3 request takes, such as a misspelled one, which the AWS SDK raises for once the path is used.
+      def warn_unusable_options(names)
+        unusable_option_names(names).each_pair do |set_by_path, unusable|
+          words = Deprecation::Words.new(unusable)
+          warn_unusable("the S3 #{words.one? ? 'option' : 'options'} #{words.keywords}", words, set_by_path)
+        end
+      end
+
+      # Reports a deprecation warning for the names in the query of the url of this path that IOStreams 3.0 raises
+      # ArgumentError for when the path is created, as for an option, see #warn_unusable_options. A name without a
+      # value is more likely part of a key, such as the `?` of `s3://bucket/data/file?.csv`, so the warning then also
+      # says how to write a `?` in a key.
+      def warn_unusable_query(query)
+        unusable_option_names(query.keys.map(&:to_sym)).each_pair do |set_by_path, unusable|
+          names  = unusable.map(&:to_s)
+          words  = Deprecation::Words.new(names)
+          encode = ", and percent-encode a '?' in a key as '%3F'" if names.any? { |name| query[name].to_s.empty? }
+          warn_unusable("#{words.keywords} in the query of the S3 url #{warning_url}", words, set_by_path, encode)
+        end
+      end
+
+      # Returns [Hash<true|false, Array>] the supplied names of options that IOStreams 3.0 raises ArgumentError for: by
+      # whether the path sets them itself (true), see PATH_PARAMETERS, or no S3 request of a path takes them (false),
+      # see .known_option_names, without either when there are none.
+      def unusable_option_names(names)
+        set_by_path = names & PATH_PARAMETERS
+        {true => set_by_path, false => names - set_by_path - self.class.known_option_names}.reject { |_, list| list.empty? }
+      end
+
+      # Reports that the options, which the subject names, and the words are about, see `IOStreams::Deprecation::Words`,
+      # are deprecated, since the path sets them itself, or since no S3 request takes them, followed by the supplied
+      # advice.
+      def warn_unusable(subject, words, set_by_path, advice = nil)
+        them   = words.them
+        reason =
+          if set_by_path
+            "the path sets #{them} itself, and overrides #{them}, so remove #{them}"
+          else
+            "no S3 request takes #{them}, so correct or remove #{them}"
+          end
+        Deprecation.warn("#{subject} #{words.are} deprecated, since #{reason}#{advice}")
+      end
+
+      # Returns [Array(Array<Symbol>, String)|nil] the methods of the IO that v3.0 reads the object from, in place of the
+      # temp File that v2.2 downloads it into, and its name, see `IOStreams::Stream#v3_source`: v3.0 reads the object as
+      # the application reads it, with an IO that only reads, unless the `range` or `part_number` option chooses the
+      # bytes to read, which it still downloads into a temp file.
+      def v3_source
+        return if options.key?(:range) || options.key?(:part_number)
+
+        [IOStreams::Reader::V3_READ_METHODS, "the IO of an S3 path"]
+      end
+
+      # The methods of the IO that v3.0 uploads the object with, see #v3_target: those of an IO that write, and #flush.
+      V3_UPLOAD_METHODS = [*IOStreams::Writer::V3_WRITE_METHODS, :flush].freeze
+      private_constant :V3_UPLOAD_METHODS
+
+      # The options that describe the whole object, with which v3.0 still writes the object into a temp file first, as
+      # does a checksum of its data, such as `checksum_crc32`, see #v3_target.
+      V3_WHOLE_OBJECT_OPTIONS = %i[content_length content_md5 write_offset_bytes].freeze
+      private_constant :V3_WHOLE_OBJECT_OPTIONS
+
+      # Returns [Array(Array<Symbol>, String)|nil] the methods of the IO that v3.0 uploads the object with, in place of the
+      # temp File that v2.2 writes it into, and its name, see `IOStreams::Stream#v3_target`: v3.0 uploads the object as
+      # the application writes it, with an IO that only writes, unless an option describes the whole object, which it
+      # still writes into a temp file first. v3.0 writes the object with only the options that `put_object` takes, so
+      # only those decide, rather than one that only another request takes, such as `checksum_mode` when reading.
+      def v3_target
+        put_object   = ::Aws::S3::Client.api.operation(:put_object).input.shape
+        whole_object = options.each_key.any? do |name|
+          put_object.member?(name) &&
+            (V3_WHOLE_OBJECT_OPTIONS.include?(name) || (name.start_with?("checksum_") && name != :checksum_algorithm))
+        end
+        [V3_UPLOAD_METHODS, "the IO of an S3 path"] unless whole_object
+      end
+
       # Yields the bucket name and each object in the bucket whose key starts with the supplied prefix.
       def each_object(prefix)
         token = nil
@@ -391,9 +563,8 @@ module IOStreams
       #
       # The child uses this path's client, so that it has the same credentials and region.
       def child_path(bucket_name, key)
-        child      = self.class.new("s3://#{bucket_name}", client: client)
-        child.path = key.dup.freeze
-        child
+        child = self.class.new("s3://#{bucket_name}", client: client)
+        child.replace_path(key.dup.freeze)
       end
     end
   end

data/lib/io_streams/paths/sftp.rb

@@ -36,6 +36,20 @@ module IOStreams
 
       attr_reader :hostname, :username, :ssh_options, :url, :port
 
+      # The password, and the private key supplied as the ssh option `IdentityKey`, see IOStreams::Path.redact_options.
+      def self.sensitive_option_names = %i[password identity_key]
+
+      # Returns [String|nil] the deprecation warning for an SFTP url without a path, such as `sftp://host`, which
+      # IOStreams v3.0 reads as `sftp://host/`, the root directory, see `IOStreams::Path.name_deprecation`, while this
+      # version lists the login directory for it, see #each_child.
+      def self.name_deprecation(url)
+        return unless url_without_path?(url)
+
+        "an SFTP url without a path, such as sftp://host, is deprecated, since v3.0 reads it as sftp://host/, the " \
+          "root directory, which changes its #to_s and #path, and what #each_child lists: supply the url with the /, " \
+          "which v2.2 reads the same way"
+      end
+
       # Stream to a remote file over sftp.
       #
       # url: [String]
@@ -44,7 +58,8 @@ module IOStreams
       #   SECURITY WARNING:
       #     A username and password supplied in the url remain part of it, so `#to_s` and `#url`
       #     return them, as does any log or error message that includes the path.
-      #     Supply them with the `username:` and `password:` arguments instead.
+      #     Supply them with the `username:` and `password:` arguments instead,
+      #     and log `#display_name`, which never includes them.
       #
       # username: [String]
       #   Name of user to login with.
@@ -117,6 +132,7 @@ module IOStreams
         validate_username!
 
         super(uri.path)
+        warn_unusable_url(uri)
       end
 
       # Does not support relative file names since there is no concept of current working directory
@@ -128,6 +144,11 @@ module IOStreams
         url
       end
 
+      # Returns [String] the url without the user name, password, query or fragment, which can hold credentials.
+      def display_name
+        url.sub(%r{\A([^:/]+://)[^/?#]*@}, "\\1").sub(/[?#].*\z/m, "")
+      end
+
       # Note that mkdir is delayed and only executed when the file write is performed.
       def mkdir
         @mkdir = true
@@ -194,6 +215,29 @@ module IOStreams
         "sftp://#{hostname.to_s.downcase}:#{port}#{normalize_path(path)}".chomp("/")
       end
 
+      # Reports a deprecation warning for each part of the url that this path cannot use, which IOStreams 3.0 raises
+      # ArgumentError for when the path is created, so that a mistake in a configured url is reported wherever the
+      # code runs: a url without a host, a query, whose ssh options are ignored, and a fragment, which an unencoded `#`
+      # starts, and which is not part of the name. Each warning names the url without its user name, password, query or
+      # fragment, see #display_name.
+      def warn_unusable_url(uri)
+        warn_url("it names no host, name one, such as 'sftp://example.org#{path}'") if uri.hostname.to_s.empty?
+        if uri.query
+          warn_url("its query is ignored, supply ssh options with ssh_options:, and percent-encode a '?' in a name as " \
+                   "'%3F'")
+        end
+        return unless uri.fragment
+
+        warn_url("it has a fragment, which a '#' starts, and which is not part of the name, percent-encode a '#' in a " \
+                 "name as '%23'")
+      end
+
+      # Reports that the url of this path is deprecated, since IOStreams 3.0 raises ArgumentError for it, for the
+      # supplied reason.
+      def warn_url(reason)
+        Deprecation.warn("the SFTP url #{display_name.inspect} is deprecated, since #{reason}")
+      end
+
       # Usernames are passed to the `sftp` executable, so reject values that it could treat as options.
       def validate_username!
         return if username.nil?
@@ -209,8 +253,8 @@ module IOStreams
       def child_path(name)
         server     = port == 22 ? "sftp://#{hostname}" : "sftp://#{hostname}:#{port}"
         child      = self.class.new(server, username: username, password: password, ssh_options: ssh_options)
-        child.path = (path.empty? ? "/#{name}" : ::File.join(path, name)).freeze
-        child.url  = "#{server}#{child.path}"
+        child.replace_path((path.empty? ? "/#{name}" : Utils::PathName.join(path, name)).freeze)
+        child.url = "#{server}#{child.path}"
         child
       end
 

data/lib/io_streams/paths.rb

@@ -0,0 +1,23 @@
+module IOStreams
+  # The path classes of the schemes of urls, such as `IOStreams::Paths::S3` for `s3://`, see `IOStreams.register_scheme`.
+  module Paths
+    # Returns [IOStreams::Path] the path of the supplied name or url, created with the supplied arguments by the path
+    # class of its scheme, see .path_class.
+    #
+    # It reports no deprecation warning for the name, which `IOStreams.path` reports for a name that the application
+    # supplies, see `IOStreams::Path.name_deprecation`, so that IOStreams can create the path of a name that it derives
+    # from one, such as the directory that a pattern is matched within, see `IOStreams::Paths::Matcher`.
+    def self.build(name, **args)
+      klass = path_class(name)
+      args.empty? ? klass.new(name) : klass.new(name, **args)
+    end
+
+    # Returns [Class] the path class of the scheme of the supplied name or url, such as `IOStreams::Paths::SFTP`, or the
+    # one registered for a name without a scheme, such as `IOStreams::Paths::File`, see `IOStreams.scheme`.
+    #
+    # Raises ArgumentError when the scheme is not registered, and `URI::Error` when the url is not valid.
+    def self.path_class(name)
+      IOStreams.scheme(name.include?("://") ? Utils::URI.new(name).scheme : nil)
+    end
+  end
+end

data/lib/io_streams/pgp/reader.rb

@@ -7,6 +7,24 @@ module IOStreams
         %i[passphrase ignore_mdc_error verify_first]
       end
 
+      def self.sensitive_option_names
+        %i[passphrase]
+      end
+
+      # The methods that the stream that v3.0 supplies to a reader block for PGP answers, when gpg does not read a regular
+      # local file, see .v3_stream_methods: those of an IO that read, and #binmode and #binmode?.
+      V3_METHODS = [*V3_READ_METHODS, :binmode, :binmode?].freeze
+      private_constant :V3_METHODS
+
+      # Returns [Array<Symbol>|nil] the methods that the stream that v3.0 supplies to a reader block, in place of the IO
+      # of gpg's output that this reader yields, answers, see `IOStreams::Reader.v3_stream_methods`: nil with
+      # `verify_first: true`, since both versions then yield the File that gpg decrypts the data into, or when it reads
+      # a regular local file, which gpg reads itself in v3.0, so that the block receives gpg's output in both versions,
+      # otherwise those of the stream that v3.0 supplies, which feeds gpg the data that it reads.
+      def self.v3_stream_methods(options)
+        V3_METHODS unless options[:verify_first] || yield
+      end
+
       # Passphrase to use to open the private key to decrypt the received file
       class << self
         attr_writer :default_passphrase

data/lib/io_streams/pgp/writer.rb

@@ -11,6 +11,22 @@ module IOStreams
            compress compress_level]
       end
 
+      def self.sensitive_option_names
+        %i[signer_passphrase]
+      end
+
+      # The methods that the stream that v3.0 supplies to a writer block for PGP answers: those of an IO that write,
+      # #flush, #binmode and #binmode?, see .v3_stream_methods.
+      V3_METHODS = [*V3_WRITE_METHODS, :flush, :binmode, :binmode?].freeze
+      private_constant :V3_METHODS
+
+      # Returns [Array<Symbol>] the methods that the stream that v3.0 supplies to a writer block, in place of the IO of
+      # gpg's input that this writer yields, answers, which writes to gpg, whatever it writes to, see
+      # `IOStreams::Writer.v3_stream_methods`.
+      def self.v3_stream_methods(_options)
+        V3_METHODS
+      end
+
       class << self
         # Sign all encrypted files with this users key.
         # Default: Do not sign encrypted files.

data/lib/io_streams/pgp.rb

@@ -262,8 +262,9 @@ module IOStreams
     # Returns [String] containing all the public keys for the supplied email address or key id.
     #
     # Raises ArgumentError when neither :email nor :key_id is supplied.
-    # Raises Pgp::Failure when `email: nil` is supplied without a :key_id, as before :key_id was added.
-    # In v3.0 this will raise ArgumentError instead.
+    # Raises Pgp::Failure when `email: nil` is supplied without a :key_id, as before :key_id was added, which is
+    # deprecated, since v3.0 raises ArgumentError for it instead: it reports a deprecation warning, see
+    # `IOStreams::Deprecation`.
     #
     # email: [String] Email address for requested key.
     #
@@ -276,6 +277,9 @@ module IOStreams
       if email.nil? && key_id.nil?
         raise(ArgumentError, "Either :email, or :key_id must be supplied") if email_omitted
 
+        Deprecation.warn("IOStreams::Pgp.export with email: nil and without a key_id: is deprecated, since v3.0 " \
+                         "raises ArgumentError for it rather than IOStreams::Pgp::Failure: supply the email: or " \
+                         "key_id: of the key")
         raise(Pgp::Failure, "GPG Failed reading key: no email address or key id was supplied")
       end
 
@@ -490,6 +494,10 @@ module IOStreams
     #
     # After importing keys, they are not trusted and the relevant trust level must be set.
     #
+    # Without an :email or :key_id, it raises Pgp::Failure, since gpg rejects the empty user id that it is asked for,
+    # which is deprecated, since v3.0 raises ArgumentError instead: it reports a deprecation warning, see
+    # `IOStreams::Deprecation`.
+    #
     # key_id: [String]
     #   The fingerprint of the key, as hexadecimal digits only.
     #   Raises ArgumentError when it contains any other characters.
@@ -511,6 +519,12 @@ module IOStreams
     #   key at this level allows that attacker to impersonate other recipients.
     #   When the key cannot be fully verified, supply a lower `level`.
     def self.set_trust(email: nil, key_id: nil, level: 5)
+      if email.nil? && key_id.nil?
+        Deprecation.warn("IOStreams::Pgp.set_trust without an email: or key_id: is deprecated, since v3.0 raises " \
+                         "ArgumentError for it rather than IOStreams::Pgp::Failure: supply the email: or key_id: of " \
+                         "the key")
+      end
+
       # The key_id is written into gpg's ownertrust input, where any other character, such as a newline,
       # could add trust lines for other keys.
       if key_id && !key_id.to_s.match?(/\A\h+\z/)

data/lib/io_streams/reader.rb

@@ -1,5 +1,8 @@
 module IOStreams
   class Reader
+    # Answers the names of the options that this reader takes in IOStreams 3.0, and those that it replaces.
+    extend Deprecation::OptionNames
+
     # Returns [Array<Symbol>] the names of the options this reader accepts,
     # or [nil] when the reader does not declare them.
     #
@@ -9,6 +12,47 @@ module IOStreams
       nil
     end
 
+    # Returns [Array<Symbol>] the names of the options whose values must not be displayed, such as a passphrase,
+    # so that `#inspect` on a path does not display them, see `IOStreams::Extension#redact_options`.
+    def self.sensitive_option_names
+      []
+    end
+
+    # Returns [Symbol|nil] the tabular format of the text that this reader turns its data into, such as `:csv` for a
+    # spreadsheet, otherwise nil, for a reader whose data is the text, such as gzip, see
+    # `IOStreams::Builder#text_format`.
+    def self.text_format
+      nil
+    end
+
+    # The methods of an IO that read, which every stream that v3.0 supplies to a reader block answers, see
+    # .v3_stream_methods.
+    V3_READ_METHODS = %i[read readpartial gets readline readlines each_line each eof? eof closed?].freeze
+
+    # Returns [Array<Symbol>|nil] the methods that the stream that v3.0 supplies to a reader block, in place of the one
+    # that this reader yields, answers, when it does not answer all of the methods of that one, such as when it is the
+    # reader of a gem, otherwise nil, for a reader that yields the same kind of stream in both versions, see
+    # `IOStreams::Builder#v3_stream`.
+    #
+    # Parameters:
+    #   options: [Hash]
+    #     The options that this reader is opened with, such as `verify_first: true` for PGP, see
+    #     `IOStreams::Pgp::Reader.v3_stream_methods`.
+    #
+    # Yields, for a reader whose stream depends on it, to ask whether this reader reads a regular local file in v3.0,
+    # rather than another stream, an IO that is not a file, or the object of an S3 or HTTP path, which v3.0 reads without
+    # a temp file. The block answers true or false.
+    def self.v3_stream_methods(_options)
+      nil
+    end
+
+    # Returns [Hash<Symbol:String>|nil] what the application uses in place of each method of the stream that this reader
+    # yields that v3.0 removes, when it is not the methods that the stream of v3.0 answers, see .v3_stream_methods, such as
+    # a setting of the path, otherwise nil, see `IOStreams::Builder#v3_stream`.
+    def self.v3_stream_advice
+      nil
+    end
+
     # When a Reader does not support streams, we copy the stream to a local temp file
     # and then pass that filename in for this reader.
     def self.stream(input_stream, **args, &block)