protocol-http 0.53.0 → 0.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49ea23b4e99ab120bfd68806628631db474b789d7ca841a28877ba176239816f
-  data.tar.gz: 2dbe6a91006f94a303babb3b156a55eb82ac60025f111d7f003896e744009394
+  metadata.gz: c76db95baeca082a769340ab2a29ee5948bb837894e55039c082653453aa4f4f
+  data.tar.gz: 868cdcc4a21786c640c8c06e7892bfd6ef19f81670a90274692cfadef10a0c39
 SHA512:
-  metadata.gz: 0d05dca30d34d5a66483cf09b3b3927af1bd6cf4679cd2421fa0737ab7f6cd56b61fd681d90c7b3252c6bc79d6843b8460c3c74c595b31ff636fb46920088165
-  data.tar.gz: 75cb7b599a2ba9d49f859b16f00f94bc2e59118813779e9a4a7e5804ea94d6cc66cc361fc4ef0d7ce957e26bbf7a6a53e1f7b02ec92e438260bfa5a1a33e1299
+  metadata.gz: acc4afb3f7caba7ec2d2611ab72dce9c954e88e8dfe72645645e442d8116909c3f228b22c2d460633d429510ffff5f6f4713bfff751f18d4873db167e773fcbe
+  data.tar.gz: ef0e92bac69dba33417d074c24ce6d2f2009e19e1d81d317eecaf945817f3c7fb0775052048ca24df32b3f39c15f8de83ca45054669e2d89b5bf3b5b445c7cf1

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,6 +14,9 @@ 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`.

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

@@ -92,6 +92,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/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)

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

@@ -0,0 +1,131 @@
+# 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 `te` header indicates the transfer encodings the client is willing to accept. AKA `accept-transfer-encoding`. How we ended up with `te` instead of `accept-transfer-encoding` is a mystery lost to time.
+			#
+			# The `te` header allows a client to indicate which transfer encodings it can handle, and in what order of preference using quality factors.
+			class TE < Split
+				ParseError = Class.new(Error)
+				
+				# Transfer encoding token pattern
+				TOKEN = /[!#$%&'*+\-.0-9A-Z^_`a-z|~]+/
+				
+				# Quality value pattern (0.0 to 1.0)
+				QVALUE = /0(\.[0-9]{0,3})?|1(\.[0]{0,3})?/
+				
+				# Pattern for parsing transfer encoding with optional quality factor
+				TRANSFER_CODING = /\A(?<name>#{TOKEN})(\s*;\s*q=(?<q>#{QVALUE}))?\z/
+				
+				# The `chunked` transfer encoding
+				CHUNKED = "chunked"
+				
+				# The `gzip` transfer encoding
+				GZIP = "gzip"
+				
+				# The `deflate` transfer encoding  
+				DEFLATE = "deflate"
+				
+				# The `compress` transfer encoding
+				COMPRESS = "compress"
+				
+				# The `identity` transfer encoding
+				IDENTITY = "identity"
+				
+				# The `trailers` pseudo-encoding indicates willingness to accept trailer fields
+				TRAILERS = "trailers"
+				
+				# A single transfer coding entry with optional quality factor
+				TransferCoding = Struct.new(:name, :q) do
+					def quality_factor
+						(q || 1.0).to_f
+					end
+					
+					def <=> other
+						other.quality_factor <=> self.quality_factor
+					end
+					
+					def to_s
+						if q && q != 1.0
+							"#{name};q=#{q}"
+						else
+							name.to_s
+						end
+					end
+				end
+				
+				# Initializes the TE header with the given value. The value is split into distinct entries and converted to lowercase for normalization.
+				#
+				# @parameter value [String | Nil] the raw header value containing transfer encodings separated by commas.
+				def initialize(value = nil)
+					super(value&.downcase)
+				end
+				
+				# Adds one or more comma-separated values to the TE header. The values are converted to lowercase for normalization.
+				#
+				# @parameter value [String] the value or values to add, separated by commas.
+				def << value
+					super(value.downcase)
+				end
+				
+				# Parse the `te` header value into a list of transfer codings with quality factors.
+				#
+				# @returns [Array(TransferCoding)] the list of transfer codings and their associated quality factors.
+				def transfer_codings
+					self.map do |value|
+						if match = value.match(TRANSFER_CODING)
+							TransferCoding.new(match[:name], match[:q])
+						else
+							raise ParseError.new("Could not parse transfer coding: #{value.inspect}")
+						end
+					end
+				end
+				
+				# @returns [Boolean] whether the `chunked` encoding is accepted.
+				def 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)}
+				end
+				
+				# @returns [Boolean] whether the `deflate` encoding is accepted.
+				def 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)}
+				end
+				
+				# @returns [Boolean] whether the `identity` encoding is accepted.
+				def identity?
+					self.any? {|value| value.start_with?(IDENTITY)}
+				end
+				
+				# @returns [Boolean] whether trailers are accepted.
+				def trailers?
+					self.any? {|value| value.start_with?(TRAILERS)}
+				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# TE headers negotiate transfer encodings and must not appear in trailers.
+				# @returns [Boolean] `false`, as TE headers are hop-by-hop and control message framing.
+				def self.trailer?
+					false
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "split"
+
+module Protocol
+	module HTTP
+		module Header
+			# Represents headers that can contain multiple distinct values separated by commas.
+			#
+			# This isn't a specific header  class is a utility for handling headers with comma-separated values, such as `accept`, `cache-control`, and other similar headers. The values are split and stored as an array internally, and serialized back to a comma-separated string when needed.
+			class Trailer < Split
+				# Whether this header is acceptable in HTTP trailers.
+				# @returns [Boolean] `false`, as Trailer headers control trailer processing and must appear before the message body.
+				def self.trailer?
+					false
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "split"
+
+module Protocol
+	module HTTP
+		module Header
+			# The `transfer-encoding` header indicates the encoding transformations that have been applied to the message body.
+			#
+			# The `transfer-encoding` header is used to specify the form of encoding used to safely transfer the message body between the sender and receiver.
+			class TransferEncoding < Split
+				# The `chunked` transfer encoding allows a server to send data of unknown length by breaking it into chunks.
+				CHUNKED = "chunked"
+				
+				# The `gzip` transfer encoding compresses the message body using the gzip algorithm.
+				GZIP = "gzip"
+				
+				# The `deflate` transfer encoding compresses the message body using the deflate algorithm.
+				DEFLATE = "deflate"
+				
+				# The `compress` transfer encoding compresses the message body using the compress algorithm.
+				COMPRESS = "compress"
+				
+				# The `identity` transfer encoding indicates no transformation has been applied.
+				IDENTITY = "identity"
+				
+				# Initializes the transfer encoding header with the given value. The value is split into distinct entries and converted to lowercase for normalization.
+				#
+				# @parameter value [String | Nil] the raw header value containing transfer encodings separated by commas.
+				def initialize(value = nil)
+					super(value&.downcase)
+				end
+				
+				# Adds one or more comma-separated values to the transfer encoding header. The values are converted to lowercase for normalization.
+				#
+				# @parameter value [String] the value or values to add, separated by commas.
+				def << value
+					super(value.downcase)
+				end
+				
+				# @returns [Boolean] whether the `chunked` encoding is present.
+				def chunked?
+					self.include?(CHUNKED)
+				end
+				
+				# @returns [Boolean] whether the `gzip` encoding is present.
+				def gzip?
+					self.include?(GZIP)
+				end
+				
+				# @returns [Boolean] whether the `deflate` encoding is present.
+				def deflate?
+					self.include?(DEFLATE)
+				end
+				
+				# @returns [Boolean] whether the `compress` encoding is present.
+				def compress?
+					self.include?(COMPRESS)
+				end
+				
+				# @returns [Boolean] whether the `identity` encoding is present.
+				def identity?
+					self.include?(IDENTITY)
+				end
+				
+				# Whether this header is acceptable in HTTP trailers.
+				# Transfer-Encoding headers control message framing and must not appear in trailers.
+				# @returns [Boolean] `false`, as Transfer-Encoding headers are hop-by-hop and must precede the message body.
+				def self.trailer?
+					false
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/headers.rb

