Middlewares

Relevant source files

The following files were used as context for generating this wiki page:

• src/controller/middleware/mod.rs
• src/controller/middleware/static_assets_embedded.rs
• src/cli.rs
• tests/controller/middlewares.rs
• docs-site/content/blog/frontend-website.md

Middlewares in the Loco framework serve as the foundational layer for request processing, handling cross-cutting concerns such as authentication, logging, CORS, compression, and static asset serving. They are implemented as layers that wrap the application's router, allowing for modular and configurable request/response manipulation.
Sources: src/controller/middleware/mod.rs:1-8

The framework utilizes a "Convention Over Configuration" approach, providing a default stack of common middlewares that can be toggled or customized via the application's configuration files. Middlewares are integrated using the Axum web framework, ensuring high performance and extensibility.
Sources: README.md, src/controller/middleware/mod.rs:88-158

Architecture and Implementation

The MiddlewareLayer Trait

All middlewares in Loco must implement the MiddlewareLayer trait. This trait defines the standard interface for naming, enabling/disabling, and applying the middleware to an AXRouter.
Sources: src/controller/middleware/mod.rs:43-69

This diagram illustrates the relationship between the base trait and specific middleware implementations.
Sources: src/controller/middleware/mod.rs:43-69, src/controller/middleware/static_assets_embedded.rs:136-179

Default Middleware Stack

Loco provides a pre-configured stack of middlewares initialized via the default_middleware_stack function. This stack is ordered to ensure correct processing (e.g., catching panics early).
Sources: src/controller/middleware/mod.rs:88-158

Middleware	Default State	Purpose
LimitPayload	Enabled	Restricts request body size to prevent DoS.
Cors	Disabled	Manages Cross-Origin Resource Sharing.
CatchPanic	Enabled	Recovers from code panics and logs errors.
Etag	Enabled	Handles HTTP cache headers.
Logger	Enabled	Provides request/response tracing and logging.
StaticAssets	Disabled	Serves static files from disk or embedded resources.
Fallback	Env-dependent	Handles missing routes (disabled in Production).
PoweredBy	Enabled	Adds the x-powered-by: loco.rs header.

Sources: src/controller/middleware/mod.rs:92-158, tests/controller/middlewares.rs:373-398

Core Middleware Modules

Static Assets Serving

Loco supports serving static assets through two primary methods: standard file system serving and embedded assets. The embedded asset middleware is useful for distributing single-binary applications.
Sources: src/controller/middleware/static_assets_embedded.rs:1-10

This flowchart describes the logic within the EmbeddedAssets::serve function.
Sources: src/controller/middleware/static_assets_embedded.rs:101-134

CORS (Cross-Origin Resource Sharing)

The CORS middleware allows developers to specify which origins, methods, and headers are permitted for cross-domain requests. Configuration is typically handled via development.yaml or production.yaml.
Sources: tests/controller/middlewares.rs:152-205

Logger and Tracing

The logger middleware integrates with the tracing crate to augment logs with request-specific metadata, such as request IDs. It is environment-aware, allowing for more verbose logging in development.
Sources: src/controller/middleware/mod.rs:136-141, src/cli.rs:563-565

Configuration and CLI Tools

Middlewares are configured globally in the server.middlewares section of the project configuration.
Sources: src/controller/middleware/mod.rs:161-201

server:
  middlewares:
    static:
      enable: true
      must_exist: true
      folder:
        uri: "/"
        path: "frontend/dist"
      fallback: "frontend/dist/index.html"

Sources: docs-site/content/blog/frontend-website.md:124-131

CLI Inspection

The Loco CLI provides a command to list all registered middlewares and their current configuration status.
Sources: src/cli.rs:94-98, src/cli.rs:647-666

$ cargo loco middleware --config

This command iterates through the middleware stack, printing the ID and configuration details for enabled layers.
Sources: src/cli.rs:651-660

Conclusion

Middlewares in Loco provide a robust and flexible way to handle HTTP-level logic. By implementing the MiddlewareLayer trait and utilizing the default stack, developers can ensure their applications are secure, observable, and performant with minimal boilerplate. The integration of static asset serving and configurable CORS makes it particularly well-suited for modern full-stack Rust development.