http-form_data 2.3.0 → 3.0.0

data/lib/http/form_data/multipart.rb

@@ -12,48 +12,95 @@ module HTTP
     class Multipart
       include Readable
 
-      attr_reader :boundary
+      # Default MIME type for multipart form data
+      DEFAULT_CONTENT_TYPE = "multipart/form-data"
 
-      # @param [#to_h, Hash] data form data key-value Hash
-      def initialize(data, boundary: self.class.generate_boundary)
-        parts = Param.coerce FormData.ensure_hash data
+      # Returns the multipart boundary string
+      #
+      # @example
+      #   multipart.boundary # => "-----abc123"
+      #
+      # @api public
+      # @return [String]
+      attr_reader :boundary
 
-        @boundary = boundary.to_s.freeze
-        @io = CompositeIO.new [*parts.flat_map { |part| [glue, part] }, tail]
+      # 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 string suitable for using as a boundary in multipart form
-      # data.
+      # 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 to be used for HTTP request `Content-Type` header.
+      # Returns MIME type for the Content-Type header
+      #
+      # @example
+      #   multipart.content_type
+      #   # => "multipart/form-data; boundary=-----abc123"
       #
+      # @api public
       # @return [String]
       def content_type
-        "multipart/form-data; boundary=#{@boundary}"
+        "#{@content_type}; boundary=#{@boundary}"
       end
 
-      # Returns form data content size to be used for HTTP request
-      # `Content-Length` header.
+      # 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

data/lib/http/form_data/part.rb

@@ -11,12 +11,34 @@ module HTTP
     # @example Usage with String
     #
     #  body = "Message"
-    #  FormData::Part.new body, :content_type => 'foobar.txt; charset="UTF-8"'
+    #  FormData::Part.new body, content_type: 'foobar.txt; charset="UTF-8"'
     class Part
       include Readable
 
-      attr_reader :content_type, :filename
+      # Returns the content type of this part
+      #
+      # @example
+      #   part.content_type # => "application/json"
+      #
+      # @api public
+      # @return [String, nil]
+      attr_reader :content_type
 
+      # Returns the filename of this part
+      #
+      # @example
+      #   part.filename # => "avatar.png"
+      #
+      # @api public
+      # @return [String, nil]
+      attr_reader :filename
+
+      # Creates a new Part with the given body and options
+      #
+      # @example
+      #   Part.new("hello", content_type: "text/plain")
+      #
+      # @api public
       # @param [#to_s] body
       # @param [String] content_type Value of Content-Type header
       # @param [String] filename     Value of filename parameter

data/lib/http/form_data/readable.rb

@@ -4,34 +4,52 @@ module HTTP
   module FormData
     # Common behaviour for objects defined by an IO object.
     module Readable
-      # Returns IO content.
+      # Returns IO content as a String
       #
+      # @example
+      #   readable.to_s # => "content"
+      #
+      # @api public
       # @return [String]
       def to_s
         rewind
-        content = read
+        content = read #: String
         rewind
         content
       end
 
-      # Reads and returns part of IO content.
+      # Reads and returns part of IO content
+      #
+      # @example
+      #   readable.read      # => "full content"
+      #   readable.read(5)   # => "full "
       #
+      # @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)
         @io.read(length, outbuf)
       end
 
-      # Returns IO size.
+      # Returns IO size in bytes
       #
+      # @example
+      #   readable.size # => 42
+      #
+      # @api public
       # @return [Integer]
       def size
         @io.size
       end
 
-      # Rewinds the IO.
+      # Rewinds the IO to the beginning
+      #
+      # @example
+      #   readable.rewind
+      #
+      # @api public
+      # @return [void]
       def rewind
         @io.rewind
       end

data/lib/http/form_data/urlencoded.rb

@@ -12,7 +12,7 @@ module HTTP
       include Readable
 
       class << self
-        # Set custom form data encoder implementation.
+        # Sets custom form data encoder implementation
         #
         # @example
         #
@@ -44,40 +44,130 @@ module HTTP
         #
         #     HTTP::FormData::Urlencoded.encoder = CustomFormDataEncoder
         #
-        # @raise [ArgumentError] if implementation deos not responds to `#call`.
+        # @api public
+        # @raise [ArgumentError] if implementation does not respond to `#call`
         # @param implementation [#call]
         # @return [void]
         def encoder=(implementation)
           raise ArgumentError unless implementation.respond_to? :call
