Skip to main content

rig_memory/
session.rs

1//! Reading a session back ([`Session`]), saving to it without a running
2//! [`Writer`](crate::Writer) ([`load`], [`save`]), and one log's history
3//! ([`history`], [`as_of`]).
4
5use std::collections::{BTreeMap, HashMap, HashSet};
6use std::io;
7use std::ops::ControlFlow;
8
9use rig_core::conversation::{ChangeRecord, Conversation, Lineage};
10use serde_json::Value;
11
12use crate::blobs::{BLOBS, load_images_with, messages_mut, named_blobs, put_blob, read_blob};
13use crate::format::{Body, Header, LogLines, Meta, SESSION, parse, stamp_of};
14use crate::store::now;
15use crate::writer::Book;
16use crate::{FORMAT, LogRewrite, Repair, SessionError, Stamp, Store, check_log_name};
17
18/// A session as its logs left it.
19#[derive(Clone, Debug, Default, PartialEq)]
20pub struct Session {
21    /// Its agents, in the order their logs were started.
22    pub agents: Vec<SavedAgent>,
23    /// The session's own saved values by key: the [`SESSION`] log's.
24    pub saved: BTreeMap<String, Value>,
25    /// What reading it repaired or worked around.
26    pub repairs: Vec<Repair>,
27    /// Where each log ended when the session was read or last saved, so a
28    /// save refuses a store that moved on.
29    pub(crate) ends: BTreeMap<String, End>,
30}
31
32/// Where a log ends: its lineage and the `seq` after its last record. A
33/// write or a rewrite of the log changes it.
34pub(crate) type End = (Lineage, u64);
35
36/// An agent as its log left it.
37#[derive(Clone, Debug, Default, PartialEq)]
38pub struct SavedAgent {
39    /// Its id, the name of its log.
40    pub id: String,
41    /// The id of the agent that spawned it, if any.
42    pub parent: Option<String>,
43    /// When its log was started, in milliseconds since the Unix epoch.
44    pub started_ms: u64,
45    /// Its conversation, continuing its log: its lineage the log's, its
46    /// revision the number of changes the log holds.
47    pub conversation: Conversation,
48    /// The newest value of each of its saved values, by key.
49    pub saved: BTreeMap<String, Value>,
50    /// Whether it is gone for good: a restore skips it, and the agents it
51    /// spawned.
52    pub retired: bool,
53    /// Who rewrote its log in place, and when, oldest first.
54    pub rewrites: Vec<LogRewrite>,
55}
56
57/// A log [`Session::read_lenient`] could not read.
58#[derive(Debug)]
59pub struct Unreadable {
60    /// Its name: an agent's id, or [`SESSION`].
61    pub log: String,
62    /// Why it could not be read.
63    pub error: SessionError,
64}
65
66/// One record of a log, as [`history`] reads it.
67#[derive(Clone, Debug, PartialEq)]
68pub enum LogRecord {
69    /// A change of the conversation, its `at` the time it was written.
70    Change(ChangeRecord),
71    /// A saved value set, or with `None` removed.
72    Saved {
73        /// Its key.
74        key: String,
75        /// Its value.
76        value: Option<Value>,
77    },
78    /// The agent is gone for good.
79    Retired,
80}
81
82/// A log read and folded.
83#[derive(Default)]
84pub(crate) struct Folded {
85    pub name: String,
86    pub header: Header,
87    pub started_ms: u64,
88    pub conversation: Conversation,
89    pub state: BTreeMap<String, Value>,
90    pub retired: bool,
91    /// The `seq` after the last record's.
92    pub next_seq: u64,
93    /// The session's `n` after the last record's.
94    pub next_n: u64,
95    /// The bytes of its complete lines.
96    pub len: u64,
97    /// The bytes read and the bytes of a torn tail after them.
98    pub torn: Option<(u64, u64)>,
99    /// Why images of it are lost.
100    pub lost: Vec<io::Error>,
101}
102
103/// A log read strictly: its header, and where it ends.
104struct Read {
105    header: Header,
106    started: Stamp,
107    last: Stamp,
108}
109
110/// The log `name` of `store` as stored; `None` when there is none.
111pub(crate) fn log_lines(store: &dyn Store, name: &str) -> Result<Option<LogLines>, SessionError> {
112    match store.read_log(name) {
113        Err(failure) if failure.kind() == io::ErrorKind::NotFound => Ok(None),
114        bytes => Ok(Some(LogLines::parse(bytes?))),
115    }
116}
117
118/// Every log of `store` as stored, in the store's order.
119pub(crate) fn read_logs(store: &dyn Store) -> Result<Vec<(String, LogLines)>, SessionError> {
120    let mut logs = Vec::new();
121    for name in store.logs()? {
122        logs.extend(log_lines(store, &name)?.map(|lines| (name, lines)));
123    }
124    Ok(logs)
125}
126
127/// Reads the log `name` of `store` strictly, as [`read_lines`] does.
128fn read(
129    store: &dyn Store,
130    name: &str,
131    each: impl FnMut(Stamp, Body) -> Result<ControlFlow<()>, String>,
132) -> Result<Option<Read>, SessionError> {
133    match log_lines(store, name)? {
134        Some(lines) => read_lines(name, &lines, each),
135        None => Ok(None),
136    }
137}
138
139/// Reads `lines`, the log `name`, strictly, giving each record after the
140/// header, in this format, to `each`, which may stop the reading early.
141/// `None` when it holds no complete line.
142fn read_lines(
143    name: &str,
144    lines: &LogLines,
145    mut each: impl FnMut(Stamp, Body) -> Result<ControlFlow<()>, String>,
146) -> Result<Option<Read>, SessionError> {
147    let Some((_, _, first)) = lines.iter().next() else {
148        return Ok(None);
149    };
150    let refuse = |line, why| SessionError::record(name, line, why);
151    let (started, header) = read_header(name, first)?;
152    let mut last = started;
153    for (line, _, bytes) in lines.iter().skip(1) {
154        let (stamp, body) = parse(bytes).map_err(|why| refuse(line, why))?;
155        if matches!(body, Body::Meta(Meta::Header(_))) {
156            return Err(refuse(line, "a second header".to_owned()));
157        }
158        if each(stamp, body)
159            .map_err(|why| refuse(line, why))?
160            .is_break()
161        {
162            break;
163        }
164        last = stamp;
165    }
166    Ok(Some(Read {
167        header,
168        started,
169        last,
170    }))
171}
172
173/// The header `first`, the first line of the log `name`, read strictly: of
174/// [`FORMAT`], with the log's lineage.
175pub(crate) fn read_header(name: &str, first: &[u8]) -> Result<(Stamp, Header), SessionError> {
176    let (started, header) = match parse(first) {
177        Ok((stamp, Body::Meta(Meta::Header(header)))) => (stamp, header),
178        _ => {
179            let found = serde_json::from_slice::<Header>(first)
180                .ok()
181                .and_then(|header| header.format);
182            return Err(SessionError::Format {
183                log: name.to_owned(),
184                found,
185            });
186        }
187    };
188    if header.format.as_deref() != Some(FORMAT) {
189        let found = header.format;
190        let log = name.to_owned();
191        return Err(SessionError::Format { log, found });
192    }
193    if !header.lineage.is_log() {
194        let why = "a header without the log's lineage".to_owned();
195        return Err(SessionError::record(name, 1, why));
196    }
197    Ok((started, header))
198}
199
200/// How a log is folded.
201#[derive(Clone, Copy, Default)]
202pub(crate) struct Fold {
203    /// Only the records made before the session's record `n`.
204    pub until: Option<u64>,
205    /// Whether images are put back from their blobs.
206    pub images: bool,
207}
208
209impl Fold {
210    /// Every record, images put back.
211    pub const WHOLE: Self = Self {
212        until: None,
213        images: true,
214    };
215}
216
217/// Folds the log `name` of `store`: every change applied in order, the
218/// newest of each saved value, whether it was retired. `None` when there
219/// is no log.
220pub(crate) fn fold(
221    store: &dyn Store,
222    name: &str,
223    how: Fold,
224) -> Result<Option<Folded>, SessionError> {
225    match log_lines(store, name)? {
226        Some(lines) => fold_lines(name, &lines, how, &|blob| read_blob(store, blob)),
227        None => Ok(None),
228    }
229}
230
231/// Folds `lines`, the log `name`, as [`fold`] does, putting images back
232/// from the blobs `blob` reads. `None` when it holds no complete line.
233pub(crate) fn fold_lines(
234    name: &str,
235    lines: &LogLines,
236    how: Fold,
237    blob: &dyn Fn(&str) -> io::Result<Vec<u8>>,
238) -> Result<Option<Folded>, SessionError> {
239    fold_lines_with(name, lines, (how, blob), &mut |_, _| {})
240}
241
242/// [`fold_lines`], giving `each` every change with the conversation the
243/// changes before it left.
244fn fold_lines_with(
245    name: &str,
246    lines: &LogLines,
247    (how, blob): (Fold, &dyn Fn(&str) -> io::Result<Vec<u8>>),
248    each: &mut dyn FnMut(&Conversation, &ChangeRecord),
249) -> Result<Option<Folded>, SessionError> {
250    let mut conversation = Conversation::new();
251    let mut state = BTreeMap::new();
252    let mut retired = false;
253    let mut lost = Vec::new();
254    let read = read_lines(name, lines, |stamp, body| {
255        if how.until.is_some_and(|until| stamp.n >= until) {
256            return Ok(ControlFlow::Break(()));
257        }
258        match body {
259            Body::Meta(meta) => note_meta(meta, &mut state, &mut retired),
260            Body::Change(mut recorded) => {
261                if how.images {
262                    let _ = messages_mut(&mut recorded.change, &mut |message| {
263                        if let Err(failure) = load_images_with(message, blob) {
264                            lost.push(failure);
265                        }
266                        Ok(())
267                    });
268                }
269                each(&conversation, &recorded);
270                conversation
271                    .apply(&recorded)
272                    .map_err(|error| error.to_string())?;
273            }
274        }
275        Ok(ControlFlow::Continue(()))
276    })?;
277    let Some(read) = read else {
278        return Ok(None);
279    };
280    let changes = conversation.revision();
281    conversation.continue_log(read.header.lineage, changes);
282    let tail = lines.tail().len() as u64;
283    Ok(Some(Folded {
284        name: name.to_owned(),
285        started_ms: read.started.t,
286        header: read.header,
287        conversation,
288        state,
289        retired,
290        next_seq: read.last.seq.saturating_add(1),
291        next_n: read.last.n.saturating_add(1),
292        len: lines.len(),
293        torn: (tail > 0).then(|| (lines.len(), tail)),
294        lost,
295    }))
296}
297
298/// A saved value set or removed, or the log retired, noted into `state`
299/// and `retired`.
300pub(crate) fn note_meta(meta: Meta, state: &mut BTreeMap<String, Value>, retired: &mut bool) {
301    match meta {
302        Meta::State { key, value } => {
303            match value.filter(|value| !value.is_null()) {
304                Some(value) => state.insert(key, value),
305                None => state.remove(&key),
306            };
307        }
308        Meta::Retired => *retired = true,
309        Meta::Header(_) => {}
310    }
311}
312
313/// `lines`, the log `name`, read for saving to it as [`fold_lines`] reads
314/// it, but its changes only counted by their stamps, not read or applied:
315/// its conversation is empty, continuing the log; its saved values and
316/// retirement are read, and a second header is refused as loading refuses
317/// it. `None` when it holds no complete line.
318fn tally(name: &str, lines: &LogLines) -> Result<Option<Folded>, SessionError> {
319    let Some((_, _, first)) = lines.iter().next() else {
320        return Ok(None);
321    };
322    let (started, header) = read_header(name, first)?;
323    let (mut last, mut changes) = (started, 0);
324    let (mut state, mut retired) = (BTreeMap::new(), false);
325    for (line, _, bytes) in lines.iter().skip(1) {
326        let refuse = |why| SessionError::record(name, line, why);
327        let (stamp, change) = stamp_of(bytes).map_err(refuse)?;
328        if !change && let (_, Body::Meta(meta)) = parse(bytes).map_err(refuse)? {
329            if matches!(meta, Meta::Header(_)) {
330                return Err(refuse("a second header".to_owned()));
331            }
332            note_meta(meta, &mut state, &mut retired);
333        }
334        last = stamp;
335        changes += u64::from(change);
336    }
337    let mut conversation = Conversation::new();
338    conversation.continue_log(header.lineage, changes);
339    let tail = lines.tail().len() as u64;
340    Ok(Some(Folded {
341        name: name.to_owned(),
342        started_ms: started.t,
343        header,
344        conversation,
345        state,
346        retired,
347        next_seq: last.seq.saturating_add(1),
348        next_n: last.n.saturating_add(1),
349        len: lines.len(),
350        torn: (tail > 0).then(|| (lines.len(), tail)),
351        ..Folded::default()
352    }))
353}
354
355/// Every log of `logs`, the session of `store`, folded, with images put
356/// back from its blobs.
357pub(crate) fn fold_all(
358    store: &dyn Store,
359    logs: &[(String, LogLines)],
360) -> Result<Vec<Folded>, SessionError> {
361    let mut folded = Vec::new();
362    for (name, lines) in logs {
363        folded.extend(fold_lines(name, lines, Fold::WHOLE, &|blob| {
364            read_blob(store, blob)
365        })?);
366    }
367    Ok(folded)
368}
369
370/// What reading `folded`, the logs of `store` that hold a record, repaired,
371/// torn tails not set aside.
372pub(crate) fn repairs(store: &dyn Store, folded: &[Folded]) -> Result<Vec<Repair>, SessionError> {
373    let torn = torn_tails(store, folded)?.into_iter();
374    let mut repairs: Vec<Repair> = torn
375        .map(|(log, kept, cut)| Repair::TornTail {
376            log,
377            kept,
378            cut,
379            set_aside: None,
380        })
381        .collect();
382    for log in folded {
383        repairs.extend(log.lost.iter().map(|why| Repair::LostImage {
384            log: log.name.clone(),
385            why: why.to_string(),
386        }));
387    }
388    Ok(repairs)
389}
390
391/// Each log of `store` that ends in a torn line, with the bytes before the
392/// line and its bytes: each of `folded`, the logs that hold a record, that
393/// does, and each log that holds no complete line but a torn one, such as
394/// one whose first write was cut short.
395pub(crate) fn torn_tails(
396    store: &dyn Store,
397    folded: &[Folded],
398) -> Result<Vec<(String, u64, u64)>, SessionError> {
399    let mut torn = Vec::new();
400    for log in store.logs()? {
401        match folded.iter().find(|folded| folded.name == log) {
402            Some(folded) => torn.extend(folded.torn.map(|(kept, cut)| (log, kept, cut))),
403            None => torn.extend(torn_whole(store, &log).map(|cut| (log, 0, cut))),
404        }
405    }
406    Ok(torn)
407}
408
409/// The bytes of the torn line the log `log` of `store` holds, when it holds
410/// no complete line but a torn one.
411fn torn_whole(store: &dyn Store, log: &str) -> Option<u64> {
412    // A log that cannot be read is refused or set aside by its fold.
413    let lines = log_lines(store, log).ok().flatten();
414    let lines = lines.filter(|lines| lines.len() == 0)?;
415    let cut = lines.tail().len() as u64;
416    (cut > 0).then_some(cut)
417}
418
419/// The names of the logs a restore skips: those retired, and the agents
420/// they spawned, all the way down.
421pub(crate) fn retired(logs: &[Folded]) -> HashSet<String> {
422    let logs = logs.iter().map(|log| {
423        let parent = log.header.parent.as_deref();
424        (log.name.as_str(), parent, log.retired)
425    });
426    skipped(logs).into_iter().map(str::to_owned).collect()
427}
428
429/// Of `logs`, each a log's name, its agent's parent and whether it was
430/// retired: those retired, and the agents they spawned, all the way down.
431pub(crate) fn skipped<'a>(
432    logs: impl Iterator<Item = (&'a str, Option<&'a str>, bool)>,
433) -> HashSet<&'a str> {
434    let logs: Vec<_> = logs.collect();
435    let parents: HashMap<&str, Option<&str>> = logs
436        .iter()
437        .map(|&(name, parent, _)| (name, parent))
438        .collect();
439    let gone: HashSet<&str> = logs
440        .iter()
441        .filter(|&&(_, _, retired)| retired)
442        .map(|&(name, ..)| name)
443        .collect();
444    let mut skipped = HashSet::new();
445    for &(name, ..) in &logs {
446        // Parents come from the logs' headers; the bound stops a corrupt store's loop.
447        let up = std::iter::successors(Some(name), |id| parents.get(id).copied().flatten());
448        if up.take(logs.len() + 1).any(|id| gone.contains(id)) {
449            skipped.insert(name);
450        }
451    }
452    skipped
453}
454
455/// Where each log of `folded` ends.
456pub(crate) fn ends(folded: &[Folded]) -> BTreeMap<String, End> {
457    let end = |log: &Folded| (log.name.clone(), (log.header.lineage, log.next_seq));
458    folded.iter().map(end).collect()
459}
460
461/// The session of `folded`, with `repairs`.
462pub(crate) fn session_of(folded: Vec<Folded>, repairs: Vec<Repair>) -> Session {
463    let mut session = Session {
464        repairs,
465        ends: ends(&folded),
466        ..Session::default()
467    };
468    for log in folded {
469        if log.name == SESSION {
470            session.saved = log.state;
471            continue;
472        }
473        session.agents.push(SavedAgent {
474            id: log.name,
475            parent: log.header.parent,
476            started_ms: log.started_ms,
477            conversation: log.conversation,
478            saved: log.state,
479            retired: log.retired,
480            rewrites: log.header.rewrites,
481        });
482    }
483    session
484        .agents
485        .sort_by(|a, b| (a.started_ms, &a.id).cmp(&(b.started_ms, &b.id)));
486    session
487}
488
489impl Session {
490    /// Reads the session kept in `store`, without writing to it: a torn
491    /// last line is reported and left. Retired agents are read too.
492    ///
493    /// # Errors
494    ///
495    /// When the store fails, or any log is in another format or holds a
496    /// record that cannot be read or does not apply: the whole session is
497    /// refused.
498    pub fn read(store: &dyn Store) -> Result<Self, SessionError> {
499        let folded = fold_all(store, &read_logs(store)?)?;
500        let repairs = repairs(store, &folded)?;
501        Ok(session_of(folded, repairs))
502    }
503
504    /// Reads each log of the session kept in `store` that reads, as
505    /// [`Self::read`] does, and sets aside each that does not, with why:
506    /// for a reader that shows what it can, such as an export or a search.
507    /// A restore reads strictly, so it never goes on from part of a
508    /// session.
509    ///
510    /// # Errors
511    ///
512    /// When the store cannot list its logs.
513    pub fn read_lenient(store: &dyn Store) -> Result<(Self, Vec<Unreadable>), SessionError> {
514        let mut folded = Vec::new();
515        let mut unreadable = Vec::new();
516        for log in store.logs()? {
517            match fold(store, &log, Fold::WHOLE) {
518                Ok(read) => folded.extend(read),
519                Err(error) => unreadable.push(Unreadable { log, error }),
520            }
521        }
522        let repairs = repairs(store, &folded)?;
523        Ok((session_of(folded, repairs), unreadable))
524    }
525
526    /// The agent `id`.
527    pub fn agent(&self, id: &str) -> Option<&SavedAgent> {
528        self.agents.iter().find(|agent| agent.id == id)
529    }
530
531    /// The agent `id`, to change it.
532    pub fn agent_mut(&mut self, id: &str) -> Option<&mut SavedAgent> {
533        self.agents.iter_mut().find(|agent| agent.id == id)
534    }
535
536    /// Saves the session to `store`, the one it was read from (or an empty
537    /// one): appends each agent's unsaved changes (an agent new to the
538    /// store gets a header), its changed and removed saved values, and its
539    /// retirement, and the session's changed values. Each agent's
540    /// conversation is left with nothing unsaved once its log is written; a
541    /// save that fails leaves the others with their unsaved changes, so it
542    /// can be tried again, and writes no change twice. A torn last line of
543    /// a log written to is first set aside, as
544    /// [`Writer::open`](crate::Writer::open) does.
545    ///
546    /// # Errors
547    ///
548    /// [`SessionError::Changed`], before anything is written, when a log
549    /// was started, written, rewritten or removed since the session was read
550    /// or last saved (unless `store` is empty, so a session saves as a copy
551    /// to an empty store), or a log that holds changes holds another
552    /// conversation than its agent's: read the session again and redo the
553    /// edit. When the store fails, a log is in another format, or a line has
554    /// no stamp; or when a write fails. It reads the stamps of the logs'
555    /// changes, not the changes, so a change that does not apply is refused
556    /// by [`Self::read`], not here.
557    pub fn save(&mut self, store: &dyn Store) -> Result<(), SessionError> {
558        let mut folded = Vec::new();
559        for (name, lines) in &read_logs(store)? {
560            folded.extend(tally(name, lines)?);
561        }
562        let now = ends(&folded);
563        if !now.is_empty() && now != self.ends {
564            let mut logs = now.keys().chain(self.ends.keys());
565            let log = logs.find(|log| now.get(*log) != self.ends.get(*log));
566            let log = log.cloned().unwrap_or_default();
567            return Err(SessionError::Changed { log });
568        }
569        let had = |id: &str| folded.iter().find(|log| log.name == id);
570        for agent in &self.agents {
571            if agent.id == SESSION {
572                let why = format!("{SESSION:?} is the session's own log, not an agent's");
573                return Err(io::Error::new(io::ErrorKind::InvalidInput, why).into());
574            }
575            check_continues(had(&agent.id), &agent.id, &agent.conversation)?;
576        }
577        let mut book = Book::after(&folded);
578        let torn = torn_tails(store, &folded)?.into_iter();
579        book.set_aside(torn.map(|(log, _, cut)| (log, cut)));
580        book.start();
581        let mut staged: Vec<_> = self.agents.iter().map(|a| a.conversation.clone()).collect();
582        for (agent, conversation) in self.agents.iter().zip(&mut staged) {
583            let _ = book.opened(&agent.id, agent.parent.as_deref());
584            let put = &mut |name: String, bytes: Vec<u8>| put_blob(store, &name, &bytes);
585            book.save(put, &agent.id, conversation);
586            let known = had(&agent.id).map(|log| &log.state);
587            book.states(&agent.id, known, &agent.saved);
588            if agent.retired && !had(&agent.id).is_some_and(|log| log.retired) {
589                book.retire(&agent.id);
590            }
591        }
592        let known = had(SESSION).map(|log| &log.state);
593        book.states(SESSION, known, &self.saved);
594        let flushed = book.flush(store);
595        self.ends = now.clone();
596        self.ends.extend(book.written());
597        for (agent, conversation) in self.agents.iter_mut().zip(staged) {
598            // A log whose end moved was written, with every change queued for it.
599            if flushed.is_ok() || self.ends.get(&agent.id) != now.get(&agent.id) {
600                agent.conversation = conversation;
601            }
602        }
603        flushed
604    }
605}
606
607/// Refuses to save `conversation` to the log `name`, now `log`, unless
608/// its unsaved changes continue that log or the log holds no change, so
609/// a reset to it loses nothing.
610fn check_continues(
611    log: Option<&Folded>,
612    name: &str,
613    conversation: &Conversation,
614) -> Result<(), SessionError> {
615    let Some(log) = log else {
616        return Ok(());
617    };
618    let changes = log.conversation.revision();
619    if changes > 0 && !conversation.continues(log.header.lineage, changes) {
620        return Err(SessionError::Changed {
621            log: name.to_owned(),
622        });
623    }
624    Ok(())
625}
626
627/// The conversation the log `log` of `store` holds; an empty one when
628/// there is none. It continues the log (its lineage and its number of
629/// changes), so [`save`] can tell whether the log moved on or the
630/// conversation is another.
631///
632/// An image whose blob is gone loads with no data, as a restore reads it;
633/// any other failure to read a blob fails the load, so a store that is
634/// down for a moment never loses an image from what a run sends.
635///
636/// # Errors
637///
638/// As [`Session::read`], for that log; when `log` is no log name; or when
639/// a blob it names cannot be read for a reason other than that it is gone.
640pub fn load(store: &dyn Store, log: &str) -> Result<Conversation, SessionError> {
641    check_log_name(log)?;
642    conversation_of(fold(store, log, Fold::WHOLE)?)
643}
644
645/// The conversation of `folded`, an empty one for no log; refused when an
646/// image of it could not be read for a reason other than that its blob is
647/// gone.
648pub(crate) fn conversation_of(folded: Option<Folded>) -> Result<Conversation, SessionError> {
649    let Some(folded) = folded else {
650        return Ok(Conversation::new());
651    };
652    let mut lost = folded.lost.into_iter();
653    match lost.find(|failure| failure.kind() != io::ErrorKind::NotFound) {
654        Some(failure) => Err(failure.into()),
655        None => Ok(folded.conversation),
656    }
657}
658
659/// Appends the unsaved changes of `conversation` to the log `log` of
660/// `store`, starting it when there is none, and leaves the conversation
661/// with nothing unsaved. A torn last line of the log is first set aside, as
662/// [`Writer::open`](crate::Writer::open) does.
663///
664/// ```
665/// use rig_core::message::Message;
666/// use rig_memory::{MemoryStore, load, save};
667///
668/// let store = MemoryStore::default();
669/// let mut conversation = load(&store, "user-123")?;
670/// conversation.push(Message::user("My name is Alice."));
671/// save(&store, "user-123", &mut conversation)?;
672/// assert_eq!(load(&store, "user-123")?, conversation);
673/// # Ok::<(), rig_memory::SessionError>(())
674/// ```
675///
676/// # Errors
677///
678/// [`SessionError::Changed`] when `conversation` does not continue the log
679/// (the log moved on since it was loaded, or it was loaded from another
680/// log or built elsewhere) and the log holds changes, or when another
681/// writer changed the log between this save's read and its append,
682/// writing nothing to it, so no change made there is lost; when the store
683/// fails, `log` is in another format, or a line of it has no stamp; or
684/// when a write fails. It
685/// reads the stamps of `log`'s records, not the records, so a change that
686/// does not apply is refused by [`load`], not here. Onto an empty log any
687/// conversation is saved, whole when it was not begun from nothing.
688pub fn save(
689    store: &dyn Store,
690    log: &str,
691    conversation: &mut Conversation,
692) -> Result<(), SessionError> {
693    now(save_async(store, log, conversation))
694}
695
696/// [`load`] from an [`AsyncStore`](crate::AsyncStore), such as a database
697/// or IndexedDB: the log read once, and the blobs its records name.
698///
699/// # Errors
700///
701/// As [`load`].
702pub async fn load_async<S: crate::AsyncStore + ?Sized>(
703    store: &S,
704    log: &str,
705) -> Result<Conversation, SessionError> {
706    check_log_name(log)?;
707    let bytes = match store.read_log_async(log).await {
708        Err(failure) if failure.kind() == io::ErrorKind::NotFound => {
709            return Ok(Conversation::new());
710        }
711        bytes => bytes?,
712    };
713    let mut named = std::collections::BTreeSet::new();
714    named_blobs(&bytes, &mut named);
715    let mut blobs = BTreeMap::new();
716    for name in named {
717        let read = store.read_file_async(&format!("{BLOBS}{name}")).await;
718        blobs.insert(name, read);
719    }
720    let blob = |name: &str| match blobs.get(name) {
721        Some(Ok(bytes)) => Ok(bytes.clone()),
722        Some(Err(failure)) => Err(io::Error::new(failure.kind(), failure.to_string())),
723        None => Err(io::ErrorKind::NotFound.into()),
724    };
725    conversation_of(fold_lines(
726        log,
727        &LogLines::parse(bytes),
728        Fold::WHOLE,
729        &blob,
730    )?)
731}
732
733/// [`save`] to an [`AsyncStore`](crate::AsyncStore): the log read once,
734/// then the blobs of new images written, then the changes appended with
735/// one write, which the store makes only if the log is still as it was
736/// read. A save reads only its own log, so one store holds many
737/// conversations, a log each. A save cut short, such as by a dropped
738/// future, has appended nothing, a cut last line (set aside by the next
739/// save), or, for a remote store that already applied it, all of it.
740///
741/// ```
742/// # async fn run() -> Result<(), rig_memory::SessionError> {
743/// use rig_core::message::Message;
744/// use rig_memory::{MemoryStore, load_async, save_async};
745///
746/// let store = MemoryStore::default();
747/// let mut conversation = load_async(&store, "user-123").await?;
748/// conversation.push(Message::user("My name is Alice."));
749/// save_async(&store, "user-123", &mut conversation).await?;
750/// assert_eq!(load_async(&store, "user-123").await?, conversation);
751/// # Ok(()) }
752/// ```
753///
754/// # Errors
755///
756/// As [`save`]. Of two saves that read the log at the same length, even
757/// at once, the store takes one and the other fails with
758/// [`SessionError::Changed`]. A save that fails leaves `conversation`
759/// with its unsaved changes, so it can be tried again.
760pub async fn save_async<S: crate::AsyncStore + ?Sized>(
761    store: &S,
762    log: &str,
763    conversation: &mut Conversation,
764) -> Result<(), SessionError> {
765    let lines = match store.read_log_async(log).await {
766        Err(failure) if failure.kind() == io::ErrorKind::NotFound => LogLines::parse(Vec::new()),
767        bytes => LogLines::parse(bytes?),
768    };
769    let folded = tally(log, &lines)?;
770    check_continues(folded.as_ref(), log, conversation)?;
771    let mut book = Book::after(folded.as_slice());
772    // This also covers a log of no complete line but a torn one, such as one whose first write
773    // was cut.
774    let cut = lines.tail().len() as u64;
775    book.set_aside((cut > 0).then(|| (log.to_owned(), cut)));
776    let mut staged = conversation.clone();
777    book.start();
778    let _ = book.opened(log, None);
779    let mut blobs = Vec::new();
780    let put = &mut |name, bytes| {
781        blobs.push((name, bytes));
782        Ok(())
783    };
784    book.save(put, log, &mut staged);
785    for (name, bytes) in blobs {
786        store
787            .write_file_async(&format!("{BLOBS}{name}"), &bytes)
788            .await?;
789    }
790    book.flush_async(store).await?;
791    *conversation = staged;
792    Ok(())
793}
794
795/// Every record of the log `log` of `store` after its header, in order,
796/// with its stamp; images are put back from their blobs. Empty when there
797/// is no log.
798///
799/// # Errors
800///
801/// As [`load`].
802pub fn history(store: &dyn Store, log: &str) -> Result<Vec<(Stamp, LogRecord)>, SessionError> {
803    let mut records = Vec::new();
804    read(store, log, |stamp, body| {
805        let record = match body {
806            Body::Change(mut recorded) => {
807                // A lost image is read without data, as by a restore.
808                let _ = messages_mut(&mut recorded.change, &mut |message| {
809                    let _ = load_images_with(message, &|name| read_blob(store, name));
810                    Ok(())
811                });
812                LogRecord::Change(recorded)
813            }
814            Body::Meta(Meta::State { key, value }) => LogRecord::Saved {
815                key,
816                value: value.filter(|value| !value.is_null()),
817            },
818            Body::Meta(Meta::Retired) => LogRecord::Retired,
819            Body::Meta(Meta::Header(_)) => return Ok(ControlFlow::Continue(())),
820        };
821        records.push((stamp, record));
822        Ok(ControlFlow::Continue(()))
823    })?;
824    Ok(records)
825}
826
827/// Reads the log `log` of `store` once, as [`load`] does, giving `each`
828/// every change with the conversation the changes before it left. Nothing
829/// when there is no log.
830///
831/// # Errors
832///
833/// As [`load`].
834pub(crate) fn replay(
835    store: &dyn Store,
836    log: &str,
837    mut each: impl FnMut(&Conversation, &ChangeRecord),
838) -> Result<(), SessionError> {
839    if let Some(lines) = log_lines(store, log)? {
840        let blob = |blob: &str| read_blob(store, blob);
841        fold_lines_with(log, &lines, (Fold::WHOLE, &blob), &mut each)?;
842    }
843    Ok(())
844}
845
846/// The conversation of the log `log` of `store` as the records made before
847/// the session's record `n` left it ([`Stamp::n`]); an empty one when
848/// there is no log.
849///
850/// # Errors
851///
852/// As [`load`].
853pub fn as_of(store: &dyn Store, log: &str, n: u64) -> Result<Conversation, SessionError> {
854    let how = Fold {
855        until: Some(n),
856        ..Fold::WHOLE
857    };
858    conversation_of(fold(store, log, how)?)
859}
860#[cfg(test)]
861mod tests;