protocol-url 0.10.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aeaada96a9b666006635d0589aefee1a0bbd4b0df7787a40a6c5d40faeb87f1
-  data.tar.gz: 3bb9157f29504fd386b9da7730ad0e346371488a2cd440525ab501a5127d62e4
+  metadata.gz: 67f58bb48277d53b3817bb38b2b7c4546a8a8e1f3df62cea531c577705c4c833
+  data.tar.gz: 55bcfd924be9ae1eada0b2e5f8ee93fcd4a1a24c0693986ed3f8818b26072fd1
 SHA512:
-  metadata.gz: 82707be363eedcc58a739f62acdca6b5b611f8a5e7e36992a2db6b48fdc2c950d7f0b72ebb38bd05cecee8fbeb42453cdb49a6be2a921053169a0bf633a998a7
-  data.tar.gz: 808c99891a07593694ce6ab7542986ef7c95d53d4882c4efef79aec34fb35812824e4c69b7ce11e9fe44fa971f0ee8765408f2997db7e4f9fca25d497f314ece
+  metadata.gz: 7df97ce90f4ce934023217fbedf9cbf864febeee311b9b25e3ee952e647d75d8cc041f16665b84884fec1e1d2dad859f9f3d21a0bfdccf40f832938158a21924
+  data.tar.gz: bb2c1f9fece1eda9cb5ee8b96d216b28e0e15c6fe9605c6ec0d43a615b5b9a247f9bc299553e1d46778d9e6c5971e34d56bbd77f172202002ad63d7be89b53c3

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,9 +14,9 @@ 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 query [String, nil] The query string.
-			# @parameter fragment [String, nil] The fragment identifier.
+			# @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)
 				@scheme = scheme
 				@authority = authority
@@ -25,11 +25,22 @@ module Protocol
 				super(path, query, fragment)
 			end
 			
-			# @attribute [String] The URL scheme.
-			attr :scheme
+			# 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 authority component.
-			attr :authority
+			# @attribute [String | Nil] The URL scheme.
+			attr_accessor :scheme
+			
+			# @attribute [String | Nil] The authority component.
+			attr_accessor :authority
 			
 			# Check if the URL has a non-empty 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
@@ -111,11 +122,11 @@ module Protocol
 			
 			# Create a new Absolute URL with modified components.
 			#
-			# @parameter scheme [String, nil] The scheme to use (nil to remove scheme).
-			# @parameter authority [String, nil] The authority to use (nil to remove authority).
-			# @parameter path [String, nil] The path to merge with the current path.
-			# @parameter query [String, nil] The query string to use.
-			# @parameter fragment [String, nil] The fragment to use.
+			# @parameter scheme [String | Nil] The scheme to use (nil to remove scheme).
+			# @parameter authority [String | Nil] The authority to use (nil to remove authority).
+			# @parameter path [String | Nil] The path to merge with the current path.
+			# @parameter query [String | Nil] The query string to use.
+			# @parameter fragment [String | Nil] The fragment to use.
 			# @parameter pop [Boolean] Whether to pop the last path component before merging.
 			# @returns [Absolute] A new Absolute URL with the modified components.
 			#
@@ -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