protocol-url 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85a50d979d385fbef9e8defa4e94f98832aca156dc86f79352a4b62673f30e2e
+  data.tar.gz: 71ea54c2460fc94773c13c8cc334f66fef89974efd71bd89537487f0833b844e
+SHA512:
+  metadata.gz: '0903cee8e33682b465b633a7bbdb2b34e52800b476cf550a06c2fec5cc328532cfd1dac820cfafe31a76500982f92cbbd566af9168ede9cd1e6ccdd9d9b72887'
+  data.tar.gz: 7c12517bafaa34bae712abacfe299231a858a12d9f9b37dd188f3275e20008bf116fab85bb53843a55834978866365444d210b93d51ea2e05b7a2d2a9a35ae1a

checksums.yaml.gz.sig

@@ -0,0 +1,3 @@
+��8>w�,��܍�Pj��Ջ�f�ԙ��P;J�j�!\�l��y��
+P�N��J�>w=E6��W`�W�iJ(:1lACΞ�}�%�ئ�4�BS����߽��Y�U(%qZ)�l[u�%
+�f��6�'��0Q?�Cq��ڐ흝h�c�]:V�Y����_�0%�R��{��0fr"�Q4���T��`Bغ����8R��q4u�ə6��*���?-�$�ߣI6��&y

data/lib/protocol/url/absolute.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "relative"
+
+module Protocol
+	module URL
+		# Represents an absolute URL with scheme and/or authority.
+		# Examples: "https://example.com/path", "//cdn.example.com/lib.js", "http://localhost/"
+		class Absolute < Relative
+			def initialize(scheme, authority, path = "/", query = nil, fragment = nil)
+				@scheme = scheme
+				@authority = authority
+				
+				# Initialize the parent Relative class with the path component
+				super(path, query, fragment)
+			end
+			
+			attr :scheme
+			attr :authority
+			
+			def scheme?
+				@scheme and !@scheme.empty?
+			end
+			
+			def authority?
+				@authority and !@authority.empty?
+			end
+			
+			# Combine this absolute URL with a relative reference according to RFC 3986 Section 5.
+			#
+			# @parameter other [String, Relative, Reference, Absolute] The reference to resolve.
+			# @returns [Absolute, String] The resolved absolute URL.
+			#
+			# @example Resolve a relative path.
+			# 	base = Absolute.new("https", "example.com", "/documents/reports/")
+			# 	relative = Relative.new("summary.pdf")
+			# 	result = base + relative
+			# 	result.to_s  # => "https://example.com/documents/reports/summary.pdf"
+			#
+			# @example Navigate to parent directory.
+			# 	base = Absolute.new("https", "example.com", "/documents/reports/2024/")
+			# 	relative = Relative.new("../../archive/")
+			# 	result = base + relative
+			# 	result.to_s  # => "https://example.com/documents/archive/"
+			def +(other)
+				case other
+				when Absolute
+					# If other is already absolute with a scheme, return it as-is:
+					return other if other.scheme
+					# Protocol-relative URL: inherit scheme from base:
+					return Absolute.new(@scheme, other.authority, other.path, other.query, other.fragment)
+				when Relative
+					# Already a Relative, use directly.
+				when String
+					other = URL[other]
+					# If parsing resulted in an Absolute URL, handle it:
+					if other.is_a?(Absolute)
+						return other if other.scheme
+						# Protocol-relative URL: inherit scheme from base:
+						return Absolute.new(@scheme, other.authority, other.path, other.query, other.fragment)
+					end
+				else
+					raise ArgumentError, "Cannot combine Absolute URL with #{other.class}"
+				end
+				
+				# RFC 3986 Section 5.3: Component Recomposition
+				# At this point, other is a Relative URL
+				
+				# Check for special cases first:
+				if other.path.empty?
+					# Empty path - could be query-only or fragment-only reference:
+					if other.query
+						# Query replacement: use base path with new query:
+						Absolute.new(@scheme, @authority, @path, other.query, other.fragment)
+					else
+						# Fragment-only: keep everything from base, just change fragment:
+						Absolute.new(@scheme, @authority, @path, @query, other.fragment || @fragment)
+					end
+				else
+					# Relative path: merge with base path:
+					path = Path.expand(@path, other.path)
+					Absolute.new(@scheme, @authority, path, other.query, other.fragment)
+				end
+			end
+			
+			# Append the absolute URL to the given buffer.
+			def append(buffer = String.new)
+				buffer << @scheme << ":" if @scheme
+				buffer << "//" << @authority if @authority
+				super(buffer)
+			end
+			
+			UNSPECIFIED = Object.new
+			
+			# 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 pop [Boolean] Whether to pop the last path component before merging.
+			# @returns [Absolute] A new Absolute URL with the modified components.
+			#
+			# @example Change the scheme.
+			# 	url = Absolute.new("http", "example.com", "/page")
+			# 	secure = url.with(scheme: "https")
+			# 	secure.to_s  # => "https://example.com/page"
+			#
+			# @example Update the query string.
+			# 	url = Absolute.new("https", "example.com", "/search", "query=ruby")
+			# 	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)
+			end
+			
+			def to_ary
+				[@scheme, @authority, @path, @query, @fragment]
+			end
+			
+			def <=>(other)
+				to_ary <=> other.to_ary
+			end
+			
+			def to_s
+				append
+			end
+		end
+	end
+end

