http-form_data 2.3.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e781be9d32ee208fa4d379569b05bd2d4e9f30c4b29e0895aaea20e8ae193206
-  data.tar.gz: 8745d97530d549d45e94f9901a50ba6f0ee88177074b2411c56f03f7ac66134c
+  metadata.gz: 3a38607435f5ac942c5b4f3d1e28c5910d151ccb978fbcaff0dc8d51a0932400
+  data.tar.gz: fe8f7bf0309d6f8dd178283aa40d2708b69d89a2c2535bf253370759b6b28b07
 SHA512:
-  metadata.gz: 12b410ec71a443a006e0ec62005bc4b829987bc562b0d9604d527b1e6cbfe82ea2ef73ce55d46ea3d3496159b3d0a2233dd6be5ab42a8766aaf7a5be78479e27
-  data.tar.gz: 2644255b6eaaf24b38658894134e62ea45b84dbb8802a4cc920dc2c219e8ca67e9bc432a1d53b84b970b4e26fa833a7d7780c95591b9b0b871eb2ab659fcf13d
+  metadata.gz: 36a8dc93a9ce4b47f7e35ebf9ea465baa6e0862660bc10b02623be502385102596c8493de46bb5c85890dba8f72f821e93c53ececeffc121d58c53e058a63e57
+  data.tar.gz: f387b4d0f46f4df352cda39732050f059ec178223635d2be008838094560291ee9bb1496920d823cbd422c22bcfb05c17844a632e743578dd5486aec672e057d

