Architecture Overview

bext is a Rust workspace with ~36 crates organized so that each crate has a single responsibility, and optional Cargo features gate heavyweight dependencies like V8, wasmtime, Quinn (QUIC), and libphp. The default-features build links V8 + the bext-turbopack bundler; everything else is feature-gated.

Workspace Structure

bext/
  Cargo.toml                # Workspace root
  crates/
    # ── Server + core ────────────────────────────────────────
    bext-server/            # Main binary — actix-web HTTP server, masquerade router, vhost
    bext-core/              # Shared logic: SSR types, caching, source transforms, route discovery, framework registry. Houses `transform/prism_compile.rs` (the build-time JSX fold pass).
    bext-impls/             # Trait impls glue between bext-core and the optional crates
    bext-license/           # Ed25519 offline license key validation
    bext-keygen/            # License key generation utility (binary)

    # ── PRISM / framework pipeline ───────────────────────────
    bext-turbopack/         # Direct API around utoo/Turbopack — JSX → JS bundle compilation, file watcher, registry, transitive-closure walker. Owns the prism_compile call sites.
    bext-v8/                # rusty_v8 SSR isolate. Eval thread, page-context cache, streaming pump.
    bext-react-compiler/    # SWC-based React-Compiler integration (auto-memo + SSR pure-fn lowering)
    bext-css/               # Rust Tailwind v4 engine (utility scanner, JIT class generator)
    bext-import/            # AST-aware "use server" / "use client" directive scanner
    bext-proxy/             # HTTP proxy pool (upstream pools, retry, health checks)

    # ── Plugins ──────────────────────────────────────────────
    bext-plugin/            # NAPI addon for Bun (native plugin mode)
    bext-plugin-api/        # Trait definitions + shared types (no heavy deps; WASM guest-safe)
    bext-plugin-wasm/       # wasmtime sandbox for WASM plugins
    bext-plugin-v8/         # V8 isolate sandbox (sibling to bext-v8; runs untrusted plugin JS)
    bext-plugin-quickjs/    # rquickjs sandbox for trusted JS plugins
    bext-plugin-lua/        # mlua sandbox for Lua plugins
    bext-plugin-nsjail/     # Process-level sandbox with JSON-over-stdio IPC

    # ── Networking + protocols ───────────────────────────────
    bext-tls/               # ACME provisioning, SNI resolution, OCSP stapling
    bext-realtime/          # SSE + WebSocket pub/sub hub with Redis relay
    bext-waf/               # Web Application Firewall (IP, geo, rules, DDoS)
    bext-ebpf/              # eBPF acceleration: XDP, uprobes, seccomp-bpf
    bext-php/               # Embedded PHP SAPI via FFI (FrankenPHP-style)
    bext-protocol-mqtt/     # MQTT pub/sub broker
    bext-protocol-grpc/     # gRPC server (codegen + dispatcher)
    bext-protocol-caldav/   # CalDAV / CardDAV server

    # ── nginx compat ─────────────────────────────────────────
    bext-nginx-compat/      # nginx.conf parser → bext config converter
    bext-nginx-shim/        # Drop-in nginx binary replacement (binary)

    # ── Framework adapters ───────────────────────────────────
    bext-framework-astro/         # Astro adapter (SSR + islands)
    bext-framework-qwik/          # Qwik adapter
    bext-framework-solidstart/    # SolidStart adapter
    bext-framework-sveltekit/     # SvelteKit adapter

    # ── Tooling / DX ─────────────────────────────────────────
    bext-dx/                # Developer-experience: dev banner, file-watcher CLI
    bext-tui/               # Terminal UI for live deploy / log streaming
    bext-lsp/               # Language Server (completions, hovers, diagnostics)
    bext-bench-history/     # Perf-history database used by the benchmark dashboard

  harnesses/
    conformance/            # Next.js conformance test suite
    ecosystem/              # Third-party framework integration tests
    security/               # Fuzzing and penetration test harness
    jsx-shootout/           # 5-engine SSR throughput bench (PRISM, Marko, Solid, React, Rust)
    plugin-harness/         # Plugin sandbox conformance tests
    cache-bench/            # ISR cache benchmark
    ssr-dev/                # PRISM SSR dev-server harness against ~/dev/apps/app
    sites/                  # Self-contained PRISM fixture sites used by integration tests

  companion/                # Desktop companion app (Tauri)
  packages/                 # NPM-published packages (@bext-stack/*, @bext/*)
  sites/                    # First-party PRISM sites (docs, status, prism-demo, etc.)

Dependency Graph (high-level)

bext-server is the root that pulls in everything; bext-plugin-api is the leaf with no bext dependencies (so WASM guest crates can depend on it without dragging in actix-web or V8).

bext-server
  |-- bext-core             (always — types, transforms, route discovery)
  |-- bext-impls            (always — trait glue)
  |-- bext-turbopack        (default — JSX/TSX → JS bundle pipeline)
  |-- bext-v8               (default `v8` feature — SSR isolate)
  |-- bext-react-compiler   (optional `react-compiler` — SWC integration)
  |-- bext-css              (optional `route-css` — Tailwind JIT)
  |-- bext-proxy            (always — upstream pools)
  |-- bext-plugin-{api,wasm,v8,quickjs,lua,nsjail}  (optional `plugins`)
  |-- bext-tls              (optional `tls`)
  |-- bext-realtime         (optional `realtime`)
  |-- bext-waf              (optional `waf`)
  |-- bext-ebpf             (optional `ebpf`)
  |-- bext-php              (optional `php`)
  |-- bext-protocol-{mqtt,grpc,caldav}  (optional)
  |-- bext-nginx-compat     (optional `nginx-compat` — masquerade routing)
  |-- bext-license          (always)

The PRISM framework is owned by bext-core (the compile pass) and bext-turbopack (the call sites + bundler integration). The runtime that the compiled output calls into lives outside the Rust workspace, in sites/shared/framework/ (TypeScript, published as @bext-stack/framework).

bext-plugin-api is deliberately lightweight (only serde and serde_json) so WASM guest crates can depend on it without pulling in bext-core or actix-web.

Feature Flags

bext-server uses Cargo feature flags to keep the binary lean. Defaults pull in V8 + the Turbopack bundler so PRISM works out-of-the-box; everything else is opt-in:

A minimal build (--no-default-features) compiles in about 45 seconds on an M2 MacBook Pro. The full-featured production build (v8 + turbopack + route-css + react-compiler + nginx-compat + tls + redis + realtime + waf + php + h3-quic) takes approximately 5 minutes cold, ~30 seconds warm.

Build Profiles

The workspace uses aggressive release optimizations:

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
strip = true

This produces a single statically-linked binary (with musl on Linux) that is typically 15-25 MB depending on enabled features. The strip = true setting removes debug symbols from the release binary.

Core Design Principles

Single binary. Everything ships as one executable. No sidecar processes, no runtime dependencies (except optionally PHP and Redis).

Feature-gated compilation. You pay only for what you use. A server that does not need WASM plugins never links wasmtime.

Zero-copy where possible. The ISR cache, compression cache, and SSR pool pass Arc<Vec<u8>> instead of cloning response bodies. The transform pipeline uses Cow<str> to avoid allocation when no transforms apply.

Compile-time safety. Plugin traits (LifecyclePlugin, MiddlewarePlugin, TransformPlugin) are defined in bext-plugin-api and enforced at compile time. The WASM boundary uses JSON-over-ABI for flexibility.

Graceful degradation. Every optional subsystem (eBPF, TLS, WAF, realtime hub) degrades gracefully when unavailable. eBPF features check kernel capabilities at startup and fall back to userspace paths.

Key External Dependencies

For the full list of crates and their roles, see Crate Reference.