+
           @encoder = implementation
         end
 
-        # Returns form data encoder implementation.
-        # Default: `URI.encode_www_form`.
+        # Returns form data encoder implementation
+        #
+        # @example
+        #   Urlencoded.encoder # => #<Method: DefaultEncoder.encode>
         #
+        # @api public
         # @see .encoder=
         # @return [#call]
         def encoder
-          @encoder ||= ::URI.method(:encode_www_form)
+          @encoder || DefaultEncoder
         end
+
+        # Default encoder for urlencoded form data
+        module DefaultEncoder
+          class << self
+            # Recursively encodes form data value
+            #
+            # @example
+            #   DefaultEncoder.encode({ foo: "bar" }) # => "foo=bar"
+            #
+            # @api public
+            # @param [Hash, Array, String, nil] value
+            # @param [String, nil] prefix
+            # @return [String]
+            def encode(value, prefix = nil)
+              case value
+              when Hash  then encode_hash(value, prefix)
+              when Array then encode_array(value, prefix)
+              when nil   then prefix.to_s
+              else
+                raise ArgumentError, "value must be a Hash" if prefix.nil?
+
+                "#{prefix}=#{escape(value)}"
+              end
+            end
+
+            alias call encode
+
+            private
+
+            # Encodes an Array value
+            #
+            # @api private
+            # @return [String]
+            def encode_array(value, prefix)
+              if prefix
+                value.map { |v| encode(v, "#{prefix}[]") }.join("&")
+              else
+                encode_pairs(value)
+              end
+            end
+
+            # Encodes an Array of key-value pairs
+            #
+            # @api private
+            # @return [String]
+            def encode_pairs(pairs)
+              pairs.map { |k, v| encode(v, escape(k)) }.reject(&:empty?).join("&")
+            end
+
+            # Encodes a Hash value
+            #
+            # @api private
+            # @return [String]
+            def encode_hash(hash, prefix)
+              hash.map do |k, v|
+                encode(v, prefix ? "#{prefix}[#{escape(k)}]" : escape(k))
+              end.reject(&:empty?).join("&")
+            end
+
+            # URL-encodes a value
+            #
+            # @api private
+            # @return [String]
+            def escape(value)
+              URI.encode_www_form_component(value)
+            end
+          end
+        end
+
+        private_constant :DefaultEncoder
       end
 
-      # @param [#to_h, Hash] data form data key-value Hash
+      # Creates a new Urlencoded form data instance
+      #
+      # @example
+      #   Urlencoded.new({ "foo" => "bar" })
+      #
+      # @api public
+      # @param [Enumerable, Hash, #to_h] data form data key-value pairs
+      # @param [#call] encoder custom encoder implementation
       def initialize(data, encoder: nil)
         encoder ||= self.class.encoder
-        @io = StringIO.new(encoder.call(FormData.ensure_hash(data)))
+        @io = StringIO.new(encoder.call(FormData.ensure_data(data)))
       end
 
-      # Returns MIME type to be used for HTTP request `Content-Type` header.
+      # Returns MIME type for the Content-Type header
       #
+      # @example
+      #   urlencoded.content_type
+      #   # => "application/x-www-form-urlencoded"
+      #
+      # @api public
       # @return [String]
       def content_type
         "application/x-www-form-urlencoded"
       end
 
-      # Returns form data content size to be used for HTTP request
-      # `Content-Length` header.
+      # Returns form data content size for Content-Length
+      #
+      # @example
+      #   urlencoded.content_length # => 17
       #
+      # @api public
       # @return [Integer]
       alias content_length size
     end

data/lib/http/form_data/version.rb

@@ -3,6 +3,6 @@
 module HTTP
   module FormData
     # Gem version.
-    VERSION = "2.3.0"
+    VERSION = "3.0.0"
   end
 end

data/lib/http/form_data.rb

@@ -16,8 +16,8 @@ module HTTP
   # @example Usage
   #
   #   form = FormData.create({
-  #     :username     => "ixti",
-  #     :avatar_file  => FormData::File.new("/home/ixti/avatar.png")
+  #     username:    "ixti",
+  #     avatar_file: FormData::File.new("/home/ixti/avatar.png")
   #   })
   #
   #   # Assuming socket is an open socket to some HTTP server
