High-fidelity engineering for the modern virtuoso.

Throughput Comparison
-------------------------------------------------------
Chopin     [██████████████████████████████] 100% (Baseline)
Actix Web  [███████████████████████████   ]  91%
Axum       [█████████████████████████     ]  84%
Hyper      [██████████████████████        ]  73%
-------------------------------------------------------

cargo install chopin-cli

[dependencies]
chopin-core = "0.5.27"
chopin-macros = "0.5.27"   # For attribute routing
chopin-pg = "0.5.27"       # High-performance PostgreSQL driver
chopin-orm = "0.5.27"      # Zero-allocation ORM layer
kowito-json = "0.2.18"     # Schema-JIT SIMD JSON serializer

use chopin_core::{Context, Response};
use chopin_macros::get;

#[get("/")]
fn hello_world(_ctx: Context) -> Response {
    Response::text("Hello, World!")
}

fn main() {
    // Automatically discovers all routes marked with macros
    Chopin::new()
        .mount_all_routes()
        .serve("0.0.0.0:8080")
        .unwrap();
}

#[get("/users")]
fn list_users(ctx: Context) -> Response { ... }

#[post("/users")]
fn create_user(ctx: Context) -> Response { ... }

#[get("/user/:id")]
fn get_user(ctx: Context) -> Response {
    let id = ctx.param("id");
    ...
}

let mut router = Router::new();
router.get("/about", about_handler);
router.get("/static/*path", static_file_handler);

use chopin_core::{Context, Response};
use kowito_json::serialize::Serialize;

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

#[get("/user/:id")]
fn get_user(ctx: Context) -> Response {
    let user = User { id: 42, username: "virtuoso".into(), is_active: true };
    ctx.json(&user)  // or Response::json(&user)
}

use serde::Deserialize;
use chopin_core::extract::Json;

#[derive(Deserialize)]
struct CreateUser { username: String, email: String }

#[post("/users")]
fn create_user(ctx: Context) -> Response {
    let Json(body) = match ctx.extract::<Json<CreateUser>>() {
        Ok(j) => j,
        Err(e) => return e,
    };
    // body.username and body.email are ready to use
    Response::new(201)
}

use serde::Deserialize;
use chopin_core::extract::Query;

#[derive(Deserialize)]
struct SearchParams { q: String, page: Option<u32> }

#[get("/search")]
fn search(ctx: Context) -> Response {
    let Query(params) = match ctx.extract::<Query<SearchParams>>() {
        Ok(q) => q,
        Err(e) => return e,
    };
    Response::text(format!("Searching: {}", params.q))
}

#[get("/assets/*path")]
fn serve_asset(ctx: Context) -> Response {
    let path = ctx.param("path").unwrap_or("");
    // Automatically sets Content-Type. Returns 404 if not found.
    Response::file(&format!("public/{}", path))
}

use chopin_core::http::OwnedFd;
use chopin_core::syscalls::{open_file_readonly, file_size};

#[get("/download")]
fn download(ctx: Context) -> Response {
    let fd = open_file_readonly("/data/archive.tar.gz").unwrap();
    let size = file_size(fd).unwrap();
    // Response::sendfile(fd, offset, len, content_type)
    Response::sendfile(OwnedFd::new(fd), 0, size, "application/gzip")
}

// Builder style — chains on a value
Response::json(&data)
    .with_header("X-Request-Id", request_id)
    .with_header("Cache-Control", "no-store")

// Direct mutation in middleware
fn cors_middleware(ctx: Context, next: BoxedHandler) -> Response {
    next(ctx).with_header("Access-Control-Allow-Origin", "*")
}

// Path parameter
let id: &str = ctx.param("id").unwrap_or("0");

// Request header (case-insensitive)
let auth: Option<&str> = ctx.header("Authorization");

// Raw query string (e.g. "page=2&limit=50")
let qs: Option<&str> = ctx.req.query;

// Raw request body bytes
let body: &[u8] = ctx.req.body;

// HTTP method and path
let method = ctx.req.method; // Method::Get / Post / Put / Delete
let path   = ctx.req.path;   // &str

#[post("/upload")]
fn upload_handler(ctx: Context) -> Response {
    let Some(multipart) = ctx.multipart() else {
        return Response::bad_request();
    };

    for part in multipart {
        let p = part.unwrap();
        println!("Field: {}, File: {:?}, Size: {} bytes",
            p.name.unwrap_or("unnamed"),
            p.filename,
            p.body.len()); // p.body is a &[u8] — zero-copy into the read buffer
    }
    
    Response::text("Upload complete")
}

