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