spru 0.1.0

Reusable components for the spru strategy and digital board game framework.
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

use core::fmt;

use crate::item;

/// The version of an [Item](crate::Item). Every transaction that modifies an Item increments its
/// version number by 1. When a [Client](crate::Client) sends an [Interaction](trait@crate::Interaction) to the
/// [Server](crate::Server) to confirm, it sends all the Versions of Items it read. If the server
/// has a different on any of those items, it rejects the Interaction, either because it
/// conflicts, or was based on outdated information.
/// Users never need to manually manage Versions, they are provided for diagnostic purposes only.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    PartialOrd,
    Ord,
    Hash,
    serde::Serialize,
    serde::Deserialize,
    deku::DekuRead,
    deku::DekuWrite,
)]
pub struct Version(u32);

impl Version {
    pub(crate) const ZERO: Self = Self(0);

    pub(crate) fn next(&self) -> Self {
        Self(self.0 + 1)
    }
}

impl fmt::Display for Version {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "v{}", self.0)
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub(crate) struct Change {
    pub before: Version,
    pub after: Version,
}

impl Change {
    pub fn new(before: Version, after: Version) -> Self {
        Self { before, after }
    }

    pub fn noop(version: Version) -> Self {
        Self::new(version, version)
    }

    pub fn create() -> Self {
        Self::new(Version::ZERO, Version::ZERO.next())
    }

    pub fn update(before: Version) -> Self {
        Self::new(before, before.next())
    }

    pub fn undo(self) -> Self {
        Self::new(self.after, self.before)
    }

    // Once a version change has been applied to an item, future modifications which are part of the
    // same transaction can leave the version as-is
    pub fn into_noop(self) -> Self {
        Self::noop(self.after)
    }
}

impl fmt::Display for Change {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{} -> {}", self.before, self.after)
    }
}

#[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
pub(crate) struct Expected {
    pub(crate) expected: Vec<(item::Id, Version)>,
}

impl Expected {
    pub(crate) fn new(versions: impl Iterator<Item = (item::Id, Version)>) -> Self {
        let mut expected: Vec<_> = versions.collect();
        expected.sort_by_key(|(id, _)| *id);
        Self { expected }
    }

    /// Find the first difference between two [Expected], if any
    pub(crate) fn diff(&self, actual: &Self) -> Result<(), item::Error> {
        let mut actual_iter = actual.expected.iter().copied();
        for (expected_id, expected_version) in self.expected.iter().copied() {
            if let Some((actual_id, actual_version)) = actual_iter.next()
                && actual_id <= expected_id
            {
                if actual_id < expected_id {
                    return Err(item::Error::unexpected_change(actual_id));
                }

                if actual_version != expected_version {
                    return Err(item::Error::wrong_version(
                        expected_id,
                        expected_version,
                        actual_version,
                    ));
                }
            } else {
                return Err(item::Error::expected_change(expected_id));
            };
        }

        if let Some((actual_id, _actual_version)) = actual_iter.next() {
            Err(item::Error::unexpected_change(actual_id))
        } else {
            Ok(())
        }
    }
}