ohkami 0.6.0

simple and macro free web framework
Documentation

ohkami - [狼] means wolf in Japanese - is simple and macro free web framework for Rust.

Features

  • simple: Less things to learn / Less code to write / Less time to hesitate.
  • macro free: No need for using macros.
  • async handlers
  • easy error handling

Quick start

  1. Add dependencies:
[dependencies]
ohkami = "0.6.0"
  1. Write your first code with ohkami:
use ohkami::prelude::*;

fn main() -> Result<()> {
    Ohkami::default()
        .GET("/", || async {
            Response::OK("Hello, world!")
        })
        .howl(":3000")
}
  1. If you're interested in ohkami, learn more by examples and documentation !

Snippets

handle query params

let name: &str = c.req.query("name")?;

let count: usize = c.req.query("count")?;

handle request body

fn main() -> Result<()> {
    Ohkami::default()
        .GET("/api/users", reflect)
        .GET("/api/users/name", reflect_name)
        .howl(":3000")
}

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

async fn reflect(user: JSON<User>) -> Result<Response> {
    Response::OK(user)
}

async fn reflect_name(user: JSON<User>) -> Result<Response> {
    let name = user.name;
    // `JSON` implements `Deref`

    Response::OK(name)
}

handle path params

fn main() -> Result<()> {
    Ohkami::default()
        .GET("/sleepy/:time/:name", sleepy_hello)
        .howl("localhost:8080")
}

async fn sleepy_hello(time: u64, name: String) -> Result<Response> {
    (time < 30)
        ._else(|| Response::BadRequest("sleeping time (sec) must be less than 30."))?;
    std::thread::sleep(
        std::time::Duration::from_secs(time)
    );
    Response::OK(format!("Hello {name}, I'm extremely sleepy..."))
}

grouping handlers on the same path (like axum)

use serde::{Serialize, Deserialize};
use ohkami::{
    prelude::*,
    group::{GET, POST} // import this
};

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

fn main() -> Result<()> {
    Ohkami::default()
        .GET("/", || async {
            Response::OK("Hello!")
        })
        .route("/api",
            GET(hello_api).POST(reflect)
        )
        .howl(":3000")
}

async fn hello_api() -> Result<Response> {
    Response::OK("Hello, api!")
}

async fn reflect(payload: JSON<User>) -> Result<Response> {
    Response::OK(payload)
}

parse request headers

let host = c.req.header(Header::Host)
           // or
           c.req.header("Host")

    ._else(|| /* error response */)?;

async fn reflect_header_custom(c: Context) -> Result<Response> {
    let custom_header_value = c.req.header("X-Custom")
        ._else(|| c.BadRequest("header `X-Custom` was not found"))?;
    c.OK(format!("`X-Custom`'s value is {custom_header_value}"))
}

add response headers

c.header(Header::AccessControlAllowOrigin, "mydomain:8000");
// or
c.header("Access-Control-Allow-Origin", "mydomain:8000");

use ohkami::prelude::*;
use Header::{AccessControlAllowOrigin};

async fn cors(c: Context) -> Context {
    c.header(AccessControlAllowOrigin, "mydomain:8000");
    c
}

fn main() -> Result<()> {
    let middleware = Middleware::new()
        .ANY("/api/*", cors);

    // ...

return OK response with text/plain

Response::OK("Hello, world!")
// without Context

c.OK("Hello, world!")
// with Context

return OK response with application/json

Response::OK(json!{"ok": true})
// or
c.OK(json!{"ok": true})

Response::OK(json("Hello!")?)
Response::OK(json(user)?)
//or
c.OK(json("Hello!"))
c.OK(json(user))
// `json()` serializes Rust value into JSON
// value has to implemant `serde::Serialize`

handle errors

make_ohkami_result()?;

// or, you can add an error context message:
make_ohkami_result()
    ._else(|e| e.error_context("failed to get user data"))?;

// or discard original error:
make_ohkami_result()
    ._else(|_| Response::InternalServerError("can't get user"))?;
    // or
    ._else(|_| Response::InternalServerError(None))?;

make_some_result(/* can't use `?` */)
    ._else(|e| Response::InternalServerError(e.to_string()))?;

make_some_result()
    ._else(|_| Response::InternalServerError(None))?;

handle Option values

let handler = self.handler.as_ref()
    ._else(|| Response::NotFound("handler not found"))?;
    // or
    ._else(|| Response::NotFound(None))?;

assert boolean conditions

(count < 10)
    ._else(|| Response::BadRequest("`count` must be less than 10"))?;
    // or
    ._else(|| Response::BadRequest(None))?;

log config

fn main() -> Result<()> {
    let config = Config {
        log_subscribe: Some(
            tracing_subscriber::fmt()
                .with_max_level(tracing::Level::TRACE)
        ),
        ..Default::default()
    };
    Ohkami::new(config)
        .GET("/", || async {Response::OK("Hello!")})
}

DB config

let config = Config {
    db_profile: DBprofile {
        options: PgPoolOptions::new().max_connections(20),
        url:     DB_URL.as_str(),
    },
    ..Default::default()
};

use sqlx

let user = sqlx::query_as::<_, User>(
    "SELECT id, name FROM users WHERE id = $1"
).bind(1)
    .fetch_one(c.pool())
    .await?; // `Response` implements `From<sqlx::Error>`

use middlewares

fn main() -> Result<()> {
    let middleware = Middleware::new()
        .ANY("*", |c| async {
            tracing::info!("Hello, middleware!");
            c
        });

    Ohkami::new(middleware)
        .GET("/", || async {
            Response::OK("Hello!")
        })
        .howl("localhost:3000")
}

fn main() -> Result<()> {
    let config = Config {
        log_subscribe: Some(
            tracing_subscriber::fmt()
                .with_max_level(tracing::Level::TRACE)
        ),
        ..Default::default()
    };

    let middleware = Middleware::new()
        .ANY("/*", |c| async {
            tracing::info!("Hello, middleware!");
            c
        });

    let thirdparty_middleware = some_external_crate::x;

    Ohkami::new(config.and(middleware).and(x))
        .GET("/", || async {
            Response::OK("Hello!")
        })
        .howl("localhost:3000")
}

test

  1. split setup process from main function:
fn server() -> Server {
    Ohkami::default()
        .GET("/", || async {Response::OK("Hello!")})
}

fn main() -> Result<()> {
    server().howl(":3000")
}
  1. import test::Test and other utils
#[cfg(test)]
mod test {
    use ohkami::{Ohkami::Server, response::Response, test::{Test, Request, Method}};
    use once_cell::sync::Lazy;

    static SERVER: Lazy<Server> = Lazy::new(|| super::server());

    #[test]
    fn test_hello() {
        let request = Request::new(Method::GET, "/");
        SERVER.assert_to_res(&request, Response::OK("Hello!"));
        SERVER.assert_not_to_res(&request, Response::BadRequest(None));
    }
}

Development

ohkami is on early stage now and not for producntion use.
Please give me your feedback ! → GetHub issue

License

This project is licensed under MIT LICENSE (LICENSE-MIT or https://opensource.org/licenses/MIT).