1use core::fmt;
20
21use smallvec::SmallVec;
22
23use crate::encode::Bytes;
24use crate::entry::{Op, Value};
25use crate::id::CommitId;
26
27#[derive(Debug, Clone, PartialEq)]
29pub enum Record {
30 Commit {
32 branch: String,
34 parents: SmallVec<[CommitId; 2]>,
36 seq: u64,
38 message: Option<String>,
40 ops: Vec<Op>,
42 },
43 BranchCreated {
45 name: String,
47 at: CommitId,
49 },
50 BranchDiscarded {
52 name: String,
54 },
55 HeadMoved {
57 branch: String,
59 to: CommitId,
61 },
62}
63
64pub trait Journal: Send + Sync + fmt::Debug {
70 fn append(&self, record: &Record) -> Result<(), JournalError>;
72}
73
74#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
76#[error("cannot record the change durably: {0}")]
77pub struct JournalError(pub String);
78
79impl JournalError {
80 pub fn new(reason: impl Into<String>) -> Self {
82 JournalError(reason.into())
83 }
84}
85
86mod tag {
89 pub const COMMIT: u8 = 1;
90 pub const BRANCH_CREATED: u8 = 2;
91 pub const BRANCH_DISCARDED: u8 = 3;
92 pub const HEAD_MOVED: u8 = 4;
93}
94
95pub fn encode(record: &Record) -> Vec<u8> {
97 let mut b = Bytes::new();
98 match record {
99 Record::Commit {
100 branch,
101 parents,
102 seq,
103 message,
104 ops,
105 } => {
106 b.u8(tag::COMMIT);
107 b.str(branch);
108 b.u64(parents.len() as u64);
109 for p in parents {
110 b.commit_id(p);
111 }
112 b.u64(*seq);
113 b.opt_str(message.as_deref());
114 b.u64(ops.len() as u64);
115 for op in ops {
116 encode_op(&mut b, op);
117 }
118 }
119 Record::BranchCreated { name, at } => {
120 b.u8(tag::BRANCH_CREATED);
121 b.str(name);
122 b.commit_id(at);
123 }
124 Record::BranchDiscarded { name } => {
125 b.u8(tag::BRANCH_DISCARDED);
126 b.str(name);
127 }
128 Record::HeadMoved { branch, to } => {
129 b.u8(tag::HEAD_MOVED);
130 b.str(branch);
131 b.commit_id(to);
132 }
133 }
134 b.into_vec()
135}
136
137fn encode_op(b: &mut Bytes, op: &Op) {
138 match op {
139 Op::Put { key, value } => {
140 b.u8(1);
141 b.str(key);
142 b.bytes(&value.value);
143 match &value.embedding {
144 None => b.u8(0),
145 Some(v) => {
146 b.u8(1);
147 b.u64(v.len() as u64);
148 for x in v {
149 b.f32(*x);
150 }
151 }
152 }
153 b.f32(value.importance);
154 b.opt_u64(value.ttl_commits);
155 b.u64(value.meta.len() as u64);
156 for (k, v) in &value.meta {
157 b.str(k);
158 b.str(v);
159 }
160 }
161 Op::Delete { key } => {
162 b.u8(2);
163 b.str(key);
164 }
165 Op::Evict { key } => {
166 b.u8(3);
167 b.str(key);
168 }
169 }
170}
171
172#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
174pub enum DecodeError {
175 #[error("the record is truncated: wanted {wanted} more byte(s) at offset {at}")]
177 Truncated {
178 at: usize,
180 wanted: usize,
182 },
183 #[error("unknown {what} tag {tag} at offset {at}")]
185 UnknownTag {
186 what: &'static str,
188 tag: u8,
190 at: usize,
192 },
193 #[error("a string in the record is not valid UTF-8, at offset {at}")]
195 BadUtf8 {
196 at: usize,
198 },
199 #[error("{extra} byte(s) left over after the record")]
201 TrailingBytes {
202 extra: usize,
204 },
205 #[error("a length field claims {claimed} items, which the record cannot hold")]
207 ImplausibleLength {
208 claimed: u64,
210 },
211}
212
213pub fn decode(bytes: &[u8]) -> Result<Record, DecodeError> {
215 let mut r = Reader::new(bytes);
216 let record = decode_record(&mut r)?;
217 if r.remaining() != 0 {
218 return Err(DecodeError::TrailingBytes {
219 extra: r.remaining(),
220 });
221 }
222 Ok(record)
223}
224
225fn decode_record(r: &mut Reader<'_>) -> Result<Record, DecodeError> {
226 let at = r.pos;
227 match r.u8()? {
228 tag::COMMIT => {
229 let branch = r.str()?;
230 let count = r.count()?;
231 let mut parents = SmallVec::new();
232 for _ in 0..count {
233 parents.push(r.commit_id()?);
234 }
235 let seq = r.u64()?;
236 let message = r.opt_str()?;
237 let op_count = r.count()?;
238 let mut ops = Vec::with_capacity(op_count.min(1024));
239 for _ in 0..op_count {
240 ops.push(decode_op(r)?);
241 }
242 Ok(Record::Commit {
243 branch,
244 parents,
245 seq,
246 message,
247 ops,
248 })
249 }
250 tag::BRANCH_CREATED => Ok(Record::BranchCreated {
251 name: r.str()?,
252 at: r.commit_id()?,
253 }),
254 tag::BRANCH_DISCARDED => Ok(Record::BranchDiscarded { name: r.str()? }),
255 tag::HEAD_MOVED => Ok(Record::HeadMoved {
256 branch: r.str()?,
257 to: r.commit_id()?,
258 }),
259 tag => Err(DecodeError::UnknownTag {
260 what: "record",
261 tag,
262 at,
263 }),
264 }
265}
266
267fn decode_op(r: &mut Reader<'_>) -> Result<Op, DecodeError> {
268 let at = r.pos;
269 match r.u8()? {
270 1 => {
271 let key = r.str()?;
272 let value = bytes::Bytes::from(r.bytes()?.to_vec());
273 let embedding = match r.u8()? {
274 0 => None,
275 1 => {
276 let n = r.count()?;
277 let mut v = Vec::with_capacity(n.min(4096));
278 for _ in 0..n {
279 v.push(r.f32()?);
280 }
281 Some(v)
282 }
283 tag => {
284 return Err(DecodeError::UnknownTag {
285 what: "embedding presence",
286 tag,
287 at: r.pos,
288 })
289 }
290 };
291 let importance = r.f32()?;
292 let ttl_commits = r.opt_u64()?;
293 let meta_count = r.count()?;
294 let mut meta = std::collections::BTreeMap::new();
295 for _ in 0..meta_count {
296 let k = r.str()?;
297 let v = r.str()?;
298 meta.insert(k, v);
299 }
300 Ok(Op::Put {
301 key,
302 value: Value {
303 value,
304 embedding,
305 importance,
306 ttl_commits,
307 meta,
308 },
309 })
310 }
311 2 => Ok(Op::Delete { key: r.str()? }),
312 3 => Ok(Op::Evict { key: r.str()? }),
313 tag => Err(DecodeError::UnknownTag {
314 what: "operation",
315 tag,
316 at,
317 }),
318 }
319}
320
321struct Reader<'a> {
323 bytes: &'a [u8],
324 pos: usize,
325}
326
327impl<'a> Reader<'a> {
328 fn new(bytes: &'a [u8]) -> Self {
329 Reader { bytes, pos: 0 }
330 }
331
332 fn remaining(&self) -> usize {
333 self.bytes.len() - self.pos
334 }
335
336 fn take(&mut self, n: usize) -> Result<&'a [u8], DecodeError> {
337 if self.remaining() < n {
338 return Err(DecodeError::Truncated {
339 at: self.pos,
340 wanted: n - self.remaining(),
341 });
342 }
343 let out = &self.bytes[self.pos..self.pos + n];
344 self.pos += n;
345 Ok(out)
346 }
347
348 fn u8(&mut self) -> Result<u8, DecodeError> {
349 Ok(self.take(1)?[0])
350 }
351
352 fn u64(&mut self) -> Result<u64, DecodeError> {
353 let b = self.take(8)?;
354 let mut a = [0u8; 8];
355 a.copy_from_slice(b);
356 Ok(u64::from_le_bytes(a))
357 }
358
359 fn f32(&mut self) -> Result<f32, DecodeError> {
360 let b = self.take(4)?;
361 let mut a = [0u8; 4];
362 a.copy_from_slice(b);
363 Ok(f32::from_bits(u32::from_le_bytes(a)))
364 }
365
366 fn count(&mut self) -> Result<usize, DecodeError> {
372 let claimed = self.u64()?;
373 if claimed > self.remaining() as u64 {
374 return Err(DecodeError::ImplausibleLength { claimed });
375 }
376 Ok(claimed as usize)
377 }
378
379 fn bytes(&mut self) -> Result<&'a [u8], DecodeError> {
380 let n = self.count()?;
381 self.take(n)
382 }
383
384 fn str(&mut self) -> Result<String, DecodeError> {
385 let at = self.pos;
386 let b = self.bytes()?;
387 core::str::from_utf8(b)
388 .map(str::to_owned)
389 .map_err(|_| DecodeError::BadUtf8 { at })
390 }
391
392 fn opt_str(&mut self) -> Result<Option<String>, DecodeError> {
393 match self.u8()? {
394 0 => Ok(None),
395 1 => Ok(Some(self.str()?)),
396 tag => Err(DecodeError::UnknownTag {
397 what: "optional string presence",
398 tag,
399 at: self.pos,
400 }),
401 }
402 }
403
404 fn opt_u64(&mut self) -> Result<Option<u64>, DecodeError> {
405 match self.u8()? {
406 0 => Ok(None),
407 1 => Ok(Some(self.u64()?)),
408 tag => Err(DecodeError::UnknownTag {
409 what: "optional number presence",
410 tag,
411 at: self.pos,
412 }),
413 }
414 }
415
416 fn commit_id(&mut self) -> Result<CommitId, DecodeError> {
417 let b = self.take(32)?;
418 let mut a = [0u8; 32];
419 a.copy_from_slice(b);
420 Ok(CommitId::from_bytes(a))
421 }
422}