harmos_domain/state/
transaction.rs

1/* ***
2 *
3 * Harmos
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 *
7 * ***
8 */
9
10/* === Modules === */
11
12/* === Re-Exports === */
13
14/* === Imports === */
15
16// Standard Library Imports
17use std::convert::Infallible;
18// Third Party Imports
19
20// Local Imports
21use crate::state::envelope::DefinitionId;
22
23/* === Constants === */
24
25/* === Macros === */
26
27/* === Type Aliases === */
28
29/* === Structs === */
30
31/* === Enums === */
32
33#[derive(Clone, Copy, Debug, PartialEq, Eq)]
34pub enum Never {}
35
36#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
37pub enum DecodeError {
38    #[error("no definition is declared for the id {id}")]
39    UnknownDefinition { id: DefinitionId },
40
41    #[error("{id} declares no implementation for version {version}")]
42    UndeclaredVersion { id: DefinitionId, version: u32 },
43
44    #[error("the payload did not decode as {id} version {version}")]
45    Malformed { id: DefinitionId, version: u32 },
46}
47
48/* === Traits === */
49
50pub trait Transaction<S> {
51    type Error;
52
53    fn check(&self, state: &S) -> Result<(), Self::Error>;
54
55    fn records(&self, _state: &S, _out: &mut super::record::Records) {}
56
57    fn apply(&self, state: &mut S);
58}
59
60pub trait TransactionCatalog<S>: Transaction<S> + super::record::CatalogCodec {
61    fn replay(&self, prepared: &super::record::Prepared, state: &mut S) -> Result<(), DecodeError> {
62        if self.identify() != (prepared.id.clone(), prepared.version) {
63            return Err(DecodeError::Malformed { id: prepared.id.clone(), version: prepared.version });
64        }
65        self.apply(state);
66        Ok(())
67    }
68}
69
70#[diagnostic::on_unimplemented(
71    message = "`{Self}` declares no inverse",
72    note = "a change answers the undo question where it is defined: `inverse = …` names the \
73            change that takes it back, `inverse = Self` says it is its own, and `irreversible` \
74            says it cannot be taken back — an irreversible change carries no invert body"
75)]
76pub trait Undoable {
77    type Inverse;
78}
79
80#[diagnostic::on_unimplemented(
81    message = "`{Self}` declares an inverse but never describes it",
82    label = "declared without a body",
83    note = "write the body beside the change: `impl harmos::state::Invert<{S}> for {Self} {{ fn \
84            invert(&self, before: &{S}) -> … }}`"
85)]
86pub trait Invert<S>: Undoable + Transaction<S> {
87    fn invert(&self, before: &S) -> Self::Inverse;
88}
89
90#[diagnostic::on_unimplemented(
91    message = "the declared inverse of `{T}` does not name `{T}` back",
92    note = "inverses come in pairs: when `{T}` declares `inverse = X`, `X` declares `inverse = \
93            {T}` — or `inverse = Self`, which is its own pair"
94)]
95pub trait Mutual<T> {}
96
97#[diagnostic::on_unimplemented(
98    message = "the declared inverse `{Self}` is not a member of `{C}`",
99    note = "add `{Self}` to `{C}` as its own variant — a catalog never invents one"
100)]
101pub trait Catalogued<C>: Sized {
102    fn catalogued(self) -> C;
103}
104
105/* === Implementations === */
106
107impl<S> TransactionCatalog<S> for Never {}
108
109impl super::record::CatalogCodec for Never {
110    fn identify(&self) -> (DefinitionId, u32) {
111        match *self {}
112    }
113
114    fn encode<S: serde::Serializer>(&self, _: S) -> Result<S::Ok, S::Error> {
115        match *self {}
116    }
117}
118
119impl super::record::RecordCatalog for Never {
120    fn restore(_: &DefinitionId, _: u32, _: &serde_json::Value) -> Result<Option<Self>, serde_json::Error> {
121        Ok(None)
122    }
123}
124
125impl<S> Transaction<S> for Never {
126    type Error = Infallible;
127
128    fn check(&self, _state: &S) -> Result<(), Self::Error> {
129        match *self {}
130    }
131
132    fn apply(&self, _state: &mut S) {
133        match *self {}
134    }
135}
136
137impl<T> Mutual<T> for T {}
138
139// The membership question is `Catalogued`, not the `Into` it is spelled with:
140// pointing an author at a missing `From` impl would send them to write one by
141// hand instead of to the catalog line that is actually missing a variant.
142#[diagnostic::do_not_recommend]
143impl<C, T: Into<C>> Catalogued<C> for T {
144    fn catalogued(self) -> C {
145        self.into()
146    }
147}
148
149/* === Public Functions === */
150
151/* === Private Functions === */
152
153/* === Tests === */
harmos_domain/state/transaction.rs

harmos_domain/state/
transaction.rs
