0
# Configuration
1

2
HTTP/2 connection configuration controlling validation, encoding, normalization, and logging behavior. Configuration provides fine-tuned control over protocol handling and allows customization for different use cases.
3

4
## Capabilities
5

6
### H2Configuration Class
7

8
Main configuration object controlling HTTP/2 connection behavior, header processing, validation rules, and logging.
9

10
```python { .api }
11
class H2Configuration:
12
    def __init__(
13
        self,
14
        client_side: bool = True,
15
        header_encoding: str | None = None,
16
        validate_outbound_headers: bool = True,
17
        normalize_outbound_headers: bool = True,
18
        split_outbound_cookies: bool = False,
19
        validate_inbound_headers: bool = True,
20
        normalize_inbound_headers: bool = True,
21
        logger: DummyLogger | OutputLogger | None = None
22
    ):
23
        """
24
        Configure HTTP/2 connection behavior.
25
        
26
        Args:
27
            client_side: Whether connection is client-side (True) or server-side (False)
28
            header_encoding: Header encoding ('utf-8', None for bytes, False to disable)
29
            validate_outbound_headers: Validate outbound headers against RFC 7540
30
            normalize_outbound_headers: Normalize outbound headers before sending
31
            split_outbound_cookies: Split cookie headers for better compression
32
            validate_inbound_headers: Validate received headers
33
            normalize_inbound_headers: Normalize received headers
34
            logger: Logger instance for debugging
35
        """
36
```
37

38
#### Configuration Properties
39

40
```python { .api }
41
@property
42
def client_side(self) -> bool:
43
    """Whether this connection is client-side or server-side."""
44

45
@property  
46
def header_encoding(self) -> str | None:
47
    """
48
    Header encoding configuration.
49
    
50
    Returns:
51
        None: Headers returned as bytes
52
        str: Encoding name (e.g., 'utf-8') for automatic string conversion
53
        False: Disable header encoding entirely
54
    """
55

56
@property
57
def validate_outbound_headers(self) -> bool:
58
    """Whether to validate outbound headers against RFC 7540 rules."""
59

60
@property
61
def normalize_outbound_headers(self) -> bool:
62
    """Whether to normalize outbound headers before sending."""
63

64
@property
65
def split_outbound_cookies(self) -> bool:
66
    """Whether to split outbound cookie headers for better compression."""
67

68
@property
69
def validate_inbound_headers(self) -> bool:
70
    """Whether to validate inbound headers against RFC 7540 rules."""
71

72
@property
73
def normalize_inbound_headers(self) -> bool:
74
    """Whether to normalize inbound headers after receiving."""
75

76
@property
77
def logger(self) -> DummyLogger | OutputLogger | None:
78
    """Logger instance for connection debugging."""
79
```
80

81
### Logger Classes
82

83
Logging infrastructure for HTTP/2 connection debugging and tracing.
84

85
#### DummyLogger
86

87
No-operation logger that discards all log messages. Used when logging is not needed.
88

89
```python { .api }
90
class DummyLogger:
91
    def __init__(self, *args): 
92
        """Initialize dummy logger that performs no logging."""
93

94
    def debug(self, *args, **kwargs) -> None:
95
        """No-op debug logging method."""
96

97
    def trace(self, *args, **kwargs) -> None:
98
        """No-op trace logging method."""
99
```
100

101
#### OutputLogger
102

103
Simple logger that outputs debug and trace messages to a file-like object (default stderr).
104

105
```python { .api }
106
class OutputLogger:
107
    def __init__(self, file=None, trace_level: bool = False):
108
        """
109
        Initialize output logger.
110
        
111
        Args:
112
            file: File-like object to write to (default: stderr)
113
            trace_level: Whether to enable trace-level logging
114
        """
115

116
    def debug(self, fmtstr: str, *args) -> None:
117
        """
118
        Log debug message.
119
        
120
        Args:
121
            fmtstr: Format string
122
            *args: Format arguments
123
        """
124

125
    def trace(self, fmtstr: str, *args) -> None:
126
        """
127
        Log trace message (if trace_level enabled).
128
        
129
        Args:
130
            fmtstr: Format string  
131
            *args: Format arguments
132
        """
133
```
134

135
## Configuration Usage Examples
136

137
### Client Configuration
138

139
```python
140
from h2.config import H2Configuration
141

142
# Basic client configuration
143
config = H2Configuration(client_side=True)
144

145
# Client with UTF-8 header encoding
146
config = H2Configuration(
147
    client_side=True,
148
    header_encoding='utf-8'
149
)
150

151
# Strict client with full validation
152
config = H2Configuration(
153
    client_side=True,
154
    validate_outbound_headers=True,
155
    validate_inbound_headers=True,  
156
    normalize_outbound_headers=True,
157
    normalize_inbound_headers=True
158
)
159
```
160

161
### Server Configuration
162

163
```python
164
from h2.config import H2Configuration, OutputLogger
165

166
# Basic server configuration
167
config = H2Configuration(client_side=False)
168

169
# Server with logging enabled
170
logger = OutputLogger(trace_level=True)
171
config = H2Configuration(
172
    client_side=False,
173
    logger=logger
174
)
175

176
# Server with cookie splitting for better compression
177
config = H2Configuration(
178
    client_side=False,
179
    split_outbound_cookies=True
180
)
181
```
182

183
### Development and Debugging Configuration
184

185
```python
186
from h2.config import H2Configuration, OutputLogger
187
import sys
188

189
# Configuration for debugging with trace logging
190
logger = OutputLogger(file=sys.stdout, trace_level=True)
191
config = H2Configuration(
192
    client_side=True,
193
    header_encoding='utf-8',
194
    logger=logger
195
)
196

197
# Permissive configuration for testing
198
config = H2Configuration(
199
    client_side=True,
200
    validate_outbound_headers=False,
201
    validate_inbound_headers=False,
202
    normalize_outbound_headers=False,
203
    normalize_inbound_headers=False
204
)
205
```
206

207
## Configuration Effects
208

209
### Header Processing
210

211
Configuration controls how headers are processed:
212

213
- **validate_outbound_headers**: Checks headers conform to RFC 7540 before sending
214
- **normalize_outbound_headers**: Converts header names to lowercase, validates format
215
- **split_outbound_cookies**: Splits cookie headers on `;` boundaries for HPACK compression
216
- **validate_inbound_headers**: Validates received headers against RFC 7540 rules  
217
- **normalize_inbound_headers**: Normalizes received header format
218
- **header_encoding**: Controls whether headers are returned as bytes or decoded strings
219

220
### Client vs Server Behavior
221

222
The `client_side` setting affects:
223

224
- Stream ID assignment (odd for client, even for server)
225
- Connection initiation behavior
226
- Push promise handling (clients receive, servers send)
227
- Default settings values
228
- State machine behavior
229

230
### Logging Integration
231

232
Logger configuration enables debugging of:
233

234
- Frame processing
235
- State transitions
236
- Header validation
237
- Flow control operations
238
- Protocol violations