Kavro

Kavro is an experimental TypeScript-first web server and reverse proxy.

This package owns the full Kavro surface: a TypeScript config DSL that compiles into a canonical JSON route graph, plus the internal Rust/Pingora runtime crate that serves that graph.

The production data plane target is Rust on top of Cloudflare's Pingora. The Rust server runtime should consume the graph without executing arbitrary user TypeScript. Cap'n Web is reserved for future browser dashboards or web-agent control surfaces. Cap'n Proto is not needed unless Kavro grows a Rust-native daemon or supervisor protocol. Pingora remains the HTTP/proxy backbone.

Source layout

packages/kavro/
  src/              TypeScript DSL, compiler, schema validation, and CLI
  crates/server/    Rust/Pingora runtime binary
  examples/         End-to-end fixtures

Example

import {
  defineConfig,
  fastCgi,
  proxy,
  respond,
  route,
  server,
  staticFiles,
  upstream,
} from '@kuratchi/kavro';

export default defineConfig({
  upstreams: [
    upstream('app', 'http://127.0.0.1:3000'),
  ],
  servers: [
    server({
      listen: 8080,
      hostnames: ['localhost'],
      routes: [
        route('/assets/*', staticFiles('./dist/assets')),
        route('/api/*', proxy('app')),
        route('/health', respond('ok')),
      ],
    }),
  ],
});

PHP-FPM/FastCGI is part of the route graph contract for the Rust runtime:

route('/*.php', fastCgi('php-fpm', './wordpress', {
  scriptRoot: '/var/www/html',
  index: ['index.php'],
  cache: {
    ttlMs: 5000,
    statuses: [200],
  },
}));

Dynamic cache is opt-in and route-scoped. The Rust runtime currently stores eligible proxy and fastcgi responses in memory and marks responses with x-kavro-cache: MISS, HIT, or BYPASS.

Compile the config:

kavro compile --config kavro.config.ts --out .kavro/route-graph.json

Validate an existing graph:

kavro validate .kavro/route-graph.json

Run the preview server:

kavro serve --config kavro.config.ts

The preview runtime is intentionally small and Node-backed. It exists only so the TypeScript config and canonical route graph can be exercised end to end while the Pingora-backed Rust runtime matures. It is not the production server architecture.

Build the Rust runtime from this package:

npm run server:build