Add File#close to prevent file handle leaks

When FormData::File is created from a String path or Pathname, the
initializer opens a file handle that was never closed. Add a #close
method that closes the underlying IO when it was opened internally.
When created from a caller-provided IO, close is a no-op.

Closes #27.

Author: sferik

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- `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.

lib/http/form_data/file.rb

@@ -55,10 +55,29 @@ def initialize(path_or_io, opts = nil) # rubocop:disable Lint/MissingSuper
         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

sig/http/form_data/file.rbs

@@ -3,12 +3,17 @@ module HTTP
     class File < Part
       DEFAULT_MIME: String
 
+      @autoclose: bool
+
       # Deprecated alias for content_type
       alias mime_type content_type
 
       # 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

test/http/form_data/file_test.rb

@@ -424,4 +424,54 @@ def test_read_after_eof_returns_empty_string_without_length
 
     assert_equal "", form_file.read
   end
+
+  # --- File#close ---
+
+  def test_close_with_string_path_closes_io
+    form_file = HTTP::FormData::File.new(fixture("the-http-gem.info").to_s)
+    form_file.read
+    form_file.close
+
+    assert_raises(IOError) { form_file.read }
+  end
+
+  def test_close_with_pathname_closes_io
+    form_file = HTTP::FormData::File.new(fixture("the-http-gem.info"))
+    form_file.read
+    form_file.close
+
+    assert_raises(IOError) { form_file.read }
+  end
+
+  def test_close_with_io_does_not_close
+    io = StringIO.new("hello")
+    form_file = HTTP::FormData::File.new(io)
+    form_file.close
+
+    assert_equal "hello", io.read
+  end
+
+  def test_close_is_idempotent
+    form_file = HTTP::FormData::File.new(fixture("the-http-gem.info").to_s)
+    form_file.close
+    form_file.close
+  end
+
+  def test_close_with_string_subclass_closes_io
+    str_subclass = Class.new(String)
+    form_file = HTTP::FormData::File.new(str_subclass.new(fixture("the-http-gem.info").to_s))
+    form_file.read
+    form_file.close
+
+    assert_raises(IOError) { form_file.read }
+  end
+
+  def test_close_with_pathname_subclass_closes_io
+    pathname_subclass = Class.new(Pathname)
+    form_file = HTTP::FormData::File.new(pathname_subclass.new(fixture("the-http-gem.info").to_s))
+    form_file.read
+    form_file.close
+
+    assert_raises(IOError) { form_file.read }
+  end
 end