0
# HTTP Client and Server
1

2
HTTP client for making requests and HTTP server for handling incoming connections. Supports both synchronous and asynchronous operations with comprehensive HTTP feature support.
3

4
## Capabilities
5

6
### HTTP Client
7

8
Asynchronous and synchronous HTTP clients for making requests with support for all HTTP methods, headers, authentication, and response handling.
9

10
```python { .api }
11
class AsyncHTTPClient:
12
    """Non-blocking HTTP client."""
13
    
14
    @classmethod
15
    def configure(cls, impl, **kwargs):
16
        """Configure HTTP client implementation."""
17
    
18
    def initialize(self, **kwargs):
19
        """Initialize client."""
20
    
21
    def close(self):
22
        """Close client and clean up resources."""
23
    
24
    def fetch(self, request, callback=None, **kwargs):
25
        """
26
        Fetch HTTP request asynchronously.
27
        
28
        Args:
29
            request: HTTPRequest object or URL string
30
            callback: Callback function (if not using async/await)
31
            **kwargs: Additional request parameters
32
            
33
        Returns:
34
            HTTPResponse object (when awaited)
35
        """
36
    
37
    def fetch_impl(self, request, callback):
38
        """Implementation-specific fetch method."""
39

40
class HTTPClient:
41
    """Blocking HTTP client."""
42
    
43
    def __init__(self, async_client_class=None, **kwargs):
44
        """Initialize blocking client."""
45
    
46
    def close(self):
47
        """Close client."""
48
    
49
    def fetch(self, request, **kwargs) -> HTTPResponse:
50
        """
51
        Fetch HTTP request synchronously.
52
        
53
        Args:
54
            request: HTTPRequest object or URL string
55
            **kwargs: Additional request parameters
56
            
57
        Returns:
58
            HTTPResponse object
59
            
60
        Raises:
61
            HTTPClientError: On HTTP errors
62
        """
63
```
64

65
### HTTP Request
66

67
Request object encapsulating all aspects of an HTTP request including URL, method, headers, body, and various options.
68

69
```python { .api }
70
class HTTPRequest:
71
    """HTTP request object."""
72
    
73
    def __init__(self, 
74
                 url: str, 
75
                 method: str = "GET", 
76
                 headers=None, 
77
                 body=None, 
78
                 auth_username: str = None, 
79
                 auth_password: str = None, 
80
                 connect_timeout: float = None, 
81
                 request_timeout: float = None, 
82
                 if_modified_since=None, 
83
                 follow_redirects: bool = None, 
84
                 max_redirects: int = None, 
85
                 user_agent: str = None, 
86
                 use_gzip: bool = None, 
87
                 network_interface: str = None, 
88
                 streaming_callback=None, 
89
                 header_callback=None, 
90
                 prepare_curl_callback=None, 
91
                 proxy_host: str = None, 
92
                 proxy_port: int = None, 
93
                 proxy_username: str = None, 
94
                 proxy_password: str = None, 
95
                 allow_nonstandard_methods: bool = None, 
96
                 validate_cert: bool = None, 
97
                 ca_certs: str = None, 
98
                 allow_ipv6: bool = None, 
99
                 client_key: str = None, 
100
                 client_cert: str = None, 
101
                 body_producer=None, 
102
                 expect_100_continue: bool = False, 
103
                 decompress_response: bool = None, 
104
                 ssl_options=None):
105
        """
106
        Initialize HTTP request.
107
        
108
        Args:
109
            url: Request URL
110
            method: HTTP method (GET, POST, etc.)
111
            headers: HTTP headers dict or HTTPHeaders
112
            body: Request body (str or bytes)
113
            auth_username: HTTP auth username
114
            auth_password: HTTP auth password
115
            connect_timeout: Connection timeout in seconds
116
            request_timeout: Total request timeout in seconds
117
            if_modified_since: datetime for conditional requests
118
            follow_redirects: Whether to follow redirects
119
            max_redirects: Maximum number of redirects
120
            user_agent: User-Agent header value
121
            use_gzip: Whether to use gzip compression
122
            network_interface: Network interface to use
123
            streaming_callback: Callback for streaming response body
124
            header_callback: Callback for response headers
125
            prepare_curl_callback: Callback to configure curl
126
            proxy_host: Proxy server hostname
127
            proxy_port: Proxy server port
128
            proxy_username: Proxy authentication username
129
            proxy_password: Proxy authentication password
130
            allow_nonstandard_methods: Allow non-standard HTTP methods
131
            validate_cert: Whether to validate SSL certificates
132
            ca_certs: Path to CA certificate file
133
            allow_ipv6: Whether to allow IPv6 addresses
134
            client_key: Path to client private key
135
            client_cert: Path to client certificate
136
            body_producer: Callable to generate request body
137
            expect_100_continue: Whether to use Expect: 100-continue
138
            decompress_response: Whether to decompress response
139
            ssl_options: SSL options dict
140
        """
141
```
142

