QUIC Transport for Zig

ZQUIC is a modular, high-performance QUIC transport stack built entirely in Zig 0.17.0-dev. It ships with a native async runtime, QUIC packet-protection helpers, explicit experimental post-quantum hooks via zcrypto, SSH/QUIC secret injection support, and HTTP/3, DoQ, VPN, and service layers tuned for Ghost workloads.

✅ Builds cleanly with Zig 0.17.0-dev on Linux/macOS/Windows and passes the dev/test.sh suite.

ZQUIC provides a modular networking foundation for Zig applications:

• 🧩 Pick-your-build: Core QUIC only for embedded targets or full HTTP/3 + services for servers
• 🛡️ Explicit crypto posture: Stable X25519/AEAD defaults with opt-in experimental ML-KEM and ML-DSA-65 via zcrypto
• ⚡ Native async runtime: Poll-based event loop, timer wheel, and connection pool in-tree
• 🌐 Layered stack: QUIC core, HTTP/3 server, DNS-over-QUIC, Ghost services, and VPN layers
• 📊 Operational insight: Built-in monitoring hooks and Prometheus-friendly metrics emitters
• 📦 Clean tooling: Straightforward zig build targets plus dev/ scripts for local workflows

# Minimal embedded target
zig build -Dhttp3=false -Ddoq=false -Dservices=false -Dvpn=false -Doptimize=ReleaseSmall

# HTTP/3 + DoQ server (stable crypto)
zig build -Dhttp3=true -Ddoq=true -Dservices=false -Dvpn=false -Doptimize=ReleaseFast

# Default build (HTTP/3, DoQ enabled; PQ disabled)
zig build

# With experimental post-quantum crypto
zig build -Dpost-quantum=true -Dexperimental-crypto=true

• Ed25519 and Secp256k1 signatures (stable)
• X25519 key exchange (stable)
• AES-256-GCM and ChaCha20-Poly1305 AEAD (stable)
• Blake3 and SHA256 hashing (stable)
• Zero-RTT resumption: Ultra-low latency with anti-replay protection

• Hybrid TLS 1.3: ML-KEM-768 + X25519 key exchange
• ML-DSA-65 post-quantum digital signatures (FIPS 204)
• Requires -Dpost-quantum=true -Dexperimental-crypto=true

• SSH secret injection: Bypass TLS handshake using pre-derived SSH secrets (draft-denis-ssh-quic)
• Secure key handling: Secrets passed by pointer, automatic zeroing on cleanup
• Bidirectional encryption: Proper local/remote key separation for client ↔ server traffic
• TLS fallback: SshQuicContext supports both SSH-injected and standard TLS modes
• Validation: Rejects all-zero and reused client/server directional secrets

// Example: Initialize QUIC with SSH-derived secrets
var secrets = zquic.SshQuic.SshQuicSecrets.init(client_secret, server_secret);
defer secrets.zeroize(); // Secure cleanup

var ctx = try zquic.SshQuic.SshQuicContext.initWithSshSecrets(
    allocator,
    is_server,
    &secrets,
);
defer ctx.deinit();

// Ready to encrypt/decrypt without TLS handshake
const ciphertext = try ctx.encrypt(plaintext, packet_number, allocator);

• Full QUIC v1 compliance: connection management, streams, flow control
• BBR/CUBIC congestion control: crypto-optimized for trading workloads
• Connection pooling: high-performance multiplexing for crypto protocols
• HTTP/3 server: hardened server surface with routing, middleware, shutdown, and backpressure coverage
• Consistent middleware execution: router fallback invokes global middleware (logging, static assets, auth) even when no route matches, so 404s still pass through your filters.
• QUIC-over-UDP VPN (experimental): docs/features/quic-vpn.md + new demos show how to tunnel mesh traffic as a concept alternative to Tailscale/NetBird.
• Zero-copy packet processing: optimized for 100K+ TPS
• IPv6-first networking: dual-stack with modern internet protocols

• QUIC Bridge: gRPC-over-QUIC relay for service communication
• QUIC Proxy: Post-quantum reverse proxy and load balancer
• DNS-over-QUIC: Secure DNS resolver for modern applications
• FFI integration: Production bindings for cross-language projects
• WASM integration: Runtime communication over QUIC transport

• Real-time metrics: performance monitoring and analytics
• Prometheus integration: dedicated exporter surfaces HTTP/3, DoQ, and VPN metrics ready for /metrics
• Alerting system: configurable thresholds for high-throughput workloads
• Connection health: advanced diagnostics for network infrastructure
• Protocol analytics: detailed breakdown of DoQ/HTTP3/gRPC usage

• 100K+ transactions/second transport capability
• <1ms latency for critical path operations with Zero-RTT
• Hybrid PQ-TLS preview paths for opt-in experiments and review fixtures
• Zero-copy operations throughout the entire stack
• Deterministic memory management with predictable allocation patterns
• Advanced congestion control optimized for high-throughput networking

