AFast

AFast is a high-performance asynchronous Rust backend framework designed to simplify building networked applications. It supports multiple protocols via feature flags and provides automatic code generation for clients (TypeScript and JavaScript), API documentation, and field validation.

Instructions

Supported Protocol Features

You can enable the following features in your Cargo.toml:

• http - enable HTTP support
  • / - Document path (feature flag doc)
  • /api - HTTP API endpoints
  • /code/{service}/{lang} - Client code (feature flag js|ts ...)
  • /doc - Service list (feature flag doc)
  • /doc/{service} - Handler defintions and documentation (feature flag doc)
• ws - enable WebSocket support
  • /ws - WebSocket endpoint
• tcp - enable TCP support
• doc - enable API documentation generation
• js - enable JavaScript client generation (auto enabled code)
• ts - enable TypeScript client generation (auto enabled code)
• code - enable code generation

Note on TCP usage:

If the tcp feature is enabled, the AFast::serve method takes two arguments:

1. The TCP address to listen on ("127.0.0.1:8080").
2. The HTTP/WS address ("127.0.0.1:8081") for web clients and generated JS/TS clients.

This allows you to run TCP and HTTP/WS servers simultaneously in the same application.

Key Features

• handler Macro: Declare HTTP endpoints with minimal boilerplate
  • Automatic TypeScript/JavaScript client generation
  • Namespace support for organized API structure (ns("api.v1.user"))
  • Descriptive API documentation generation (desc("Get user info"))
• Automatic field validation with custom rules
• Async handler functions with state management
• Flexible multi-protocol support: HTTP, WS, TCP

Handler Macro Overview

The #[handler] attribute macro transforms async functions into full-featured API endpoints:

#[handler(desc("Get user information"), ns("api.v1.user"))]
async fn get_user(state: String, header: Header, req: Request) -> Result<Response, Error> {
    // Your business logic
}

Macro Parameters:

• desc("description") - API description for documentation
• ns("api.v1.user") - Namespace for nested JS client generation

Generated Output:

• Type-safe HTTP endpoints
• Nested JavaScript client structure
• TypeScript type definitions
• OpenAPI documentation

Upcoming Features / Development Plan

• Nested structure validation for complex types
• Enable or disable js / ts / document by feature flags
• Add command for generating client code
• Generate client code for additional languages: Java, Kotlin, C#, Rust, etc.
• Improved code generation templates for easier integration
• Enhanced error handling and validation reporting

Example

use afast::{AFast, AFastData, AFastKind, Error, handler, middleware, register};

#[derive(Debug, Clone, AFastData, AFastKind)]
enum Sex {
    Male,
    Female,
    Other(#[validate(desc("Other sex id"))] i64),
    Custom {
        #[validate(desc("Custom sex name"))]
        name: String,
    },
}

#[derive(Debug, Clone, AFastData, AFastKind)]
struct Request {
    #[validate(desc("User ID"))]
    id: i64,
    #[validate(desc("User name"))]
    name: String,
    #[validate(
        desc("User age"),
        required("age is required"),
        min(1, "age must be at least 1"),
        max(256, "age must be at most 256")
    )]
    age: u32,
    #[validate(desc("User hobbies"))]
    hobbies: Vec<Hobby>,
    #[validate(desc("User tags"))]
    tags: Vec<String>,
    #[validate(desc("User gender"))]
    superuser: Option<bool>,
    #[validate(desc("User sex"))]
    sex: Sex,
    #[validate(desc("User number"))]
    number: f64,
}

#[derive(Debug, Clone, AFastData, AFastKind)]
struct Hobby {
    id: i64,
    name: String,
}

#[derive(Debug, AFastData, AFastKind)]
pub struct Response {
    sex: Sex,
    id: i64,
    name: String,
    age: u32,
    hobbies: Vec<Hobby>,
    tags: Vec<String>,
    superuser: Option<bool>,
}

#[handler(desc("Get user information"), ns("api.user"))]
async fn get_user(_state: String, _header: Header, req: Request) -> Result<Response, Error> {
    Ok(Response {
        id: req.id,
        name: req.name.clone(),
        age: req.age,
        hobbies: req.hobbies.clone(),
        tags: req.tags.clone(),
        superuser: req.superuser,
        sex: req.sex.clone(),
    })
}

#[derive(Debug, AFastData, AFastKind)]
struct Req2 {
    id: i64,
}

#[derive(Debug, AFastData, AFastKind)]
struct Resp2 {
    id: i64,
    name: String,
}

#[handler(desc("Get user by id"), ns("api"))]
async fn get_id(_state: String, _header: Header, req: Req2) -> Result<Resp2, Error> {
    Ok(Resp2 {
        id: req.id,
        name: "John".to_string(),
    })
}

#[derive(Debug, Clone, AFastData, AFastKind)]
struct Header {
    token: String,
}

#[middleware]
async fn auth(_state: String, header: Header) -> Result<Header, Error> {
    println!("Token: {:?}", header);
    Ok(header)
}

#[tokio::main]
async fn main() {
    let state = "".to_string();

    let server = AFast::<String, Header>::new(state)
        .service("user", "User service", register! { get_user, get_id })
        .middleware(auth);

    server
        .serve(
            #[cfg(feature = "tcp")]
            &"127.0.0.1:8080",
            #[cfg(any(feature = "http", feature = "ws"))]
            &"127.0.0.1:8081",
        )
        .await
        .unwrap();
}