protocol-multipart 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8020a17a66f95c8dcc80853403a434db667e787dcc1e7e33a3402c72f12356c1
-  data.tar.gz: 6779e480527eec3c7fa1ca93663d823c89bc326cc27e48212d4d42c7e91c9ca9
+  metadata.gz: 6f780cb8777ab2bcdacd17295c0017d194f0e43e864b76064c2f5a17feaeebce
+  data.tar.gz: 5b6c27f78eb2dc61fe351ae3c493847413580af1b6c194cd090a6eeca9a46ad6
 SHA512:
-  metadata.gz: 8081e11c625c5b8e68e7f1a19a8e7c814ba7b9fc092d2ad91877b56d2f9e6822aacbe777891d667a7d5bf0ef802ded0882656146f38f7c8ce40b63d643d8d10d
-  data.tar.gz: eb2e3cf8796c4ac0eb1146d834732eb1e140215c3605c0933cbadbf6a7dc8fceb2a01bd9f9902a1b78bb7c1c189ae5b8e8f79d5a5be14f62bf568af9d5aa2e0e
+  metadata.gz: '08d99314fcd9dbafde62056380a4d17a4288f5d0fef2cc33a00ac55ddcfd9bf2dfeaabf4e26c209a8b94b7bd01c553e883767323143b7f2f55e04e02a571ef0c'
+  data.tar.gz: 0770603bb53169f98a8fd2582d464c1677fe906fddbebc3470f14e426d3bdc4db9cf05a3757ba615724fefa9510ad7cb11085becbc884d7950593a93ae00f3f1

data/lib/protocol/multipart/byte_limit.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Protocol
+	module Multipart
+		# Tracks consumed bytes against an optional maximum.
+		class ByteLimit
+			# Initialize a byte limit.
+			# @parameter maximum [Integer | Nil] The maximum number of bytes, or nil for no limit.
+			# @parameter name [Symbol] The name used when reporting a limit violation.
+			def initialize(maximum, name: :size)
+				if maximum and maximum < 0
+					raise ArgumentError, "Multipart limits must be non-negative!"
+				end
+				
+				@maximum = maximum
+				@name = name
+				@size = 0
+			end
+			
+			# The number of bytes consumed.
+			attr :size
+			
+			# Consume the given number of bytes.
+			# @parameter size [Integer] The number of bytes to consume.
+			# @returns [Integer] The total number of bytes consumed.
+			def consume(size)
+				@size += size
+				
+				if @maximum and @size > @maximum
+					raise RangeError, "Multipart #{@name} exceeded limit of #{@maximum}!"
+				end
+				
+				return @size
+			end
+		end
+	end
+end

data/lib/protocol/multipart/form_data.rb

@@ -4,8 +4,10 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "mixed"
+require_relative "parser"
 require_relative "string_part"
 require_relative "escape"
+require_relative "byte_limit"
 
 module Protocol
 	module Multipart
@@ -14,6 +16,112 @@ module Protocol
 		class FormData < Mixed
 			include Escape
 			
+			# The default maximum size of a buffered form field.
+			MAXIMUM_FIELD_SIZE = 2 * 1024 * 1024
+			
+			# The default maximum size of a streamed file upload.
+			MAXIMUM_UPLOAD_SIZE = 128 * 1024 * 1024
+			
+			# The default maximum combined size of all form fields and file uploads.
+			MAXIMUM_TOTAL_SIZE = 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)
+					@part = part
+					@filename = filename
+					@limit = ByteLimit.new(maximum_size, name: :upload_size)
+					@total_limit = total_limit
+				end
+				
+				# The submitted filename.
+				attr :filename
+				
+				# The multipart headers associated with this upload.
+				def headers
+					@part.headers
+				end
+				
+				# The number of upload bytes consumed so far.
+				def size
+					@limit.size
+				end
+				
+				# Whether the complete upload has been consumed.
+				def ended?
+					@part.ended?
+				end
+				
+				# Iterate over the upload body.
+				# @parameter chunk_size [Integer] The maximum chunk size.
+				def each(chunk_size = 8192)
+					return to_enum(:each, chunk_size) unless block_given?
+					
+					@part.each(chunk_size) do |chunk|
+						@limit.consume(chunk.bytesize)
+						@total_limit.consume(chunk.bytesize)
+						yield chunk
+					end
+					
+					return self
+				end
+				
+				# Consume any unread upload body while applying its limits.
+				def discard
+					self.each{|chunk|}
+					return nil
+				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".

