protocol-http 0.53.0 → 0.55.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49ea23b4e99ab120bfd68806628631db474b789d7ca841a28877ba176239816f
-  data.tar.gz: 2dbe6a91006f94a303babb3b156a55eb82ac60025f111d7f003896e744009394
+  metadata.gz: 4c016217fd5d9ddfac87278d8a629d47ec338d02441d0f27ed25102962e927b9
+  data.tar.gz: 51d479e7f25046ca76d08ed60676b7bf4afe5ffa3e234bbb4501478d3fe1db2c
 SHA512:
-  metadata.gz: 0d05dca30d34d5a66483cf09b3b3927af1bd6cf4679cd2421fa0737ab7f6cd56b61fd681d90c7b3252c6bc79d6843b8460c3c74c595b31ff636fb46920088165
-  data.tar.gz: 75cb7b599a2ba9d49f859b16f00f94bc2e59118813779e9a4a7e5804ea94d6cc66cc361fc4ef0d7ce957e26bbf7a6a53e1f7b02ec92e438260bfa5a1a33e1299
+  metadata.gz: a49eb6993da937df85d263f3b505dc700066c796b102c2e4290b9893700fd9f82852bb17f330ef2bf350e11dbf0782e206ae1d29cc4be3fb422d8f6642f1720b
+  data.tar.gz: 2680c120c9d72c6ee7c35929984b67e248d26496145dc08700e4a8a5f60568e6dfe2600b5179042d92793d5784ee46e270a59e76f6d272c094c47ccf1c97c0b3

data/context/headers.md

@@ -0,0 +1,94 @@
+# Headers
+
+This guide explains how to work with HTTP headers using `protocol-http`.
+
+## Core Concepts
+
+`protocol-http` provides several core concepts for working with HTTP headers:
+
+- A {ruby Protocol::HTTP::Headers} class which represents a collection of HTTP headers with built-in security and policy features.
+- Header-specific classes like {ruby Protocol::HTTP::Header::Accept} and {ruby Protocol::HTTP::Header::Authorization} which provide specialized parsing and formatting.
+- Trailer security validation to prevent HTTP request smuggling attacks.
+
+## Usage
+
+The {Protocol::HTTP::Headers} class provides a comprehensive interface for creating and manipulating HTTP headers:
+
+```ruby
+require 'protocol/http'
+
+headers = Protocol::HTTP::Headers.new
+headers.add('content-type', 'text/html')
+headers.add('set-cookie', 'session=abc123')
+
+# Access headers
+content_type = headers['content-type'] # => "text/html"
+
+# Check if header exists
+headers.include?('content-type') # => true
+```
+
+### Header Policies
+
+Different header types have different behaviors for merging, validation, and trailer handling:
+
+```ruby
+# Some headers can be specified multiple times
+headers.add('set-cookie', 'first=value1')
+headers.add('set-cookie', 'second=value2')
+
+# Others are singletons and will raise errors if duplicated
+headers.add('content-length', '100')
+# headers.add('content-length', '200') # Would raise DuplicateHeaderError
+```
+
+### Structured Headers
+
+Some headers have specialized classes for parsing and formatting:
+
+```ruby
+# Accept header with media ranges
+accept = Protocol::HTTP::Header::Accept.new('text/html,application/json;q=0.9')
+media_ranges = accept.media_ranges
+
+# Authorization header
+auth = Protocol::HTTP::Header::Authorization.basic('username', 'password')
+# => "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
+```
+
+### Trailer Security
+
+HTTP trailers are headers that appear after the message body. For security reasons, only certain headers are allowed in trailers:
+
+```ruby
+# Working with trailers
+headers = Protocol::HTTP::Headers.new([
+  ['content-type', 'text/html'],
+  ['content-length', '1000']
+])
+
+# Start trailer section
+headers.trailer!
+
+# These will be allowed (safe metadata)
+headers.add('etag', '"12345"')
+headers.add('date', Time.now.httpdate)
+
+# These will be silently ignored for security
+headers.add('authorization', 'Bearer token') # Ignored - credential leakage risk
+headers.add('connection', 'close') # Ignored - hop-by-hop header
+```
+
+The trailer security system prevents HTTP request smuggling by restricting which headers can appear in trailers:
+
+**Allowed headers** (return `true` for `trailer?`):
+- `date` - Response generation timestamps.
+- `digest` - Content integrity verification.
+- `etag` - Cache validation tags.
+- `server-timing` - Performance metrics.
+
+**Forbidden headers** (return `false` for `trailer?`):
+- `authorization` - Prevents credential leakage.
+- `connection`, `te`, `transfer-encoding` - Hop-by-hop headers that control connection behavior.
+- `cookie`, `set-cookie` - State information needed during initial processing.
+- `accept` - Content negotiation must occur before response generation.