data/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.0] - 2026-03-16
+
+### Added
+
+- `Multipart` accepts a `content_type:` keyword to support `multipart/related`,
+  `multipart/mixed`, and other multipart content types. Defaults to
+  `multipart/form-data`.
+  ([#1](https://github.com/httprb/form_data/issues/1))
+- `FormData::File#close` for closing file handles opened from String paths or
+  Pathnames. When a File is created from an existing IO, `close` is a no-op.
+  ([#27](https://github.com/httprb/form_data/issues/27))
+- Accept any Enumerable (not just Hash or Array) as form data input for both
+  `Multipart` and `Urlencoded` encoders. This enables lazy enumerators and
+  custom collections as input.
+- `FormData.ensure_data` for coercing input to an Enumerable of key-value pairs.
+- Array of pairs input for `Multipart`, allowing duplicate parameter names and
+  preserved ordering.
+- Array of pairs input for `Urlencoded`, preserving duplicate keys.
+- RBS type signatures for all public and private APIs.
+- `sig/` directory shipped in the gem for downstream type checking.
+- `homepage_uri`, `source_code_uri`, `bug_tracker_uri`, and `documentation_uri`
+  gemspec metadata.
+
+### Changed
+
+- Default urlencoded encoder replaced with a custom implementation that supports
+  nested Hashes and Arrays (e.g., `{foo: {bar: "baz"}}` encodes as
+  `foo[bar]=baz`). Previously used `URI.encode_www_form`.
+- `FormData.ensure_hash` no longer treats `nil` as a special case; `nil.to_h`
+  returns `{}` which is used instead.
+
+### Removed
+
+- Ruby < 3.2 support.
+- Explicit JRuby support.
+- `FormData::File#mime_type` deprecated alias. Use `#content_type` instead.
+- `:mime_type` option in `FormData::File#initialize`. Use `:content_type` instead.
+
+## [2.3.0] - 2020-03-08
+
+### Added
+
+- Per-instance encoder for `HTTP::FormData::Urlencoded`.
+  ([#29](https://github.com/httprb/form_data/pull/29) by [@summera])
+
+## [2.2.0] - 2020-01-09
+
+### Fixed
+
+- Ruby 2.7 compatibility.
+  ([#28](https://github.com/httprb/form_data/pull/28) by [@janko])
+
+## [2.1.1] - 2018-06-01
+
+### Added
+
+- Allow overriding urlencoded form data encoder.
+  ([#23](https://github.com/httprb/form_data/pull/23) by [@FabienChaynes])
+
+## [2.1.0] - 2018-03-05
+
+### Fixed
+
+- Rewind content at the end of `Readable#to_s`.
+  ([#21](https://github.com/httprb/form_data/pull/21) by [@janko-m])
+- Buffer encoding.
+  ([#19](https://github.com/httprb/form_data/pull/19) by [@HoneyryderChuck])
+
+## [2.0.0] - 2017-10-01
+
+### Fixed
+
+- Add CRLF character to end of multipart body.
+  ([#17](https://github.com/httprb/form_data/pull/17) by [@mhickman])
+
+## [2.0.0.pre2] - 2017-05-11
+
+### Added
+
+- Streaming for urlencoded form data.
+  ([#14](https://github.com/httprb/form_data/pull/14) by [@janko-m])
+
+## [2.0.0.pre1] - 2017-05-10
+
+### Added
+
+- Form data streaming.
+  ([#12](https://github.com/httprb/form_data.rb/pull/12) by [@janko-m])
+
+## [1.0.2] - 2017-05-08
+
+### Added
+
+- Allow setting Content-Type on non-file parts.
+  ([#5](https://github.com/httprb/form_data.rb/issues/5) by [@abotalov])
+- Creation of file parts without filename.
+  ([#6](https://github.com/httprb/form_data.rb/issues/6) by [@abotalov])
+
+### Deprecated
+
+- `HTTP::FormData::File#mime_type`. Use `#content_type` instead.
+  ([#11](https://github.com/httprb/form_data.rb/pull/11) by [@ixti])
+
+## [1.0.1] - 2015-03-31
+
+### Fixed
+
+- Usage of URI module.
+
+## [1.0.0] - 2015-01-04
+
+### Changed
+
+- Gem renamed to `http-form_data` as `FormData` is no longer a top-level
+  constant: `FormData` → `HTTP::FormData`.
+
+## [0.1.0] - 2015-01-02
+
+### Added
+
+- `nil` support to `FormData#ensure_hash`.
+
+### Changed
+
+- Moved repo under `httprb` organization on GitHub.
+
+## [0.0.1] - 2014-12-15
+
+### Added
+
+- Initial release.
+
+[3.0.0]: https://github.com/httprb/form_data/compare/v2.3.0...v3.0.0
+[2.3.0]: https://github.com/httprb/form_data/compare/v2.2.0...v2.3.0
+[2.2.0]: https://github.com/httprb/form_data/compare/v2.1.1...v2.2.0
+[2.1.1]: https://github.com/httprb/form_data/compare/v2.1.0...v2.1.1
+[2.1.0]: https://github.com/httprb/form_data/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/httprb/form_data/compare/v2.0.0.pre2...v2.0.0
+[2.0.0.pre2]: https://github.com/httprb/form_data/compare/v2.0.0.pre1...v2.0.0.pre2
+[2.0.0.pre1]: https://github.com/httprb/form_data/compare/v1.0.2...v2.0.0.pre1
+[1.0.2]: https://github.com/httprb/form_data/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/httprb/form_data/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/httprb/form_data/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/httprb/form_data/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/httprb/form_data/releases/tag/v0.0.1
+
+[@abotalov]: https://github.com/abotalov
+[@FabienChaynes]: https://github.com/FabienChaynes
+[@HoneyryderChuck]: https://github.com/HoneyryderChuck
+[@ixti]: https://github.com/ixti
+[@janko]: https://github.com/janko
+[@janko-m]: https://github.com/janko-m
+[@mhickman]: https://github.com/mhickman
+[@summera]: https://github.com/summera

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2015-2017 Alexey V Zapparov
+Copyright (c) 2015-2026 Alexey V Zapparov
 
 MIT License
 

data/README.md

@@ -1,9 +1,11 @@
 # HTTP::FormData
 
 [![Gem Version](https://badge.fury.io/rb/http-form_data.svg)](http://rubygems.org/gems/http-form_data)
-[![Build Status](https://secure.travis-ci.org/httprb/form_data.svg?branch=master)](http://travis-ci.org/httprb/form_data)
-[![Code Climate](https://codeclimate.com/github/httprb/form_data.svg)](https://codeclimate.com/github/httprb/form_data)
-[![Coverage Status](https://coveralls.io/repos/httprb/form_data.rb/badge.svg?branch=master)](https://coveralls.io/r/httprb/form_data.rb)
+[![Test](https://github.com/httprb/form_data/actions/workflows/test.yml/badge.svg)](https://github.com/httprb/form_data/actions/workflows/test.yml)
+[![Lint](https://github.com/httprb/form_data/actions/workflows/lint.yml/badge.svg)](https://github.com/httprb/form_data/actions/workflows/lint.yml)
+[![Type Check](https://github.com/httprb/form_data/actions/workflows/typecheck.yml/badge.svg)](https://github.com/httprb/form_data/actions/workflows/typecheck.yml)
+[![Mutant](https://github.com/httprb/form_data/actions/workflows/mutant.yml/badge.svg)](https://github.com/httprb/form_data/actions/workflows/mutant.yml)
+[![Docs](https://github.com/httprb/form_data/actions/workflows/docs.yml/badge.svg)](https://github.com/httprb/form_data/actions/workflows/docs.yml)
 
 Utility-belt to build form data request bodies.
 
@@ -58,11 +60,10 @@ form = HTTP::FormData.create({
 This library aims to support and is [tested against][ci] the following Ruby
 versions:
 
-* Ruby 2.4.x
-* Ruby 2.5.x
-* Ruby 2.6.x
-* Ruby 2.7.x
-* JRuby 9.1.x.x
+* Ruby 3.2
+* Ruby 3.3
+* Ruby 3.4
+* Ruby 4.0
 
 If something doesn't work on one of these versions, it's a bug.
 
@@ -89,9 +90,9 @@ dropped.
 
 ## Copyright
 
-Copyright (c) 2015-2017 Alexey V Zapparov.
+Copyright (c) 2015-2026 Alexey V Zapparov.
 See [LICENSE.txt][license] for further details.
 
 
-[ci]:       http://travis-ci.org/httprb/form_data.rb
+[ci]:       https://github.com/httprb/form_data/actions
 [license]:  https://github.com/httprb/form_data.rb/blob/master/LICENSE.txt

data/http-form_data.gemspec

@@ -1,25 +1,39 @@
 # frozen_string_literal: true
 
-lib = File.expand_path("../lib", __FILE__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "http/form_data/version"
+require_relative "lib/http/form_data/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "http-form_data"
   spec.version       = HTTP::FormData::VERSION
-  spec.homepage      = "https://github.com/httprb/form_data.rb"
   spec.authors       = ["Aleksey V Zapparov"]
   spec.email         = ["ixti@member.fsf.org"]
+
+  spec.summary       = "Build form data request bodies"
+  spec.homepage      = "https://github.com/httprb/form_data"
   spec.license       = "MIT"
-  spec.summary       = "http-form_data-#{HTTP::FormData::VERSION}"
-  spec.description   = <<-DESC.gsub(/^\s+> /m, "").tr("\n", " ").strip
-  > Utility-belt to build form data request bodies.
-  > Provides support for `application/x-www-form-urlencoded` and
-  > `multipart/form-data` types.
-  DESC
-
-  spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin\/}).map { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)\/})
+
+  spec.description   = <<~DESCRIPTION.strip.gsub(/\s+/, " ")
+    Utility-belt to build form data request bodies.
+    Provides support for `application/x-www-form-urlencoded` and
+    `multipart/form-data` types.
+  DESCRIPTION
+
+  spec.metadata["homepage_uri"]          = spec.homepage
+  spec.metadata["source_code_uri"]       = "#{spec.homepage}/tree/v#{spec.version}"
+  spec.metadata["bug_tracker_uri"]       = "#{spec.homepage}/issues"
+  spec.metadata["changelog_uri"]         = "#{spec.homepage}/blob/v#{spec.version}/CHANGELOG.md"
+  spec.metadata["documentation_uri"]     = "https://www.rubydoc.info/gems/http-form_data/#{spec.version}"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    extras = %w[CHANGELOG.md LICENSE.txt README.md] << File.basename(__FILE__)
+
+    ls.readlines("\x0", chomp: true).select do |f|
+      f.start_with?("lib/", "sig/http/") || extras.include?(f)
+    end
+  end
+
   spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 3.2"
 end

data/lib/http/form_data/composite_io.rb

@@ -6,27 +6,36 @@ 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
-        @buffer = "".b
-        @ios    = ios.map do |io|
+        @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"
+                  "#{io.inspect} is neither a String nor an IO object"
           end
         end
       end
 
-      # Reads and returns partial content acrosss multiple IO objects.
+      # 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
@@ -37,12 +46,24 @@ module HTTP
         data unless length && data.empty?
       end
 
-      # Returns sum of all IO sizes.
+      # Returns sum of all IO sizes
+      #
+      # @example
+      #   composite_io.size # => 11
+      #
+      # @api public
+      # @return [Integer]
       def size
-        @size ||= @ios.map(&:size).inject(0, :+)
+        @size ||= @ios.sum(&:size)
       end
 
-      # Rewinds all IO objects and set cursor to the first IO object.
+      # Rewinds all IO objects and resets cursor
+      #
+      # @example
+      #   composite_io.rewind
+      #
+      # @api public
+      # @return [void]
       def rewind
         @ios.each(&:rewind)
         @index = 0
@@ -50,39 +71,36 @@ module HTTP
 
       private
 
-      # Yields chunks with total length up to `length`.
-      def read_chunks(length = nil)
+      # 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?
 
-          length -= chunk.bytesize
+          remaining = length - chunk.bytesize
+          break if remaining.zero?
 
-          break if length.zero?
+          length = remaining
         end
       end
 
-      # Reads chunk from current IO with length up to `max_length`.
-      def readpartial(max_length = nil)
-        while current_io
-          chunk = current_io.read(max_length, @buffer)
+      # 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?
 
-          advance_io
+          @index += 1
         end
       end
-
-      # Returns IO object under the cursor.
-      def current_io
-        @ios[@index]
-      end
-
-      # Advances cursor to the next IO object.
-      def advance_io
-        @index += 1
-      end
     end
   end
 end

data/lib/http/form_data/file.rb

@@ -7,7 +7,7 @@ module HTTP
     # @example Usage with StringIO
     #
     #  io = StringIO.new "foo bar baz"
-    #  FormData::File.new io, :filename => "foobar.txt"
+    #  FormData::File.new io, filename: "foobar.txt"
     #
     # @example Usage with IO
     #
@@ -22,45 +22,70 @@ module HTTP
       # Default MIME type
       DEFAULT_MIME = "application/octet-stream"
 
-      # @deprecated Use #content_type instead
-      alias mime_type content_type
-
+      # 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 [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 = {})
+      #   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)
 
-        if opts.key? :mime_type
-          warn "[DEPRECATED] :mime_type option deprecated, use :content_type"
-          opts[:content_type] = opts[:mime_type]
-        end
-
         @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)
-        if path_or_io.is_a?(String)
-          ::File.open(path_or_io, :binmode => true)
-        elsif defined?(Pathname) && path_or_io.is_a?(Pathname)
-          path_or_io.open(:binmode => true)
-        else
-          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
+          ::File.basename(io.path)
         else
           "stream-#{io.object_id}"
         end

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

@@ -10,7 +10,7 @@ module HTTP
       class Param
         include Readable
 
-        # Initializes body part with headers and data.
+        # Initializes body part with headers and data
         #
         # @example With {FormData::File} value
         #
@@ -25,66 +25,36 @@ module HTTP
         #
         #   ixti
         #
-        # @return [String]
+        # @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 =
-            if value.is_a?(FormData::Part)
-              value
-            else
-              FormData::Part.new(value)
-            end
-
-          @io = CompositeIO.new [header, @part, footer]
-        end
-
-        # Flattens given `data` Hash into an array of `Param`'s.
-        # Nested array are unwinded.
-        # Behavior is similar to `URL.encode_www_form`.
-        #
-        # @param [Hash] data
-        # @return [Array<FormData::MultiPart::Param>]
-        def self.coerce(data)
-          params = []
-
-          data.each do |name, values|
-            Array(values).each do |value|
-              params << new(name, value)
-            end
-          end
-
-          params
+          @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 = "".b
-          header << "Content-Disposition: form-data; #{parameters}#{CRLF}"
-          header << "Content-Type: #{content_type}#{CRLF}" if content_type
+          header = "Content-Disposition: form-data; #{parameters}#{CRLF}"
+          header << "Content-Type: #{@part.content_type}#{CRLF}" if @part.content_type
           header << CRLF
-          header
         end
 
+        # Builds Content-Disposition parameters string
+        #
+        # @api private
+        # @return [String]
         def parameters
-          parameters = { :name => @name }
-          parameters[:filename] = filename if filename
-          parameters.map { |k, v| "#{k}=#{v.inspect}" }.join("; ")
-        end
-
-        def content_type
-          @part.content_type
-        end
-
-        def filename
-          @part.filename
-        end
-
-        def footer
-          CRLF.dup
+          params = "name=#{@name.inspect}"
+          params << "; filename=#{@part.filename.inspect}" if @part.filename
+          params
         end
       end
     end