Crate blazing_agi 

blazing_agi is a fast, ergonomic and correct FastAGI Server.

blazing_agi requires the use of tokio. Executor independence is currently not a goal. blazing_agi does not currently contain definitions for all AGI commands. Please file an issue or a PR if you want one added.

To get started, consider this “Hello World” example:

use blazing_agi::{command::{verbose::Verbose}, router::Router, serve};
use blazing_agi_macros::create_handler;
use tokio::net::TcpListener;

// The create_handler macro is used to turn an async fn into a handler.
// Make sure to use the same signature as here (including the variable names, but not the function
// name)
#[create_handler]
async fn foo(connection: &mut Connection, request: &AGIRequest) -> Result<(), AGIError> {
    connection.send_command(Verbose::new("Hello There".to_owned())).await?;
    Ok(())
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create the router from the handlers you have defined
    let router = Router::new()
        .route("/script", foo);
    let listener = TcpListener::bind("0.0.0.0:4573").await?;
    // Start serving the Router
    serve::serve(listener, router).await?;
    Ok(())
}

You can find a more elaborate example in examples/layer-agi-digest.rs.

In general, blazing_agi works by defining AGIHandler (read: scripts). You then combine them into Routers. They define which requested uri is handled by which handler. An AGIHandler takes:

• a &mut Connection - this is a wrapper around a tokio TcpStream, which handles sending Commands and parsing the response
• a & AGIRequest - this contains the data send in the initial request made by the client (asterisk).

An AGIHandler can then use the Connection::send_command function to send commands to the client. When it is done, the Handler simply returns Ok(()) to signal that the execution was successful and the stream can be terminated. If an error is encountered that the Handler does not want to handle, it can be bubbled up as AGIError, which tells the runtime that something went wrong - the stream is also closed.

Modules

command

This module contains all AGI commands that can be sent.

connection

This module handles the literal network connection and sends/receives packets.

handler

Defines the AGIHandler, the most basic instrument for answering FastAGI requests.

layer

Defines the Layer, a way to transform an AGIHandler into another one.

router

The Router is the basic element describing a service you may want to run. A Router is made up of AGIHandlers at some paths, potentially with Layers to apply logic to multiple routes at once.

serve

Serve an existing Router.

Structs

AGIRequest

The Data sent with the request.

Enums

AGIError

Contains all the ways in which serving a FastAGI Request can fail.