frozone

frozone is a crate that allows you to 'freeze' structs and enums recursively to ensure they never get changed, helping enforcing backwards-compatibility or API stability (arewesemveryet.org ?)

Use case

Let's say there is a very important data structure for your application:

#[derive(Serialize, Deserialize)]
struct Frozone {
    power: Power,
    equipment: Vec<Part>,
    super_suit: Suit
}

#[derive(Serialize, Deserialize)]
enum Part {
    Sunglasses,
    Skates,
    //...
}

that gets serialized in ~/.config/frozone/state.json on each user's machine. You've released v1 and everyone is happy.

However, for v2, you realize that you would prefer super_suit to be included in equipment instead. Good, but now, whenever your v2 program runs and tries to load a 'v1' config, your deserializer will rightfully tell you: Honey, where's my super_suit ?

You probably know that the answer to this backward-compatibility issue is to add a version field, save the old structure tree somewhere, and create new ones

struct FrozoneV2 {
    version: String,
    power: Power,
    equipments: Vec<PartV2>
}

impl From<Frozone> for FrozoneV2 {
    fn from(value: Frozone) -> FrozoneV2 {
        // ..proper migration code
    }
}

Of course, you'll never forget to check that no similar changes during the v1->v2 development have affected Power: a deeply-nested struct, with enough optional fields to make coverage testing a full-on PhD thesis, spanning multiple modules/crates/developer's responsibilities.

OF COURSE, RIGHT ?

frozone enforces your 'object tree' semantically never changes, ensuring serialization and API stability.

Usage

use frozone::Freezable;

#[derive(Serialize, Deserialize, Freezable)]
struct Frozone {
    power: Power,
    equipment: Vec<Part>,
    super_suit: Suit
}

#[derive(Serialize, Deserialize, Freezable)]
struct Power {
    // ...
}
// ...

fn main() {
    /// call the associated method `::freeze()` on your structure, and
    /// compare it to the fixed value it evaluated to
    assert_eq!(Frozone::freeze(),  12298013273002774775); // frozone hash from v1 release
    /// .. okay, `Frozone` has not changed since v1
}

What's frozen and what's not

#[derive(Freezable)]
pub struct StructName {       // visibility qualifier, struct name: NOT FROZEN
    field_name: FieldType,    // field names, fields types: FROZEN

    #[assume_frozen]                             // assume_frozen'd field name: FROZEN
    assumed_frozen_field_name: ExternalFieldType // assume_frozen'd field type: NOT FROZEN
}
// note: the order of the fields is "not frozen"


#[derive(Freezable)]
enum FieldType {  // enum name: NOT FROZEN
    UnitVariant,  // variant name: FROZEN
    Variant1 = 1, // discriminant value: FROZEN
    StructVariant(Type1, Type2, Type3), // inner types (and their order): FROZEN

    #[assume_frozen]  // assume_frozen'd field name: FROZEN
    AssumedFrozenVariant(Type4, Type5), // assume_frozen'd inner types: NOT FROZEN
}
// note: the order of the variants is "not frozen"

Roadmap

• structs support
• enums support
• compile-time check (probably requires const trait = nightly Rust)