protocol-multipart 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f780cb8777ab2bcdacd17295c0017d194f0e43e864b76064c2f5a17feaeebce
-  data.tar.gz: 5b6c27f78eb2dc61fe351ae3c493847413580af1b6c194cd090a6eeca9a46ad6
+  metadata.gz: 891a0cd8210426411b1b44e2304bdfb282ab907adf1f3bf53089b2ecd6407a44
+  data.tar.gz: 7d24bcf5941c609e11dea28e1554e03c8696282a90f5d344c3aad580fa1484de
 SHA512:
-  metadata.gz: '08d99314fcd9dbafde62056380a4d17a4288f5d0fef2cc33a00ac55ddcfd9bf2dfeaabf4e26c209a8b94b7bd01c553e883767323143b7f2f55e04e02a571ef0c'
-  data.tar.gz: 0770603bb53169f98a8fd2582d464c1677fe906fddbebc3470f14e426d3bdc4db9cf05a3757ba615724fefa9510ad7cb11085becbc884d7950593a93ae00f3f1
+  metadata.gz: f515cd40482a06d977d689f2d43a917aef4193f5bbd2e23d0fe7b13fdc5984d42fbe5a8841736ac1d3deb1e9fa8ced71788ec17d5aacd4cedd2e17f3ac75219e
+  data.tar.gz: e96bc422119c3c7001b3e6588281964ebab9445a6a52e8293ffb1035f01172a2f77e6497db43f36b2cd7cf4cbc319714c8352c4ae4946d8d9dbc0bc87e7d5441

data/lib/protocol/multipart/form_data/parser.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../form_data"
+
+require "protocol/url/form_data/nested"
+
+module Protocol
+	module Multipart
+		class FormData
+			# A configurable parser for `multipart/form-data` bodies.
+			class Parser
+				CONTENT_TYPE = "multipart/form-data"
+				
+				# Initialize the form data parser.
+				# @parameter maximum_field_size [Integer | Nil] The maximum size of each buffered field.
+				# @parameter maximum_upload_size [Integer | Nil] The maximum size of each file upload.
+				# @parameter maximum_total_size [Integer | Nil] The maximum combined size of all fields and uploads.
+				# @parameter maximum_depth [Integer | Nil] The maximum depth of a bracketed form name.
+				# @parameter options [Hash] Limits passed to the underlying multipart parser.
+				def initialize(maximum_field_size: MAXIMUM_FIELD_SIZE, maximum_upload_size: MAXIMUM_UPLOAD_SIZE, maximum_total_size: MAXIMUM_TOTAL_SIZE, maximum_depth: Protocol::URL::FormData::Nested::MAXIMUM_DEPTH, **options)
+					if maximum_depth and maximum_depth < 0
+						raise ArgumentError, "Form data limits must be non-negative!"
+					end
+					
+					@maximum_field_size = maximum_field_size
+					@maximum_upload_size = maximum_upload_size
+					@maximum_total_size = maximum_total_size
+					@maximum_depth = maximum_depth
+					@options = options
+				end
+				
+				# Parse multipart form data into a nested hash.
+				#
+				# When a block is given, each value is passed through the block before assignment. The value returned by the block is assigned to the result. Uploads require a block because they must be consumed before parsing advances to the next part.
+				#
+				# @parameter readable [IO, IO::Stream] The readable stream containing multipart form data.
+				# @parameter result [Object] The result to populate. It must support `#add` and `#to_h`.
+				# @parameter boundary [String] The multipart boundary.
+				# @yields {|name, value| ...} Each form entry before assignment.
+				# @returns [Hash] The nested form data.
+				def parse(readable, result = make_result, boundary:)
+					each(readable, boundary:) do |name, value|
+						if block_given?
+							value = yield(name, value)
+						elsif value.is_a?(Upload)
+							raise ArgumentError, "A block is required to consume file uploads!"
+						end
+						
+						result.add(name, value)
+					end
+					
+					return result.to_h
+				end
+				
+				# Incrementally enumerate multipart form data.
+				#
+				# Fields are yielded as strings. File uploads are yielded as streaming {Upload} instances and are only readable during the corresponding block invocation.
+				#
+				# @parameter readable [IO, IO::Stream] The readable stream containing multipart form data.
+				# @parameter boundary [String] The multipart boundary.
+				# @yields {|name, value| ...} Each form field name and its string or streaming upload value.
+				# @returns [Enumerator | Boolean] An enumerator without a block, or true when complete.
+				def each(readable, boundary:)
+					return to_enum(__method__, readable, boundary:) unless block_given?
+					
+					total_limit = ByteLimit.new(@maximum_total_size, name: :total_size)
+					parser = Multipart::Parser.new(readable, boundary, **@options)
+					
+					parser.each do |part|
+						disposition = part.headers["content-disposition"]
+						
+						unless disposition&.type == "form-data" and name = disposition["name"]
+							raise ArgumentError, "Multipart form part is missing a form-data name!"
+						end
+						
+						if filename = disposition["filename"]
+							upload = Upload.new(part, filename, @maximum_upload_size, total_limit)
+							yield name, upload
+							upload.discard
+						else
+							field_limit = ByteLimit.new(@maximum_field_size, name: :field_size)
+							value = String.new.b
+							
+							part.each do |chunk|
+								field_limit.consume(chunk.bytesize)
+								total_limit.consume(chunk.bytesize)
+								value << chunk
+							end
+							
+							yield name, value
+						end
+					end
+				end
+				
+				private
+				
+				def make_result
+					return Protocol::URL::FormData::Nested.new(maximum_depth: @maximum_depth)
+				end
+			end
+		end
+	end
+end