data/context/index.yaml

@@ -14,17 +14,12 @@ files:
   title: Message Body
   description: This guide explains how to work with HTTP request and response message
     bodies using `Protocol::HTTP::Body` classes.
+- path: headers.md
+  title: Headers
+  description: This guide explains how to work with HTTP headers using `protocol-http`.
 - 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,6 +3,7 @@
 # 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"
 
@@ -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,9 +2,10 @@
 
 # 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
@@ -81,7 +82,7 @@ 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.
-				def << (value)
+				def << value
 					self.concat(value.scan(SEPARATOR).map(&:strip))
 				end
 				
@@ -92,6 +93,12 @@ module Protocol
 					join(",")
 				end
 				
+				# Whether this header is acceptable in HTTP trailers.
+				# @returns [Boolean] `false`, as Accept headers are used for response content negotiation.
+				def self.trailer?
+					false
+				end
+				
 				# Parse the `accept` header.
 				#
 				# @returns [Array(Charset)] the list of content types and their associated parameters.

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2025, by Samuel Williams.
 # Copyright, 2024, by Earlopain.
 
 module Protocol
@@ -34,6 +34,12 @@ module Protocol
 						"Basic #{strict_base64_encoded}"
 					)
 				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# @returns [Boolean] `false`, as authorization headers are used for request authentication.
+				def self.trailer?
+					false
+				end
 			end
 		end
 	end

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

@@ -50,6 +50,13 @@ module Protocol
 				def upgrade?
 					self.include?(UPGRADE)
 				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# Connection headers control the current connection and must not appear in trailers.
+				# @returns [Boolean] `false`, as connection headers are hop-by-hop and forbidden in trailers.
+				def self.trailer?
+					false
+				end
 			end
 		end
 	end

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

@@ -23,6 +23,13 @@ module Protocol
 					
 					cookies.map{|cookie| [cookie.name, cookie]}.to_h
 				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# Cookie headers should not appear in trailers as they contain state information needed early in processing.
+				# @returns [Boolean] `false`, as cookie headers are needed during initial request processing.
+				def self.trailer?
+					false
+				end
 			end
 			
 			# The `set-cookie` header sends cookies from the server to the user agent.

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2024, by Samuel Williams.
+# Copyright, 2023-2025, by Samuel Williams.
 
 require "time"
 
@@ -25,6 +25,13 @@ module Protocol
 				def to_time
 					::Time.parse(self)
 				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# Date headers can safely appear in trailers as they provide metadata about response generation.
+				# @returns [Boolean] `true`, as date headers are metadata that can be computed after response generation.
+				def self.trailer?
+					true
+				end
 			end
 		end
 	end

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "split"
+require_relative "../quoted_string"
+require_relative "../error"
+
+module Protocol
+	module HTTP
+		module Header
+			# The `digest` header provides a digest of the message body for integrity verification.
+			#
+			# This header allows servers to send cryptographic hashes of the response body, enabling clients to verify data integrity. Multiple digest algorithms can be specified, and the header is particularly useful as a trailer since the digest can only be computed after the entire message body is available.
+			#
+			# ## Examples
+			#
+			# ```ruby
+			# digest = Digest.new("sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=")
+			# digest << "md5=9bb58f26192e4ba00f01e2e7b136bbd8"
+			# puts digest.to_s
+			# # => "sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=, md5=9bb58f26192e4ba00f01e2e7b136bbd8"
+			# ```
+			class Digest < Split
+				ParseError = Class.new(Error)
+				
+				# https://tools.ietf.org/html/rfc3230#section-4.3.2
+				ENTRY = /\A(?<algorithm>[a-zA-Z0-9][a-zA-Z0-9\-]*)\s*=\s*(?<value>.*)\z/
+				
+				# A single digest entry in the Digest header.
+				Entry = Struct.new(:algorithm, :value) do
+					# Create a new digest entry.
+					#
+					# @parameter algorithm [String] the digest algorithm (e.g., "sha-256", "md5").
+					# @parameter value [String] the base64-encoded or hex-encoded digest value.
+					def initialize(algorithm, value)
+						super(algorithm.downcase, value)
+					end
+					
+					# Convert the entry to its string representation.
+					#
+					# @returns [String] the formatted digest string.
+					def to_s
+						"#{algorithm}=#{value}"
+					end
+				end
+				
+				# Parse the `digest` header value into a list of digest entries.
+				#
+				# @returns [Array(Entry)] the list of digest entries with their algorithms and values.
+				def entries
+					self.map do |value|
+						if match = value.match(ENTRY)
+							Entry.new(match[:algorithm], match[:value])
+						else
+							raise ParseError.new("Could not parse digest value: #{value.inspect}")
+						end
+					end
+				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# @returns [Boolean] `true`, as digest headers contain integrity hashes that can only be calculated after the entire message body is available.
+				def self.trailer?
+					true
+				end
+			end
+		end
+	end
+end

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

