allframe 0.1.27

AllFrame is a complete Rust web framework with a built-in HTTP/2 server, designed and evolved exclusively through TDD. Write your handler once and expose it via REST, GraphQL, and gRPC from a single codebase.

Quick Start

cargo install allframe
allframe ignite my-api
cd my-api && cargo run
# Visit http://localhost:8080/swagger-ui

Or add it as a dependency:

[dependencies]
allframe = "0.1"

use allframe::prelude::*;

#[allframe::main]
async fn main() {
    let app = App::new()
        .route("/hello", get(hello_handler));
    app.run().await;
}

#[api_handler]
async fn hello_handler() -> &'static str {
    "Hello, AllFrame!"
}

Crates

AllFrame ships as composable crates -- use only what you need:

Crate	Description
allframe	Re-exports core + CLI (allframe ignite)
allframe-core	Router, CQRS, DI, resilience, auth, security
allframe-macros	Proc macros (#[handler], #[di_container], #[retry], ...)
allframe-forge	Project scaffolding & code generation
allframe-mcp	MCP server -- expose handlers as LLM tools (zero overhead when unused)
allframe-tauri	Tauri 2.x plugin for offline-first desktop apps

Features at a Glance

Protocol-Agnostic Routing

#[handler(protocols = ["rest", "graphql", "grpc"])]
async fn create_user(input: CreateUserInput) -> Result<User, Error> {
    // Exposed as POST /users, mutation { createUser }, and CreateUser(request)
}

78 tests across 5 phases. Full adapters for REST, GraphQL (async-graphql), and gRPC (tonic) with automatic schema generation (OpenAPI 3.1, GraphQL SDL, .proto).

CQRS + Event Sourcing

85% average boilerplate reduction with CommandBus, QueryBus, ProjectionRegistry, event versioning with auto-upcasting, and saga orchestration with automatic compensation. Pluggable backends: in-memory, SQLite, AllSource.

#[command], #[query], and #[event] macros generate real trait implementations at compile time:

#[command]
struct CreateUser { user_id: String, email: String }

#[event]
#[derive(Clone, Serialize, Deserialize)]
enum UserEvent {
    Created { user_id: String, email: String },
}

#[command_handler]
async fn create_user(cmd: CreateUser) -> CommandResult<UserEvent> {
    Ok(vec![UserEvent::Created { user_id: cmd.user_id, email: cmd.email }])
}

Read the CQRS announcement

Clean Architecture Enforcement

Layer dependency rules enforced at compile time via #[domain], #[repository], #[use_case], and #[handler] macros. Domain types that reference repository or handler types produce clear compile errors:

#[domain]
struct User { id: String, email: String }  // No upper-layer deps allowed

#[use_case]
struct GetUser { repo: Arc<dyn UserRepository> }  // Can depend on repositories

Compile-Time DI

#[di_container]
struct AppContainer {
    user_repo: Arc<dyn UserRepository>,
    user_service: Arc<UserService>,
}
// Resolved at compile time -- zero runtime overhead

Resilience Patterns

Retry with exponential backoff, circuit breaker (per-resource with KeyedCircuitBreaker), rate limiting (token bucket, Redis-backed for distributed), adaptive retry, and retry budgets. Use the Clean Architecture ResilienceOrchestrator API:

let orchestrator = DefaultResilienceOrchestrator::new();
let policy = ResiliencePolicy::Retry {
    max_attempts: 3,
    backoff: BackoffStrategy::Exponential {
        initial_delay: Duration::from_millis(100),
        multiplier: 2.0,
        max_delay: Some(Duration::from_secs(30)),
        jitter: true,
    },
};
let result = orchestrator.execute_with_policy(policy, || fetch_user(id)).await;

Note: The #[retry], #[circuit_breaker], and #[rate_limited] attribute macros are deprecated since 0.1.13. See the migration guide for the new Clean Architecture approach.

MCP Server (LLM Tool Calling)

Handlers automatically become Model Context Protocol tools. Zero overhead when not used -- opt-in via a separate crate.

let mcp = McpServer::with_router(router);
let result = mcp.call_tool("get_user", json!({"user_id": "123"})).await;

allframe-mcp docs | MCP distribution model

Layered Authentication

Protocol-agnostic auth with zero-bloat feature flags: core Authenticator trait, JWT validation (HS256, RS256, EdDSA), Axum extractors/middleware, gRPC interceptors, and type-safe AuthContext<C>.

Security Utilities

URL/credential obfuscation, Sensitive<T> wrapper, #[derive(Obfuscate)] with #[sensitive] field attributes, smart header obfuscation.

API Documentation

Auto-generated interactive docs for all protocols:

• Scalar UI for REST (10x smaller than Swagger) -- guide
• GraphiQL 3.0 playground for GraphQL -- guide
• gRPC Explorer for service discovery -- example

Offline-First Architecture

SQLite event store, offline circuit breaker with operation queuing, store-and-forward for intermittent connectivity, bidirectional projection sync with conflict resolution. Zero network dependencies in offline builds, enforced by CI.

Streaming Handlers

StreamSender with backpressure and cooperative cancellation. Tauri IPC bridge with per-stream events. TypeScript codegen with RxJS adapter.

Contract Testing

Automatic test generation from router, schema validation, breaking change detection, and coverage reporting.

Graceful Shutdown

ShutdownAwareTaskSpawner for named tasks with automatic cancellation, GracefulShutdownExt for cleanup orchestration.

Feature Flags

Start minimal and add features as needed. Detailed guide: docs/guides/FEATURE_FLAGS.md

# Minimal REST API
allframe = { version = "0.1", default-features = false, features = ["router"] }

# Full multi-protocol gateway
allframe = { version = "0.1", features = ["router-full", "resilience", "auth-jwt"] }

Examples

cargo run --example rest_api
cargo run --example graphql_api
cargo run --example grpc_api
cargo run --example multi_protocol
cargo run --example resilience --features resilience
cargo run --example security --features security
cargo run -p allframe-core --example graceful_shutdown

See examples/README.md for details.

Why AllFrame?

Documentation

CQRS Deep Dives

• Phase 1: AllSource Integration
• Phase 2: CommandBus (90% reduction)
• Phase 3: ProjectionRegistry
• Phase 4: Event Versioning (95% reduction)
• Phase 5: Saga Orchestration

Contributing

AllFrame is 100% TDD-driven. Every commit must contain at least one new failing test.

git clone https://github.com/all-source-os/all-frame.git
cd all-frame
cargo test
cargo clippy -- -D warnings
cargo fmt -- --check

1. Read the PRD
2. Ensure 100% test coverage for all changes
3. Follow the Clean Architecture Guide

License

Licensed under either of Apache License 2.0 or MIT, at your option.

Community

• Discussions
• Issue Tracker