Krab

🦀 Krab
A full-stack Rust framework for SSR + Island Hydration, service composition, and operational hardening.

Quick Start · Architecture · Features · API Reference · Contributing · Release Policy

What is Krab?

Krab is a Rust-native full-stack framework designed to give you the developer experience of modern JavaScript frameworks (Next.js, Astro, SvelteKit) with the performance, memory safety, and type guarantees of Rust.

It uses a Server-Side Rendering (SSR) with Island Hydration architecture: pages are rendered as fast HTML on the server, while only interactive components are selectively hydrated with WebAssembly on the client. This results in minimal bundle sizes and blazing-fast page loads.

Unlike single-purpose libraries, Krab ships with built-in service composition — a multi-service architecture with auth, users, and frontend services — and enterprise operational hardening including migration governance, dependency security enforcement, structured telemetry, and production secret management.

Why Krab over alternatives?

Quick Start

Prerequisites

• Rust stable 1.75+ (rustup.rs)
• PostgreSQL 15+ (production backend) or SQLite (lightweight/dev)
• wasm-pack (for WASM client builds): cargo install wasm-pack
• cargo-deny (for dependency auditing): cargo install cargo-deny

Setup

# Clone and configure
git clone https://github.com/your-org/krab.git
cd krab
cp .env.example .env
# Edit .env with your local settings (DATABASE_URL, KRAB_AUTH_MODE, etc.)

Run services

# Individual services
cargo run --bin service_auth       # Auth REST API         → localhost:3001
cargo run --bin service_users      # Users GraphQL API     → localhost:3002
cargo run --bin service_frontend   # SSR Frontend          → localhost:3000

# Or use the orchestrator to run all at once
cargo run --bin krab_orchestrator

Validate the workspace

cargo fmt --all --check                                    # Formatting
cargo clippy --workspace --all-targets -- -D warnings      # Linting
cargo test --workspace                                     # Tests
cargo deny --all-features check advisories licenses bans   # Dependency audit
cargo doc --workspace --no-deps                            # Generate rustdoc

Architecture

Krab follows a "Server-First, Client-Opt-In" architecture organized as a Cargo workspace.

┌──────────────────────────────────────────────────────────┐
│                    krab_orchestrator                      │
│              (multi-process service runner)               │
├────────────┬─────────────────┬────────────────────────────┤
│service_auth│ service_users   │      service_frontend      │
│  (REST)    │ (GraphQL + DB)  │     (SSR + Islands)        │
├────────────┴─────────────────┴────────────────────────────┤
│                        krab_core                          │
│  config · http · db · telemetry · resilience · signal     │
├──────────────────┬────────────────────────────────────────┤
│   krab_macros    │  krab_server  │  krab_client (WASM)    │
│ (view!, #[island])│ (Hyper/Tower) │ (Island hydration)    │
├──────────────────┴────────────────────────────────────────┤
│                      krab_cli                             │
│            (dev tooling, env-check, bootstrap)            │
└──────────────────────────────────────────────────────────┘

Workspace crates

Features

Islands Architecture

Pages are server-rendered as static HTML by default. Interactive components are marked with #[island] and selectively hydrated via WebAssembly:

#[island]
pub fn Counter(initial: i32) -> impl View {
    let (count, set_count) = create_signal(initial);
    view! {
        <button on:click=move |_| set_count.update(|n| *n += 1)>
            "Count: " {count}
        </button>
    }
}

• Server: Renders to HTML string
• Client: Downloads targeted WASM, attaches event listeners to existing DOM

Multi-Database Support

Krab supports pluggable database backends via the KRAB_DB_DRIVER environment variable:

PostgreSQL includes enterprise features: versioned migrations with checksums, drift detection, promotion policy enforcement, and rollback rehearsal requirements.

Authentication & Security

• JWT/OIDC token issuance with key rotation (KeyRing with multiple kid support)
• Rate limiting with configurable capacity/refill and explicit store-failure policy (KRAB_RATE_LIMIT_FAIL_OPEN)
• JWT algorithm allowlist via KRAB_JWT_ALLOWED_ALGS
• Proxy trust controls via KRAB_TRUST_PROXY_HEADERS (forwarded headers are untrusted by default)
• Production secret enforcement: Inline secrets are rejected in non-dev environments; must use *_FILE or *_VAULT_REF sourcing
• RBAC: Admin scope/role gating on protected endpoints
• Token lifecycle: Issue, refresh (with replay detection), revoke

Dependency Security

Zero-tolerance dependency governance enforced via cargo-deny:

• Advisories: All known vulnerabilities denied (no ignore entries)
• Licenses: Allowlist-only (MIT, Apache-2.0, BSD, ISC, Zlib, MPL-2.0, Unicode)
• Bans: Unknown registries and git sources denied
• CI gate: cargo deny --all-features check advisories licenses bans

Observability

• Structured logging via tracing with OpenTelemetry-aligned field names
• Prometheus metrics at /metrics/prometheus on every service
• Prometheus compatibility aliases maintained for legacy dashboard/alert migration (krab_response_5xx_total, krab_request_duration_ms_*)
• JSON metrics at /metrics for programmatic consumption
• Health (/health) and readiness (/ready) endpoints with dependency status
• Request correlation via x-request-id header propagation

Configuration

All configuration is via environment variables. See .env.example for the complete reference.

Core variables

Secret sourcing (production)

In staging and prod environments, secrets must be provided via file mount or vault reference:

For the full environment template with validation rules, see plans/environment_template.md.

Database

PostgreSQL (default, production-grade)

Full enterprise governance is available when using PostgreSQL:

• Versioned migrations with checksum integrity validation
• Drift detection comparing expected vs. applied migration state
• Promotion policy: Enforces local → dev → staging → prod ordering
• Rollback rehearsal: Required before release environment promotions
• Governance audit trail: All policy decisions recorded to krab_migration_policy_audit
• Security validation: Rejects default credentials in non-dev environments

SQLite (lightweight alternative)

SQLite is available for development, testing, and lightweight deployments:

KRAB_DB_DRIVER=sqlite DATABASE_URL="sqlite://krab_users.sqlite?mode=rwc" cargo run --bin service_users

CI/CD Gates

All gates must pass before merge. Automated workflows enforce quality at every PR:

Documentation Map

Root documents

Technical references (docs/)

Planning documents (plans/)

Security

Report vulnerabilities privately via GitHub Security Advisories.

Current security posture:

• ✅ Zero cargo-deny advisory ignores
• ✅ Production secret sourcing enforced (*_FILE / *_VAULT_REF)
• ✅ Inline secrets rejected in non-dev environments
• ✅ No panic-driven startup paths
• ✅ Rate limiting on authentication endpoints
• ✅ CORS, compression, and request-id middleware on all services
• ✅ Non-dev startup rejects empty CORS allowlist (KRAB_CORS_ORIGINS required in staging/prod)

For the full security architecture, see docs/security.md.

Contributors

License

MIT — see individual crate Cargo.toml files for per-crate license declarations.