How salvo-rs/salvo works
Based on our analysis of the complete file tree and the README, this project is an open‐source web backend framework written in Rust (called “Salvo”) that is extremely modular and extensible. It is designed as a full‐featured server framework with support for HTTP1/2/3, middleware chaining, ACME-based automatic TLS, routing, and even integration with OpenAPI and more. The project is partitioned into many separate crates, each encapsulating a specific functionality or service (for example, “core”, “cache”, “compression”, “cors”, “csrf”, “flash”, “jwt-auth”, “oapi”, etc.) while also providing a consistent API for the end developer.
Main Components
• Client Interface: Illustrate external HTTP/HTTPS/HTTP3 clients that connect via TCP.
• Listener/Server: Represent the TCP listeners that bind to various ports (80, 443, etc.) and include support for multiple transport protocols (using underlying libraries like native_tls, rustls, quinn, openssl).
• Core Engine: Identify the “core” crate, which contains modules for connection management, HTTP request/response handling, routing, middleware processing, error handling, and extraction.
• Middleware Layer: Show how middleware functions (which are essentially handlers themselves) are applied before or after the main business logic. This includes middleware for adding headers, authentication checks, logging, error handling, etc.
• Utilities and Extensions: Illustrate supporting crates such as “cache”, “compression”, “cors”, “csrf”, “flash”, “jwt-auth”, “rate-limiter”, “serve-static”, “session” and “extra”. These add specialized functionality and plug into the overall request handling and response pipeline.
• Interface/DSL Macros: Include the “craft-macros”, “oapi-macros”, and “macros” crates that provide custom derive traits, attribute macros, and OpenAPI documentation integration.
• OpenAPI and Documentation: Represent the components (found inside “oapi” and associated macros) that automatically generate and serve OpenAPI documentation.
• External Dependencies: Note the reliance on the Tokio asynchronous runtime and Hyper as well as integration with other services (e.g., external proxies, OpenTelemetry for tracing, etc.).
Relationships and Interactions
• From the TCP listener, show the data flow into the “core” module where connection handling and protocol negotiation happens (sometimes via separate modules based on the TLS/HTTP version).
• Inside the core, branch off to the routing module responsible for mapping the inbound request to the correct handler or middleware chain.
• Middleware components (possibly as overlays on the routing paths) indicating that these can be attached to any route to modify requests/responses.
• Link utilities (cache, compression, CSRF, etc.) to the core flow to illustrate the extension points.
• Provide a separate block for OpenAPI generation and documentation, showing its connection to the router and the endpoint handlers.
• Support for various TLS libraries within the connection handling part (native_tls, openssl, rustls, quinn).
Architectural Patterns/Design Principles
• Layered Architecture: Separate concerns by isolating the transport (TCP/HTTP) from application-level routing and middleware.
• Modular Design: Illustrate how the project is divided into many crates, each encapsulating unique functionality.
• Middleware as a First-class Citizen: Indicate the chainable and composable nature of middleware (no distinction between middleware and handler).
• Protocol Abstraction: Demonstrate support for multiple protocols (HTTP1, HTTP2, HTTP3) by abstracting over the underlying protocol-specific modules.