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