data/lib/protocol/multipart/header/content_disposition.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "parameterized"
+
+module Protocol
+	module Multipart
+		module Header
+			# A MIME Content-Disposition header value.
+			class ContentDisposition < Parameterized
+				VALUE_PATTERN = /\A[ \t]*(#{TOKEN})[ \t]*/.freeze
+				NAME = "content-disposition"
+			end
+		end
+	end
+end

data/lib/protocol/multipart/header/content_type.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "parameterized"
+
+module Protocol
+	module Multipart
+		module Header
+			# A MIME Content-Type header value.
+			class ContentType < Parameterized
+				VALUE_PATTERN = /\A[ \t]*(#{TOKEN}\/#{TOKEN})[ \t]*/.freeze
+				NAME = "content-type"
+			end
+		end
+	end
+end

data/lib/protocol/multipart/header/parameterized.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http/error"
+
+module Protocol
+	module Multipart
+		module Header
+			# A parameterized MIME header value.
+			class Parameterized
+				TOKEN = "[!#$%&'*+\\-.^_`|~0-9A-Za-z]+"
+				VALUE_PATTERN = /\A[ \t]*(#{TOKEN}(?:\/#{TOKEN})?)[ \t]*/.freeze
+				PARAMETER_PATTERN = /\G;[ \t]*(#{TOKEN})[ \t]*=[ \t]*(?:"((?:\\[^\x00-\x1f\x7f]|[^"\\\x00-\x1f\x7f])*)"|(#{TOKEN}))[ \t]*/.freeze
+				NAME = nil
+				
+				# Parse a parameterized header value.
+				# @parameter string [String] The header value.
+				# @returns [Parameterized] The parsed header.
+				# @raises [ArgumentError] If the header value is malformed or contains duplicate parameters.
+				def self.parse(string)
+					unless match = self::VALUE_PATTERN.match(string)
+						raise ArgumentError, "Invalid header value: #{string.inspect}!"
+					end
+					
+					type = match[1].downcase
+					parameters = {}
+					offset = match.end(0)
+					
+					while offset < string.length
+						unless match = PARAMETER_PATTERN.match(string, offset)
+							raise ArgumentError, "Invalid header parameter at offset #{offset}: #{string.inspect}!"
+						end
+						
+						name = match[1].downcase
+						
+						if parameters.key?(name)
+							raise ArgumentError, "Duplicate header parameter: #{name.inspect}!"
+						end
+						
+						if quoted = match[2]
+							parameters[name] = quoted.gsub(/\\(.)/, "\\1")
+						else
+							parameters[name] = match[3]
+						end
+						
+						offset = match.end(0)
+					end
+					
+					return new(type, parameters)
+				end
+				
+				# Coerce an object to a parameterized header value.
+				# @parameter value [Object] The header value.
+				# @returns [Parameterized] The parsed header.
+				def self.coerce(value)
+					if value.is_a?(self)
+						return value
+					end
+					
+					return parse(value.to_s)
+				end
+				
+				# Initialize a parameterized header value.
+				# @parameter type [String] The primary header value.
+				# @parameter parameters [Hash] The named parameters.
+				def initialize(type, parameters = {})
+					@type = type
+					@parameters = parameters
+				end
+				
+				# The primary header value.
+				attr :type
+				
+				# The named parameters.
+				attr :parameters
+				
+				# Fetch a named parameter.
+				# @parameter name [String] The case-insensitive parameter name.
+				# @returns [String | Nil] The parameter value, if present.
+				def [](name)
+					@parameters[name.downcase]
+				end
+				
+				# Reject a second value for this singular MIME field.
+				def <<(value)
+					raise Protocol::HTTP::DuplicateHeaderError.new(self.class::NAME, self, value)
+				end
+				
+				# Convert the header to its wire representation.
+				# @returns [String] The serialized header value.
+				def to_s
+					value = String.new(@type)
+					
+					@parameters.each do |name, parameter|
+						escaped = parameter.gsub(/["\\]/, "\\\\\\0")
+						value << "; #{name}=\"#{escaped}\""
+					end
+					
+					return value
+				end
+			end
+		end
+	end
+end

data/lib/protocol/multipart/headers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http/headers"
+
+require_relative "header/content_disposition"
+require_relative "header/content_type"
+
+module Protocol
+	module Multipart
+		# @namespace
+		module Header
+		end
+		
+		# The header fields associated with a multipart body or part.
+		class Headers < Protocol::HTTP::Headers
+			POLICY = {
+				"content-description" => false,
+				"content-disposition" => Header::ContentDisposition,
+				"content-id" => false,
+				"content-length" => false,
+				"content-transfer-encoding" => false,
+				"content-type" => Header::ContentType,
+				"mime-version" => false,
+			}.tap do |policy|
+				policy.default = Protocol::HTTP::Header::Multiple
+			end
+			
+			# Initialize the multipart headers.
+			# @parameter fields [Array] An array of `[key, value]` pairs.
+			# @parameter tail [Integer | Nil] The index of the trailer start.
+			# @parameter indexed [Hash | Nil] The cached header index.
+			# @parameter policy [Hash] The header normalization policy.
+			def initialize(fields = [], tail = nil, indexed: nil, policy: POLICY)
+				super
+			end
+		end
+	end
+end

data/lib/protocol/multipart/parser.rb

@@ -4,18 +4,34 @@
 # Copyright, 2025, by Samuel Williams.
 
 require "io/stream"
+require_relative "headers"
 
 module Protocol
 	module Multipart
 		# A parser for multipart data based on RFC 2046 and RFC 2387.
 		# Parses multipart bodies and provides an enumerable interface to access the parts.
 		class Parser
+			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 default maximum number of header bytes in each part.
+			MAXIMUM_HEADER_SIZE = 64 * 1024
+			
+			# The default maximum number of headers in each part.
+			MAXIMUM_HEADER_COUNT = 64
+			
+			# The default maximum number of parts.
+			MAXIMUM_PART_COUNT = 128
+			
 			# Represents a single part within a multipart message.
 			class Part
 				# Initialize a new part with a readable stream, headers, and a boundary string.
 				#
 				# @parameter readable [IO::Stream] The readable stream that contains the part's data.
-				# @parameter headers [Hash] The headers associated with this part.
+				# @parameter headers [Headers] The headers associated with this part.
 				# @parameter boundary [String] The boundary string used to separate parts.
 				def initialize(readable, headers, boundary)
 					@readable = readable
@@ -25,7 +41,7 @@ module Protocol
 					@is_closing = false
 				end
 				
-				# @attribute [Hash] The headers associated with this part.
+				# @attribute [Headers] The headers associated with this part.
 				attr_reader :headers
 				
 				# Iterate through the part content in chunks.
@@ -147,9 +163,23 @@ module Protocol
 			#
 			# @parameter readable [IO, IO::Stream] The readable stream containing multipart data.
 			# @parameter boundary [String] The boundary string that separates the parts.
-			def initialize(readable, boundary)
+			# @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]
+				
+				if limits.any?{|limit| limit and limit < 0}
+					raise ArgumentError, "Multipart limits must be non-negative!"
+				end
+				
 				@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
 				
 				@boundary_marker = "--#{@boundary}\r\n".freeze
 			end
@@ -161,11 +191,16 @@ module Protocol
 			def each
 				return to_enum unless block_given?
 				
+				preamble_size = 0
+				
 				# Read lines until we find the first boundary:
 				while true
-					if line = @readable.gets("\r\n", chomp: false)
+					if line = read_line(preamble_size, @maximum_preamble_size, 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)
 						end
 					else
 						# End of stream reached without finding boundary:
@@ -173,18 +208,21 @@ module Protocol
 					end
 				end
 				
+				part_count = 0
+				
 				while true
+					part_count += 1
+					check_limit(:part_count, part_count, @maximum_part_count)
+					
 					part = read_part
 					break unless part
 					
 					if part.read_empty_boundary?
 					else
-						begin
-							yield part
-						ensure
-							# After yielding, ensure the part is finished to advance to the next boundary. This is either a no-op if user already read the part, or reads remaining data.
-							part.discard
-						end
+						yield part
+						
+						# Advance to the next boundary after the consumer returns normally. If the consumer raises, stop parsing without draining the request body.
+						part.discard
 					end
 					
 					# Check if this was the last part:
@@ -196,34 +234,41 @@ module Protocol
 			
 			private
 			
+			def read_line(size, maximum, allowance: 0, chomp:)
+				if maximum
+					limit = maximum - 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}!"
+				end
+			end
+			
 			def read_part
-				headers = {}
-				value = nil
+				fields = []
+				header_size = 0
+				header_count = 0
 				
 				# Read headers until empty line
-				while line = @readable.gets("\r\n", chomp: true)
+				while line = read_line(header_size, @maximum_header_size, allowance: 2, chomp: true)
 					if line.empty?
 						break # End of headers
-					elsif match = line.match(/^\s+([^:]+)$/)
-						if value
-							value << " " << match[1]
-						else
-							raise RuntimeError, "Unexpected whitespace before header name: #{line.inspect}"
-						end
-					elsif match = line.match(/^([^:]+):\s*(.*)$/) 
+					end
+					
+					header_size += line.bytesize + 2
+					check_limit(:header_size, header_size, @maximum_header_size)
+					
+					if match = line.match(HEADER_PATTERN)
 						# Parse header line (name: value)
-						name = match[1].strip.downcase
-						value = match[2].strip
+						header_count += 1
+						check_limit(:header_count, header_count, @maximum_header_count)
 						
-						if current = headers[name]
-							if current.is_a?(Array)
-								current << value
-							else
-								headers[name] = [current, value]
-							end
-						else
-							headers[name] = value
-						end
+						fields << [match[1], match[2].strip]
 					else
 						raise RuntimeError, "Invalid header line: #{line.inspect}"
 					end
@@ -233,7 +278,7 @@ module Protocol
 					raise EOFError, "Unexpected end of stream while reading headers!"
 				end
 				
-				return Part.new(@readable, headers, @boundary)
+				return Part.new(@readable, Headers.new(fields), @boundary)
 			end
 		end
 	end

data/lib/protocol/multipart/version.rb

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

data/lib/protocol/multipart.rb

@@ -4,6 +4,8 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "multipart/version"
+require_relative "multipart/byte_limit"
+require_relative "multipart/headers"
 require_relative "multipart/parser"
 require_relative "multipart/mixed"
 require_relative "multipart/part"

data/readme.md

@@ -6,6 +6,13 @@
 
 Please see the [project releases](https://socketry.github.io/protocol-multipart/releases/index) for all releases.
 
+### v0.2.0
+
+  - Add strict, policy-driven parsing for parameterized `Content-Type` and `Content-Disposition` fields using `Protocol::Multipart::Headers`.
+  - Limit multipart preamble size, header size, header count and part count by default.
+  - Add `Protocol::Multipart::ByteLimit` for limiting streamed multipart content.
+  - Add streaming multipart form-data parsing with field, upload and total content limits.
+
 ### v0.1.0
 
 ## Contributing
@@ -18,6 +25,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### Developer Certificate of Origin
 
 In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.

data/releases.md

@@ -1,3 +1,10 @@
 # Releases
 
+## v0.2.0
+
+  - Add strict, policy-driven parsing for parameterized `Content-Type` and `Content-Disposition` fields using `Protocol::Multipart::Headers`.
+  - Limit multipart preamble size, header size, header count and part count by default.
+  - Add `Protocol::Multipart::ByteLimit` for limiting streamed multipart content.
+  - Add streaming multipart form-data parsing with field, upload and total content limits.
+
 ## v0.1.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-multipart
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -52,14 +52,33 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: protocol-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.67'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.67'
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
 - lib/protocol/multipart.rb
 - lib/protocol/multipart/boundary.rb
+- lib/protocol/multipart/byte_limit.rb
 - lib/protocol/multipart/escape.rb
 - lib/protocol/multipart/form_data.rb
+- lib/protocol/multipart/header/content_disposition.rb
+- lib/protocol/multipart/header/content_type.rb
+- lib/protocol/multipart/header/parameterized.rb
+- lib/protocol/multipart/headers.rb
 - lib/protocol/multipart/io_part.rb
 - lib/protocol/multipart/mixed.rb
 - lib/protocol/multipart/parser.rb
@@ -82,14 +101,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Provides abstractions to handle the multipart format.
 test_files: []