# prefect-server

zig implementation of [prefect server](https://github.com/prefecthq/prefect) - single binary, ~3x faster, ~20x less memory.

supports sqlite/postgres for storage and memory/redis for messaging. see [ROADMAP.md](ROADMAP.md) for implementation status.

## usage

```bash
just dev           # build and run with debug logging
just test          # run functional tests (requires running server)
just bench-compare # benchmark zig vs python (throughput, latency, memory)
just docker-test   # build and test in docker
```

requires [zig 0.15](https://ziglang.org/) and [just](https://github.com/casey/just). run `just --list` for all commands.

## testing

**functional tests** (`scripts/test-api-sequence`) - verify API correctness by exercising all endpoints. includes scheduler integration tests with intentional delays.

**performance benchmark** (`scripts/benchmark`) - measure throughput (requests/second), latency percentiles (p50/p95/p99), and memory usage.

```bash
just bench         # benchmark zig server
just bench-compare # compare zig vs python
just bench-matrix  # test all db × broker combinations
```

## docker

published to [atcr.io](https://atcr.io) (AT Protocol container registry):

```bash
docker pull atcr.io/zzstoatzz.io/prefect-server:latest
docker run -p 4200:4200 atcr.io/zzstoatzz.io/prefect-server:latest
```

to publish:
```bash
just docker-publish           # push :latest
just docker-publish v0.1.0    # push specific tag
```

## configuration

see [`docs/`](docs/) for configuration details.

<details>
<summary>contributing</summary>

### playbooks

- [implement orchestration rule](.claude/commands/implement-orchestration-rule.md) - add flow run state transition rules
- [update database schema](.claude/commands/update-database-schema.md) - add migrations for schema changes

### architecture

```
src/
├── api/           # http handlers (flow_runs.zig, deployments.zig, etc.)
├── db/            # database layer (backend.zig, migrations/, entity modules)
├── orchestration/ # state transition rules and transforms
├── broker/        # message broker (memory + redis backends)
├── services/      # background workers (scheduler, event_persister)
└── main.zig
```

### testing

- unit tests: `zig build test`
- functional tests: `just test` (requires running server)
- both: `zig build test && just test`

### reference

- python prefect source: `~/github.com/prefecthq/prefect`
- zig 0.15 notes: `~/tangled.sh/@zzstoatzz.io/notes/languages/ziglang/0.15/`

</details>