protocol-http 0.54.0 → 0.56.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c76db95baeca082a769340ab2a29ee5948bb837894e55039c082653453aa4f4f
-  data.tar.gz: 868cdcc4a21786c640c8c06e7892bfd6ef19f81670a90274692cfadef10a0c39
+  metadata.gz: 5409468cd5dfe153d3ab2ecc8fae839ff0a688e0d54a81aa402395e6b3de0f1e
+  data.tar.gz: 11d700efbe0ecc425438a605f09643bba5bdde1e258bb0508e34428285b209f3
 SHA512:
-  metadata.gz: acc4afb3f7caba7ec2d2611ab72dce9c954e88e8dfe72645645e442d8116909c3f228b22c2d460633d429510ffff5f6f4713bfff751f18d4873db167e773fcbe
-  data.tar.gz: ef0e92bac69dba33417d074c24ce6d2f2009e19e1d81d317eecaf945817f3c7fb0775052048ca24df32b3f39c15f8de83ca45054669e2d89b5bf3b5b445c7cf1
+  metadata.gz: 90bf1b95afe9e830249676ab82cba8306c2184dfac7b105dff9c068eb67484f5002b73ec5141a1f42177042a4016c83a118a875df36f30ab65c8aa4b9b1ed2fb
+  data.tar.gz: 43ce8ee9a1ace9ff2ae0be4d9ae90625415a504fad5162ebf7e8b1f487bab25bae0aa452260b7cd3fe00193c53835c80f730a1ca16ac142c90f827c852119497

data/context/index.yaml

@@ -20,14 +20,6 @@ files:
 - path: middleware.md
   title: Middleware
   description: This guide explains how to build and use HTTP middleware with `Protocol::HTTP::Middleware`.
-- path: hypertext-references.md
-  title: Hypertext References
-  description: This guide explains how to use `Protocol::HTTP::Reference` for constructing
-    and manipulating hypertext references (URLs with parameters).
-- path: url-parsing.md
-  title: URL Parsing
-  description: This guide explains how to use `Protocol::HTTP::URL` for parsing and
-    manipulating URL components, particularly query strings and parameters.
 - path: streaming.md
   title: Streaming
   description: This guide gives an overview of how to implement streaming requests

data/lib/protocol/http/body/stream.rb

@@ -3,13 +3,14 @@
 # Released under the MIT License.
 # Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2023, by Genki Takiuchi.
+# Copyright, 2025, by William T. Nelson.
 
 require_relative "buffered"
 
 module Protocol
 	module HTTP
 		module Body
-			# The input stream is an IO-like object which contains the raw HTTP POST data. When applicable, its external encoding must be “ASCII-8BIT” and it must be opened in binary mode, for Ruby 1.9 compatibility. The input stream must respond to gets, each, read and rewind.
+			# The input stream is an IO-like object which contains the raw HTTP POST data. When applicable, its external encoding must be "ASCII-8BIT" and it must be opened in binary mode, for Ruby 1.9 compatibility. The input stream must respond to gets, each, read and rewind.
 			class Stream
 				# The default line separator, used by {gets}.
 				NEWLINE = "\n"
@@ -315,7 +316,7 @@ module Protocol
 				end
 				
 				# Write data to the stream using {write}.
-				def <<(buffer)
+				def << buffer
 					write(buffer)
 				end
 				

data/lib/protocol/http/cookie.rb

@@ -4,59 +4,66 @@
 # Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2022, by Herrick Fang.
 
-require_relative "url"
+require_relative "quoted_string"
 
 module Protocol
 	module HTTP
 		# Represents an individual cookie key-value pair.
 		class Cookie
+			# Valid cookie name characters according to RFC 6265.
+			# cookie-name = token (RFC 2616 defines token)
+			VALID_COOKIE_KEY = /\A#{TOKEN}\z/.freeze
+			
+			# Valid cookie value characters according to RFC 6265.
+			# cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )
+			# cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
+			# Excludes control chars, whitespace, DQUOTE, comma, semicolon, and backslash
+			VALID_COOKIE_VALUE = /\A[\x21\x23-\x2B\x2D-\x3A\x3C-\x5B\x5D-\x7E]*\z/.freeze
+			
 			# Initialize the cookie with the given name, value, and directives.
 			#
-			# @parameter name [String] The name of the cookiel, e.g. "session_id".
+			# @parameter name [String] The name of the cookie, e.g. "session_id".
 			# @parameter value [String] The value of the cookie, e.g. "1234".
 			# @parameter directives [Hash] The directives of the cookie, e.g. `{"path" => "/"}`.