@@ -17,11 +17,16 @@ require_relative "header/vary"
 require_relative "header/authorization"
 require_relative "header/date"
 require_relative "header/priority"
+require_relative "header/trailer"
+require_relative "header/server_timing"
+require_relative "header/digest"
 
 require_relative "header/accept"
 require_relative "header/accept_charset"
 require_relative "header/accept_encoding"
 require_relative "header/accept_language"
+require_relative "header/transfer_encoding"
+require_relative "header/te"
 
 module Protocol
 	module HTTP
@@ -65,7 +70,7 @@ module Protocol
 			#
 			# @parameter fields [Array] An array of `[key, value]` pairs.
 			# @parameter tail [Integer | Nil] The index of the trailer start in the @fields array.
-			def initialize(fields = [], tail = nil, indexed: nil)
+			def initialize(fields = [], tail = nil, indexed: nil, policy: POLICY)
 				@fields = fields
 				
 				# Marks where trailer start in the @fields array:
@@ -73,6 +78,21 @@ module Protocol
 				
 				# The cached index of headers:
 				@indexed = nil
+				
+				@policy = policy
+			end
+			
+			# @attribute [Hash] The policy for the headers.
+			attr :policy
+			
+			# Set the policy for the headers.
+			#
+			# The policy is used to determine how headers are merged and normalized. For example, if a header is specified multiple times, the policy will determine how the values are merged.
+			#
+			# @parameter policy [Hash] The policy for the headers.
+			def policy=(policy)
+				@policy = policy
+				@indexed = nil
 			end
 			
 			# Initialize a copy of the headers.
@@ -250,17 +270,23 @@ module Protocol
 				"content-disposition" => false,
 				"content-length" => false,
 				"content-type" => false,
+				"expect" => false,
 				"from" => false,
 				"host" => false,
 				"location" => false,
 				"max-forwards" => false,
+				"range" => false,
 				"referer" => false,
 				"retry-after" => false,
+				"server" => false,
+				"transfer-encoding" => Header::TransferEncoding,
 				"user-agent" => false,
+				"trailer" => Header::Trailer,
 				
 				# Custom headers:
 				"connection" => Header::Connection,
 				"cache-control" => Header::CacheControl,
+				"te" => Header::TE,
 				"vary" => Header::Vary,
 				"priority" => Header::Priority,
 				
@@ -299,6 +325,12 @@ module Protocol
 				"accept-charset" => Header::AcceptCharset,
 				"accept-encoding" => Header::AcceptEncoding,
 				"accept-language" => Header::AcceptLanguage,
+				
+				# Performance headers:
+				"server-timing" => Header::ServerTiming,
+				
+				# Content integrity headers:
+				"digest" => Header::Digest,
 			}.tap{|hash| hash.default = Split}
 			
 			# Delete all header values for the given key, and return the merged value.
@@ -316,7 +348,7 @@ module Protocol
 				
 				if @indexed
 					return @indexed.delete(key)
-				elsif policy = POLICY[key]
+				elsif policy = @policy[key]
 					(key, value), *tail = deleted
 					merged = policy.new(value)
 					
@@ -334,14 +366,24 @@ 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)
-				if policy = POLICY[key]
+			protected def merge_into(hash, key, value, trailer = @tail)
+				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
 						hash[key] = policy.new(value)
 					end
 				else
+					# By default, headers are not allowed in trailers:
+					if trailer
+						return false
+					end
+					
 					if hash.key?(key)
 						raise DuplicateHeaderError, key
 					end
@@ -362,11 +404,17 @@ module Protocol
 			#
 			# @returns [Hash] A hash table of `{key, value}` pairs.
 			def to_h
-				@indexed ||= @fields.inject({}) do |hash, (key, value)|
-					merge_into(hash, key.downcase, value)
+				unless @indexed
+					@indexed = {}
 					
-					hash
+					@fields.each_with_index do |(key, value), index|
+						trailer = (@tail && index >= @tail)
+						
+						merge_into(@indexed, key.downcase, value, trailer)
+					end
 				end
