Assayer

a•SEY•er, n.

1. A detailed report of the findings in analysis of a substance
2. An unfortunate person whose job it was to taste test royal food, in case of poison
3. Static (compile-time) validation library for Rust

Motivation

Frequently, programs need to process untrusted input. Before doing so, it is important to ensure that the values being processed are, in fact, valid for the purpose for which they are intended.

Examples include values representing the hour of the day, the day of the month, a person's age, a URL, phone number, and so on. Regardless of the underlying data type (integer, string, custom struct, etc.) some values are valid, and some are not.

As a validation library, Assayer allows you to build efficient, highly cohesive code by concentrating your custom validation logic to one place--your validator. You can create any number of validators for each of the different types in your application requiring validation.

How to Use

Quickstart

• Define your custom validator (eg. for non-empty strings) by implementing ValidatorRef and/or ValidatorMutRef and/or Validator depending on the move/copy/mutability semantics you want. Here is an example using ValidatorRef:

extern crate assayer;
use assayer::{ValidatorRef, ValidatorMutRef, Validator};  //Ok to import just the one(s) you want to use
use assayer::{MethodSyntaxValidatorRef, MethodSyntaxValidatorMutRef, MethodSyntaxValidator}; //ditto
use assayer::Error as AssayerError;

struct NonEmptyString;  //A dummy custom type to validate

impl ValidatorRef<String> for NonEmptyString {
    fn validate_ref(input: &String) -> std::result::Result<&String, AssayerError> {
        Ok(input)
            .and_then(|input| match !input.is_empty() {
                true => Ok(input),
                false => Err(AssayerError::ValueEmpty("<Validation failure message here>".to_string())),
            })

        // Chain as many additional .and_then() clauses as you need to validate your input.
        // Each validation clause in the .and_then() chain must return:
        //   * Ok(input) if the value passes that validation step or
        //   * Err(String) if the value fails that validation step.
        // A clause in a Result::and_then() chain which returns Err() will terminate further validation processing
        // and the returned Err() will be returned to the caller.

        //.and_then(|input| ...test #2...)
        //...
        //.and_then(|input| ...test #n...)
    }
}

To call the the validator, use either the function- or method-call syntax illustrated below:

    //Function-call syntax example
    let empty_string = String::new();
    let function_call_syntax_result = String::validate_ref::<NonEmptyString>(&empty_string);
    assert_eq!(function_call_syntax_result.err(),
               Some(AssayerError::ValueEmpty("<Validation failure message here>".to_string())));

    //Method-call syntax example
    let non_empty_string = "Not an empty string".to_string();
    let method_call_syntax_result = (&non_empty_string).validate_ref::<NonEmptyString>();
    assert_eq!(method_call_syntax_result.ok(), Some(&non_empty_string));

Usage note: The above is just a quick example to illustrate how to set up can call the library. In practice, you could have your custom type's constructor(s) call the validator on any input parameters, so that the type, once successfully constructed, could provide strong guarantees that its contents are always valid.

FAQ

What are some of Assayer's design goals?

• Lightweight, Zero Dependencies

Languages have long been heading down the path of pulling in other "modules" and building on top of them (the Javascript community is particularly notable in this regard). Rust's Cargo and crate system brings easy dependencies to Rust, which we fully welcome. At the same time, we are fans of beautiful, maintainable, predictable, small focuse code. When less code can do more, we think that kind of efficiency gain is particularly elegant. So the library ended up being a grand total of six trait definitions, plus three blanket impls and no dependencies.

• Facilitating High Cohesion, Single-Responsiblity and Don't Repeat Yourself Principles

A validator allows you to factor out all your checking into pre-conditions all in one place. When all the code in a routine is focused on achieving the same goal, you get high cohesion, which as been shown to be very beneficial to the reliability and maintainability of a codebase.

By focusing only validation code into a validator, the validator becomes responsible for just one thing: validation. The single-responsibility principle helps to keep the code from growing into a "god object", which, if you've ever had the pleasure of working with, we're sure you'll agree you don't want to go back any time soon!

• Static (compile-time) validator

As a static validator, the validation chain you create is able to fully benefit from the compiler optimizers. A dynamic validator using, for example, the builder pattern at run-time cannot realize these benefits, because the validation chain does not exist as a chain at compile time.

We thought about various use-cases, and could not think of a drawback for static validators. If you come across a compelling case for dynamic validators, please let us know!

What is the difference between function-call syntax and method-call syntax?

From a code perspective, none. (For the tests we've run under Rust v1.18.0, the compiler emits 100% identical assembly instructions.)

From a personal perspective, you may be more comfortable with one style or the other, or it may be convenient to use one particular style or the other under specific circumstances. The choice is yours.

When should I implement Validator vs. ValidatorRef vs. ValidatorMutRef?

Implementing Validator means that your validator will consume the value being passed by the caller:

impl Validator<String> for NonEmptyString {
    fn validate(input: String) -> std::result::Result<String, AssayerError> {
        Ok(input)
            .and_then(|input| match !input.is_empty() {
                true => Ok(input),
                false => Err(AssayerError::ValueEmpty("<Validation failure message here>".to_string())),
            })
    }
}

fn main() {
    let input = "Not an empty string".to_string();
    let result = input.validate::<NonEmptyString>();
    assert_eq!(result.ok(), Some(input)); //Oops!  input has been moved!
}

If this is undesirable, either a) the caller can call the validator using clone(): input.clone().validate::<NonEmptyString>(), or b) you may choose to implement ValidateRef and the caller can call the validator using: (&input).validate_ref::<NonEmptyString>().

The case for implementing ValidatorMutRef is somewhat rare and arguably a violation of the Single Responsibility Principle. Whether you consider it to be or not, it can be used to 'fix up' an incoming value before it is used by your post-validation code (you might want to pad or round a valid input value before it is used, for example). Here is how it is used:

impl ValidatorMutRef<String> for NonEmptyString {
    fn validate_mut_ref(input: &mut String) -> std::result::Result<&mut String, AssayerError> {
        Ok(input)
            .and_then(|input| match !input.is_empty() {
                true => { input.push_str("!"); Ok(input) }, //proof validate_mut_ref can mutate the input value
                false => Err(AssayerError::ValueEmpty("<Validation failure message here>".to_string())),
            })
    }
}

fn main() {
    let mut input = "Not an empty string".to_string();
    let mut expected_result_inner = "Not an empty string!".to_string();
    let expected_result = Some(&mut expected_result_inner);

    let result = (&mut input).validate_mut_ref::<NonEmptyString>();
    assert_eq!(result.ok(), expected_result);
}

Finally, if you simply want all three implementations to "just work" whenever you implement one, implement ValidateRef as per above according to your needs, and "blanket implementations" for ValidateMutRef and Validate as follows:

impl ValidatorMutRef<String> for NonEmptyString {
    fn validate_mut_ref(input: &mut String) -> Result<&mut String> {
        Ok(input)
            .and_then(|input| match (&*input).validate_ref::<NonEmptyString>() {
                Ok(_) => Ok(input),
                Err(err) => Err(err),
            })
    }
}

impl Validator<String> for NonEmptyString {
    fn validate(input: String) -> Result<String> {
        Ok(input)
            .and_then(|input| match (&input).validate_ref::<NonEmptyString>() {
                Ok(_) => Ok(input),
                Err(err) => Err(err),
            })
    }
}