[dependencies]
chopin-auth = "0.5.16"
serde = { version = "1", features = ["derive"] }

use chopin_auth::HasJti;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Claims {
    sub: String,
    role: String,
    jti: String,
    exp: u64,
}

impl HasJti for Claims {
    fn jti(&self) -> Option<&str> { Some(&self.jti) }
}

use chopin_auth::{init_jwt_manager, JwtManager, TokenBlacklist};
use std::time::Duration;

fn init_auth() {
    let blacklist = TokenBlacklist::new();
    blacklist.start_cleanup_task(Duration::from_secs(300));

    let manager = JwtManager::new(b"super-secret")
        .with_blacklist(blacklist.clone());

    init_jwt_manager(manager);
}

use chopin_auth::JwtManager;

// HS256 sign + verify (shared secret)
let _hs = JwtManager::new(b"secret");

// HS256 verify-only (encode() returns EncodingKeyMissing)
let _hs_verify = JwtManager::verify_only(b"secret");

// RS256 sign + verify
let _rs = JwtManager::from_rsa_pem(PRIVATE_PEM, PUBLIC_PEM)?;

// RS256 verify-only
let _rs_verify = JwtManager::from_rsa_public_pem(PUBLIC_PEM)?;

// ES256 sign + verify
let _es = JwtManager::from_ec_pem(EC_PRIVATE_PEM, EC_PUBLIC_PEM)?;

// ES256 verify-only
let _es_verify = JwtManager::from_ec_public_pem(EC_PUBLIC_PEM)?;

// Advanced: use JwtManager::with_config(JwtConfig { ... }) for full validation/key control.

use chopin_auth::{AuthError, JwtManager};

let manager = JwtManager::new(b"secret");
let claims = Claims {
    sub: "user-1".into(),
    role: "admin".into(),
    jti: "jti-123".into(),
    exp: 4_102_444_800, // 2100-01-01 UTC
};

let token = manager.encode(&claims)?;
let decoded: Claims = manager.decode(&token)?;

match manager.decode::<Claims>("bad.token") {
    Ok(_) => {}
    Err(AuthError::Expired) => eprintln!("expired"),
    Err(AuthError::Revoked) => eprintln!("revoked"),
    Err(AuthError::InvalidToken(e)) => eprintln!("invalid: {}", e),
    Err(e) => eprintln!("other auth error: {}", e),
}

use chopin_auth::Auth;
use chopin_core::{Context, Response};

#[get("/me")]
fn me(ctx: Context) -> Response {
    let auth = match ctx.extract::<Auth<Claims>>() {
        Ok(a) => a,
        Err(resp) => return resp,
    };

    Response::text(format!("hello {}", auth.claims.sub))
}

use chopin_auth::{Role, RoleCheck, require_role_middleware};

#[derive(Debug, PartialEq)]
enum UserRole { Admin, User }
impl Role for UserRole {}

impl RoleCheck<UserRole> for Claims {
    fn has_role(&self, role: &UserRole) -> bool {
        matches!((&*self.role, role), ("admin", UserRole::Admin) | ("user", UserRole::User))
    }
}

require_role_middleware!(admin_only, Claims, UserRole::Admin, Claims::has_role);

// Use `admin_only` in your router/middleware chain for admin endpoints.

use chopin_auth::TokenBlacklist;

let blacklist = TokenBlacklist::new();

// revoke until token expiry (recommended)
blacklist.revoke("jti-123".to_string(), Some(4_102_444_800));

// checks
let revoked = blacklist.is_revoked("jti-123");
println!("revoked={}", revoked);

// maintenance
blacklist.cleanup();
println!("entries={} empty={}", blacklist.len(), blacklist.is_empty());

use chopin_auth::{set_error_handler, AuthError, ErrorHandler};
use chopin_core::Response;

struct JsonAuthErrors;

impl ErrorHandler for JsonAuthErrors {
    fn handle(&self, err: AuthError) -> Response {
        match err {
            AuthError::Expired => Response::new(401),
            AuthError::Revoked => Response::new(401),
            AuthError::InvalidToken(_) => Response::new(401),
            _ => Response::server_error(),
        }
    }
}

// call once at startup
set_error_handler(JsonAuthErrors);

use chopin_auth::{PasswordHasher, hash_password, verify_password};

// Presets
let interactive = PasswordHasher::interactive(); // login default
let sensitive = PasswordHasher::sensitive();     // stronger / slower

