protocol-url 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aeaada96a9b666006635d0589aefee1a0bbd4b0df7787a40a6c5d40faeb87f1
-  data.tar.gz: 3bb9157f29504fd386b9da7730ad0e346371488a2cd440525ab501a5127d62e4
+  metadata.gz: 1b1993c620685f91b17b6a707eace1ff03219c1d6e2eace3d272e8ec8c723680
+  data.tar.gz: 8969a20bccae90e49a5d541ea9f384127aaf817e7df12b1ac8b16a27ba450b1a
 SHA512:
-  metadata.gz: 82707be363eedcc58a739f62acdca6b5b611f8a5e7e36992a2db6b48fdc2c950d7f0b72ebb38bd05cecee8fbeb42453cdb49a6be2a921053169a0bf633a998a7
-  data.tar.gz: 808c99891a07593694ce6ab7542986ef7c95d53d4882c4efef79aec34fb35812824e4c69b7ce11e9fe44fa971f0ee8765408f2997db7e4f9fca25d497f314ece
+  metadata.gz: 46b12bedaa0fca57e658677545a09ea2839ce6496c149eaa30c10b5cd213d3abbc517f850ddffce5cc159a8c5a73cb99be10c1737e06ed75974ace4448beca70
+  data.tar.gz: 513ab9374d04bf04512d11f8610dbae6a14deea9c27a70b1d7a813df569c6642ca1eb679a5f51ad4b99319980f0b5f6c178d895c12de0c2037726337261dbce2

data/lib/protocol/url/absolute.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "relative"
 
@@ -14,7 +14,7 @@ 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] The path component (defaults to "/").
+			# @parameter path [String | Path] The encoded path component (defaults to "/").
 			# @parameter query [String, nil] The query string.
 			# @parameter fragment [String, nil] The fragment identifier.
 			def initialize(scheme, authority, path = "/", query = nil, fragment = nil)
@@ -25,6 +25,17 @@ module Protocol
 				super(path, query, fragment)
 			end
 			
+			# Freeze the URL and its direct components.
+			# @returns [Absolute] The frozen URL.
+			def freeze
+				return self if frozen?
+				
+				@scheme.freeze
+				@authority.freeze
+				
+				return super
+			end
+			
 			# @attribute [String] The URL scheme.
 			attr :scheme
 			
@@ -97,7 +108,7 @@ module Protocol
 					end
 				else
 					# Relative path: merge with base path:
-					path = Path.expand(@path, other.path)
+					path = @path.join(other.path)
 					Absolute.new(@scheme, @authority, path, other.query, other.fragment)
 				end
 			end
@@ -129,7 +140,9 @@ module Protocol
 			# 	updated = url.with(query: "query=python")
 			# 	updated.to_s  # => "https://example.com/search?query=python"
 			def with(scheme: @scheme, authority: @authority, path: nil, query: @query, fragment: @fragment, pop: true)
-				self.class.new(scheme, authority, Path.expand(@path, path, pop), query, fragment)
+				path = @path.join(path, pop: pop) unless path.nil?
+				
+				self.class.new(scheme, authority, path || @path, query, fragment)
 			end
 			
 			# Convert the URL to an array representation.

data/lib/protocol/url/encoding.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Protocol
 	module URL
@@ -29,6 +29,7 @@ module Protocol
 			#
 			# @parameter string [String] The string to unescape.
 			# @returns [String] The unescaped string.
+			# @raises [ArgumentError] If the string contains malformed percent encoding.
 			#
 			# @example Unescape spaces and special characters.
 			# 	Encoding.unescape("hello%20world%21")
@@ -38,60 +39,66 @@ module Protocol
 			# 	Encoding.unescape("caf%C3%A9")
 			# 	# => "café"
 			def self.unescape(string, encoding = string.encoding)
-				string.b.gsub(/%(\h\h)/) do |hex|
-					Integer($1, 16).chr
+				string.b.gsub(/%([0-9A-Fa-f]{2})?/) do
+					unless hexadecimal = $1
+						raise ArgumentError, "String contains malformed percent encoding!"
+					end
+					
+					Integer(hexadecimal, 16).chr
 				end.force_encoding(encoding)
 			end
 			
