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}