Crate spring_web 

Axum is one of the best web frameworks in the Rust community. It is a sub-project based on hyper maintained by Tokio. Axum provides web routing, declarative HTTP request parsing, HTTP response serialization, and can be combined with the middleware in the tower ecosystem.

Dependencies

spring-web = { version = "<version>" }

optional features:

• http2: http2
• multipart: file upload
• ws: websocket
• socket_io: SocketIO support
• openapi: OpenAPI documentation
• openapi-redoc: Redoc documentation interface
• openapi-scalar: Scalar documentation interface
• openapi-swagger: Swagger documentation interface

Configuration items

[web]
binding = "172.20.10.4"  # IP address of the network interface to bind, default 0.0.0.0
port = 8000              # Port number to bind, default 8080
connect_info = false     # Whether to use client connection information, default false
graceful = true          # Whether to enable graceful shutdown, default false

# Web middleware configuration
[web.middlewares]
compression = { enable = true }                        # Enable compression middleware
catch_panic = { enable = true }                        # Capture panic generated by handler
logger = { enable = true, level = "info" }             # Enable log middleware
limit_payload = { enable = true, body_limit = "5MB" }  # Limit request body size
timeout_request = { enable = true, timeout = 60000 }   # Request timeout 60s

# Cross-domain configuration
cors = { enable = true, allow_origins = [
    "*.github.io",
], allow_headers = [
    "Authentication",
], allow_methods = [
    "GET",
    "POST",
], max_age = 60 }

# Static resource configuration
static = { enable = true, uri = "/static", path = "static", precompressed = true, fallback = "index.html" }

NOTE: The above middleware configuration can integrate the middleware provided in the tower ecosystem. Of course, if you are very familiar with the tower ecosystem, you can also configure it yourself by writing code without enabling these middleware. The following are relevant document links:

• tower
• tower-http

API interface

App implements the WebConfigurator feature, which can be used to specify routing configuration:

use spring::App;
use spring_web::{get, get_api};
use spring_web::{WebPlugin, WebConfigurator, Router, axum::response::IntoResponse, handler::TypeRouter};
use spring_sqlx::SqlxPlugin;

#[tokio::main]
async fn main() {
    App::new()
      .add_plugin(SqlxPlugin)
      .add_plugin(WebPlugin)
      .add_router(router())
      .run()
      .await
}

fn router() -> Router {
    Router::new().typed_route(hello_word)
}

#[get("/")]
async fn hello_word() -> impl IntoResponse {
   "hello word"
}

/// # The API summary title must use the head-1 in Markdown format.
/// description
/// description support multi line
/// The get_api macro automatically collects the request parameters and response schema.
/// @tag api_tag
#[get_api("/api")]
async fn hello_api() -> String {
   "hello api".to_string()
}

You can also use the auto_config macro to implement automatic configuration. This process macro will automatically register the routes marked by the Procedural Macro into the app:

+#[auto_config(WebConfigurator)]
 #[tokio::main]
 async fn main() {
    App::new()
    .add_plugin(SqlxPlugin)
    .add_plugin(WebPlugin)
-   .add_router(router())
    .run()
    .await
}

-fn router() -> Router {
-    Router::new().typed_route(hello_word)
-}

Attribute macro

In the example above, get is an attribute macro. spring-web provides procedural macros for eight standard HTTP methods: get, post, patch, put, delete, head, trace, and options. It also provides eight macros for generating OpenAPI documentation, such as get_api and post_api.

You can also use the route or api_route macros to bind multiple methods simultaneously:

use spring_web::route;
use spring_web::axum::response::IntoResponse;

#[route("/test", method = "GET", method = "HEAD")]
async fn example() -> impl IntoResponse {
    "hello world"
}

In addition, spring also supports binding multiple routes to a handler, which requires the routes attribute macro:

use spring_web::{routes, get, delete};
use spring_web::axum::response::IntoResponse;

#[routes]
#[get("/test")]
#[get("/test2")]
#[delete("/test")]
async fn example() -> impl IntoResponse {
    "hello world"
}

Extract the Component registered by the plugin

