capy-framework 0.10.0

An opinionated full-stack Rust web framework with strong conventions and sensible defaults.
Documentation
//! Public facade derive ergonomics and documentation exposure policy.
use capy_framework::{self as capy, prelude::*};
use capy_testing::TestApp;
use std::sync::Arc;

#[derive(Serialize, ApiSchema)]
#[serde(crate = "capy::serde")]
#[schemars(crate = "capy::schema")]
struct Message {
    message: String,
}

fn application() -> App {
    App::new().api_routes(
        Routes::new()
            .get("/hello", || async {
                Json(Message {
                    message: "hello".into(),
                })
            })
            .operation("hello")
            .response::<Message>(),
    )
}

async fn context(openapi: bool, docs: bool, production: bool) -> AppContext {
    let mut config = AppConfig::default();
    config.database.url = "sqlite::memory:".into();
    config.api.openapi = openapi;
    config.api.docs = docs;
    if production {
        config.app.environment = "production".into();
    }
    AppContext {
        db: capy::db::connect(&config.database).await.unwrap(),
        config: Arc::new(config),
    }
}

#[test]
fn export_needs_no_database_and_advanced_standard_properties_are_available() {
    let mut config = AppConfig::default();
    config.api.title = Some("Example API".into());
    config.api.version = "2026.1".into();
    let document = application()
        .config(config)
        .openapi_with(|document| {
            document.as_value_mut()["components"]["securitySchemes"] =
                json!({"bearer":{"type":"http","scheme":"bearer"}});
        })
        .openapi()
        .unwrap();
    assert_eq!(document.as_value()["info"]["title"], "Example API");
    assert_eq!(document.as_value()["info"]["version"], "2026.1");
    assert_eq!(
        document.as_value()["paths"]["/api/hello"]["get"]["operationId"],
        "hello"
    );
    assert_eq!(
        document.as_value()["components"]["securitySchemes"]["bearer"]["scheme"],
        "bearer"
    );
}

#[test]
fn strict_mode_checks_all_public_routes_and_respects_explicit_exemptions() {
    let undocumented = || {
        App::new()
            .config(AppConfig::default())
            .api_routes(Routes::new().get("/missing", || async { "missing" }))
    };
    assert!(undocumented().openapi().is_ok(), "strictness is opt-in");
    assert!(undocumented()
        .openapi_strict()
        .unwrap_err()
        .to_string()
        .contains("GET /api/missing"));
    let mut config = AppConfig::default();
    config.api.require_documented_routes = true;
    assert!(undocumented().config(config).openapi().is_err());
    let routes = Routes::new()
        .get("/health", capy::health)
        .contract_exempt("internal liveness")
        .merge(
            Routes::new()
                .get("/hello", || async { "hello" })
                .operation("hello")
                .response::<Message>(),
        );
    let document = App::new()
        .config(AppConfig::default())
        .api_routes(routes)
        .routes(Routes::new().get("/web", || async { "web" }))
        .openapi_strict()
        .unwrap();
    assert!(document.as_value()["paths"].get("/api/hello").is_some());
    assert!(document.as_value()["paths"].get("/api/health").is_none());
    let error = App::new()
        .config(AppConfig::default())
        .routes(Routes::new().get("/api/legacy", || async { "legacy" }))
        .openapi_strict()
        .unwrap_err();
    assert!(error.to_string().contains("GET /api/legacy"));
    let error = App::new()
        .config(AppConfig::default())
        .api_routes(
            Routes::new()
                .get("/broken", || async { "broken" })
                .operation("broken")
                .contract_exempt("internal"),
        )
        .openapi_strict()
        .unwrap_err();
    assert!(
        error.to_string().contains("no success response"),
        "exemptions cannot hide invalid metadata"
    );
}

#[test]
fn strict_native_escape_hatches_require_reviewed_reasons() {
    let routes = || {
        Routes::new()
            .get("/health", capy::health)
            .contract_exempt("probe")
    };
    assert!(App::new()
        .config(AppConfig::default())
        .api_routes(routes().map_router(|r| r))
        .openapi_strict()
        .is_err());
    assert!(App::new()
        .config(AppConfig::default())
        .api_routes(routes().map_router_exempt("middleware only", |r| r))
        .openapi_strict()
        .is_ok());
    assert!(App::new()
        .config(AppConfig::default())
        .api_routes(routes().map_router_exempt(" ", |r| r))
        .openapi_strict()
        .is_err());
    assert!(App::new()
        .config(AppConfig::default())
        .api_routes(Routes::new().contract_exempt("no preceding route"))
        .openapi_strict()
        .is_err());
}

#[tokio::test]
async fn documentation_is_opt_in_and_production_exposure_is_explicit() {
    let app = TestApp::new(application().into_router(context(false, false, false).await));
    app.get("/openapi.json")
        .send()
        .await
        .assert_status(capy::axum::http::StatusCode::NOT_FOUND);
    app.get("/docs/api")
        .send()
        .await
        .assert_status(capy::axum::http::StatusCode::NOT_FOUND);
    let ctx = context(false, true, false).await;
    ctx.db.clone().close().await.unwrap();
    let app = TestApp::new(application().into_router(ctx));
    app.get("/openapi.json").send().await.assert_ok();
    app.get("/docs/api").send().await.assert_ok();
    let app = TestApp::new(application().into_router(context(false, true, true).await));
    app.get("/openapi.json")
        .send()
        .await
        .assert_status(capy::axum::http::StatusCode::NOT_FOUND);
    app.get("/docs/api")
        .send()
        .await
        .assert_status(capy::axum::http::StatusCode::NOT_FOUND);
    let app = TestApp::new(application().into_router(context(true, true, true).await));
    app.get("/openapi.json").send().await.assert_ok();
    app.get("/docs/api")
        .send()
        .await
        .assert_status(capy::axum::http::StatusCode::NOT_FOUND);
}