Skip to content

Add zeemo-tuned — first Zig tuned-category entry#739

Draft
skylightis666 wants to merge 4 commits into
MDA2AV:mainfrom
skylightis666:zeemo-tuned
Draft

Add zeemo-tuned — first Zig tuned-category entry#739
skylightis666 wants to merge 4 commits into
MDA2AV:mainfrom
skylightis666:zeemo-tuned

Conversation

@skylightis666
Copy link
Copy Markdown
Contributor

Description

First Zig entry in the tuned category. Built on the zeemo Zig HTTP library — same author and same core io_uring transport as the existing zeemo (engine) entry, but reworked as a proper framework:

  • Public Zig API (Server.init/.get/.post/.run, Request, Response, comptime JSON serializer, static file mount)
  • JSON responses are serialized per request from native Zig structs via the library's comptime-reflection serializer. No pre-rendered fragments, no per-(count,m) response caching — strictly the runtime work that the json profile is designed to measure.
  • Static files are loaded into memory at startup and the full HTTP/1.1 response is pre-baked per (file, encoding) variant — allowed for tuned per the static profile rules ("May cache files in memory at startup, use memory-mapped files, pre-rendered response headers, or any caching strategy. May serve pre-compressed files (.gz, .br) from disk via any mechanism.").
  • The framework dependency is a real, published library: https://github.com/skylightis666/zeemo (pinned in build.zig.zon via zig fetch --save).

