protocol-http 0.56.1 → 0.58.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9874b094d1320bc400ff81a991311fa74a9b95d0a89adc9c4a4c41b89380bb2a
-  data.tar.gz: d2f9206d98a99557152c4758f266ef70d516072e2cfb9e0b6099dc4901bbbe95
+  metadata.gz: 971bece5e113d3f945faf8b8ce44858e97f0e6282e3a264b6e6fca1e57c8e71c
+  data.tar.gz: 8d1139a2022dbe96710d7e0286a5c30c2384e14fcba3e0907428361b25c3a703
 SHA512:
-  metadata.gz: ec515579222f78ee8ee4353c346cf8d361bb244deefc4bf0deb5899fe28399c96e273fe8c1fca10e328b9e5872e5e2b40ea09fcf6c4463da704e097a58e795bb
-  data.tar.gz: d2b739b64da0af2db050ddccfe292e464ed1defc7310e0152ddeeff58b4455b725483dd76aa237f21ff44d0ae3b1ff798269f81ed2c69a7ba6a1f865c1bc3820
+  metadata.gz: 69d17f997389daf2332cacc0d5ac407897e2dc2a45c3e329f23dfc9b18f7075b425e10c43fff27ff1728f64e92a6843e3291be5103e9ee8c72d1f810c2603c01
+  data.tar.gz: '09676f19f6b3bd4d6290b5dccd8f93d2c6409e82926fa74a9b21f39f4fa92df0d289ef8fac6b0460a9de2784d78d7114d262f9a5088f66518ef60b9d60a877f4'

data/context/design-overview.md

@@ -205,5 +205,5 @@ interim_response_callback = proc do |status, headers|
 	end
 end
 
-response = client.post("/upload", {'expect' => '100-continue'}, body, interim_response: interim_response_callback)
+response = client.post("/upload", {"expect" => "100-continue"}, body, interim_response: interim_response_callback)
 ```

data/context/getting-started.md

@@ -34,7 +34,7 @@ This gem does not provide any specific client or server implementation, rather i
 {ruby Protocol::HTTP::Request} represents an HTTP request which can be used both server and client-side.
 
 ``` ruby
-require 'protocol/http/request'
+require "protocol/http/request"
 
 # Short form (recommended):
 request = Protocol::HTTP::Request["GET", "/index.html", {"accept" => "text/html"}]
@@ -54,7 +54,7 @@ request.headers          # => Protocol::HTTP::Headers instance
 {ruby Protocol::HTTP::Response} represents an HTTP response which can be used both server and client-side.
 
 ``` ruby
-require 'protocol/http/response'
+require "protocol/http/response"
 
 # Short form (recommended):
 response = Protocol::HTTP::Response[200, {"content-type" => "text/html"}, "Hello, World!"]
@@ -83,15 +83,15 @@ response.failure?        # => false (400-599)
 #### Basic Usage
 
 ``` ruby
-require 'protocol/http/headers'
+require "protocol/http/headers"
 
 headers = Protocol::HTTP::Headers.new
 
 # Assignment by title-case key:
-headers['Content-Type'] = "image/jpeg"
+headers["Content-Type"] = "image/jpeg"
 
 # Lookup by lower-case (normalized) key:
-headers['content-type']
+headers["content-type"]
 # => "image/jpeg"
 ```
 
@@ -101,8 +101,8 @@ Many headers receive special semantic processing, automatically splitting comma-
 
 ``` ruby
 # Accept header with quality values:
-headers['Accept'] = 'text/html, application/json;q=0.8, */*;q=0.1'
-accept = headers['accept']
+headers["Accept"] = "text/html, application/json;q=0.8, */*;q=0.1"
+accept = headers["accept"]
 # => ["text/html", "application/json;q=0.8", "*/*;q=0.1"]
 
 # Access parsed media ranges with quality factors:
@@ -114,17 +114,17 @@ end
 # */* (q=0.1)
 
 # Accept-Encoding automatically splits values:
-headers['Accept-Encoding'] = 'gzip, deflate, br;q=0.9'
-headers['accept-encoding']
+headers["Accept-Encoding"] = "gzip, deflate, br;q=0.9"
+headers["accept-encoding"]
 # => ["gzip", "deflate", "br;q=0.9"]
 
 # Cache-Control splits directives:
