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 class Protocol::HTTP::Headers class which represents a collection of HTTP headers with built-in security and policy features.
Header-specific classes like class Protocol::HTTP::Header::Accept and class 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:

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:

# 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:

# 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:

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