zzstoatzz.io
prefect server in zig
add configuration audit comparing zig vs python settings
documents magic values in zig implementation and their python equivalents,
with recommendations for improving parity.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+106
+106
docs/configuration-audit.md
+106
docs/configuration-audit.md
···
1
+
# configuration audit
2
+
3
+
comparison of magic values in zig implementation vs python prefect server settings.
4
+
5
+
## http server
6
+
7
+
| setting | zig value | python default | python env var | notes |
8
+
|---------|-----------|----------------|----------------|-------|
9
+
| port | 4200 | 4200 | `PREFECT_SERVER_API_PORT` | ✅ matches |
10
+
| host | 0.0.0.0 | 127.0.0.1 | `PREFECT_SERVER_API_HOST` | zig binds all interfaces by default |
11
+
| workers | 1 | 1 | `--workers` CLI flag | ✅ matches |
12
+
| threads | 4 | n/a | - | zap/facil.io specific; python uses async |
13
+
| max_clients | 1000 | n/a | - | zap/facil.io specific; uvicorn unlimited |
14
+
| max_body_size | 16MB | n/a | - | uvicorn default is unlimited |
15
+
| keepalive_timeout | n/a | 5s | `PREFECT_SERVER_API_KEEPALIVE_TIMEOUT` | not implemented in zig |
16
+
17
+
### recommendations
18
+
19
+
- **host**: consider defaulting to `127.0.0.1` for security parity, allow override via `PREFECT_SERVER_API_HOST`
20
+
- **threads/workers**: zap's model is different (threads per worker). current 4 threads × 1 worker is reasonable for single-process mode
21
+
- **max_body_size**: 16MB is reasonable; python has no limit which could be a DoS vector
22
+
- **keepalive_timeout**: consider adding support
23
+
24
+
## api behavior
25
+
26
+
| setting | zig value | python default | python env var | notes |
27
+
|---------|-----------|----------------|----------------|-------|
28
+
| default_limit | varies | 200 | `PREFECT_SERVER_API_DEFAULT_LIMIT` | see breakdown below |
29
+
30
+
### hardcoded limits by endpoint
31
+
32
+
| endpoint | zig limit | python default | location |
33
+
|----------|-----------|----------------|----------|
34
+
| deployments/filter | 200 | 200 | deployments.zig:316 |
35
+
| deployments/get_scheduled_flow_runs | 100 | 200 | deployments.zig:523 |
36
+
| variables/filter | 200 | 200 | variables.zig:322 |
37
+
| work_pools/filter | 10 | 200 | work_pools.zig:429 |
38
+
| work_pool_queues/filter | 10 | 200 | work_pool_queues.zig:254 |
39
+
| work_pool_workers/filter | 10 | 200 | work_pool_workers.zig:86 |
40
+
41
+
### recommendations
42
+
43
+
- make default_limit configurable via `PREFECT_SERVER_API_DEFAULT_LIMIT`
44
+
- align work_pools/workers/queues limits to 200 for parity
45
+
46
+
## database
47
+
48
+
| setting | zig value | python default | python env var | notes |
49
+
|---------|-----------|----------------|----------------|-------|
50
+
| pool_size | 10 (hardcoded in backend.zig:275) | 5 | `PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_SIZE` | zig uses larger pool |
51
+
| max_overflow | n/a | 10 | `PREFECT_SERVER_DATABASE_SQLALCHEMY_MAX_OVERFLOW` | not applicable to pg.zig |
52
+
| pool_recycle | n/a | 3600s | - | not implemented |
53
+
| statement_timeout | n/a | 10s | `PREFECT_SERVER_DATABASE_TIMEOUT` | not implemented |
54
+
| connection_timeout | n/a | 5s | `PREFECT_SERVER_DATABASE_CONNECTION_TIMEOUT` | not implemented |
55
+
56
+
### recommendations
57
+
58
+
- make pool_size configurable via `PREFECT_DATABASE_POOL_SIZE` (default 10 is fine)
59
+
- statement and connection timeouts would be good to add for production safety
60
+
61
+
## events
62
+
63
+
| setting | zig value | python default | python env var | notes |
64
+
|---------|-----------|----------------|----------------|-------|
65
+
| max_event_size | n/a | 1.5MB | `PREFECT_SERVER_EVENTS_MAXIMUM_SIZE_BYTES` | not validated in zig |
66
+
| max_related_resources | n/a | 100 | `PREFECT_SERVER_EVENTS_MAXIMUM_RELATED_RESOURCES` | not validated |
67
+
| max_labels_per_resource | n/a | 500 | `PREFECT_SERVER_EVENTS_MAXIMUM_LABELS_PER_RESOURCE` | not validated |
68
+
| retention_period | n/a | 7 days | `PREFECT_SERVER_EVENTS_RETENTION_PERIOD` | not implemented |
69
+
| websocket_backfill_page_size | 250 | 250 | `PREFECT_SERVER_EVENTS_WEBSOCKET_BACKFILL_PAGE_SIZE` | ✅ matches |
70
+
| max_websocket_backfill | 15min | 15min | `PREFECT_SERVER_EVENTS_MAXIMUM_WEBSOCKET_BACKFILL` | ✅ matches |
71
+
72
+
### recommendations
73
+
74
+
- event validation (size, related resources, labels) would improve API parity
75
+
- retention cleanup service would be good for production
76
+
77
+
## logging
78
+
79
+
| setting | zig value | python default | python env var | notes |
80
+
|---------|-----------|----------------|----------------|-------|
81
+
| level | INFO | WARNING | `PREFECT_SERVER_LOGGING_LEVEL` | zig more verbose by default |
82
+
83
+
### recommendations
84
+
85
+
- consider defaulting to WARNING to match python
86
+
87
+
## deployments
88
+
89
+
| setting | zig value | python default | python env var | notes |
90
+
|---------|-----------|----------------|----------------|-------|
91
+
| schedule_max_runs | n/a | 50 | `PREFECT_SERVER_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS` | scheduler not implemented yet |
92
+
93
+
## action items
94
+
95
+
### high priority (behavioral parity)
96
+
1. default host to 127.0.0.1
97
+
2. default logging level to WARNING
98
+
99
+
### medium priority (production safety)
100
+
3. add database statement timeout
101
+
4. add event size validation
102
+
5. add keepalive timeout support
103
+
104
+
### low priority (completeness)
105
+
6. event retention cleanup
106
+
7. deployment scheduler service