protocol-url 0.12.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 67f58bb48277d53b3817bb38b2b7c4546a8a8e1f3df62cea531c577705c4c833
-  data.tar.gz: 55bcfd924be9ae1eada0b2e5f8ee93fcd4a1a24c0693986ed3f8818b26072fd1
+  metadata.gz: 9ff041406f4bc298081aaa3f7150a374bf937f87e0f2783458082c4635d51488
+  data.tar.gz: 90aa117ed86f9df29b3278420b8c3b450a8f6fc7b30cf6473e5fbf68bb939d40
 SHA512:
-  metadata.gz: 7df97ce90f4ce934023217fbedf9cbf864febeee311b9b25e3ee952e647d75d8cc041f16665b84884fec1e1d2dad859f9f3d21a0bfdccf40f832938158a21924
-  data.tar.gz: bb2c1f9fece1eda9cb5ee8b96d216b28e0e15c6fe9605c6ec0d43a615b5b9a247f9bc299553e1d46778d9e6c5971e34d56bbd77f172202002ad63d7be89b53c3
+  metadata.gz: 371901582d694902f2610377663c7aca91835c3e04fde1a06854a3b2a67456bff313d71a347686e3d7e80b1dc35cd0103379fe0abf28c6050967534f0d3ae888
+  data.tar.gz: 8446857f07d8aa19317a1ce85e067b623df958e2a56b4df9b9110d52de1cc4eb70115d1af6ed068c5cbb9e2d78ebefd02d406ab551e36258e8acfb99276c9694

data/lib/protocol/url/path.rb

@@ -20,7 +20,8 @@ module Protocol
 			
 			EMPTY_SEGMENTS = [].freeze
 			ROOT_SEGMENTS = ["", ""].freeze
-			private_constant :EMPTY_SEGMENTS, :ROOT_SEGMENTS
+			NORMALIZATION_PATTERN = /%[0-9A-Fa-f]{2}|%|[^a-zA-Z0-9_.~!$&'()*+,;=:@-]/
+			private_constant :EMPTY_SEGMENTS, :ROOT_SEGMENTS, :NORMALIZATION_PATTERN
 			
 			# Coerce an encoded string or encoded segment array into a path.
 			#
@@ -207,14 +208,18 @@ module Protocol
 			end
 			
 			# @parameter other [Object] The value to compare with this path.
-			# @returns [Boolean] Whether both paths have the same encoded representation.
+			# @returns [Boolean] Whether both values are the same.
 			def ==(other)
-				eql?(other)
+				if other.is_a?(String)
+					return encoded == other
+				else
+					return eql?(other)
+				end
 			end
 			
 			# Compare this path with another path using exact encoded string identity.
 			# @parameter other [Object] The value to compare with this path.
-			# @returns [Boolean] Whether both paths have equal encoded strings.
+			# @returns [Boolean] Whether both paths are the same.
 			def eql?(other)
 				other.is_a?(Path) && encoded.eql?(other.encoded)
 			end
@@ -252,6 +257,42 @@ module Protocol
 			alias to_s encoded
 			alias to_str encoded
 			
+			# Normalize the encoded spelling of this path.
+			#
+			# Percent-encoded unreserved characters are decoded, retained percent escapes
+			# use uppercase hexadecimal digits, and literal characters outside the path
+			# segment grammar are percent encoded. Reserved characters retain their
+			# encoded or literal form because those forms are not generally equivalent.
+			#
+			# This operation preserves the path structure. Use {simplify} separately when
+			# application semantics permit resolving dot segments or collapsing repeated separators.
+			#
+			# @returns [Path] The normalized path, or this path if already normalized.
+			# @raises [ArgumentError] If the path contains malformed percent encoding, NUL, or invalid string encoding.
+			def normalize
+				encoded = self.encoded
+				unless encoded.valid_encoding? && encoded.encoding.ascii_compatible?
+					raise ArgumentError, "Path segment has invalid encoding!"
+				end
+				
+				segments = self.segments
+				normalized_segments = nil
+				
+				segments.each_with_index do |segment, index|
+					next unless NORMALIZATION_PATTERN.match?(segment)
+					
+					normalized = normalize_segment(segment)
+					next if normalized == segment
+					
+					normalized_segments ||= segments.dup
+					normalized_segments[index] = normalized
+				end
+				
+				return self unless normalized_segments
+				
+				return self.class.new(nil, normalized_segments)
+			end
+			
 			# Simplify this path in place by resolving literal or percent-encoded dot segments and repeated separators.
 			#
 			# @returns [Path | Nil] This path when changed, otherwise `nil`.
@@ -342,6 +383,42 @@ module Protocol
 			
 			private
 			
+			# Normalize one encoded path segment:
+			def normalize_segment(segment)
+				return segment.gsub(NORMALIZATION_PATTERN) do |character|
+					byte = character.getbyte(0)
+					
+					if byte == 0
+						raise ArgumentError, "Path segment contains NUL!"
+					elsif byte == 0x25
+						if character.bytesize == 1
+							raise ArgumentError, "String contains malformed percent encoding!"
+						end
+						
+						byte = character.byteslice(1, 2).to_i(16)
+						if byte == 0
+							raise ArgumentError, "Path segment contains NUL!"
+						elsif unreserved_byte?(byte)
+							byte.chr
+						else
+							character.upcase
+						end
+					else
+						Encoding.escape(character)
+					end
+				end
+			end
+			
+			# Whether the byte represents an unreserved URI character:
+			def unreserved_byte?(byte)
+				case byte
+				when 0x30..0x39, 0x41..0x5A, 0x61..0x7A, 0x2D, 0x2E, 0x5F, 0x7E
+					return true
+				else
+					return false
+				end
+			end
+			
 			# Identify dot segments, including percent-encoded spellings. RFC 3986 treats
 			# percent-encoded unreserved characters as equivalent to their literal forms;
 			# the WHATWG URL Standard explicitly recognizes `%2e`, `.%2e`, `%2e.`, and
@@ -415,9 +492,9 @@ module Protocol
 							offset += 1
 						end
 					elsif segment == "" && index != last_index
-						# Collapse repeated separators.
+						# Collapse repeated separators:
 					elsif dot == ".." && offset > 0 && dot_segment(segments[offset - 1]) != ".."
-						# Pop a component, but never pop the absolute-path root.
+						# Pop a component, but never pop the absolute-path root:
 						offset -= 1 if segments[offset - 1] != ""
 						
 						# A trailing parent reference also denotes a directory.

data/lib/protocol/url/relative.rb

@@ -132,12 +132,17 @@ module Protocol
 				self.class.new(path || @path, query, fragment)
 			end
 			
-			# Normalize the path by resolving "." and ".." segments and removing duplicate slashes.
+			# Normalize the encoded path and simplify its structure.
 			#
-			# This modifies the URL in-place by simplifying the path component:
+			# This modifies the URL in-place by normalizing and simplifying the path component:
+			# - Decodes percent-encoded unreserved characters
+			# - Uses uppercase hexadecimal digits for retained percent escapes
 			# - Removes "." segments (current directory)
 			# - Resolves ".." segments (parent directory)
-			# - Collapses multiple consecutive slashes to single slashes (except at start)
+			# - Collapses empty path segments represented by consecutive slashes
+			#
+			# Normalization is intentionally lossy. Callers that need to preserve the
+			# original path structure should retain the parsed URL and avoid this method.
 			#
 			# @returns [self] The normalized URL.
 			#
@@ -146,7 +151,7 @@ module Protocol
 			#   url.normalize!
 			#   url.path.to_s  # => "/foo/bar/qux"
 			def normalize!
-				@path = @path.simplify
+				@path = @path.normalize.simplify
 				
 				return self
 			end

data/lib/protocol/url/version.rb

@@ -7,6 +7,6 @@
 module Protocol
 	# @namespace
 	module URL
-		VERSION = "0.12.0"
+		VERSION = "0.14.0"
 	end
 end

data/readme.md

@@ -34,6 +34,104 @@ bundle exec sus
 
 Please see the [project releases](https://socketry.github.io/protocol-url/releases/index) for all releases.
 
+### v0.14.0
+
+  - Allow paths to compare with their encoded string representation.
+
+### v0.13.0
+
+  - Add conservative normalization of encoded URL paths.
+
+### v0.12.0
+
+  - Allow unfrozen relative and absolute URLs to replace their components.
+
+### v0.10.0
+
+  - Rename `Protocol::URL::FormData::Parser::CONTENT_TYPE` to `MEDIA_TYPE`.
+
+### v0.9.0
+
+  - Add `Protocol::URL::LimitError` for configured processing limits.
+
+### v0.8.0
+
+  - Use consistent limit naming for form data parser constraints.
+
+### v0.7.0
+
+  - Allow `Protocol::URL::FormData::Parser#parse` to populate a supplied result object.
+
+### 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.
+
+### v0.4.0
+
+  - Add comparison methods to `Protocol::URL::Relative` (and by inheritance to `Protocol::URL::Absolute`):
+      - `#==` for structural equality comparison (compares path, query, fragment components).
+      - `#===` for string equality comparison (enables case statement matching).
+      - `#<=>` for ordering and sorting.
+      - `#hash` for hash key support.
+      - `#equal?` for component-based equality checking.
+  - Add JSON serialization support to `Protocol::URL::Relative`:
+      - `#as_json` returns the string representation.
+      - `#to_json` returns a JSON-encoded string.
+
+### v0.13.0
+
+  - Add conservative normalization of encoded URL paths.
+
+### v0.12.0
+
+  - Allow unfrozen relative and absolute URLs to replace their components.
+
+### v0.10.0
+
+  - Rename `Protocol::URL::FormData::Parser::CONTENT_TYPE` to `MEDIA_TYPE`.
+
+### v0.9.0
+
+  - Add `Protocol::URL::LimitError` for configured processing limits.
+
+### v0.8.0
+
+  - Use consistent limit naming for form data parser constraints.
+
+### v0.7.0
+
+  - Allow `Protocol::URL::FormData::Parser#parse` to populate a supplied result object.
+
+### 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.
+
+### v0.4.0
+
+  - Add comparison methods to `Protocol::URL::Relative` (and by inheritance to `Protocol::URL::Absolute`):
+      - `#==` for structural equality comparison (compares path, query, fragment components).
+      - `#===` for string equality comparison (enables case statement matching).
+      - `#<=>` for ordering and sorting.
+      - `#hash` for hash key support.
+      - `#equal?` for component-based equality checking.
+  - Add JSON serialization support to `Protocol::URL::Relative`:
+      - `#as_json` returns the string representation.
+      - `#to_json` returns a JSON-encoded string.
+
+### v0.3.0
+
+  - Add `relative(target, from)` for computing relative paths between URLs.
+
 ### v0.12.0
 
   - Allow unfrozen relative and absolute URLs to replace their components.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.14.0
+
+  - Allow paths to compare with their encoded string representation.
+
+## v0.13.0
+
+  - Add conservative normalization of encoded URL paths.
+
 ## v0.12.0
 
   - Allow unfrozen relative and absolute URLs to replace their components.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-url
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Samuel Williams