-			def initialize(name, value, directives)
+			# @raises [ArgumentError] If the name or value contains invalid characters.
+			def initialize(name, value, directives = nil)
+				unless VALID_COOKIE_KEY.match?(name)
+					raise ArgumentError, "Invalid cookie name: #{name.inspect}"
+				end
+				
+				if value && !VALID_COOKIE_VALUE.match?(value)
+					raise ArgumentError, "Invalid cookie value: #{value.inspect}"
+				end
+				
 				@name = name
 				@value = value
 				@directives = directives
 			end
 			
 			# @attribute [String] The name of the cookie.
-			attr :name
+			attr_accessor :name
 			
 			# @attribute [String] The value of the cookie.
-			attr :value
+			attr_accessor :value
 			
 			# @attribute [Hash] The directives of the cookie.
-			attr :directives
-			
-			# Encode the name of the cookie.
-			def encoded_name
-				URL.escape(@name)
-			end
-			
-			# Encode the value of the cookie.
-			def encoded_value
-				URL.escape(@value)
-			end
+			attr_accessor :directives
 			
 			# Convert the cookie to a string.
 			#
 			# @returns [String] The string representation of the cookie.
 			def to_s
-				buffer = String.new.b
+				buffer = String.new
 				
-				buffer << encoded_name << "=" << encoded_value
+				buffer << @name << "=" << @value
 				
 				if @directives
-					@directives.collect do |key, value|
+					@directives.each do |key, value|
 						buffer << ";"
+						buffer << key
 						
-						case value
-						when String
-							buffer << key << "=" << value
-						when TrueClass
-							buffer << key
+						if value != true
+							buffer << "=" << value.to_s
 						end
 					end
 				end
@@ -74,11 +81,7 @@ module Protocol
 				key, value = head.split("=", 2)
 				directives = self.parse_directives(directives)
 				
-				self.new(
-					URL.unescape(key),
-					URL.unescape(value),
-					directives,
-				)
+				self.new(key, value, directives)
 			end
 			
 			# Parse a list of strings into a hash of directives.

data/lib/protocol/http/header/accept.rb

@@ -2,16 +2,17 @@
 
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
+# Copyright, 2025, by William T. Nelson.
 
 require_relative "split"
-require_relative "quoted_string"
+require_relative "../quoted_string"
 require_relative "../error"
 
 module Protocol
 	module HTTP
 		module Header
 			# The `accept-content-type` header represents a list of content-types that the client can accept.
-			class Accept < Array
+			class Accept < Split
 				# Regular expression used to split values on commas, with optional surrounding whitespace, taking into account quoted strings.
 				SEPARATOR = /
 					(?:            # Start non-capturing group
@@ -67,27 +68,26 @@ module Protocol
 					end
 				end
 				
-				# Parse the `accept` header value into a list of content types.
+				# Parses a raw header value.
 				#
-				# @parameter value [String] the value of the header.
-				def initialize(value = nil)
-					if value
-						super(value.scan(SEPARATOR).map(&:strip))
-					end
+				# @parameter value [String] a raw header value containing comma-separated media types.
+				# @returns [Accept] a new instance containing the parsed media types.
+				def self.parse(value)
+					self.new(value.scan(SEPARATOR).map(&:strip))
 				end
 				
 				# Adds one or more comma-separated values to the header.
 				#
 				# The input string is split into distinct entries and appended to the array.
 				#
-				# @parameter value [String] the value or values to add, separated by commas.
-				def << (value)
+				# @parameter value [String] a raw header value containing one or more media types separated by commas.
+				def << value
 					self.concat(value.scan(SEPARATOR).map(&:strip))
 				end
 				
-				# Serializes the stored values into a comma-separated string.
+				# Converts the parsed header value into a raw header value.
 				#
-				# @returns [String] the serialized representation of the header values.
+				# @returns [String] a raw header value (comma-separated string).
 				def to_s
 					join(",")
 				end

data/lib/protocol/http/header/accept_charset.rb

@@ -4,7 +4,7 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "split"
-require_relative "quoted_string"
+require_relative "../quoted_string"
 require_relative "../error"
 
 module Protocol

data/lib/protocol/http/header/accept_encoding.rb

@@ -4,7 +4,7 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "split"
-require_relative "quoted_string"
+require_relative "../quoted_string"
 require_relative "../error"
 
 module Protocol

data/lib/protocol/http/header/accept_language.rb

@@ -4,7 +4,7 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "split"
-require_relative "quoted_string"
+require_relative "../quoted_string"
 require_relative "../error"
 
 module Protocol

data/lib/protocol/http/header/authorization.rb

@@ -15,6 +15,22 @@ module Protocol
 			#
 			# TODO Support other authorization mechanisms, e.g. bearer token.
 			class Authorization < String
+				# Parses a raw header value.
+				#
+				# @parameter value [String] a raw header value.
+				# @returns [Authorization] a new instance.
+				def self.parse(value)
+					self.new(value)
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String] the value to coerce.
+				# @returns [Authorization] a parsed header object.
+				def self.coerce(value)
+					self.new(value.to_s)
+				end
+				
 				# Splits the header into the credentials.
 				#
 				# @returns [Tuple(String, String)] The username and password.