Subscribed profiles

  • baselineGET/POST /baseline11?a=…&b=…
  • pipelinedGET /pipeline
  • limited-conn — same /baseline11 endpoint, connection-churn pattern
  • jsonGET /json/{count}?m=… with per-request struct walk
  • staticGET /static/* with .br/.gz variant selection by Accept-Encoding

Local validation

Full scripts/validate.sh zeemo-tuned suite passes — 22 checks, 0 failures (baseline GET/POST/chunked + Content-Type, anti-cheat random inputs, 4 TCP-fragmentation cases, pipelined + Content-Type, JSON shape for 4 counts × multipliers + Content-Type, static Content-Type for css/js/json, 20 file sizes uncompressed, 15 compression variants, 404 for missing).

How tuned differs from the existing engine entry

  • Goes through a framework HTTP server (zeemo.Server), not raw socket dispatch
  • JSON serialized per request from live struct data (no pre-rendered prefixes)
  • Same io_uring transport, multishot accept, fork-workers with SO_REUSEPORT, parser

PR Commands — comment to trigger (requires collaborator approval):

Command Description
/benchmark -f zeemo-tuned Preview run
/benchmark -f zeemo-tuned --save Run and save results

@skylightis666 skylightis666 marked this pull request as draft May 19, 2026 12:55
@skylightis666
Copy link
Copy Markdown
Contributor Author

/benchmark -f zeemo-tuned

@skylightis666 skylightis666 marked this pull request as ready for review May 19, 2026 12:56
@github-actions
Copy link
Copy Markdown
Contributor

👋 /benchmark request received. A collaborator will review and approve the run.

1 similar comment
@github-actions
Copy link
Copy Markdown
Contributor

👋 /benchmark request received. A collaborator will review and approve the run.

@github-actions
Copy link
Copy Markdown
Contributor

Benchmark Results

Framework: zeemo-tuned | Test: all tests

Test Conn RPS CPU Mem Δ RPS Δ Mem
baseline 512 4,058,741 6369.3% 69MiB NEW NEW
baseline 4096 4,304,474 6275.4% 140MiB NEW NEW
pipelined 512 40,627,670 6707.0% 69MiB NEW NEW
pipelined 4096 42,436,528 6540.8% 133MiB NEW NEW
limited-conn 512 2,253,588 5926.3% 77MiB NEW NEW
limited-conn 4096 2,644,597 6195.0% 154MiB NEW NEW
json 4096 1,646,153 6489.5% 203MiB NEW NEW
static 1024 1,487,134 4927.6% 83MiB NEW NEW
static 4096 1,387,100 4923.0% 147MiB NEW NEW
static 6800 1,270,012 5152.3% 202MiB NEW NEW
Full log
gcannon v0.5.3
  Target:    localhost:8080/
  Threads:   64
  Conns:     4096 (64/thread)
  Pipeline:  1
  Req/conn:  25
  Templates: 7
  Expected:  200
  Duration:  5s


  Thread Stats   Avg      p50      p90      p99    p99.9
    Latency   2.00ms   1.87ms   3.89ms   4.65ms   5.17ms

  8201998 requests in 5.00s, 8199236 responses
  Throughput: 1.64M req/s
  Bandwidth:  5.49GB/s
  Status codes: 2xx=8199236, 3xx=0, 4xx=0, 5xx=0
  Latency samples: 8198882 / 8199236 responses (100.0%)
  Reconnects: 329202
  Per-template: 1165932,1169138,1172061,1175377,1175901,1172841,1167632
  Per-template-ok: 1165932,1169138,1172061,1175377,1175901,1172841,1167632
[info] CPU 6484.8% | Mem 212MiB

=== Best: 1646153 req/s (CPU: 6489.5%, Mem: 203MiB) ===
[info] input BW: 78.49MB/s (avg template: 50 bytes)
[info] saved results/json/4096/zeemo-tuned.json
httparena-bench-zeemo-tuned
httparena-bench-zeemo-tuned
[info] skip: zeemo-tuned does not subscribe to json-comp
[info] skip: zeemo-tuned does not subscribe to json-tls
[info] skip: zeemo-tuned does not subscribe to upload
[info] skip: zeemo-tuned does not subscribe to api-4
[info] skip: zeemo-tuned does not subscribe to api-16

==============================================
=== zeemo-tuned / static / 1024c (tool=wrk) ===
==============================================
[info] waiting for server...
[info] server ready

[run 1/3]
Running 5s test @ http://localhost:8080
  64 threads and 1024 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   398.03us  139.41us   6.66ms   75.69%
    Req/Sec    23.38k     0.99k   36.01k    97.79%
  7584188 requests in 5.10s, 115.55GB read
Requests/sec: 1487134.47
Transfer/sec:     22.66GB
[info] CPU 4927.6% | Mem 83MiB

[run 2/3]
Running 5s test @ http://localhost:8080
  64 threads and 1024 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   398.92us  137.33us   5.36ms   76.18%
    Req/Sec    23.25k     0.85k   33.75k    97.88%
  7546137 requests in 5.10s, 114.97GB read
Requests/sec: 1479689.54
Transfer/sec:     22.54GB
[info] CPU 4967.1% | Mem 83MiB

[run 3/3]
Running 5s test @ http://localhost:8080
  64 threads and 1024 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   400.07us  138.54us   3.71ms   75.87%
    Req/Sec    23.23k     0.93k   33.98k    97.82%
  7535575 requests in 5.10s, 114.81GB read
Requests/sec: 1477629.78
Transfer/sec:     22.51GB
[info] CPU 4890.5% | Mem 83MiB

=== Best: 1487134 req/s (CPU: 4927.6%, Mem: 83MiB) ===
[info] saved results/static/1024/zeemo-tuned.json
httparena-bench-zeemo-tuned
httparena-bench-zeemo-tuned

==============================================
=== zeemo-tuned / static / 4096c (tool=wrk) ===
==============================================
[info] waiting for server...
[info] server ready

[run 1/3]
Running 5s test @ http://localhost:8080
  64 threads and 4096 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.54ms  348.53us   5.64ms   92.61%
    Req/Sec    21.85k     1.30k   43.54k    97.87%
  7061990 requests in 5.10s, 107.59GB read
Requests/sec: 1384537.51
Transfer/sec:     21.09GB
[info] CPU 4946.3% | Mem 146MiB

[run 2/3]
Running 5s test @ http://localhost:8080
  64 threads and 4096 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.55ms  374.48us   9.10ms   91.91%
    Req/Sec    21.80k     1.38k   43.27k    97.84%
  7043369 requests in 5.10s, 107.31GB read
Requests/sec: 1380902.47
Transfer/sec:     21.04GB
[info] CPU 4979.8% | Mem 148MiB

[run 3/3]
Running 5s test @ http://localhost:8080
  64 threads and 4096 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     1.56ms  410.15us   6.99ms   90.43%
    Req/Sec    21.86k     1.40k   41.30k    97.87%
  7074603 requests in 5.10s, 107.78GB read
Requests/sec: 1387100.90
Transfer/sec:     21.13GB
[info] CPU 4923.0% | Mem 147MiB

=== Best: 1387100 req/s (CPU: 4923.0%, Mem: 147MiB) ===
[info] saved results/static/4096/zeemo-tuned.json
httparena-bench-zeemo-tuned
httparena-bench-zeemo-tuned

==============================================
=== zeemo-tuned / static / 6800c (tool=wrk) ===
==============================================
[info] waiting for server...
[info] server ready

[run 1/3]
Running 5s test @ http://localhost:8080
  64 threads and 6800 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     2.77ms  618.04us   8.81ms   92.81%
    Req/Sec    19.96k     1.38k   40.07k    97.71%
  6479062 requests in 5.10s, 98.71GB read
Requests/sec: 1270012.60
Transfer/sec:     19.35GB
[info] CPU 5152.3% | Mem 202MiB

[run 2/3]
Running 5s test @ http://localhost:8080
  64 threads and 6800 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     2.78ms  598.74us  18.77ms   92.87%
    Req/Sec    19.87k     1.41k   36.91k    97.55%
  6436429 requests in 5.10s, 98.06GB read
Requests/sec: 1261822.47
Transfer/sec:     19.22GB
[info] CPU 5240.9% | Mem 204MiB

[run 3/3]
Running 5s test @ http://localhost:8080
  64 threads and 6800 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency     2.78ms  574.33us  12.30ms   93.57%
    Req/Sec    19.77k     1.39k   43.23k    97.77%
  6416941 requests in 5.10s, 97.76GB read
Requests/sec: 1259077.68
Transfer/sec:     19.18GB
[info] CPU 5131.5% | Mem 205MiB

=== Best: 1270012 req/s (CPU: 5152.3%, Mem: 202MiB) ===
[info] saved results/static/6800/zeemo-tuned.json
httparena-bench-zeemo-tuned
httparena-bench-zeemo-tuned
[info] skip: zeemo-tuned does not subscribe to async-db
[info] skip: zeemo-tuned does not subscribe to crud
[info] skip: zeemo-tuned does not subscribe to fortunes
[info] skip: zeemo-tuned does not subscribe to baseline-h2
[info] skip: zeemo-tuned does not subscribe to static-h2
[info] skip: zeemo-tuned does not subscribe to baseline-h2c
[info] skip: zeemo-tuned does not subscribe to json-h2c
[info] skip: zeemo-tuned does not subscribe to baseline-h3
[info] skip: zeemo-tuned does not subscribe to static-h3
[info] skip: zeemo-tuned does not subscribe to gateway-64
[info] skip: zeemo-tuned does not subscribe to gateway-h3
[info] skip: zeemo-tuned does not subscribe to production-stack
[info] skip: zeemo-tuned does not subscribe to unary-grpc
[info] skip: zeemo-tuned does not subscribe to unary-grpc-tls
[info] skip: zeemo-tuned does not subscribe to stream-grpc
[info] skip: zeemo-tuned does not subscribe to stream-grpc-tls
[info] skip: zeemo-tuned does not subscribe to echo-ws
[info] skip: zeemo-tuned does not subscribe to echo-ws-pipeline
[info] rebuilding site/data/*.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/frameworks.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/baseline-4096.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/baseline-512.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/json-4096.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/limited-conn-4096.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/limited-conn-512.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/pipelined-4096.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/pipelined-512.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/static-1024.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/static-4096.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/static-6800.json
[updated] /home/diogo/actions-runner/_work/HttpArena/HttpArena/site/data/current.json
[info] done
[info] restoring loopback MTU to 65536
[info] restoring CPU governor → powersave

@MDA2AV
Copy link
Copy Markdown
Owner

MDA2AV commented May 19, 2026

Tuned or Production entries must be actual frameworks, this is still very early work, it needs more than just routing handlers to the engine. At least having some proper documentation on how to use it to build an API. Rule of thumb is "would I use this to build something I can deploy to prod and be confident about it?"

@skylightis666 skylightis666 marked this pull request as draft May 19, 2026 13:58
@skylightis666
Copy link
Copy Markdown
Contributor Author

Fully fair — agree it's early for "framework" status. Converting back to draft and keeping it open as the tracking PR while I bring zeemo up to that bar. Plan:

Framework features

  • Middleware pipeline (server.use(...), ordered, with req.next()-style chaining)
  • Error handling — server.onError(fn), structured Response.problemJson(rfc7807), default 4xx/5xx pages
  • Body parsing helpers — JSON-in, form, multipart
  • Graceful shutdown on SIGTERM
  • Logging interface — pluggable sink, request-scoped fields
  • Request context / locals — handler-local typed state

Additional profile coverage

  • upload — streaming body API (currently capped at small bodies)
  • json-comp — gzip + brotli via @cImport, honoring Accept-Encoding
  • json-tls — TLS server through BoringSSL bindings
  • crud — Postgres client + cache-aside read pattern (covers the most "real-world" workload)

Documentation

  • Getting started tutorial (write your first API end-to-end)
  • API reference for every public symbol
  • Architecture overview (io_uring loop, fork-workers, lifecycle)
  • Production deployment guide (Dockerfile, systemd, tuning knobs and their tradeoffs)
  • Cookbook (auth, validation, file upload, REST CRUD patterns)

Real example

  • Partial FHIR (HL7) Patient resource API — search by name/birthdate, create/update/delete, content negotiation, structured error responses. FHIR is what you'd ship in a healthcare backend, so it forces the framework through realistic JSON-in, validation, search params, paginated responses, and proper error codes.

Keeping PR #739 in draft until all of those land so we don't lose the benchmark-runner association. Will ping when ready for a fresh look.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants