Feather Web Framework

Feather Runtime is a high-concurrency web server engine designed to provide a synchronous-feeling development experience without the complexity of async/await or lifetime management.

It achieves high performance through a coroutine-based model using the may crate. Instead of a thread-per-connection model, every incoming connection is assigned its own lightweight coroutine (green thread). Sockets are non-blocking and event-driven: when a coroutine encounters I/O that would normally block, it yields control back to the runtime, allowing other coroutines to execute. This allows the server to handle thousands of concurrent connections while letting developers write standard, synchronous-looking Rust code.

You can use the asterisk (*) wildcard to match any path structure. This is useful for prefix matching (e.g., /api/*) or creating catch-all routes (e.g., /*) for handling 404 errors.

// Match any path starting with /api/
app.get("/api/*", middleware!(|_req, res, _ctx| {
    res.send_text("API route");
    next!()
}));

// Catch-all route
app.get("/*", middleware!(|_req, res, _ctx| {
    res.set_status(404);
    res.send_text("Not found");
    next!()
}));

The #[derive(Claim)] macro is the recommended way to define custom claims. It automatically implements the Claim trait and provides validation for specific attributes:

• #[required]: Ensures the field is not empty.
• #[exp]: Ensures the field is a valid Unix timestamp in the future.

Example structure:

#[derive(Serialize, Deserialize, Claim, Clone)]
pub struct UserClaims {
    #[required]
    pub sub: String,        // Subject (usually user ID)
    #[required]
    pub email: String,      // Custom field
    pub role: String,       // Custom field
    #[exp]
    pub exp: usize,         // Expiration time (automatically validated)
}

Every route handler in Feather is a middleware. You define them using the middleware! macro, which provides three parameters to your closure:

1. req: &mut Request - The incoming HTTP request containing headers, body, and metadata.
2. res: &mut Response - The HTTP response object used to build the response.
3. ctx: &AppContext - The application context for accessing shared state.

Control Flow Macros

• next!(): Continues execution to the next middleware in the chain.
• next_route!(): (v0.8.0+) Skips the current route entirely, useful for logic-based routing.
• end!(): (v0.8.0+) Stops all execution and sends the response immediately.

middleware!(|req, res, ctx| {
    // Process the request
    // Modify the response
    next!() // Continue to next middleware or finish
})

Feather distinguishes between middleware applied to all requests and middleware applied to specific routes.

• Global Middleware: Use app.use_middleware(middleware!(...)) to run logic on every incoming request (e.g., logging).
• Route-specific Middleware: Defined directly within route methods like app.get("/path", middleware!(...)).

// Global middleware
app.use_middleware(middleware!(|req, res, _ctx| {
    println!("Request to: {}", req.uri);
    next!()
}));

// Route-specific middleware
app.get("/", middleware!(|_req, res, _ctx| {
    res.send_text("Home page");
    next!()
}));

By default, Feather catches all unhandled errors and returns a 500 Internal Server Error response to the client. The error is logged to stderr. This occurs when an error is returned from a middleware using the ? operator or similar mechanisms.

use feather::App;

fn main() {
    let mut app = App::new();
    
    // If any error occurs, Feather returns 500
    app.get("/", middleware!(|_req, res, _ctx| {
        std::fs::File::open("non-existingfile.txt")?; // This will send a 500 response to the client
        next!()
    }));
    
    app.listen("127.0.0.1:5050");
}

Feather uses explicit macros to control the execution of the middleware chain:

• next!(): The standard way to move to the next middleware in the current stack.
• next_route!(): (New in 0.8.0) Tells the engine to abandon the current route matching entirely and look for the next path that matches the request.
• end!(): Stops the chain immediately. Use this if you have already sent a response and want to prevent subsequent middleware (like loggers) from executing logic.

Middleware execution order follows this hierarchy:

1. Global middleware: Applied via app.use_middleware(), runs on every request in the order defined.
2. Route-specific middleware: Applied directly to a route or router, runs after global middleware.

Example of applying both:

// Global middleware
app.use_middleware(middleware!(|req, res, _ctx| {
    println!("Request: {} {}", req.method, req.uri);
    next!()
}));

// Route-specific middleware
app.get("/", middleware!(|_req, res, _ctx| {
    res.send_text("Hello");
    next!()
}));