• docs/getting-started/quick-start.md – bootstrap instructions
• docs/getting-started/build-config.md – flag reference kept in sync with build.zig
• docs/README.md – diagram-rich documentation map and navigation
• docs/architecture/overview.md – protocol layering and component responsibilities
• docs/architecture/state-machines.md – connection, stream, key phase, shutdown, and PQ reuse state diagrams
• docs/architecture/flow-control-recovery.md – stream backpressure, packet recovery, and loss timer diagrams
• docs/architecture/async-runtime.md – explains the in-tree async runtime that replaced zsync
• docs/getting-started/examples.md – walkthroughs mirroring the binaries prepared by zig build
• docs/features/overview.md & docs/features/quic-vpn.md – catalogue of major modules plus the experimental QUIC VPN deep dive
• docs/operations/deployment.md – deployment profiles, validation pipeline, observability, and incident response
• docs/integrations/prometheus.md – how to attach the exporter and what metrics to expect
• docs/integrations/zcrypto.md – tuning notes for PQ TLS + VPN helpers
• examples/*.zig – runnable samples that match the documentation

Repository hosting is expected to move to git.cktechx.com, a self-hosted GitLab instance maintained with image-based server backups and Wasabi S3 repository backups. The move is intended to provide more control over the CI environment, runner configuration, and release infrastructure, while GitHub will likely remain as a backup mirror.

• Manual memory management for performance + predictability
• Compile-time safety with low runtime cost
• Works well in high-performance and embedded networking environments
• No hidden allocations or runtime overhead
• Cross-platform support with consistent behavior

zig fetch --save https://github.com/ghostkellz/zquic/archive/refs/tags/v0.9.14.tar.gz

git clone https://github.com/ghostkellz/zquic
cd zquic
zig build        # produces all enabled binaries under zig-out/bin/

Keep the dependency metadata intact (build.zig.zon pins dependencies) and build with the latest Zig 0.17.0-dev toolchain. Use zig build -Dtarget=<triple> for cross compilation.

# Format and lint quickly
./dev/fmt.sh

# Release validation matrix
./dev/validate.sh

# Smoke test HTTP/3 or DoQ locally
./dev/smoke_test.sh
# QUIC VPN routing smoke (experimental)
./dev/vpn_smoke.sh

Prefer individual commands? Run /opt/zig-dev/zig build integration-tests for handshake coverage or /opt/zig-dev/zig build fuzz-tests for the packet parser harness.

The dev/ scripts default to /opt/zig-dev/zig and accept ZIG=/path/to/zig overrides.

• 6 shipping binaries under zig-out/bin/
• Clean Zig 0.17.0-dev builds across Linux/macOS/Windows
• Internal async runtime + connection pool validated via new tests
• Documentation refreshed to match current feature flags

• ReleaseFast builds are the benchmark profile for throughput work
• Async runtime, packet, and buffer paths have dedicated regression coverage
• Deterministic memory behavior is checked through integration tests and release validation

const std = @import("std");
const zquic = @import("zquic");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    // Configure HTTP/3 server
    const config = zquic.Http3.ServerConfig{
        .max_connections = 10000,
        .enable_compression = true,
        .enable_cors = true,
        .enable_security_headers = true,
    };

    // Initialize HTTP/3 server
    var server = try zquic.Http3.Http3Server.init(allocator, config);
    defer server.deinit();

    // Add routes via the router
    try server.router.get("/", homeHandler);
    try server.router.get("/api/status", statusHandler);
    try server.router.post("/api/data", submitHandler);

    // Start server
    try server.start();
    std.debug.print("HTTP/3 server running on QUIC\n", .{});
}

fn homeHandler(_: *zquic.Http3.Request, res: *zquic.Http3.Response) !void {
    try res.setStatus(.ok);
    try res.setBody("Welcome to ZQUIC");
}

fn statusHandler(_: *zquic.Http3.Request, res: *zquic.Http3.Response) !void {
    try res.setStatus(.ok);
    try res.setBody("{\"status\": \"online\"}");
}

fn submitHandler(req: *zquic.Http3.Request, res: *zquic.Http3.Response) !void {
    _ = req;
    try res.setStatus(.created);
    try res.setBody("{\"created\": true}");
}

• src/async/ – native event loop, timer wheel, and runtime orchestration
• src/core/ – QUIC transport (connection, stream, packet, recovery, flow control)
• src/crypto/ – TLS 1.3 + PQ handshake glue over zcrypto
• src/http3/ – frame parsing, router, middleware, and advanced server
• src/doq/ – DNS-over-QUIC client/server implementations
• src/services/ – GhostBridge, Wraith, CNS resolver, and VPN adapters
• src/monitoring/ – metrics hooks for Prometheus/exporters
• examples/ – runnable demos built during zig build

1. ./dev/deps.sh – ensure Zig toolchain + deps are ready
2. ./dev/build_all.sh – compile every target with current feature flags
3. ./dev/test.sh – runs zig build test, zig build integration-tests, and zig build fuzz-tests (network-dependent tests emit warnings)
4. ./dev/smoke_test.sh – launch sample client/server pairs for manual validation
5. zig fmt src/ docs/ examples/ – formatting gate before opening PRs

Please read CONTRIBUTING.md for coding standards, testing expectations, and PR workflow. At a minimum run ./dev/test.sh and ensure new code paths include unit or integration coverage.

Apache 2.0 — built to power the post-quantum future with modern Zig applications.