-headers['Cache-Control'] = 'max-age=3600, no-cache, must-revalidate'
-headers['cache-control']
+headers["Cache-Control"] = "max-age=3600, no-cache, must-revalidate"
+headers["cache-control"]
 # => ["max-age=3600", "no-cache", "must-revalidate"]
 
 # Vary header normalizes field names to lowercase:
-headers['Vary'] = 'Accept-Encoding, User-Agent'
-headers['vary']
+headers["Vary"] = "Accept-Encoding, User-Agent"
+headers["vary"]
 # => ["accept-encoding", "user-agent"]
 ```

data/context/headers.md

@@ -15,17 +15,17 @@ This guide explains how to work with HTTP headers using `protocol-http`.
 The {Protocol::HTTP::Headers} class provides a comprehensive interface for creating and manipulating HTTP headers:
 
 ```ruby
-require 'protocol/http'
+require "protocol/http"
 
 headers = Protocol::HTTP::Headers.new
-headers.add('content-type', 'text/html')
-headers.add('set-cookie', 'session=abc123')
+headers.add("content-type", "text/html")
+headers.add("set-cookie", "session=abc123")
 
 # Access headers
-content_type = headers['content-type'] # => "text/html"
+content_type = headers["content-type"] # => "text/html"
 
 # Check if header exists
-headers.include?('content-type') # => true
+headers.include?("content-type") # => true
 ```
 
 ### Header Policies
@@ -34,11 +34,11 @@ Different header types have different behaviors for merging, validation, and tra
 
 ```ruby
 # Some headers can be specified multiple times
-headers.add('set-cookie', 'first=value1')
-headers.add('set-cookie', 'second=value2')
+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", "100")
 # headers.add('content-length', '200') # Would raise DuplicateHeaderError
 ```
 
@@ -48,11 +48,11 @@ 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')
+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')
+auth = Protocol::HTTP::Header::Authorization.basic("username", "password")
 # => "Basic dXNlcm5hbWU6cGFzc3dvcmQ="
 ```
 
@@ -63,20 +63,20 @@ HTTP trailers are headers that appear after the message body. For security reaso
 ```ruby
 # Working with trailers
 headers = Protocol::HTTP::Headers.new([
-  ['content-type', 'text/html'],
-  ['content-length', '1000']
+		["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)
+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
+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:

data/context/hypertext-references.md

@@ -9,10 +9,10 @@ This guide explains how to use `Protocol::HTTP::Reference` for constructing and
 ## Basic Construction
 
 ``` ruby
-require 'protocol/http/reference'
+require "protocol/http/reference"
 
 # Simple reference with parameters:
-reference = Protocol::HTTP::Reference.new("/search", nil, nil, {q: 'kittens', limit: 10})
+reference = Protocol::HTTP::Reference.new("/search", nil, nil, {q: "kittens", limit: 10})
 reference.to_s
 # => "/search?q=kittens&limit=10"
 

data/context/message-body.md

@@ -97,7 +97,7 @@ body.empty?  # => true
 Use {ruby Protocol::HTTP::Body::File} for serving files efficiently:
 
 ``` ruby
-require 'protocol/http/body/file'
+require "protocol/http/body/file"
 
 # Open a file:
 body = Protocol::HTTP::Body::File.open("/path/to/file.txt")
@@ -140,7 +140,7 @@ body = Protocol::HTTP::Body::File.new(file, block_size: 8192)  # 8KB chunks
 Use {ruby Protocol::HTTP::Body::Writable} for dynamic content generation:
 
 ``` ruby
-require 'protocol/http/body/writable'
+require "protocol/http/body/writable"
 
 # Create a writable body:
 body = Protocol::HTTP::Body::Writable.new
@@ -181,7 +181,7 @@ body.write("chunk 1")
 Use {ruby Protocol::HTTP::Body::Streamable} for computed content:
 
 ``` ruby
-require 'protocol/http/body/streamable'
+require "protocol/http/body/streamable"
 
 # Generate content dynamically:
 body = Protocol::HTTP::Body::Streamable.new do |output|
@@ -202,7 +202,7 @@ end
 Use {ruby Protocol::HTTP::Body::Stream} to wrap IO-like objects:
 
 ``` ruby
-require 'protocol/http/body/stream'
+require "protocol/http/body/stream"
 
 # Wrap an IO object:
 io = StringIO.new("Hello\nWorld\nFrom\nStream")
