Bump zig version 0.16 support

.github/workflows/ci.yml

@@ -12,34 +12,62 @@ jobs:
   unit_test_and_coverage:
     runs-on: ubuntu-latest
     container:
-      image: imng/zero-kcov:0.1
+      image: imng/zero-kcov:0.3.4
       options: --security-opt seccomp=unconfined
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
           token: ${{ secrets.GH_TOKEN }}
 
-      - name: Set Zig 0.15.2 as active
+      - name: Set Zig 0.16.0 as active
         run: |
           zig version
           kcov --version
           more /etc/os-release
 
       - name: Run tests with coverage
         run: |
+          ls -alth /usr/local/lib
+          mkdir -p ~/.cache/zig/tmp
           zig build test -Dcoverage --summary all
 
+      - name: Run integration tests (real database)
+        env:
+          DB_HOST: postgres
+          DB_PORT: "5432"
+          DB_USER: postgres
+          DB_PASSWORD: postgres
+          DB_NAME: postgres
+        run: |
+          mkdir -p ~/.cache/zig/tmp
+          zig build test-integration --summary all
+
       - name: Extract coverage
         id: coverage
         run: |
           if [ -f zig-out/kcov/test/coverage.json ]; then
             COVERAGE=$(jq -r '.percent_covered' zig-out/kcov/test/coverage.json)
             echo "coverage=$COVERAGE" >> $GITHUB_OUTPUT
-            echo "Coverage for Zig 0.15.2: $COVERAGE%"
+            echo "Coverage for Zig 0.16.0: $COVERAGE%"
           else
             echo "coverage=0" >> $GITHUB_OUTPUT
-            echo "Coverage for Zig 0.15.2: 0%"
+            echo "Coverage for Zig 0.16.0: 0%"
           fi
 
       - name: Update README with coverage
@@ -72,4 +100,89 @@ jobs:
         uses: actions/upload-artifact@v4
         with:
           name: zero_coverage
-          path: zig-out/kcov/test/coverage.json
+          path: zig-out/kcov/test/coverage.json
+
+  bench_regression:
+    runs-on: ubuntu-latest
+    container:
+      image: imng/zero-kcov:0.3.4
+      options: --security-opt seccomp=unconfined
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+
+      - name: Set Zig 0.16.0 as active
+        run: zig version
+
+      - name: Build bench harness
+        run: |
+          ls -alth /usr/local/lib
+          mkdir -p ~/.cache/zig/tmp
+          zig build bench --summary all
+
+      - name: Run bench suite
+        run: |
+          mkdir -p ~/.cache/zig/tmp
+          ./zig-out/bin/bench --suite --json --duration=2 --levels=1,25,100
+
+      - name: Compare against baseline
+        run: |
+          set -uo pipefail
+          jq empty zig-out/bench/report.json 2>/dev/null || { echo "no report.json produced"; exit 1; }
+          if [ ! -f bench/baseline.json ]; then
+            echo "No baseline present; initializing baseline (skip regression)."
+            cp zig-out/bench/report.json bench/baseline.json
+            exit 0
+          fi
+          jq empty bench/baseline.json 2>/dev/null || { echo "baseline corrupt"; exit 1; }
+
+          fails=0
+          while IFS= read -r row; do
+            name=$(echo "$row" | jq -r '.name')
+            peak=$(echo "$row" | jq -r '.peak_rss_mib')
+            leak=$(echo "$row" | jq -r '.leak')
+            if [ "$leak" = "true" ]; then
+              echo "LEAK detected in scenario: $name"
+              fails=$((fails + 1))
+              continue
+            fi
+            bpeak=$(jq -r --arg n "$name" '.scenarios[] | select(.name==$n) | .peak_rss_mib' bench/baseline.json)
+            if [ -n "$bpeak" ] && [ "$bpeak" != "null" ]; then
+              rel=$(awk -v p="$peak" -v b="$bpeak" 'BEGIN{printf "%.4f", (p-b)/b}')
+              absmb=$(awk -v p="$peak" -v b="$bpeak" 'BEGIN{printf "%.4f", (p-b)}')
+              echo "$name: baseline=${bpeak}MiB now=${peak}MiB (rel +${rel}, abs +${absmb}MiB)"
+              rel_bad=$(awk -v g="$rel" 'BEGIN{print (g>0.15)?1:0}')
+              abs_bad=$(awk -v a="$absmb" 'BEGIN{print (a>8)?1:0}')
+              if [ "$rel_bad" = "1" ] && [ "$abs_bad" = "1" ]; then
+                echo "REGRESSION: $name peak RSS grew ${rel}% (>15%) and ${absmb}MiB (>8MiB)"
+                fails=$((fails + 1))
+              fi
+            fi
+          done < <(jq -c '.scenarios[]' zig-out/bench/report.json)
+
+          if [ "$fails" -gt 0 ]; then
+            echo "Bench regression: $fails scenario(s) failed."
+            exit 1
+          fi
+          echo "No bench regression."
+
+      - name: Upload bench report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: zero_bench_report
+          path: zig-out/bench/report.json
+
+      - name: Update baseline on merge
+        if: github.event.pull_request.merged == true
+        run: |
+          cp zig-out/bench/report.json bench/baseline.json
+          git config --global --add safe.directory /__w/zero/zero
+          git config --global user.name "im-ng"
+          git config --global user.email "2039564+im-ng@users.noreply.github.com"
+          git add bench/baseline.json
+          git commit -m "chore: update bench baseline" || echo "No changes to commit"
+          git push