+				
+				return @indexed
 			end
 			
 			alias as_json to_h

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.53.0"
+		VERSION = "0.54.0"
 	end
 end

data/readme.md

@@ -18,6 +18,8 @@ Please see the [project documentation](https://socketry.github.io/protocol-http/
 
   - [Message Body](https://socketry.github.io/protocol-http/guides/message-body/index) - This guide explains how to work with HTTP request and response message bodies using `Protocol::HTTP::Body` classes.
 
+  - [Headers](https://socketry.github.io/protocol-http/guides/headers/index) - This guide explains how to work with HTTP headers using `protocol-http`.
+
   - [Middleware](https://socketry.github.io/protocol-http/guides/middleware/index) - This guide explains how to build and use HTTP middleware with `Protocol::HTTP::Middleware`.
 
   - [Hypertext References](https://socketry.github.io/protocol-http/guides/hypertext-references/index) - This guide explains how to use `Protocol::HTTP::Reference` for constructing and manipulating hypertext references (URLs with parameters).
@@ -32,6 +34,11 @@ 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.54.0
+
+  - Introduce rich support for `Header::Digest`, `Header::ServerTiming`, `Header::TE`, `Header::Trailer` and `Header::TransferEncoding`.
+  - [Improved HTTP Trailer Security](https://socketry.github.io/protocol-http/releases/index#improved-http-trailer-security)
+
 ### v0.53.0
 
   - Improve consistency of Body `#inspect`.

data/releases.md

@@ -1,5 +1,54 @@
 # Releases
 
+## v0.54.0
+
+  - Introduce rich support for `Header::Digest`, `Header::ServerTiming`, `Header::TE`, `Header::Trailer` and `Header::TransferEncoding`.
+
+### Improved HTTP Trailer Security
+
+This release introduces significant security improvements for HTTP trailer handling, addressing potential HTTP request smuggling vulnerabilities by implementing a restrictive-by-default policy for trailer headers.
+
+  - **Security-by-default**: HTTP trailers are now validated and restricted by default to prevent HTTP request smuggling attacks.
+  - Only safe headers are permitted in trailers:
+      - `date` - Response generation timestamps (safe metadata)
+      - `digest` - Content integrity verification (safe metadata)
+      - `etag` - Cache validation tags (safe metadata)
+      - `server-timing` - Performance metrics (safe metadata)
+  - All other trailers are ignored by default.
+
+If you are using this library for gRPC, you will need to use a custom policy to allow the `grpc-status` and `grpc-message` trailers:
+
+``` ruby
+module GRPCStatus
+	def self.new(value)
+		Integer(value)
+	end
+	
+	def self.trailer?
+		true
+	end
+end
+
+module GRPCMessage
+	def self.new(value)
+		value
+	end
+	
+	def self.trailer?
+		true
+	end
+end
+
+GRPC_POLICY = Protocol::HTTP::Headers::POLICY.dup
+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"
+```
+
 ## v0.53.0
 
   - Improve consistency of Body `#inspect`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.53.0
+  version: 0.54.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -55,6 +55,7 @@ extra_rdoc_files: []
 files:
 - context/design-overview.md
 - context/getting-started.md
+- context/headers.md
 - context/hypertext-references.md
 - context/index.yaml
 - context/message-body.md
@@ -90,12 +91,17 @@ files:
 - lib/protocol/http/header/connection.rb
 - lib/protocol/http/header/cookie.rb
 - lib/protocol/http/header/date.rb
+- lib/protocol/http/header/digest.rb
 - lib/protocol/http/header/etag.rb
 - lib/protocol/http/header/etags.rb
 - lib/protocol/http/header/multiple.rb
 - lib/protocol/http/header/priority.rb
 - lib/protocol/http/header/quoted_string.rb
+- lib/protocol/http/header/server_timing.rb
 - lib/protocol/http/header/split.rb
+- lib/protocol/http/header/te.rb
+- lib/protocol/http/header/trailer.rb
+- lib/protocol/http/header/transfer_encoding.rb
 - lib/protocol/http/header/vary.rb
 - lib/protocol/http/headers.rb
 - lib/protocol/http/methods.rb