Fix notification event stream cleanup, add bounded send concurrency, and reduce overhead (#1224)

crates/notify/src/rules/config.rs

@@ -15,13 +15,60 @@
 use super::rules_map::RulesMap;
 use super::xml_config::ParseConfigError as BucketNotificationConfigError;
 use crate::rules::NotificationConfiguration;
-use crate::rules::pattern_rules;
-use crate::rules::target_id_set;
-use hashbrown::HashMap;
+use crate::rules::subscriber_snapshot::{BucketRulesSnapshot, DynRulesContainer, RuleEvents, RulesContainer};
 use rustfs_targets::EventName;
 use rustfs_targets::arn::TargetID;
 use serde::{Deserialize, Serialize};
 use std::io::Read;
+use std::sync::Arc;
+
+/// A "rule view", only used for snapshot mask/consistency verification.
+/// Here we choose to generate the view by "single event" to ensure that event_mask calculation is reliable and simple.
+#[derive(Debug)]
+struct RuleView {
+    events: Vec<EventName>,
+}
+
+impl RuleEvents for RuleView {
+    fn subscribed_events(&self) -> &[EventName] {
+        &self.events
+    }
+}
+
+/// Adapt RulesMap to RulesContainer.
+/// Key point: The items returned by iter_rules are &dyn RuleEvents, so a RuleView list is cached in the container.
+#[derive(Debug)]
+struct CompiledRules {
+    // Keep RulesMap (can be used later if you want to make more complex judgments during the snapshot reading phase)
+    #[allow(dead_code)]
+    rules_map: RulesMap,
+    // for RulesContainer::iter_rules
+    rule_views: Vec<RuleView>,
+}
+
+impl CompiledRules {
+    fn from_rules_map(rules_map: &RulesMap) -> Self {
+        let mut rule_views = Vec::new();
+
+        for ev in rules_map.iter_events() {
+            rule_views.push(RuleView { events: vec![ev] });
+        }
+
+        Self {
+            rules_map: rules_map.clone(),
+            rule_views,
+        }
+    }
+}
+
+impl RulesContainer for CompiledRules {
+    type Rule = dyn RuleEvents;
+
+    fn iter_rules<'a>(&'a self) -> Box<dyn Iterator<Item = &'a Self::Rule> + 'a> {
+        // Key: Convert &RuleView into &dyn RuleEvents
+        Box::new(self.rule_views.iter().map(|v| v as &dyn RuleEvents))
+    }
+}
 
 /// Configuration for bucket notifications.
 /// This struct now holds the parsed and validated rules in the new RulesMap format.
@@ -119,11 +166,26 @@ impl BucketNotificationConfig {
     pub fn set_region(&mut self, region: &str) {
         self.region = region.to_string();
     }
-}
 
-// Add a helper to PatternRules if not already present
-impl pattern_rules::PatternRules {
-    pub fn inner(&self) -> &HashMap<String, target_id_set::TargetIdSet> {
-        &self.rules
+    /// Compiles the current BucketNotificationConfig into a BucketRulesSnapshot.
+    /// This involves transforming the rules into a format suitable for runtime use,
+    /// and calculating the event mask based on the subscribed events of the rules.
+    ///
+    /// # Returns
+    /// A BucketRulesSnapshot containing the compiled rules and event mask.
+    pub fn compile_snapshot(&self) -> BucketRulesSnapshot<DynRulesContainer> {
+        // 1) Generate container from RulesMap
+        let compiled = CompiledRules::from_rules_map(self.get_rules_map());
+        let rules: Arc<DynRulesContainer> = Arc::new(compiled) as Arc<DynRulesContainer>;
+
+        // 2) Calculate event_mask
+        let mut mask = 0u64;
+        for rule in rules.iter_rules() {
+            for ev in rule.subscribed_events() {
+                mask |= ev.mask();
+            }
+        }
+
+        BucketRulesSnapshot { event_mask: mask, rules }
     }
 }

crates/notify/src/rules/mod.rs

@@ -12,22 +12,24 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+mod config;
 pub mod pattern;
-pub mod pattern_rules;
-pub mod rules_map;
-pub mod target_id_set;
+mod pattern_rules;
+mod rules_map;
+mod subscriber_index;
+mod subscriber_snapshot;
+mod target_id_set;
 pub mod xml_config; // For XML structure definition and parsing
-
-pub mod config; // Definition and parsing for BucketNotificationConfig
+// Definition and parsing for BucketNotificationConfig
 
 // Re-export key types from submodules for easy access to `crate::rules::TypeName`
 // Re-export key types from submodules for external use
 pub use config::BucketNotificationConfig;
 // Assume that BucketNotificationConfigError is also defined in config.rs
 // Or if it is still an alias for xml_config::ParseConfigError , adjust accordingly
-pub use xml_config::ParseConfigError as BucketNotificationConfigError;
-
 pub use pattern_rules::PatternRules;
 pub use rules_map::RulesMap;
+pub use subscriber_index::*;
+pub use subscriber_snapshot::*;
 pub use target_id_set::TargetIdSet;
-pub use xml_config::{NotificationConfiguration, ParseConfigError};
+pub use xml_config::{NotificationConfiguration, ParseConfigError, ParseConfigError as BucketNotificationConfigError};

crates/notify/src/rules/pattern_rules.rs

@@ -12,8 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use super::pattern;
-use super::target_id_set::TargetIdSet;
+use crate::rules::TargetIdSet;
+use crate::rules::pattern;
 use hashbrown::HashMap;
 use rayon::prelude::*;
 use rustfs_targets::arn::TargetID;
@@ -27,31 +27,69 @@ pub struct PatternRules {
 }
 
 impl PatternRules {
+    /// Create a new, empty PatternRules.
     pub fn new() -> Self {
         Default::default()
     }
 
     /// Add rules: Pattern and Target ID.
     /// If the schema already exists, add target_id to the existing TargetIdSet.
+    ///
+    /// # Arguments
+    /// * `pattern` - The object name pattern.
+    /// * `target_id` - The TargetID to associate with the pattern.
     pub fn add(&mut self, pattern: String, target_id: TargetID) {
         self.rules.entry(pattern).or_default().insert(target_id);
     }
 
     /// Checks if there are any rules that match the given object name.
+    ///
+    /// # Arguments
+    /// * `object_name` - The object name to match against the patterns.
+    ///
+    /// # Returns
+    /// `true` if any pattern matches the object name, otherwise `false`.
     pub fn match_simple(&self, object_name: &str) -> bool {
         self.rules.keys().any(|p| pattern::match_simple(p, object_name))
     }
 
     /// Returns all TargetIDs that match the object name.
+    ///
+    /// Performance optimization points:
+    /// 1) Small collections are serialized directly to avoid rayon scheduling/merging overhead
+    /// 2) When hitting, no longer temporarily allocate TargetIdSet for each rule, but directly extend
+    ///
+    /// # Arguments
+    /// * `object_name` - The object name to match against the patterns.
+    ///
+    /// # Returns
+    /// A TargetIdSet containing all TargetIDs that match the object name.
     pub fn match_targets(&self, object_name: &str) -> TargetIdSet {
+        let n = self.rules.len();
+        if n == 0 {
+            return TargetIdSet::new();
+        }
+
+        // Experience Threshold: Serial is usually faster below this value (can be adjusted after benchmarking)
+        const PAR_THRESHOLD: usize = 128;
+
+        if n < PAR_THRESHOLD {
+            let mut out = TargetIdSet::new();
+            for (pattern_str, target_set) in self.rules.iter() {
+                if pattern::match_simple(pattern_str, object_name) {
+                    out.extend(target_set.iter().cloned());
+                }
+            }
+            return out;
+        }
+        // Parallel path: Each thread accumulates a local set and finally merges it to reduce frequent allocations
         self.rules
             .par_iter()
-            .filter_map(|(pattern_str, target_set)| {
+            .fold(TargetIdSet::new, |mut local, (pattern_str, target_set)| {
                 if pattern::match_simple(pattern_str, object_name) {
-                    Some(target_set.iter().cloned().collect::<TargetIdSet>())
-                } else {
-                    None
+                    local.extend(target_set.iter().cloned());
                 }
+                local
             })
             .reduce(TargetIdSet::new, |mut acc, set| {
                 acc.extend(set);
@@ -65,6 +103,11 @@ impl PatternRules {
 
     /// Merge another PatternRules.
     /// Corresponding to Go's `Rules.Union`.
+    /// # Arguments
+    /// * `other` - The PatternRules to merge with.
+    ///
+    /// # Returns
+    /// A new PatternRules containing the union of both.
     pub fn union(&self, other: &Self) -> Self {
         let mut new_rules = self.clone();
         for (pattern, their_targets) in &other.rules {
@@ -76,6 +119,13 @@ impl PatternRules {
 
     /// Calculate the difference from another PatternRules.
     /// Corresponding to Go's `Rules.Difference`.
+    /// The result contains only the patterns and TargetIDs that are in `self` but not in `other`.
+    ///
+    /// # Arguments
+    /// * `other` - The PatternRules to compare against.
+    ///
+    /// # Returns
+    /// A new PatternRules containing the difference.
     pub fn difference(&self, other: &Self) -> Self {
         let mut result_rules = HashMap::new();
         for (pattern, self_targets) in &self.rules {
@@ -94,4 +144,59 @@ impl PatternRules {
         }
         PatternRules { rules: result_rules }
     }
+
+    /// Merge another PatternRules into self in place.
+    /// Corresponding to Go's `Rules.UnionInPlace`.
+    /// # Arguments
+    /// * `other` - The PatternRules to merge with.
+    pub fn union_in_place(&mut self, other: &Self) {
+        for (pattern, their_targets) in &other.rules {
+            self.rules
+                .entry(pattern.clone())
+                .or_default()
+                .extend(their_targets.iter().cloned());
+        }
+    }
+
+    /// Calculate the difference from another PatternRules in place.
+    /// Corresponding to Go's `Rules.DifferenceInPlace`.
+    /// The result contains only the patterns and TargetIDs that are in `self` but not in `other`.
+    /// # Arguments
+    /// * `other` - The PatternRules to compare against.
+    pub fn difference_in_place(&mut self, other: &Self) {
+        self.rules.retain(|pattern, self_targets| {
+            if let Some(other_targets) = other.rules.get(pattern) {
+                // Remove other_targets from self_targets
+                self_targets.retain(|tid| !other_targets.contains(tid));
+            }
+            !self_targets.is_empty()
+        });
+    }
+
+    /// Remove a pattern and its associated TargetID set from the PatternRules.
+    ///
+    /// # Arguments
+    /// * `pattern` - The pattern to remove.
+    pub fn remove_pattern(&mut self, pattern: &str) -> bool {
+        self.rules.remove(pattern).is_some()
+    }
+
+    /// Determine whether the current PatternRules contains the specified TargetID (referenced by any pattern).
+    ///
+    /// # Parameters
+    /// * `target_id` - The TargetID to check for existence within the PatternRules
+    ///
+    /// # Returns
+    /// * `true` if the TargetID exists in any of the patterns; `false` otherwise.
+    pub fn contains_target_id(&self, target_id: &TargetID) -> bool {
+        self.rules.values().any(|set| set.contains(target_id))
+    }
+
+    /// Expose the internal rules for use in scenarios such as BucketNotificationConfig::validate.
+    ///
+    /// # Returns
+    /// A reference to the internal HashMap of patterns to TargetIdSets.
+    pub fn inner(&self) -> &HashMap<String, TargetIdSet> {
+        &self.rules
+    }
 }

crates/notify/src/rules/rules_map.rs

@@ -12,8 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use super::pattern_rules::PatternRules;
-use super::target_id_set::TargetIdSet;
+use crate::rules::{PatternRules, TargetIdSet};
 use hashbrown::HashMap;
 use rustfs_targets::EventName;
 use rustfs_targets::arn::TargetID;
@@ -31,6 +30,9 @@ pub struct RulesMap {
 
 impl RulesMap {
     /// Create a new, empty RulesMap.
+    ///
+    /// # Returns
+    /// A new instance of RulesMap with an empty map and a total_events_mask set to 0.
     pub fn new() -> Self {
         Default::default()
     }
@@ -67,12 +69,12 @@ impl RulesMap {
 
     /// Merge another RulesMap.
     /// `RulesMap.Add(rulesMap2 RulesMap) corresponding to Go
+    ///
+    /// # Parameters
+    /// * `other_map` - The other RulesMap to be merged into the current one.
     pub fn add_map(&mut self, other_map: &Self) {
         for (event_name, other_pattern_rules) in &other_map.map {
-            let self_pattern_rules = self.map.entry(*event_name).or_default();
-            // PatternRules::union Returns the new PatternRules, we need to modify the existing ones
-            let merged_rules = self_pattern_rules.union(other_pattern_rules);
-            *self_pattern_rules = merged_rules;
+            self.map.entry(*event_name).or_default().union_in_place(other_pattern_rules);
         }
         // Directly merge two masks.
         self.total_events_mask |= other_map.total_events_mask;
@@ -81,11 +83,14 @@ impl RulesMap {
     /// Remove another rule defined in the RulesMap from the current RulesMap.
     ///
     /// After the rule is removed, `total_events_mask` is recalculated to ensure its accuracy.
+    ///
+    /// # Parameters
+    /// * `other_map` - The other RulesMap containing rules to be removed from the current one.
     pub fn remove_map(&mut self, other_map: &Self) {
         let mut events_to_remove = Vec::new();
         for (event_name, self_pattern_rules) in &mut self.map {
             if let Some(other_pattern_rules) = other_map.map.get(event_name) {
-                *self_pattern_rules = self_pattern_rules.difference(other_pattern_rules);
+                self_pattern_rules.difference_in_place(other_pattern_rules);
                 if self_pattern_rules.is_empty() {
                     events_to_remove.push(*event_name);
                 }
@@ -102,6 +107,9 @@ impl RulesMap {
     ///
     /// This method uses a bitmask for a quick check of O(1) complexity.
     /// `event_name` can be a compound type, such as `ObjectCreatedAll`.
+    ///
+    /// # Parameters
+    /// * `event_name` - The event name to check for subscribers.
     pub fn has_subscriber(&self, event_name: &EventName) -> bool {
         // event_name.mask() will handle compound events correctly
         (self.total_events_mask & event_name.mask()) != 0
@@ -112,39 +120,54 @@ impl RulesMap {
     /// # Notice
     /// The `event_name` parameter should be a specific, non-compound event type.
     /// Because this is taken from the `Event` object that actually occurs.
+    ///
+    /// # Parameters
+    /// * `event_name` - The specific event name to match against.
+    /// * `object_key` - The object key to match against the patterns in the rules.
+    ///
+    /// # Returns
+    /// * A set of TargetIDs that match the given event and object key.
     pub fn match_rules(&self, event_name: EventName, object_key: &str) -> TargetIdSet {
         // Use bitmask to quickly determine whether there is a matching rule
         if (self.total_events_mask & event_name.mask()) == 0 {
             return TargetIdSet::new(); // No matching rules
         }
 
-        // First try to directly match the event name
-        if let Some(pattern_rules) = self.map.get(&event_name) {
-            let targets = pattern_rules.match_targets(object_key);
-            if !targets.is_empty() {
-                return targets;
-            }
-        }
-        // Go's RulesMap[eventName] is directly retrieved, and if it does not exist, it is empty Rules.
-        // Rust's HashMap::get returns Option. If the event name does not exist, there is no rule.
-        // Compound events (such as ObjectCreatedAll) have been expanded as a single event when add_rule_config.
-        // Therefore, a single event name should be used when querying.
-        // If event_name itself is a single type, look it up directly.
-        // If event_name is a compound type, Go's logic is expanded when added.
-        // Here match_rules should receive events that may already be single.
-        // If the caller passes in a compound event, it should expand itself or handle this function first.
-        // Assume that event_name is already a specific event that can be used for searching.
+        // In Go, RulesMap[eventName] returns empty rules if the key doesn't exist.
+        // Rust's HashMap::get returns Option, so missing key means no rules.
+        // Compound events like ObjectCreatedAll are expanded into specific events during add_rule_config.
+        // Thus, queries should use specific event names.
+        // If event_name is compound, expansion happens at addition time.
+        // match_rules assumes event_name is already a specific event for lookup.
+        // Callers should expand compound events before calling this method.
         self.map
             .get(&event_name)
             .map_or_else(TargetIdSet::new, |pr| pr.match_targets(object_key))
     }
 
     /// Check if RulesMap is empty.
+    ///
+    /// # Returns
+    /// * `true` if there are no rules in the map; `false` otherwise
     pub fn is_empty(&self) -> bool {
         self.map.is_empty()
     }
 
+    /// Determine whether the current RulesMap contains the specified TargetID (referenced by any event / pattern).
+    ///
+    /// # Parameters
+    /// * `target_id` - The TargetID to check for existence within the RulesMap
+    ///
+    /// # Returns
+    /// * `true` if the TargetID exists in any of the PatternRules; `false` otherwise.
+    pub fn contains_target_id(&self, target_id: &TargetID) -> bool {
+        self.map.values().any(|pr| pr.contains_target_id(target_id))
+    }
+
     /// Returns a clone of internal rules for use in scenarios such as BucketNotificationConfig::validate.
+    ///
+    /// # Returns
+    /// A reference to the internal HashMap of EventName to PatternRules.
     pub fn inner(&self) -> &HashMap<EventName, PatternRules> {
         &self.map
     }
@@ -160,18 +183,32 @@ impl RulesMap {
     }
 
     /// Remove rules and optimize performance
+    ///
+    /// # Parameters
+    /// * `event_name` - The EventName from which to remove the rule.
+    /// * `pattern` - The pattern of the rule to be removed.
     #[allow(dead_code)]
     pub fn remove_rule(&mut self, event_name: &EventName, pattern: &str) {
+        let mut remove_event = false;
+
         if let Some(pattern_rules) = self.map.get_mut(event_name) {
-            pattern_rules.rules.remove(pattern);
+            pattern_rules.remove_pattern(pattern);
             if pattern_rules.is_empty() {
-                self.map.remove(event_name);
+                remove_event = true;
             }
         }
+
+        if remove_event {
+            self.map.remove(event_name);
+        }
+
         self.recalculate_mask(); // Delay calculation mask
     }
 
-    /// Batch Delete Rules
+    /// Batch Delete Rules and Optimize Performance
+    ///
+    /// # Parameters
+    /// * `event_names` - A slice of EventNames to be removed.
     #[allow(dead_code)]
     pub fn remove_rules(&mut self, event_names: &[EventName]) {
         for event_name in event_names {
@@ -181,9 +218,27 @@ impl RulesMap {
     }
 
     /// Update rules and optimize performance
+    ///
+    /// # Parameters
+    /// * `event_name` - The EventName to update.
+    /// * `pattern` - The pattern of the rule to be updated.
+    /// * `target_id` - The TargetID to be added.
     #[allow(dead_code)]
     pub fn update_rule(&mut self, event_name: EventName, pattern: String, target_id: TargetID) {
         self.map.entry(event_name).or_default().add(pattern, target_id);
         self.total_events_mask |= event_name.mask(); // Update only the relevant bitmask
     }
+
+    /// Iterate all EventName keys contained in this RulesMap.
+    ///
+    /// Used by snapshot compilation to compute bucket event_mask.
+    ///
+    /// # Returns
+    /// An iterator over all EventName keys in the RulesMap.
+    #[inline]
+    pub fn iter_events(&self) -> impl Iterator<Item = EventName> + '_ {
+        // `inner()` is already used by config.rs, so we reuse it here.
+        // If the key type is `EventName`, `.copied()` is the cheapest way to return values.
+        self.inner().keys().copied()
+    }
 }

crates/notify/src/rules/subscriber_index.rs

@@ -0,0 +1,131 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use crate::rules::{BucketRulesSnapshot, BucketSnapshotRef, DynRulesContainer};
+use arc_swap::ArcSwap;
+use rustfs_targets::EventName;
+use starshard::ShardedHashMap;
+use std::fmt;
+use std::sync::Arc;
+
+/// A global bucket -> snapshot index.
+///
+/// Read path: lock-free load (ArcSwap)
+/// Write path: atomic replacement after building a new snapshot
+pub struct SubscriberIndex {
+    // Use starshard for sharding to reduce lock competition when the number of buckets is large
+    inner: ShardedHashMap<String, Arc<ArcSwap<BucketRulesSnapshot<DynRulesContainer>>>>,
+    // Cache an "empty rule container" for empty snapshots (avoids building every time)
+    empty_rules: Arc<DynRulesContainer>,
+}
+
+/// Avoid deriving fields that do not support Debug
+impl fmt::Debug for SubscriberIndex {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("SubscriberIndex").finish_non_exhaustive()
+    }
+}
+
+impl SubscriberIndex {
+    /// Create a new SubscriberIndex.
+    ///
+    /// # Arguments
+    /// * `empty_rules` - An Arc to an empty rules container used for empty snapshots
+    ///
+    /// Returns a new instance of SubscriberIndex.
+    pub fn new(empty_rules: Arc<DynRulesContainer>) -> Self {
+        Self {
+            inner: ShardedHashMap::new(64),
+            empty_rules,
+        }
+    }
+
+    /// Get the current snapshot of a bucket.
+    /// If it does not exist, return empty snapshot.
+    ///
+    /// # Arguments
+    /// * `bucket` - The name of the bucket to load.
+    ///
+    /// Returns the snapshot reference for the specified bucket.
+    pub fn load_snapshot(&self, bucket: &str) -> BucketSnapshotRef {
+        match self.inner.get(&bucket.to_string()) {
+            Some(cell) => cell.load_full(),
+            None => Arc::new(BucketRulesSnapshot::empty(self.empty_rules.clone())),
+        }
+    }
+
+    /// Quickly determine whether the bucket has a subscription to an event.
+    /// This judgment can be consistent with subsequent rule matching when reading the same snapshot.
+    ///
+    /// # Arguments
+    /// * `bucket` - The name of the bucket to check.
+    /// * `event` - The event name to check for subscriptions.
+    ///
+    /// Returns `true` if there are subscribers for the event, `false` otherwise.
+    #[inline]
+    pub fn has_subscriber(&self, bucket: &str, event: &EventName) -> bool {
+        let snap = self.load_snapshot(bucket);
+        if snap.event_mask == 0 {
+            return false;
+        }
+        snap.has_event(event)
+    }
+
+    /// Atomically update a bucket's snapshot (whole package replacement).
+    ///
+    /// - The caller first builds the complete `BucketRulesSnapshot` (including event\_mask and rules).
+    /// - This method ensures that the read path will not observe intermediate states.
+    ///
+    /// # Arguments
+    /// * `bucket` - The name of the bucket to update.
+    /// * `new_snapshot` - The new snapshot to store for the bucket.
+    pub fn store_snapshot(&self, bucket: &str, new_snapshot: BucketRulesSnapshot<DynRulesContainer>) {
+        let key = bucket.to_string();
+
+        let cell = self.inner.get(&key).unwrap_or_else(|| {
+            // Insert a default cell (empty snapshot)
+            let init = Arc::new(ArcSwap::from_pointee(BucketRulesSnapshot::empty(self.empty_rules.clone())));
+            self.inner.insert(key.clone(), init.clone());
+            init
+        });
+
+        cell.store(Arc::new(new_snapshot));
+    }
+
+    /// Delete the bucket's subscription view (make it empty).
+    ///
+    /// # Arguments
+    /// * `bucket` - The name of the bucket to clear.
+    pub fn clear_bucket(&self, bucket: &str) {
+        if let Some(cell) = self.inner.get(&bucket.to_string()) {
+            cell.store(Arc::new(BucketRulesSnapshot::empty(self.empty_rules.clone())));
+        }
+    }
+}
+
+impl Default for SubscriberIndex {
+    fn default() -> Self {
+        // An available empty rule container is required; here it is implemented using minimal empty
+        #[derive(Debug)]
+        struct EmptyRules;
+        impl crate::rules::subscriber_snapshot::RulesContainer for EmptyRules {
+            type Rule = dyn crate::rules::subscriber_snapshot::RuleEvents;
+            fn iter_rules<'a>(&'a self) -> Box<dyn Iterator<Item = &'a Self::Rule> + 'a> {
+                Box::new(std::iter::empty())
+            }
+        }
+
+        Self::new(Arc::new(EmptyRules) as Arc<DynRulesContainer>)
+    }
+}

crates/notify/src/rules/subscriber_snapshot.rs

@@ -0,0 +1,117 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use rustfs_targets::EventName;
+use std::sync::Arc;
+
+/// Let the rules structure provide "what events it is subscribed to".
+/// This way BucketRulesSnapshot does not need to know the internal shape of rules.
+pub trait RuleEvents {
+    fn subscribed_events(&self) -> &[EventName];
+}
+
+/// Let the rules container provide the ability to iterate over all rules (abstracting only to the minimum necessary).
+pub trait RulesContainer {
+    type Rule: RuleEvents + ?Sized;
+    fn iter_rules<'a>(&'a self) -> Box<dyn Iterator<Item = &'a Self::Rule> + 'a>;
+
+    /// Fast empty judgment for snapshots (fix missing `rules.is_empty()`)
+    fn is_empty(&self) -> bool {
+        self.iter_rules().next().is_none()
+    }
+}
+
+/// Represents a bucket's notification subscription view snapshot (immutable).
+///
+/// - `event_mask`: Quickly determine whether there is a subscription to a certain type of event (bitset/flags).
+/// - `rules`: precise rule mapping (prefix/suffix/pattern -> targets).
+///
+/// The read path only reads this snapshot to ensure consistency.
+#[derive(Debug, Clone)]
+pub struct BucketRulesSnapshot<R>
+where
+    R: RulesContainer + ?Sized,
+{
+    pub event_mask: u64,
+    pub rules: Arc<R>,
+}
+
+impl<R> BucketRulesSnapshot<R>
+where
+    R: RulesContainer + ?Sized,
+{
+    /// Create an empty snapshot with no subscribed events and no rules.
+    ///
+    /// # Arguments
+    /// * `rules` - An Arc to a rules container (can be an empty container).
+    ///
+    /// # Returns
+    /// An instance of `BucketRulesSnapshot` with an empty event mask.
+    #[inline]
+    pub fn empty(rules: Arc<R>) -> Self {
+        Self { event_mask: 0, rules }
+    }
+
+    /// Check if the snapshot has any subscribers for the specified event.
+    ///
+    /// # Arguments
+    /// * `event` - The event name to check for subscriptions.
+    ///
+    /// # Returns
+    /// `true` if there are subscribers for the event, `false` otherwise.
+    #[inline]
+    pub fn has_event(&self, event: &EventName) -> bool {
+        (self.event_mask & event.mask()) != 0
+    }
+
+    /// Check if the snapshot is empty (no subscribed events or rules).
+    ///
+    /// # Returns
+    /// `true` if the snapshot is empty, `false` otherwise.
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.event_mask == 0 || self.rules.is_empty()
+    }
+
+    /// [debug] Assert that `event_mask` is consistent with the event declared in `rules`.
+    ///
+    /// Constraints:
+    /// - only runs in debug builds (release incurs no cost).
+    /// - If the rule contains compound events (\*All / Everything), rely on `EventName::mask()` to automatically expand.
+    #[inline]
+    pub fn debug_assert_mask_consistent(&self) {
+        #[cfg(debug_assertions)]
+        {
+            let mut recomputed = 0u64;
+            for rule in self.rules.iter_rules() {
+                for ev in rule.subscribed_events() {
+                    recomputed |= ev.mask();
+                }
+            }
+
+            debug_assert!(
+                recomputed == self.event_mask,
+                "BucketRulesSnapshot.event_mask inconsistent: stored={:#x}, recomputed={:#x}",
+                self.event_mask,
+                recomputed
+            );
+        }
+    }
+}
+
+/// Unify trait-object snapshot types (fix Sized / missing generic arguments)
+pub type DynRulesContainer = dyn RulesContainer<Rule = dyn RuleEvents> + Send + Sync;
+
+/// Expose Arc form to facilitate sharing.
+pub type BucketSnapshotRef = Arc<BucketRulesSnapshot<DynRulesContainer>>;

crates/notify/src/rules/xml_config.rs

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use super::pattern;
+use crate::rules::pattern;
 use hashbrown::HashSet;
 use rustfs_targets::EventName;
 use rustfs_targets::arn::{ARN, ArnError, TargetIDError};