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>>;