@@ -224,8 +224,8 @@ rest = body.read     # => "Stream"
 ### Compression Bodies
 
 ``` ruby
-require 'protocol/http/body/deflate'
-require 'protocol/http/body/inflate'
+require "protocol/http/body/deflate"
+require "protocol/http/body/inflate"
 
 # Compress a body:
 original = Protocol::HTTP::Body::Buffered.new(["Hello World"])
@@ -241,7 +241,7 @@ content = decompressed.join  # => "Hello World"
 Create custom body transformations:
 
 ``` ruby
-require 'protocol/http/body/wrapper'
+require "protocol/http/body/wrapper"
 
 class UppercaseBody < Protocol::HTTP::Body::Wrapper
 	def read
@@ -299,7 +299,7 @@ end
 Make any body rewindable by buffering:
 
 ``` ruby
-require 'protocol/http/body/rewindable'
+require "protocol/http/body/rewindable"
 
 # Wrap a non-rewindable body:
 file_body = Protocol::HTTP::Body::File.open("data.txt")
@@ -318,7 +318,7 @@ same_chunk = rewindable.read  # Same as first_chunk
 For HEAD requests that need content-length but no body:
 
 ``` ruby
-require 'protocol/http/body/head'
+require "protocol/http/body/head"
 
 # Create head body from another body:
 original = Protocol::HTTP::Body::File.open("large_file.zip")

data/context/middleware.md

@@ -38,7 +38,7 @@ end
 The `Protocol::HTTP::Middleware` class provides a convenient base for building middleware:
 
 ``` ruby
-require 'protocol/http/middleware'
+require "protocol/http/middleware"
 
 class LoggingMiddleware < Protocol::HTTP::Middleware
 	def call(request)
@@ -60,7 +60,7 @@ app = LoggingMiddleware.new(Protocol::HTTP::Middleware::HelloWorld)
 Use `Protocol::HTTP::Middleware.build` to construct middleware stacks:
 
 ``` ruby
-require 'protocol/http/middleware'
+require "protocol/http/middleware"
 
 app = Protocol::HTTP::Middleware.build do
 	use LoggingMiddleware
@@ -84,7 +84,7 @@ Convert a block into middleware using `Middleware.for`:
 
 ``` ruby
 middleware = Protocol::HTTP::Middleware.for do |request|
-	if request.path == '/health'
+	if request.path == "/health"
 		Protocol::HTTP::Response[200, {}, ["OK"]]
 	else
 		# This would normally delegate, but this example doesn't have a delegate
@@ -141,7 +141,7 @@ class AuthenticationMiddleware < Protocol::HTTP::Middleware
 	end
 	
 	def call(request)
-		auth_header = request.headers['authorization']
+		auth_header = request.headers["authorization"]
 		
 		unless auth_header == "Bearer #{@api_key}"
 			return Protocol::HTTP::Response[401, {}, ["Unauthorized"]]
@@ -166,8 +166,8 @@ class ContentTypeMiddleware < Protocol::HTTP::Middleware
 		response = super
 		
 		# Add content-type header if not present
-		unless response.headers.include?('content-type')
-			response.headers['content-type'] = 'text/plain'
+		unless response.headers.include?("content-type")
+			response.headers["content-type"] = "text/plain"
 		end
 		
 		response
@@ -189,7 +189,7 @@ describe MyMiddleware do
 	end
 	
 	it "closes properly" do
-		expect { app.close }.not.to raise_exception
+		expect{app.close}.not.to raise_exception
 	end
 end
 ```

data/context/streaming.md

@@ -9,15 +9,15 @@ The request and response body work independently of each other can stream data i
 ```ruby
 #!/usr/bin/env ruby
 
-require 'async'
-require 'async/http/client'
-require 'async/http/server'
-require 'async/http/endpoint'
+require "async"
+require "async/http/client"
+require "async/http/server"
+require "async/http/endpoint"
 
-require 'protocol/http/body/stream'
-require 'protocol/http/body/writable'
+require "protocol/http/body/stream"
+require "protocol/http/body/writable"
 
-endpoint = Async::HTTP::Endpoint.parse('http://localhost:3000')
+endpoint = Async::HTTP::Endpoint.parse("http://localhost:3000")
 
 Async do
 	server = Async::HTTP::Server.for(endpoint) do |request|
@@ -74,15 +74,15 @@ While WebSockets can work on the above streaming interface, it's a bit more conv
 ```ruby
 #!/usr/bin/env ruby
 
