Kerniq Server

use kerniq_server::prelude::*;

#[tokio::main]
async fn main() -> Result<()> {
    let app = App::new()
        .get("/", || async { "Hello from Kerniq" });

    app.run("127.0.0.1:3000").await
}

[dependencies]
kerniq-server = "0.1"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
serde = { version = "1", features = ["derive"] }

use std::sync::Arc;
use std::time::Duration;

use kerniq_server::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Clone)]
struct AppState {
    service_name: Arc<str>,
}

#[derive(Serialize)]
struct User { id: u64, name: String }

#[derive(Deserialize)]
struct CreateUser { name: String }

async fn get_user(Path(id): Path<u64>) -> Result<Json<User>> {
    if id == 0 {
        return Err(Error::not_found("The requested user does not exist").with_code("USER_NOT_FOUND"));
    }
    Ok(Json(User { id, name: "Ada".into() }))
}

async fn create_user(Json(input): Json<CreateUser>) -> Created<User> {
    Created(User { id: 1, name: input.name })
}

async fn health(State(state): State<AppState>) -> String {
    format!("{} is healthy", state.service_name)
}

#[tokio::main]
async fn main() -> Result<()> {
    let users = Router::new()
        .get("/{id}", get_user)
        .post("/", create_user);

    let config = ServerConfig::from_env()?
        .request_timeout(Duration::from_secs(30))
        .max_concurrent_requests(1024);
    let address = config.address();

    App::new()
        .config(config)
        .state(AppState { service_name: "customer-api".into() })
        .middleware(RequestId::new())
        .middleware(Logger::new())
        .middleware(SecurityHeaders::new())
        .get("/health", health)
        .mount("/users", users)
        .run(address)
        .await
}

{"error":{"code":"USER_NOT_FOUND","message":"The requested user does not exist"}}

use kerniq_server::prelude::*;
use serde::Deserialize;

#[derive(Deserialize)]
struct NewUser { email: String }

async fn create_user(Json(body): Json<NewUser>) -> Result<NoContent> {
    if body.email.is_empty() {
        return Err(Error::bad_request("Email is required")                 // 400
            .with_code("EMAIL_MISSING")                                     // custom machine code
            .with_details(serde_json::json!({ "field": "email" })));        // structured details
    }
    Ok(NoContent)
}

// Any other status:
fn payment_required() -> Error {
    Error::new(StatusCode::PAYMENT_REQUIRED, "LIMIT_EXCEEDED", "Monthly limit reached")
}

use kerniq_server::prelude::*;

fn lookup(id: u64) -> Result<String> {
    let raw: std::result::Result<Option<String>, std::io::Error> = Ok(Some(format!("user {id}")));
    let user = raw
        .or_internal()?                       // unexpected error → 500 (logged, never leaked)
        .or_not_found("User not found")?;     // None → 404
    Ok(user)
}

use kerniq_server::prelude::*;

async fn accepted() -> (StatusCode, &'static str) {
    (StatusCode::ACCEPTED, "queued")                                       // 202
}

async fn created() -> (StatusCode, [(&'static str, &'static str); 1], &'static str) {
    (StatusCode::CREATED, [("location", "/users/7")], "created")           // 201 + header
}

async fn health() -> StatusCode {
    StatusCode::OK                                                          // empty body
}

use kerniq_server::prelude::*;
use sqlx::postgres::{PgPool, PgPoolOptions};

#[derive(Clone)]
struct AppState { db: PgPool }

async fn count_users(State(state): State<AppState>) -> Result<String> {
    let (n,): (i64,) = sqlx::query_as("SELECT count(*) FROM users")
        .fetch_one(&state.db)
        .await
        .or_internal()?; // logged, never leaked; the client sees a generic 500
    Ok(n.to_string())
}

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
    let db = PgPoolOptions::new()
        .max_connections(20)
        .connect(&std::env::var("DATABASE_URL")?)
        .await?; // an unreachable database fails startup, not the first request

    App::new()
        .state(AppState { db: db.clone() })
        .get("/users/count", count_users)
        .background_task("orders-consumer", |shutdown: Shutdown| async move {
            // e.g. a Kafka or RabbitMQ consumer loop:
            // tokio::select! { msg = consumer.recv() => ..., () = shutdown.wait() => break }
            shutdown.wait().await;
        })
        .run("0.0.0.0:3000")
        .await?;

    db.close().await; // requests have drained and tasks have stopped
    Ok(())
}

cargo install --path crates/kerniq-cli
kerniq new customer-api --template production --kerniq-path .
cd customer-api
kerniq dev      # run, rebuild and restart on change
kerniq check    # fmt --check, check, clippy -D warnings
kerniq test

cp -r skills/kerniq-server ~/.claude/skills/                  # every project
cp -r skills/kerniq-server <your-project>/.claude/skills/     # one project

kerniq-server  ── App, prelude, re-exports (the crate you depend on)
├── kerniq-core        Error model, ServerConfig
├── kerniq-http        Extractors and responses
├── kerniq-routing     Router, groups, Middleware composition
├── kerniq-middleware  Production middleware (tower / tower-http)
├── kerniq-runtime     Accept loop, graceful shutdown, background tasks
└── kerniq-openapi     Utoipa documents + Swagger UI   (optional)
kerniq-cli             Independent scaffolding tool

cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings