Struct Request 

pub struct Request<W: AsyncWrite + Unpin> {
    pub role: Role,
    /* private fields */
}

Represents a FastCGI request that can be handled by the application.

An instance of this struct is returned by the next function of the Requests struct. It represents one request that should be handled via FastCGI. Normally process is called on every instance that is returned. The request gets passed to the callback function and can be used to get the input/output streams and environment values.

Fields

role: Role

Contains the role that this request is requesting from the FastCGI application.

If the FastCGI application can not comply to this role the callback passed to process should return RequestResult::UnknownRole.

Implementations

impl<W: AsyncWrite + Unpin> Request<W>

pub fn get_param(&self, name: &str) -> Option<&Vec<u8>>

Returns the parameter with the given name as a byte vector.

Parameters are passed to the FastCGI application as name value pairs. Parameters can contain environment variables or other parameters that the web-server wants to pass to the application.

If the parameter does not exist None is returned.

Example

request.process(|request| async move {
  if let Some(binary_data) = request.get_param("BINARY_DATA") {
    assert_eq!(binary_data, &[10, 20, 30]);
  }

  RequestResult::Complete(0)
});

pub fn get_str_param(&self, name: &str) -> Option<&str>

Returns the parameter with the given name as a UTF-8 string.

Parameters are passed to the FastCGI application as name value pairs. Parameters can contain environment variables or other parameters that the web-server wants to pass to the application.

If the parameter does not exist or is not valid UTF-8 None is returned.

Example

request.process(|request| async move {
  if let Some(uri) = request.get_str_param("REQUEST_URI") {
    assert_eq!(uri, "/index.html");
  }

  RequestResult::Complete(0)
});

pub fn params_iter( &self, ) -> Option<Box<dyn Iterator<Item = (&'_ str, &'_ [u8])> + '_>>

Returns an iterator over all parameters.

The parameter value is a u8 slice containing the raw data for the parameter. If you need the parameter values as string, take a look at str_params_iter.

Example

request.process(|request| async move {
  if let Some(params) = request.params_iter() {
    // Output a list of all parameters
    for param in params {
      println!("{}: {:?}", param.0, param.1);
    }
  }

  RequestResult::Complete(0)
});

pub fn str_params_iter( &self, ) -> Option<Box<dyn Iterator<Item = (&'_ str, Option<&'_ str>)> + '_>>

Returns an iterator over all parameters that tries to convert the parameter values into strings.

The parameter value is an Option containing a String reference. If the parameter could not be converted into a string (because it is not valid UTF8) the Option will be None.

Example

request.process(|request| async move {
  if let Some(params) = request.str_params_iter() {
    // Output a list of all parameters
    for param in params {
      println!("{}: {}", param.0, param.1.unwrap_or("[Invalid UTF8]"));
    }
  }

  RequestResult::Complete(0)
});

pub fn get_request_id(&self) -> u16

Returns the request id of this request.

This id is unique within the current connection. It is managed by the web-server.

pub fn get_stdout(&self) -> OutStream<W>

Allows the process closure to write to StdOut.

Returns an OutStream instance that will send StdOut records back to the web-server.

Example

request.process(|request| async move {
  let mut stdout = request.get_stdout();

  assert!(stdout.write(b"Hello World").await.is_ok());

  RequestResult::Complete(0)
});

pub fn get_stderr(&self) -> OutStream<W>

Allows the process closure to write to StdErr.

Returns an OutStream instance that will send StdErr records back to the web-server. What is done with the data that is sent to StdErr depends on the web-server.

Example

request.process(|request| async move {
  let mut stderr = request.get_stderr();

  assert!(stderr.write(b"Hello World").await.is_ok());

  RequestResult::Complete(0)
});

pub fn get_stdin(&self) -> OwnedInStream<'_>

Allows the process closure to read from StdIn.

Returns an InStream instance that will read the data passed as StdIn by the web-server.

Example

request.process(|request| async move {
  let mut stdin = request.get_stdin();

  let mut buffer = Vec::with_capacity(10);
  assert!(stdin.read(&mut buffer).is_ok());

  assert_eq!(buffer.len(), 10);

  RequestResult::Complete(0)
});

pub fn get_data(&self) -> OwnedInStream<'_>

Allows the process closure to read from the Data stream.

Returns an InStream instance that will read the data passed as a Data stream by the web-server.

Example

request.process(|request| async move {
  let mut data = request.get_data();

  let mut buffer = Vec::with_capacity(10);
  assert!(data.read(&mut buffer).is_ok());

  assert_eq!(buffer.len(), 10);

  RequestResult::Complete(0)
});

pub async fn process<F: Future<Output = RequestResult>, C: FnOnce(Arc<Self>) -> F>( self, callback: C, ) -> Result<(), Error>

Processes a FastCGI request.

As soon as a request is completely received it is returned by Requests::next. Calling process on this request allows the request to be processed. The application logic is passed to process via a callback function.

The callback function gets a reference to the Request instance that contains all necessary information (input-/output-streams, parameters, etc.) for processing the request.

See the examples directory for a complete example for using this function.

Callback function

The callback function can access all information about the request via the passed request parameter. The return value can be one of the following values:

• RequestResult::Complete
• RequestResult::Overloaded
• RequestResult::UnknownRole

Example

let mut requests = Requests::new(instream, outstream, 1, 1);

while let Some(request) = requests.next().await.expect("Request could not be constructed.") {
  request.process(|request| async move {

    // Process request

    RequestResult::Complete(0)
  });
}

Trait Implementations

impl<W: AsyncWrite + Unpin> Debug for Request<W>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.