ic-storage 0.66.2

Governed stable allocation and collections for Internet Computer applications
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

use super::*;

#[test]
fn parse_stores_the_string_it_validates() {
    struct ChangingKey(std::cell::Cell<bool>);

    impl AsRef<str> for ChangingKey {
        fn as_ref(&self) -> &str {
            if self.0.replace(true) {
                "INVALID"
            } else {
                "app.rows.v1"
            }
        }
    }

    let key = StableKey::parse(ChangingKey(std::cell::Cell::new(false))).unwrap();
    assert_eq!(key.as_str(), "app.rows.v1");
}

#[test]
fn accepts_canonical_keys() {
    assert_eq!(
        StableKey::parse("app.users.primary.v1")
            .expect("valid key")
            .as_str(),
        "app.users.primary.v1"
    );
    assert!(StableKey::parse("framework.core.auth_state.v12").is_ok());
    assert!(StableKey::parse("app.vault.v1").is_ok());
    assert!(StableKey::parse("app.v1.v2").is_ok());
}

#[test]
fn key_decode_enforces_grammar_and_preserves_current_encoding() {
    let key = StableKey::parse("app.users.v1").unwrap();
    let json = serde_json::to_string(&key).unwrap();
    assert_eq!(json, "\"app.users.v1\"");
    assert_eq!(serde_json::from_str::<StableKey>(&json).unwrap(), key);
    let bytes = ic_wire::native::encode(&key, crate::StorageConfig::default().wire).unwrap();
    assert_eq!(bytes, b"\x0capp.users.v1");
    assert_eq!(
        ic_wire::native::decode::<StableKey>(&bytes, crate::StorageConfig::default().wire).unwrap(),
        key
    );

    for invalid in [
        "App.users.v1",
        "app.users.v0",
        "app.vault",
        "app.users.v1.tail",
        "app..users.v1",
        &"x".repeat(129),
    ] {
        let json = serde_json::to_string(invalid).unwrap();
        assert!(serde_json::from_str::<StableKey>(&json).is_err());
        let bytes =
            ic_wire::native::encode(&invalid, crate::StorageConfig::default().wire).unwrap();
        assert!(
            ic_wire::native::decode::<StableKey>(&bytes, crate::StorageConfig::default().wire)
                .is_err()
        );
    }
}

#[test]
fn whitespace_rejection_preserves_input_and_precedence() {
    for whitespace in [' ', '\t', '\n', '\u{b}', '\u{c}', '\r'] {
        let key = format!("app.us{whitespace}ers.v1");
        assert_eq!(
            StableKey::parse(&key),
            Err(StableKeyError {
                stable_key: key,
                reason: "must not contain whitespace",
            })
        );
    }
    for (key, reason) in [
        ("app.us\u{a0}ers.v1", "must be ASCII"),
        ("App.us\u{b}ers.v1", "must be lowercase"),
    ] {
        assert_eq!(StableKey::parse(key).unwrap_err().reason, reason);
    }
}

#[test]
fn rejects_noncanonical_keys() {
    for key in [
        "",
        "App.users.v1",
        "app.users",
        "app.users.v0",
        "app..users.v1",
        ".app.users.v1",
        "app.users.v1.",
        "app-users.v1",
        "app/users.v1",
        "app.1users.v1",
    ] {
        assert!(StableKey::parse(key).is_err(), "{key} should fail");
    }
}