Kavro Current Status | Kavro | Primitives Docs
Primitives

Kavro Current Status

Kavro Current Status

Kavro is currently a TypeScript-authored, JSON-validated, Rust/Pingora-executed web server and reverse proxy prototype.

The important product bet is intact:

TypeScript config
  -> canonical .kavro/route-graph.json
  -> validated Rust route graph
  -> Pingora-backed server runtime

Node can be an application upstream when a framework needs it, such as SvelteKit adapter-node, but Node is not Kavro's production server runtime.

Source Layout

Path Purpose Status
packages/kavro/src TypeScript DSL, compiler, schema validator, CLI, and preview runtime. Working. Compiles configs to canonical route graphs and validates them.
packages/kavro/crates/server Internal Rust/Pingora data plane crate owned by Kavro. Working prototype. Serves respond, static, proxy, and fastcgi actions.

Runtime Surface

The Rust runtime currently supports:

  • loading .kavro/route-graph.json
  • host, path, wildcard, and method matching
  • static files with index resolution and SPA fallback
  • MIME detection for common web assets
  • ETags
  • static cache rules
  • precompressed .br and .gz asset selection
  • reverse proxy routes through Pingora
  • request and response header policy
  • standard forwarded proxy headers:
    • x-forwarded-host
    • x-forwarded-port
    • x-forwarded-proto
    • x-forwarded-for
  • FastCGI/PHP-FPM routes over TCP
  • route-scoped in-memory response cache for proxy and fastcgi
  • cache status headers: x-kavro-cache: MISS, HIT, or BYPASS

Cache Semantics

Dynamic response cache is opt-in per route.

The current cache stores only safe responses:

  • request method must be allowed by the route cache policy
  • current write path stores GET
  • cacheable status must match the route policy
  • request with Cookie bypasses
  • request with Authorization bypasses
  • response with Set-Cookie bypasses
  • response with Cache-Control: private or no-store bypasses
  • response body must fit maxBodyBytes when configured

Cache keys currently include:

  • route id
  • host
  • method, with HEAD sharing the GET key
  • path
  • query string when includeQuery is enabled
  • selected request headers when configured

This gives Kavro the first nginx/LiteSpeed-style page cache primitive, but with a typed route policy rather than string directives scattered across config.

Compatibility Fixtures

Fixture What it proves Status
packages/kavro/examples/static-site Minimal static site served from Kavro. Working compiler/runtime fixture.
apps/kavro-react-spa Vite React SPA with direct Kavro static serving and SPA fallback. Working fixture. Needs production-grade split cache defaults for shell vs hashed assets.
apps/kavro-sveltekit-ssr Basic SvelteKit adapter-node reverse proxy. Working first SSR proxy fixture.
apps/kavro-sveltekit-compat Full SvelteKit SSR compatibility gate. Current strongest proof. Verified SSR, deep routes, API, form actions, redirects, 404s, session cookies, forwarded headers, direct static assets, Brotli assets, and dynamic cache MISS/HIT/BYPASS.
apps/kavro-wordpress-proxy Kavro in front of an existing WordPress HTTP server. Working fixture.
apps/kavro-wordpress-fastcgi WordPress through native Kavro FastCGI/PHP-FPM without Apache in front. Working prototype. Needs hardening for uploads, PATH_INFO edge cases, and WordPress security/cache presets.
apps/kavro-php-fastcgi-cache FastCGI dynamic page cache without Apache/nginx. Working fixture.

SvelteKit Compatibility Gate

The primary fixture is apps/kavro-sveltekit-compat.

It proves that a normal SvelteKit SSR app can be placed behind Kavro:

  • SvelteKit builds with @sveltejs/adapter-node.
  • Kavro serves immutable client assets directly from build/client.
  • Kavro proxies SSR, endpoint, form, redirect, session, and error routes.
  • SvelteKit sees the public Kavro host/proto through forwarded headers.
  • Kavro can cache safe anonymous SSR pages and bypass unsafe ones.

Known-green checks:

curl -i http://127.0.0.1:7481/health
curl -i http://127.0.0.1:7481/
curl -i http://127.0.0.1:7481/blog/kavro-handoff
curl -i http://127.0.0.1:7481/api/time
curl -i -X POST \
  -H "Origin: http://127.0.0.1:7481" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "email=test@example.com" \
  http://127.0.0.1:7481/forms
curl -I http://127.0.0.1:7481/_app/version.json
curl -i http://127.0.0.1:7481/cached/market-brief?edition=morning
curl -i http://127.0.0.1:7481/cached/market-brief?edition=morning
curl -i -H "Cookie: kavro=1" \
  http://127.0.0.1:7481/cached/market-brief?edition=morning
curl -i http://127.0.0.1:7481/cached/private
curl -i http://127.0.0.1:7481/cached/market-brief?setCookie=1
curl -i http://127.0.0.1:7481/redirect
curl -i http://127.0.0.1:7481/does-not-exist

Browser verification was also done against the Kavro URL:

  • homepage rendered
  • API button called SvelteKit endpoint through Kavro
  • form action submitted successfully
  • cached SSR page rendered

WSL Is The Reference Dev Path

Pingora should be built and tested on Linux. On Windows, use WSL for the Rust runtime and compile route graphs from WSL when static roots must be consumed by the Linux process.

Reference commands:

cd $KAVRO_REPO
bun run --cwd packages/kavro build
node packages/kavro/dist/cli.js compile --cwd apps/kavro-sveltekit-compat
node packages/kavro/dist/cli.js validate apps/kavro-sveltekit-compat/.kavro/route-graph.json
cargo build --manifest-path packages/kavro/crates/server/Cargo.toml

Validation Commands

Focused checks for this checkpoint:

bun run --cwd packages/kavro check
bun run --cwd packages/kavro test
bun run --cwd packages/kavro build
bun run --cwd apps/kavro-sveltekit-compat check
bun run --cwd apps/kavro-sveltekit-compat build

From WSL:

cargo fmt --manifest-path packages/kavro/crates/server/Cargo.toml -- --check
cargo test --manifest-path packages/kavro/crates/server/Cargo.toml
node packages/kavro/dist/cli.js compile --cwd apps/kavro-sveltekit-compat
node packages/kavro/dist/cli.js validate apps/kavro-sveltekit-compat/.kavro/route-graph.json

What Is Still Missing

Absolute next must-dos:

  1. Add a first-class SvelteKit config helper/profile so users do not hand-write the asset/proxy split.
  2. Add a SvelteKit adapter-static fixture.
  3. Verify WebSockets, SSE, and streaming through Pingora.
  4. Add graceful shutdown and graceful route graph reload.
  5. Add route inspection and structured logs.

Important but later:

  • TLS automation and certificate storage
  • upstream health checks and real load balancing
  • disk-backed response cache
  • cache purge and cache tags
  • stale-while-revalidate and stale-if-error
  • WordPress security/cache presets
  • Docker/systemd/Kubernetes discovery plugins
  • Cap'n Web dashboard/control surface
  • Cap'n Proto only if a Rust-native daemon or supervisor becomes real