http 5.3.1 → 6.0.0

data/lib/http/features/logging.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module HTTP
+  # Namespace for HTTP client features
   module Features
     # Log requests and responses. Request verb and uri, and Response status are
     # logged at `info`, and the headers and bodies of both are logged at
@@ -8,9 +9,21 @@ module HTTP
     #
     #    HTTP.use(logging: {logger: Logger.new(STDOUT)}).get("https://example.com/")
     #
+    # Binary bodies (IO/Enumerable request sources and binary-encoded
+    # responses) are formatted using the +binary_formatter+ option instead
+    # of being dumped raw. Available formatters:
+    #
+    # - +:stats+ (default) — logs <tt>BINARY DATA (N bytes)</tt>
+    # - +:base64+ — logs <tt>BINARY DATA (N bytes)\n<base64></tt>
+    # - +Proc+ — calls the proc with the raw binary string
+    #
+    # @example Custom binary formatter
+    #    HTTP.use(logging: {logger: Logger.new(STDOUT), binary_formatter: :base64})
+    #
     class Logging < Feature
       HTTP::Options.register_feature(:logging, self)
 
+      # No-op logger used as default when none is provided
       class NullLogger
         %w[fatal error warn info debug].each do |level|
           define_method(level.to_sym) do |*_args|
@@ -23,31 +36,196 @@ module HTTP
         end
       end
 
+      # The logger instance
+      #
+      # @example
+      #   feature.logger
+      #
+      # @return [#info, #debug] the logger instance
+      # @api public
       attr_reader :logger
 
-      def initialize(logger: NullLogger.new)
+      # Initializes the Logging feature
+      #
+      # @example
+      #   Logging.new(logger: Logger.new(STDOUT))
+      #
+      # @example With binary formatter
+      #   Logging.new(logger: Logger.new(STDOUT), binary_formatter: :base64)
+      #
+      # @param logger [#info, #debug] logger instance
+      # @param binary_formatter [:stats, :base64, #call] how to log binary bodies
+      # @return [Logging]
+      # @api public
+      def initialize(logger: NullLogger.new, binary_formatter: :stats)
+        super()
         @logger = logger
+        @binary_formatter = validate_binary_formatter!(binary_formatter)
       end
 
+      # Logs and returns the request
+      #
+      # @example
+      #   feature.wrap_request(request)
+      #
+      # @param request [HTTP::Request]
+      # @return [HTTP::Request]
+      # @api public
       def wrap_request(request)
-        logger.info { "> #{request.verb.to_s.upcase} #{request.uri}" }
-        logger.debug { "#{stringify_headers(request.headers)}\n\n#{request.body.source}" }
+        logger.info { format("> %s %s", String(request.verb).upcase, request.uri) }
+        log_request_details(request)
 
         request
       end
 
+      # Logs and returns the response
+      #
+      # @example
+      #   feature.wrap_response(response)
+      #
+      # @param response [HTTP::Response]
+      # @return [HTTP::Response]
+      # @api public
       def wrap_response(response)
         logger.info { "< #{response.status}" }
-        logger.debug { "#{stringify_headers(response.headers)}\n\n#{response.body}" }
 
-        response
+        return log_response_body_inline(response) unless response.body.is_a?(Response::Body)
+
+        logger.debug { stringify_headers(response.headers) }
+        return response unless logger.debug?
+
+        Response.new(**logged_response_options(response)) # steep:ignore
       end
 
       private
 