In the above example, the SqlxPlugin plugin automatically registers a Sqlx connection pool component for us. We can use Component to extract this connection pool from State. Component is an axum extractor.

use anyhow::Context;
use spring_web::get;
use spring_web::{axum::response::IntoResponse, extractor::Component, error::Result};
use spring_sqlx::{ConnectPool, sqlx::{self, Row}};

#[get("/version")]
async fn mysql_version(Component(pool): Component<ConnectPool>) -> Result<String> {
    let version = sqlx::query("select version() as version")
        .fetch_one(&pool)
        .await
        .context("sqlx query failed")?
        .get("version");
    Ok(version)
}

Axum also provides other extractors, which are reexported under spring_web::extractor.

Read configuration

You can use Config to extract the configuration in the toml file.

use spring_web::get;
use spring_web::{extractor::Config, axum::response::IntoResponse};
use spring::config::Configurable;
use serde::Deserialize;

#[derive(Debug, Configurable, Deserialize)]
#[config_prefix = "custom"]
struct CustomConfig {
    a: u32,
    b: bool,
}

#[get("/config")]
async fn use_toml_config(Config(conf): Config<CustomConfig>) -> impl IntoResponse {
    format!("a={}, b={}", conf.a, conf.b)
}

Add the corresponding configuration to your configuration file:

[custom]
a = 1
b = true

Complete code reference web-example

Use Extractor in Middleware

You can also use Extractor in middleware, but please note that you need to follow the rules of axum.

use spring_web::{middlewares, axum::middleware};

/// you can apply this middleware to your routes using the `middlewares` macro:
#[middlewares(
    middleware::from_fn(problem_middleware),
)]
mod routes {
    use spring_web::{axum::{response::Response, middleware::Next, response::IntoResponse}, extractor::{Request, Component}};
    use spring_sqlx::ConnectPool;
    use spring_web::{middlewares, get, axum::middleware};
    use std::time::Duration;

    async fn problem_middleware(Component(db): Component<ConnectPool>, request: Request, next: Next) -> Response {
        // do something
        let response = next.run(request).await;

        response
    }

    #[get("/")]
    async fn hello_world() -> impl IntoResponse {
        "hello world"
    }

}

This middleware will:

• Intercept all responses from routes in the module

Complete code reference web-middleware-example

spring-web is a thin wrapper around axum, adding some macros to simplify development. The examples of axum can be run in spring-web.

SocketIO support

You can enable the socket_io feature of spring-web to use a integration with socketioxide.

SocketIO is a implementation of WebSocket with more definitions.

• Named events (like chat message, user joined, etc.) instead of just plain messages
• Automatic reconnection if the connection is lost
• Heartbeat mechanism to detect dead connections
• Rooms / Namespaces to group clients
• Fallbacks to other transports if WebSocket isn’t available

You can refer to the socketio-example for a example of using SocketIO in spring-web.

We can share components registered by plugins in SocketIO handlers, just like in normal HTTP handlers, for example, using the Sqlx connection pool component registered by the SqlxPlugin plugin.

Re-exports

pub use axum;

Modules

config

spring-web config

error

spring-web defined error

extractor

axum extract

handler

axum route handler

middleware

Macros

submit_typed_handler

auto_config

Structs

AppState

State of App

MethodFilter

axum::routing::MethodFilter re-export A filter that matches one or more HTTP methods.

MethodRouter

MethodRouter with AppState A Service that accepts requests based on a MethodFilter and allows chaining additional handlers and services.

WebPlugin

Web Plugin Definition

Traits

WebConfigurator

Web Configurator

Type Aliases

Router

Router with AppState

Routers

Attribute Macros

async_trait

delete

Syntax

get

Syntax

head

Syntax

middlewares

To use these Procedural Macros, you need to add spring-web dependency Applies middleware layers to all route handlers within a module.

nest

Prepends a path prefix to all handlers using routing macros inside the attached module.

options

Syntax

patch

Syntax

post

Syntax

put

Syntax

route

Creates resource handler.

routes

Creates resource handler.

trace

Syntax