-			# Unescapes a percent encoded path component, preserving encoded path separators.
-			#
-			# This method unescapes percent-encoded characters except for path separators
-			# (forward slash `/` and backslash `\`). This prevents encoded separators like
-			# `%2F` or `%5C` from being decoded into actual path separators, which could
-			# allow bypassing path component boundaries.
-			#
-			# @parameter string [String] The path component to unescape.
-			# @returns [String] The unescaped string with separators still encoded.
-			#
-			# @example
-			#   Encoding.unescape_path("hello%20world")     # => "hello world"
-			#   Encoding.unescape_path("safe%2Fname")       # => "safe%2Fname" (%2F not decoded)
-			#   Encoding.unescape_path("name%5Cfile")       # => "name%5Cfile" (%5C not decoded)
-			def self.unescape_path(string, encoding = string.encoding)
-				string.b.gsub(/%(\h\h)/) do |hex|
-					byte = Integer($1, 16)
-					char = byte.chr
+			# Maps individual URL path segments to and from local filesystem components.
+			#
+			# Unlike generic URL decoding, this encoding rejects values which would turn one
+			# URL segment into multiple local path components.
+			module System
+				ENCODING = ::Encoding.find("filesystem")
+				INVALID_CHARACTER_PATTERN = Regexp.union(["\0", File::SEPARATOR, File::ALT_SEPARATOR].compact)
+				
+				# Encode one local filesystem component as one URL path segment.
+				# @parameter component [String] The local filesystem component.
+				# @returns [String] The encoded URL segment.
+				# @raises [ArgumentError] If the component cannot be converted or contains a system path separator.
+				def self.escape(component)
+					validate(component)
+					Encoding.escape(transcode(component, ::Encoding::UTF_8))
+				end
+				
+				# Decode one URL path segment as one local filesystem component.
+				# @parameter segment [String] The encoded URL segment.
+				# @returns [String] The local filesystem component.
+				# @raises [ArgumentError] If the segment cannot map to one local filesystem component.
+				def self.unescape(segment)
+					component = Encoding.unescape(segment, ::Encoding::UTF_8)
+					validate(component)
+					transcode(component, ENCODING)
+				end
+				
+				# Transcode a path component to the requested character encoding.
+				def self.transcode(component, encoding)
+					component.encode(encoding)
+				rescue ::Encoding::InvalidByteSequenceError, ::Encoding::UndefinedConversionError
+					raise ArgumentError, "Path component could not be transcoded!"
+				end
+				
+				# Validate that a string can represent exactly one local filesystem component.
+				def self.validate(component)
+					unless component.valid_encoding?
+						raise ArgumentError, "Path component has invalid encoding!"
+					end
 					
-					# Don't decode forward slash (0x2F) or backslash (0x5C)
-					if byte == 0x2F || byte == 0x5C
-						hex  # Keep as %2F or %5C
-					else
-						char
+					if INVALID_CHARACTER_PATTERN.match?(component)
+						raise ArgumentError, "Path component contains invalid characters!"
 					end
-				end.force_encoding(encoding)
+				end
+				private_class_method :transcode, :validate
+				private_constant :ENCODING, :INVALID_CHARACTER_PATTERN
 			end
 			