+      # Validate and return the binary_formatter option
+      # @return [:stats, :base64, #call]
+      # @raise [ArgumentError] if the formatter is not a valid option
+      # @api private
+      def validate_binary_formatter!(formatter)
+        return formatter if formatter.eql?(:stats) || formatter.eql?(:base64) || formatter.respond_to?(:call)
+
+        raise ArgumentError,
+              "binary_formatter must be :stats, :base64, or a callable " \
+              "(got #{formatter.inspect})"
+      end
+
+      # Log request headers and body (when loggable)
+      # @return [void]
+      # @api private
+      def log_request_details(request)
+        headers = stringify_headers(request.headers)
+        if request.body.loggable?
+          source = request.body.source
+          body = source.encoding.eql?(Encoding::BINARY) ? format_binary(source) : source
+          logger.debug { "#{headers}\n\n#{body}" }
+        else
+          logger.debug { headers }
+        end
+      end
+
+      # Log response with body inline (for non-streaming string bodies)
+      # @return [HTTP::Response]
+      # @api private
+      def log_response_body_inline(response)
+        body    = response.body
+        headers = stringify_headers(response.headers)
+        if body.respond_to?(:encoding) && body.encoding.eql?(Encoding::BINARY)
+          logger.debug { "#{headers}\n\n#{format_binary(body)}" } # steep:ignore
+        else
+          logger.debug { "#{headers}\n\n#{body}" }
+        end
+        response
+      end
+
+      # Build options hash for a response with body logging
+      # @return [Hash]
+      # @api private
+      def logged_response_options(response)
+        {
+          status:        response.status,
+          version:       response.version,
+          headers:       response.headers,
+          proxy_headers: response.proxy_headers,
+          connection:    response.connection,
+          body:          logged_body(response.body),
+          request:       response.request
+        }
+      end
+
+      # Wrap a response body with a logging stream
+      # @return [HTTP::Response::Body]
+      # @api private
+      def logged_body(body)
+        formatter = (method(:format_binary) unless body.loggable?) # steep:ignore
+        stream = BodyLogger.new(body.instance_variable_get(:@stream), logger, formatter: formatter) # steep:ignore
+        Response::Body.new(stream, encoding: body.encoding)
+      end
+
+      # Format binary data according to the configured binary_formatter
+      # @return [String]
+      # @api private
+      def format_binary(data)
+        case @binary_formatter
+        when :stats
+          format("BINARY DATA (%d bytes)", data.bytesize)
+        when :base64
+          format("BINARY DATA (%d bytes)\n%s", data.bytesize, [data].pack("m0"))
+        else
+          @binary_formatter.call(data) # steep:ignore
+        end
+      end
+
+      # Convert headers to a string representation
+      # @return [String]
+      # @api private
       def stringify_headers(headers)
         headers.map { |name, value| "#{name}: #{value}" }.join("\n")
       end
+
+      # Stream wrapper that logs each chunk as it flows through readpartial
+      class BodyLogger
+        # The underlying connection
+        #
+        # @example
+        #   body_logger.connection
+        #
+        # @return [HTTP::Connection] the underlying connection
+        # @api public
+        attr_reader :connection
+
+        # Create a new BodyLogger wrapping a stream
+        #
+        # @example
+        #   BodyLogger.new(stream, logger)
+        #
+        # @param stream [#readpartial] the stream to wrap
+        # @param logger [#debug] the logger instance
+        # @param formatter [#call, nil] optional formatter for each chunk
+        # @return [BodyLogger]
+        # @api public
+        def initialize(stream, logger, formatter: nil)
+          @stream = stream
+          @connection = stream.respond_to?(:connection) ? stream.connection : stream
+          @logger = logger
+          @formatter = formatter
+        end
+
+        # Read a chunk from the underlying stream and log it
+        #
+        # @example
+        #   body_logger.readpartial # => "chunk"
+        #
+        # @return [String] the chunk read from the stream
+        # @raise [EOFError] when no more data left
+        # @api public
+        def readpartial(*)
+          chunk = @stream.readpartial(*)
+          @logger.debug { @formatter ? @formatter.call(chunk) : chunk } # steep:ignore
+          chunk
+        end
+      end
     end
   end
 end

data/lib/http/features/normalize_uri.rb

@@ -4,10 +4,27 @@ require "http/uri"
 
 module HTTP
   module Features
