Salvo Web Framework

Use salvo-serve-static to serve static files and directories within a Salvo web application.

Key capabilities include:

• Automatic Content Type Detection: Automatically detects and sets the correct Content-Type header for files.
• Directory Listing: Supports directory browsing with multiple output formats: HTML, JSON, XML, and Text.
• Compression Support: Serves compressed file variants including Brotli, Gzip, Deflate, and Zstd.
• Embedded Files: Integrates with rust-embed to serve files embedded directly into your Rust binary.

The Salvo ecosystem includes several community-maintained modules for extending functionality:

• Socketioxide: A socket.io server implementation in Rust that integrates with the Tower ecosystem and the Tokio stack.
• Websocket: A websocket tool specifically for Salvo.
• protect-endpoints: A collection of crates designed to protect your endpoints.
• salvo-captcha: A captcha middleware for the Salvo framework.
• salvo-casbin: An access control hook for Salvo using Casbin.
• SalvoRsTool: An Idea RustRover plugin for quickly generating DTO, router, and service template code.

To use the salvo-acme feature in your Salvo project, enable the acme feature flag in your Cargo.toml file.

salvo = { version = "*", features = ["acme"] }

To use OpenAPI support in your Salvo project, you must enable the oapi feature in your Cargo.toml file. This provides the necessary macros and functionality to generate OpenAPI documentation for your web services.

salvo = { version = "*", features = ["oapi"] }

To automatically generate OpenAPI documentation for your endpoints, replace the #[handler] macro with the #[endpoint] macro on your handler functions.

#[endpoint]
async fn hello() -> &'static str {
    "Hello World"
}

To use JWT authentication, enable the jwt-auth feature in your Cargo.toml.

By default, Salvo uses aws-lc-rs as the cryptography provider. If you prefer the RustCrypto provider, disable default features and enable jwt-auth-ring instead.

# Default (AWS-LC)
salvo = { version = "*", features = ["jwt-auth"] }

# Using RustCrypto (Ring)
salvo = { version = "*", default-features = false, features = [
    "server",
    "http1",
    "ring",
    "jwt-auth-ring",
] }

Salvo supports tree-based routing where you can push sub-routers to a parent router. This allows you to apply specific middleware (using .hoop()) to entire branches of your API (e.g., applying authentication only to certain paths).

Router::new()
    // Public routes
    .push(Router::with_path("articles").get(list_articles))
    // Routes requiring authentication
    .push(Router::with_path("articles").hoop(auth_check).post(create_article).delete(delete_article))

To use session management features in your Salvo project, you must enable the session feature in your Cargo.toml file.

salvo = { version = "*", features = ["session"] }

Salvo handlers can automatically deserialize request bodies and return typed JSON responses using serde.

To use this pattern, ensure you have serde with the derive feature added to your project:

cargo add serde --features derive

Example of a JSON POST handler:

use salvo::http::ParseError;
use salvo::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct CreateTodo {
    text: String,
}

#[derive(Serialize)]
struct Todo {
    id: u64,
    text: String,
}

#[handler]
async fn create_todo(req: &mut Request) -> Result<Json<Todo>, ParseError> {
    let payload = req.parse_json::<CreateTodo>().await?;
    Ok(Json(Todo {
        id: 1,
        text: payload.text,
    }))
}

Handlers can deserialize request bodies and return typed JSON responses. To use this pattern, you must add serde with the derive feature to your project.

1. Add dependency:

cargo add serde --features derive

2. Example implementation:

use salvo::http::ParseError;
use salvo::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct CreateTodo {
    text: String,
}

#[derive(Serialize)]
struct Todo {
    id: u64,
    text: String,
}

#[handler]
async fn create_todo(req: &mut Request) -> Result<Json<Todo>, ParseError> {
    let payload = req.parse_json::<CreateTodo>().await?;
    Ok(Json(Todo {
        id: 1,
        text: payload.text,
    }))
}