143
### HTTP Response
144

145
Response object containing status, headers, body, and metadata from an HTTP response.
146

147
```python { .api }
148
class HTTPResponse:
149
    """HTTP response object."""
150
    
151
    def __init__(self, request, code, headers=None, buffer=None, effective_url=None, error=None, request_time=None, time_info=None, reason=None):
152
        """Initialize HTTP response."""
153
    
154
    @property
155
    def body(self) -> bytes:
156
        """Response body as bytes."""
157
    
158
    @property
159
    def headers(self):
160
        """Response headers."""
161
    
162
    @property
163
    def code(self) -> int:
164
        """HTTP status code."""
165
    
166
    @property
167
    def reason(self) -> str:
168
        """HTTP reason phrase."""
169
    
170
    @property
171
    def effective_url(self) -> str:
172
        """Final URL after redirects."""
173
    
174
    def rethrow(self):
175
        """Re-raise HTTPClientError if response was an error."""
176
```
177

178
### HTTP Server
179

180
HTTP server for handling incoming requests with support for SSL, multiple processes, and custom connection handling.
181

182
```python { .api }
183
class HTTPServer:
184
    """Multi-threaded, non-blocking HTTP server."""
185
    
186
    def __init__(self, request_callback, no_keep_alive: bool = False, xheaders: bool = False, ssl_options=None, protocol: str = None, decompress_request: bool = False, chunk_size: int = None, max_header_size: int = None, idle_connection_timeout: float = None, body_timeout: float = None, max_body_size: int = None, max_buffer_size: int = None, trusted_downstream=None):
187
        """
188
        Initialize HTTP server.
189
        
190
        Args:
191
            request_callback: Function to handle requests
192
            no_keep_alive: Disable HTTP keep-alive
193
            xheaders: Use X-Real-Ip and X-Forwarded-For headers
194
            ssl_options: SSL configuration options
195
            protocol: HTTP protocol class
196
            decompress_request: Decompress request bodies
197
            chunk_size: Chunk size for streaming
198
            max_header_size: Maximum header size
199
            idle_connection_timeout: Idle connection timeout
200
            body_timeout: Request body timeout
201
            max_body_size: Maximum request body size
202
            max_buffer_size: Maximum buffer size
203
            trusted_downstream: Trusted proxy addresses
204
        """
205
    
206
    def listen(self, port: int, address: str = ""):
207
        """
208
        Listen on given port and address.
209
        
210
        Args:
211
            port: Port number
212
            address: IP address to bind (empty for all interfaces)
213
        """
214
    
215
    def bind(self, port: int, address: str = None, family=socket.AF_INET, backlog: int = 128, flags=None, reuse_port: bool = False):
216
        """
217
        Bind to port without starting server.
218
        
219
        Args:
220
            port: Port number
221
            address: IP address to bind
222
            family: Socket family
223
            backlog: Listen backlog
224
            flags: Additional socket flags
225
            reuse_port: Enable SO_REUSEPORT
226
        """
227
    
228
    def start(self, num_processes: int = 1):
229
        """
230
        Start server with specified number of processes.
231
        
232
        Args:
233
            num_processes: Number of processes (1 for single-process)
234
        """
235
    
236
    def stop(self):
237
        """Stop accepting new connections."""
238
    
239
    def handle_stream(self, stream, address):
240
        """Handle incoming stream connection."""
241
```
242

243
### HTTP Utilities
244

245
Utility functions and classes for HTTP header handling, URL manipulation, and request/response parsing.
246

