protocol-http 0.52.0 → 0.54.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/response.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 "body/buffered"
 require_relative "body/reader"

data/lib/protocol/http/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
 	module HTTP
-		VERSION = "0.52.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,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.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`.
+  - Improve `as_json` support for Body wrappers.
+
 ### v0.52.0
 
   - Add `Protocol::HTTP::Headers#to_a` method that returns the fields array, providing compatibility with standard Ruby array conversion pattern.

data/releases.md

@@ -1,5 +1,59 @@
 # 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`.
+  - Improve `as_json` support for Body wrappers.
+
 ## v0.52.0
 
   - Add `Protocol::HTTP::Headers#to_a` method that returns the fields array, providing compatibility with standard Ruby array conversion pattern.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-http
 version: !ruby/object:Gem::Version
-  version: 0.52.0
+  version: 0.54.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -53,9 +53,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- agent.md
 - context/design-overview.md
 - context/getting-started.md
+- context/headers.md
 - context/hypertext-references.md
 - context/index.yaml
 - context/message-body.md
@@ -91,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

data/agent.md

@@ -1,145 +0,0 @@
-# Agent
-
-## Context
-
-This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
-
-**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**
-
-**Setup Instructions:** If the referenced files are not present or if dependencies have been updated, run `bake agent:context:install` to install the latest context files.
-
-### agent-context
-
-Install and manage context files from Ruby gems.
-
-#### [Getting Started](.context/agent-context/getting-started.md)
-
-This guide explains how to use `agent-context`, a tool for discovering and installing contextual information from Ruby gems to help AI agents.
-
-### async
-
-A concurrency framework for Ruby.
-
-#### [Getting Started](.context/async/getting-started.md)
-
-This guide shows how to add async to your project and run code asynchronously.
-
-#### [Scheduler](.context/async/scheduler.md)
-
-This guide gives an overview of how the scheduler is implemented.
-
-#### [Tasks](.context/async/tasks.md)
-
-This guide explains how asynchronous tasks work and how to use them.
-
-#### [Best Practices](.context/async/best-practices.md)
-
-This guide gives an overview of best practices for using Async.
-
-#### [Debugging](.context/async/debugging.md)
-
-This guide explains how to debug issues with programs that use Async.
-
-#### [Thread safety](.context/async/thread-safety.md)
-
-This guide explains thread safety in Ruby, focusing on fibers and threads, common pitfalls, and best practices to avoid problems like data corruption, race conditions, and deadlocks.
-
-### async-service
-
-A service layer for Async.
-
-#### [Getting Started](.context/async-service/getting-started.md)
-
-This guide explains how to get started with `async-service` to create and run services in Ruby.
-
-#### [Service Architecture](.context/async-service/service-architecture.md)
-
-This guide explains the key architectural components of `async-service` and how they work together to provide a clean separation of concerns.
-
-#### [Best Practices](.context/async-service/best-practices.md)
-
-This guide outlines recommended patterns and practices for building robust, maintainable services with `async-service`.
-
-### decode
-
-Code analysis for documentation generation.
-
-#### [Getting Started with Decode](.context/decode/getting-started.md)
-
-The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, documentation generation, and other programmatic manipulations of Ruby codebases.
-
-#### [Documentation Coverage](.context/decode/coverage.md)
-
-This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
-
-#### [Ruby Documentation](.context/decode/ruby-documentation.md)
-
-This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate API documentation and achieve complete documentation coverage.
-
-#### [Setting Up RBS Types and Steep Type Checking for Ruby Gems](.context/decode/types.md)
-
-This guide covers the process for establishing robust type checking in Ruby gems using RBS and Steep, focusing on automated generation from source documentation and proper validation.
-
-### falcon
-
-A fast, asynchronous, rack-compatible web server.
-
-#### [Getting Started](.context/falcon/getting-started.md)
-
-This guide gives an overview of how to use Falcon for running Ruby web applications.
-
-#### [Rails Integration](.context/falcon/rails-integration.md)
-
-This guide explains how to host Rails applications with Falcon.
-
-#### [Deployment](.context/falcon/deployment.md)
-
-This guide explains how to deploy applications using the Falcon web server. It covers the recommended deployment methods, configuration options, and examples for different environments, including systemd and kubernetes.
-
-#### [Performance Tuning](.context/falcon/performance-tuning.md)
-
-This guide explains the performance characteristics of Falcon.
-
-#### [WebSockets](.context/falcon/websockets.md)
-
-This guide explains how to use WebSockets with Falcon.
-
-#### [Interim Responses](.context/falcon/interim-responses.md)
-
-This guide explains how to use interim responses in Falcon to send early hints to the client.
-
-#### [How It Works](.context/falcon/how-it-works.md)
-
-This guide gives an overview of how Falcon handles an incoming web request.
-
-### sus
-
-A fast and scalable test runner.
-
-#### [Using Sus Testing Framework](.context/sus/usage.md)
-
-Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
-
-#### [Mocking](.context/sus/mocking.md)
-
-There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace method implementations or set up more complex behavior.
-
-#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
-
-Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.
-
-### utopia-project
-
-A project documentation tool based on Utopia.
-
-#### [Getting Started](.context/utopia-project/getting-started.md)
-
-This guide explains how to use `utopia-project` to add documentation to your project.
-
-#### [Documentation Guides](.context/utopia-project/documentation-guidelines.md)
-
-This guide explains how to create and maintain documentation for your project using `utopia-project`.
-
-#### [GitHub Pages Integration](.context/utopia-project/github-pages-integration.md)
-
-This guide shows you how to use `utopia-project` with GitHub Pages to deploy documentation.