protocol-url 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb5e51237375afb74dda311e130ad550240453d53c42c5c0c05ddc532231261f
-  data.tar.gz: fbcf705936fedf9e967af1eb66ef2d901f68448bfe9e47d3ffd21156486207f0
+  metadata.gz: 10d18a95d6f20f5ca2457a52a2defa8d961ecf26eb372d45bea1f2d339f3a5c6
+  data.tar.gz: f15a84b24bd971e6262306b84e271196b5c20cde76983eba4625af28b0895ddd
 SHA512:
-  metadata.gz: c49c2bc6639b2b0777ae93c3b8ee34bd7c496831deb32da8af725ebc4f873d2666a47b68bc6aa031d7b1dbee522488927011c1d5ceb9b81140e4ea3c4ae2e575
-  data.tar.gz: 05c41426fdc297a5bae0a59d6ef4ca31e88a0cc592769038474c28b948b7615b5cecae17943d6263fe8bd02b079f178d427b2cdc7c4ea1393a5e28da8ccaa55f
+  metadata.gz: e1493486247a9e36b696bf62225a33888905d7e4a5a83b31357dc67d227b3a6f481844e2423befc5cc21f4c0a14aebc4ea507faa68a06a50490619e455396950
+  data.tar.gz: ee45f80e209b66b2a30d6b155188138a513e9a2c632bf1a4edc0322823e9bef209d2515babc955030c43c26c9da9ea687303a2aa91fa9704a2ac0594405d8cda

data/lib/protocol/url/form_data/nested.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../encoding"
+
+module Protocol
+	module URL
+		module FormData
+			# Builds nested form data from names and values.
+			class Nested
+				# The default maximum depth of a bracketed form name.
+				MAXIMUM_DEPTH = 8
+				
+				# Initialize the nested form data.
+				# @parameter maximum_depth [Integer | Nil] The maximum depth of a bracketed form name.
+				def initialize(maximum_depth: MAXIMUM_DEPTH)
+					@maximum_depth = maximum_depth
+					@root = {}
+				end
+				
+				# Add a form data value using its bracketed name.
+				# @parameter name [String] The form data name.
+				# @parameter value [Object] The form data value.
+				# @returns [Nested] The receiver.
+				def add(name, value)
+					keys = Encoding.split(name)
+					
+					if keys.empty?
+						raise ArgumentError, "Invalid form data name: #{name.inspect}!"
+					end
+					
+					if @maximum_depth and keys.size > @maximum_depth
+						raise RangeError, "Form data depth exceeded limit of #{@maximum_depth}!"
+					end
+					
+					Encoding.assign(keys, value, @root)
+					
+					return self
+				end
+				
+				# Convert the arguments to a nested hash.
+				# @returns [Hash] The nested arguments.
+				def to_h
+					return @root
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "nested"
+
+module Protocol
+	module URL
+		# @namespace
+		module FormData
+			# Incrementally parses `application/x-www-form-urlencoded` form data.
+			class Parser
+				CONTENT_TYPE = "application/x-www-form-urlencoded"
+				
+				# The default maximum encoded body size.
+				MAXIMUM_TOTAL_SIZE = 2 * 1024 * 1024
+				
+				# The default maximum number of form pairs.
+				MAXIMUM_PAIR_COUNT = 1024
+				
+				# Initialize the form data parser.
+				# @parameter maximum_total_size [Integer | Nil] The maximum encoded body size.
+				# @parameter maximum_pair_count [Integer | Nil] The maximum number of form pairs.
+				# @parameter maximum_depth [Integer | Nil] The maximum depth of a bracketed form name.
+				def initialize(maximum_total_size: MAXIMUM_TOTAL_SIZE, maximum_pair_count: MAXIMUM_PAIR_COUNT, maximum_depth: Nested::MAXIMUM_DEPTH)
+					@maximum_total_size = maximum_total_size
+					@maximum_pair_count = maximum_pair_count
+					@maximum_depth = maximum_depth
+				end
+				
+				# Parse URL-encoded form data into a nested hash.
+				#
+				# When a block is given, each decoded value is passed through the block before assignment. The value returned by the block is assigned to the result.
+				#
+				# @parameter body [Object] A readable body which yields chunks from `#read`.
+				# @yields {|name, value| ...} Each decoded form pair before assignment.
+				# @returns [Hash] The nested form data.
+				def parse(body)
+					nested = Nested.new(maximum_depth: @maximum_depth)
+					
+					each(body) do |name, value|
+						value = yield(name, value) if block_given?
+						nested.add(name, value)
+					end
+					
+					return nested.to_h
+				end
+				
+				# Incrementally enumerate URL-encoded form data as ordered name/value pairs.
+				# @parameter body [Object] A readable body which yields chunks from `#read`.
+				# @yields {|name, value| ...} Each decoded form pair.
+				# @returns [Enumerator | Boolean] An enumerator without a block, or true when complete.
+				def each(body)
+					return to_enum(__method__, body) unless block_given?
+					
+					buffer = String.new.b
+					total_size = 0
+					pair_count = 0
+					
+					while chunk = body.read
+						break if chunk.empty?
+						
+						total_size += chunk.bytesize
+						check_limit(:total_size, total_size, @maximum_total_size)
+						buffer << chunk
+						
+						while separator = buffer.index("&")
+							assignment = buffer.slice!(0, separator + 1)
+							assignment.chop!
+							
+							unless assignment.empty?
+								pair_count += 1
+								check_limit(:pair_count, pair_count, @maximum_pair_count)
+								yield_pair(assignment) {|name, value| yield name, value}
+							end
+						end
+					end
+					
+					unless buffer.empty?
+						pair_count += 1
+						check_limit(:pair_count, pair_count, @maximum_pair_count)
+						yield_pair(buffer) {|name, value| yield name, value}
+					end
+					
+					return true
+				end
+				
+				private
+				
+				def yield_pair(assignment)
+					name, value = assignment.split("=", 2)
+					
+					if value
+						value = decode_component(value)
+					end
+					
+					yield decode_component(name), value
+				end
+				
+				def decode_component(component)
+					return Encoding.unescape(component.tr("+", " "))
+				end
+				
+				def check_limit(name, value, maximum)
+					if maximum and value > maximum
+						raise RangeError, "Form data #{name} exceeded limit of #{maximum}!"
+					end
+				end
+			end
+		end
+	end
+end