@@ -31,8 +47,8 @@ module Protocol
 					strict_base64_encoded = ["#{username}:#{password}"].pack("m0")
 					
 					self.new(
-						"Basic #{strict_base64_encoded}"
-					)
+								"Basic #{strict_base64_encoded}"
+							)
 				end
 				
 				# Whether this header is acceptable in HTTP trailers.

data/lib/protocol/http/header/cache_control.rb

@@ -44,16 +44,44 @@ module Protocol
 				# The `proxy-revalidate` directive is similar to `must-revalidate` but applies only to shared caches.
 				PROXY_REVALIDATE = "proxy-revalidate"
 				
-				# Initializes the cache control header with the given value. The value is expected to be a comma-separated string of cache directives.
+				# Parses a raw header value.
 				#
-				# @parameter value [String | Nil] the raw Cache-Control header value.
+				# @parameter value [String] a raw header value containing comma-separated directives.
+				# @returns [CacheControl] a new instance containing the parsed and normalized directives.
+				def self.parse(value)
+					self.new(value.downcase.split(COMMA))
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String | Array] the value to coerce.
+				# @returns [CacheControl] a parsed header object with normalized values.
+				def self.coerce(value)
+					case value
+					when Array
+						self.new(value.map(&:downcase))
+					else
+						self.parse(value.to_s)
+					end
+				end
+				
+				# Initializes the cache control header with the given values.
+				#
+				# @parameter value [Array | String | Nil] an array of directives, a raw header value, or `nil` for an empty header.
 				def initialize(value = nil)
-					super(value&.downcase)
+					if value.is_a?(Array)
+						super(value)
+					elsif value.is_a?(String)
+						super()
+						self << value
+					elsif value
+						raise ArgumentError, "Invalid value: #{value.inspect}"
+					end
 				end
 				
 				# Adds a directive to the Cache-Control header. The value will be normalized to lowercase before being added.
 				#
-				# @parameter value [String] the directive to add.
+				# @parameter value [String] a raw header value containing directives to add.
 				def << value
 					super(value.downcase)
 				end
@@ -132,3 +160,4 @@ module Protocol
 		end
 	end
 end
+

data/lib/protocol/http/header/connection.rb

@@ -22,16 +22,44 @@ module Protocol
 				# The `upgrade` directive indicates that the connection should be upgraded to a different protocol, as specified in the `Upgrade` header.
 				UPGRADE = "upgrade"
 				
-				# Initializes the connection header with the given value. The value is expected to be a comma-separated string of directives.
+				# Parses a raw header value.
 				#
-				# @parameter value [String | Nil] the raw `connection` header value.
+				# @parameter value [String] a raw header value containing comma-separated directives.
+				# @returns [Connection] a new instance with normalized (lowercase) directives.
+				def self.parse(value)
+					self.new(value.downcase.split(COMMA))
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String | Array] the value to coerce.
+				# @returns [Connection] a parsed header object with normalized values.
+				def self.coerce(value)
+					case value
+					when Array
+						self.new(value.map(&:downcase))
+					else
+						self.parse(value.to_s)
+					end
+				end
+				
+				# Initializes the connection header with the given values.
+				#
+				# @parameter value [Array | String | Nil] an array of directives, a raw header value, or `nil` for an empty header.
 				def initialize(value = nil)
-					super(value&.downcase)
+					if value.is_a?(Array)
+						super(value)
+					elsif value.is_a?(String)
+						super()
+						self << value
+					elsif value
+						raise ArgumentError, "Invalid value: #{value.inspect}"
+					end
 				end
 				
 				# Adds a directive to the `connection` header. The value will be normalized to lowercase before being added.
 				#
-				# @parameter value [String] the directive to add.
+				# @parameter value [String] a raw header value containing directives to add.
 				def << value
 					super(value.downcase)
 				end
