refactor(ui): Create a mapping between remote events to timeline items

[Hywan]

A messenger trying to find its path in an unknown land

---

Don't be fooled by the number of new lines in this PR, patches are small and relatively easy to read. Most of the new lines are documentation or tests (around 1300).

The idea of this PR is to create a mapping between events to timeline items. More precisely, a mapping between event indexes and timeline item indexes. Why is this needed? We want Timeline to receive its updates via VectorDiff. Those VectorDiff are generated by the EventCache (via linked_chunk::AsVector). The indexes from these VectorDiff —like VectorDiff::Insert { index, .. } or VectorDiff::Remove { index }— are event index. The Timeline manipulates a collection of timeline items, where each item has an event ID, but no event index.

Fortunately for us, a recent patch has clarified an internal data type, now known as AllRemoteEvents (see #4370). We can re-use this type to maintain an index between the events and the timeline items.

This PR must be reviewed patch-by-patch:

• The first 3 patches are adding the EventMeta::timeline_item_index field, and maintains it. That's it, everything works at this step!
• The other patches are a refactoring to make this mechanism more robust:
  • It introduces ObservableItems which is a new type that replaces/wraps ObservableVector<Arc<TimelineItem>>: the idea is to provide a small API we control!
  • Then, AllRemoteEvents is moved inside ObservableItems, so that operations on the items and the events happen “atomically”, which removes many possible errors of misuses.
• Finally, the last patches add documentations and tests.

---

• Address [meta] EventCache storage #3280
• Follow up feat(ui): Propagate RoomEventCache's VectorDiff to Timeline #3512 but these patches have taken a very different approach with new types like AllRemoteEvents and ObservableItems types.

[codecov]

Codecov Report

Attention: Patch coverage is 93.82716% with 15 lines in your changes missing coverage. Please review.

Project coverage is 85.21%. Comparing base (ee93c27) to head (bd648cd).
Report is 47 commits behind head on main.

Files with missing lines	Patch %	Lines
crates/matrix-sdk-ui/src/timeline/event_handler.rs	80.00%	7 Missing ⚠️
...tes/matrix-sdk-ui/src/timeline/controller/state.rs	84.21%	3 Missing ⚠️
...rates/matrix-sdk-ui/src/timeline/controller/mod.rs	94.28%	2 Missing ⚠️
crates/matrix-sdk-ui/src/timeline/read_receipts.rs	92.30%	2 Missing ⚠️
crates/matrix-sdk-ui/src/timeline/day_dividers.rs	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4377      +/-   ##
==========================================
+ Coverage   85.15%   85.21%   +0.05%     
==========================================
  Files         280      281       +1     
  Lines       30831    30971     +140     
==========================================
+ Hits        26254    26391     +137     
- Misses       4577     4580       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Hywan]

I think there is a problem when replacing a timeline item. I need to investigate that. Moving back the PR as a draft.

[Hywan]

I think the current PR was actually alright. When editing a timeline item, its internal event_id doesn't change, I think it would break all the replies to such timeline item otherwise. I think it's fine with the actual state of this PR.

[poljar]

I think all of this makes sense, a bit challenging to review since some aspects of my review were already addressed in subsequent comments.

I mostly left a bunch of nits here and there. The unsafe function makes me uneasy so would be good to rethink if we could express this a bit differently.

[poljar]

Nice, looks good.