protocol-http 0.53.0 → 0.55.0

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/quoted_string.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Protocol
+	module HTTP
+		# According to https://tools.ietf.org/html/rfc7231#appendix-C
+		TOKEN = /[!#$%&'*+\-.^_`|~0-9A-Z]+/i
+		
+		QUOTED_STRING = /"(?:.(?!(?<!\\)"))*.?"/
+		
+		# https://tools.ietf.org/html/rfc7231#section-5.3.1
+		QVALUE = /0(\.[0-9]{0,3})?|1(\.[0]{0,3})?/
+		
+		# Handling of HTTP quoted strings.
+		module QuotedString
+			# Unquote a "quoted-string" value according to <https://tools.ietf.org/html/rfc7230#section-3.2.6>. It should already match the QUOTED_STRING pattern above by the parser.
+			def self.unquote(value, normalize_whitespace = true)
+				value = value[1...-1]
+				
+				value.gsub!(/\\(.)/, '\1')
+				
+				if normalize_whitespace
+					# LWS = [CRLF] 1*( SP | HT )
+					value.gsub!(/[\r\n]+\s+/, " ")
+				end
+				
+				return value
+			end
+			
+			QUOTES_REQUIRED = /[()<>@,;:\\"\/\[\]?={} \t]/
+			
+			# Quote a string for HTTP header values if required.
+			#
+			# @raises [ArgumentError] if the value contains invalid characters like control characters or newlines.
+			def self.quote(value, force = false)
+				# Check if quoting is required:
+				if value =~ QUOTES_REQUIRED or force
+					"\"#{value.gsub(/["\\]/, '\\\\\0')}\""
+				else
+					value
+				end
+			end
+		end
+	end
+end

data/lib/protocol/http/version.rb

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

data/readme.md

@@ -18,11 +18,9 @@ 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.
 
-  - [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).
+  - [Headers](https://socketry.github.io/protocol-http/guides/headers/index) - This guide explains how to work with HTTP headers using `protocol-http`.
 
-  - [URL Parsing](https://socketry.github.io/protocol-http/guides/url-parsing/index) - This guide explains how to use `Protocol::HTTP::URL` for parsing and manipulating URL components, particularly query strings and parameters.
+  - [Middleware](https://socketry.github.io/protocol-http/guides/middleware/index) - This guide explains how to build and use HTTP middleware with `Protocol::HTTP::Middleware`.
 
   - [Streaming](https://socketry.github.io/protocol-http/guides/streaming/index) - This guide gives an overview of how to implement streaming requests and responses.
 
@@ -32,6 +30,20 @@ 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.55.0
+
+  - **Breaking**: Move `Protocol::HTTP::Header::QuotedString` to `Protocol::HTTP::QuotedString` for better reusability.
+  - **Breaking**: Handle cookie key/value pairs using `QuotedString` as per RFC 6265.
+      - Don't use URL encoding for cookie key/value.
+  - **Breaking**: Remove `Protocol::HTTP::URL` and `Protocol::HTTP::Reference` – replaced by `Protocol::URL` gem.
+      - `Protocol::HTTP::URL` -\> `Protocol::URL::Encoding`.
+      - `Protocol::HTTP::Reference` -\> `Protocol::URL::Reference`.
+
+### 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`.
@@ -70,17 +82,13 @@ Please see the [project releases](https://socketry.github.io/protocol-http/relea
 
   - Ensure chunks are flushed if required, when streaming.
 
-### v0.30.0
-
-  - [`Request[]` and `Response[]` Keyword Arguments](https://socketry.github.io/protocol-http/releases/index#request[]-and-response[]-keyword-arguments)
-  - [Interim Response Handling](https://socketry.github.io/protocol-http/releases/index#interim-response-handling)
-
 ## See Also
 
   - [protocol-http1](https://github.com/socketry/protocol-http1) — HTTP/1 client/server implementation using this
     interface.
   - [protocol-http2](https://github.com/socketry/protocol-http2) — HTTP/2 client/server implementation using this
     interface.
+  - [protocol-url](https://github.com/socketry/protocol-url) — URL parsing and manipulation library.
   - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client and server, supporting multiple HTTP
     protocols & TLS.
   - [async-websocket](https://github.com/socketry/async-websocket) — Asynchronous client and server WebSockets.