ratify_protocol/v2/
checkpoint_ack.rs1use base64::{engine::general_purpose::STANDARD, Engine as _};
6
7use super::crypto::lower_hex;
8use super::errors::{plain, Classify, V2Error, V2ErrorClass, V2Result};
9use super::json::{canonical, obj, parse_wire, CJ};
10use super::limits::{
11 check_v2_wire_size, valid_v2_timestamp, MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2,
12};
13use super::wire::MAX_SAFE;
14
15#[derive(Debug, Clone, PartialEq, Eq, Default)]
17pub struct V2CheckpointAcknowledgement {
18 pub log_id: String,
19 pub sequence: i64,
20 pub entry_hash: Vec<u8>,
21 pub timestamp: i64,
22}
23
24const CHECKPOINT_ACKNOWLEDGEMENT_V2_FIELDS: &[&str] =
25 &["entry_hash", "log_id", "sequence", "timestamp"];
26
27fn validate_v2_checkpoint_acknowledgement(ack: &V2CheckpointAcknowledgement) -> V2Result<()> {
28 if ack.log_id.len() != 32
29 || !lower_hex(&ack.log_id)
30 || ack.sequence < 1
31 || ack.sequence > MAX_SAFE
32 || ack.entry_hash.len() != 48
33 || !valid_v2_timestamp(ack.timestamp)
34 {
35 return plain(
36 "wire v2: checkpoint acknowledgement log_id, sequence, entry_hash, or timestamp is invalid",
37 );
38 }
39 Ok(())
40}
41
42pub fn encode_v2_checkpoint_acknowledgement(
47 ack: &V2CheckpointAcknowledgement,
48) -> V2Result<Vec<u8>> {
49 validate_v2_checkpoint_acknowledgement(ack).classify(V2ErrorClass::Malformed)?;
50 canonical(&CJ::obj(vec![
51 ("entry_hash", CJ::Str(STANDARD.encode(&ack.entry_hash))),
52 ("log_id", CJ::s(&ack.log_id)),
53 ("sequence", CJ::Int(ack.sequence)),
54 ("timestamp", CJ::Int(ack.timestamp)),
55 ]))
56 .classify(V2ErrorClass::Malformed)
57}
58
59pub fn decode_v2_checkpoint_acknowledgement(data: &[u8]) -> V2Result<V2CheckpointAcknowledgement> {
62 (|| {
63 check_v2_wire_size(
64 data,
65 "checkpoint acknowledgement",
66 "MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2",
67 MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2,
68 )?;
69 let root = parse_wire(data, &["entry_hash"], &[])?;
70 let o = obj(&root)?;
71 o.require(CHECKPOINT_ACKNOWLEDGEMENT_V2_FIELDS, &[])?;
72 o.only(CHECKPOINT_ACKNOWLEDGEMENT_V2_FIELDS)?;
73 let entry_hash_text = o.str("entry_hash")?;
74 let log_id = o.str("log_id")?;
75 let sequence = o.i64("sequence")?;
76 let timestamp = o.i64("timestamp")?;
77 let entry_hash = STANDARD
78 .decode(&entry_hash_text)
79 .ok()
80 .filter(|h| STANDARD.encode(h) == entry_hash_text)
81 .ok_or_else(|| {
82 V2Error::plain(
83 "wire v2: checkpoint acknowledgement entry_hash is not canonical base64",
84 )
85 })?;
86 let ack = V2CheckpointAcknowledgement {
87 log_id,
88 sequence,
89 entry_hash,
90 timestamp,
91 };
92 let canonical_bytes = encode_v2_checkpoint_acknowledgement(&ack)?;
93 if canonical_bytes != data {
94 return plain("wire v2: checkpoint acknowledgement is not canonically encoded");
95 }
96 Ok(ack)
97 })()
98 .classify(V2ErrorClass::Malformed)
99}
100
101#[cfg(test)]
102mod tests {
103 use super::*;
104
105 fn ack() -> V2CheckpointAcknowledgement {
106 V2CheckpointAcknowledgement {
107 log_id: "0123456789abcdef0123456789abcdef".into(),
108 sequence: 7,
109 entry_hash: vec![0xab; 48],
110 timestamp: 1_800_000_000,
111 }
112 }
113
114 #[test]
115 fn round_trip_is_canonical_only() {
116 let wire = encode_v2_checkpoint_acknowledgement(&ack()).expect("encode");
117 assert_eq!(
118 String::from_utf8(wire.clone()).expect("utf8"),
119 format!(
120 "{{\"entry_hash\":\"{}\",\"log_id\":\"0123456789abcdef0123456789abcdef\",\"sequence\":7,\"timestamp\":1800000000}}",
121 STANDARD.encode([0xab; 48])
122 )
123 );
124 assert_eq!(
125 decode_v2_checkpoint_acknowledgement(&wire).expect("decode"),
126 ack()
127 );
128 let spaced = String::from_utf8(wire.clone())
129 .expect("utf8")
130 .replace(",", ", ");
131 let reordered = String::from_utf8(wire).expect("utf8").replace(
132 "\"sequence\":7,\"timestamp\":1800000000",
133 "\"timestamp\":1800000000,\"sequence\":7",
134 );
135 for bad in [spaced, reordered, "{}".into(), "null".into()] {
136 let e =
137 decode_v2_checkpoint_acknowledgement(bad.as_bytes()).expect_err("non-canonical");
138 assert_eq!(e.class, V2ErrorClass::Malformed);
139 }
140 for mutate in [
141 |a: &mut V2CheckpointAcknowledgement| {
142 a.log_id = "0123456789ABCDEF0123456789abcdef".into()
143 },
144 |a: &mut V2CheckpointAcknowledgement| a.sequence = 0,
145 |a: &mut V2CheckpointAcknowledgement| a.entry_hash.pop().map(|_| ()).unwrap_or(()),
146 |a: &mut V2CheckpointAcknowledgement| a.timestamp = -1,
147 ] {
148 let mut a = ack();
149 mutate(&mut a);
150 assert_eq!(
151 encode_v2_checkpoint_acknowledgement(&a)
152 .expect_err("invalid")
153 .class,
154 V2ErrorClass::Malformed
155 );
156 }
157 }
158
159 #[test]
160 fn size_limit_is_checked_before_parsing() {
161 let wire = encode_v2_checkpoint_acknowledgement(&ack()).expect("encode");
162 let mut at_limit = wire.clone();
165 at_limit.resize(MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2, b' ');
166 let e = decode_v2_checkpoint_acknowledgement(&at_limit).expect_err("padded");
167 assert!(
168 !e.message
169 .contains("MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2"),
170 "{}",
171 e.message
172 );
173 let mut over = wire;
174 over.resize(MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2 + 1, b' ');
175 let e = decode_v2_checkpoint_acknowledgement(&over).expect_err("limit+1");
176 assert_eq!(e.class, V2ErrorClass::Malformed);
177 assert!(
178 e.message
179 .contains("MAX_CHECKPOINT_ACKNOWLEDGEMENT_BYTES_V2"),
180 "{}",
181 e.message
182 );
183 }
184}