@@ -61,3 +89,4 @@ module Protocol
 		end
 	end
 end
+

data/lib/protocol/http/header/date.rb

@@ -12,9 +12,25 @@ module Protocol
 			#
 			# This header is typically included in HTTP responses and follows the format defined in RFC 9110.
 			class Date < String
-				# Replaces the current value of the `date` header with the specified value.
+				# Parses a raw header value.
 				#
-				# @parameter value [String] the new value for the `date` header.
+				# @parameter value [String] a raw header value.
+				# @returns [Date] a new instance.
+				def self.parse(value)
+					self.new(value)
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String] the value to coerce.
+				# @returns [Date] a parsed header object.
+				def self.coerce(value)
+					self.new(value.to_s)
+				end
+				
+				# Replaces the current value of the `date` header.
+				#
+				# @parameter value [String] a raw header value for the `date` header.
 				def << value
 					replace(value)
 				end

data/lib/protocol/http/header/digest.rb

@@ -4,7 +4,7 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "split"
-require_relative "quoted_string"
+require_relative "../quoted_string"
 require_relative "../error"
 
 module Protocol

data/lib/protocol/http/header/etag.rb

@@ -10,9 +10,25 @@ module Protocol
 			#
 			# The `etag` header provides a unique identifier for a specific version of a resource, typically used for cache validation or conditional requests. It can be either a strong or weak validator as defined in RFC 9110.
 			class ETag < String
-				# Replaces the current value of the `etag` header with the specified value.
+				# Parses a raw header value.
 				#
-				# @parameter value [String] the new value for the `etag` header.
+				# @parameter value [String] a raw header value.
+				# @returns [ETag] a new instance.
+				def self.parse(value)
+					self.new(value)
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String] the value to coerce.
+				# @returns [ETag] a parsed header object.
+				def self.coerce(value)
+					self.new(value.to_s)
+				end
+				
+				# Replaces the current value of the `etag` header.
+				#
+				# @parameter value [String] a raw header value for the `etag` header.
 				def << value
 					replace(value)
 				end

data/lib/protocol/http/header/etags.rb

@@ -52,7 +52,7 @@ module Protocol
 					wildcard? || self.include?(etag) || self.include?(opposite_tag(etag))
 				end
 				
-				private
+			private
 				
 				# Converts a weak tag to its strong counterpart or vice versa.
 				#

data/lib/protocol/http/header/multiple.rb

@@ -10,18 +10,47 @@ module Protocol
 			#
 			# This isn't a specific header but is used as a base for headers that store multiple values, such as cookies. The values are split and stored as an array internally, and serialized back to a newline-separated string when needed.
 			class Multiple < Array
-				# Initializes the multiple header with the given value. As the header key-value pair can only contain one value, the value given here is added to the internal array, and subsequent values can be added using the `<<` operator.
+				# Parses a raw header value.
 				#
-				# @parameter value [String] the raw header value.
-				def initialize(value)
+				# Multiple headers receive each value as a separate header entry, so this method takes a single string value and creates a new instance containing it.
+				#
+				# @parameter value [String] a single raw header value.
+				# @returns [Multiple] a new instance containing the parsed value.
+				def self.parse(value)
+					self.new([value])
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# This method is used by the Headers class when setting values via `[]=` to convert application values into the appropriate policy type.
+				#
+				# @parameter value [String | Array] the value to coerce.
+				# @returns [Multiple] a parsed header object.
+				def self.coerce(value)
+					case value
+					when Array
+						self.new(value.map(&:to_s))
+					else
+						self.parse(value.to_s)
+					end
+				end
+				
+				# Initializes the multiple header with the given values.
+				#
+				# @parameter value [Array | Nil] an array of header values, or `nil` for an empty header.
+				def initialize(value = nil)
 					super()
 					
-					self << value
+					if value
+						self.concat(value)
+					end
 				end
 				
-				# Serializes the stored values into a newline-separated string.
+				# Converts the parsed header value into a raw header value.
+				#
+				# Multiple headers are transmitted as separate header entries, so this serializes to a newline-separated string for storage.
 				#
-				# @returns [String] the serialized representation of the header values.
+				# @returns [String] a raw header value (newline-separated string).
 				def to_s
 					join("\n")
 				end

data/lib/protocol/http/header/priority.rb

