0
# Configuration
1
2
Comprehensive configuration system for tuning server performance, security, and behavior through the Adjustments class and utility functions.
3
4
## Capabilities
5
6
### Adjustments Class
7
8
Central configuration container for all server parameters, with validation and type conversion.
9
10
```python { .api }
11
class Adjustments:
12
"""Configuration container for all tunable server parameters."""
13
14
def __init__(self, **kw):
15
"""
16
Initialize server configuration.
17
18
Parameters accept both command-line style (with dashes) and
19
Python style (with underscores) parameter names.
20
"""
21
22
@classmethod
23
def parse_args(cls, argv):
24
"""
25
Parse command-line arguments into configuration dictionary.
26
27
Parameters:
28
- argv (list): Command-line argument list
29
30
Returns:
31
tuple: (kw, args) where kw is configuration dict and args is remaining arguments
32
33
Note:
34
This method creates a dictionary suitable for passing to __init__,
35
where __init__ performs the type casting and validation.
36
"""
37
```
38
39
### Network Configuration
40
41
Parameters controlling network binding and socket behavior.
42
43
```python { .api }
44
# Network binding attributes
45
host: str = "0.0.0.0" # Hostname/IP to bind to
46
port: int = 8080 # TCP port to bind to
47
listen: list # List of (host, port) tuples for multiple bindings
48
ipv4: bool = True # Enable IPv4 socket support
49
ipv6: bool = True # Enable IPv6 socket support
50
unix_socket: str = None # Unix domain socket path
51
unix_socket_perms: int = 0o600 # Unix socket file permissions
52
sockets: list = [] # Pre-existing socket objects to use
53
```
54
55
Usage example:
56
57
```python
58
from waitress import serve
59
from waitress.adjustments import Adjustments
60
61
# Direct parameter passing
62
serve(app, host='127.0.0.1', port=5000, ipv6=True)
63
64
# Using Adjustments class
65
adj = Adjustments(
66
host='0.0.0.0',
67
port=8080,
68
unix_socket='/tmp/app.sock',
69
unix_socket_perms=0o666
70
)
71
serve(app, **adj.__dict__)
72
73
# Multiple listening addresses
74
serve(app, listen=[('127.0.0.1', 8080), ('127.0.0.1', 8081)])
75
```
76
77
### Performance Configuration
78
79
Parameters for tuning server performance and resource usage.
80
81
```python { .api }
82
# Threading and concurrency
83
threads: int = 4 # Number of worker threads
84
backlog: int = 1024 # Socket listen backlog
85
connection_limit: int = 100 # Maximum concurrent connections
86
87
# Buffer sizes
88
recv_bytes: int = 8192 # Socket receive buffer size
89
send_bytes: int = 18000 # Socket send buffer size
90
inbuf_overflow: int = 512000 # Input buffer overflow threshold
91
outbuf_overflow: int = 1048576 # Output buffer overflow threshold
92
93
# Timeouts
94
channel_timeout: int = 120 # Idle connection timeout (seconds)
95
cleanup_interval: int = 30 # Connection cleanup interval (seconds)
96
asyncore_loop_timeout: float = 1.0 # asyncore loop timeout (seconds)
97
```
98
99
Usage example:
100
101
```python
102
# High-performance configuration
103
serve(app,
104
threads=8, # More worker threads
105
connection_limit=1000, # Higher connection limit
106
recv_bytes=16384, # Larger receive buffer
107
channel_timeout=300, # Longer timeout
108
backlog=2048 # Larger listen backlog
109
)
110
```
111
112
### Request Limits
113
114
Parameters controlling request size and processing limits.
115
116
```python { .api }
117
# Request size limits
118
max_request_header_size: int = 262144 # Maximum header size (256KB)
119
max_request_body_size: int = 1073741824 # Maximum body size (1GB)
120
121
# Content handling
122
expose_tracebacks: bool = False # Show Python tracebacks to clients
123
```
124
125
Usage example:
126
127
```python
128
# Restrict request sizes for security
129
serve(app,
130
max_request_header_size=65536, # 64KB headers max
131
max_request_body_size=10485760, # 10MB body max
132
expose_tracebacks=False # Never expose tracebacks
133
)
134
```
135
136
### Proxy Configuration
137
138
Parameters for handling requests from reverse proxies and load balancers.
139
140
```python { .api }
141
# Proxy trust settings
142
trusted_proxy: str = None # Trusted proxy IP address
143
trusted_proxy_count: int = None # Number of trusted proxies
144
trusted_proxy_headers: set = None # Which proxy headers to trust
145
146
# URL scheme handling
147
url_scheme: str = "http" # Default URL scheme for WSGI environ
148
url_prefix: str = "" # SCRIPT_NAME prefix for applications
149
```
150
151
Usage example:
152
153
```python
154
# Behind nginx reverse proxy
155
serve(app,
156
trusted_proxy='127.0.0.1',
157
trusted_proxy_headers={'x-forwarded-for', 'x-forwarded-proto'},
158
url_scheme='https' # App sees HTTPS even if proxy uses HTTP
159
)
160
161
# Multiple proxy layers
162
serve(app,
163
trusted_proxy_count=2, # Trust 2 proxy hops
164
trusted_proxy_headers={'x-forwarded-for', 'x-forwarded-proto', 'x-forwarded-host'}
165
)
166
```
167
168
### Logging and Debugging
169
170
Parameters controlling server logging and error reporting.
171
172
```python { .api }
173
# Logging configuration
174
log_socket_errors: bool = True # Log socket-level errors
175
ident: str = "waitress" # Server identification string for logs
176
expose_tracebacks: bool = False # Show tracebacks in error responses
177
```
178
179
### Configuration Utility Functions
180
181
Helper functions for parsing and converting configuration values.
182
183
```python { .api }
184
def asbool(s):
185
"""
186
Convert string to boolean value.
187
188
Parameters:
189
- s: String value ('t', 'true', 'y', 'yes', 'on', '1' are truthy)
190
191
Returns:
192
bool: Converted boolean value
193
"""
194
195
def asoctal(s):
196
"""
197
Convert octal string to integer.
198
199
Parameters:
200
- s (str): Octal string (e.g., '644', '0o755')
201
202
Returns:
203
int: Integer value
204
"""
205
206
def aslist(value):
207
"""
208
Convert value to list, splitting on whitespace and newlines.
209
210
Parameters:
211
- value: String or iterable to convert
212
213
Returns:
214
list: List of string values
215
"""
216
217
def aslist_cronly(value):
218
"""
219
Convert value to list, splitting only on newlines.
220
221
Parameters:
222
- value: String or iterable to convert
223
224
Returns:
225
list: List of string values
226
"""
227
228
def asset(value):
229
"""
230
Convert value to set using aslist().
231
232
Parameters:
233
- value: Value to convert to set
234
235
Returns:
236
set: Set of string values
237
"""
238
239
def slash_fixed_str(s):
240
"""
241
Normalize URL path with leading slash.
242
243
Parameters:
244
- s (str): URL path to normalize
245
246
Returns:
247
str: Path with single leading slash and no trailing slash
248
249
Example:
250
>>> slash_fixed_str('path/to/resource/')
251
'/path/to/resource'
252
"""
253
254
def str_iftruthy(s):
255
"""
256
Convert to string if truthy, else return None.
257
258
Parameters:
259
- s: Value to convert
260
261
Returns:
262
str or None: String representation if truthy, None otherwise
263
"""
264
265
def as_socket_list(sockets):
266
"""
267
Filter list to socket objects only.
268
269
Parameters:
270
- sockets (list): List that may contain socket objects
271
272
Returns:
273
list: List containing only actual socket.socket instances
274
275
Notes:
276
- Removes non-socket objects from the list
277
- Used for validating socket configuration
278
"""
279
```
280
281
Usage example:
282
283
```python
284
from waitress.adjustments import asbool, asoctal, aslist
285
286
# Configuration parsing
287
expose_tracebacks = asbool('true') # True
288
socket_perms = asoctal('644') # 420
289
trusted_headers = asset('x-forwarded-for x-forwarded-proto') # {'x-forwarded-for', 'x-forwarded-proto'}
290
```
291
292
### Command-Line Integration
293
294
The Adjustments class automatically handles command-line argument parsing.
295
296
```python { .api }
297
# Command-line parameter formats accepted:
298
# --host=127.0.0.1
299
# --port=8080
300
# --threads=6
301
# --unix-socket=/tmp/app.sock
302
# --trusted-proxy=127.0.0.1
303
# --max-request-body-size=1048576
304
```
305
306
Usage example:
307
308
```python
309
import sys
310
from waitress.adjustments import Adjustments
311
312
# Parse command-line arguments
313
adj = Adjustments.parse_args(sys.argv[1:])
314
serve(app, **adj.__dict__)
315
```