247
```python { .api }
248
class HTTPHeaders:
249
    """Case-insensitive HTTP headers dictionary."""
250
    
251
    def __init__(self, *args, **kwargs):
252
        """Initialize headers."""
253
    
254
    def add(self, name: str, value: str):
255
        """Add header (allows multiple values)."""
256
    
257
    def get(self, name: str, default=None) -> str:
258
        """Get header value."""
259
    
260
    def get_list(self, name: str) -> List[str]:
261
        """Get all values for header."""
262
    
263
    def get_all(self) -> List[Tuple[str, str]]:
264
        """Get all header name-value pairs."""
265
    
266
    def parse_line(self, line: str):
267
        """Parse header line."""
268
    
269
    @classmethod
270
    def parse(cls, headers: str):
271
        """Parse headers from string."""
272

273
class HTTPServerRequest:
274
    """HTTP request object for server-side handling."""
275
    
276
    def __init__(self, method: str = None, uri: str = None, version: str = "HTTP/1.0", headers=None, body=None, host: str = None, files=None, connection=None, start_line=None, server_connection=None):
277
        """Initialize server request."""
278
    
279
    @property
280
    def cookies(self) -> Dict[str, str]:
281
        """Request cookies."""
282
    
283
    def supports_http_1_1(self) -> bool:
284
        """Check if request supports HTTP/1.1."""
285
    
286
    def write(self, chunk: bytes, callback=None):
287
        """Write response chunk."""
288
    
289
    def finish(self):
290
        """Finish response."""
291

292
def url_concat(url: str, args) -> str:
293
    """
294
    Concatenate URL with query arguments.
295
    
296
    Args:
297
        url: Base URL
298
        args: Query arguments dict or list of tuples
299
        
300
    Returns:
301
        URL with query string
302
    """
303

304
def parse_body_arguments(content_type: str, body: bytes, arguments: Dict[str, List[bytes]], files: Dict[str, List]):
305
    """
306
    Parse form-encoded request body.
307
    
308
    Args:
309
        content_type: Content-Type header value
310
        body: Request body bytes
311
        arguments: Dictionary to store parsed arguments
312
        files: Dictionary to store uploaded files
313
    """
314

315
def parse_multipart_form_data(boundary: bytes, data: bytes, arguments: Dict[str, List[bytes]], files: Dict[str, List]):
316
    """
317
    Parse multipart form data.
318
    
319
    Args:
320
        boundary: Multipart boundary
321
        data: Form data bytes
322
        arguments: Dictionary to store parsed arguments
323
        files: Dictionary to store uploaded files
324
    """
325

326
def format_timestamp(ts) -> str:
327
    """Format timestamp for HTTP headers."""
328

329
def parse_request_start_line(line: str):
330
    """Parse HTTP request start line."""
331

332
def parse_response_start_line(line: str):
333
    """Parse HTTP response start line."""
334

335
def encode_username_password(username: str, password: str) -> str:
336
    """Encode username and password for HTTP auth."""
337

338
def split_host_and_port(netloc: str) -> Tuple[str, int]:
339
    """Split host and port from netloc."""
340
```
341

342
### HTTP/1.x Protocol
343

344
Low-level HTTP/1.x protocol implementation for custom servers and advanced use cases.
345

346
```python { .api }
347
class HTTP1Connection:
348
    """HTTP/1.x connection handler."""
349
    
350
    def __init__(self, stream, is_client: bool, params=None, context=None):
351
        """Initialize HTTP/1.x connection."""
352
    
353
    def read_response(self, delegate):
354
        """Read HTTP response."""
355
    
356
    def read_message(self, delegate):
357
        """Read HTTP message."""
358
    
359
    def write_headers(self, start_line, headers, chunk=None, callback=None):
360
        """Write response headers."""
361
    
362
    def write(self, chunk: bytes, callback=None):
363
        """Write response body chunk."""
364
    
365
    def finish(self):
366
        """Finish response."""
367

368
class HTTP1ConnectionParameters:
369
    """Parameters for HTTP/1.x connections."""
370
    
371
    def __init__(self, no_keep_alive: bool = False, chunk_size: int = None, max_header_size: int = None, header_timeout: float = None, max_body_size: int = None, body_timeout: float = None, decompress: bool = False):
372
        """Initialize connection parameters."""
373
```
374

375
## Types
376

377
```python { .api }
378
# HTTP method type
379
HTTPMethod = str
380

381
# Headers type
382
HTTPHeadersType = Union[HTTPHeaders, Dict[str, str]]
383

384
# Request callback type  
385
HTTPRequestCallback = Callable[[HTTPRequest], None]
386

387
# Response callback type
388
HTTPResponseCallback = Callable[[HTTPResponse], None]
389

390
# Streaming callback type
391
StreamingCallback = Callable[[bytes], None]
392

393
# Header callback type
394
HeaderCallback = Callable[[str], None]
395
```
396

397
## Exceptions
398

399
```python { .api }
400
class HTTPClientError(Exception):
401
    """Exception for HTTP client errors."""
402
    
403
    def __init__(self, code: int, response=None):
404
        """
405
        Initialize client error.
406
        
407
        Args:
408
            code: HTTP status code
409
            response: HTTPResponse object
410
        """
411

412
class HTTPOutputError(Exception):
413
    """Exception for HTTP output errors."""
414

415
class HTTPInputError(Exception):
416
    """Exception for HTTP input parsing errors."""
417
```