+    # Normalizes request URIs before sending
     class NormalizeUri < Feature
+      # The URI normalizer proc
+      #
+      # @example
+      #   feature.normalizer
+      #
+      # @return [#call] the URI normalizer proc
+      # @api public
       attr_reader :normalizer
 
+      # Initializes the NormalizeUri feature
+      #
+      # @example
+      #   NormalizeUri.new(normalizer: HTTP::URI::NORMALIZER)
+      #
+      # @param normalizer [#call] URI normalizer
+      # @return [NormalizeUri]
+      # @api public
       def initialize(normalizer: HTTP::URI::NORMALIZER)
+        super()
         @normalizer = normalizer
       end
 

data/lib/http/features/raise_error.rb

@@ -2,18 +2,33 @@
 
 module HTTP
   module Features
+    # Raises an error for non-successful HTTP responses
     class RaiseError < Feature
+      # Initializes the RaiseError feature
+      #
+      # @example
+      #   RaiseError.new(ignore: [404])
+      #
+      # @param ignore [Array<Integer>] status codes to ignore
+      # @return [RaiseError]
+      # @api public
       def initialize(ignore: [])
-        super()
-
         @ignore = ignore
       end
 
+      # Raises an error for non-successful responses
+      #
+      # @example
+      #   feature.wrap_response(response)
+      #
+      # @param response [HTTP::Response]
+      # @return [HTTP::Response]
+      # @api public
       def wrap_response(response)
         return response if response.code < 400
         return response if @ignore.include?(response.code)
 
-        raise HTTP::StatusError, response
+        raise StatusError, response
       end
 
       HTTP::Options.register_feature(:raise_error, self)

data/lib/http/form_data/composite_io.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module HTTP
+  module FormData
+    # Provides IO interface across multiple IO objects.
+    class CompositeIO
+      # Creates a new CompositeIO from an array of IOs
+      #
+      # @example
+      #   CompositeIO.new([StringIO.new("hello"), StringIO.new(" world")])
+      #
+      # @api public
+      # @param [Array<IO>] ios Array of IO objects
+      def initialize(ios)
+        @index = 0
+        @ios   = ios.map do |io|
+          if io.is_a?(String)
+            StringIO.new(io)
+          elsif io.respond_to?(:read)
+            io
+          else
+            raise ArgumentError,
+                  "#{io.inspect} is neither a String nor an IO object"
+          end
+        end
+      end
+
+      # Reads and returns content across multiple IO objects
+      #
+      # @example
+      #   composite_io.read     # => "hello world"
+      #   composite_io.read(5)  # => "hello"
+      #
+      # @api public
+      # @param [Integer] length Number of bytes to retrieve
+      # @param [String] outbuf String to be replaced with retrieved data
+      # @return [String, nil]
+      def read(length = nil, outbuf = nil)
+        data   = outbuf.clear.force_encoding(Encoding::BINARY) if outbuf
+        data ||= "".b
+
+        read_chunks(length) { |chunk| data << chunk }
+
+        data unless length && data.empty?
+      end
+
+      # Returns sum of all IO sizes
+      #
+      # @example
+      #   composite_io.size # => 11
+      #
+      # @api public
+      # @return [Integer]
+      def size
+        @size ||= @ios.sum(&:size)
+      end
+
+      # Rewinds all IO objects and resets cursor
+      #
+      # @example
+      #   composite_io.rewind
+      #
+      # @api public
+      # @return [void]
+      def rewind
+        @ios.each(&:rewind)
+        @index = 0
+      end
+
+      private
+
+      # Yields chunks with total length up to `length`
+      #
+      # @api private
+      # @return [void]
+      def read_chunks(length)
+        while (chunk = readpartial(length))
+          yield chunk.force_encoding(Encoding::BINARY)
+
+          next if length.nil?
+
+          remaining = length - chunk.bytesize
+          break if remaining.zero?
+
+          length = remaining
+        end
+      end
+
+      # Reads chunk from current IO with length up to `max_length`
+      #
+      # @api private
+      # @return [String, nil]
+      def readpartial(max_length)
+        while (io = @ios.at(@index))
+          chunk = io.read(max_length)
+
+          return chunk if chunk && !chunk.empty?
+
+          @index += 1
+        end
+      end
+    end
+  end
+end

