1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
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.
|
