protocol-http 0.52.0 → 0.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e1927ee19fba11fbeb421268490fabcde86d7ef9ca5d472320b9aaad6763892
-  data.tar.gz: fe4c304a05ce7c3637ad460e976dbbf114c22dfb49fe425f9a2dbde1cf280d35
+  metadata.gz: c76db95baeca082a769340ab2a29ee5948bb837894e55039c082653453aa4f4f
+  data.tar.gz: 868cdcc4a21786c640c8c06e7892bfd6ef19f81670a90274692cfadef10a0c39
 SHA512:
-  metadata.gz: 97d19c21e2d67d5870077b7ae2856438a1e4314934f01bc93148f63be4db4d55ffee18f45f66ed7b0665678dd8b0deb4718cda92fd9334f198bb2fa335bb297f
-  data.tar.gz: 674bd9d94d4efacde5d42d8c02dd8876f7f8f96290a26051343103c11f6e68ae54678746bf6d034071c0bba3a5dd7263affecc8c3e86be9ec1766faefc93e50a
+  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/body/buffered.rb

@@ -153,8 +153,10 @@ module Protocol
 				#
 				# @returns [String] a string representation of the buffered body.
 				def inspect
-					if @chunks
-						"\#<#{self.class} #{@chunks.size} chunks, #{self.length} bytes>"
+					if @chunks and @chunks.size > 0
+						"#<#{self.class} #{@index}/#{@chunks.size} chunks, #{self.length} bytes>"
+					else
+						"#<#{self.class} empty>"
 					end
 				end
 			end

data/lib/protocol/http/body/completable.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.
 
 require_relative "wrapper"
 
@@ -53,6 +53,23 @@ module Protocol
 					
 					super
 				end
+				
+				# Convert the body to a hash suitable for serialization.
+				#
+				# @returns [Hash] The body as a hash.
+				def as_json(...)
+					super.merge(
+						callback: @callback&.to_s
+					)
+				end
+				
+				# Inspect the completable body.
+				#
+				# @returns [String] a string representation of the completable body.
+				def inspect
+					callback_status = @callback ? "callback pending" : "callback completed"
+					return "#{super} | #<#{self.class} #{callback_status}>"
+				end
 			end
 		end
 	end

data/lib/protocol/http/body/deflate.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.
 
 require_relative "wrapper"
 
@@ -75,11 +75,22 @@ module Protocol
 					end
 				end
 				
+				# Convert the body to a hash suitable for serialization.
+				#
+				# @returns [Hash] The body as a hash.
+				def as_json(...)
+					super.merge(
+						input_length: @input_length,
+						output_length: @output_length,
+						compression_ratio: (ratio * 100).round(2)
+					)
+				end
+				
 				# Inspect the body, including the compression ratio.
 				#
 				# @returns [String] a string representation of the body.
 				def inspect
-					"#{super} | \#<#{self.class} #{(ratio*100).round(2)}%>"
+					"#{super} | #<#{self.class} #{(ratio*100).round(2)}%>"
 				end
 			end
 			

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2025, by Samuel Williams.
 
 require_relative "wrapper"
 
@@ -64,6 +64,16 @@ module Protocol
 						return nil
 					end
 				end
+				
+				# Convert the body to a hash suitable for serialization.
+				#
+				# @returns [Hash] The body as a hash.
+				def as_json(...)
+					super.merge(
+						digest_class: @digest.class.name,
+						callback: @callback&.to_s
+					)
+				end
 			end
 		end
 	end

data/lib/protocol/http/body/file.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.
 
 require_relative "readable"
 
@@ -135,7 +135,11 @@ module Protocol
 				#
 				# @returns [String] a string representation of the file body.
 				def inspect
-					"\#<#{self.class} file=#{@file.inspect} offset=#{@offset} remaining=#{@remaining}>"
+					if @offset > 0
+						"#<#{self.class} #{@file.inspect} +#{@offset}, #{@remaining} bytes remaining>"
+					else
+						"#<#{self.class} #{@file.inspect}, #{@remaining} bytes remaining>"
+					end
 				end
 			end
 		end

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

@@ -53,6 +53,13 @@ module Protocol
 				def length
 					@length
 				end
+				
+				# Inspect the head body.
+				#
+				# @returns [String] a string representation of the head body.
+				def inspect
+					"#<#{self.class} #{@length} bytes (empty)>"
+				end
 			end
 		end
 	end

data/lib/protocol/http/body/inflate.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.
 
 require "zlib"
 

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

@@ -82,11 +82,21 @@ module Protocol
 					true
 				end
 				
+				# Convert the body to a hash suitable for serialization.
+				#
+				# @returns [Hash] The body as a hash.
+				def as_json(...)
+					super.merge(
+						index: @index,
+						chunks: @chunks.size
+					)
+				end
+				
 				# Inspect the rewindable body.
 				#
 				# @returns [String] a string representation of the body.
 				def inspect
-					"\#<#{self.class} #{@index}/#{@chunks.size} chunks read>"
+					"#{super} | #<#{self.class} #{@index}/#{@chunks.size} chunks read>"
 				end
 			end
 		end

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

@@ -386,6 +386,21 @@ module Protocol
 					@closed
 				end
 				
+				# Inspect the stream.
+				#
+				# @returns [String] a string representation of the stream.
+				def inspect
+					buffer_info = @buffer ? "#{@buffer.bytesize} bytes buffered" : "no buffer"
+					
+					status = []
+					status << "closed" if @closed
+					status << "read-closed" if @closed_read
+					
+					status_info = status.empty? ? "open" : status.join(", ")
+					
+					return "#<#{self.class} #{buffer_info}, #{status_info}>"
+				end
+				
 				# @returns [Boolean] Whether there are any output chunks remaining.
 				def empty?
 					@output.empty?

data/lib/protocol/http/body/streamable.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.
 
 require_relative "readable"
 require_relative "writable"
@@ -147,7 +147,23 @@ module Protocol
 					#
 					# @parameter error [Exception | Nil] The error that caused this stream to be closed, if any.
 					def close_output(error = nil)
-						@output&.close(error)
+						if output = @output
+							@output = nil
+							output.close(error)
+						end
+					end
+					
+					# Inspect the streaming body.
+					#
+					# @returns [String] a string representation of the streaming body.
+					def inspect
+						if @block
+							"#<#{self.class} block available, not consumed>"
+						elsif @output
+							"#<#{self.class} block consumed, output active>"
+						else
+							"#<#{self.class} block consumed, output closed>"
+						end
 					end
 				end
 				

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "readable"
 
@@ -166,9 +166,9 @@ module Protocol
 				# @returns [String] A string representation of the body.
 				def inspect
 					if @error
-						"\#<#{self.class} #{@count} chunks written, #{status}, error=#{@error}>"
+						"#<#{self.class} #{@count} chunks written, #{status}, error=#{@error}>"
 					else
-						"\#<#{self.class} #{@count} chunks written, #{status}>"
+						"#<#{self.class} #{@count} chunks written, #{status}>"
 					end
 				end
 				

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)