AGENTS.md

@@ -6,11 +6,17 @@
 - Requires `librdkafka-dev` (`apt install librdkafka-dev` / `brew install librdkafka`)
 - On macOS, `build.zig` hardcodes `/usr/local/Cellar/librdkafka/2.13.0` include/lib paths
 - **Always `rm -rf .zig-cache zig-out zig-pkg/` before switching Zig versions** — stale cache causes build failures and runtime corruption
+- This environment builds and tests with **Zig 0.16.0** (`/usr/local/zig-x86_64-linux-0.16.0/zig`); the deps vendored in `zig-pkg/` compile under it.
 
 ## Commands
 
 ```bash
-zig build test              # run all unit tests
+zig build test              # unit tests (52; 7 known leaks, assertions pass)
+zig build test-integration  # real SQLite :memory: + Postgres integration tests (21)
+zig build test-validation   # Context memory-release + timestampz invalid-free (3)
+zig build -Dcoverage test   # kcov coverage report -> zig-out/kcov/
+zig build bench             # build the HTTP load/benchmark harness
+./zig-out/bin/bench         # run the harness (see BENCHMARK.md)
 zig build --release=fast    # release build
 make clean                  # remove .zig-cache, zig-out, and all example build artifacts
 ```
@@ -26,6 +32,48 @@ make clean                  # remove .zig-cache, zig-out, and all example build
 - Zig 0.15.2 uses `.@"enum".fields` not `.Enum.fields` for `@typeInfo` enum field access
 - `utils.combine`/`toString`/`toStringFromInt` allocate 256-byte buffers via `bufPrint` and return subslices — intentionally don't free; use `std.heap.page_allocator` in their tests
 - `process.setValue`, `host.setValue`, `validateBasicAuth`, `validateAPIKeyAuth` allocate via `dupe`/allocator and don't return owned memory — test with `std.testing.allocator` and accept leak warnings
