protocol-url 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b1993c620685f91b17b6a707eace1ff03219c1d6e2eace3d272e8ec8c723680
-  data.tar.gz: 8969a20bccae90e49a5d541ea9f384127aaf817e7df12b1ac8b16a27ba450b1a
+  metadata.gz: 4a8be4027ad2b93f7707396fe9a53a47846b53e78cde0269be4fdd3dbdb448e3
+  data.tar.gz: 89ae574fc48ca43bcd0b224bdbe91ab0da1354869f6c8dbc87bdfbe9e6cd45b0
 SHA512:
-  metadata.gz: 46b12bedaa0fca57e658677545a09ea2839ce6496c149eaa30c10b5cd213d3abbc517f850ddffce5cc159a8c5a73cb99be10c1737e06ed75974ace4448beca70
-  data.tar.gz: 513ab9374d04bf04512d11f8610dbae6a14deea9c27a70b1d7a813df569c6642ca1eb679a5f51ad4b99319980f0b5f6c178d895c12de0c2037726337261dbce2
+  metadata.gz: fb21e1c877b41f75975183cacab2a9dbea71e09c5fa4e11f66767f713e50fe0c27b63f07b1daa83feb00309a41132703544620541c794c598ce1efc9c402a830
+  data.tar.gz: 7c0703c48866182719b0a12edee9b45447f2ce3233519058af33c171ddf729fa9f8615cb76ae0aaf8355383703e21937fa912e94eff05428c6007d62c4e763cd

data/lib/protocol/url/absolute.rb

@@ -15,8 +15,8 @@ module Protocol
 			# @parameter scheme [String] The URL scheme (e.g., "https", "http").
 			# @parameter authority [String] The authority component (e.g., "example.com", "user@host:port").
 			# @parameter path [String | Path] The encoded path component (defaults to "/").
-			# @parameter query [String, nil] The query string.
-			# @parameter fragment [String, nil] The fragment identifier.
+			# @parameter query [String | Nil] The query string.
+			# @parameter fragment [String | Nil] The fragment identifier.
 			def initialize(scheme, authority, path = "/", query = nil, fragment = nil)
 				@scheme = scheme
 				@authority = authority
@@ -36,11 +36,11 @@ module Protocol
 				return super
 			end
 			
-			# @attribute [String] The URL scheme.
-			attr :scheme
+			# @attribute [String | Nil] The URL scheme.
+			attr_accessor :scheme
 			
-			# @attribute [String] The authority component.
-			attr :authority
+			# @attribute [String | Nil] The authority component.
+			attr_accessor :authority
 			
 			# Check if the URL has a non-empty scheme.
 			#
@@ -122,11 +122,11 @@ module Protocol
 			
 			# Create a new Absolute URL with modified components.
 			#
-			# @parameter scheme [String, nil] The scheme to use (nil to remove scheme).
-			# @parameter authority [String, nil] The authority to use (nil to remove authority).
-			# @parameter path [String, nil] The path to merge with the current path.
-			# @parameter query [String, nil] The query string to use.
-			# @parameter fragment [String, nil] The fragment to use.
+			# @parameter scheme [String | Nil] The scheme to use (nil to remove scheme).
+			# @parameter authority [String | Nil] The authority to use (nil to remove authority).
+			# @parameter path [String | Nil] The path to merge with the current path.
+			# @parameter query [String | Nil] The query string to use.
+			# @parameter fragment [String | Nil] The fragment to use.
 			# @parameter pop [Boolean] Whether to pop the last path component before merging.
 			# @returns [Absolute] A new Absolute URL with the modified components.
 			#

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.
 			#
@@ -252,6 +253,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 +379,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 +488,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/reference.rb

@@ -102,8 +102,8 @@ module Protocol
 				@parameters = parameters
 			end
 			
-			# @attribute [Hash] User supplied parameters that will be appended to the query part.
-			attr :parameters
+			# @attribute [Hash | Nil] User supplied parameters that will be appended to the query part.
+			attr_accessor :parameters
 			
 			# Freeze the reference.
 			#

data/lib/protocol/url/relative.rb

@@ -15,8 +15,8 @@ module Protocol
 			# Initialize a new relative URL.
 			#
 			# @parameter path [String | Path] The encoded path component.
-			# @parameter query [String, nil] The query string.
-			# @parameter fragment [String, nil] The fragment identifier.
+			# @parameter query [String | Nil] The query string.
+			# @parameter fragment [String | Nil] The fragment identifier.
 			def initialize(path, query = nil, fragment = nil)
 				@path = Path[path]
 				@query = query
@@ -38,11 +38,18 @@ module Protocol
 			# @attribute [Path] The path component of the URL.
 			attr :path
 			
-			# @attribute [String, nil] The query string component.
-			attr :query
+			# Replace the path component of this URL.
+			# @parameter path [String | Path] The encoded path component.
+			# @returns [Path] The assigned path component.
+			def path=(path)
+				@path = Path[path]
+			end
 			
-			# @attribute [String, nil] The fragment identifier.
-			attr :fragment
+			# @attribute [String | Nil] The query string component.
+			attr_accessor :query
+			
+			# @attribute [String | Nil] The fragment identifier.
+			attr_accessor :fragment
 			
 			# Resolve the URL path beneath a local filesystem root.
 			#
@@ -104,9 +111,9 @@ module Protocol
 			
 			# Create a new Relative URL with modified components.
 			#
-			# @parameter path [String, nil] The path to merge with the current path.
-			# @parameter query [String, nil] The query string to use.
-			# @parameter fragment [String, nil] The fragment to use.
+			# @parameter path [String | Nil] The path to merge with the current path.
+			# @parameter query [String | Nil] The query string to use.
+			# @parameter fragment [String | Nil] The fragment to use.
 			# @parameter pop [Boolean] Whether to pop the last path component before merging.
 			# @returns [Relative] A new Relative URL with the modified components.
 			#
@@ -125,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.
 			#
@@ -139,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.11.0"
+		VERSION = "0.13.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.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.
+
+### 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.2.0
+
+  - Move `Protocol::URL::PATTERN` to `protocol/url/pattern.rb` so it can be shared more easily.
+
 ### v0.10.0
 
   - Rename `Protocol::URL::FormData::Parser::CONTENT_TYPE` to `MEDIA_TYPE`.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## 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`.

metadata

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