-			# Matches characters that are not allowed in a URI path segment. According to RFC 3986 Section 3.3 (https://tools.ietf.org/html/rfc3986#section-3.3), a valid path segment consists of "pchar" characters. This pattern identifies characters that must be percent-encoded when included in a URI path segment.
-			NON_PATH_CHARACTER_PATTERN = /([^a-zA-Z0-9_\-\.~!$&'()*+,;=:@\/]+)/.freeze
-			
 			# Matches characters that are not allowed in a URI fragment. According to RFC 3986 Section 3.5, a valid fragment consists of pchar / "/" / "?" characters.
 			NON_FRAGMENT_CHARACTER_PATTERN = /([^a-zA-Z0-9_\-\.~!$&'()*+,;=:@\/\?]+)/.freeze
 			
-			# Escapes non-path characters using percent encoding. In other words, this method escapes characters that are not allowed in a URI path segment. According to RFC 3986 Section 3.3 (https://tools.ietf.org/html/rfc3986#section-3.3), a valid path segment consists of "pchar" characters. This method percent-encodes characters that are not "pchar" characters.
-			#
-			# @parameter path [String] The path to escape.
-			# @returns [String] The escaped path.
-			#
-			# @example Escape spaces while preserving path separators.
-			# 	Encoding.escape_path("/documents/my reports/summary.pdf")
-			# 	# => "/documents/my%20reports/summary.pdf"
-			def self.escape_path(path)
-				encoding = path.encoding
-				path.b.gsub(NON_PATH_CHARACTER_PATTERN) do |m|
-					"%" + m.unpack("H2" * m.bytesize).join("%").upcase
-				end.force_encoding(encoding)
-			end
-			
 			# Escapes non-fragment characters using percent encoding. According to RFC 3986 Section 3.5, fragments can contain pchar / "/" / "?" characters.
 			#
 			# @parameter fragment [String] The fragment to escape.
@@ -118,13 +125,13 @@ module Protocol
 			def self.encode(value, prefix = nil)
 				case value
 				when Array
-					return value.map {|v|
+					return value.map do |v|
 						self.encode(v, "#{prefix}[]")
-					}.join("&")
+					end.join("&")
 				when Hash
-					return value.map {|k, v|
+					return value.map do |k, v|
 						self.encode(v, prefix ? "#{prefix}[#{escape(k.to_s)}]" : escape(k.to_s))
-					}.reject(&:empty?).join("&")
+					end.reject(&:empty?).join("&")
 				when nil
 					return prefix
 				else

data/lib/protocol/url/path.rb

@@ -1,122 +1,62 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "encoding"
 
 module Protocol
 	module URL
-		# Represents a relative URL, which does not include a scheme or authority.
-		module Path
-			# Split the given path into its components.
-			# 
-			# - `split("")` => `[]`
-			# - `split("/")` => `["", ""]`
-			# - `split("/a/b/c")` => `["", "a", "b", "c"]`
-			# - `split("a/b/c/")` => `["a", "b", "c", ""]`
-			#
-			# @parameter path [String] The path to split.
-			# @returns [Array(String)] The path components.
-			#
-			# @example Split an absolute path.
-			# 	Path.split("/documents/report.pdf")
-			# 	# => ["", "documents", "report.pdf"]
-			#
-			# @example Split a relative path.
-			# 	Path.split("images/logo.png")
-			# 	# => ["images", "logo.png"]
-			def self.split(path)
-				return path.split("/", -1)
-			end
-			
-			# Join the given path components into a single path.
-			#
-			# @parameter components [Array(String)] The path components to join.
-			# @returns [String] The joined path.
-			#
-			# @example Join absolute path components.
-			# 	Path.join(["", "documents", "report.pdf"])
-			# 	# => "/documents/report.pdf"
-			#
-			# @example Join relative path components.
-			# 	Path.join(["images", "logo.png"])
-			# 	# => "images/logo.png"
-			def self.join(components)
-				return components.join("/")
-			end
-			
-			# Simplify the given path components by resolving "." and "..".
-			#
-			# @parameter components [Array(String)] The path components to simplify.
-			# @returns [Array(String)] The simplified path components.
-			#
-			# @example Resolve parent directory references.
-			# 	Path.simplify(["documents", "reports", "..", "invoices", "2024.pdf"])
-			# 	# => ["documents", "invoices", "2024.pdf"]
-			#
-			# @example Remove current directory references.
-			# 	Path.simplify(["documents", ".", "report.pdf"])
-			# 	# => ["documents", "report.pdf"]
-			def self.simplify(components)
-				output = []
-				
-				components.each_with_index do |component, index|
-					if index == 0 && component == ""
-						# Preserve leading slash:
-						output << ""
-					elsif component == "."
-						# Handle current directory - trailing . means directory, preserve trailing slash:
-						output << "" if index == components.size - 1
-					elsif component == "" && index != components.size - 1
-						# Ignore empty segments (multiple slashes) except at end - no-op.
-					elsif component == ".." && output.last && output.last != ".."
-						# Handle parent directory: go up one level if not at root:
-						output.pop if output.last != ""
-						# Trailing .. means directory, preserve trailing slash:
-						output << "" if index == components.size - 1
-					else
-						# Regular path component:
-						output << component
-					end
+		# Represents a URL path without losing its encoded segment boundaries.
+		#
+		# String input is interpreted as an encoded URL path. A literal `/` is structural,
+		# while `%2F` remains encoded data within a single segment. Decoding is explicit and
+		# controlled by the encoding object passed to {components}.
+		class Path
+			include Comparable
+			
+			# The path separator.
+			SEPARATOR = "/"
+			
+			EMPTY_SEGMENTS = [].freeze
+			ROOT_SEGMENTS = ["", ""].freeze
+			private_constant :EMPTY_SEGMENTS, :ROOT_SEGMENTS
+			
+			# Coerce an encoded string or encoded segment array into a path.
+			#
+			# @parameter path [String | Array(String) | Path] The encoded value to coerce.
+			# @returns [Path] The coerced path, or the existing path unchanged.
+			def self.[](path)
+				if path.is_a?(self)
+					return path
+				elsif path.is_a?(Array)
+					return self.new(nil, path)
+				else
+					return self.new(path.to_s)
 				end
-				
-				return output
 			end
 			
-			# @parameter pop [Boolean] whether to remove the last path component of the base path, to conform to URI merging behaviour, as defined by RFC2396.
+			# Construct a path from decoded components.
 			#
-			# @example Expand a relative path against a base path.
-			# 	Path.expand("/documents/reports/", "invoices/2024.pdf")
-			# 	# => "/documents/reports/invoices/2024.pdf"
+			# Each component is escaped independently, so decoded `/` characters remain data
+			# inside one encoded segment rather than becoming structural separators.
 			#
-			# @example Navigate to parent directory.
-			# 	Path.expand("/documents/reports/2024/", "../summary.pdf")
-			# 	# => "/documents/reports/summary.pdf"
-			def self.expand(base, relative, pop = true)
-				# Empty relative path means no change:
-				return base if relative.nil? || relative.empty?
-				
-				components = split(base)
-				
-				# RFC2396 Section 5.2:
-				# 6) a) All but the last segment of the base URI's path component is
-				# copied to the buffer.  In other words, any characters after the
-				# last (right-most) slash character, if any, are excluded.
-				if pop and components.last != ".."
-					components.pop
-				elsif components.last == ""
-					components.pop
-				end
-				
-				relative = relative.split("/", -1)
-				if relative.first == ""
-					components = relative
-				else
-					components.concat(relative)
+			# @parameter components [Array(String)] The decoded path components.
+			# @parameter encoding [Object] An object implementing `escape(String)`.
+			# @returns [Path] The encoded path.
+			# @raises [ArgumentError] If the encoding does not produce one valid encoded segment per component.
+			def self.for(components, encoding: Encoding)
+				segments = components.map do |component|
+					segment = encoding.escape(component)
+					
+					unless segment.is_a?(String) && !segment.include?(SEPARATOR)
+						raise ArgumentError, "Path encoding produced an invalid segment!"
+					end
+					
+					segment
 				end
 				
-				return join(simplify(components))
+				return self.new(nil, segments)
 			end
 			
 			# Calculate the relative path from one absolute path to another.
@@ -136,58 +76,368 @@ module Protocol
 			# 	Path.relative("/docs/guide.html", "/docs/index.html")
 			# 	# => "guide.html"
 			def self.relative(target, from)
-				target_components = split(target)
-				from_components = split(from)
+				return Path[target].relative(from).to_s
+			end
+			
+			# Initialize a path from either its complete encoded representation or encoded segments.
+			#
+			# @parameter encoded [String | Nil] The encoded URL path.
+			# @parameter segments [Array(String) | Nil] The encoded path segments.
+			# @raises [ArgumentError] If an encoded segment contains a structural separator.
+			def initialize(encoded, segments = nil)
+				if encoded
+					@encoded = -encoded
+				end
+				
+				if encoded.nil? && segments.nil?
+					segments = EMPTY_SEGMENTS
+				elsif segments
+					segments.each do |segment|
+						unless segment.is_a?(String) && !segment.include?(SEPARATOR)
+							raise ArgumentError, "Path contains an invalid encoded segment!"
+						end
+					end
+					
+					segments = segments.map(&:-@).freeze
+				end
+				
+				@segments = segments
+			end
+			
+			# Freeze the path and materialize both lossless representations.
+			# @returns [Path] The frozen path.
+			def freeze
+				return self if frozen?
+				
+				self.segments
+				self.encoded
+				
+				return super
+			end
+			
+			# @returns [Boolean] Whether the path begins at the URL path root.
+			def absolute?
+				encoded.start_with?(SEPARATOR)
+			end
+			
+			# @returns [Boolean] Whether the path is relative to another URL path.
+			def relative?
+				!absolute?
+			end
+			
+			# @returns [Boolean] Whether the path has a trailing separator.
+			def directory?
+				encoded.end_with?(SEPARATOR)
+			end
+			
+			# The final decoded component. A path with a trailing separator has an empty basename.
+			#
+			# @parameter extension [Boolean] Whether to include the final file extension.
+			# @returns [String | Nil] The final component, or `nil` for an empty path.
+			def basename(extension: true)
+				component = self.components.last
+				return component if extension || component.nil?
+				
+				if index = component.rindex(".")
+					basename = component[0...index]
+					return basename if basename.b.match?(/[^.]/n)
+				end
+				
+				return component
+			end
+			
+			# Return a path with its final component removed.
+			#
+			# The empty path and absolute root are their own parents. For a directory path,
+			# this removes the trailing empty component which represents its separator.
+			#
+			# @parameter level [Integer] The number of components to remove.
+			# @returns [Path] The parent path.
+			# @raises [ArgumentError] If `level` is not a non-negative integer.
+			def parent(level = 1)
+				unless level.is_a?(Integer) && level >= 0
+					raise ArgumentError, "Path parent level must be a non-negative integer!"
+				end
+				
+				segments = self.segments
+				return self if level == 0 || segments.empty? || segments == ROOT_SEGMENTS
+				
+				remaining = segments.size - level
+				if absolute?
+					segments = remaining <= 1 ? ROOT_SEGMENTS : segments.first(remaining)
+				else
+					segments = remaining <= 0 ? EMPTY_SEGMENTS : segments.first(remaining)
+				end
+				
+				return self.class.new(nil, segments)
+			end
+			
+			# @returns [Array(String)] The encoded segments, preserving their exact spelling.
+			def segments
+				@segments ||= @encoded.split(SEPARATOR, -1).map!(&:-@).freeze
+			end
+			
+			# Decode the path segments using the given encoding.
+			#
+			# The result is not cached because different encoding objects can produce different
+			# component values. In particular, a decoded component may contain `/` without
+			# changing its boundary in the returned array.
+			#
+			# @parameter encoding [Object] An object implementing `unescape(String)`.
+			# @returns [Array(String)] The decoded components.
+			def components(encoding = Encoding)
+				segments.map{|segment| encoding.unescape(segment)}
+			end
+			
+			# @returns [String] The encoded URL path.
+			def encoded
+				@encoded ||= @segments.join(SEPARATOR).freeze
+			end
+			
+			# @returns [Boolean] Whether the path contains no components.
+			def empty?
+				encoded.empty?
+			end
+			
+			# Paths compare by their exact encoded representation.
+			def <=>(other)
+				return nil unless other.is_a?(Path)
+				
+				encoded <=> other.encoded
+			end
+			
+			# @parameter other [Object] The value to compare with this path.
+			# @returns [Boolean] Whether both paths have the same encoded representation.
+			def ==(other)
+				eql?(other)
+			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.
+			def eql?(other)
+				other.is_a?(Path) && encoded.eql?(other.encoded)
+			end
+			
+			# @returns [Integer] A hash derived from the exact encoded representation.
+			def hash
+				encoded.hash
+			end
+			
+			# Resolve a URL path beneath a local filesystem root.
+			#
+			# Each decoded URL component must map to exactly one local path component. Components
+			# containing NUL or a platform path separator cannot be represented and are rejected.
+			# Absolute URL paths are interpreted relative to `root`, not the filesystem root.
+			#
+			# @parameter root [String] The filesystem root beneath which to resolve the URL path.
+			# @returns [String] The expanded local filesystem path.
+			# @raises [ArgumentError] If a URL segment is invalid or the path escapes the specified root.
+			#
+			# This establishes lexical containment only. It does not resolve symbolic links or
+			# prevent filesystem races while a returned path is subsequently opened.
+			def local_path(root)
+				root = File.expand_path(root)
+				root_prefix = root.end_with?(File::SEPARATOR) ? root : root + File::SEPARATOR
+				
+				components = self.components(Encoding::System)
+				components.shift if components.first == ""
+				
+				path = File.expand_path(File.join(root, *components))
+				return path if path == root || path.start_with?(root_prefix)
+				
+				raise ArgumentError, "Path escapes the specified root!"
+			end
+			
+			alias to_s encoded
+			alias to_str encoded
+			
+			# 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`.
+			def simplify!
+				simplified = simplify
+				return nil if simplified.equal?(self)
+				
+				@encoded = simplified.encoded
+				@segments = simplified.segments
+				
+				return self
+			end
+			
+			# Return a canonical path by resolving literal or percent-encoded dot segments and repeated separators.
+			#
+			# Absolute paths do not retain parent components above the root. Relative paths
+			# retain leading parent components which cannot be resolved locally.
+			#
+			# @returns [Path] The simplified path, or this path if already canonical.
+			def simplify
+				segments = simplify_segments
+				return self unless segments
+				
+				return self.class.new(nil, segments)
+			end
+			
+			# Resolve another path relative to this path.
+			#
+			# @parameter other [String | Array(String) | Path] The path to resolve.
+			# @parameter pop [Boolean] Whether to remove the final base component first.
+			# @parameter simplify [Boolean] Whether to simplify the resulting components.
+			# @returns [Path] The resolved path.
+			def join(other, pop: true, simplify: true)
+				other = Path[other]
+				return self if other.empty?
+				
+				if other.absolute?
+					return simplify ? other.simplify : other
+				end
+				
+				segments = self.segments.dup
+				
+				# RFC2396 Section 5.2:
+				# 6) a) All but the last segment of the base URI's path component is
+				# copied to the buffer.  In other words, any characters after the
+				# last (right-most) slash character, if any, are excluded.
+				if pop and dot_segment(segments.last) != ".."
+					segments.pop
+				elsif segments.last == ""
+					segments.pop
+				end
+				
+				segments.concat(other.segments)
+				
+				if simplify
+					simplify_segments!(segments)
+				end
+				
+				return Path.new(nil, segments)
+			end
+			
+			# Calculate this path relative to another path.
+			#
+			# @parameter from [String | Array(String) | Path] The source path.
+			# @returns [Path] The relative path from `from` to this path.
+			def relative(from)
+				target_segments = self.segments
+				from_segments = Path[from].segments
 				
 				# Remove the last component from 'from' to get the directory
-				from_components = from_components[0...-1] if from_components.size > 0
+				from_segments = from_segments[0...-1] if from_segments.size > 0
 				
 				# Find the common prefix
 				common_length = 0
-				[target_components.size, from_components.size].min.times do |i|
-					break if target_components[i] != from_components[i]
+				[target_segments.size, from_segments.size].min.times do |i|
+					break if target_segments[i] != from_segments[i]
 					common_length = i + 1
 				end
 				
 				# Calculate how many levels to go up
-				up_levels = from_components.size - common_length
+				up_levels = from_segments.size - common_length
 				
-				# Build the relative path components
-				relative_components = [".."] * up_levels + target_components[common_length..-1]
+				# Build the relative path segments
+				relative_segments = [".."] * up_levels + target_segments[common_length..-1]
 				
-				return join(relative_components)
+				return Path.new(nil, relative_segments)
 			end
 			
-			# Convert a URL path to a local file system path using the platform's file separator.
-			#
-			# This method splits the URL path on `/` characters, unescapes each component using
-			# {Encoding.unescape_path} (which preserves encoded separators), then joins the
-			# components using `File.join`.
-			#
-			# Percent-encoded path separators (`%2F` for `/` and `%5C` for `\`) are NOT decoded,
-			# preventing them from being interpreted as directory boundaries. This ensures that
-			# URL path components map directly to file system path components.
-			#
-			# @parameter path [String] The URL path to convert (should be percent-encoded).
-			# @returns [String] The local file system path.
-			#
-			# @example Generating local paths.
-			# 	Path.to_local_path("/documents/report.pdf")  # => "/documents/report.pdf"
-			# 	Path.to_local_path("/files/My%20Document.txt")  # => "/files/My Document.txt"
+			private
+			
+			# 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
+			# `%2e%2e` as dot segments, case-insensitively.
 			#
-			# @example Preserves encoded separators.
-			# 	Path.to_local_path("/folder/safe%2Fname/file.txt")
-			# 	# => "/folder/safe%2Fname/file.txt"
-			# 	# %2F is NOT decoded to prevent creating additional path components
-			def self.to_local_path(path)
-				components = split(path)
+			# This classification does not decode or rewrite the stored encoded segment.
+			# Paths retain their exact encoded representation unless a structural operation
+			# removes the segment. General percent-encoding normalization, such as decoding
+			# other unreserved characters or uppercasing hexadecimal digits, must be an
+			# explicit operation rather than part of lossless path storage or simplification.
+			def dot_segment(segment)
+				return nil unless segment
+				return "." if segment.match?(/\A(?:\.|%2e)\z/i)
+				return ".." if segment.match?(/\A(?:\.|%2e){2}\z/i)
+			end
+			
+			# Find the first encoded segment which requires simplification.
+			def simplification_index(segments)
+				absolute = segments.first == ""
+				regular_segment = false
+				last_index = segments.size - 1
+				
+				segments.each_with_index do |segment, index|
+					dot = dot_segment(segment)
+					
+					if dot == "."
+						return index
+					elsif segment == ""
+						# Leading and trailing empty components are significant.
+						return index if index > 0 && index < last_index
+					elsif dot == ".."
+						# Absolute paths cannot retain parent components. Relative paths
+						# can retain them only before the first regular component.
+						return index if absolute || regular_segment
+					else
+						regular_segment = true
+					end
+				end
+				
+				return nil
+			end
+			
+			# Return simplified encoded segments, or nil if they are already canonical.
+			def simplify_segments
+				segments = self.segments
+				return nil unless start_index = simplification_index(segments)
+				
+				segments = segments.dup
+				simplify_segments!(segments, start_index)
+				
+				return segments
+			end
+			
+			# Simplify the given encoded segments in place.
+			def simplify_segments!(segments, start_index = nil)
+				start_index ||= simplification_index(segments)
+				return nil unless start_index
+				
+				offset = start_index
+				index = start_index
+				last_index = segments.size - 1
+				
+				while index <= last_index
+					segment = segments[index]
+					dot = dot_segment(segment)
+					
+					if dot == "."
+						# A trailing dot denotes a directory.
+						if index == last_index
+							segments[offset] = ""
+							offset += 1
+						end
+					elsif segment == "" && index != last_index
+						# Collapse repeated separators.
+					elsif dot == ".." && offset > 0 && dot_segment(segments[offset - 1]) != ".."
+						# Pop a component, but never pop the absolute-path root.
+						offset -= 1 if segments[offset - 1] != ""
+						
+						# A trailing parent reference also denotes a directory.
+						if index == last_index
+							segments[offset] = ""
+							offset += 1
+						end
+					else
+						segments[offset] = segment if offset < index
+						offset += 1
+					end
+					
+					index += 1
+				end
 				
-				# Unescape each component, preserving encoded path separators
-				components.map! do |component|
-					Encoding.unescape_path(component)
+				if offset < segments.size
+					segments[offset, segments.size - offset] = EMPTY_SEGMENTS
 				end
 				
-				return File.join(*components)
+				return segments
 			end
 		end
 	end

data/lib/protocol/url/reference.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "pattern"
 require_relative "encoding"
@@ -21,8 +21,8 @@ module Protocol
 			#
 			# This method provides flexible conversion from various types into a {Reference}.
 			# When given a {String}, it parses the URL-encoded path, query, and fragment components
-			# and unescapes them for internal storage. When given a {Relative}, it converts the
-			# encoded values to unescaped form suitable for {Reference} instances.
+			# and preserves the path as a {Path}. When given a {Relative}, it preserves the
+			# existing path and its component boundaries.
 			#
 			# @parameter value [String | Relative | Nil] The value to coerce.
 			# @parameter parameters [Hash | Nil] Optional user-supplied parameters to append to the query string.
@@ -34,7 +34,7 @@ module Protocol
 			#
 			# @example Coerce a string with path, query, and fragment.
 			# 	reference = Reference["/search?q=ruby#results"]
-			# 	reference.path      # => "/search"
+			# 	reference.path.to_s # => "/search"
 			# 	reference.query     # => "q=ruby"
 			# 	reference.fragment  # => "results"
 			#
@@ -45,7 +45,7 @@ module Protocol
 			# @example Coerce a Relative instance.
 			# 	relative = Relative.new("/path%20with%20spaces", nil, "top")
 			# 	reference = Reference[relative]
-			# 	reference.path  # => "/path with spaces"
+			# 	reference.path.components  # => ["", "path with spaces"]
 			def self.[](value, parameters = nil)
 				case value
 				when String
@@ -54,9 +54,8 @@ module Protocol
 						query = match[:query]
 						fragment = match[:fragment]
 						
-						# Unescape path and fragment for user-friendly internal storage:
-						# Query strings are kept as-is since they contain = and & syntax
-						path = Encoding.unescape(path) if path && !path.empty?
+						# Paths retain their encoded structure while exposing decoded components.
+						path = Path[path]
 						fragment = Encoding.unescape(fragment) if fragment
 						
 						self.new(path, query, fragment, parameters)
@@ -64,11 +63,9 @@ module Protocol
 						raise ArgumentError, "Invalid URL (contains whitespace or control characters): #{value.inspect}"
 					end
 				when Relative
-					# Relative stores encoded values, so we need to unescape them for Reference:
+					# Relative stores an encoded path; preserve its component boundaries.
 					path = value.path
 					fragment = value.fragment
-					
-					path = Encoding.unescape(path) if path && !path.empty?
 					fragment = Encoding.unescape(fragment) if fragment
 					
 					self.new(path, value.query, fragment, parameters)
@@ -77,20 +74,22 @@ module Protocol
 				else
 					raise ArgumentError, "Cannot coerce #{value.inspect} to Reference!"
 				end
-			end			# Generate a reference from a path and user parameters. The path may contain a `#fragment` or `?query=parameters`.
+			end
+			
+			# Generate a reference from a path and user parameters. The path may contain a `#fragment` or `?query=parameters`.
 			#
 			# @example Parse a path with query and fragment.
 			# 	reference = Reference.parse("/search?query=ruby#results")
-			# 	reference.path      # => "/search"
+			# 	reference.path.to_s # => "/search"
 			# 	reference.query     # => "query=ruby"
 			# 	reference.fragment  # => "results"
 			def self.parse(value = "/", parameters = nil)
 				self.[](value, parameters)
 			end
 			
-			# Initialize the reference with raw, unescaped values.
+			# Initialize the reference from an encoded path and reference values.
 			#
-			# @parameter path [String] The unescaped path.
+			# @parameter path [String | Path] The encoded path string, or an existing path.
 			# @parameter query [String | Nil] An already-formatted query string.
 			# @parameter fragment [String | Nil] The unescaped fragment.
 			# @parameter parameters [Hash | Nil] User supplied parameters that will be safely encoded.
@@ -161,10 +160,10 @@ module Protocol
 			end
 			
 			# Append the reference to the given buffer.
-			# Encodes the path and fragment which are stored unescaped internally.
+			# Encodes the fragment; the path already retains its encoded structure.
 			# Query strings are passed through as-is (they contain = and & which are valid syntax).
 			def append(buffer = String.new)
-				buffer << Encoding.escape_path(@path)
+				buffer << @path.encoded
 				
 				if @query and !@query.empty?
 					buffer << "?" << @query
@@ -185,7 +184,7 @@ module Protocol
 				other = self.class[other]
 				
 				self.class.new(
-					Path.expand(self.path, other.path, true),
+					@path.join(other.path),
 					other.query,
 					other.fragment,
 					other.parameters,
@@ -199,7 +198,7 @@ module Protocol
 			
 			# Update the reference with the given path, query, fragment, and parameters.
 			#
-			# @parameter path [String] Append the string to this reference similar to `File.join`.
+			# @parameter path [String | Path] Append the encoded path to this reference similar to `File.join`.
 			# @parameter query [String | Nil] Replace the query string. Defaults to keeping the existing query if not specified.
 			# @parameter fragment [String | Nil] Replace the fragment. Defaults to keeping the existing fragment if not specified.
 			# @parameter parameters [Hash | false] Parameters to merge or replace. Pass `false` (default) to keep existing parameters.
@@ -251,7 +250,11 @@ module Protocol
 					end
 				end
 				
-				path = Path.expand(@path, path, pop)
+				if path.nil?
+					path = @path
+				else
+					path = @path.join(path, pop: pop)
+				end
 				
 				self.class.new(path, query, fragment, parameters)
 			end

data/lib/protocol/url/relative.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "encoding"
 require_relative "path"
@@ -14,16 +14,28 @@ module Protocol
 			
 			# Initialize a new relative URL.
 			#
-			# @parameter path [String] The path component.
+			# @parameter path [String | Path] The encoded path component.
 			# @parameter query [String, nil] The query string.
 			# @parameter fragment [String, nil] The fragment identifier.
 			def initialize(path, query = nil, fragment = nil)
-				@path = path.to_s
+				@path = Path[path]
 				@query = query
 				@fragment = fragment
 			end
 			
-			# @attribute [String] The path component of the URL.
+			# Freeze the URL and its direct components.
+			# @returns [Relative] The frozen URL.
+			def freeze
+				return self if frozen?
+				
+				@path.freeze
+				@query.freeze
+				@fragment.freeze
+				
+				return super
+			end
+			
+			# @attribute [Path] The path component of the URL.
 			attr :path
 			
 			# @attribute [String, nil] The query string component.
@@ -32,13 +44,17 @@ module Protocol
 			# @attribute [String, nil] The fragment identifier.
 			attr :fragment
 			
-			# Convert the URL path to a local filesystem path.
+			# Resolve the URL path beneath a local filesystem root.
 			#
-			# @returns [String] The local filesystem path.
-			def to_local_path
-				Path.to_local_path(@path)
+			# @parameter root [String] The filesystem root beneath which to resolve the URL path.
+			# @returns [String] The expanded local filesystem path.
+			# @raises [ArgumentError] If a URL segment is invalid or the path escapes the specified root.
+			def local_path(root)
+				@path.local_path(root)
 			end
 			
+			alias to_local_path local_path
+			
 			# @returns [Boolean] If there is a query string.
 			def query?
 				@query and !@query.empty?
@@ -58,13 +74,13 @@ module Protocol
 			# 	base = Relative.new("/documents/reports/")
 			# 	other = Relative.new("invoices/2024.pdf")
 			# 	result = base + other
-			# 	result.path  # => "/documents/reports/invoices/2024.pdf"
+			# 	result.path.to_s  # => "/documents/reports/invoices/2024.pdf"
 			#
 			# @example Navigate to parent directory.
 			# 	base = Relative.new("/documents/reports/archive/")
 			# 	other = Relative.new("../../summary.pdf")
 			# 	result = base + other
-			# 	result.path  # => "/documents/summary.pdf"
+			# 	result.path.to_s  # => "/documents/summary.pdf"
 			def +(other)
 				case other
 				when Absolute
@@ -74,7 +90,7 @@ module Protocol
 				when Relative
 					# Relative + Relative: merge paths directly
 					self.class.new(
-						Path.expand(self.path, other.path, true),
+						@path.join(other.path),
 						other.query,
 						other.fragment
 					)
@@ -104,7 +120,9 @@ module Protocol
 			# 	updated = url.with(path: "report.pdf", pop: false)
 			# 	updated.to_s  # => "/documents/report.pdf"
 			def with(path: nil, query: @query, fragment: @fragment, pop: true)
-				self.class.new(Path.expand(@path, path, pop), query, fragment)
+				path = @path.join(path, pop: pop) unless path.nil?
+				
+				self.class.new(path || @path, query, fragment)
 			end
 			
 			# Normalize the path by resolving "." and ".." segments and removing duplicate slashes.
@@ -119,11 +137,9 @@ module Protocol
 			# @example Basic normalization
 			#   url = Relative.new("/foo//bar/./baz/../qux")
 			#   url.normalize!
-			#   url.path  # => "/foo/bar/qux"
+			#   url.path.to_s  # => "/foo/bar/qux"
 			def normalize!
-				components = Path.split(@path)
-				normalized = Path.simplify(components)
-				@path = Path.join(normalized)
+				@path = @path.simplify
 				
 				return self
 			end
@@ -131,7 +147,7 @@ module Protocol
 			# Append the relative URL to the given buffer.
 			# The path, query, and fragment are expected to already be properly encoded.
 			def append(buffer = String.new)
-				buffer << @path
+				buffer << @path.encoded
 				
 				if @query and !@query.empty?
 					buffer << "?" << @query
@@ -217,6 +233,7 @@ module Protocol
 			def inspect
 				"#<#{self.class} #{to_s}>"
 			end
+			
 		end
 	end
 end

data/lib/protocol/url/version.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 # @namespace
 module Protocol
 	# @namespace
 	module URL
-		VERSION = "0.10.0"
+		VERSION = "0.11.0"
 	end
 end

data/lib/protocol/url.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "url/version"
 require_relative "url/error"

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2025, by Samuel Williams.  
+Copyright, 2025-2026, by Samuel Williams.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/notes.md

@@ -0,0 +1,17 @@
+# Follow-up Notes
+
+## Update `low-rb/low_loop`
+
+File a follow-up PR against [`low-rb/low_loop`](https://github.com/low-rb/low_loop). Its file server currently uses the removed `Protocol::URL::Path.to_local_path` API in `lib/servers/file_server.rb`:
+
+```ruby
+filepath = Protocol::URL::Path.to_local_path(Protocol::URL[event.request.path].path)
+```
+
+Update it to use the `Path` instance returned by `URL#path`:
+
+```ruby
+filepath = Protocol::URL[event.request.path].path.local_path(web_root)
+```
+
+This call is security-sensitive because it converts an untrusted request path into a filesystem path. Confirm that the updated code passes `web_root` directly to `local_path`, handles traversal errors, and has an explicit policy for symlinks beneath the served root.

data/readme.md

@@ -16,11 +16,72 @@ Please see the [project documentation](https://socketry.github.io/protocol-url/)
 
 We welcome contributions to this project.
 
-1.  Fork it.
+1.  Fork the repository.
 2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some feature'`).
+3.  Commit your changes (`git commit -am 'Add some feature.'`).
 4.  Push to the branch (`git push origin my-new-feature`).
-5.  Create new Pull Request.
+5.  Create a new pull request.
+
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+Please see the [project releases](https://socketry.github.io/protocol-url/releases/index) for all releases.
+
+### 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.1.0
+
+  - Initial implementation.
 
 ### Developer Certificate of Origin
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-url
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -54,14 +54,17 @@ files:
 - lib/protocol/url/relative.rb
 - lib/protocol/url/version.rb
 - license.md
+- notes.md
 - readme.md
 - releases.md
 homepage: https://github.com/socketry/protocol-url
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/socketry/protocol-url.git
+  bug_tracker_uri: https://github.com/socketry/protocol-url/issues
+  changelog_uri: https://github.com/socketry/protocol-url/blob/main/releases.md
   documentation_uri: https://socketry.github.io/protocol-url/
+  source_code_uri: https://github.com/socketry/protocol-url.git
 rdoc_options: []
 require_paths:
 - lib
@@ -69,7 +72,7 @@ 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:
   - - ">="