// Custom params: memory_kib, iterations, parallelism
let custom = PasswordHasher::custom(32_768, 3, 1)?;

let hash = interactive.hash(b"my-password")?;
assert!(interactive.verify(b"my-password", &hash)?);

// Convenience helpers
let h2 = hash_password(b"another-password")?;
assert!(verify_password(b"another-password", &h2)?);
assert!(!verify_password(b"wrong", &h2)?);

use chopin_pg::{PgConfig, PgConnection, PgResult};

fn main() -> PgResult<()> {
    // URL form
    let config = PgConfig::from_url("postgres://chopin:chopin@127.0.0.1:5432/postgres")?;

    // Builder form
    let _config2 = PgConfig::new("127.0.0.1", 5432, "chopin", "chopin", "postgres");

    // Unix socket form (macOS/Linux)
    let _config3 = PgConfig::new("localhost", 5432, "chopin", "chopin", "postgres")
        .with_socket_dir("/var/run/postgresql");

    let mut conn = PgConnection::connect(&config)?;
    let rows = conn.query_simple("SELECT 1")?;
    let one: i32 = rows[0].get_typed(0)?;
    assert_eq!(one, 1);
    Ok(())
}

use chopin_pg::{PgConfig, PgPool};
use std::cell::RefCell;

thread_local! {
    pub static DB: RefCell<PgPool> = RefCell::new(
        PgPool::connect(
            PgConfig::from_url("postgres://chopin:chopin@127.0.0.1:5432/postgres").unwrap(),
            10,
        ).expect("DB connect failed")
    );
}

#[get("/users/:id")]
fn get_user(ctx: Context) -> Response {
    let id: i32 = ctx.param("id").unwrap_or("1").parse().unwrap_or(1);
    DB.with(|db| {
        let mut pool = db.borrow_mut();
        let mut conn = pool.get().unwrap();
        let row = conn
            .query_one("SELECT id, name FROM users WHERE id = $1", &[&id])
            .unwrap();

        let id: i32 = row.get_typed(0).unwrap();
        let name: String = row.get_typed(1).unwrap();
        Response::text(format!("{}:{}", id, name))
    })
}

let mut conn = PgConnection::connect(&config)?;

// No parameters (simple protocol)
let _rows = conn.query_simple("SELECT current_database()")?;

// Multi-row
let rows = conn.query("SELECT id FROM users WHERE active = $1", &[&true])?;

// Exactly one row (Err(PgError::NoRows) if none)
let row = conn.query_one("SELECT email FROM users WHERE id = $1", &[&42i32])?;

// Optional row
let maybe = conn.query_opt("SELECT email FROM users WHERE id = $1", &[&9999i32])?;

// Execute returns affected rows
let changed = conn.execute("UPDATE users SET active = $1 WHERE id = $2", &[&false, &42i32])?;
println!("updated={}", changed);

// Closure transaction (auto BEGIN/COMMIT/ROLLBACK)
conn.transaction(|tx| {
    tx.execute("INSERT INTO users (name) VALUES ($1)", &[&"Alice"])?;

    // Nested transaction => SAVEPOINT
    tx.transaction(|nested| {
        nested.execute("INSERT INTO logs (msg) VALUES ($1)", &[&"created Alice"])?;
        Ok(())
    })?;

    Ok(())
})?;

// Manual control
conn.begin()?;
conn.savepoint("sp1")?;
conn.execute("UPDATE accounts SET balance = balance - 100 WHERE id = $1", &[&1i32])?;
conn.rollback_to("sp1")?;
conn.release_savepoint("sp1")?;
conn.commit()?;

// COPY IN
let mut writer = conn.copy_in("COPY users (name, email) FROM STDIN")?;
writer.write_row(&["Alice", "alice@example.com"])?;
writer.write_row(&["Bob", "bob@example.com"])?;
let copied = writer.finish()?;
println!("copied rows={}", copied);

// COPY IN with failure path
let writer = conn.copy_in("COPY users (name) FROM STDIN")?;
writer.fail("invalid source format")?;

// COPY OUT
let mut reader = conn.copy_out("COPY users TO STDOUT")?;
let bytes = reader.read_all()?;
println!("{}", String::from_utf8_lossy(&bytes));

conn.listen("events")?;
conn.notify("events", "hello")?;

if let Some(n) = conn.poll_notification()? {
    println!("pid={} channel={} payload={}", n.process_id, n.channel, n.payload);
}

for n in conn.drain_notifications() {
    println!("{}: {}", n.channel, n.payload);
}