@@ -35,46 +35,66 @@ module HTTP
     class Error < StandardError; end
 
     class << self
-      # FormData factory. Automatically selects best type depending on given
-      # `data` Hash.
+      # Selects encoder type based on given data
       #
-      # @param [#to_h, Hash] data
+      # @example
+      #   FormData.create({ username: "ixti" })
+      #
+      # @api public
+      # @param [Enumerable, Hash, #to_h] data
       # @return [Multipart] if any of values is a {FormData::File}
       # @return [Urlencoded] otherwise
       def create(data, encoder: nil)
-        data = ensure_hash data
+        data = ensure_data data
 
         if multipart?(data)
           Multipart.new(data)
         else
-          Urlencoded.new(data, :encoder => encoder)
+          Urlencoded.new(data, encoder: encoder)
         end
       end
 
-      # Coerce `obj` to Hash.
+      # Coerces obj to Hash
+      #
+      # @example
+      #   FormData.ensure_hash({ foo: :bar }) # => { foo: :bar }
       #
-      # @note Internal usage helper, to workaround lack of `#to_h` on Ruby < 2.1
-      # @raise [Error] `obj` can't be coerced.
+      # @api public
+      # @raise [Error] `obj` can't be coerced
       # @return [Hash]
       def ensure_hash(obj)
-        case
-        when obj.nil?               then {}
-        when obj.is_a?(Hash)        then obj
-        when obj.respond_to?(:to_h) then obj.to_h
+        if    obj.is_a?(Hash)        then obj
+        elsif obj.respond_to?(:to_h) then obj.to_h
         else raise Error, "#{obj.inspect} is neither Hash nor responds to :to_h"
         end
       end
 
+      # Coerces obj to an Enumerable of key-value pairs
+      #
+      # @example
+      #   FormData.ensure_data([[:foo, :bar]]) # => [[:foo, :bar]]
+      #
+      # @api public
+      # @raise [Error] `obj` can't be coerced
+      # @return [Enumerable]
+      def ensure_data(obj)
+        if    obj.nil?                  then []
+        elsif obj.is_a?(Enumerable)     then obj
+        elsif obj.respond_to?(:to_h)    then obj.to_h
+        else raise Error, "#{obj.inspect} is neither Enumerable nor responds to :to_h"
+        end
+      end
+
       private
 
-      # Tells whenever data contains multipart data or not.
+      # Checks if data contains multipart data
       #
-      # @param [Hash] data
+      # @api private
+      # @param [Enumerable] data
       # @return [Boolean]
       def multipart?(data)
         data.any? do |_, v|
-          next true if v.is_a? FormData::Part
-          v.respond_to?(:to_ary) && v.to_ary.any? { |e| e.is_a? FormData::Part }
+          v.is_a?(Part) || (v.respond_to?(:to_ary) && v.to_ary.any?(Part))
         end
       end
     end

data/sig/http/form_data/composite_io.rbs

@@ -0,0 +1,32 @@
+module HTTP
+  module FormData
+    class CompositeIO
+      @index: Integer
+      @ios: Array[untyped]
+      @size: Integer?
+
+      # Creates a new CompositeIO from an array of IO-like objects
+      def initialize: (Array[untyped] ios) -> void
+
+      # Reads and returns content across multiple IO objects
+      def read: (?Integer? length, ?String? outbuf) -> String?
+
+      # Returns sum of all IO sizes
+      def size: () -> Integer
+
+      # Rewinds all IO objects and resets cursor
+      def rewind: () -> void
+
+      private
+
+      # Yields chunks with total length up to `length`
+      def read_chunks: (Integer? length) { (String chunk) -> void } -> void
+
+      # Reads chunk from current IO with length up to `max_length`
+      def readpartial: (Integer? max_length) -> String?
+
+      # Advances cursor to the next IO object
+      def advance_io: () -> void
+    end
+  end
+end

data/sig/http/form_data/file.rbs

@@ -0,0 +1,23 @@
+module HTTP
+  module FormData
+    class File < Part
+      DEFAULT_MIME: String
+
+      @autoclose: bool
+
+      # Creates a new File from a path or IO object
+      def initialize: (String | Pathname | untyped path_or_io, ?Hash[Symbol, untyped]? opts) -> void
+
+      # Closes the underlying IO if it was opened by this instance
+      def close: () -> void
+
+      private
+
+      # Wraps path_or_io into an IO object
+      def make_io: (String | Pathname | untyped path_or_io) -> untyped
+
+      # Determines filename for the given IO
+      def filename_for: (untyped io) -> String
+    end
+  end
+end

