macltok

public

Star0

Fork 0

Watch0

10 commits 3 branches 0 tags 0 releases3.0 MiB

Commit `d5d8097c3afd`

tarball

atagen <boss@atagen.co>2026-09-27 01:42 UTC

9 files changed+113-42

timeline: share snapshots as imbl vectors

A state mirror hands out a timeline with every update, which as a Vec is a deep copy of every item each time. TimelineReset now carries an imbl::Vector, the type matrix-sdk-ui already keeps its own timelines in. try_apply_all checks a whole batch against lengths before touching anything, so a misfit halfway through no longer leaves the snapshot half applied.

Modified file: Cargo.lock+1

@@ -1827,6 +1827,7 @@ dependencies = [

18271827 "getrandom 0.3.4",

18281828 "getrandom 0.4.3",

18291829 "http",

1830+ "imbl",

18301831 "matrix-sdk",

18311832 "matrix-sdk-crypto",

18321833 "matrix-sdk-test",

Modified file: Cargo.toml+2 additions−1 deletions@@ -6,7 +6,7 @@ description = "A compact application backend on top of the Matrix Rust SDK"
 
 [features]
 default = []
-serde = ["dep:serde"]
+serde = ["dep:serde", "imbl/serde"]
 sqlite = ["matrix-sdk/sqlite", "serde", "dep:url"]
 bundled-sqlite = ["sqlite", "matrix-sdk/bundled-sqlite"]
 indexeddb = ["matrix-sdk/indexeddb", "serde", "dep:url"]
@@ -14,6 +14,7 @@ indexeddb = ["matrix-sdk/indexeddb", "serde", "dep:url"]
 [dependencies]
 futures-util = { version = "0.3.31", default-features = false, features = ["std"] }
 http = "1"
+imbl = { version = "6.1.0", default-features = false }
 matrix-sdk = { version = "0.18.0", default-features = false, features = ["e2e-encryption"] }
 matrix-sdk-crypto = { version = "0.18.0", default-features = false }
 matrix-sdk-ui = { version = "0.18.0", default-features = false }

Modified file: README.md+4 additions−3 deletions@@ -29,9 +29,10 @@ drop. a sent message answers when the sdk send queue has it, delivery shows up
 as the timeline item's send state. reads like `rooms`, `members` and `media`
 go straight to the sdk. the stream only carries state
 
-start a timeline from `TimelineReset`, then apply `TimelineChanged` diffs with
-`TimelineDiff::try_apply`. when one doesn't fit, stop applying, call `resync`,
-and pick up from the next `TimelineReset`
+start a timeline from `TimelineReset`, then apply each `TimelineChanged` whole
+with `TimelineDiff::try_apply_all`. snapshots are `imbl::Vector`s, re-exported
+as `macltok::imbl`, so a copy costs nothing. when a batch doesn't fit none of it
+lands. stop applying, call `resync`, and pick up from the next `TimelineReset`
 
 With `sqlite` or `indexeddb`, persist the initial `Session::record()`
 separately from its encrypted store. On `SessionTokensChanged`, obtain a new record from

Modified file: docs/design-decisions.md+6 additions−3 deletions@@ -84,9 +84,12 @@ and gets logged
 ## timelines
 
 `TimelineDiff::try_apply` refuses a diff whose indices don't fit your snapshot
-and leaves the snapshot alone. stop applying, `resync`, and carry on from the
-next `TimelineReset`. resync kills the old watcher before the new reset goes
-out, so no stale diff can land after it
+and leaves the snapshot alone. `try_apply_all` does the same for a whole batch,
+checking every diff against lengths alone first, since that's all a diff's fit
+depends on. snapshots are `imbl::Vector`s so keeping one is a pointer copy.
+stop applying, `resync`, and carry on from the next `TimelineReset`. resync
+kills the old watcher before the new reset goes out, so no stale diff can land
+after it
 
 `TimelineId` tells a room from a thread by its root event
 

Modified file: examples/headless.rs+4 additions−4 deletions@@ -1,6 +1,6 @@
 use macltok::{
     EngineConfig, Event, PasswordLogin, Retain, RoomMembership, Session, StoreConfig,
-    TimelineContent, TimelineId, TimelineItem,
+    TimelineContent, TimelineDiff, TimelineId, TimelineItem, imbl::Vector,
 };
 
 #[tokio::main]
@@ -30,7 +30,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     let (engine, handle, mut events) = session.build(EngineConfig::default()).await?;
     let running = tokio::spawn(engine.run());
     let mut opened: Option<TimelineId> = None;
-    let mut items = Vec::new();
+    let mut items = Vector::new();
     let mut stale = false;
 
     loop {
@@ -66,7 +66,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
                     Event::TimelineChanged { timeline_id, diffs }
                         if !stale && opened.as_ref() == Some(&timeline_id) =>
                     {
-                        if diffs.into_iter().any(|diff| diff.try_apply(&mut items).is_err()) {
+                        if TimelineDiff::try_apply_all(diffs, &mut items).is_err() {
                             stale = true;
                             let handle = handle.clone();
                             tokio::spawn(async move { handle.resync(timeline_id).await });
@@ -96,7 +96,7 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 
-fn print_messages(items: &[TimelineItem]) {
+fn print_messages(items: &Vector<TimelineItem>) {
     for item in items {
         if let TimelineItem::Event(event) = item
             && let TimelineContent::Message(message) = &event.content

Modified file: src/lib.rs+1

@@ -25,6 +25,7 @@ pub use account::{

2525

2626 pub use engine::{Engine, EngineConfig, EngineError};

2727 pub use error::{Error, ErrorKind};

28+pub use imbl;

2829 pub use model::{

2930 AccountCommand, AttachmentUpload, Change, Command, CommandOutput, ConnectionState,

3031 CreateRoomOptions, EncryptionCommand, EncryptionState, EngineErrorKind, EngineFailure, Event,

Modified file: src/model.rs+93 additions−29 deletions@@ -1,5 +1,6 @@
 use std::{fmt, sync::Arc};
 
+use imbl::Vector;
 use ruma::{
     OwnedDeviceId, OwnedEventId, OwnedMxcUri, OwnedRoomAliasId, OwnedRoomId, OwnedRoomOrAliasId,
     OwnedServerName, OwnedTransactionId, OwnedUserId,
@@ -648,7 +649,7 @@ pub enum Event {
     /// replaces whatever you had for this timeline. every diff after it applies to it
     TimelineReset {
         timeline_id: TimelineId,
-        items: Vec<TimelineItem>,
+        items: Vector<TimelineItem>,
     },
     TimelineChanged {
         timeline_id: TimelineId,
@@ -1151,43 +1152,75 @@ impl TimelineDiff {
     /// Apply a diff only when its indices match the current snapshot.
     /// On error the snapshot is unchanged; request `TimelineCommand::Resync`
     /// and ignore further diffs until the corresponding `TimelineReset`.
-    pub fn try_apply(self, items: &mut Vec<TimelineItem>) -> Result<(), TimelineDiffError> {
+    pub fn try_apply(self, items: &mut Vector<TimelineItem>) -> Result<(), TimelineDiffError> {
         let length = items.len();
+        if self.length_after(length).is_none() {
+            return Err(TimelineDiffError { length });
+        }
+        self.apply(items);
+        Ok(())
+    }
+
+    /// a whole `TimelineChanged` or none of it. whether a diff fits depends only on the
+    /// length before it, so the batch is checked against lengths alone before anything
+    /// moves. the error carries the length the snapshot would have had at the misfit
+    pub fn try_apply_all(
+        diffs: Vec<Self>,
+        items: &mut Vector<TimelineItem>,
+    ) -> Result<(), TimelineDiffError> {
+        diffs.iter().try_fold(items.len(), |length, diff| {
+            diff.length_after(length)
+                .ok_or(TimelineDiffError { length })
+        })?;
+        for diff in diffs {
+            diff.apply(items);
+        }
+        Ok(())
+    }
+
+    fn length_after(&self, length: usize) -> Option<usize> {
+        match self {
+            Self::Append { values } => Some(length + values.len()),
+            Self::Clear => Some(0),
+            Self::PushFront { .. } | Self::PushBack { .. } => Some(length + 1),
+            Self::PopFront | Self::PopBack => length.checked_sub(1),
+            Self::Insert { index, .. } => (*index <= length).then_some(length + 1),
+            Self::Set { index, .. } => (*index < length).then_some(length),
+            Self::Remove { index } => (*index < length).then(|| length - 1),
+            Self::Truncate { length: target } => (*target <= length).then_some(*target),
+            Self::Reset { values } => Some(values.len()),
+        }
+    }
+
+    fn apply(self, items: &mut Vector<TimelineItem>) {
         match self {
             Self::Append { values } => items.extend(values),
             Self::Clear => items.clear(),
-            Self::PushFront { value } => items.insert(0, value),
-            Self::PushBack { value } => items.push(value),
-            Self::PopFront if length == 0 => return Err(TimelineDiffError { length }),
+            Self::PushFront { value } => items.push_front(value),
+            Self::PushBack { value } => items.push_back(value),
             Self::PopFront => {
-                items.remove(0);
+                items.pop_front();
             }
-            Self::PopBack if length == 0 => return Err(TimelineDiffError { length }),
             Self::PopBack => {
-                items.pop();
-            }
-            Self::Insert { index, .. } if index > length => {
-                return Err(TimelineDiffError { length });
+                items.pop_back();
             }
             Self::Insert { index, value } => items.insert(index, value),
-            Self::Set { index, .. } if index >= length => return Err(TimelineDiffError { length }),
-            Self::Set { index, value } => items[index] = value,
-            Self::Remove { index } if index >= length => return Err(TimelineDiffError { length }),
+            Self::Set { index, value } => {
+                items.set(index, value);
+            }
             Self::Remove { index } => {
                 items.remove(index);
             }
-            Self::Truncate { length: target } if target > length => {
-                return Err(TimelineDiffError { length });
-            }
             Self::Truncate { length } => items.truncate(length),
-            Self::Reset { values } => *items = values,
+            Self::Reset { values } => *items = values.into_iter().collect(),
         }
-        Ok(())
     }
 }
 
 #[cfg(test)]
 mod tests {
+    use imbl::{Vector, vector};
+
     use super::{TimelineDiff, TimelineItem};
 
     fn item(timestamp_ms: u64) -> TimelineItem {
@@ -1196,14 +1229,14 @@ mod tests {
 
     #[test]
     fn timeline_diff_try_apply_handles_every_variant() {
-        let mut items = vec![item(1), item(2)];
+        let mut items = vector![item(1), item(2)];
 
         TimelineDiff::Append {
             values: vec![item(3)],
         }
         .try_apply(&mut items)
         .unwrap();
-        assert_eq!(items, vec![item(1), item(2), item(3)]);
+        assert_eq!(items, vector![item(1), item(2), item(3)]);
 
         TimelineDiff::Clear.try_apply(&mut items).unwrap();
         assert!(items.is_empty());
@@ -1214,7 +1247,7 @@ mod tests {
         TimelineDiff::PushBack { value: item(3) }
             .try_apply(&mut items)
             .unwrap();
-        assert_eq!(items, vec![item(2), item(3)]);
+        assert_eq!(items, vector![item(2), item(3)]);
 
         TimelineDiff::PopFront.try_apply(&mut items).unwrap();
         TimelineDiff::PopBack.try_apply(&mut items).unwrap();
@@ -1231,7 +1264,7 @@ mod tests {
         }
         .try_apply(&mut items)
         .unwrap();
-        assert_eq!(items, vec![item(1), item(2), item(3)]);
+        assert_eq!(items, vector![item(1), item(2), item(3)]);
 
         TimelineDiff::Set {
             index: 1,
@@ -1239,17 +1272,17 @@ mod tests {
         }
         .try_apply(&mut items)
         .unwrap();
-        assert_eq!(items, vec![item(1), item(4), item(3)]);
+        assert_eq!(items, vector![item(1), item(4), item(3)]);
 
         TimelineDiff::Remove { index: 1 }
             .try_apply(&mut items)
             .unwrap();
-        assert_eq!(items, vec![item(1), item(3)]);
+        assert_eq!(items, vector![item(1), item(3)]);
 
         TimelineDiff::Truncate { length: 1 }
             .try_apply(&mut items)
             .unwrap();
-        assert_eq!(items, vec![item(1)]);
+        assert_eq!(items, vector![item(1)]);
     }
 
     #[test]
@@ -1267,16 +1300,47 @@ mod tests {
             TimelineDiff::Truncate { length: 3 },
         ];
         for diff in invalid {
-            let mut items = vec![item(1), item(2)];
+            let mut items = vector![item(1), item(2)];
             assert_eq!(diff.try_apply(&mut items).unwrap_err().length, 2);
-            assert_eq!(items, vec![item(1), item(2)]);
+            assert_eq!(items, vector![item(1), item(2)]);
         }
         for diff in [TimelineDiff::PopFront, TimelineDiff::PopBack] {
-            let mut items = Vec::new();
+            let mut items = Vector::new();
             assert_eq!(diff.try_apply(&mut items).unwrap_err().length, 0);
             assert!(items.is_empty());
         }
     }
+
+    #[test]
+    fn a_batch_that_goes_wrong_halfway_changes_nothing() {
+        let mut items = vector![item(1), item(2)];
+        let batch = vec![
+            TimelineDiff::PushBack { value: item(3) },
+            TimelineDiff::Remove { index: 0 },
+            TimelineDiff::Set {
+                index: 2,
+                value: item(4),
+            },
+        ];
+        assert_eq!(
+            TimelineDiff::try_apply_all(batch, &mut items)
+                .unwrap_err()
+                .length,
+            2
+        );
+        assert_eq!(items, vector![item(1), item(2)]);
+
+        let batch = vec![
+            TimelineDiff::PushBack { value: item(3) },
+            TimelineDiff::Remove { index: 0 },
+            TimelineDiff::Set {
+                index: 1,
+                value: item(4),
+            },
+        ];
+        TimelineDiff::try_apply_all(batch, &mut items).unwrap();
+        assert_eq!(items, vector![item(2), item(4)]);
+    }
 }
 
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]

Modified file: src/normalise/timeline.rs+1−1

@@ -31,7 +31,7 @@ use super::media::{

3131

3232 #[derive(Default)]

3333 pub(crate) struct NormalisedTimeline {

34- pub(crate) items: Vec<TimelineItem>,

34+ pub(crate) items: imbl::Vector<TimelineItem>,

3535 pub(crate) media: Vec<MediaRegistration>,

3636 /// replies whose target isn't loaded, so somebody should go and ask for it

3737 pub(crate) missing_replies: Vec<OwnedEventId>,

Modified file: tests/engine.rs+1−1

@@ -518,7 +518,7 @@ async fn resync_and_confirm_reset_first(

518518 handle: &ClientHandle,

519519 events: &mut EventStream,

520520 timeline_id: TimelineId,

521-) -> Vec<TimelineItem> {

521+) -> macltok::imbl::Vector<TimelineItem> {

522522 let mut pending = handle

523523 .send(Command::Timeline(TimelineCommand::Resync {

524524 timeline_id: timeline_id.clone(),

macltok

Commit d5d8097c3afd

Commit `d5d8097c3afd`