Skip to main content

rustfs_notify/rules/
subscriber_snapshot.rs

1// Copyright 2024 RustFS Team
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15use rustfs_s3_types::EventName;
16use std::sync::Arc;
17
18/// Let the rules structure provide "what events it is subscribed to".
19/// This way BucketRulesSnapshot does not need to know the internal shape of rules.
20pub trait RuleEvents {
21    fn subscribed_events(&self) -> &[EventName];
22}
23
24/// Let the rules container provide the ability to iterate over all rules (abstracting only to the minimum necessary).
25pub trait RulesContainer {
26    type Rule: RuleEvents + ?Sized;
27    fn iter_rules<'a>(&'a self) -> Box<dyn Iterator<Item = &'a Self::Rule> + 'a>;
28
29    /// Fast empty judgment for snapshots (fix missing `rules.is_empty()`)
30    fn is_empty(&self) -> bool {
31        self.iter_rules().next().is_none()
32    }
33}
34
35/// Represents a bucket's notification subscription view snapshot (immutable).
36///
37/// - `event_mask`: Quickly determine whether there is a subscription to a certain type of event (bitset/flags).
38/// - `rules`: precise rule mapping (prefix/suffix/pattern -> targets).
39///
40/// The read path only reads this snapshot to ensure consistency.
41#[derive(Debug, Clone)]
42pub struct BucketRulesSnapshot<R>
43where
44    R: RulesContainer + ?Sized,
45{
46    pub event_mask: u64,
47    pub rules: Arc<R>,
48}
49
50impl<R> BucketRulesSnapshot<R>
51where
52    R: RulesContainer + ?Sized,
53{
54    /// Create an empty snapshot with no subscribed events and no rules.
55    ///
56    /// # Arguments
57    /// * `rules` - An Arc to a rules container (can be an empty container).
58    ///
59    /// # Returns
60    /// An instance of `BucketRulesSnapshot` with an empty event mask.
61    #[inline]
62    pub fn empty(rules: Arc<R>) -> Self {
63        Self { event_mask: 0, rules }
64    }
65
66    /// Check if the snapshot has any subscribers for the specified event.
67    ///
68    /// # Arguments
69    /// * `event` - The event name to check for subscriptions.
70    ///
71    /// # Returns
72    /// `true` if there are subscribers for the event, `false` otherwise.
73    #[inline]
74    pub fn has_event(&self, event: &EventName) -> bool {
75        (self.event_mask & event.mask()) != 0
76    }
77
78    /// Check if the snapshot is empty (no subscribed events or rules).
79    ///
80    /// # Returns
81    /// `true` if the snapshot is empty, `false` otherwise.
82    #[inline]
83    pub fn is_empty(&self) -> bool {
84        self.event_mask == 0 || self.rules.is_empty()
85    }
86
87    /// [debug] Assert that `event_mask` is consistent with the event declared in `rules`.
88    ///
89    /// Constraints:
90    /// - only runs in debug builds (release incurs no cost).
91    /// - If the rule contains compound events (\*All / Everything), rely on `EventName::mask()` to automatically expand.
92    #[inline]
93    pub fn debug_assert_mask_consistent(&self) {
94        #[cfg(debug_assertions)]
95        {
96            let mut recomputed = 0u64;
97            for rule in self.rules.iter_rules() {
98                for ev in rule.subscribed_events() {
99                    recomputed |= ev.mask();
100                }
101            }
102
103            debug_assert!(
104                recomputed == self.event_mask,
105                "BucketRulesSnapshot.event_mask inconsistent: stored={:#x}, recomputed={:#x}",
106                self.event_mask,
107                recomputed
108            );
109        }
110    }
111}
112
113/// Unify trait-object snapshot types (fix Sized / missing generic arguments)
114pub type DynRulesContainer = dyn RulesContainer<Rule = dyn RuleEvents> + Send + Sync;
115
116/// Expose Arc form to facilitate sharing.
117pub type BucketSnapshotRef = Arc<BucketRulesSnapshot<DynRulesContainer>>;