-require 'async'
-require 'async/http/client'
-require 'async/http/server'
-require 'async/http/endpoint'
+require "async"
+require "async/http/client"
+require "async/http/server"
+require "async/http/endpoint"
 
-require 'protocol/http/body/stream'
-require 'protocol/http/body/writable'
+require "protocol/http/body/stream"
+require "protocol/http/body/writable"
 
-endpoint = Async::HTTP::Endpoint.parse('http://localhost:3000')
+endpoint = Async::HTTP::Endpoint.parse("http://localhost:3000")
 
 Async do
 	server = Async::HTTP::Server.for(endpoint) do |request|

data/context/url-parsing.md

@@ -11,7 +11,7 @@ While basic query parameter encoding follows the `application/x-www-form-urlenco
 ## Basic Query Parameter Parsing
 
 ``` ruby
-require 'protocol/http/url'
+require "protocol/http/url"
 
 # Parse query parameters from a URL:
 reference = Protocol::HTTP::Reference.parse("/search?q=ruby&category=programming&page=2")

data/lib/protocol/http/accept_encoding.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require_relative "middleware"
 
@@ -21,7 +21,7 @@ module Protocol
 			# The default wrappers to use for decoding content.
 			DEFAULT_WRAPPERS = {
 				"gzip" => Body::Inflate.method(:for),
-				"identity" => ->(body) {body}, # Identity means no encoding
+				"identity" => ->(body){body}, # Identity means no encoding
 				
 				# There is no point including this:
 				# 'identity' => ->(body){body},

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 # Copyright, 2020, by Bryan Powell.
 # Copyright, 2025, by William T. Nelson.
 
@@ -90,7 +90,7 @@ module Protocol
 				
 				# The length of the body. Will compute and cache the length of the body, if it was not provided.
 				def length
-					@length ||= @chunks.inject(0) {|sum, chunk| sum + chunk.bytesize}
+					@length ||= @chunks.inject(0){|sum, chunk| sum + chunk.bytesize}
 				end
 				
 				# @returns [Boolean] if the body is empty.

data/lib/protocol/http/error.rb

@@ -26,5 +26,18 @@ module Protocol
 			# @attribute [String] key The header key that was duplicated.
 			attr :key
 		end
+		
+		# Raised when an invalid trailer header is encountered in headers.
+		class InvalidTrailerError < Error
+			include BadRequest
+			
+			# @parameter key [String] The trailer key that is invalid.
+			def initialize(key)
+				super("Invalid trailer key: #{key.inspect}")
+			end
+			
+			# @attribute [String] key The trailer key that is invalid.
+			attr :key
+		end
 	end
 end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require_relative "multiple"
 require_relative "../cookie"
@@ -24,6 +24,11 @@ module Protocol
 					cookies.map{|cookie| [cookie.name, cookie]}.to_h
 				end
 				
+				# Serializes the `cookie` header by joining individual cookie strings with semicolons.
+				def to_s
+					join(";")
+				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.

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "split"
+
+module Protocol
+	module HTTP
+		module Header
+			# Represents generic or custom headers that can be used in trailers.
+			#
+			# This class is used as the default policy for headers not explicitly defined in the POLICY hash.
+			#
+			# It allows generic headers to be used in HTTP trailers, which is important for:
+			# - Custom application headers.
+			# - gRPC status headers (grpc-status, grpc-message).
+			# - Headers used by proxies and middleware.
+			# - Future HTTP extensions.
+			class Generic < Split
+				# Whether this header is acceptable in HTTP trailers.
+				# Generic headers are allowed in trailers by default to support extensibility.
+				# @returns [Boolean] `true`, generic headers are allowed in trailers.
+				def self.trailer?
+					true
+				end
+			end
+		end
+	end
+end

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "split"
 

data/lib/protocol/http/header/te.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 "split"
 require_relative "../quoted_string"
@@ -105,32 +105,32 @@ module Protocol
 				
 				# @returns [Boolean] whether the `chunked` encoding is accepted.
 				def chunked?
-					self.any? {|value| value.start_with?(CHUNKED)}
+					self.any?{|value| value.start_with?(CHUNKED)}
 				end
 				
 				# @returns [Boolean] whether the `gzip` encoding is accepted.
 				def gzip?
-					self.any? {|value| value.start_with?(GZIP)}
+					self.any?{|value| value.start_with?(GZIP)}
 				end
 				
 				# @returns [Boolean] whether the `deflate` encoding is accepted.
 				def deflate?
-					self.any? {|value| value.start_with?(DEFLATE)}
+					self.any?{|value| value.start_with?(DEFLATE)}
 				end
 				
 				# @returns [Boolean] whether the `compress` encoding is accepted.
 				def compress?
-					self.any? {|value| value.start_with?(COMPRESS)}
+					self.any?{|value| value.start_with?(COMPRESS)}
 				end
 				
 				# @returns [Boolean] whether the `identity` encoding is accepted.
 				def identity?
-					self.any? {|value| value.start_with?(IDENTITY)}
+					self.any?{|value| value.start_with?(IDENTITY)}
 				end
 				
 				# @returns [Boolean] whether trailers are accepted.
 				def trailers?
-					self.any? {|value| value.start_with?(TRAILERS)}
+					self.any?{|value| value.start_with?(TRAILERS)}
 				end
 				
 				# Whether this header is acceptable in HTTP trailers.

data/lib/protocol/http/headers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2025, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
 require_relative "error"
 
@@ -20,6 +20,7 @@ require_relative "header/priority"
 require_relative "header/trailer"
 require_relative "header/server_timing"
 require_relative "header/digest"
+require_relative "header/generic"
 
 require_relative "header/accept"
 require_relative "header/accept_charset"
@@ -158,7 +159,26 @@ module Protocol
 				return trailer(&block)
 			end
 			
+			# Enumerate all the headers in the header, if there are any.
+			# 
+			# @yields {|key, value| ...} The header key and value.
+			# 	@parameter key [String] The header key.
+			# 	@parameter value [String] The raw header value.
+			def header(&block)
+				return to_enum(:header) unless block_given?
+				
+				if @tail and @tail < @fields.size
+					@fields.first(@tail).each(&block)
+				else
+					@fields.each(&block)
+				end
+			end
+			
 			# Enumerate all headers in the trailer, if there are any.
+			# 
+			# @yields {|key, value| ...} The header key and value.
+			# 	@parameter key [String] The header key.
+			# 	@parameter value [String] The raw header value.
 			def trailer(&block)
 				return to_enum(:trailer) unless block_given?
 				
@@ -227,9 +247,18 @@ module Protocol
 			#
 			# @parameter key [String] the header key.
 			# @parameter value [String] the header value to assign.
-			def add(key, value)
+			# @parameter trailer [Boolean] whether this header is being added as a trailer.
+			def add(key, value, trailer: self.trailer?)
 				value = value.to_s
 				
+				if trailer
+					policy = @policy[key.downcase]
+					
+					if !policy or !policy.trailer?
+						raise InvalidTrailerError, key
+					end
+				end
+				
 				if @indexed
 					merge_into(@indexed, key.downcase, value)
 				end
@@ -279,7 +308,7 @@ module Protocol
 			# @parameter key [String] The header key.
 			# @returns [String | Array | Object] The header value.
 			def [] key
-				to_h[key]
+				self.to_h[key]
 			end
 			
 			# Merge the headers into this instance.
@@ -297,6 +326,10 @@ module Protocol
 			end
 			
 			# The policy for various headers, including how they are merged and normalized.
+			#
+			# A policy may be `false` to indicate that the header may only be specified once and is a simple string.
+			#
+			# Otherwise, the policy is a class which implements the header normalization logic, including `parse` and `coerce` class methods.
 			POLICY = {
 				# Headers which may only be specified once:
 				"content-disposition" => false,
@@ -315,8 +348,11 @@ module Protocol
 				"user-agent" => false,
 				"trailer" => Header::Trailer,
 				
-				# Custom headers:
+				# Connection handling:
 				"connection" => Header::Connection,
+				"upgrade" => Header::Split,
+				
+				# Cache handling:
 				"cache-control" => Header::CacheControl,
 				"te" => Header::TE,
 				"vary" => Header::Vary,
@@ -354,16 +390,21 @@ module Protocol
 				
 				# Accept headers:
 				"accept" => Header::Accept,
+				"accept-ranges" => Header::Split,
 				"accept-charset" => Header::AcceptCharset,
 				"accept-encoding" => Header::AcceptEncoding,
 				"accept-language" => Header::AcceptLanguage,
 				
+				# Content negotiation headers:
+				"content-encoding" => Header::Split,
+				"content-range" => false,
+				
 				# Performance headers:
 				"server-timing" => Header::ServerTiming,
 				
 				# Content integrity headers:
 				"digest" => Header::Digest,
-			}.tap{|hash| hash.default = Split}
+			}.tap{|hash| hash.default = Header::Generic}
 			
 			# Delete all header values for the given key, and return the merged value.
 			#