@@ -12,16 +12,44 @@ module Protocol
 			#
 			# The `priority` header allows clients to express their preference for how resources should be prioritized by the server. It supports directives like `u=` to specify the urgency level of a request, and `i` to indicate whether a response can be delivered incrementally. The urgency levels range from 0 (highest priority) to 7 (lowest priority), while the `i` directive is a boolean flag.
 			class Priority < Split
-				# Initialize the priority header with the given value.
+				# Parses a raw header value.
 				#
-				# @parameter value [String | Nil] the value of the priority header, if any. The value should be a comma-separated string of directives.
+				# @parameter value [String] a raw header value containing comma-separated directives.
+				# @returns [Priority] a new instance with normalized (lowercase) directives.
+				def self.parse(value)
+					self.new(value.downcase.split(COMMA))
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# @parameter value [String | Array] the value to coerce.
+				# @returns [Priority] a parsed header object with normalized values.
+				def self.coerce(value)
+					case value
+					when Array
+						self.new(value.map(&:downcase))
+					else
+						self.parse(value.to_s)
+					end
+				end
+				
+				# Initializes the priority header with the given values.
+				#
+				# @parameter value [Array | String | Nil] an array of directives, a raw header value, or `nil` for an empty header.
 				def initialize(value = nil)
-					super(value&.downcase)
+					if value.is_a?(Array)
+						super(value)
+					elsif value.is_a?(String)
+						super()
+						self << value
+					elsif value
+						raise ArgumentError, "Invalid value: #{value.inspect}"
+					end
 				end
 				
 				# Add a value to the priority header.
 				#
-				# @parameter value [String] the directive to add to the header.
+				# @parameter value [String] a raw header value containing directives to add to the header.
 				def << value
 					super(value.downcase)
 				end
@@ -55,3 +83,4 @@ module Protocol
 		end
 	end
 end
+

data/lib/protocol/http/header/server_timing.rb

@@ -4,7 +4,7 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "split"
-require_relative "quoted_string"
+require_relative "../quoted_string"
 require_relative "../error"
 
 module Protocol

data/lib/protocol/http/header/split.rb

@@ -13,14 +13,43 @@ module Protocol
 				# Regular expression used to split values on commas, with optional surrounding whitespace.
 				COMMA = /\s*,\s*/
 				
-				# Initializes a `Split` header with the given value. If the value is provided, it is split into distinct entries and stored as an array.
+				# Parses a raw header value.
 				#
-				# @parameter value [String | Nil] the raw header value containing multiple entries separated by commas, or `nil` for an empty header.
-				def initialize(value = nil)
-					if value
-						super(value.split(COMMA))
+				# Split headers receive comma-separated values in a single header entry. This method splits the raw value into individual entries.
+				#
+				# @parameter value [String] a raw header value containing multiple entries separated by commas.
+				# @returns [Split] a new instance containing the parsed values.
+				def self.parse(value)
+					self.new(value.split(COMMA))
+				end
+				
+				# Coerces a value into a parsed header object.
+				#
+				# This method is used by the Headers class when setting values via `[]=` to convert application values into the appropriate policy type.
+				#
+				# @parameter value [String | Array] the value to coerce.
+				# @returns [Split] a parsed header object.
+				def self.coerce(value)
+					case value
+					when Array
+						self.new(value.map(&:to_s))
 					else
+						self.parse(value.to_s)
+					end
+				end
+				
+				# Initializes a `Split` header with the given values.
+				#
+				# @parameter value [Array | String | Nil] an array of values, a raw header value, or `nil` for an empty header.
+				def initialize(value = nil)
+					if value.is_a?(Array)
+						super(value)
+					elsif value.is_a?(String)
+						# Compatibility with the old constructor, prefer to use `parse` instead:
 						super()
+						self << value
+					elsif value
+						raise ArgumentError, "Invalid value: #{value.inspect}"
 					end
 				end
 				
@@ -28,14 +57,14 @@ module Protocol
 				#
 				# The input string is split into distinct entries and appended to the array.
 				#
-				# @parameter value [String] the value or values to add, separated by commas.
+				# @parameter value [String] a raw header value containing one or more values separated by commas.
 				def << value
 					self.concat(value.split(COMMA))
 				end
 				
-				# Serializes the stored values into a comma-separated string.
+				# Converts the parsed header value into a raw header value.
 				#
-				# @returns [String] the serialized representation of the header values.
+				# @returns [String] a raw header value (comma-separated string).
 				def to_s
 					join(",")
 				end
@@ -47,7 +76,7 @@ module Protocol
 					false
 				end
 				
-				protected
+			protected
 				
 				def reverse_find(&block)
 					reverse_each do |value|