zzstoatzz.io
prefect server in zig
1# prefect-server
2
3zig implementation of [prefect server](https://github.com/prefecthq/prefect) - single binary, ~3x faster, ~20x less memory.
4
5supports sqlite/postgres for storage and memory/redis for messaging. see [ROADMAP.md](ROADMAP.md) for implementation status.
6
7## usage
8
9```bash
10just dev # build and run with debug logging
11just test # run functional tests (requires running server)
12just bench-compare # benchmark zig vs python (throughput, latency, memory)
13just docker-test # build and test in docker
14```
15
16requires [zig 0.15](https://ziglang.org/) and [just](https://github.com/casey/just). run `just --list` for all commands.
17
18## testing
19
20**functional tests** (`scripts/test-api-sequence`) - verify API correctness by exercising all endpoints. includes scheduler integration tests with intentional delays.
21
22**performance benchmark** (`scripts/benchmark`) - measure throughput (requests/second), latency percentiles (p50/p95/p99), and memory usage.
23
24```bash
25just bench # benchmark zig server
26just bench-compare # compare zig vs python
27just bench-matrix # test all db × broker combinations
28```
29
30## docker
31
32published to [atcr.io](https://atcr.io) (AT Protocol container registry):
33
34```bash
35docker pull atcr.io/zzstoatzz.io/prefect-server:latest
36docker run -p 4200:4200 atcr.io/zzstoatzz.io/prefect-server:latest
37```
38
39to publish:
40```bash
41just docker-publish # push :latest
42just docker-publish v0.1.0 # push specific tag
43```
44
45## configuration
46
47see [`docs/`](docs/) for configuration details.
48
49<details>
50<summary>contributing</summary>
51
52### playbooks
53
54- [implement orchestration rule](.claude/commands/implement-orchestration-rule.md) - add flow run state transition rules
55- [update database schema](.claude/commands/update-database-schema.md) - add migrations for schema changes
56
57### architecture
58
59```
60src/
61├── api/ # http handlers (flow_runs.zig, deployments.zig, etc.)
62├── db/ # database layer (backend.zig, migrations/, entity modules)
63├── orchestration/ # state transition rules and transforms
64├── broker/ # message broker (memory + redis backends)
65├── services/ # background workers (scheduler, event_persister)
66└── main.zig
67```
68
69### testing
70
71- unit tests: `zig build test`
72- functional tests: `just test` (requires running server)
73- both: `zig build test && just test`
74
75### reference
76
77- python prefect source: `~/github.com/prefecthq/prefect`
78- zig 0.15 notes: `~/tangled.sh/@zzstoatzz.io/notes/languages/ziglang/0.15/`
79
80</details>