@@ -403,28 +444,14 @@ module Protocol
 			# @parameter hash [Hash] The hash to merge into.
 			# @parameter key [String] The header key.
 			# @parameter value [String] The raw header value.
-			protected def merge_into(hash, key, value, trailer = @tail)
+			protected def merge_into(hash, key, value)
 				if policy = @policy[key]
-					# Check if we're adding to trailers and this header is allowed:
-					if trailer && !policy.trailer?
-						return false
-					end
-					
 					if current_value = hash[key]
 						current_value << value
 					else
-						if policy.respond_to?(:parse)
-							hash[key] = policy.parse(value)
-						else
-							hash[key] = policy.new(value)
-						end
+						hash[key] = policy.parse(value)
 					end
 				else
-					# By default, headers are not allowed in trailers:
-					if trailer
-						return false
-					end
-					
 					if hash.key?(key)
 						raise DuplicateHeaderError, key
 					end
@@ -435,16 +462,19 @@ module Protocol
 			
 			# Compute a hash table of headers, where the keys are normalized to lower case and the values are normalized according to the policy for that header.
 			#
+			# This will enforce policy rules, such as merging multiple headers into arrays, or raising errors for duplicate headers.
+			# 
 			# @returns [Hash] A hash table of `{key, value}` pairs.
 			def to_h
 				unless @indexed
