iostreams 1.10.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 30ace4685022c88754654b2b48d1c86185e47841f1d3c6a3916bc348098b178d
-  data.tar.gz: 040c669d7ad4521941a3752dc405390c4f7dda98a583cc0f5d923091e12bd452
+  metadata.gz: 90f2ff2c49b4d9fcf8105dcf586f237cea428be7a2d4ce2ed6989134a8acba55
+  data.tar.gz: 3984b551f0be2b77fbd1c361a73b0e9e23fa41f639854bff2e338cfad3c02a90
 SHA512:
-  metadata.gz: 90f2635d2e443fe4c4f3992d8f92a725118b2f52c0d4861ee1d778be8f145d93c2f0663904f8cf699b33106a154d13980634881a0039c7e0ad6389d137d69760
-  data.tar.gz: 970da1fd8e3b6ea7e1b36dad476c7f842413c2b8b50dc2939802b1962c00347bcdfa6a135245550c9cb639b694e9ca2c16439bde1afe7677701f3867cdc277e4
+  metadata.gz: 20d29687d9f136bd6799962dc7d31de0a6c872edfad7eb57fd8254362c5ab969fa59b87ac62ae8eec4674707eb59321b2f66bd01c71325420b344e40b33a3191
+  data.tar.gz: 60f46999480b15f0620d8f0e3204f8ec6776f7da57329e33c43ed70cc6a641f4a8c9a4afdb1c5e945f9925b4a24fd8bda908f9abd23e061bcf21c47e879e60b7

data/README.md

