# Kavro Current Status

Package: Kavro
Canonical: https://kuratchi.dev/docs/kavro/current-status
Markdown: https://kuratchi.dev/docs/kavro/current-status.md

# 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:

```txt
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:

```sh
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:

```sh
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:

```sh
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:

```sh
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