data/lib/http/form_data/file.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module HTTP
+  module FormData
+    # Represents file form param.
+    #
+    # @example Usage with StringIO
+    #
+    #  io = StringIO.new "foo bar baz"
+    #  FormData::File.new io, filename: "foobar.txt"
+    #
+    # @example Usage with IO
+    #
+    #  File.open "/home/ixti/avatar.png" do |io|
+    #    FormData::File.new io
+    #  end
+    #
+    # @example Usage with pathname
+    #
+    #  FormData::File.new "/home/ixti/avatar.png"
+    class File < Part
+      # Default MIME type
+      DEFAULT_MIME = "application/octet-stream"
+
+      # Creates a new File from a path or IO object
+      #
+      # @example
+      #   File.new("/path/to/file.txt")
+      #
+      # @api public
+      # @see DEFAULT_MIME
+      # @param [String, Pathname, IO] path_or_io Filename or IO instance
+      # @param [#to_h] opts
+      # @option opts [#to_s] :content_type (DEFAULT_MIME)
+      #   Value of Content-Type header
+      # @option opts [#to_s] :filename
+      #   When `path_or_io` is a String, Pathname or File, defaults to basename.
+      #   When `path_or_io` is a IO, defaults to `"stream-{object_id}"`
+      def initialize(path_or_io, opts = nil) # rubocop:disable Lint/MissingSuper
+        opts = FormData.ensure_hash(opts)
+
+        @io           = make_io(path_or_io)
+        @autoclose    = path_or_io.is_a?(String) || path_or_io.is_a?(Pathname)
+        @content_type = opts.fetch(:content_type, DEFAULT_MIME).to_s
+        @filename     = opts.fetch(:filename, filename_for(@io))
+      end
+
+      # Closes the underlying IO if it was opened by this instance
+      #
+      # When the File was created from a String path or Pathname, the
+      # underlying file handle is closed. When created from an existing
+      # IO object, this is a no-op (the caller is responsible for
+      # closing it).
+      #
+      # @example
+      #   file = FormData::File.new("/path/to/file.txt")
+      #   file.to_s
+      #   file.close
+      #
+      # @api public
+      # @return [void]
+      def close
+        @io.close if @autoclose
+      end
+
+      private
+
+      # Wraps path_or_io into an IO object
+      #
+      # @api private
+      # @param [String, Pathname, IO] path_or_io
+      # @return [IO]
+      def make_io(path_or_io)
+        case path_or_io
+        when String   then ::File.new(path_or_io, binmode: true)
+        when Pathname then path_or_io.open(binmode: true)
+        else path_or_io
+        end
+      end
+
+      # Determines filename for the given IO
+      #
+      # @api private
+      # @param [IO] io
+      # @return [String]
+      def filename_for(io)
+        if io.respond_to?(:path)
+          ::File.basename(io.path)
+        else
+          "stream-#{io.object_id}"
+        end
+      end
+    end
+  end
+end

