Crate tokio_fastcgi

source ·
Expand description

Rust Current Version Docs.rs License Apache 2.0

§Async FastCGI handler library

This crate implements a FastCGI handler for Tokio. It’s a complete re-implementation of the FastCGI protocol in safe rust and supports all three FastCGI roles: Responder, Authorizer and Filter. The Role enum documents the different roles and their input and output parameters.

If you just want to use this library, look at the examples, open the documentation and start using it by adding the following to the [dependencies] section of your Cargo.toml:

tokio-fastcgi = "1"

§Principle of operation

The tokio-fastcgi library handles FastCGI requests that are sent by a server. Accepting the connection and spawning a new task to handle the requests is done via Tokio. Within the handler task, Requests::from_split_socket is called to create an asynchronous requests stream. Calling Requests::next().await on this stream will return a new Request instance as soon as it was completely received from the web-server.

The returned Request instance has a process method that accepts an asynchronous callback function or closure that will process the request. The current request will be passed to the callback as a parameter and can be used to retrieve the input streams sent by the web-server and to write to the output streams. The callback returns a result or an error, if processing the request failed.

This is repeated while the Requests instance for the connection returns more requests. If no more requests are returned, the stream will be dropped and the connection to the web-server will be closed.

This library handles connection reuse and aborting requests for the user. See Requests::next for more details.

§Examples

The library contains two examples: A bare bones one and a litte REST API. Just have a look :)

§Changelog

  • Version 1.0.0
    Initial release

  • Version 1.1.0
    Add methods to enumerate the parameters of a request (params_iter and str_params_iter).

  • Version 1.1.1
    Update dependency versions. Make dependency to once_cell less restrictive.

  • Version 1.2.0
    Fix bug #4: Under heavy load, FastCGI responses are not delivered correctly. This makes the FastCGI protocol fail and connections get dropped with various error messages. This release fixes this problem. The tokio-fastcgi library is now stable even under heavy load.

§Basic Example

use tokio::net::TcpListener;
use tokio_fastcgi::{Requests, RequestResult};

#[tokio::main]
async fn main() {
	let addr = "127.0.0.1:8080";
	let listener = TcpListener::bind(addr).await.unwrap();

	loop {
		let connection = listener.accept().await;
		// Accept new connections
		match connection {
			Err(err) => {
				println!("Establishing connection failed: {}", err);
				break;
			},
			Ok((mut stream, address)) => {
				println!("Connection from {}", address);

				// If the socket connection was established successfully spawn a new task to handle
				// the requests that the webserver will send us.
				tokio::spawn(async move {
					// Create a new requests handler it will collect the requests from the server and
					// supply a streaming interface.
					let mut requests = Requests::from_split_socket(stream.split(), 10, 10);

					// Loop over the requests via the next method and process them.
					while let Ok(Some(request)) = requests.next().await {
						if let Err(err) = request.process(|_request| async move {
							// This is the place to handle the FastCGI request and return a result.
							RequestResult::Complete(0)
						}).await {
							// This is the error handler that is called if the process call returns an error.
							println!("Processing request failed: {}", err);
						}
					}
				});
			}
		}
	}
}

Structs§

  • InStream
    Implements a data stream from the web-server to the FastCGI application.
  • OutStream
    Implements a data stream from the FastCGI application to the web-server.
  • Request
    Represents a FastCGI request that can be handled by the application.
  • Requests
    Processes records form an input and output stream.

Enums§

  • Error
    Errors that can be returned by calls to process.
  • RequestResult
    The result of a FastCGI request.
  • Role
    Enum containing the role that is requested from the FastCGI client. See the different variants for a description of the roles and their input and output streams.

Type Aliases§