RFC: Introduce a new validation construct

[Erk-]

Summary

This RFC introduces a new way to handle validation by moving the validation
into the validate crate and exports a new-type that will mean it is
verified.

We also provide a small example program here:
https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=faa5e9fa8447f8bba7e30defc54cce8a

Motivation

Currently the logic behind the validation happens in a separate crate which is
then called from inside of the relevant http functions. One consequence of this
is that there is no way to not use validation for example.

Guide-level explanation

Since a type cannot uniquely describe which validation is needed we introduce
marker struct for different types of validations. For example:

/// Marker for message content validation.
struct MessageContentMarker;

/// Marker for nick name validation.
struct NickNameMarker;

These markers should probably implement a sealed trait to limit what can be used.

Then we introduce struct we can use to wrap validated data in.

struct Validated<T, M> {
    inner: T,
    marker: PhantomData<M>,
}

impl<T, M> Validated<T, M> {
    fn new(inner: T) -> Self {
        Validated {
            inner,
            marker: PhantomData,
        }
    }
}

Then we introduce a trait to validate data, this trait also includes a trait
method, validate_unchecked to skip the validation of data:

trait Validate<Marker> where Self: Sized {
    type Error;

    /// Validate the data.
    fn validate(self) -> Result<Validated<Self, Marker>, Self::Error>;

    /// Skip verification of data.
    fn validate_unchecked(self) -> Validated<Self, Marker> {
        Validated {
            inner: self,
            marker: PhantomData,
        }
    }
}

This is then the methods you call to validate data, the type inference should be able to figure out which trait to call.

Reference-level explanation

Implementations of various validators could look like this:

#[derive(Debug)]
pub struct MessageContentError;

impl Validate<MessageContentMarker> for &str {
    type Error = MessageContentError;

    fn validate(self) -> Result<Validated<Self, MessageContentMarker>, Self::Error> {
        if self.len() > 10 {
            Err(MessageContentError)
        } else {
            Ok(Validated::new(self))
        }
    }
}

#[derive(Debug)]
struct NickNameError;

impl Validate<NickNameMarker> for &str {
    type Error = NickNameError;

    fn validate(self) -> Result<Validated<Self, NickNameMarker>, Self::Error> {
        if self.len() < 5 {
            Err(NickNameError)
        } else {
            Ok(Validated::new(self))
        }
    }
}

Functions taking these values would look like the following:

struct Request<'a> {
    pub content: Option<&'a str>,
    pub nick: Option<&'a str>,
}

impl<'a> Request<'a> {
    // pub fn content(mut self, content: &'a str) -> Result<Self, MessageValidationError>
    pub fn content(mut self, content: Validated<&'a str, markers::MessageContentMarker>) -> Self {
        self.content.replace(content.inner);

        self
    }

    pub fn nick(mut self, nick: Validated<&'a str, markers::NickNameMarker>) -> Self {
        self.nick.replace(nick.inner);

        self
    }
}

Then it is possible to call them in the following fashion with the type
inference selecting the correct verifier:

let mut req = Request::default();

let nick = "Rainbow Dash".validate().unwrap();
let content = "Twilight".validate().unwrap();

req = req.content(content);
req = req.nick(nick);

println!("{}: {}", req.nick.unwrap(), req.content.unwrap());

Drawbacks

This may be seen as making how it works harder to understand, especially with
the type inference.

Rationale and alternatives

The main alternative would be to stay at status quo and keep it the way we have
now.

Prior art

The main prior art of this in Rust is the validity crate which implementes
somthing similar. The main difference from the method described in this RFC is
that we use marker structs.

Unresolved questions

• Validate or Verify? Validate as that is what is already used.

Future possibilities

• No ideas for now.

[Erk-]

A couple of things I have been thinking about since I posted the RFC:

Pre-Validate built constructs

This RFC would make it possible to pre-validate objects built by the builder thus not doing the same work twice.

Staged rollout

We could get around much of the breaking changes this would cause initially by first changing the signatures to use TryInto though that would mean that they still have to return a result.

[7596ff]

Unresolved questions

Validate or Verify?

I'm pretty set on naming everything under the root validate. Verification is a different concept, which is also present in the Discord ecosystem.

[Erk-]

Unresolved questions
Validate or Verify?

I'm pretty set on naming everything under the root validate. Verification is a different concept, which is also present in the Discord ecosystem.

Changed the RFC to now use validate.

[Erk-]

Example implementation of it here: https://github.com/twilight-rs/twilight/tree/erk-/validate-rfc-impl, I have found some changes I have to make to the RFC when making that and I will update it soon