Skip to main content

matter_kit/dm/
events.rs

1//! The event store (Core §7.14) — the node's log of things that happened.
2//!
3//! > Unlike attributes, which do not provide any edge-preserving capabilities (i.e. no
4//! > guarantees that every attribute change will be conveyed to observers), events permit
5//! > capturing every single edge or change and conveying it reliably to an observer. **This
6//! > is critical for safety and security applications that rely upon such guarantees for
7//! > correct behavior.**
8//!
9//! That is the whole difference. A subscriber that misses an attribute report learns the new
10//! value on the next one; a subscriber that misses a `Leave` event never learns the node left.
11//! So events are buffered, numbered, and delivered in order.
12//!
13//! # The number is the guarantee
14//!
15//! §7.14.1.1: "This number SHALL be monotonically increasing for the life of the node. **This
16//! monotonicity guarantee SHALL be preserved across restarts.**" A client uses it to tell
17//! "nothing happened" from "I missed something", and an `EventFilter` uses it to resume.
18//!
19//! Preserving it across a restart without writing to flash on every event is §7.14.1.1's own
20//! recipe: reserve a block of numbers at start-up, hand them out from RAM, and reserve the
21//! next block just before running out. [`EventNumbers`] is that, and the cost is stated
22//! plainly — "When a node restarts, the event number MAY increase by a larger step than 1."
23//!
24//! # Priority decides what survives
25//!
26//! §7.14.2: "Event records SHALL be buffered on the Node, with priority given to events of a
27//! higher priority level over a lower priority level. Within a priority level, newer event
28//! records SHALL overwrite older event records."
29//!
30//! So the buffers are per priority and each is a ring: a flood of `Debug` records can never
31//! push out a `Critical` one, which is what makes the safety guarantee hold under load. The
32//! second sentence is the one that decides the data structure — **newer overwrites older**, so
33//! a full buffer drops its oldest record rather than refusing the new one.
34
35use heapless::Vec;
36
37use crate::dm::meta::EventPriority;
38use crate::im::{ClusterId, EndpointId, EventId, EventPath};
39use crate::msg::FabricIndex;
40
41/// How far ahead of the last durable value an event number is reserved.
42///
43/// §7.14.1.1's worked strategy: "write counter + N to storage, where N is a carefully chosen
44/// number (e.g. 1000). This number N should be chosen carefully in order not to exhaust the
45/// lifetime 64-bit counter space." A thousand is the specification's own example, and at one
46/// flash write per thousand events a device generating one event a second writes once every
47/// seventeen minutes.
48pub const NUMBER_RESERVATION: u64 = 1000;
49
50/// The node's event-number counter (§7.14.1.1).
51///
52/// Hands out numbers from RAM and tells the caller when to persist the next reservation, so
53/// that monotonicity survives a restart without a flash write per event.
54#[derive(Debug, Clone, Copy, PartialEq, Eq)]
55pub struct EventNumbers {
56    next: u64,
57    reserved_through: u64,
58}
59
60impl Default for EventNumbers {
61    fn default() -> Self {
62        Self::restore(0)
63    }
64}
65
66impl EventNumbers {
67    /// Resumes from the value that was last persisted.
68    ///
69    /// §7.14.1.1's step 1 and 2: "Read the counter value at start-up. Before processing any
70    /// message, write counter + N to storage." So a fresh boot starts at the persisted value
71    /// and immediately owes a write of `persisted + N` — which [`EventNumbers::reservation`]
72    /// reports.
73    #[must_use]
74    pub const fn restore(persisted: u64) -> Self {
75        Self {
76            next: persisted,
77            reserved_through: persisted,
78        }
79    }
80
81    /// The value the node must persist before handing out any more numbers.
82    ///
83    /// `None` when the current reservation still has room. A caller that ignores this breaks
84    /// the monotonicity guarantee *only across a restart* — which is exactly the kind of bug
85    /// that never shows up in testing.
86    #[must_use]
87    pub const fn reservation(&self) -> Option<u64> {
88        if self.next >= self.reserved_through {
89            Some(self.next.saturating_add(NUMBER_RESERVATION))
90        } else {
91            None
92        }
93    }
94
95    /// Records that `value` has been durably stored.
96    pub const fn reserved(&mut self, value: u64) {
97        if value > self.reserved_through {
98            self.reserved_through = value;
99        }
100    }
101
102    /// Takes the next event number.
103    ///
104    /// Returns `None` while a reservation is owed: handing out a number the node has not
105    /// reserved is precisely how a restart rewinds the counter, and a record with a reused
106    /// number tells a client that nothing happened when something did.
107    pub const fn next(&mut self) -> Option<u64> {
108        if self.next >= self.reserved_through {
109            return None;
110        }
111        let number = self.next;
112        self.next = self.next.saturating_add(1);
113        Some(number)
114    }
115
116    /// The number the next event will take.
117    #[must_use]
118    pub const fn peek(&self) -> u64 {
119        self.next
120    }
121}
122
123/// The timestamp an event record carries (§7.14.1.2).
124///
125/// > This timestamp SHALL either be System Time in milliseconds or POSIX Time in
126/// > milliseconds.
127///
128/// Which one a node uses depends on whether it knows the wall-clock time —
129/// [`Clock::utc`](crate::platform::Clock::utc) returning `None` is exactly the case for
130/// `System`. A node must not invent an epoch time it does not have: a client comparing
131/// timestamps across nodes would be comparing an uptime with a date.
132#[derive(Debug, Clone, Copy, PartialEq, Eq)]
133pub enum Timestamp {
134    /// POSIX milliseconds.
135    Epoch(u64),
136    /// Milliseconds since boot.
137    System(u64),
138}
139
140impl Timestamp {
141    /// The value, whichever kind it is.
142    #[must_use]
143    pub const fn millis(self) -> u64 {
144        match self {
145            Self::Epoch(value) | Self::System(value) => value,
146        }
147    }
148
149    /// The absolute `EventDataIB` form (§10.6.9).
150    #[must_use]
151    pub const fn absolute(self) -> crate::im::EventTimestamp {
152        match self {
153            Self::Epoch(value) => crate::im::EventTimestamp::Epoch(value),
154            Self::System(value) => crate::im::EventTimestamp::System(value),
155        }
156    }
157
158    /// The delta form against `previous`, when both are the same kind and `previous` is no
159    /// later (§10.6.9.1, §10.6.9.2).
160    ///
161    /// `None` when they cannot be compared — different kinds, or a timestamp that went
162    /// backwards — in which case the absolute form is the only correct encoding. Encoding a
163    /// delta across a kind change would produce a number with no meaning at all.
164    #[must_use]
165    pub fn delta_from(self, previous: Self) -> Option<crate::im::EventTimestamp> {
166        match (self, previous) {
167            (Self::Epoch(now), Self::Epoch(before)) => Some(crate::im::EventTimestamp::DeltaEpoch(
168                now.checked_sub(before)?,
169            )),
170            (Self::System(now), Self::System(before)) => Some(
171                crate::im::EventTimestamp::DeltaSystem(now.checked_sub(before)?),
172            ),
173            _ => None,
174        }
175    }
176}
177
178/// The longest event payload one record holds.
179///
180/// An event's `Data` is "the cluster-specific payload of the Event" encoded as a TLV
181/// structure. Matter's own events are small — §11.1.6's `StartUp` is one `uint32` — and a
182/// device that needs more is describing something an event is the wrong shape for.
183pub const EVENT_DATA_MAX: usize = 128;
184
185/// One buffered event record (§7.14.1).
186#[derive(Debug, Clone, PartialEq, Eq)]
187pub struct EventRecord {
188    /// `Number` — §7.14.1.1's node-scoped monotonic value.
189    pub number: u64,
190    /// Which endpoint, cluster and event this is.
191    pub endpoint: EndpointId,
192    /// The cluster.
193    pub cluster: ClusterId,
194    /// The event.
195    pub event: EventId,
196    /// `Priority` — "Each generated event record SHALL have an event priority that MAY
197    /// override the defined priority for that event", so it is stored per record rather than
198    /// looked up from the descriptor.
199    pub priority: EventPriority,
200    /// When it happened — "at the time it was created (and not when it is reported to a
201    /// client)".
202    pub timestamp: Timestamp,
203    /// The fabric a fabric-sensitive event belongs to (§7.14.4).
204    ///
205    /// `None` for an event that "SHALL NOT be associated with a fabric", which is most of
206    /// them. The distinction decides who may read the record, so it is part of it.
207    pub fabric_index: Option<FabricIndex>,
208    /// `Data` — the encoded TLV structure, tag included.
209    ///
210    /// §10.6.9.3: an event with no payload is "encoded as a struct with no member elements",
211    /// not an absent field — so this is never empty.
212    pub data: Vec<u8, EVENT_DATA_MAX>,
213}
214
215impl EventRecord {
216    /// The `EventPathIB` this record reports under.
217    #[must_use]
218    pub const fn path(&self) -> EventPath {
219        EventPath::event(self.endpoint, self.cluster, self.event)
220    }
221
222    /// Whether `path` — possibly a wildcard — names this record.
223    ///
224    /// §10.6.8: "Omission of the Endpoint, Cluster and Event tags SHALL have different
225    /// interpretations depending on where the EventPathIB is used"; in a request they are
226    /// wildcards. `IsUrgent` is not part of the match: it says how to *deliver*, not what.
227    #[must_use]
228    pub fn matches(&self, path: &EventPath) -> bool {
229        path.endpoint.is_none_or(|wanted| wanted == self.endpoint)
230            && path.cluster.is_none_or(|wanted| wanted == self.cluster)
231            && path.event.is_none_or(|wanted| wanted == self.event)
232    }
233
234    /// Whether a subject on `accessing` may read this record (§7.14.4).
235    ///
236    /// > A read interaction SHALL NOT filter event records, based on fabric, for event records
237    /// > that are not associated with a fabric.
238    /// >
239    /// > A read interaction SHALL NOT report fabric-sensitive event records that are
240    /// > associated with a fabric different than the accessing fabric.
241    ///
242    /// Two sentences that pull in opposite directions, and both matter: an unassociated record
243    /// is visible to everyone, and an associated one only to its own fabric. Treating the
244    /// first like the second would hide a node's `StartUp` from every client.
245    #[must_use]
246    pub fn visible_to(&self, accessing: Option<FabricIndex>) -> bool {
247        match self.fabric_index {
248            None => true,
249            Some(fabric) => accessing == Some(fabric),
250        }
251    }
252}
253
254/// A ring of records at one priority level.
255///
256/// §7.14.2: "Within a priority level, newer event records SHALL overwrite older event
257/// records." So when it is full the *oldest* goes — a full buffer never refuses a new record,
258/// because refusing would lose the edge that events exist to preserve.
259#[derive(Debug)]
260pub struct PriorityBuffer<const N: usize> {
261    records: Vec<EventRecord, N>,
262    /// How many records have been dropped to make room, so a caller can tell a client that
263    /// its view has a hole in it.
264    dropped: u64,
265}
266
267impl<const N: usize> Default for PriorityBuffer<N> {
268    fn default() -> Self {
269        Self::new()
270    }
271}
272
273impl<const N: usize> PriorityBuffer<N> {
274    /// An empty buffer.
275    #[must_use]
276    pub const fn new() -> Self {
277        Self {
278            records: Vec::new(),
279            dropped: 0,
280        }
281    }
282
283    /// Appends a record, dropping the oldest if there is no room.
284    pub fn push(&mut self, record: EventRecord) {
285        if self.records.len() >= N {
286            if self.records.is_empty() {
287                // `N == 0`: the buffer cannot hold anything, and the record is dropped whole
288                // rather than half-stored.
289                self.dropped = self.dropped.saturating_add(1);
290                return;
291            }
292            self.records.remove(0);
293            self.dropped = self.dropped.saturating_add(1);
294        }
295        // Cannot fail: room was just made.
296        let _ = self.records.push(record);
297    }
298
299    /// The records, oldest first — which is the order §8.5 requires them reported in:
300    /// "Each Report containing events SHALL deliver queued events without reordering the
301    /// queue."
302    #[must_use]
303    pub fn records(&self) -> &[EventRecord] {
304        &self.records
305    }
306
307    /// How many records have been lost to make room.
308    #[must_use]
309    pub const fn dropped(&self) -> u64 {
310        self.dropped
311    }
312
313    /// How many are held.
314    #[must_use]
315    pub fn len(&self) -> usize {
316        self.records.len()
317    }
318
319    /// Whether none are.
320    #[must_use]
321    pub fn is_empty(&self) -> bool {
322        self.records.is_empty()
323    }
324
325    /// Forgets every record with a number below `number` — what a client's acknowledged
326    /// progress allows.
327    pub fn prune_below(&mut self, number: u64) {
328        self.records.retain(|record| record.number >= number);
329    }
330}
331
332/// The node's event store: one ring per priority (§7.14.2).
333///
334/// > Event records SHALL be buffered on the Node, with priority given to events of a higher
335/// > priority level over a lower priority level.
336///
337/// Separate buffers rather than one shared ring with a priority field, because that sentence
338/// is a *guarantee*: a flood of `Debug` records must not be able to push out a `Critical` one,
339/// and in a shared ring it always can. The sizes are the caller's, so a device that logs
340/// heavily at `Debug` pays for it only there.
341#[derive(Debug)]
342pub struct EventStore<const C: usize, const I: usize, const D: usize> {
343    critical: PriorityBuffer<C>,
344    info: PriorityBuffer<I>,
345    debug: PriorityBuffer<D>,
346    numbers: EventNumbers,
347}
348
349impl<const C: usize, const I: usize, const D: usize> Default for EventStore<C, I, D> {
350    fn default() -> Self {
351        Self::new(EventNumbers::default())
352    }
353}
354
355/// Why an event could not be recorded.
356#[derive(Debug, Clone, Copy, PartialEq, Eq)]
357pub enum RecordError {
358    /// The event-number counter needs a durable reservation first (§7.14.1.1).
359    ///
360    /// The caller must persist [`EventNumbers::reservation`] and call
361    /// [`EventStore::reserved`], then try again. Handing out an unreserved number would let a
362    /// restart rewind the counter — and a record with a reused number tells a client that
363    /// nothing happened when something did.
364    NeedsReservation(u64),
365    /// The payload is longer than [`EVENT_DATA_MAX`].
366    DataTooLong,
367}
368
369impl<const C: usize, const I: usize, const D: usize> EventStore<C, I, D> {
370    /// An empty store resuming from a counter.
371    #[must_use]
372    pub const fn new(numbers: EventNumbers) -> Self {
373        Self {
374            critical: PriorityBuffer::new(),
375            info: PriorityBuffer::new(),
376            debug: PriorityBuffer::new(),
377            numbers,
378        }
379    }
380
381    /// The event-number counter.
382    #[must_use]
383    pub const fn numbers(&self) -> EventNumbers {
384        self.numbers
385    }
386
387    /// Records that a reservation has been durably stored (§7.14.1.1 step 2).
388    pub const fn reserved(&mut self, value: u64) {
389        self.numbers.reserved(value);
390    }
391
392    /// Records an event, assigning it the next number.
393    pub fn record(&mut self, event: &NewEvent<'_>) -> Result<u64, RecordError> {
394        let NewEvent {
395            endpoint,
396            cluster,
397            event: event_id,
398            priority,
399            timestamp,
400            fabric_index,
401            data,
402        } = *event;
403        let stored = Vec::from_slice(data).map_err(|_| RecordError::DataTooLong)?;
404        let Some(number) = self.numbers.next() else {
405            let owed = self
406                .numbers
407                .reservation()
408                .unwrap_or(self.numbers.peek().saturating_add(NUMBER_RESERVATION));
409            return Err(RecordError::NeedsReservation(owed));
410        };
411        let record = EventRecord {
412            number,
413            endpoint,
414            cluster,
415            event: event_id,
416            priority,
417            timestamp,
418            fabric_index,
419            data: stored,
420        };
421        match priority {
422            EventPriority::Critical => self.critical.push(record),
423            EventPriority::Info => self.info.push(record),
424            EventPriority::Debug => self.debug.push(record),
425        }
426        Ok(number)
427    }
428
429    /// The buffer for one priority.
430    #[must_use]
431    pub const fn buffer(&self, priority: EventPriority) -> &dyn BufferView {
432        match priority {
433            EventPriority::Critical => &self.critical,
434            EventPriority::Info => &self.info,
435            EventPriority::Debug => &self.debug,
436        }
437    }
438
439    /// Every buffered record matching `path`, visible to `accessing`, with a number at or
440    /// above `min_number`, **in event-number order**.
441    ///
442    /// §8.5: "Each Report containing events SHALL deliver queued events without reordering the
443    /// queue." Across priorities that means by number, because the number is the order things
444    /// happened in — reporting all the `Critical` records before all the `Info` ones would
445    /// hand a client a log that contradicts itself.
446    pub fn matching<'a>(
447        &'a self,
448        path: &'a EventPath,
449        accessing: Option<FabricIndex>,
450        min_number: u64,
451    ) -> impl Iterator<Item = &'a EventRecord> {
452        let mut all: Vec<&'a EventRecord, 64> = Vec::new();
453        for record in self
454            .critical
455            .records()
456            .iter()
457            .chain(self.info.records())
458            .chain(self.debug.records())
459        {
460            if record.number >= min_number
461                && record.matches(path)
462                && record.visible_to(accessing)
463                && all.push(record).is_err()
464            {
465                break;
466            }
467        }
468        all.sort_unstable_by_key(|record| record.number);
469        all.into_iter()
470    }
471
472    /// How many records are held, across every priority.
473    #[must_use]
474    pub fn len(&self) -> usize {
475        self.critical
476            .len()
477            .saturating_add(self.info.len())
478            .saturating_add(self.debug.len())
479    }
480
481    /// Whether none are.
482    #[must_use]
483    pub fn is_empty(&self) -> bool {
484        self.len() == 0
485    }
486
487    /// Forgets every record below `number`, across every priority.
488    pub fn prune_below(&mut self, number: u64) {
489        self.critical.prune_below(number);
490        self.info.prune_below(number);
491        self.debug.prune_below(number);
492    }
493}
494
495/// An event about to be recorded.
496///
497/// A struct rather than seven parameters because the seven travel together — they come from
498/// one thing happening — and because the three identifiers are all integers, which at a call
499/// site is how an endpoint ends up where a cluster belongs.
500#[derive(Debug, Clone, Copy)]
501pub struct NewEvent<'a> {
502    /// Which endpoint it happened on.
503    pub endpoint: EndpointId,
504    /// Which cluster.
505    pub cluster: ClusterId,
506    /// Which event.
507    pub event: EventId,
508    /// Its priority. "Each generated event record SHALL have an event priority that MAY
509    /// override the defined priority for that event" — so it is given here, not looked up.
510    pub priority: EventPriority,
511    /// When it happened — "at the time it was created (and not when it is reported to a
512    /// client)".
513    pub timestamp: Timestamp,
514    /// The fabric, for a fabric-sensitive event (§7.14.4); `None` otherwise.
515    pub fabric_index: Option<FabricIndex>,
516    /// The encoded TLV structure under context tag 7 — §10.6.9.3's "struct with no member
517    /// elements" for an event that carries no payload.
518    pub data: &'a [u8],
519}
520
521/// What a caller may ask of a priority buffer without knowing its size.
522pub trait BufferView {
523    /// The records, oldest first.
524    fn records(&self) -> &[EventRecord];
525    /// How many have been dropped to make room.
526    fn dropped(&self) -> u64;
527}
528
529impl<const N: usize> BufferView for PriorityBuffer<N> {
530    fn records(&self) -> &[EventRecord] {
531        self.records()
532    }
533
534    fn dropped(&self) -> u64 {
535        self.dropped()
536    }
537}
538
539/// The node's event log, as §8.4.3.3's report writer needs to see it.
540///
541/// A trait rather than a concrete store for the same reason
542/// [`AccessControl`](crate::im::AccessControl) and [`ClusterHandler`](crate::im::ClusterHandler)
543/// are: [`EventStore`] is generic over three buffer sizes, and threading those through
544/// [`Server`](crate::im::Server) would put a device's capacity choices into the type of every
545/// read. The server needs one question answered — "which records match this path, for this
546/// subject, from this number on" — and that is the whole trait.
547///
548/// The callback returns whether to continue, because a report stops when the message is full
549/// and resumes in the next one: §10.2.3's chunking applies to events exactly as it does to
550/// attributes.
551pub trait EventSource: core::fmt::Debug {
552    /// Every queued record matching `path`, visible to `accessing`, whose number is at least
553    /// `min_number` — **in event-number order**, which §8.5 requires: "Each Report containing
554    /// events SHALL deliver queued events without reordering the queue."
555    ///
556    /// Stops early when `each` returns `false`.
557    fn each_matching(
558        &self,
559        path: &EventPath,
560        accessing: Option<FabricIndex>,
561        min_number: u64,
562        each: &mut dyn FnMut(&EventRecord) -> bool,
563    );
564
565    /// The highest event number the node has assigned, or `None` when it has recorded nothing.
566    ///
567    /// §8.5.3.4: "Subsequent ReportData actions … SHALL include the latest EventNo associated
568    /// with each node generating new events" — a subscription's bookmark moves to this even
569    /// when nothing it asked for happened, so that a later report does not re-walk the whole
570    /// log to discover that again.
571    fn highest_number(&self) -> Option<u64>;
572}
573
574impl<const C: usize, const I: usize, const D: usize> EventSource for EventStore<C, I, D> {
575    fn each_matching(
576        &self,
577        path: &EventPath,
578        accessing: Option<FabricIndex>,
579        min_number: u64,
580        each: &mut dyn FnMut(&EventRecord) -> bool,
581    ) {
582        for record in self.matching(path, accessing, min_number) {
583            if !each(record) {
584                return;
585            }
586        }
587    }
588
589    fn highest_number(&self) -> Option<u64> {
590        self.critical
591            .records()
592            .iter()
593            .chain(self.info.records())
594            .chain(self.debug.records())
595            .map(|record| record.number)
596            .max()
597    }
598}
599
600/// A store a device keeps behind a [`RefCell`](core::cell::RefCell) is still an event source.
601///
602/// Recording needs `&mut`, reporting needs `&`, and both happen on one device between two
603/// messages — so the store lives in a `RefCell` exactly as `DataVersions` does. Without this
604/// impl a device would have to choose between recording events and serving them.
605///
606/// The borrow is taken for the duration of one walk. That is safe because the callback belongs
607/// to the report writer, which does not record: a cluster that tried to log an event *while*
608/// the log was being read would be re-entering its own store, and the panic that produces is a
609/// better answer than the half-written report.
610impl<T: EventSource> EventSource for core::cell::RefCell<T> {
611    fn each_matching(
612        &self,
613        path: &EventPath,
614        accessing: Option<FabricIndex>,
615        min_number: u64,
616        each: &mut dyn FnMut(&EventRecord) -> bool,
617    ) {
618        self.borrow()
619            .each_matching(path, accessing, min_number, each);
620    }
621
622    fn highest_number(&self) -> Option<u64> {
623        self.borrow().highest_number()
624    }
625}