data/lib/protocol/url/version.rb

@@ -7,6 +7,6 @@
 module Protocol
 	# @namespace
 	module URL
-		VERSION = "0.5.0"
+		VERSION = "0.6.0"
 	end
 end

data/lib/protocol/url.rb

@@ -6,6 +6,8 @@
 require_relative "url/version"
 require_relative "url/pattern"
 require_relative "url/encoding"
+require_relative "url/form_data/nested"
+require_relative "url/form_data/parser"
 require_relative "url/reference"
 require_relative "url/relative"
 require_relative "url/absolute"

data/readme.md

@@ -34,6 +34,11 @@ This project is best served by a collaborative and respectful environment. Treat
 
 Please see the [project releases](https://socketry.github.io/protocol-url/releases/index) for all releases.
 
+### v0.6.0
+
+  - Add `Protocol::URL::FormData::Parser` for incremental, limited parsing of `application/x-www-form-urlencoded` form data.
+  - Add `Protocol::URL::FormData::Nested` for consistently building nested form data while preserving absent and empty values.
+
 ### v0.5.0
 
   - Add `Protocol::URL::Encoding.decode_www_form` for decoding HTML form data where `+` represents a space.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.6.0
+
+  - Add `Protocol::URL::FormData::Parser` for incremental, limited parsing of `application/x-www-form-urlencoded` form data.
+  - Add `Protocol::URL::FormData::Nested` for consistently building nested form data while preserving absent and empty values.
+
 ## v0.5.0
 
   - Add `Protocol::URL::Encoding.decode_www_form` for decoding HTML form data where `+` represents a space.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-url
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -45,6 +45,8 @@ files:
 - lib/protocol/url.rb
 - lib/protocol/url/absolute.rb
 - lib/protocol/url/encoding.rb
+- lib/protocol/url/form_data/nested.rb
+- lib/protocol/url/form_data/parser.rb
 - lib/protocol/url/path.rb
 - lib/protocol/url/pattern.rb
 - lib/protocol/url/reference.rb