vstorage 0.9.0

Common API for various icalendar/vcard storages.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

// Copyright 2024-2026 Hugo Osvaldo Barrera
//
// SPDX-License-Identifier: EUPL-1.2

//! Monitor a storage for changes as they occur.
use futures_util::future::BoxFuture;

use crate::Href;

/// Monitors a storage for live events.
///
/// Implementations shall yield [`Event::General`] whenever changes have happened, but the
/// underlying interfaces don't provide enough information to determine which items changed.
/// This includes (but is not limited to) disconnection or buffer full.
///
/// Monitors MUST yield events for changes that have occurred since the last access to this
/// storage. If this is unknown (e.g.: no state is preserved between executions), an
/// [`Event::General`] must be emitted immediately upon the first call to
/// [`StorageMonitor::next_event`].
///
/// # See also
///
/// - [[`Storage::monitor`][crate::base::Storage::monitor]
pub trait StorageMonitor: Send {
    /// Return the next event on this storage.
    ///
    /// Returns a future which resolves the next change event, or `None` when monitoring cannot
    /// continue. Transient errors are resolved internally, so `None` generally implies a fatal
    /// error condition.
    ///
    /// # Cancel safety
    ///
    /// Implementations MUST be cancel safe. If the returned future is dropped before completion, the
    /// next call MUST return the following event without dropping any events.
    fn next_event(&mut self) -> BoxFuture<'_, Option<Event>>;
}

/// Event yielded when monitoring a storage.
///
/// Returned by [`StorageMonitor::next_event`]
#[derive(Debug, PartialEq)]
pub enum Event {
    /// No details are known; only that something has changed.
    ///
    /// Indicates that something has changed, but there is insufficient information to determine
    /// what changed. The entire storage should be re-scanned to manually find changes.
    General,
    /// Details of exactly what changed are known.
    Specific(SpecificEvent),
}

/// Specific event on a given resource or collection.
///
/// See also: [`Event`].
#[derive(Debug, PartialEq)]
pub struct SpecificEvent {
    /// The location of the resource.
    pub href: Href,
    /// The type of event that occurred on the resource.
    pub kind: EventKind,
}

/// Kind of event.
///
/// See: [`SpecificEvent`].
#[derive(Debug, PartialEq)]
pub enum EventKind {
    /// A new element was created or an existing one was modified.
    Change,
    /// A previously seen element has been deleted.
    Delete,
    // /// A property has changed.
    // Property { name: String },
    // Unknown,
}