Crate axum_messages

This crate provides one-time notification messages, or flash messages, for axum applications.

Example

use std::net::SocketAddr;

use axum::{
    response::{IntoResponse, Redirect},
    routing::get,
    Router,
};
use axum_messages::{Messages, MessagesManagerLayer};
use tower_sessions::{MemoryStore, SessionManagerLayer};

async fn set_messages_handler(messages: Messages) -> impl IntoResponse {
    messages
        .info("Hello, world!")
        .debug("This is a debug message.");

    Redirect::to("/read-messages")
}

async fn read_messages_handler(messages: Messages) -> impl IntoResponse {
    let messages = messages
        .into_iter()
        .map(|message| format!("{}: {}", message.level, message))
        .collect::<Vec<_>>()
        .join(", ");

    if messages.is_empty() {
        "No messages yet!".to_string()
    } else {
        messages
    }
}

#[tokio::main]
async fn main() {
    let session_store = MemoryStore::default();
    let session_layer = SessionManagerLayer::new(session_store).with_secure(false);

    let app = Router::new()
        .route("/", get(set_messages_handler))
        .route("/read-messages", get(read_messages_handler))
        .layer(MessagesManagerLayer)
        .layer(session_layer);

    let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
    let listener = tokio::net::TcpListener::bind(&addr).await.unwrap();
    axum::serve(listener, app.into_make_service())
        .await
        .unwrap();
}

Design

This library, while compact and straightforward, benefits from an understanding of its design and its integration with core web application fundamentals like HTTP.

How Messages are Managed

Messages in this library are written during one HTTP request and are accessible only in subsequent requests. This lifecycle management is handled transparently by the library, ensuring simplicity for the consuming application.

At first glance, this approach might seem to limit functionality: if messages are delayed until the next request, how does this not result in lost presentation state during user interactions? This is where the state management capabilities of HTTP sessions come into play.

Use of Sessions for State Management

HTTP is a stateless protocol, but managing state over HTTP is a long-solved problem with various effective solutions, sessions being one of the most prominent. This library leverages sessions to maintain state, allowing messages to persist between requests without affecting the continuity of the user experience.

Sessions can handle complex state scenarios, and when used in conjunction with HTTP, they provide a robust foundation for modern, feature-rich web applications. This library slots naturally into this well-established paradigm by serializing state to and from the session.

Practical Example: Managing User Registration State

To better illustrate the concept, consider an application that uses axum-messages with an HTML user registration form containing inputs for the user’s name, desired username, and password.

• GET Request: When users navigate to /registration, the server renders the form.
• POST Request: Users submit the form, which is then sent to /registration where the server processes the data.

During form processing, if the desired username is unavailable, the server sets a flash message indicating the issue and redirects back to the /registration URL. However, instead of presenting a blank form upon redirection, the server can utilize the session to repopulate the form fields with previously submitted data (except for sensitive fields like passwords). This not only enhances user experience by reducing the need to re-enter information but also demonstrates efficient state management using sessions.

By integrating messages and form data into sessions, we facilitate a smoother and more intuitive interaction flow, illustrating the powerful synergy between state management via sessions and HTTP’s stateless nature.

Structs

• Message
  Container for a message which provides a level and message content.
• Messages
  An extractor which holds the state of messages, using the session to ensure messages are persisted between requests.
• MessagesManager
  MIddleware provider Messages as a request extension.
• MessagesManagerLayer
  Layer for MessagesManager.

Enums

• Level
  Enumeration of message levels.

Type Aliases

• Metadata
  Mapping of key-value pairs which provide additional context to the message.