axial-rs

Axial - All in One web framework for Rust.

[!NOTE] All in One - everything you need to develop web servers in one framework

The framework is inspired by Ruby on Rails

Usage

To specify server routes, the #[axial_macros::get("/path")] macro (or another type) is used. Next is the function that describes this route:

#[get("/user/{id}")]
async fn get_user_details(req: Request) -> impl Responder {
    let user_id_str = req.path_params.get("id").cloned().unwrap_or_default();

    let version_str = req.query_param("version");

    let mut response_body = format!("User ID: {}", user_id_str);
    if let Some(v) = version_str {
        response_body.push_str(&format!(", Version (from query): {}", v));
    } else {
        response_body.push_str(", Version (from query): not specified");
    }

    Response::new(200).body(response_body)
}

async and returning impl Responder are mandatory!

The code is quite similar to actix_web, but the goal of my framework is to put everything necessary in one place, providing a convenient API.

Structures

Response:

This structure provides access to the response to a request. Methods:

• body(String) - sets the body of the request;
• status(u16) - response status;
• header(impl Into, value: impl Into) - sets the response header;
• cookie(impl Into, value: impl Into) - sets a cookie to the response;
• new(u16) - response constructor. Takes the response status as input.

All functions return the Response structure.

Request:

This structure provides access to the request. You can get data from a specific request like this:

async fn greet(req: Request) -> impl Responder

req will give you access to the request fields:

• body - access to the request body. Returns String;
• headers - access to the request headers. Returns Vec<(String, String)>;
• method - access to the method by which the request came. Returns enum Methods;

pub enum Methods {
    GET,
    POST,
    PUT,
    DELETE,
}

• path - access to the request path. Returns String;
• path_params - access to the path fields (those that you specify via {name} in the path of the macro: #[get("/user/{id} = /user/1). Returns Arc<HashMap<String, String, RandomState>, Global>;
• query_string - access to the path parameters (those specified in the request via ?: /user?name=somename. Returns Option

Starting the server

HttpServer::new(String::from("127.0.0.1"), 9092).service(get_user_details)
        .service(post_user_details).start()
        .await.map_err(|e| {
            eprintln!("Error on start server: {e}")
        }).unwrap();

The server constructor is called via HttpServer::new(host: String, port: u16);

Each route function is specified via the .service() function (1 function = 1 service() call);

The server is started by the start() function - an asynchronous function that can return an error, so it should be handled in the code.

Client

Access to client functionality can be obtained using feature = "client".

Example:

async fn client() -> String {
    let client = HttpClient::new()
        .timeout(Some(std::time::Duration::from_secs(5)))
        .user_agent(Some(axial::core::clients::http::USER_AGENT_CHROME.to_string()))
        .header("X-Custom-Header", "value")
        .build()
        .unwrap();

    let response = client.get("https://google.com/").await.unwrap();

    response
}

• HttpClient::new() - client constructor call;
• timeout(Option<std::time::Duration>) - specifies the timeout;
• user_agent(Option<String>) - specifies the user agent for the request. The framework has (at the time of publication) two constants (one for each OS available under one name): USER_AGENT_CHROME and USER_AGENT_FIREFOX.

#[cfg(target_os = "windows")] pub const USER_AGENT_CHROME: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36";
#[cfg(target_os = "linux")] pub const USER_AGENT_CHROME: &str = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36";
#[cfg(target_os = "macos")] pub const USER_AGENT_CHROME: &str = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/136.0.0.0 Safari/537.36";

#[cfg(target_os = "windows")] pub const USER_AGENT_FIREFOX: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:137.0) Gecko/20100101 Firefox/137.0";
#[cfg(target_os = "macos")] pub const USER_AGENT_FIREFOX: &str = "Mozilla/5.0 (Macintosh; Intel Mac OS X 14.7; rv:128.0) Gecko/20100101 Firefox/128.0";
#[cfg(target_os = "linux")] pub const USER_AGENT_FIREFOX: &str = "Mozilla/5.0 (X11; Linux i686; rv:128.0) Gecko/20100101 Firefox/128.0";

• build() - will build the client. Returns Result<HttpClient, String>, so you need to handle the error.

You can send requests:

• client.get(url: &str) - get request to the link. The function receives (in addition to the link) self, so the example uses client: HttpClient;
• client.post(url: &str, body: &String) - post request to the link (with body);
• client.put(url: &str, body: &String) - put request to the link (with body);
• client.delete(url: &str) - delete request to the link.

All functions are asynchronous and return Result<String, String> - the response body.

A little about the attribute to the routes:

This get, post, etc. are procedural macros that translate your asynchronous function into a structure and make an implementation for it, which then goes to core::routes::router::RouteFactory and is adapted for the server. The serivce() passes exactly the generic type routes::router::RouteFactory.

Installation

Classic:

• cargo add axial
• cargo add axial_macros

If you also need a client:

• cargo add axial --features=client