batpak 0.2.0

Event sourcing with causal graphs and policy gates. Sync API, zero async.
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158

use serde::de::{self, Deserializer, SeqAccess, Visitor};
use serde::ser::Serializer;
use std::fmt;

/// Serde helpers for u128 serialization as [u8; 16] big-endian.
/// MessagePack has no native u128 type. Bare u128 causes rmp-serde errors.
/// Big-endian preserves sort order and is standard network byte order.
/// [SPEC:WIRE FORMAT DECISIONS item 2]
///
/// ZERO internal dependencies. This module is declared FIRST in lib.rs.
/// Every serializable type with a u128 field uses these helpers.
/// [SPEC:BUILD ORDER STEP 4 — wire.rs is FIRST]
pub mod u128_bytes {
    /// Usage: #[serde(with = "crate::wire::u128_bytes")]
    /// Annotated on: EventHeader.event_id, EventHeader.correlation_id,
    ///   Notification.event_id, Notification.correlation_id,
    ///   Committed.event_id, WaitCondition::Event.event_id,
    ///   CompensationAction::Notify.target_id, Outcome::Pending.resume_token
    use super::*;

    /// Serialize a `u128` as 16 big-endian bytes into the given serializer.
    ///
    /// # Errors
    /// Returns `S::Error` if the underlying serializer fails to write the byte array.
    pub fn serialize<S: Serializer>(val: &u128, ser: S) -> Result<S::Ok, S::Error> {
        // Convert to 16-byte big-endian array, serialize as bytes.
        // [DEP:serde::Serializer::serialize_bytes]
        ser.serialize_bytes(&val.to_be_bytes())
    }

    /// Deserialize a `u128` from 16 big-endian bytes produced by the paired `serialize`.
    ///
    /// # Errors
    /// Returns `D::Error` if the input is not exactly 16 bytes or the deserializer fails.
    pub fn deserialize<'de, D: Deserializer<'de>>(de: D) -> Result<u128, D::Error> {
        // Accept bytes, convert from big-endian to u128.
        // Use a Visitor that handles both byte arrays and sequences.
        // [DEP:serde::de::Visitor]
        struct U128Visitor;
        impl<'de> Visitor<'de> for U128Visitor {
            type Value = u128;
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
                f.write_str("16 bytes for u128")
            }
            fn visit_bytes<E: de::Error>(self, v: &[u8]) -> Result<u128, E> {
                // v must be exactly 16 bytes. Convert via from_be_bytes.
                let arr: [u8; 16] = v
                    .try_into()
                    .map_err(|_| E::invalid_length(v.len(), &"16 bytes"))?;
                Ok(u128::from_be_bytes(arr))
            }
            // Also handle seq format (some deserializers emit sequences not bytes)
            fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<u128, A::Error> {
                let mut bytes = [0u8; 16];
                for (i, byte) in bytes.iter_mut().enumerate() {
                    *byte = seq
                        .next_element()?
                        .ok_or_else(|| de::Error::invalid_length(i, &"16 bytes"))?;
                }
                Ok(u128::from_be_bytes(bytes))
            }
        }
        de.deserialize_bytes(U128Visitor)
    }
}

/// Serde helpers for `Option<u128>` serialization as optional 16-byte big-endian arrays.
pub mod option_u128_bytes {
    /// Usage: #[serde(with = "crate::wire::option_u128_bytes")]
    /// Annotated on: EventHeader.causation_id, Notification.causation_id
    use super::*;

    /// Serialize an `Option<u128>` as `None` or 16 big-endian bytes.
    ///
    /// # Errors
    /// Returns `S::Error` if the underlying serializer fails.
    pub fn serialize<S: Serializer>(val: &Option<u128>, ser: S) -> Result<S::Ok, S::Error> {
        match val {
            Some(v) => ser.serialize_bytes(&v.to_be_bytes()),
            None => ser.serialize_none(),
        }
    }

    /// Deserialize an `Option<u128>` from `None` or 16 big-endian bytes.
    ///
    /// # Errors
    /// Returns `D::Error` if the input is present but not exactly 16 bytes, or the deserializer fails.
    pub fn deserialize<'de, D: Deserializer<'de>>(de: D) -> Result<Option<u128>, D::Error> {
        // Visitor that handles None (nil) and Some(bytes).
        struct OptU128Visitor;
        impl<'de> Visitor<'de> for OptU128Visitor {
            type Value = Option<u128>;
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
                f.write_str("null or 16 bytes for u128")
            }
            fn visit_none<E: de::Error>(self) -> Result<Option<u128>, E> {
                Ok(None)
            }
            fn visit_some<D2: Deserializer<'de>>(self, de: D2) -> Result<Option<u128>, D2::Error> {
                super::u128_bytes::deserialize(de).map(Some)
            }
            fn visit_bytes<E: de::Error>(self, v: &[u8]) -> Result<Option<u128>, E> {
                let arr: [u8; 16] = v
                    .try_into()
                    .map_err(|_| E::invalid_length(v.len(), &"16 bytes"))?;
                Ok(Some(u128::from_be_bytes(arr)))
            }
        }
        de.deserialize_option(OptU128Visitor)
    }
}

/// Serde helpers for `Vec<u128>` serialization as sequences of 16-byte big-endian arrays.
pub mod vec_u128_bytes {
    /// Usage: #[serde(with = "crate::wire::vec_u128_bytes")]
    /// Annotated on: CompensationAction::Rollback.event_ids,
    ///   CompensationAction::Release.resource_ids
    use super::*;

    /// Serialize a `Vec<u128>` as a sequence of 16-byte big-endian arrays.
    ///
    /// # Errors
    /// Returns `S::Error` if the underlying serializer fails to write the sequence.
    pub fn serialize<S: Serializer>(val: &[u128], ser: S) -> Result<S::Ok, S::Error> {
        // Serialize as a sequence of [u8; 16] fixed-size arrays (NOT bytes).
        // Using arrays ensures serialize and deserialize use the same msgpack
        // format (array of arrays, not array of bin). Avoids format mismatch.
        use serde::ser::SerializeSeq;
        let mut seq = ser.serialize_seq(Some(val.len()))?;
        for v in val {
            seq.serialize_element(&v.to_be_bytes())?; // [u8; 16], serialized as array
        }
        seq.end()
    }

    /// Deserialize a `Vec<u128>` from a sequence of 16-byte big-endian arrays.
    ///
    /// # Errors
    /// Returns `D::Error` if any element is not a valid 16-byte array or the deserializer fails.
    pub fn deserialize<'de, D: Deserializer<'de>>(de: D) -> Result<Vec<u128>, D::Error> {
        // Deserialize a sequence of [u8; 16] arrays back to Vec<u128>.
        struct VecU128Visitor;
        impl<'de> Visitor<'de> for VecU128Visitor {
            type Value = Vec<u128>;
            fn expecting(&self, f: &mut fmt::Formatter) -> fmt::Result {
                f.write_str("sequence of 16-byte u128 values")
            }
            fn visit_seq<A: SeqAccess<'de>>(self, mut seq: A) -> Result<Vec<u128>, A::Error> {
                let mut out = Vec::with_capacity(seq.size_hint().unwrap_or(0));
                while let Some(arr) = seq.next_element::<[u8; 16]>()? {
                    out.push(u128::from_be_bytes(arr));
                }
                Ok(out)
            }
        }
        de.deserialize_seq(VecU128Visitor)
    }
}