@@ -25,6 +25,13 @@ module Protocol
 				def weak?
 					self.start_with?("W/")
 				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# ETag headers can safely appear in trailers as they provide cache validation metadata.
+				# @returns [Boolean] `true`, as ETag headers are metadata that can be computed after response generation.
+				def self.trailer?
+					true
+				end
 			end
 		end
 	end

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

@@ -25,6 +25,13 @@ module Protocol
 				def to_s
 					join("\n")
 				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# This is a base class for headers with multiple values, default is to disallow in trailers.
+				# @returns [Boolean] `false`, as most multiple-value headers should not appear in trailers by default.
+				def self.trailer?
+					false
+				end
 			end
 		end
 	end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "split"
+require_relative "../quoted_string"
+require_relative "../error"
+
+module Protocol
+	module HTTP
+		module Header
+			# The `server-timing` header communicates performance metrics about the request-response cycle to the client.
+			#
+			# This header allows servers to send timing information about various server-side operations, which can be useful for performance monitoring and debugging. Each metric can include a name, optional duration, and optional description.
+			#
+			# ## Examples
+			#
+			# ```ruby
+			# server_timing = ServerTiming.new("db;dur=53.2")
+			# server_timing << "cache;dur=12.1;desc=\"Redis lookup\""
+			# puts server_timing.to_s
+			# # => "db;dur=53.2, cache;dur=12.1;desc=\"Redis lookup\""
+			# ```
+			class ServerTiming < Split
+				ParseError = Class.new(Error)
+				
+				# https://www.w3.org/TR/server-timing/
+				METRIC = /\A(?<name>[a-zA-Z0-9][a-zA-Z0-9_\-]*)(;(?<parameters>.*))?\z/
+				PARAMETER = /(?<key>dur|desc)=((?<value>#{TOKEN})|(?<quoted_value>#{QUOTED_STRING}))/
+				
+				# A single metric in the Server-Timing header.
+				Metric = Struct.new(:name, :duration, :description) do
+					# Create a new server timing metric.
+					#
+					# @parameter name [String] the name of the metric.
+					# @parameter duration [Float | Nil] the duration in milliseconds.
+					# @parameter description [String | Nil] the description of the metric.
+					def initialize(name, duration = nil, description = nil)
+						super(name, duration, description)
+					end
+					
+					# Convert the metric to its string representation.
+					#
+					# @returns [String] the formatted metric string.
+					def to_s
+						result = name.dup
+						result << ";dur=#{duration}" if duration
+						result << ";desc=\"#{description}\"" if description
+						result
+					end
+				end
+				
+				# Parse the `server-timing` header value into a list of metrics.
+				#
+				# @returns [Array(Metric)] the list of metrics with their names, durations, and descriptions.
+				def metrics
+					self.map do |value|
+						if match = value.match(METRIC)
+							name = match[:name]
+							parameters = match[:parameters] || ""
+							
+							duration = nil
+							description = nil
+							
+							parameters.scan(PARAMETER) do |key, value, quoted_value|
+								value = QuotedString.unquote(quoted_value) if quoted_value
+								
+								case key
+								when "dur"
+									duration = value.to_f
+								when "desc"
+									description = value
+								end
+							end
+							
+							Metric.new(name, duration, description)
+						else
+							raise ParseError.new("Could not parse server timing metric: #{value.inspect}")
+						end
+					end
+				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# @returns [Boolean] `true`, as server-timing headers contain performance metrics that are typically calculated during response generation.
+				def self.trailer?
+					true
+				end
+			end
+		end
+	end
+end

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

@@ -40,6 +40,13 @@ module Protocol
 					join(",")
 				end
 				
+				# Whether this header is acceptable in HTTP trailers.
+				# This is a base class for comma-separated headers, default is to disallow in trailers.
+				# @returns [Boolean] `false`, as most comma-separated headers should not appear in trailers by default.
+				def self.trailer?
+					false
+				end
+				
 				protected
 				
 				def reverse_find(&block)