protocol-http 0.57.0 → 0.58.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46aa99ddc598b23eb7d9670a806ca18d21314fc7e4bb4e42305a4ac4bd92c868
-  data.tar.gz: 0dd66a51205e73c5d5bd57fca401ce592f31a21fb09d1bc9126fb084b293d378
+  metadata.gz: 971bece5e113d3f945faf8b8ce44858e97f0e6282e3a264b6e6fca1e57c8e71c
+  data.tar.gz: 8d1139a2022dbe96710d7e0286a5c30c2384e14fcba3e0907428361b25c3a703
 SHA512:
-  metadata.gz: 979dec4d8fedfce87917074576493ff6365e897bd6403f409d0ff862ed1517cb4cbfbc65b0f1c95ef83f77ceb20530e4a90131e0530c737fa7532886f6d431d5
-  data.tar.gz: a52fbe05985d5d6d87d37c46b72cc71ff79b8d4023d765c79efaa5e947681dd53a1d10a083ff1e54ad47bd9358ddb7a8e8ede7313c7db36c4c7d88cfad52d3a8
+  metadata.gz: 69d17f997389daf2332cacc0d5ac407897e2dc2a45c3e329f23dfc9b18f7075b425e10c43fff27ff1728f64e92a6843e3291be5103e9ee8c72d1f810c2603c01
+  data.tar.gz: '09676f19f6b3bd4d6290b5dccd8f93d2c6409e82926fa74a9b21f39f4fa92df0d289ef8fac6b0460a9de2784d78d7114d262f9a5088f66518ef60b9d60a877f4'

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/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,25 +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.
-			# @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
 					end
@@ -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.0"
 	end
 end

data/readme.md

@@ -30,6 +30,12 @@ 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.
@@ -83,10 +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.
-
 ## See Also
 
   - [protocol-http1](https://github.com/socketry/protocol-http1) — HTTP/1 client/server implementation using this

data/releases.md

@@ -1,5 +1,11 @@
 # 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.

metadata

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

metadata.gz.sig

@@ -1,4 +1,4 @@
-1k	ҟ$l�;�Iͥ�[��&��}L���D�R���m�
�p_�_>���\�šN��>��Ͱ���Dৎ�Z;���?�*�D���T�kveҩjVvE^N5�
�j��+�7��d��iӄW�'�Q�[J�)E&
-��ա��D=H�[��F�0����[�#K���V�{U���� ��Y4��zm����[��Gs�E�y�Ff�i�x���
-yo�.y^�q=�b8 �	�D�{�g�No�4$�Is��K2_��KFc�6��A�;��������CvegAm��
-�VW�}�}�/X������y_[���m=�o�����9�3��_���õ�Kn�:�EEoS��
+^�eG�{d65o���u����abH��]��+�>�ҁg������j'���S��6
+�n�q�(�6j��:��|ʱ����"�p�tD磩.#ac�F����B&Za����^PYL���򌑓��^��w��(Yj�cRay��	��ʃ�H|\�]�Μ]�dAo�08�\Rî�;�@��J�Ы����I�Y��1���Z�/�O=���
�o6�*��a���+���#u�����+6Ml8�~a�`��=4��K̬�	��ӭ0hN�
+@}L��O�pS5�������
+:b����