protocol-url 0.10.0 → 0.12.0

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.
@@ -103,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.
 			#
@@ -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,31 +14,54 @@ module Protocol
 			
 			# Initialize a new relative URL.
 			#
-			# @parameter path [String] The path component.
-			# @parameter query [String, nil] The query string.
-			# @parameter fragment [String, nil] The fragment identifier.
+			# @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.
-			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
 			
-			# Convert the URL path to a local filesystem path.
+			# @attribute [String | Nil] The fragment identifier.
+			attr_accessor :fragment
+			
+			# 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 +81,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 +97,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
 					)
@@ -88,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.
 			#
@@ -104,7 +127,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 +144,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 +154,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 +240,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.12.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,121 @@ 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.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`.
+
+### 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
 

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## 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.10.0
+  version: 0.12.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:
   - - ">="