Bump minor version.

Author: ioquatix

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.

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`.

lib/protocol/http/version.rb

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

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,11 @@ 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`.

releases.md

@@ -1,6 +1,6 @@
 # Releases
 
-## Unreleased
+## v0.54.0
 
   - Introduce rich support for `Header::Digest`, `Header::ServerTiming`, `Header::TE`, `Header::Trailer` and `Header::TransferEncoding`.
 
@@ -10,15 +10,15 @@ This release introduces significant security improvements for HTTP trailer handl
 
   - **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)
+      - `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
+``` ruby
 module GRPCStatus
 	def self.new(value)
 		Integer(value)