@@ -1,8 +1,9 @@
 # IOStreams
 [![Gem Version](https://img.shields.io/gem/v/iostreams.svg)](https://rubygems.org/gems/iostreams) [![Downloads](https://img.shields.io/gem/dt/iostreams.svg)](https://rubygems.org/gems/iostreams) [![License](https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg)](http://opensource.org/licenses/Apache-2.0) ![](https://img.shields.io/badge/status-Production%20Ready-blue.svg)
 
-IOStreams is an incredibly powerful streaming library that makes changes to file formats, compression, encryption, 
-or storage mechanism transparent to the application.
+IOStreams is a streaming library for Ruby that makes compression, encryption, file format, and storage
+location transparent to your code. Read and write files of any size, one block at a time, whether they
+are gzip, zip, or PGP encrypted, and whether they live on local disk, AWS S3, SFTP, or are fetched over HTTP.
 
 ## Project Status
 
@@ -14,6 +15,18 @@ Start with the [IOStreams tutorial](https://iostreams.rocketjob.io/tutorial) to
 
 Next, checkout the remaining [IOStreams documentation](https://iostreams.rocketjob.io/)
 
+See the [CHANGELOG](CHANGELOG.md) for the release history and notable changes.
+
+## Upgrading to v2.0
+
+v2.0 is a major release with breaking changes. See the [CHANGELOG](CHANGELOG.md) for the full list. The changes most likely to affect you:
+
+- **Ruby 3.2 or later is now required.** Older Ruby versions are no longer supported.
+- **Writing Zip files now requires the `zip_kit` gem.** The retired `zip_tricks` gem has been replaced by its successor, `zip_kit`. If your application writes Zip files, replace `gem "zip_tricks"` with `gem "zip_kit"` in your Gemfile. Reading Zip files is unaffected. The IOStreams API itself is unchanged.
+- **The deprecated pre-v1.6 API has been removed.** The `IOStreams::Deprecated` mix-in described below no longer exists. Any code still using those old apis must move to the current `IOStreams.path` / `IOStreams.stream` API.
+- **The deprecated PGP writer `compression:` option has been removed.** Use `compress:` instead (available since v1.11.0).
+- **`IOStreams::Pgp.logger` and `IOStreams::Pgp.logger=` have been removed.** Logging is now configured centrally for the whole library via `IOStreams.logger` / `IOStreams.logger=`. Replace `IOStreams::Pgp.logger = my_logger` with `IOStreams.logger = my_logger`. [Semantic Logger](https://logger.rocketjob.io) is detected automatically when loaded.
+
 ## Upgrading to v1.6
 
 The old, deprecated api's are no longer loaded by default with v1.6. To add back the deprecated api support, add
@@ -30,6 +43,11 @@ release.
 
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## Contributing
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on documentation
+updates, code changes, the project architecture, and the code of conduct.
+
 ## Author
 
 [Reid Morrison](https://github.com/reidmorrison)

data/Rakefile

@@ -1,10 +1,12 @@
 require "rake/testtask"
 require_relative "lib/io_streams/version"
 
+desc "Build the iostreams gem"
 task :gem do
   system "gem build iostreams.gemspec"
 end
 
+desc "Build and publish the iostreams gem, then tag and push the release"
 task publish: :gem do
   system "git tag -a v#{IOStreams::VERSION} -m 'Tagging #{IOStreams::VERSION}'"
   system "git push --tags"
@@ -12,6 +14,11 @@ task publish: :gem do
   system "rm iostreams-#{IOStreams::VERSION}.gem"
 end
 
+desc "Start an IRB console with the gem loaded"
+task :console do
+  exec "irb -I lib -r iostreams"
+end
+
 Rake::TestTask.new(:test) do |t|
   t.pattern = "test/**/*_test.rb"
   t.verbose = true

data/lib/io_streams/builder.rb

@@ -1,5 +1,5 @@
 module IOStreams
-  # Build the streams that need to be applied to a path druing reading or writing.
+  # Build the streams that need to be applied to a path during reading or writing.
   class Builder
     attr_accessor :file_name, :format_options
     attr_reader :streams, :options
@@ -50,13 +50,13 @@ module IOStreams
       self
     end
 
-    def option_or_stream(stream, **options)
+    def option_or_stream(stream, **)
       if streams
-        stream(stream, **options)
+        stream(stream, **)
       elsif file_name
-        option(stream, **options)
+        option(stream, **)
       else
-        stream(stream, **options)
+        stream(stream, **)
       end
     end
 
@@ -67,12 +67,12 @@ module IOStreams
       options[stream] if options
     end
 
-    def reader(io_stream, &block)
-      execute(:reader, pipeline, io_stream, &block)
+    def reader(io_stream, &)
+      execute(:reader, pipeline, io_stream, &)
     end
 
-    def writer(io_stream, &block)
-      execute(:writer, pipeline, io_stream, &block)
+    def writer(io_stream, &)
+      execute(:writer, pipeline, io_stream, &)
     end
 
     # Returns [Hash<Symbol:Hash>] the pipeline of streams
@@ -120,7 +120,7 @@ module IOStreams
     end
 
     def class_for_stream(type, stream)
-      ext = IOStreams.extensions[stream.nil? ? nil : stream.to_sym] ||
+      ext = IOStreams.extensions[stream&.to_sym] ||
             raise(ArgumentError, "Unknown Stream type: #{stream.inspect}")
       ext.send("#{type}_class") || raise(ArgumentError, "No #{type} registered for Stream type: #{stream.inspect}")
     end

data/lib/io_streams/bzip2/writer.rb

@@ -2,7 +2,7 @@ module IOStreams
   module Bzip2
     class Writer < IOStreams::Writer
       # Write to a stream, compressing with Bzip2
-      def self.stream(input_stream, original_file_name: nil, **args)
+      def self.stream(input_stream, **args)
         Utils.load_soft_dependency("bzip2-ffi", "Bzip2", "bzip2/ffi") unless defined?(::Bzip2::FFI)
 
         begin

data/lib/io_streams/encode/reader.rb

@@ -3,7 +3,7 @@ module IOStreams
     class Reader < IOStreams::Reader
       attr_reader :encoding, :cleaner
 
-      NOT_PRINTABLE = Regexp.compile(/[^[:print:]|\r|\n]/).freeze
+      NOT_PRINTABLE = /[^[:print:]|\r\n]/
       # Builtin strip options to apply after encoding the read data.
       CLEANSE_RULES = {
         # Strips all non printable characters
@@ -13,7 +13,7 @@ module IOStreams
       }.freeze
 
       # Read a line at a time from a file or stream
-      def self.stream(input_stream, original_file_name: nil, **args)
+      def self.stream(input_stream, **args)
         yield new(input_stream, **args)
       end
 

data/lib/io_streams/encode/writer.rb

@@ -4,7 +4,7 @@ module IOStreams
       attr_reader :encoding, :cleaner
 
       # Write a line at a time to a file or stream
-      def self.stream(input_stream, original_file_name: nil, **args)
+      def self.stream(input_stream, **args)
         yield new(input_stream, **args)
       end
 
@@ -46,7 +46,7 @@ module IOStreams
       # Write a line to the output stream
       #
       # Example:
-      #   IOStreams.writer('a.txt', encoding: 'UTF-8') do |stream|
+      #   IOStreams.path('a.txt').option(:encode, encoding: 'UTF-8').writer do |stream|
       #     stream << 'first line' << 'second line'
       #   end
       def <<(record)
@@ -54,13 +54,13 @@ module IOStreams
         self
       end
 
-      # Write a line to the output stream followed by the delimiter.
+      # Encode data and write it to the output stream.
       # Returns [Integer] the number of bytes written.
       #
       # Example:
-      #   IOStreams.writer('a.txt', encoding: 'UTF-8') do |stream|
+      #   IOStreams.path('a.txt').option(:encode, encoding: 'UTF-8').writer do |stream|
       #     count = stream.write('first line')
-      #     puts "Wrote #{count} bytes to the output file, including the delimiter"
+      #     puts "Wrote #{count} bytes to the output file"
       #   end
       def write(data)
         return 0 if data.nil?

data/lib/io_streams/gzip/reader.rb

@@ -2,7 +2,7 @@ module IOStreams
   module Gzip
     class Reader < IOStreams::Reader
       # Read from a gzip stream, decompressing the contents as it is read
-      def self.stream(input_stream, original_file_name: nil)
+      def self.stream(input_stream)
         io = ::Zlib::GzipReader.new(input_stream)
         yield io
       ensure

data/lib/io_streams/gzip/writer.rb

@@ -2,7 +2,7 @@ module IOStreams
   module Gzip
     class Writer < IOStreams::Writer
       # Write to a stream, compressing with GZip
-      def self.stream(input_stream, original_file_name: nil, &block)
+      def self.stream(input_stream, &block)
         io = ::Zlib::GzipWriter.new(input_stream)
         block.call(io)
       ensure

data/lib/io_streams/io_streams.rb

@@ -23,7 +23,7 @@ module IOStreams
   #    # => "/usr/local/sample"
   #
   #    IOStreams.path("s3://mybucket/path/file.xls")
-  #    # => #<IOStreams::S3::Path:0x00007fec66e3a288, @path="s3://mybucket/path/file.xls">
+  #    # => #<IOStreams::Paths::S3:0x00007fec66e3a288 @path="s3://mybucket/path/file.xls">
   #
   #    IOStreams.path("s3://mybucket/path/file.xls").to_s
   #    # => "s3://mybucket/path/file.xls"
@@ -36,10 +36,9 @@ module IOStreams
   #
   # For Files
   # IOStreams.path('blah.zip').option(:encode, encoding: 'BINARY').each(:line) { |line| puts line }
-  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each(:line).first
-  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each(:hash).last
-  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each(:hash).size
-  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').reader.size
+  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each(:line) { |line| puts line }
+  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').each(:hash) { |hash| p hash }
+  # IOStreams.path('blah.zip').option(:encode, encoding: 'UTF-8').read
   # IOStreams.path('blah.csv.zip').each(:line) { |line| puts line }
   # IOStreams.path('blah.zip').option(:pgp, passphrase: 'receiver_passphrase').read
   # IOStreams.path('blah.zip').stream(:zip).stream(:pgp, passphrase: 'receiver_passphrase').read
@@ -75,14 +74,25 @@ module IOStreams
 
   # Join the supplied path elements to a root path.
   #
+  # Roots allow paths to reference a particular root directory, so that all path names
+  # are appended to that root. Use `IOStreams.join` instead of `IOStreams.path` so that
+  # the exact same code can run in production and development, yet use completely
+  # different data sources in each. For example, in production the root can point to
+  # an S3 bucket, while in development it points to the local file system.
+  #
+  # Roots are configured via an initializer at startup. Multiple roots can be setup,
+  # for example one for input files, another for output files, another for reports, etc.
+  # The `:default` root is used whenever a root is not supplied when calling `IOStreams.join`.
+  #
   # Example:
   #    IOStreams.add_root(:default, "tmp/export")
+  #    IOStreams.add_root(:ftp, "tmp/ftp")
   #
   #    IOStreams.join('file.xls')
-  #    # => #<IOStreams::Paths::File:0x00007fec70391bd8 @path="tmp/export/sample">
+  #    # => #<IOStreams::Paths::File:0x00007fec70391bd8 @path="tmp/export/file.xls">
   #
   #    IOStreams.join('file.xls').to_s
-  #    # => "tmp/export/sample"
+  #    # => "tmp/export/file.xls"
   #
   #    IOStreams.join('sample', 'file.xls', root: :ftp)
   #    # => #<IOStreams::Paths::File:0x00007fec6ee329b8 @path="tmp/ftp/sample/file.xls">
@@ -108,7 +118,7 @@ module IOStreams
   #     Optional extension to add to the tempfile.
   #
   # Example:
-  #   IOStreams.temp_file
+  #   IOStreams.temp_file("export", ".csv") { |path| path.write("Hello World") }
   def self.temp_file(basename, extension = "")
     Utils.temp_file_name(basename, extension) { |file_name| yield(Paths::File.new(file_name).stream(:none)) }
   end
@@ -193,9 +203,9 @@ module IOStreams
   # "\a"        "a"              true     # escaped ordinary remains ordinary
   # "[\?]"      "?"              true     # can escape inside bracket expression
   #
-  # "*"         ".profile"       false    # wildcard doesn't match leading
-  # "*"         ".profile"       true     # period by default.
-  # ".*"        ".profile"       true                                   {hidden: true}
+  # "*"         ".profile"       false    # wildcard doesn't match leading period by default
+  # "*"         ".profile"       true     # unless hidden is enabled    {hidden: true}
+  # ".*"        ".profile"       true     # leading period is explicit
   #
   # "**/*.rb"   "main.rb"        false
   # "**/*.rb"   "./main.rb"      false
@@ -221,10 +231,10 @@ module IOStreams
   end
 
   # Add a named root path
-  def self.add_root(root, *elements)
+  def self.add_root(root, *elements, **args)
     raise(ArgumentError, "Invalid characters in root name #{root.inspect}") unless root.to_s =~ /\A\w+\Z/
 
-    @root_paths[root.to_sym] = path(*elements)
+    @root_paths[root.to_sym] = path(*elements, **args)
   end
 
   def self.roots
@@ -234,7 +244,7 @@ module IOStreams
   # Set the temporary path to use when creating local temp files.
   def self.temp_dir=(temp_dir)
     temp_dir = File.expand_path(temp_dir)
-    FileUtils.mkdir_p(temp_dir) unless ::File.exist?(temp_dir)
+    FileUtils.mkdir_p(temp_dir)
 
     @temp_dir = temp_dir
   end
@@ -249,6 +259,23 @@ module IOStreams
 
   @temp_dir = nil
 
+  # Returns [Logger] the logger used by IOStreams for debug logging.
+  #
+  # When SemanticLogger is loaded a SemanticLogger instance is used by default,
+  # otherwise no logging is performed unless a logger is assigned via #logger=.
+  def self.logger
+    @logger
+  end
+
+  # Replace the logger used by IOStreams.
+  #
+  # Set to nil to disable logging.
+  def self.logger=(logger)
+    @logger = logger
+  end
+
+  @logger = (SemanticLogger[IOStreams] if defined?(SemanticLogger::Logger))
+
   # Register a file extension and the reader and writer streaming classes
   #
   # Example:
@@ -257,7 +284,7 @@ module IOStreams
   def self.register_extension(extension, reader_class, writer_class)
     raise(ArgumentError, "Invalid extension #{extension.inspect}") unless extension.nil? || extension.to_s =~ /\A\w+\Z/
 
-    @extensions[extension.nil? ? nil : extension.to_sym] = Extension.new(reader_class, writer_class)
+    @extensions[extension&.to_sym] = Extension.new(reader_class, writer_class)
   end
 
   # De-Register a file extension
@@ -265,7 +292,7 @@ module IOStreams
   # Returns [Symbol] the extension removed, or nil if the extension was not registered
   #
   # Example:
-  #   register_extension(:xls)
+  #   deregister_extension(:xls)
   def self.deregister_extension(extension)
     raise(ArgumentError, "Invalid extension #{extension.inspect}") unless extension.to_s =~ /\A\w+\Z/
 
@@ -277,15 +304,14 @@ module IOStreams
     @extensions.dup
   end
 
-  # Register a file extension and the reader and writer streaming classes
+  # Register a URI scheme and the path class that handles it
   #
   # Example:
-  #   # MyXls::Reader and MyXls::Writer must implement .open
-  #   register_scheme(:xls, MyXls::Reader, MyXls::Writer)
+  #   register_scheme(:gcs, MyGoogleCloudStoragePath)
   def self.register_scheme(scheme, klass)
     raise(ArgumentError, "Invalid scheme #{scheme.inspect}") unless scheme.nil? || scheme.to_s =~ /\A\w+\Z/
 
-    @schemes[scheme.nil? ? nil : scheme.to_sym] = klass
+    @schemes[scheme&.to_sym] = klass
   end
 
   def self.schemes
@@ -293,7 +319,7 @@ module IOStreams
   end
 
   def self.scheme(scheme_name)
-    @schemes[scheme_name.nil? ? nil : scheme_name.to_sym] || raise(ArgumentError, "Unknown Scheme type: #{scheme_name.inspect}")
+    @schemes[scheme_name&.to_sym] || raise(ArgumentError, "Unknown Scheme type: #{scheme_name.inspect}")
   end
 
   Extension = Struct.new(:reader_class, :writer_class)

data/lib/io_streams/line/reader.rb

@@ -6,7 +6,7 @@ module IOStreams
       # Prevent denial of service when a delimiter is not found before this number * `buffer_size` characters are read.
       MAX_BLOCKS_MULTIPLIER = 100
 
-      LINEFEED_REGEXP = Regexp.compile(/\r\n|\n|\r/).freeze
+      LINEFEED_REGEXP = /\r\n|\n|\r/
 
       # Read a line at a time from a stream
       def self.stream(input_stream, **args)
@@ -44,7 +44,7 @@ module IOStreams
       #
       # Note:
       # * When using a line reader and the file_name ends with ".csv" then embedded_within is automatically set to `"`
-      def initialize(input_stream, delimiter: nil, buffer_size: 65_536, embedded_within: nil, original_file_name: nil)
+      def initialize(input_stream, delimiter: nil, buffer_size: 65_536, embedded_within: nil)
         super(input_stream)
 
         @embedded_within = embedded_within

data/lib/io_streams/line/writer.rb

@@ -24,7 +24,7 @@ module IOStreams
       #     Add the specified delimiter after every record when writing it
       #     to the output stream
       #     Default: OS Specific. Linux: "\n"
-      def initialize(output_stream, delimiter: $/, original_file_name: nil)
+      def initialize(output_stream, delimiter: $/)
         super(output_stream)
         @delimiter = delimiter
       end

data/lib/io_streams/path.rb

@@ -41,7 +41,7 @@ module IOStreams
     # Runs the pattern from the current path, returning the complete path for located files.
     #
     # See IOStreams::Paths::File.each for arguments.
-    def each_child(pattern = "*", **args, &block)
+    def each_child(pattern = "*", **args, &)
       raise NotImplementedError
     end
 
@@ -84,7 +84,7 @@ module IOStreams
     # Cleanup an incomplete write to the target "file" if the copy fails.
     # rubocop:disable Lint/SuppressedException
     def copy_from(source, **args)
-      super(source, **args)
+      super
     rescue StandardError => e
       begin
         delete

data/lib/io_streams/paths/file.rb

@@ -15,16 +15,16 @@ module IOStreams
       # Examples:
       #
       # # Case Insensitive file name lookup:
-      # IOStreams.path("ruby").glob("r*.md") { |name| puts name }
+      # IOStreams.path("ruby").each_child("r*.md") { |path| puts path }
       #
       # # Case Sensitive file name lookup:
-      # IOStreams.path("ruby").each("R*.md", case_sensitive: true) { |name| puts name }
+      # IOStreams.path("ruby").each_child("R*.md", case_sensitive: true) { |path| puts path }
       #
       # # Also return the names of directories found during the search:
-      # IOStreams.path("ruby").each("R*.md", directories: true) { |name| puts name }
+      # IOStreams.path("ruby").each_child("R*.md", directories: true) { |path| puts path }
       #
       # # Case Insensitive recursive file name lookup:
-      # IOStreams.path("ruby").glob("**/*.md") { |name| puts name }
+      # IOStreams.path("ruby").each_child("**/*.md") { |path| puts path }
       #
       # Parameters:
       #   pattern [String]
@@ -77,9 +77,9 @@ module IOStreams
       # "\a"        "a"              true     # escaped ordinary remains ordinary
       # "[\?]"      "?"              true     # can escape inside bracket expression
       #
-      # "*"         ".profile"       false    # wildcard doesn't match leading
-      # "*"         ".profile"       true     # period by default.
-      # ".*"        ".profile"       true                                   {hidden: true}
+      # "*"         ".profile"       false    # wildcard doesn't match leading period by default
+      # "*"         ".profile"       true     # unless hidden is enabled    {hidden: true}
+      # ".*"        ".profile"       true     # leading period is explicit
       #
       # "**/*.rb"   "main.rb"        false
       # "**/*.rb"   "./main.rb"      false
@@ -99,7 +99,21 @@ module IOStreams
         flags |= ::File::FNM_DOTMATCH if hidden
 
         # Dir.each_child("testdir") {|x| puts "Got #{x}" }
-        Dir.glob(::File.join(path, pattern), flags) do |full_path|
+        full_pattern = ::File.join(path, pattern)
+
+        results = Dir.glob(full_pattern, flags)
+
+        # On some platforms or Ruby versions, FNM_CASEFOLD may not work properly
+        # with complex patterns. If case-insensitive matching returns no results
+        # but we expected some, try a more robust approach.
+        if results.empty? && !case_sensitive && pattern.match?(/[A-Z]/)
+          # Try converting the pattern to lowercase and re-matching
+          lowercase_pattern = pattern.downcase
+          lowercase_full_pattern = ::File.join(path, lowercase_pattern)
+          results = Dir.glob(lowercase_full_pattern, flags)
+        end
+
+        results.each do |full_path|
           next if !directories && ::File.directory?(full_path)
 
           yield(self.class.new(full_path))
@@ -122,12 +136,12 @@ module IOStreams
 
       def mkpath
         dir = ::File.dirname(path)
-        FileUtils.mkdir_p(dir) unless ::File.exist?(dir)
+        FileUtils.mkdir_p(dir)
         self
       end
 
       def mkdir
-        FileUtils.mkdir_p(path) unless ::File.exist?(path)
+        FileUtils.mkdir_p(path)
         self
       end
 
@@ -175,7 +189,7 @@ module IOStreams
         begin
           ::File.open(path, "wb") { |io| builder.writer(io, &block) }
         rescue StandardError => e
-          ::File.unlink(path) if ::File.exist?(path)
+          ::FileUtils.rm_f(path)
           raise(e)
         end
       end

data/lib/io_streams/paths/http.rb

@@ -26,7 +26,32 @@ module IOStreams
       #
       #   http_redirect_count: [Integer]
       #     Maximum number of http redirects to follow.
-      def initialize(url, username: nil, password: nil, http_redirect_count: 10, parameters: nil)
+      #     Set to 0 to disable following redirects entirely.
+      #     Default: 10
+      #
+      #   allow_hosts: [String | Array<String>]
+      #     Optional allow-list of host names that may be contacted, applied to the
+      #     supplied url and to every redirect that is followed.
+      #     When supplied, a request to any other host raises CommunicationsFailure.
+      #     Use this to limit Server Side Request Forgery (SSRF) exposure when the url
+      #     can be influenced by untrusted input.
+      #     Default: nil (any host is allowed).
+      #
+      #   maximum_file_size: [Integer]
+      #     Optional maximum number of bytes to download.
+      #     When the response body exceeds this size the download is aborted with a
+      #     CommunicationsFailure, protecting against unbounded (denial of service) responses.
+      #     Default: nil (no limit).
+      #
+      # Security notes:
+      # - Redirect targets are supplied by the remote server. Validating only the url that is
+      #   passed in is therefore not sufficient to prevent SSRF: use `allow_hosts` (or disable
+      #   redirects with `http_redirect_count: 0`) when the url is not fully trusted.
+      # - Basic authentication credentials are only sent to the original host. They are not
+      #   resent when a redirect points at a different scheme, host, or port, so that a
+      #   redirect cannot leak the credentials to another server.
+      def initialize(url, username: nil, password: nil, http_redirect_count: 10, parameters: nil,
+                     allow_hosts: nil, maximum_file_size: nil)
         uri = URI.parse(url)
         unless %w[http https].include?(uri.scheme)
           raise(
@@ -38,6 +63,8 @@ module IOStreams
         @username            = username || uri.user
         @password            = password || uri.password
         @http_redirect_count = http_redirect_count
+        @allow_hosts         = allow_hosts.nil? ? nil : Array(allow_hosts)
+        @maximum_file_size   = maximum_file_size
         @url                 = parameters ? "#{url}?#{URI.encode_www_form(parameters)}" : url
         super(uri.path)
       end
@@ -53,6 +80,8 @@ module IOStreams
 
       private
 
+      attr_reader :allow_hosts, :maximum_file_size
+
       # Read a file using an http get.
       #
       # For example:
@@ -63,18 +92,20 @@ module IOStreams
       #
       # Notes:
       # * Since Net::HTTP download only supports a push stream, the data is streamed into a tempfile first.
-      def stream_reader(&block)
-        handle_redirects(url, http_redirect_count, &block)
+      def stream_reader(&)
+        handle_redirects(url, http_redirect_count, &)
       end
 
       def handle_redirects(uri, http_redirect_count, &block)
         uri    = URI.parse(uri) unless uri.is_a?(URI)
         result = nil
-        raise(IOStreams::Errors::CommunicationsFailure, "Too many redirects") if http_redirect_count < 1
+
+        validate_uri!(uri)
 
         Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
           request = Net::HTTP::Get.new(uri)
-          request.basic_auth(username, password) if username
+          # Only send credentials to the original host to avoid leaking them via a redirect.
+          request.basic_auth(username, password) if username && same_origin?(uri)
 
           http.request(request) do |response|
             raise(IOStreams::Errors::CommunicationsFailure, "Invalid URL: #{uri}") if response.is_a?(Net::HTTPNotFound)
@@ -83,7 +114,13 @@ module IOStreams
             end
 
             if response.is_a?(Net::HTTPRedirection)
-              new_uri = response["location"]
+              raise(IOStreams::Errors::CommunicationsFailure, "Too many redirects") if http_redirect_count < 1
+
+              location = response["location"]
+              raise(IOStreams::Errors::CommunicationsFailure, "Redirect missing location header: #{uri}") unless location
+
+              # Resolve relative redirects against the current uri.
+              new_uri = uri.merge(location)
               return handle_redirects(new_uri, http_redirect_count - 1, &block)
             end
 
@@ -93,7 +130,7 @@ module IOStreams
 
             # Since Net::HTTP download only supports a push stream, write it to a tempfile first.
             Utils.temp_file_name("iostreams_http") do |file_name|
-              ::File.open(file_name, "wb") { |io| response.read_body { |chunk| io.write(chunk) } }
+              download_to_file(response, file_name)
               # Return a read stream
               result = ::File.open(file_name, "rb") { |io| builder.reader(io, &block) }
             end
@@ -101,6 +138,42 @@ module IOStreams
         end
         result
       end
+
+      # Validate that the host may be contacted, and that the scheme is still http(s)
+      # after following a redirect.
+      def validate_uri!(uri)
+        unless %w[http https].include?(uri.scheme)
+          raise(IOStreams::Errors::CommunicationsFailure, "Invalid redirect, only http and https are supported: #{uri}")
+        end
+        return if allow_hosts.nil? || allow_hosts.include?(uri.hostname)
+
+        raise(IOStreams::Errors::CommunicationsFailure, "Host not in the allowed list of hosts: #{uri.hostname}")
+      end
+
+      def same_origin?(uri)
+        original = original_uri
+        uri.scheme == original.scheme && uri.hostname == original.hostname && uri.port == original.port
+      end
+
+      def original_uri
+        @original_uri ||= URI.parse(url)
+      end
+
+      def download_to_file(response, file_name)
+        size = 0
+        ::File.open(file_name, "wb") do |io|
+          response.read_body do |chunk|
+            size += chunk.bytesize
+            if maximum_file_size && (size > maximum_file_size)
+              raise(
+                IOStreams::Errors::CommunicationsFailure,
+                "Exceeded maximum allowed download size of #{maximum_file_size} bytes"
+              )
+            end
+            io.write(chunk)
+          end
+        end
+      end
     end
   end
 end