sword-web/sword

Server-side application framework for Rust, built on top of the Tokio ecosystem. Designed to write code with less boilerplate, more simplicity, and cleaner patterns. It leverages the Tokio ecosystem to give you performance with great DX.

Sword is under active development; expect breaking changes.

Features

• Multiple application types - Web, Socket.IO, gRPC, events, and jobs, all able to run together
• Macro-based approach - Clean, intuitive, and declarative macros for defining the application structure
• Built-in validation - Support for the validator crate and an extensible validation system
• Dependency Injection - Built-in DI support with declarative macros
• TOML configuration loader - Built-in support for loading configuration from TOML files

Web Controller Example

use sword::prelude::*;
use sword::web::*;

#[controller(kind = Controller::Web, path = "/users")]
pub struct UsersController {
    hasher: Arc<Hasher>,
    users: Arc<UserRepository>,
}

impl UsersController {
    #[get("/")]
    async fn get_users(&self, req: Request) -> WebResult {
        let data = self.users.find_all().await?;

        Ok(JsonResponse::Ok().data(data).request_id(req.id()))
    }

    #[post("/")]
    async fn create_user(&self, req: Request) -> WebResult {
        let body = req.body_validator::<CreateUserDto>()?;
        let user = User::new(body.username, self.hasher.hash(&body.password)?);

        if self.users.find_by_username(&user.username).await?.is_some() {
            tracing::error!(
                "Attempt to create user with existing username: {}",
                user.username
            );

            Err(AppError::UserConflictError("username", &user.username))?;
        }

        self.users.save(&user).await?;

        Ok(JsonResponse::Created().message("User created").data(user))
    }
}

Full Examples

• Controllers API
• Socket.IO Controllers Chat
• Interceptors (Web + Socket.IO controllers)
• gRPC Application with error handling

Application Features

Sword provides a set of application types based on cargo features:

• web: enables the web application type
• socketio: enables Socket.IO controllers for web applications (implies web)
• grpc: enables the gRPC application type
• events: enables event handling application primitives
• jobs: enables cron/repeated/once job scheduling

Algo gives a set of sub-features for the top-level applications:

Web Features:

• web-multipart: enables multipart/form-data support in web controllers
• web-swagger-ui: enables Swagger UI for OpenAPI specs

Grpc Features:

• grpc-reflection: enables gRPC reflection
• grpc-error-details: enables detailed gRPC errors with GrpcStatus

Events Features:

• events-memory: enables in-memory pub/sub event handling
• events-nats: enables NATS event handling support

Cross type sub-features:

• validation-validator: enables input validation with the validator crate
• hot-reload: enables hot reload during development

Changelog

See CHANGELOG.md for more details.

Contributing

Contributions are welcome! Please open an issue or submit a pull request. See CONTRIBUTING.md for more details.