frozone 0.3.0

Freeze structs and enums in time
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

# 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:

```rust
#[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

```rust
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

```rust
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

```rust
#[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

- [x] structs support
- [x] enums support
- [x] core/alloc/std types support
- [x] assume_frozen attribute for external types (incl. Freezable generics support)
- [ ] configurable inclusion of the type names themselves
- [ ] compile-time check (probably requires const trait = nightly Rust)
- [ ] better errors
- [ ] consider #[repr(..)] changes inclusion in hash
- [ ] consideration for non-exhaustive enums
- [ ] common crates shims (uuid, url ...)
- [ ] pub-only fields feature?