nostr_database/collections/
events.rs

1// Copyright (c) 2022-2023 Yuki Kishimoto
2// Copyright (c) 2023-2025 Rust Nostr Developers
3// Distributed under the MIT software license
4
5use std::collections::btree_set::IntoIter;
6use std::collections::hash_map::DefaultHasher;
7use std::hash::{Hash, Hasher};
8
9use nostr::{Event, Filter};
10
11use super::tree::{BTreeCappedSet, Capacity, OverCapacityPolicy};
12
13// Lookup ID: EVENT_ORD_IMPL
14const POLICY: OverCapacityPolicy = OverCapacityPolicy::Last;
15
16/// Descending sorted collection of events
17#[derive(Debug, Clone)]
18pub struct Events {
19    set: BTreeCappedSet<Event>,
20    hash: u64,
21    prev_not_match: bool,
22}
23
24impl PartialEq for Events {
25    fn eq(&self, other: &Self) -> bool {
26        self.set == other.set
27    }
28}
29
30impl Eq for Events {}
31
32impl Events {
33    /// New collection
34    #[inline]
35    pub fn new(filter: &Filter) -> Self {
36        let mut hasher = DefaultHasher::new();
37        filter.hash(&mut hasher);
38        let hash: u64 = hasher.finish();
39
40        let set: BTreeCappedSet<Event> = match filter.limit {
41            Some(limit) => BTreeCappedSet::bounded_with_policy(limit, POLICY),
42            None => BTreeCappedSet::unbounded(),
43        };
44
45        Self {
46            set,
47            hash,
48            prev_not_match: false,
49        }
50    }
51
52    /// Returns the number of events in the collection.
53    #[inline]
54    pub fn len(&self) -> usize {
55        self.set.len()
56    }
57
58    /// Returns the number of events in the collection.
59    #[inline]
60    pub fn is_empty(&self) -> bool {
61        self.set.is_empty()
62    }
63
64    /// Check if contains [`Event`]
65    #[inline]
66    pub fn contains(&self, event: &Event) -> bool {
67        self.set.contains(event)
68    }
69
70    /// Insert [`Event`]
71    ///
72    /// If the set did not previously contain an equal value, `true` is returned.
73    /// If the collection is full, the older events will be discarded.
74    /// Use [`Events::force_insert`] to always make sure the event is inserted.
75    #[inline]
76    pub fn insert(&mut self, event: Event) -> bool {
77        self.set.insert(event).inserted
78    }
79
80    /// Force insert [`Event`]
81    ///
82    /// Use [`Events::insert`] to respect the max collection capacity (if any).
83    /// If the collection capacity is full, this method will increase it.
84    #[inline]
85    pub fn force_insert(&mut self, event: Event) -> bool {
86        self.set.force_insert(event).inserted
87    }
88
89    /// Insert events
90    #[inline]
91    pub fn extend<I>(&mut self, events: I)
92    where
93        I: IntoIterator<Item = Event>,
94    {
95        self.set.extend(events);
96    }
97
98    /// Merge events collections into a single one.
99    ///
100    /// Collection is converted to unbounded if one of the merge [`Events`] have a different hash.
101    /// In other words, the filters limit is respected only if the [`Events`] are related to the same
102    /// list of filters.
103    pub fn merge(mut self, other: Self) -> Self {
104        // Hash not match -> change capacity to unbounded
105        if self.hash != other.hash || self.prev_not_match || other.prev_not_match {
106            self.set.change_capacity(Capacity::Unbounded);
107            self.hash = 0;
108            self.prev_not_match = true;
109        }
110
111        // Extend
112        self.extend(other.set);
113
114        self
115    }
116
117    /// Get first [`Event`] (descending order)
118    #[inline]
119    pub fn first(&self) -> Option<&Event> {
120        // Lookup ID: EVENT_ORD_IMPL
121        self.set.first()
122    }
123
124    /// Get first [`Event`] (descending order)
125    #[inline]
126    pub fn first_owned(self) -> Option<Event> {
127        // Lookup ID: EVENT_ORD_IMPL
128        self.into_iter().next()
129    }
130
131    /// Get last [`Event`] (descending order)
132    #[inline]
133    pub fn last(&self) -> Option<&Event> {
134        // Lookup ID: EVENT_ORD_IMPL
135        self.set.last()
136    }
137
138    /// Get last [`Event`] (descending order)
139    #[inline]
140    pub fn last_owned(self) -> Option<Event> {
141        // Lookup ID: EVENT_ORD_IMPL
142        self.into_iter().next_back()
143    }
144
145    /// Iterate events in descending order
146    #[inline]
147    pub fn iter(&self) -> impl Iterator<Item = &Event> {
148        // Lookup ID: EVENT_ORD_IMPL
149        self.set.iter()
150    }
151
152    /// Convert the collection to vector of events.
153    #[inline]
154    pub fn to_vec(self) -> Vec<Event> {
155        self.into_iter().collect()
156    }
157}
158
159impl IntoIterator for Events {
160    type Item = Event;
161    type IntoIter = IntoIter<Self::Item>;
162
163    fn into_iter(self) -> Self::IntoIter {
164        // Lookup ID: EVENT_ORD_IMPL
165        self.set.into_iter()
166    }
167}
168
169#[cfg(test)]
170mod tests {
171    use nostr::{JsonUtil, Kind};
172
173    use super::*;
174
175    #[test]
176    fn test_events_equality() {
177        // Match
178        {
179            let event1 = Event::from_json(r#"{"content":"Kind 10050 is for DMs, kind 10002 for the other stuff. But both have the same aim. So IMO both have to be under the `gossip` option.","created_at":1732738371,"id":"f2d71a515ce3576d238aaaeaa48fde97388162d08208f729b540a4c3f9723e6b","kind":1,"pubkey":"68d81165918100b7da43fc28f7d1fc12554466e1115886b9e7bb326f65ec4272","sig":"d88d3ac21036cfb541809288c12844747dbf1d20a246133dbd37374254b281808c5582bade27c880477759491b2b964d7235142c8b80d233dfb9ae8a50252119","tags":[["e","8262a50cf7832351ae3f21c429e111bb31be0cf754ec437e015534bf5cc2eee8","","root"],["e","0f4bcc83ef2af2febbc7eb9aea5d615a29084ed9e65c467ef2a9387ff79b57e8"],["e","94469431e367b2c16e6d224a4ac2c369c18718a1abdf42759ff591d9816b5ff3","","reply"],["p","68d81165918100b7da43fc28f7d1fc12554466e1115886b9e7bb326f65ec4272"],["p","1739d937dc8c0c7370aa27585938c119e25c41f6c441a5d34c6d38503e3136ef"],["p","03f9cfd948e95aeb04f780382344f7c1cfc0210d9af3f4006bb6d451c7b08692"],["p","126103bfddc8df256b6e0abfd7f3797c80dcc4ea88f7c2f87dd4104220b4d65f"],["p","13a665157257e79d9dcc960deeb367fd79383be2d0babb3d861679a5701d463b"],["p","ee0d20b47fb298e8a9ed3609108fe7f2296bd71e8b82fb4f9ff8f61f62bbc7a6"],["p","1c71312fb45273956b078e27981dcc15b178db8d55bffd7ad57a8cfaed6b5ab4"],["p","800e0fe3d8638ce3f75a56ed865df9d96fc9d9cd2f75550df0d7f5c1d8468b0b"]]}"#).unwrap();
180            let mut events1 = Events::new(&Filter::new().kind(Kind::TextNote).limit(1));
181            events1.insert(event1);
182
183            let event2 = Event::from_json(r#"{"content":"Kind 10050 is for DMs, kind 10002 for the other stuff. But both have the same aim. So IMO both have to be under the `gossip` option.","created_at":1732738371,"id":"f2d71a515ce3576d238aaaeaa48fde97388162d08208f729b540a4c3f9723e6b","kind":1,"pubkey":"68d81165918100b7da43fc28f7d1fc12554466e1115886b9e7bb326f65ec4272","sig":"d88d3ac21036cfb541809288c12844747dbf1d20a246133dbd37374254b281808c5582bade27c880477759491b2b964d7235142c8b80d233dfb9ae8a50252119","tags":[["e","8262a50cf7832351ae3f21c429e111bb31be0cf754ec437e015534bf5cc2eee8","","root"],["e","0f4bcc83ef2af2febbc7eb9aea5d615a29084ed9e65c467ef2a9387ff79b57e8"],["e","94469431e367b2c16e6d224a4ac2c369c18718a1abdf42759ff591d9816b5ff3","","reply"],["p","68d81165918100b7da43fc28f7d1fc12554466e1115886b9e7bb326f65ec4272"],["p","1739d937dc8c0c7370aa27585938c119e25c41f6c441a5d34c6d38503e3136ef"],["p","03f9cfd948e95aeb04f780382344f7c1cfc0210d9af3f4006bb6d451c7b08692"],["p","126103bfddc8df256b6e0abfd7f3797c80dcc4ea88f7c2f87dd4104220b4d65f"],["p","13a665157257e79d9dcc960deeb367fd79383be2d0babb3d861679a5701d463b"],["p","ee0d20b47fb298e8a9ed3609108fe7f2296bd71e8b82fb4f9ff8f61f62bbc7a6"],["p","1c71312fb45273956b078e27981dcc15b178db8d55bffd7ad57a8cfaed6b5ab4"],["p","800e0fe3d8638ce3f75a56ed865df9d96fc9d9cd2f75550df0d7f5c1d8468b0b"]]}"#).unwrap();
184            let mut events2 = Events::new(&Filter::new().kind(Kind::TextNote).limit(2)); // Different filter from above
185            events2.insert(event2);
186
187            assert_eq!(events1, events2);
188        }
189
190        // NOT match
191        {
192            let event1 = Event::from_json(r#"{"content":"Kind 10050 is for DMs, kind 10002 for the other stuff. But both have the same aim. So IMO both have to be under the `gossip` option.","created_at":1732738371,"id":"f2d71a515ce3576d238aaaeaa48fde97388162d08208f729b540a4c3f9723e6b","kind":1,"pubkey":"68d81165918100b7da43fc28f7d1fc12554466e1115886b9e7bb326f65ec4272","sig":"d88d3ac21036cfb541809288c12844747dbf1d20a246133dbd37374254b281808c5582bade27c880477759491b2b964d7235142c8b80d233dfb9ae8a50252119","tags":[["e","8262a50cf7832351ae3f21c429e111bb31be0cf754ec437e015534bf5cc2eee8","","root"],["e","0f4bcc83ef2af2febbc7eb9aea5d615a29084ed9e65c467ef2a9387ff79b57e8"],["e","94469431e367b2c16e6d224a4ac2c369c18718a1abdf42759ff591d9816b5ff3","","reply"],["p","68d81165918100b7da43fc28f7d1fc12554466e1115886b9e7bb326f65ec4272"],["p","1739d937dc8c0c7370aa27585938c119e25c41f6c441a5d34c6d38503e3136ef"],["p","03f9cfd948e95aeb04f780382344f7c1cfc0210d9af3f4006bb6d451c7b08692"],["p","126103bfddc8df256b6e0abfd7f3797c80dcc4ea88f7c2f87dd4104220b4d65f"],["p","13a665157257e79d9dcc960deeb367fd79383be2d0babb3d861679a5701d463b"],["p","ee0d20b47fb298e8a9ed3609108fe7f2296bd71e8b82fb4f9ff8f61f62bbc7a6"],["p","1c71312fb45273956b078e27981dcc15b178db8d55bffd7ad57a8cfaed6b5ab4"],["p","800e0fe3d8638ce3f75a56ed865df9d96fc9d9cd2f75550df0d7f5c1d8468b0b"]]}"#).unwrap();
193            let mut events1 = Events::new(&Filter::new().kind(Kind::TextNote).limit(1));
194            events1.insert(event1);
195
196            let event2 = Event::from_json(r#"{"content":"Thank you !","created_at":1732738224,"id":"035a18ba52a9b40137c0c60ed955eb1f1f93e12423082f6d8a83f62726462d21","kind":1,"pubkey":"1c71312fb45273956b078e27981dcc15b178db8d55bffd7ad57a8cfaed6b5ab4","sig":"54921c7a4f972428c67267a0d99df7d5094c7ca4d26fe9c08221de88ffafb0cab347939ff77129ecfdebad6b18cd2c4c229bf67ce8914fe778d24e19bc22be43","tags":[["p","68d81165918100b7da43fc28f7d1fc12554466e1115886b9e7bb326f65ec4272"],["p","1739d937dc8c0c7370aa27585938c119e25c41f6c441a5d34c6d38503e3136ef"],["p","03f9cfd948e95aeb04f780382344f7c1cfc0210d9af3f4006bb6d451c7b08692"],["p","126103bfddc8df256b6e0abfd7f3797c80dcc4ea88f7c2f87dd4104220b4d65f"],["p","13a665157257e79d9dcc960deeb367fd79383be2d0babb3d861679a5701d463b"],["p","ee0d20b47fb298e8a9ed3609108fe7f2296bd71e8b82fb4f9ff8f61f62bbc7a6"],["e","8262a50cf7832351ae3f21c429e111bb31be0cf754ec437e015534bf5cc2eee8","wss://nos.lol/","root"],["e","670303f9cbb24568c705b545c277be1f5172ad84795cc9e700aeea5bb248fd74","wss://n.ok0.org/","reply"]]}"#).unwrap();
197            let mut events2 = Events::new(&Filter::new().kind(Kind::TextNote).limit(2)); // Different filter from above
198            events2.insert(event2);
199
200            assert_ne!(events1, events2);
201        }
202    }
203
204    #[test]
205    fn test_merge() {
206        // Same filter
207        let filter = Filter::new().kind(Kind::TextNote).limit(100);
208
209        let events1 = Events::new(&filter);
210        assert_eq!(
211            events1.set.capacity(),
212            Capacity::Bounded {
213                max: 100,
214                policy: POLICY
215            }
216        );
217
218        let events2 = Events::new(&filter);
219        assert_eq!(
220            events2.set.capacity(),
221            Capacity::Bounded {
222                max: 100,
223                policy: POLICY
224            }
225        );
226
227        let hash1 = events1.hash;
228
229        assert_eq!(events1.hash, events2.hash);
230
231        let events = events1.merge(events2);
232        assert_eq!(events.hash, hash1);
233        assert!(!events.prev_not_match);
234        assert_eq!(
235            events.set.capacity(),
236            Capacity::Bounded {
237                max: 100,
238                policy: POLICY
239            }
240        );
241
242        // Different filters
243        let filter1 = Filter::new().kind(Kind::TextNote).limit(100);
244        let filter2 = Filter::new().kind(Kind::Metadata).limit(10);
245        let filter3 = Filter::new().kind(Kind::ContactList).limit(1);
246
247        let events1 = Events::new(&filter1);
248        assert_eq!(
249            events1.set.capacity(),
250            Capacity::Bounded {
251                max: 100,
252                policy: POLICY
253            }
254        );
255
256        let events2 = Events::new(&filter2);
257        assert_eq!(
258            events2.set.capacity(),
259            Capacity::Bounded {
260                max: 10,
261                policy: POLICY
262            }
263        );
264
265        let events3 = Events::new(&filter3);
266        assert_eq!(
267            events3.set.capacity(),
268            Capacity::Bounded {
269                max: 1,
270                policy: POLICY
271            }
272        );
273
274        assert_ne!(events1.hash, events2.hash);
275
276        let events = events1.merge(events2);
277        assert_eq!(events.hash, 0);
278        assert!(events.prev_not_match);
279        assert_eq!(events.set.capacity(), Capacity::Unbounded);
280
281        let events = events.merge(events3);
282        assert_eq!(events.hash, 0);
283        assert!(events.prev_not_match);
284        assert_eq!(events.set.capacity(), Capacity::Unbounded);
285    }
286}
nostr_database/collections/events.rs

nostr_database/collections/
events.rs
