Skip to content

MIGRATION.adoc

Latest commit

 

History

History
97 lines (77 loc) · 4.07 KB

MIGRATION.adoc

File metadata and controls

97 lines (77 loc) · 4.07 KB
Raw

Aerie — zig Removed (deprecated 2026-04-12, removed 2026-05-16)

Table of Contents

Status

The zig implementation in src/api/v/ is removed as of 2026-05-16 (deprecated 2026-04-12 following the estate-wide zig ban of 2026-04-10).

Per the day-1 estate architecture law (ABI = Idris2, FFI = Zig, API = Zig), the canonical implementation is the Zig gateway at src/api/zig/, built by the repository’s root build.zig (binary aerie-gateway). The Containerfile and stapeln.toml build that Zig binary; no V toolchain is fetched or used anywhere in this repo.

Note
 the src/api/rust/ crate and the earlier "Migration Target: Rust" text in this document are off-policy drift — Rust is not an API language in this estate. That crate is debt to be removed; it is NOT the migration target. Retained below only as a historical module-name reference.

Migration Target: Zig

Canonical: src/api/zig/ (Idris2 ABI in src/abi/, Zig FFI in ffi/zig/).

Module Map

V module (removed) Zig module

src/api/v/main.v

src/api/zig/main.zig

src/api/v/policy.v

src/api/zig/policy.zig

src/api/v/proof.v

src/api/zig/proof.zig

src/api/v/redis_client.v

src/api/zig/redis_client.zig

src/api/v/verb_governance.v

src/api/zig/verb_governance.zig

src/api/v/resolvers.v

src/api/zig/resolvers.zig

src/api/v/librespeed_client.v

src/api/zig/librespeed_client.zig

src/api/v/hyperglass_client.v

src/api/zig/hyperglass_client.zig

src/api/v/smokeping_client.v

src/api/zig/smokeping_client.zig

src/api/v/verisim_client.v

src/api/zig/verisim_client.zig

Build and Run

# From aerie/ root (Idris2 ABI + Zig API/FFI)
zig build -Doptimize=ReleaseSafe
zig build test

# Run (all mounts enabled, default ports)
./zig-out/bin/aerie-gateway

# Disable gRPC mount
ENABLE_GRPC=false ./zig-out/bin/aerie-gateway

# Custom ports
AERIE_PORT=8080 AERIE_GRPC_PORT=8081 ./zig-out/bin/aerie-gateway

# Configure backends
LIBRESPEED_URL=http://localhost:8888  \
HYPERGLASS_URL=http://localhost:8001  \
SMOKEPING_URL=http://localhost:8080   \
REDIS_URL=redis://localhost:6379      \
VERISIMDB_URL=http://localhost:8084   \
./zig-out/bin/aerie-gateway

Feature Parity

All V features are preserved:

  • Triple-mount: REST (port 4000) + GraphQL (port 4000) + gRPC Phase 1 (port 4001)

  • Mount flags: ENABLE_REST, ENABLE_GRAPHQL, ENABLE_GRPC (all default true)

  • Five resolvers: telemetry, route_forensics, smokeping, audit, temporal_audit

  • GraphQL dispatcher routes to the same resolver set (root field detection)

  • Phase 1 policy gate: validates X-Api-Key format (≥16 chars, alphanumeric + hyphen)

  • ProofEnvelope wraps all responses: SHA-256 result hash, policy hash, UUID v4 query_id, RFC 3339 issued_at, proof_type: "light", empty signature placeholder (Phase 2: Ed25519)

  • Redis hot cache: 30 s TTL, GET/SET per resolver, LPUSH/LTRIM audit list (≤10 000), XADD to aerie:audit:stream for Observatory

  • VerisimDB cold store: fire-and-forget POST /api/v1/events, as-of / range / history queries

  • Verb governance: explicit HTTP-verb allowlist per route prefix, stealth 404 (not 405), 1–8 ms random timing jitter on all responses

  • gRPC Phase 1: raw TCP, 4-byte big-endian length prefix + JSON body, per-connection goroutine

Next Steps

  1. Build and smoke-test: cargo build -p aerie-api && cargo test -p aerie-api

  2. Start backends (Redis, LibreSpeed, Hyperglass, SmokePing, VerisimDB) and run ./target/debug/aerie-api against the container network.

  3. Verify GET /health, GET /api/v1/telemetry, and POST /api/v1/graphql against a valid key.

  4. [DONE 2026-05-16] src/api/v/, v.mod, vpkg.json, and the V generated stubs (src/api/proto/aerie.pb.v, src/api/graphql/schema.gql.v) removed; Containerfile + stapeln.toml repointed to the Rust build.

  5. Wire aerie-api binary into compose.yml to replace the V container.