Struct tide_disco::request::RequestParams

pub struct RequestParams { /* private fields */ }

Parameters passed to a route handler.

These parameters describe the incoming request and the current server state.

Implementations

impl RequestParams

pub fn method(&self) -> Method

The Method used to dispatch the request.

pub fn headers(&self) -> &Headers

The headers of the incoming request.

pub fn accept(&self) -> Result<Accept, RequestError>

The [Accept] header of this request.

The media type proposals in the resulting header are sorted in order of decreasing weight.

If no [Accept] header was explicitly set, defaults to the wildcard Accept: *.

Error

Returns RequestError::Http if the [Accept] header is malformed.

pub fn remote(&self) -> Option<&str>

Get the remote address for this request.

This is determined in the following priority:

1. Forwarded header for key
2. The first X-Forwarded-For header
3. Peer address of the transport

pub fn param<Name>( &self, name: &Name, ) -> Result<&RequestParamValue, RequestError>

where Name: ?Sized + Display,

Get the value of a named parameter.

The name of the parameter can be given by any type that implements Display. Of course, the simplest option is to use str or String, as in

req.param("foo")

However, you have the option of defining a statically typed enum representing the possible parameters of a given route and using enum variants as parameter names. Among other benefits, this allows you to change the client-facing parameter names just by tweaking the Display implementation of your enum, without changing other code.

use std::fmt::{self, Display, Formatter};

enum RouteParams {
    Param1,
    Param2,
}

impl Display for RouteParams {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        let name = match self {
            Self::Param1 => "param1",
            Self::Param2 => "param2",
        };
        write!(f, "{}", name)
    }
}

req.param(&RouteParams::Param1)

You can also use [strum_macros] to automatically derive the Display implementation, so you only have to specify the client-facing names of each parameter:

#[derive(strum_macros::Display)]
enum RouteParams {
    #[strum(serialize = "param1")]
    Param1,
    #[strum(serialize = "param2")]
    Param2,
}

req.param(&RouteParams::Param1)

Errors

Returns RequestError::MissingParam if a parameter called name was not provided with the request.

It is recommended to implement From<RequestError> for the error type for your API, so that you can use ? with this function in a route handler. If your error type implements Error, you can easily use the catch_all constructor to do this:

use serde::{Deserialize, Serialize};
use snafu::Snafu;
use tide_disco::{Error, RequestError, RequestParams, StatusCode};

type ApiState = ();

#[derive(Debug, Snafu, Deserialize, Serialize)]
struct ApiError {
    status: StatusCode,
    msg: String,
}

impl Error for ApiError {
    fn catch_all(status: StatusCode, msg: String) -> Self {
        Self { status, msg }
    }

    fn status(&self) -> StatusCode {
        self.status
    }
}

impl From<RequestError> for ApiError {
    fn from(err: RequestError) -> Self {
        Self::catch_all(StatusCode::BAD_REQUEST, err.to_string())
    }
}

async fn my_route_handler(req: RequestParams, _state: &ApiState) -> Result<(), ApiError> {
    let param = req.param("my_param")?;
    Ok(())
}

pub fn opt_param<Name>(&self, name: &Name) -> Option<&RequestParamValue>

where Name: ?Sized + Display,

Get the value of a named optional parameter.

Like param, but returns None instead of Err if the parametre is missing.

pub fn integer_param<Name, T>(&self, name: &Name) -> Result<T, RequestError>

where Name: ?Sized + Display, T: TryFrom<u128>,

Get the value of a named parameter and convert it to an integer.

Like param, but returns Err if the parameter value cannot be converted to an integer of the desired size.

pub fn opt_integer_param<Name, T>( &self, name: &Name, ) -> Result<Option<T>, RequestError>

where Name: ?Sized + Display, T: TryFrom<u128>,

Get the value of a named optional parameter and convert it to an integer.

Like opt_param, but returns Err if the parameter value cannot be converted to an integer of the desired size.

pub fn boolean_param<Name>(&self, name: &Name) -> Result<bool, RequestError>

where Name: ?Sized + Display,

Get the value of a named parameter and convert it to a bool.

Like param, but returns Err if the parameter value cannot be converted to a bool.

pub fn opt_boolean_param<Name>( &self, name: &Name, ) -> Result<Option<bool>, RequestError>

where Name: ?Sized + Display,

Get the value of a named optional parameter and convert it to a bool.

Like opt_param, but returns Err if the parameter value cannot be converted to a bool.

pub fn string_param<Name>(&self, name: &Name) -> Result<&str, RequestError>

where Name: ?Sized + Display,

Get the value of a named parameter and convert it to a string.

Like param, but returns Err if the parameter value cannot be converted to a String.

pub fn opt_string_param<Name>( &self, name: &Name, ) -> Result<Option<&str>, RequestError>

where Name: ?Sized + Display,

Get the value of a named optional parameter and convert it to a string.

Like opt_param, but returns Err if the parameter value cannot be converted to a String.

pub fn tagged_base64_param<Name>( &self, name: &Name, ) -> Result<&TaggedBase64, RequestError>

where Name: ?Sized + Display,

Get the value of a named parameter and convert it to [TaggedBase64].

Like param, but returns Err if the parameter value cannot be converted to [TaggedBase64].

pub fn opt_tagged_base64_param<Name>( &self, name: &Name, ) -> Result<Option<&TaggedBase64>, RequestError>

where Name: ?Sized + Display,

Get the value of a named optional parameter and convert it to [TaggedBase64].

Like opt_param, but returns Err if the parameter value cannot be converted to [TaggedBase64].

pub fn blob_param<'a, Name, T>(&'a self, name: &Name) -> Result<T, RequestError>

where Name: ?Sized + Display, T: TryFrom<&'a TaggedBase64>, <T as TryFrom<&'a TaggedBase64>>::Error: Display,

Get the value of a named parameter and convert it to a custom type through [TaggedBase64].

Like param, but returns Err if the parameter value cannot be converted to T.

pub fn opt_blob_param<'a, Name, T>( &'a self, name: &Name, ) -> Result<Option<T>, RequestError>

where Name: ?Sized + Display, T: TryFrom<&'a TaggedBase64>, <T as TryFrom<&'a TaggedBase64>>::Error: Display,

Get the value of a named optional parameter and convert it to a custom type through [TaggedBase64].

Like opt_param, but returns Err if the parameter value cannot be converted to T.

pub fn body_bytes(&self) -> Vec<u8>

pub fn body_json<T>(&self) -> Result<T, RequestError>

where T: DeserializeOwned,

pub fn body_auto<T, VER: StaticVersionType>( &self, _: VER, ) -> Result<T, RequestError>

where T: DeserializeOwned,

Deserialize the body of a request.

The Content-Type header is used to determine the serialization format.

Trait Implementations

impl Clone for RequestParams

fn clone(&self) -> RequestParams

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for RequestParams

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

Formats the value using the given formatter.