data/sig/http/form_data/multipart/param.rbs

@@ -0,0 +1,23 @@
+module HTTP
+  module FormData
+    class Multipart
+      class Param
+        include Readable
+
+        @name: String
+        @part: Part
+
+        # Initializes body part with headers and data
+        def initialize: (untyped name, untyped value) -> void
+
+        private
+
+        # Builds the MIME header for this part
+        def header: () -> String
+
+        # Builds Content-Disposition parameters string
+        def parameters: () -> String
+      end
+    end
+  end
+end

data/sig/http/form_data/multipart.rbs

@@ -0,0 +1,40 @@
+module HTTP
+  module FormData
+    class Multipart
+      include Readable
+
+      DEFAULT_CONTENT_TYPE: String
+
+      # Returns the multipart boundary string
+      attr_reader boundary: String
+
+      @content_type: _ToS
+
+      # Creates a new Multipart form data instance
+      def initialize: (untyped data, ?boundary: _ToS, ?content_type: _ToS) -> void
+
+      # Generates a boundary string for multipart form data
+      def self.generate_boundary: () -> String
+
+      # Returns MIME type for the Content-Type header
+      def content_type: () -> String
+
+      # Returns form data content size for Content-Length
+      alias content_length size
+
+      private
+
+      @glue: String?
+      @tail: String?
+
+      # Returns the boundary glue between parts
+      def glue: () -> String
+
+      # Returns the closing boundary tail
+      def tail: () -> String
+
+      # Coerces data into an array of Param objects
+      def parts: (untyped data) -> Array[Param]
+    end
+  end
+end

data/sig/http/form_data/part.rbs

@@ -0,0 +1,16 @@
+module HTTP
+  module FormData
+    class Part
+      include Readable
+
+      # Returns the content type of this part
+      attr_reader content_type: String?
+
+      # Returns the filename of this part
+      attr_reader filename: String?
+
+      # Creates a new Part with the given body and options
+      def initialize: (_ToS body, ?content_type: String?, ?filename: String?) -> void
+    end
+  end
+end

data/sig/http/form_data/readable.rbs

@@ -0,0 +1,19 @@
+module HTTP
+  module FormData
+    module Readable
+      @io: StringIO | CompositeIO
+
+      # Returns IO content as a String
+      def to_s: () -> String
+
+      # Reads and returns part of IO content
+      def read: (?Integer? length, ?String? outbuf) -> String?
+
+      # Returns IO size in bytes
+      def size: () -> Integer
+
+      # Rewinds the IO to the beginning
+      def rewind: () -> (Integer | void)
+    end
+  end
+end

data/sig/http/form_data/urlencoded.rbs

@@ -0,0 +1,46 @@
+module HTTP
+  module FormData
+    class Urlencoded
+      include Readable
+
+      self.@encoder: _Encoder?
+
+      # Sets custom form data encoder implementation
+      def self.encoder=: (untyped implementation) -> void
+
+      # Returns form data encoder implementation
+      def self.encoder: () -> _Encoder
+
+      # Default encoder for urlencoded form data
+      module DefaultEncoder
+        # Recursively encodes form data value
+        def self.encode: (untyped value, ?String? prefix) -> String
+
+        alias self.call self.encode
+
+        private
+
+        # Encodes an Array value
+        def self.encode_array: (Array[untyped] value, String? prefix) -> String
+
+        # Encodes an Array of key-value pairs
+        def self.encode_pairs: (Array[untyped] pairs) -> String
+
+        # Encodes a Hash value
+        def self.encode_hash: (Hash[untyped, untyped] hash, String? prefix) -> String
+
+        # URL-encodes a value
+        def self.escape: (untyped value) -> String
+      end
+
+      # Creates a new Urlencoded form data instance
+      def initialize: (untyped data, ?encoder: _Encoder?) -> void
+
+      # Returns MIME type for the Content-Type header
+      def content_type: () -> String
+
+      # Returns form data content size for Content-Length
+      alias content_length size
+    end
+  end
+end

data/sig/http/form_data/version.rbs

@@ -0,0 +1,5 @@
+module HTTP
+  module FormData
+    VERSION: String
+  end
+end