data/lib/protocol/multipart/form_data.rb

@@ -78,50 +78,6 @@ module Protocol
 				end
 			end
 			
-			# Parse multipart form data.
-			#
-			# Fields are yielded as strings. File uploads are yielded as streaming {Upload} instances and are only readable during the corresponding block invocation.
-			#
-			# @parameter readable [IO, IO::Stream] The readable stream containing multipart form data.
-			# @parameter boundary [String] The multipart boundary.
-			# @parameter maximum_field_size [Integer | Nil] The maximum size of each buffered field.
-			# @parameter maximum_upload_size [Integer | Nil] The maximum size of each file upload.
-			# @parameter maximum_total_size [Integer | Nil] The maximum combined size of all fields and uploads.
-			# @yields {|name, value| ...} Each form field name and its string or streaming upload value.
-			def self.parse(readable, boundary, maximum_field_size: MAXIMUM_FIELD_SIZE, maximum_upload_size: MAXIMUM_UPLOAD_SIZE, maximum_total_size: MAXIMUM_TOTAL_SIZE, **options)
-				unless block_given?
-					return enum_for(__method__, readable, boundary, maximum_field_size: maximum_field_size, maximum_upload_size: maximum_upload_size, maximum_total_size: maximum_total_size, **options)
-				end
-				
-				total_limit = ByteLimit.new(maximum_total_size, name: :total_size)
-				parser = Parser.new(readable, boundary, **options)
-				
-				parser.each do |part|
-					disposition = part.headers["content-disposition"]
-					
-					unless disposition&.type == "form-data" and name = disposition["name"]
-						raise ArgumentError, "Multipart form part is missing a form-data name!"
-					end
-					
-					if filename = disposition["filename"]
-						upload = Upload.new(part, filename, maximum_upload_size, total_limit)
-						yield name, upload
-						upload.discard
-					else
-						field_limit = ByteLimit.new(maximum_field_size, name: :field_size)
-						value = String.new.b
-						
-						part.each do |chunk|
-							field_limit.consume(chunk.bytesize)
-							total_limit.consume(chunk.bytesize)
-							value << chunk
-						end
-						
-						yield name, value
-					end
-				end
-			end
-			
 			# Returns the MIME type for form data.
 			#
 			# @returns [String] The MIME type "multipart/form-data".
@@ -147,3 +103,5 @@ module Protocol
 		end
 	end
 end
+
+require_relative "form_data/parser"

data/lib/protocol/multipart/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module Multipart
-		VERSION = "0.2.0"
+		VERSION = "0.3.0"
 	end
 end

data/readme.md

@@ -6,6 +6,12 @@
 
 Please see the [project releases](https://socketry.github.io/protocol-multipart/releases/index) for all releases.
 
+### v0.3.0
+
+  - Add a configurable `Protocol::Multipart::FormData::Parser` which parses a streaming body and explicit boundary into nested arguments.
+  - Use `Protocol::URL::FormData::Nested` so URL-encoded and multipart forms share hierarchy semantics.
+  - Allow `Protocol::Multipart::FormData::Parser#parse` to populate a supplied result object.
+
 ### v0.2.0
 
   - Add strict, policy-driven parsing for parameterized `Content-Type` and `Content-Disposition` fields using `Protocol::Multipart::Headers`.

data/releases.md

@@ -1,5 +1,11 @@
 # Releases
 
+## v0.3.0
+
+  - Add a configurable `Protocol::Multipart::FormData::Parser` which parses a streaming body and explicit boundary into nested arguments.
+  - Use `Protocol::URL::FormData::Nested` so URL-encoded and multipart forms share hierarchy semantics.
+  - Allow `Protocol::Multipart::FormData::Parser#parse` to populate a supplied result object.
+
 ## v0.2.0
 
   - Add strict, policy-driven parsing for parameterized `Content-Type` and `Content-Disposition` fields using `Protocol::Multipart::Headers`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-multipart
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.67'
+- !ruby/object:Gem::Dependency
+  name: protocol-url
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -75,6 +89,7 @@ files:
 - lib/protocol/multipart/byte_limit.rb
 - lib/protocol/multipart/escape.rb
 - lib/protocol/multipart/form_data.rb
+- lib/protocol/multipart/form_data/parser.rb
 - lib/protocol/multipart/header/content_disposition.rb
 - lib/protocol/multipart/header/content_type.rb
 - lib/protocol/multipart/header/parameterized.rb