protocol-multipart 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f780cb8777ab2bcdacd17295c0017d194f0e43e864b76064c2f5a17feaeebce
-  data.tar.gz: 5b6c27f78eb2dc61fe351ae3c493847413580af1b6c194cd090a6eeca9a46ad6
+  metadata.gz: 32d7a5d9ab53cbe80b179ea8ff2ac318415484eea858c4fc8f170c2bdcdb998a
+  data.tar.gz: 8540f4f11737134c960c1bcdd6303a2418c17ca6c754864e9b83204bc93410fb
 SHA512:
-  metadata.gz: '08d99314fcd9dbafde62056380a4d17a4288f5d0fef2cc33a00ac55ddcfd9bf2dfeaabf4e26c209a8b94b7bd01c553e883767323143b7f2f55e04e02a571ef0c'
-  data.tar.gz: 0770603bb53169f98a8fd2582d464c1677fe906fddbebc3470f14e426d3bdc4db9cf05a3757ba615724fefa9510ad7cb11085becbc884d7950593a93ae00f3f1
+  metadata.gz: ce50fbd0c0bb2afc3396eba792684b2db2cfd839808bede5b0e38196966481d5924a1548dabbb6f42621b7afe0039ba8342e27c22ee815de142cc1e266ac7ee1
+  data.tar.gz: 534c8bbc606b71e2d532d861a7d1633c53e28188f7542c1d5aa5000b758715a2eecad9ab1ed047a0f69d6e9def50ba019fe0f0e3965cf979e3c99aa4b1d5affe

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 field_size_limit [Integer | Nil] The buffered field size limit.
+				# @parameter upload_size_limit [Integer | Nil] The file upload size limit.
+				# @parameter total_size_limit [Integer | Nil] The combined size limit for all fields and uploads.
+				# @parameter depth_limit [Integer | Nil] The bracketed form name depth limit.
+				# @parameter options [Hash] Limits passed to the underlying multipart parser.
+				def initialize(field_size_limit: FIELD_SIZE_LIMIT, upload_size_limit: UPLOAD_SIZE_LIMIT, total_size_limit: TOTAL_SIZE_LIMIT, depth_limit: Protocol::URL::FormData::Nested::DEPTH_LIMIT, **options)
+					if depth_limit and depth_limit < 0
+						raise ArgumentError, "Form data limits must be non-negative!"
+					end
+					
+					@field_size_limit = field_size_limit
+					@upload_size_limit = upload_size_limit
+					@total_size_limit = total_size_limit
+					@depth_limit = depth_limit
+					@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_size_limit = ByteLimit.new(@total_size_limit, 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, @upload_size_limit, total_size_limit)
+							yield name, upload
+							upload.discard
+						else
+							field_size_limit = ByteLimit.new(@field_size_limit, name: :field_size)
+							value = String.new.b
+							
+							part.each do |chunk|
+								field_size_limit.consume(chunk.bytesize)
+								total_size_limit.consume(chunk.bytesize)
+								value << chunk
+							end
+							
+							yield name, value
+						end
+					end
+				end
+				
+				private
+				
+				def make_result
+					return Protocol::URL::FormData::Nested.new(depth_limit: @depth_limit)
+				end
+			end
+		end
+	end
+end

data/lib/protocol/multipart/form_data.rb

@@ -16,27 +16,27 @@ module Protocol
 		class FormData < Mixed
 			include Escape
 			
-			# The default maximum size of a buffered form field.
-			MAXIMUM_FIELD_SIZE = 2 * 1024 * 1024
+			# The buffered form field size limit.
+			FIELD_SIZE_LIMIT = 2 * 1024 * 1024
 			
-			# The default maximum size of a streamed file upload.
-			MAXIMUM_UPLOAD_SIZE = 128 * 1024 * 1024
+			# The streamed file upload size limit.
+			UPLOAD_SIZE_LIMIT = 128 * 1024 * 1024
 			
-			# The default maximum combined size of all form fields and file uploads.
-			MAXIMUM_TOTAL_SIZE = 256 * 1024 * 1024
+			# The combined size limit for all form fields and file uploads.
+			TOTAL_SIZE_LIMIT = 256 * 1024 * 1024
 			
 			# A file upload yielded while parsing form data.
 			class Upload
 				# Initialize a streamed file upload.
 				# @parameter part [Parser::Part] The underlying multipart part.
 				# @parameter filename [String] The submitted filename.