conn.unlisten("events")?;
conn.unlisten_all()?;

use chopin_pg::{PgPool, PgPoolConfig};
use std::time::Duration;

let pool_cfg = PgPoolConfig::new()
    .max_size(32)
    .min_size(8)
    .checkout_timeout(Duration::from_secs(3))
    .connection_timeout(Duration::from_secs(3))
    .idle_timeout(Duration::from_secs(300))
    .max_lifetime(Duration::from_secs(1800))
    .test_on_checkout(true);

let mut pool = PgPool::connect_with_config(config.clone(), pool_cfg)?;

// Non-blocking checkout
let _guard = pool.try_get()?;

println!(
    "idle={} active={} total={}",
    pool.idle_connections(),
    pool.active_connections(),
    pool.total_connections()
);

let stats = pool.stats();
println!("checkouts={} created={}", stats.total_checkouts, stats.total_connections_created);

use std::time::Duration;

conn.set_io_timeout(Duration::from_secs(2));
conn.set_statement_cache_capacity(512);

// ... run workload ...

conn.clear_statement_cache();

use chopin_pg::{ErrorClass, PgError};

match conn.query_one("SELECT * FROM users WHERE id = $1", &[&id]) {
    Ok(row) => { /* use row */ }
    Err(err) => match err.classify() {
        ErrorClass::Transient => eprintln!("retry candidate: {}", err),
        ErrorClass::Pool => eprintln!("pool pressure: {}", err),
        ErrorClass::Client | ErrorClass::Permanent => eprintln!("fail fast: {}", err),
    },
}

#[derive(Model, Serialize, Deserialize)]
#[model(table_name = "inventories")]
pub struct Item {
    #[model(primary_key)]
    pub sku: String,
    pub quantity: i32,
    pub last_restock: Option,
}

use chopin_orm::QueryBuilder;

fn find_low_stock(min: i32) -> Vec {
    DB.with(|db| {
        let mut pool = db.borrow_mut();
        QueryBuilder::::new()
            .filter("quantity < $1", vec![min.to_param()])
            .order_by("quantity ASC")
            .limit(50)
            .all(&mut *pool) // Executes on the pool
            .unwrap()
    })
}

use chopin_orm::Transaction;

DB.with(|db| {
    let mut pool = db.borrow_mut();
    let mut conn = pool.get().unwrap();
    let mut tx = Transaction::begin(&mut conn).unwrap();

    item.quantity -= 1;
    item.update(&mut tx).unwrap(); // Part of transaction

    log.record(&mut tx).unwrap();  // Part of transaction

    tx.commit().unwrap();          // Atomic success
});

use chopin_core::websocket;

#[get("/ws")]
fn ws_handler(ctx: Context) -> Response {
    // Validate Upgrade headers and build 101 Switching Protocols response
    match websocket::ws_upgrade(&ctx) {
        Some(resp) => resp,  // 101 — caller should now use the raw fd for frames
        None       => Response::bad_request(),
    }
}

use chopin_core::websocket::{decode_frame, encode_frame, WsMessage, OPCODE_TEXT};

// Decode a received frame from a byte buffer
let (frame, consumed) = decode_frame(&buf)?;

// Build an outgoing text frame
let bytes = encode_frame(OPCODE_TEXT, b"hello from server", false);

// High-level message assembly (handles fragmentation)
let msg = WsMessage::Text("hello".into());

[dependencies]
chopin-core = { version = "0.5.27", features = ["tls"] }

use chopin_core::{get, Context, Response, Chopin};

#[get("/")]
fn index(_ctx: Context) -> Response {
    Response::text("Hello, secure world!")
}

fn main() {
    Chopin::new()
        .mount_all_routes()
        .serve_tls("0.0.0.0:443", "certs/cert.pem", "certs/key.pem")
        .unwrap();
}

Chopin::new()
    .mount_all_routes()
    .with_metrics("/metrics")   // GET /metrics  → Prometheus text format
    .with_health("/health")     // GET /health   → JSON probe (k8s / ALB)
    .serve("0.0.0.0:8080")
    .unwrap();

{"status":"ok","uptime_secs":1234,"workers":8,"requests":9876543,"active_connections":42,"bytes_sent":987654321}

[dependencies]
chopin-core = { version = "0.5.27", features = ["logging"] }

Chopin::new()
    .mount_all_routes()
    .with_logging()    // reads RUST_LOG; default: info
    .serve("0.0.0.0:8080")
    .unwrap();