-					@indexed = {}
+					indexed = {}
 					
-					@fields.each_with_index do |(key, value), index|
-						trailer = (@tail && index >= @tail)
-						
-						merge_into(@indexed, key.downcase, value, trailer)
+					@fields.each do |key, value|
+						merge_into(indexed, key.downcase, value)
 					end
+					
+					# Deferred assignment so that exceptions in `merge_into` don't leave us in an inconsistent state:
+					@indexed = indexed
 				end
 				
 				return @indexed
@@ -465,7 +495,7 @@ module Protocol
 			def == other
 				case other
 				when Hash
-					to_h == other
+					self.to_h == other
 				when Headers
 					@fields == other.fields
 				else

data/lib/protocol/http/middleware/builder.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require_relative "../middleware"
 
@@ -25,7 +25,7 @@ module Protocol
 				# @parameter options [Hash] The options to pass to the middleware constructor.
 				# @parameter block [Proc] The block to pass to the middleware constructor.
 				def use(middleware, *arguments, **options, &block)
-					@use << proc {|app| middleware.new(app, *arguments, **options, &block)}
+					@use << proc{|app| middleware.new(app, *arguments, **options, &block)}
 				end
 				
 				# Specify the (default) middleware application to use.
@@ -39,7 +39,7 @@ module Protocol
 				#
 				# @returns [Middleware] The application.
 				def to_app
-					@use.reverse.inject(@app) {|app, use| use.call(app)}
+					@use.reverse.inject(@app){|app, use| use.call(app)}
 				end
 			end
 			

data/lib/protocol/http/quoted_string.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 HTTP
@@ -44,4 +44,4 @@ module Protocol
 			end
 		end
 	end
-end
+end

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.56.1"
+		VERSION = "0.58.0"
 	end
 end

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2018-2025, by Samuel Williams.  
+Copyright, 2018-2026, by Samuel Williams.  
 Copyright, 2019, by Yuta Iwama.  
 Copyright, 2020, by Olle Jonsson.  
 Copyright, 2020, by Bryan Powell.  

data/readme.md