-				# @parameter maximum_size [Integer | Nil] The maximum upload size.
-				# @parameter total_limit [ByteLimit] The shared form-data size limit.
-				def initialize(part, filename, maximum_size, total_limit)
+				# @parameter size_limit [Integer | Nil] The upload size limit.
+				# @parameter total_size_limit [ByteLimit] The shared form-data size limit.
+				def initialize(part, filename, size_limit, total_size_limit)
 					@part = part
 					@filename = filename
-					@limit = ByteLimit.new(maximum_size, name: :upload_size)
-					@total_limit = total_limit
+					@size_limit = ByteLimit.new(size_limit, name: :upload_size)
+					@total_size_limit = total_size_limit
 				end
 				
 				# The submitted filename.
@@ -49,7 +49,7 @@ module Protocol
 				
 				# The number of upload bytes consumed so far.
 				def size
-					@limit.size
+					@size_limit.size
 				end
 				
 				# Whether the complete upload has been consumed.
@@ -63,8 +63,8 @@ module Protocol
 					return to_enum(:each, chunk_size) unless block_given?
 					
 					@part.each(chunk_size) do |chunk|
-						@limit.consume(chunk.bytesize)
-						@total_limit.consume(chunk.bytesize)
+						@size_limit.consume(chunk.bytesize)
+						@total_size_limit.consume(chunk.bytesize)
 						yield chunk
 					end
 					
@@ -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/parser.rb

@@ -14,17 +14,17 @@ module Protocol
 			HEADER_PATTERN = /\A([!-9;-~]+):[ \t]*([^\x00-\x08\x0a-\x1f\x7f]*)\z/.freeze
 			private_constant :HEADER_PATTERN
 			
-			# The default maximum number of preamble bytes before the first boundary.
-			MAXIMUM_PREAMBLE_SIZE = 64 * 1024
+			# The preamble size limit.
+			PREAMBLE_SIZE_LIMIT = 64 * 1024
 			
-			# The default maximum number of header bytes in each part.
-			MAXIMUM_HEADER_SIZE = 64 * 1024
+			# The header size limit for each part.
+			HEADER_SIZE_LIMIT = 64 * 1024
 			
-			# The default maximum number of headers in each part.
-			MAXIMUM_HEADER_COUNT = 64
+			# The header count limit for each part.
+			HEADER_COUNT_LIMIT = 64
 			
-			# The default maximum number of parts.
-			MAXIMUM_PART_COUNT = 128
+			# The part count limit.
+			PART_COUNT_LIMIT = 128
 			
 			# Represents a single part within a multipart message.
 			class Part
@@ -163,12 +163,12 @@ module Protocol
 			#
 			# @parameter readable [IO, IO::Stream] The readable stream containing multipart data.
 			# @parameter boundary [String] The boundary string that separates the parts.
-			# @parameter maximum_preamble_size [Integer | Nil] The maximum preamble size, or nil for no limit.
-			# @parameter maximum_header_size [Integer | Nil] The maximum header size per part, or nil for no limit.
-			# @parameter maximum_header_count [Integer | Nil] The maximum header count per part, or nil for no limit.
-			# @parameter maximum_part_count [Integer | Nil] The maximum part count, or nil for no limit.
-			def initialize(readable, boundary, maximum_preamble_size: MAXIMUM_PREAMBLE_SIZE, maximum_header_size: MAXIMUM_HEADER_SIZE, maximum_header_count: MAXIMUM_HEADER_COUNT, maximum_part_count: MAXIMUM_PART_COUNT)
-				limits = [maximum_preamble_size, maximum_header_size, maximum_header_count, maximum_part_count]
+			# @parameter preamble_size_limit [Integer | Nil] The preamble size limit, or nil for no limit.
+			# @parameter header_size_limit [Integer | Nil] The header size limit per part, or nil for no limit.
+			# @parameter header_count_limit [Integer | Nil] The header count limit per part, or nil for no limit.
+			# @parameter part_count_limit [Integer | Nil] The part count limit, or nil for no limit.
+			def initialize(readable, boundary, preamble_size_limit: PREAMBLE_SIZE_LIMIT, header_size_limit: HEADER_SIZE_LIMIT, header_count_limit: HEADER_COUNT_LIMIT, part_count_limit: PART_COUNT_LIMIT)
+				limits = [preamble_size_limit, header_size_limit, header_count_limit, part_count_limit]
 				
 				if limits.any?{|limit| limit and limit < 0}
 					raise ArgumentError, "Multipart limits must be non-negative!"