data/lib/http/form_data/multipart/param.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "http/form_data/readable"
+require "http/form_data/composite_io"
+
+module HTTP
+  module FormData
+    class Multipart
+      # Utility class to represent multi-part chunks
+      class Param
+        include Readable
+
+        # Initializes body part with headers and data
+        #
+        # @example With {FormData::File} value
+        #
+        #   Content-Disposition: form-data; name="avatar"; filename="avatar.png"
+        #   Content-Type: application/octet-stream
+        #
+        #   ...data of avatar.png...
+        #
+        # @example With non-{FormData::File} value
+        #
+        #   Content-Disposition: form-data; name="username"
+        #
+        #   ixti
+        #
+        # @api public
+        # @param [#to_s] name
+        # @param [FormData::File, FormData::Part, #to_s] value
+        # @return [Param]
+        def initialize(name, value)
+          @name = name.to_s
+          @part = value.is_a?(Part) ? value : Part.new(value)
+          @io   = CompositeIO.new [header, @part, CRLF]
+        end
+
+        private
+
+        # Builds the MIME header for this part
+        #
+        # @api private
+        # @return [String]
+        def header
+          header = "Content-Disposition: form-data; #{parameters}#{CRLF}"
+          header << "Content-Type: #{@part.content_type}#{CRLF}" if @part.content_type
+          header << CRLF
+        end
+
+        # Builds Content-Disposition parameters string
+        #
+        # @api private
+        # @return [String]
+        def parameters
+          params = "name=#{@name.inspect}"
+          params << "; filename=#{@part.filename.inspect}" if @part.filename
+          params
+        end
+      end
+    end
+  end
+end

data/lib/http/form_data/multipart.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require "http/form_data/multipart/param"
+require "http/form_data/readable"
+require "http/form_data/composite_io"
+
+module HTTP
+  module FormData
+    # `multipart/form-data` form data.
+    class Multipart
+      include Readable
+
+      # Default MIME type for multipart form data
+      DEFAULT_CONTENT_TYPE = "multipart/form-data"
+
+      # Returns the multipart boundary string
+      #
+      # @example
+      #   multipart.boundary # => "-----abc123"
+      #
+      # @api public
+      # @return [String]
+      attr_reader :boundary
+
+      # Creates a new Multipart form data instance
+      #
+      # @example Basic form data
+      #   Multipart.new({ foo: "bar" })
+      #
+      # @example With custom content type
+      #   Multipart.new(parts, content_type: "multipart/related")
+      #
+      # @api public
+      # @param [Enumerable, Hash, #to_h] data form data key-value pairs
+      # @param [String] boundary custom boundary string
+      # @param [String] content_type MIME type for the Content-Type header
+      def initialize(data, boundary: self.class.generate_boundary, content_type: DEFAULT_CONTENT_TYPE)
+        @boundary     = boundary.to_s.freeze
+        @content_type = content_type
+        @io = CompositeIO.new(parts(data).flat_map { |part| [glue, part] } << tail)
+      end
+
+      # Generates a boundary string for multipart form data
+      #
+      # @example
+      #   Multipart.generate_boundary # => "-----abc123..."
+      #
+      # @api public
+      # @return [String]
+      def self.generate_boundary
+        ("-" * 21) << SecureRandom.hex(21)
+      end
+
+      # Returns MIME type for the Content-Type header
+      #
+      # @example
+      #   multipart.content_type
+      #   # => "multipart/form-data; boundary=-----abc123"
+      #
+      # @api public
+      # @return [String]
+      def content_type
+        "#{@content_type}; boundary=#{@boundary}"
+      end
+
+      # Returns form data content size for Content-Length
+      #
+      # @example
+      #   multipart.content_length # => 123
+      #
+      # @api public
+      # @return [Integer]
+      alias content_length size
+
+      private
+
+      # Returns the boundary glue between parts
+      #
+      # @api private
+      # @return [String]
+      def glue
+        @glue ||= "--#{@boundary}#{CRLF}"
+      end
+
+      # Returns the closing boundary tail
+      #
+      # @api private
+      # @return [String]
+      def tail
+        @tail ||= "--#{@boundary}--#{CRLF}"
+      end
+
+      # Coerces data into an array of Param objects
+      #
+      # @api private
+      # @return [Array<Param>]
+      def parts(data)
+        FormData.ensure_data(data).flat_map do |name, values|
+          Array(values).map { |value| Param.new(name, value) }
+        end
+      end
+    end
+  end
+end