@@ -30,6 +30,18 @@ Please see the [project documentation](https://socketry.github.io/protocol-http/
 
 Please see the [project releases](https://socketry.github.io/protocol-http/releases/index) for all releases.
 
+### v0.58.0
+
+  - Move trailer validation to `Headers#add` method to ensure all additions are checked at the time of addition as this is a hard requirement.
+  - Introduce `Headers#header` method to enumerate only the main headers, excluding trailers. This can be used after invoking `Headers#trailer!` to avoid race conditions.
+  - Fix `Headers#to_h` so that indexed headers are not left in an inconsistent state if errors occur during processing.
+
+### v0.57.0
+
+  - Always use `#parse` when parsing header values from strings to ensure proper normalization and validation.
+  - Introduce `Protocol::HTTP::InvalidTrailerError` which is raised when a trailer header is not allowed by the current policy.
+  - **Breaking**: `Headers#each` now yields parsed values according to the current policy. For the previous behaviour, use `Headers#fields`.
+
 ### v0.56.0
 
   - Introduce `Header::*.parse(value)` which parses a raw header value string into a header instance.
@@ -77,15 +89,6 @@ Please see the [project releases](https://socketry.github.io/protocol-http/relea
 
   - Add support for parsing `accept`, `accept-charset`, `accept-encoding` and `accept-language` headers into structured values.
 
-### v0.46.0
-
-  - Add support for `priority:` header.
-
-### v0.33.0
-
-  - Clarify behaviour of streaming bodies and copy `Protocol::Rack::Body::Streaming` to `Protocol::HTTP::Body::Streamable`.
-  - Copy `Async::HTTP::Body::Writable` to `Protocol::HTTP::Body::Writable`.
-
 ## See Also
 
   - [protocol-http1](https://github.com/socketry/protocol-http1) — HTTP/1 client/server implementation using this

data/releases.md

@@ -1,5 +1,17 @@
 # Releases
 
+## v0.58.0
+
+  - Move trailer validation to `Headers#add` method to ensure all additions are checked at the time of addition as this is a hard requirement.
+  - Introduce `Headers#header` method to enumerate only the main headers, excluding trailers. This can be used after invoking `Headers#trailer!` to avoid race conditions.
+  - Fix `Headers#to_h` so that indexed headers are not left in an inconsistent state if errors occur during processing.
+
+## v0.57.0
+
+  - Always use `#parse` when parsing header values from strings to ensure proper normalization and validation.
+  - Introduce `Protocol::HTTP::InvalidTrailerError` which is raised when a trailer header is not allowed by the current policy.
+  - **Breaking**: `Headers#each` now yields parsed values according to the current policy. For the previous behaviour, use `Headers#fields`.
+
 ## v0.56.0
 
   - Introduce `Header::*.parse(value)` which parses a raw header value string into a header instance.
@@ -57,13 +69,13 @@ module GRPCMessage
 end
 
 GRPC_POLICY = Protocol::HTTP::Headers::POLICY.dup
-GRPC_POLICY['grpc-status'] = GRPCStatus
-GRPC_POLICY['grpc-message'] = GRPCMessage
+GRPC_POLICY["grpc-status"] = GRPCStatus
+GRPC_POLICY["grpc-message"] = GRPCMessage
 
 # Reinterpret the headers using the new policy:
 response.headers.policy = GRPC_POLICY
-response.headers['grpc-status'] # => 0
-response.headers['grpc-message'] # => "OK"
+response.headers["grpc-status"] # => 0
+response.headers["grpc-message"] # => "OK"
 ```
 
 ## v0.53.0
@@ -117,6 +129,7 @@ client.get("/", headers: {"accept" => "text/html"}, authority: "example.com")
 # Response keyword arguments:
 def call(request)
 	return Response[200, headers: {"content-Type" => "text/html"}, body: "Hello, World!"]
+end
 ```
 
 ### Interim Response Handling
@@ -127,7 +140,12 @@ On the client side, you can pass a callback using the `interim_response` keyword
 
 ``` ruby
 client = ...
-response = client.get("/index", interim_response: proc{|status, headers| ...})
+
+interim_response = proc do |status, headers|
+	puts "Received interim response: #{status} -> #{headers.inspect}"
+end
+
+response = client.get("/index", interim_response: interim_response)
 ```
 
 On the server side, you can send an interim response using the `#send_interim_response` method:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.56.1
+  version: 0.58.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -94,6 +94,7 @@ files:
 - lib/protocol/http/header/digest.rb
 - lib/protocol/http/header/etag.rb
 - lib/protocol/http/header/etags.rb
+- lib/protocol/http/header/generic.rb
 - lib/protocol/http/header/multiple.rb
 - lib/protocol/http/header/priority.rb
 - lib/protocol/http/header/server_timing.rb
@@ -134,7 +135,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Provides abstractions to handle HTTP protocols.
 test_files: []