+- `utils.timestampz`/`sqlTimestampz`/`DTtimestampz` return **caller-owned** buffers from `std.fmt.allocPrint` — the caller must `allocator.free` them. A prior `bufPrint` version returned a stack-subslice that caused an invalid free; fixed and covered by `test-validation`.
+
+### Test layers
+
+- `zig build test` — unit tests (52; 7 known leaks, assertions pass)
+- `zig build test-integration` — real `SQLite :memory:` + Postgres, 21 tests (`src/tests_integration.zig`)
+- `zig build test-validation` — Context request/cron/pubsub release + `timestampz` invalid-free fix, 3 tests (`src/tests_validation.zig`, `src/validation/memory_test.zig`)
+- `zig build -Dcoverage test` — kcov over `src/` → `zig-out/kcov/` (HTML); measured **87.91%**
+
+### HTTP load / benchmark harness
+
+- `zig build bench` builds `./zig-out/bin/bench`; it starts the real `zero.App` and drives a concurrency ramp, reporting throughput, latency percentiles (fixed-bucket histogram, bounded memory), error count, and per-level RSS (`readRss()` samples `/proc/self/status` VmRSS — 0.0 off-Linux). A `dRss` that keeps climbing (or `peak RSS` that never plateaus) is the leak signal.
+- Uses the `zul` HTTP client; each worker times requests with `clock_gettime(CLOCK_MONOTONIC)` (no `std.time.nanoTimestamp` in 0.16.0).
+- The framework's liveness endpoint is **`/.well-known/health`** (not `/health`) — hitting `/health` returns 404 by design.
+- Full usage, flags, and sample results in `BENCHMARK.md`.
+- Flags: `--path=<url>` (default `/.well-known/health`, single scenario), `--suite` / `--target=all` (runs every category below), `--target=<csv>` (subset of `health,http,sql,nosql,timeseries,search,proto,graphql,filestore`, comma-separated), `--host=<host>` `--port=<port>` (benchmark an external zero server instead of booting the embedded app), `--vusers=<N>` (ramp `1,N/4,N/2,N`), `--duration=<s>` per level, `--levels=1,25,100`, `--json` (writes `zig-out/bench/report.json` with per-scenario `{name, peak_rss_mib, drss_kib, leak}`), `--debug-alloc` (runs the server on a `DebugAllocator` and reports leaks at exit — deep but noisy, flags all unfreed startup state too), `--server` (serves the same routes, listens on `HTTP_PORT` default 8080, blocks until Ctrl-C so an external load generator like k6 can drive them).
+- The `--suite` (or `--target=all`) drives the `zero-basic` workload at clean paths (registered in `src/bench/main.zig`), grouped by category: `health` (`/.well-known/health`, default JSON + `health-json`/`health-html` content-negotiation variants), `http` (`/`, `/text`, `/json`, `/keys`, `/db`), `sql` (`/duckdb/query` in-memory read path), `proto` (`GET /proto` + `POST /proto` inline `TestMsg` `bindProto`+encode round-trip), `graphql` (`GET /graphql?query=…` + `POST /graphql` pure `Query` resolver), `filestore` (`GET /filestore?key=bench-seed` + `POST /filestore` local `FileStore` save→get→delete; each request uses a unique key so concurrent workers don't race). Gated categories `nosql`/`timeseries`/`search` run only when their backend env var is set.
+- The POST `/proto` handler uses an inline `TestMsg{ value: []const u8 }` with `protobuf` field descriptors (`pub usingnamespace protobuf;` + `pub const NAME`/`fd`/encode/decode) — no generated proto. The seed file `./data/bench/bench-seed` is written at startup so `filestore-get` has data.
+- The `/.well-known/health` endpoint does content negotiation: `Accept: text/html` → HTML status page (`content_type = .HTML`), otherwise JSON (default, backward compatible). The handler set lives in `src/bench/main.zig` (`indexHandler`, `textHandler`, `jsonHandler`, `keysHandler`, `dbHandler`, `protoGetHandler`, `protoPostHandler`, `filestoreGetHandler`, `filestorePostHandler`, `Query`/resolver).
+- CI regression: `.github/workflows/ci.yml` has a `bench_regression` job (Linux `imng/zero-kcov:0.3` container, offline) that runs `./zig-out/bin/bench --suite --json --duration=2 --levels=1,25,100` and diffs `zig-out/bench/report.json` against the committed `bench/baseline.json` (14 scenarios); it fails if any scenario's `peak_rss_mib` grew >15% relative AND >8 MiB absolute, or if `leak:true` appears. On merge to `main` it refreshes `bench/baseline.json` (mirrors the coverage step via `GH_TOKEN`).
+- **k6 local baseline**: `bench/k6/baseline.js` is a k6 script that drives the same endpoints (health / health-json / health-html / index / text / json / keys / db / proto-get / graphql-get / filestore-get / proto / graphql / filestore) for a formatted, exportable report (console table + `bench/k6/report.json` + `bench/k6/report.html`). Run the server locally with `./zig-out/bin/bench --server` (listens on `HTTP_PORT`, default 8080, blocks until Ctrl-C), then `k6 run bench/k6/baseline.js` (tune via `BASE_URL`/`VUS`/`DURATION`). The k6 script is the nicer-format local counterpart to the Zig harness; CI still uses the Zig binary for RSS/leak regression.
+
+### Outbound service-client auth + circuit breaker
+
+`app.addHttpService(name, url, opts)` registers a `zero.Client` (`src/service/client.zig`)
+that auto-attaches outbound auth to every `get/post/put/delete` and guards the
+downstream with a circuit breaker.
+
+- `opts: zero.client.ServiceOptions { auth, circuitBreaker }` — explicit values
+  **override** `SERVICE_<NAME>_*` env defaults resolved by `zero.client.fromEnv`
+  (service name uppercased, non-alphanumeric → `_`).
+- Auth modes mirror the inbound ones: `Basic` → `Authorization: Basic <base64(user:pass)>`,
+  `ApiKey` → `x-api-key: <key>`, `OAuth` → `Authorization: Bearer <jwt>`
+  (client_credentials grant; token cached + refreshed before expiry via
+  `src/service/outbound_auth.zig`).
+- Circuit breaker (`src/service/circuit_breaker.zig`): `closed → open → half_open`,
+  configurable `failure_threshold` (5), `cooldown_ms` (30000), `half_open_trials` (1);
+  `error.CircuitOpen`/`ClientError.CircuitOpen` returned while open.
+- Env keys: `SERVICE_<NAME>_AUTH_MODE` (`Basic`/`ApiKey`/`OAuth`),
+  `_API_KEY`, `_BASIC_USER`/`_BASIC_PASS`, `_OAUTH_TOKEN_URL`/`_OAUTH_CLIENT_ID`/
+  `_OAUTH_CLIENT_SECRET`/`_OAUTH_SCOPE`/`_OAUTH_AUDIENCE`, and
+  `_CB_FAILURE_THRESHOLD`/`_CB_COOLDOWN_MS`/`_CB_HALF_OPEN_TRIALS`.
 
 ## Architecture
 
@@ -81,15 +129,16 @@ These are used consistently across the codebase and must be referenced as-is:
 - The `kafka` build option in `build.zig` is commented out; rdkafka is always linked
 - Auth modes: `Basic`, `APIKey`, `OAuth` — configured via `AUTH_MODE` env var
 - `src/cronz/scheduler.zig` and `src/mw/authProvider.zig` use `@import("../zero.zig")` (relative path), not `@import("zero")` — the module name form conflicts in test builds
+- `zul.http.Request.header(name, value)` returns an error union — always call it as `try req.header(...)` (the outbound client in `src/service/client.zig` does this)
 
 ## Zig version compatibility
 
 | Version | Compiles | Tests | Runtime | Notes |
 |---|---|---|---|---|
 | 0.15.1 | Yes | 52/52 (7 leaks) | Full | Production baseline |
 | 0.15.2 | Yes | 52/52 (7 leaks) | **Broken** | No log output, no HTTP server — `std.fs.File.stdout()` I/O change in logger.zig breaks httpz |
-| 0.16.0 | No | N/A | N/A | Build system API changed; dependency build.zig files fail first |
+| 0.16.0 | Yes | 52+21+3 | Yes | Works in this env with vendored deps; benchmark HTTP server binds and serves |
 
 - See `recommendation.md` for full analysis and 0.16.0 migration plan
 - **0.15.2 runtime issue**: `src/logger.zig` uses `std.fs.File.stdout().writer(&stdout_buffer)` pattern which silently fails under 0.15.2 — stdout fd becomes a socket, HTTP server never binds
-- **0.16.0 compilation blocked** by 6 dependency `build.zig` files using removed `Compile.linkLibC()` / `Compile.linkSystemLibrary()` / `Compile.addLibraryPath()` (moved to `Module` in 0.16.0)
+- **0.16.0 now works here**: the 6 dependency `build.zig` files were updated for the `Module`-based link API and the deps are vendored in `zig-pkg/`, so `zig build {test,test-integration,test-validation,bench}` all pass under 0.16.0.

Dockerfiles/alpine.Dockerfile

@@ -20,22 +20,22 @@ RUN apk add --no-cache \
     binutils-dev curl-dev elfutils-dev
 
 # Create working directories
-RUN mkdir -p /opt/zig-0.15.1 /opt/zig-0.15.2 /opt/zig-0.16.0 /opt/kcov
+RUN mkdir -p /opt/zig-0.15.1 /opt/zig-0.15.2 /opt/zig-0.16.0 /opt/kcov /opt/libduckdb
 
 # Install Zig 0.15.1
 # RUN wget -q https://ziglang.org/download/0.15.1/zig-x86_64-linux-0.15.1.tar.xz \
 #     && tar -xJf zig-x86_64-linux-0.15.1.tar.xz -C /opt/zig-0.15.1 --strip-components=1 \
 #     && rm zig-x86_64-linux-0.15.1.tar.xz
 
 # Install Zig 0.15.2
-RUN wget -q https://ziglang.org/download/0.15.2/zig-x86_64-linux-0.15.2.tar.xz \
-    && tar -xJf zig-x86_64-linux-0.15.2.tar.xz -C /opt/zig-0.15.2 --strip-components=1 \
-    && rm zig-x86_64-linux-0.15.2.tar.xz
+# RUN wget -q https://ziglang.org/download/0.15.2/zig-x86_64-linux-0.15.2.tar.xz \
+#     && tar -xJf zig-x86_64-linux-0.15.2.tar.xz -C /opt/zig-0.15.2 --strip-components=1 \
+#     && rm zig-x86_64-linux-0.15.2.tar.xz
 
 # Install Zig 0.16.0
-# RUN wget -q https://ziglang.org/download/0.16.0/zig-x86_64-linux-0.16.0.tar.xz \
-#     && tar -xJf zig-x86_64-linux-0.16.0.tar.xz -C /opt/zig-0.16.0 --strip-components=1 \
-#     && rm zig-x86_64-linux-0.16.0.tar.xz
+RUN wget -q https://ziglang.org/download/0.16.0/zig-x86_64-linux-0.16.0.tar.xz \
+    && tar -xJf zig-x86_64-linux-0.16.0.tar.xz -C /opt/zig-0.16.0 --strip-components=1 \
+    && rm zig-x86_64-linux-0.16.0.tar.xz
 
 # Install kcov from source
 RUN wget -q https://github.com/SimonKagstrom/kcov/archive/refs/heads/master.tar.gz \
@@ -49,39 +49,54 @@ RUN wget -q https://github.com/SimonKagstrom/kcov/archive/refs/heads/master.tar.
     && make install \
     && cd / && rm -rf kcov-master master.tar.gz
 
+RUN wget -q https://install.duckdb.org/v1.5.5/libduckdb-linux-amd64.zip \
+    && unzip libduckdb-linux-amd64.zip -d /opt/libduckdb \
+    && cd / && rm -rf libduckdb-linux-amd64.zip
+
 FROM alpine:latest 
 LABEL maintainer="im-ng"
 LABEL description="Multi-version Zig CI container with kcov coverage support"
-LABEL version="0.1"
+LABEL version="0.3.4"
 
 # Update dependencies for zig, zero, kcov
 RUN apk add --no-cache \
     git \
     bash \
     jq \
+    openssh \
+    libssh libssh2 libssh2-dev \
+    musl-dev libc6-compat \
     ca-certificates \
     librdkafka librdkafka-dev \
     binutils-dev curl-dev elfutils-dev
 
 # Create working directories
-RUN mkdir -p /usr/local/zig-0.15.2 /app
+# RUN mkdir -p /usr/local/zig-0.15.2 /app
+RUN mkdir -p /usr/local/zig-0.16.0 /app /app/libs
 
 COPY --from=builder /opt/kcov* /usr/
-COPY --from=builder /opt/zig-0.15.2 /usr/local/zig-0.15.2/
+COPY --from=builder /opt/zig-0.16.0 /usr/local/zig-0.16.0/
 # RUN ls -alt /usr/local/zig-0.15.2/
 # RUN ls -alth
 
+# COPY ALPINE SPECIFIC DUCKDB LIBRARY FOR ZERO COMPILATION
+COPY /libs/duckdb-alpine.h /usr/local/lib/duckdb.h
+COPY /libs/libduckdb-alpine.so /usr/local/lib/libduckdb.so
+COPY /libs/libduckdb-alpine.so /usr/local/lib/libduckdb.so.1.5
+
 # Set environment variables for Zig versions
 # ENV ZIG151=/opt/zig/zig-0.15.1
 # ENV ZIG152=/opt/zig/zig-0.15.2
 # ENV ZIG160=/opt/zig/zig-0.16.0
-ENV ZIG=/usr/local/zig-0.15.2
+ENV ZIG=/usr/local/zig-0.16.0
 
-RUN ln -s /usr/local/zig-0.15.2/zig /usr/local/bin/zig
+RUN ln -s /usr/local/zig-0.16.0/zig /usr/local/bin/zig
 # RUN chmod -R 777 /usr/local/zig-0.15.2
 # ENV PATH="${ZIG151}:${ZIG152}:${ZIG160}:${PATH}"
 # ENV PATH="${ZIG}:${PATH}"
 
 WORKDIR /app
+RUN ls -alth /usr/local/lib/
+RUN tree -a
 
 CMD ["/bin/bash"]

Dockerfiles/baseImage.Dockerfile

@@ -0,0 +1,30 @@
+FROM gitea.pi/ng/alpine:3.24 
+LABEL maintainer="im-ng"
+LABEL description="Base image to run zero framework apps"
+LABEL version="1.0.0"
+
+# COPY ALPINE SPECIFIC DUCKDB LIBRARY FOR ZERO COMPILATION
+COPY ../../libs/duckdb-alpine.h /usr/local/lib/duckdb.h
+COPY ../../libs/libduckdb-alpine.so /usr/local/lib/libduckdb.so
+COPY ../../libs/libduckdb-alpine.so /usr/local/lib/libduckdb.so.1.5
+
+WORKDIR /app
+
+RUN apk add --no-cache \
+    curl wget \
+    openssh \
+    libssh libssh2 libssh2-dev \
+    ca-certificates tzdata \
+    librdkafka librdkafka-dev
+
+RUN mkdir -p /app/data  && chmod 777 /app/data
+RUN mkdir -p /app/static  && chmod 777 /app/static
+
+COPY /data /app/data
+COPY /static /app/static
+COPY /zig-out/bin/basic /app/basic
+
+RUN ls -alth /usr/local/lib/
+
+EXPOSE 8080
+CMD ["./basic"]