protocol-http 0.57.0 → 0.58.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46aa99ddc598b23eb7d9670a806ca18d21314fc7e4bb4e42305a4ac4bd92c868
-  data.tar.gz: 0dd66a51205e73c5d5bd57fca401ce592f31a21fb09d1bc9126fb084b293d378
+  metadata.gz: e755c82bfe5d9098e7fe898dfb19e6963e500ab9410d9c7d04e2b6eb18886689
+  data.tar.gz: 23717c1485024e2f324cc069f7684a924f864a9f57c2a6e62b7be72ba532db45
 SHA512:
-  metadata.gz: 979dec4d8fedfce87917074576493ff6365e897bd6403f409d0ff862ed1517cb4cbfbc65b0f1c95ef83f77ceb20530e4a90131e0530c737fa7532886f6d431d5
-  data.tar.gz: a52fbe05985d5d6d87d37c46b72cc71ff79b8d4023d765c79efaa5e947681dd53a1d10a083ff1e54ad47bd9358ddb7a8e8ede7313c7db36c4c7d88cfad52d3a8
+  metadata.gz: a70c2c04344069a17fe6cdf1a5d23dcdaffcfbbfad815937d229c8bdeb7299bef0db2eb45c37e0fec6c1ba8cdf729560ebfcbb261910d630fc2d15d89a7b46a9
+  data.tar.gz: fc047716362a83605223b9f0107a652ac8dcaa860c10815dd755c55a7ba73dc4a4ef468212d570e6c37340e6d7bfc3ba85ad6623c1620d38b2bbce57a9e3e4be

checksums.yaml.gz.sig

@@ -1,2 +1 @@
-E��:?[T�3-ӿ���5�@5.�ͣ:��Z�5X�0�@S�]g秱L�����W��(�8���^4�-S�Jml����7������L˸����⦓.���0`+x�j�jPCq;O�4�vx����_U�ǔ!�r�����Q"��՗!p
-J��%pw���3��{Y���������G_�!O��s�v�N��]��8�m(���e^�eʘ����H/���<u����Kߧh��4dk)� �[fS��y���0�bC�gf�_��6�k�n�?vV��y7F�1��q�f�p���1�y��	�-kz��
+_��I�X ��d2�gT�Ow����h�o��h��.ї�2���s&۰�*j	:U��2��5;�aK��5 �:�@|N�/�DMy�����������F��e5���P�󺑙j�r�����lֿn��nS1��7��ɰ�)�7y� �o��4g

data/context/streaming.md

@@ -38,7 +38,7 @@ Async do
 		Protocol::HTTP::Response[200, {}, output]
 	end
 	
-	server_task = Async {server.run}
+	server_task = Async{server.run}
 	
 	client = Async::HTTP::Client.new(endpoint)
 	
@@ -104,7 +104,7 @@ Async do
 		Protocol::HTTP::Response[200, {}, output]
 	end
 	
-	server_task = Async {server.run}
+	server_task = Async{server.run}
 	
 	client = Async::HTTP::Client.new(endpoint)
 	

data/lib/protocol/http/error.rb

@@ -19,12 +19,30 @@ module Protocol
 			include BadRequest
 			
 			# @parameter key [String] The header key that was duplicated.
-			def initialize(key)
+			def initialize(key, existing_value, new_value)
 				super("Duplicate singleton header key: #{key.inspect}")
+				
+				@key = key
+				@existing_value = existing_value
+				@new_value = new_value
 			end
 			
 			# @attribute [String] key The header key that was duplicated.
 			attr :key
+			
+			# @attribute [String] existing_value The existing value for the duplicated header.
+			attr :existing_value
+			
+			# @attribute [String] new_value The new value for the duplicated header.
+			attr :new_value
+			
+			def detailed_message(highlight: false)
+				<<~MESSAGE
+					#{self.message}
+						Existing value: #{@existing_value.inspect}
+						New value: #{@new_value.inspect}
+				MESSAGE
+			end
 		end
 		
 		# Raised when an invalid trailer header is encountered in headers.

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

@@ -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?
 				
@@ -191,7 +211,7 @@ module Protocol
 			# 	@parameter key [String] The header key.
 			# 	@parameter value [String] The raw header value.
 			def each(&block)
-				self.to_h.each(&block)
+				@fields.each(&block)
 			end
 			
 			# @returns [Boolean] Whether the headers include the specified key.
@@ -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
@@ -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,27 +444,16 @@ module Protocol
 			# @parameter hash [Hash] The hash to merge into.
 			# @parameter key [String] The header key.
 			# @parameter value [String] The raw header value.
-			# @parameter trailer [Boolean] Whether this header is in the trailer section.
-			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?
-						raise InvalidTrailerError, key
-					end
-					
 					if current_value = hash[key]
 						current_value << value
 					else
 						hash[key] = policy.parse(value)
 					end
 				else
-					# By default, headers are not allowed in trailers:
-					if trailer
-						raise InvalidTrailerError, key
-					end
-					
 					if hash.key?(key)
-						raise DuplicateHeaderError, key
+						raise DuplicateHeaderError.new(key, hash[key], value)
 					end
 					
 					hash[key] = value
@@ -437,13 +467,14 @@ module Protocol
 			# @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

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.57.0"
+		VERSION = "0.58.1"
 	end
 end

data/readme.md

@@ -30,6 +30,16 @@ 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.1
+
+  - `Protocol::HTTP::DuplicateHeaderError` now includes the existing and new values for better debugging.
+
+### 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.
@@ -79,14 +89,6 @@ Please see the [project releases](https://socketry.github.io/protocol-http/relea
 
     - Drop support for Ruby v3.1.
 
-### v0.48.0
-
-  - Add support for parsing `accept`, `accept-charset`, `accept-encoding` and `accept-language` headers into structured values.
-
-### v0.46.0
-
-  - Add support for `priority:` header.
-
 ## See Also
 
   - [protocol-http1](https://github.com/socketry/protocol-http1) — HTTP/1 client/server implementation using this

data/releases.md

@@ -1,5 +1,15 @@
 # Releases
 
+## v0.58.1
+
+  - `Protocol::HTTP::DuplicateHeaderError` now includes the existing and new values for better debugging.
+
+## 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.57.0
+  version: 0.58.1
 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