salvo 0.9.7

A simple web framework
Documentation

build status build status build status codecov crates.io Download License

Salvo is a web server framework written in Rust.

🎯 Features

  • Base on hyper, tokio and async supported;
  • Websocket supported;
  • Middleware is handler and support executed before or after handle;
  • Easy to use routing system, routers can be nested, and you can add middleware in routers;
  • multipart form supported, handle files upload is very simple;
  • Serve a static virtual directory from many physical directories;

⚡️ Quick start

You can view samples here or read docs here.

Create a new rust project:

cargo new hello_salvo --bin

Add this to Cargo.toml

[dependencies]
salvo = "0.9"
tokio = { version = "1", features = ["full"] }

Create a simple function handler in the main.rs file, we call it hello_world, this function just render plain text "Hello World".

use salvo::prelude::*;

#[fn_handler]
async fn hello_world(_req: &mut Request, _depot: &mut Depot, res: &mut Response) {
    res.render_plain_text("Hello World");
}

There are many ways to write function handler.

  • You can omit function arguments if they do not used, like _req, _depot in this example:

    #[fn_handler]
async fn hello_world(res: &mut Response) {
    res.render_plain_text("Hello World");
}

  • Any type can be function handler's return value if it implements Writer. For example &str implements Writer and it will render string as plain text:

    #[fn_handler]
async fn hello_world(res: &mut Response) -> &'static str {// just return &str
    "Hello World"
}

  • The more common situation is we want to return a Result<T, E> to implify error handling. If T and E implements Writer, Result<T, E> can be function handler's return type:

    #[fn_handler]
async fn hello_world(res: &mut Response) -> Result<&'static str, ()> {// return Result
    Ok("Hello World")
}

In the main function, we need to create a root Router first, and then create a server and call it's bind function:

use salvo::prelude::*;

#[fn_handler]
async fn hello_world() -> &'static str {
    "Hello World"
}
#[tokio::main]
async fn main() {
    let router = Router::new().get(hello_world);
    let server = Server::new(router);
    server.bind(([0, 0, 0, 0], 7878)).await;
}

Middleware

There is no difference between Handler and Middleware, Middleware is just Handler.

Tree-like routing system

Router supports nested, and you can add middleware in router. In this example, there are two routers, both of them has same path router "user", and both of them added to the same parent router, to do that because we want to add middleware to them and let them has different access control:

use salvo::prelude::*;

#[tokio::main]
async fn main() {
    let router = Router::new()
        .get(index)
        .push(
            Router::new()
                .path("users")
                .before(auth)
                .post(create_user)
                .push(Router::new().path(r"<id:/\d+/>").post(update_user).delete(delete_user)),
        )
        .push(
            Router::new()
                .path("users")
                .get(list_users)
                .push(Router::new().path(r"<id:/\d+/>").get(show_user)),
        );

    Server::new(router).bind(([0, 0, 0, 0], 7878)).await;
}

#[fn_handler]
async fn index() -> &'static str {
    "Hello world!"
}
#[fn_handler]
async fn auth() -> &'static str {
    "user has authed\n\n"
}
#[fn_handler]
async fn list_users() -> &'static str {
    "list users"
}
#[fn_handler]
async fn show_user() -> &'static str {
    "show user"
}
#[fn_handler]
async fn create_user() -> &'static str {
    "user created"
}
#[fn_handler]
async fn update_user() -> &'static str {
    "user updated"
}
#[fn_handler]
async fn delete_user() -> &'static str {
    "user deleted"
}

File upload

We can get file async by the function get_file in Request:

#[fn_handler]
async fn upload(req: &mut Request, res: &mut Response) {
    let file = req.get_file("file").await;
    if let Some(file) = file {
        let dest = format!("temp/{}", file.filename().unwrap_or_else(|| "file".into()));
        if let Err(e) = std::fs::copy(&file.path, Path::new(&dest)) {
            res.set_status_code(StatusCode::INTERNAL_SERVER_ERROR);
        } else {
            res.render_plain_text("Ok");
        }
    } else {
        res.set_status_code(StatusCode::BAD_REQUEST);
    }
}

Multiple files also very simple:

#[fn_handler]
async fn upload(req: &mut Request, res: &mut Response) {
    let files = req.get_files("files").await;
    if let Some(files) = files {
        let mut msgs = Vec::with_capacity(files.len());
        for file in files {
            let dest = format!("temp/{}", file.filename().unwrap_or_else(|| "file".into()));
            if let Err(e) = std::fs::copy(&file.path, Path::new(&dest)) {
                res.set_status_code(StatusCode::INTERNAL_SERVER_ERROR);
                res.render_plain_text(&format!("file not found in request: {}", e.to_string()));
            } else {
                msgs.push(dest);
            }
        }
        res.render_plain_text(&format!("Files uploaded:\n\n{}", msgs.join("\n")));
    } else {
        res.set_status_code(StatusCode::BAD_REQUEST);
        res.render_plain_text("file not found in request");
    }
}

More Examples

Your can find more examples in examples folder:

Some code and examples port from from warp and multipart-async.

☕ Supporters

Salvo is an open source project. If you want to support Salvo, you can ☕ buy a coffee here.

⚠️ License

Salvo is licensed under either of