check_mate

在自我毁灭之前检查自己。

A small Rust utility library inspired by the ideas of "Parse, don't validate"¹ and its follow-up, "Names are not type safety"². Its goal is to extend the idea to checking invariants more generally. See the crate documentation for more information.

lib.rs:

在自我毁灭之前检查自己。

This is a small utility library inspired by the ideas of "Parse, don't validate"¹ and its follow-up, "Names are not type safety"². Its goal is to extend the idea to checking invariants more generally.

动机示例

The motivating use-case for this crate was validating signed messages. Consider a Signed struct like the following

struct Signed {
    payload: Vec<u8>,
    public_key: PublicKey,
    signature: Signature,
}

The struct contains a payload, a public key, and a signature. Let's give the struct a validate method that we could use to check for validity

impl Signed {
    fn validate(&self) -> Result<(), Error> {
        self.public_key.verify(&self.payload, &self.signature)
    }
}

Now when we find a Signed we're able to verify it. Of course, whenever we see a Signed in our code, it may not immediately be clear whether it has been checked yet. In particular, if Signed appears in another struct, or as a signature to some method, has it already been checked? Should we check it anyway?

It's possible to manage this with disciplined use of documentation and convention, making it clear where signatures should be validated and relying on that being the case later in the call stack. However discipline is not always a reliable tool, particularly in an evolving codebase with multiple contributors. Perhaps we can do something better?

Parse, don't validate

This is where the ideas from "Parse, don't validate" come in. Specifically, rather than validating a Signed instance, we could 'parse' it into something else, such as CheckedSigned

/// A [`Signed`] that has been checked and confirmed to be valid.
struct CheckedSigned(Signed);

impl CheckedSigned {
    fn try_from(signed: Signed) -> Result<Self, Error> {
        signed.public_key.verify(&signed.payload, &signed.signature)?;
        Ok(Self(signed))
    }
}

通过将其自己的模块中的CheckedSigned保持为私有字段，我们可以保证唯一构建它的方式是通过执行检查的try_from方法。这意味着结构和函数可以使用CheckedSigned并安全地假设签名是有效的。

fn process_message(message: CheckedSigned) {
    /* ... */
}

// Or

struct ProcessMessage {
    message: CheckedSigned,
}

在这两种情况下，message已经被检查，并且已知是有效的，这一点是立即清晰的。

到目前为止一切顺利，但是由于CheckedSigned的字段是私有的，我们失去了对内部值的直接访问。Rust通过为CheckedSigned实现Deref来简化这里的某些功能。

impl core::ops::Deref for CheckedSigned {
    type Target = Signed;
    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

这允许直接在CheckedSigned实例上调用具有&self接收器的Signed方法。

那么这个库呢...？

为需要检查的每个类型创建一个Checked*新类型将会产生很多样板代码，而且有很多种方法可以解决这个问题。可以说，check_mate的存在就是为了提供一种一致的模式，并尽可能地减少样板代码。

struct Signed {
    payload: Vec<u8>,
    public_key: PublicKey,
    signature: Signature,
}

impl check_mate::Check for Signed {
    type Ok = Self;
    type Err = Error;

    fn check(self) -> Result<Self::Ok, Self::Err> {
        self.public_key.verify(&self.payload, &self.signature)?;
        Ok(self)
    }
}

#
let _ = check_mate::Checked::try_from(signed);