data/lib/protocol/url/encoding.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Protocol
+	module URL
+		# Helpers for encoding and decoding URL components.
+		module Encoding
+			# Escapes a string using percent encoding, e.g. `a b` -> `a%20b`.
+			#
+			# @parameter string [String] The string to escape.
+			# @returns [String] The escaped string.
+			#
+			# @example Escape spaces and special characters.
+			# 	Encoding.escape("hello world!")
+			# 	# => "hello%20world%21"
+			#
+			# @example Escape unicode characters.
+			# 	Encoding.escape("café")
+			# 	# => "caf%C3%A9"
+			def self.escape(string, encoding = string.encoding)
+				string.b.gsub(/([^a-zA-Z0-9_.\-]+)/) do |m|
+					"%" + m.unpack("H2" * m.bytesize).join("%").upcase
+				end.force_encoding(encoding)
+			end
+			
+			# Unescapes a percent encoded string, e.g. `a%20b` -> `a b`.
+			#
+			# @parameter string [String] The string to unescape.
+			# @returns [String] The unescaped string.
+			#
+			# @example Unescape spaces and special characters.
+			# 	Encoding.unescape("hello%20world%21")
+			# 	# => "hello world!"
+			#
+			# @example Unescape unicode characters.
+			# 	Encoding.unescape("caf%C3%A9")
+			# 	# => "café"
+			def self.unescape(string, encoding = string.encoding)
+				string.b.gsub(/%(\h\h)/) do |hex|
+					Integer($1, 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
+					
+					# Don't decode forward slash (0x2F) or backslash (0x5C)
+					if byte == 0x2F || byte == 0x5C
+						hex  # Keep as %2F or %5C
+					else
+						char
+					end
+				end.force_encoding(encoding)
+			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.
+			# @returns [String] The escaped fragment.
+			def self.escape_fragment(fragment)
+				encoding = fragment.encoding
+				fragment.b.gsub(NON_FRAGMENT_CHARACTER_PATTERN) do |m|
+					"%" + m.unpack("H2" * m.bytesize).join("%").upcase
+				end.force_encoding(encoding)
+			end
+			
+			# Encodes a hash or array into a query string. This method is used to encode query parameters in a URL. For example, `{"a" => 1, "b" => 2}` is encoded as `a=1&b=2`.
+			#
+			# @parameter value [Hash | Array | Nil] The value to encode.
+			# @parameter prefix [String] The prefix to use for keys.
+			#
+			# @example Encode simple parameters.
+			# 	Encoding.encode({"name" => "Alice", "age" => "30"})
+			# 	# => "name=Alice&age=30"
+			#
+			# @example Encode nested parameters.
+			# 	Encoding.encode({"user" => {"name" => "Alice", "role" => "admin"}})
+			# 	# => "user[name]=Alice&user[role]=admin"
+			def self.encode(value, prefix = nil)
+				case value
+				when Array
+					return value.map {|v|
+						self.encode(v, "#{prefix}[]")
+					}.join("&")
+				when Hash
+					return value.map {|k, v|
+						self.encode(v, prefix ? "#{prefix}[#{escape(k.to_s)}]" : escape(k.to_s))
+					}.reject(&:empty?).join("&")
+				when nil
+					return prefix
+				else
+					raise ArgumentError, "value must be a Hash" if prefix.nil?
+					
+					return "#{prefix}=#{escape(value.to_s)}"
+				end
+			end
+			
+			# Scan a string for URL-encoded key/value pairs.
+			# @yields {|key, value| ...}
+			# 	@parameter key [String] The unescaped key.
+			# 	@parameter value [String] The unescaped key.
+			def self.scan(string)
+				string.split("&") do |assignment|
+					next if assignment.empty?
+					
+					key, value = assignment.split("=", 2)
+					
+					yield unescape(key), value.nil? ? value : unescape(value)
+				end
+			end
+			
+			# Split a key into parts, e.g. `a[b][c]` -> `["a", "b", "c"]`.
+			#
+			# @parameter name [String] The key to split.
+			# @returns [Array(String)] The parts of the key.
+			def self.split(name)
+				name.scan(/([^\[]+)|(?:\[(.*?)\])/)&.tap do |parts|
+					parts.flatten!
+					parts.compact!
+				end
+			end
+			
+			# Assign a value to a nested hash.
+			#
+			# This method handles building nested data structures from query string parameters, including arrays of objects. When processing array elements (empty key like `[]`), it intelligently decides whether to add to the last array element or create a new one.
+			#
+			# @parameter keys [Array(String)] The parts of the key.
+			# @parameter value [Object] The value to assign.
+			# @parameter parent [Hash] The parent hash.
+			#
+			# @example Building an array of objects.
+			# 	# Query: items[][name]=a&items[][value]=1&items[][name]=b&items[][value]=2
+			# 	# When "name" appears again, it creates a new array element
+			# 	# Result: {"items" => [{"name" => "a", "value" => "1"}, {"name" => "b", "value" => "2"}]}
+			def self.assign(keys, value, parent)
+				top, *middle = keys
+				
+				middle.each_with_index do |key, index|
+					if key.nil? or key.empty?
+						# Array element (e.g., items[]):
+						parent = (parent[top] ||= Array.new)
+						top = parent.size
+						
+						# Check if we should reuse the last array element or create a new one. If there's a nested key coming next, and the last array element already has that key, then we need a new array element. Otherwise, add to the existing one.
+						if nested = middle[index+1] and last = parent.last
+							# If the last element doesn't include the nested key, reuse it (decrement index).
+							# If it does include the key, keep current index (creates new element).
+							top -= 1 unless last.include?(nested)
+						end
+					else
+						# Hash key (e.g., user[name]):
+						parent = (parent[top] ||= Hash.new)
+						top = key
+					end
+				end
+				
+				parent[top] = value
+			end
+			
+			# Decode a URL-encoded query string into a hash.
+			#
+			# @parameter string [String] The query string to decode.
+			# @parameter maximum [Integer] The maximum number of keys in a path.
+			# @parameter symbolize_keys [Boolean] Whether to symbolize keys.
+			# @returns [Hash] The decoded query string.
+			#
+			# @example Decode simple parameters.
+			# 	Encoding.decode("name=Alice&age=30")
+			# 	# => {"name" => "Alice", "age" => "30"}
+			#
+			# @example Decode nested parameters.
+			# 	Encoding.decode("user[name]=Alice&user[role]=admin")
+			# 	# => {"user" => {"name" => "Alice", "role" => "admin"}}
+			def self.decode(string, maximum = 8, symbolize_keys: false)
+				parameters = {}
+				
+				self.scan(string) do |name, value|
+					keys = self.split(name)
+					
+					if keys.empty?
+						raise ArgumentError, "Invalid key path: #{name.inspect}!"
+					end
+					
+					if keys.size > maximum
+						raise ArgumentError, "Key length exceeded limit!"
+					end
+					
+					if symbolize_keys
+						keys.collect!{|key| key.empty? ? nil : key.to_sym}
+					end
+					
+					self.assign(keys, value, parameters)
+				end
+				
+				return parameters
+			end
+		end
+	end
+end

data/lib/protocol/url/path.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, 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
+				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.
+			#
+			# @example Expand a relative path against a base path.
+			# 	Path.expand("/documents/reports/", "invoices/2024.pdf")
+			# 	# => "/documents/reports/invoices/2024.pdf"
+			#
+			# @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)
+				end
+				
+				return join(simplify(components))
+			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"
+			#
+			# @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)
+				
+				# Unescape each component, preserving encoded path separators
+				components.map! do |component|
+					Encoding.unescape_path(component)
+				end
+				
+				return File.join(*components)
+			end
+		end
+	end
+end

data/lib/protocol/url/reference.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "encoding"
+require_relative "relative"
+
+module Protocol
+	module URL
+		# Represents a "Hypertext Reference", which may include a path, query string, fragment, and user parameters.
+		#
+		# This class is designed to be easy to manipulate and combine URL references, following the rules specified in RFC2396, while supporting standard URL encoded parameters.
+		#
+		# Use {parse} for external/untrusted data, and {new} for constructing references from known good values.
+		class Reference < Relative
+			include Comparable
+			
+			def self.[](value, parameters = nil)
+				case value
+				when String
+					if match = value.match(PATTERN)
+						path = match[:path]
+						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?
+						fragment = Encoding.unescape(fragment) if fragment
+						
+						self.new(path, query, fragment, parameters)
+					else
+						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
+					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)
+				when nil
+					nil
+				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`.
+			#
+			# @example Parse a path with query and fragment.
+			# 	reference = Reference.parse("/search?query=ruby#results")
+			# 	reference.path      # => "/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.
+			#
+			# @parameter path [String] The unescaped 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.
+			#
+			# @example Create a reference with parameters.
+			# 	reference = Reference.new("/search", nil, nil, {"query" => "ruby", "limit" => "10"})
+			# 	reference.to_s  # => "/search?query=ruby&limit=10"
+			def initialize(path = "/", query = nil, fragment = nil, parameters = nil)
+				super(path, query, fragment)
+				@parameters = parameters
+			end
+			
+			# @attribute [Hash] User supplied parameters that will be appended to the query part.
+			attr :parameters
+			
+			# Freeze the reference.
+			#
+			#	@returns [Reference] The frozen reference.
+			def freeze
+				return self if frozen?
+				
+				@parameters.freeze
+				
+				super
+			end
+			
+			# Implicit conversion to an array.
+			#
+			# @returns [Array] The reference as an array, `[path, query, fragment, parameters]`.
+			def to_ary
+				[@path, @query, @fragment, @parameters]
+			end
+			
+			# Compare two references.
+			#
+			# @parameter other [Reference] The other reference to compare.
+			# @returns [Integer] -1, 0, 1 if the reference is less than, equal to, or greater than the other reference.
+			def <=> other
+				to_ary <=> other.to_ary
+			end
+			
+			# @returns [Boolean] Whether the reference has parameters.
+			def parameters?
+				@parameters and !@parameters.empty?
+			end
+			
+			# Parse the query string into parameters and merge with existing parameters.
+			#
+			# Afterwards, the `query` attribute will be cleared.
+			#
+			# @returns [Hash] The merged parameters.
+			def parse_query!(encoding = Encoding)
+				if @query and !@query.empty?
+					parsed = encoding.decode(@query)
+					
+					if @parameters
+						@parameters = @parameters.merge(parsed)
+					else
+						@parameters = parsed
+					end
+					
+					@query = nil
+				end
+				
+				return @parameters
+			end
+			
+			# @returns [Boolean] Whether the reference has a query string.
+			def query?
+				@query and !@query.empty?
+			end
+			
+			# @returns [Boolean] Whether the reference has a fragment.
+			def fragment?
+				@fragment and !@fragment.empty?
+			end
+			
+			# Append the reference to the given buffer.
+			# Encodes the path and fragment which are stored unescaped internally.
+			# Query strings are passed through as-is (they contain = and & which are valid syntax).
+			def append(buffer = String.new)
+				buffer << Encoding.escape_path(@path)
+				
+				if @query and !@query.empty?
+					buffer << "?" << @query
+					buffer << "&" << Encoding.encode(@parameters) if parameters?
+				elsif parameters?
+					buffer << "?" << Encoding.encode(@parameters)
+				end
+				
+				if @fragment and !@fragment.empty?
+					buffer << "#" << Encoding.escape_fragment(@fragment)
+				end
+				
+				return buffer
+			end
+			
+			# Merges two references as specified by RFC2396, similar to `URI.join`.
+			def + other
+				other = self.class[other]
+				
+				self.class.new(
+					Path.expand(self.path, other.path, true),
+					other.query,
+					other.fragment,
+					other.parameters,
+				)
+			end
+			
+			# Just the base path, without any query string, parameters or fragment.
+			def base
+				self.class.new(@path, nil, nil, nil)
+			end
+			
+			# 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 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.
+			# @parameter pop [Boolean] If the path contains a trailing filename, pop the last component of the path before appending the new path.
+			# @parameter merge [Boolean] Controls how parameters are handled. When `true` (default), new parameters are merged with existing ones and query is kept. When `false` and new parameters are provided, parameters replace existing ones and query is cleared. Explicitly passing `query:` always overrides this behavior.
+			#
+			# @example Merge parameters.
+			# 	reference = Reference.new("/search", nil, nil, {"query" => "ruby"})
+			# 	updated = reference.with(parameters: {"limit" => "10"})
+			# 	updated.to_s  # => "/search?query=ruby&limit=10"
+			#
+			# @example Replace parameters.
+			# 	reference = Reference.new("/search", nil, nil, {"query" => "ruby"})
+			# 	updated = reference.with(parameters: {"query" => "python"}, merge: false)
+			# 	updated.to_s  # => "/search?query=python"
+			def with(path: nil, query: false, fragment: @fragment, parameters: false, pop: false, merge: true)
+				if merge
+					# If merging, we keep existing query unless explicitly overridden:
+					if query == false
+						query = @query
+					end
+					
+					# Merge mode: combine new parameters with existing, keep query:
+					# parameters = (@parameters || {}).merge(parameters || {})
+					if @parameters
+						if parameters
+							parameters = @parameters.merge(parameters)
+						else
+							parameters = @parameters
+						end
+					elsif !parameters
+						parameters = @parameters
+					end
+				else
+					# Replace mode: use new parameters if provided, clear query when replacing:
+					if parameters == false
+						# No new parameters provided, keep existing:
+						parameters = @parameters
+						
+						# Also keep query if not explicitly specified:
+						if query == false
+							query = @query
+						end
+					else
+						# New parameters provided, clear query unless explicitly specified:
+						if query == false
+							query = nil
+						end
+					end
+				end
+				
+				path = Path.expand(@path, path, pop)
+				
+				self.class.new(path, query, fragment, parameters)
+			end
+		end
+	end
+end

data/lib/protocol/url/relative.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "encoding"
+require_relative "path"
+
+module Protocol
+	module URL
+		# Represents a relative URL, which does not include a scheme or authority.
+		class Relative
+			include Comparable
+			
+			def initialize(path, query = nil, fragment = nil)
+				@path = path.to_s
+				@query = query
+				@fragment = fragment
+			end
+			
+			attr :path
+			attr :query
+			attr :fragment
+			
+			def to_local_path
+				Path.to_local_path(@path)
+			end
+			
+			# @returns [Boolean] If there is a query string.
+			def query?
+				@query and !@query.empty?
+			end
+			
+			# @returns [Boolean] If there is a fragment.
+			def fragment?
+				@fragment and !@fragment.empty?
+			end
+			
+			# Combine this relative URL with another URL or path.
+			#
+			# @parameter other [String, Absolute, Relative] The URL or path to combine.
+			# @returns [Absolute, Relative] The combined URL.
+			#
+			# @example Combine two relative paths.
+			# 	base = Relative.new("/documents/reports/")
+			# 	other = Relative.new("invoices/2024.pdf")
+			# 	result = base + other
+			# 	result.path  # => "/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"
+			def +(other)
+				case other
+				when Absolute
+					# Relative + Absolute: the absolute URL takes precedence
+					# You can't apply relative navigation to an absolute URL
+					other
+				when Relative
+					# Relative + Relative: merge paths directly
+					self.class.new(
+						Path.expand(self.path, other.path, true),
+						other.query,
+						other.fragment
+					)
+				when String
+					# Relative + String: parse and combine
+					self + URL[other]
+				else
+					raise ArgumentError, "Cannot combine Relative URL with #{other.class}"
+				end
+			end
+			
+			# 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 pop [Boolean] Whether to pop the last path component before merging.
+			# @returns [Relative] A new Relative URL with the modified components.
+			#
+			# @example Update the query string.
+			# 	url = Relative.new("/search", "query=ruby")
+			# 	updated = url.with(query: "query=python")
+			# 	updated.to_s  # => "/search?query=python"
+			#
+			# @example Append to the path.
+			# 	url = Relative.new("/documents/")
+			# 	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)
+			end
+			
+			# Normalize the path by resolving "." and ".." segments and removing duplicate slashes.
+			#
+			# This modifies the URL in-place by simplifying the path component:
+			# - Removes "." segments (current directory)
+			# - Resolves ".." segments (parent directory)
+			# - Collapses multiple consecutive slashes to single slashes (except at start)
+			#
+			# @returns [self] The normalized URL.
+			#
+			# @example Basic normalization
+			#   url = Relative.new("/foo//bar/./baz/../qux")
+			#   url.normalize!
+			#   url.path  # => "/foo/bar/qux"
+			def normalize!
+				components = Path.split(@path)
+				normalized = Path.simplify(components)
+				@path = Path.join(normalized)
+				
+				return self
+			end
+			
+			# 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
+				
+				if @query and !@query.empty?
+					buffer << "?" << @query
+				end
+				
+				if @fragment and !@fragment.empty?
+					buffer << "#" << @fragment
+				end
+				
+				return buffer
+			end
+			
+			def to_ary
+				[@path, @query, @fragment]
+			end
+			
+			def <=>(other)
+				to_ary <=> other.to_ary
+			end
+			
+			def to_s
+				append
+			end
+			
+			def inspect
+				"#<#{self.class} #{to_s}>"
+			end
+		end
+	end
+end

data/lib/protocol/url/version.rb

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

data/lib/protocol/url.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "url/version"
+require_relative "url/encoding"
+require_relative "url/reference"
+require_relative "url/relative"
+require_relative "url/absolute"
+
+module Protocol
+	module URL
+		# RFC 3986 URI pattern with named capture groups.
+		# Matches: [scheme:][//authority][path][?query][#fragment]
+		# Rejects strings containing whitespace or control characters (matching standard URI behavior).
+		PATTERN = %r{
+			\A
+			(?:(?<scheme>[a-z][a-z0-9+.-]*):)?      # scheme (optional)
+			(?://(?<authority>[^/?#\s]*))?          # authority (optional, without //, no whitespace)
+			(?<path>[^?#\s]*)                       # path (no whitespace)
+			(?:\?(?<query>[^#\s]*))?                # query (optional, no whitespace)
+			(?:\#(?<fragment>[^\s]*))?              # fragment (optional, no whitespace)
+			\z
+		}ix
+		private_constant :PATTERN
+		
+		# Coerce a value into an appropriate URL type (Absolute or Relative).
+		#
+		# @parameter value [String, Absolute, Relative, nil] The value to coerce.
+		# @returns [Absolute, Relative, nil] The coerced URL.
+		def self.[](value)
+			case value
+			when String
+				if match = value.match(PATTERN)
+					scheme = match[:scheme]
+					authority = match[:authority]
+					path = match[:path]
+					query = match[:query]
+					fragment = match[:fragment]
+					
+					# If we have a scheme or authority, it's an absolute URL
+					if scheme || authority
+						Absolute.new(scheme, authority, path, query, fragment)
+					else
+						# No scheme or authority, treat as relative:
+						Relative.new(path, query, fragment)
+					end
+				else
+					raise ArgumentError, "Invalid URL (contains whitespace or control characters): #{value.inspect}"
+				end
+			when Relative
+				value
+			when nil
+				nil
+			else
+				raise ArgumentError, "Cannot coerce #{value.inspect} to URL!"
+			end
+		end
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,43 @@
+# Protocol::URL
+
+Provides abstractions for working with URLs.
+
+[![Development Status](https://github.com/socketry/protocol-url/workflows/Test/badge.svg)](https://github.com/socketry/protocol-url/actions?workflow=Test)
+
+## Usage
+
+Please see the [project documentation](https://github.com/socketry/protocol-url) for more details.
+
+  - [Getting Started](https://github.com/socketry/protocol-urlguides/getting-started/index) - This guide explains how to get started with `protocol-url` for parsing, manipulating, and constructing URLs in Ruby.
+
+  - [Working with References](https://github.com/socketry/protocol-urlguides/working-with-references/index) - This guide explains how to use <code class="language-ruby">Protocol::URL::Reference</code> for managing URLs with query parameters and fragments.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-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.
+
+### 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.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.
+
+## Releases
+
+Please see the [project releases](https://github.com/socketry/protocol-urlreleases/index) for all releases.
+
+### v0.1.0
+
+  - Initial implementation.
+
+## See Also
+
+  - [protocol-http](https://github.com/socketry/protocol-http) — HTTP protocol implementation and abstractions.

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v0.1.0
+
+  - Initial implementation.

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: protocol-url
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIE2DCCA0CgAwIBAgIBATANBgkqhkiG9w0BAQsFADBhMRgwFgYDVQQDDA9zYW11
+  ZWwud2lsbGlhbXMxHTAbBgoJkiaJk/IsZAEZFg1vcmlvbnRyYW5zZmVyMRIwEAYK
+  CZImiZPyLGQBGRYCY28xEjAQBgoJkiaJk/IsZAEZFgJuejAeFw0yMjA4MDYwNDUz
+  MjRaFw0zMjA4MDMwNDUzMjRaMGExGDAWBgNVBAMMD3NhbXVlbC53aWxsaWFtczEd
+  MBsGCgmSJomT8ixkARkWDW9yaW9udHJhbnNmZXIxEjAQBgoJkiaJk/IsZAEZFgJj
+  bzESMBAGCgmSJomT8ixkARkWAm56MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIB
+  igKCAYEAomvSopQXQ24+9DBB6I6jxRI2auu3VVb4nOjmmHq7XWM4u3HL+pni63X2
+  9qZdoq9xt7H+RPbwL28LDpDNflYQXoOhoVhQ37Pjn9YDjl8/4/9xa9+NUpl9XDIW
+  sGkaOY0eqsQm1pEWkHJr3zn/fxoKPZPfaJOglovdxf7dgsHz67Xgd/ka+Wo1YqoE
+  e5AUKRwUuvaUaumAKgPH+4E4oiLXI4T1Ff5Q7xxv6yXvHuYtlMHhYfgNn8iiW8WN
+  XibYXPNP7NtieSQqwR/xM6IRSoyXKuS+ZNGDPUUGk8RoiV/xvVN4LrVm9upSc0ss
+  RZ6qwOQmXCo/lLcDUxJAgG95cPw//sI00tZan75VgsGzSWAOdjQpFM0l4dxvKwHn
+  tUeT3ZsAgt0JnGqNm2Bkz81kG4A2hSyFZTFA8vZGhp+hz+8Q573tAR89y9YJBdYM
+  zp0FM4zwMNEUwgfRzv1tEVVUEXmoFCyhzonUUw4nE4CFu/sE3ffhjKcXcY//qiSW
+  xm4erY3XAgMBAAGjgZowgZcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFO9t7XWuFf2SKLmuijgqR4sGDlRsMC4GA1UdEQQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MC4GA1UdEgQnMCWBI3NhbXVlbC53aWxs
+  aWFtc0BvcmlvbnRyYW5zZmVyLmNvLm56MA0GCSqGSIb3DQEBCwUAA4IBgQB5sxkE
+  cBsSYwK6fYpM+hA5B5yZY2+L0Z+27jF1pWGgbhPH8/FjjBLVn+VFok3CDpRqwXCl
+  xCO40JEkKdznNy2avOMra6PFiQyOE74kCtv7P+Fdc+FhgqI5lMon6tt9rNeXmnW/
+  c1NaMRdxy999hmRGzUSFjozcCwxpy/LwabxtdXwXgSay4mQ32EDjqR1TixS1+smp
+  8C/NCWgpIfzpHGJsjvmH2wAfKtTTqB9CVKLCWEnCHyCaRVuKkrKjqhYCdmMBqCws
+  JkxfQWC+jBVeG9ZtPhQgZpfhvh+6hMhraUYRQ6XGyvBqEUe+yo6DKIT3MtGE2+CP
+  eX9i9ZWBydWb8/rvmwmX2kkcBbX0hZS1rcR593hGc61JR6lvkGYQ2MYskBveyaxt
+  Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
+  voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/protocol/url.rb
+- lib/protocol/url/absolute.rb
+- lib/protocol/url/encoding.rb
+- lib/protocol/url/path.rb
+- lib/protocol/url/reference.rb
+- lib/protocol/url/relative.rb
+- lib/protocol/url/version.rb
+- license.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
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Provides abstractions for working with URLs.
+test_files: []