@@ -176,10 +176,10 @@ module Protocol
 				
 				@readable = IO::Stream(readable)
 				@boundary = boundary
-				@maximum_preamble_size = maximum_preamble_size
-				@maximum_header_size = maximum_header_size
-				@maximum_header_count = maximum_header_count
-				@maximum_part_count = maximum_part_count
+				@preamble_size_limit = preamble_size_limit
+				@header_size_limit = header_size_limit
+				@header_count_limit = header_count_limit
+				@part_count_limit = part_count_limit
 				
 				@boundary_marker = "--#{@boundary}\r\n".freeze
 			end
@@ -195,12 +195,12 @@ module Protocol
 				
 				# Read lines until we find the first boundary:
 				while true
-					if line = read_line(preamble_size, @maximum_preamble_size, allowance: @boundary_marker.bytesize, chomp: false)
+					if line = read_line(preamble_size, @preamble_size_limit, allowance: @boundary_marker.bytesize, chomp: false)
 						if line == @boundary_marker
 							break
 						else
 							preamble_size += line.bytesize
-							check_limit(:preamble_size, preamble_size, @maximum_preamble_size)
+							check_limit(:preamble_size, preamble_size, @preamble_size_limit)
 						end
 					else
 						# End of stream reached without finding boundary:
@@ -212,7 +212,7 @@ module Protocol
 				
 				while true
 					part_count += 1
-					check_limit(:part_count, part_count, @maximum_part_count)
+					check_limit(:part_count, part_count, @part_count_limit)
 					
 					part = read_part
 					break unless part
@@ -234,18 +234,18 @@ module Protocol
 			
 			private
 			
-			def read_line(size, maximum, allowance: 0, chomp:)
-				if maximum
-					limit = maximum - size + allowance + 1
+			def read_line(size, limit, allowance: 0, chomp:)
+				if limit
+					limit = limit - size + allowance + 1
 					return @readable.gets("\r\n", limit, chomp: chomp)
 				else
 					return @readable.gets("\r\n", chomp: chomp)
 				end
 			end
 			
-			def check_limit(name, value, maximum)
-				if maximum and value > maximum
-					raise RangeError, "Multipart #{name} exceeded limit of #{maximum}!"
+			def check_limit(name, value, limit)
+				if limit and value > limit
+					raise RangeError, "Multipart #{name} exceeded limit of #{limit}!"
 				end
 			end
 			
@@ -255,18 +255,18 @@ module Protocol
 				header_count = 0
 				
 				# Read headers until empty line
-				while line = read_line(header_size, @maximum_header_size, allowance: 2, chomp: true)
+				while line = read_line(header_size, @header_size_limit, allowance: 2, chomp: true)
 					if line.empty?
 						break # End of headers
 					end
 					
 					header_size += line.bytesize + 2
-					check_limit(:header_size, header_size, @maximum_header_size)
+					check_limit(:header_size, header_size, @header_size_limit)
 					
 					if match = line.match(HEADER_PATTERN)
 						# Parse header line (name: value)
 						header_count += 1
-						check_limit(:header_count, header_count, @maximum_header_count)
+						check_limit(:header_count, header_count, @header_count_limit)
 						
 						fields << [match[1], match[2].strip]
 					else

data/lib/protocol/multipart/version.rb

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

data/readme.md

@@ -6,6 +6,16 @@
 
 Please see the [project releases](https://socketry.github.io/protocol-multipart/releases/index) for all releases.
 
+### v0.4.0
+
+  - Use consistent limit naming for multipart parser constraints.
+
+### 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,15 @@
 # Releases
 
+## v0.4.0
+
+  - Use consistent limit naming for multipart parser constraints.
+
+## 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.4.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