Skip to main content

rustfs_notify/rules/
subscriber_index.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 crate::rules::{BucketRulesSnapshot, BucketSnapshotRef, DynRulesContainer};
16use arc_swap::ArcSwap;
17use rustfs_s3_types::EventName;
18use starshard::{DEFAULT_SHARDS, ShardedHashMap};
19use std::fmt;
20use std::sync::Arc;
21
22/// A global bucket -> snapshot index.
23///
24/// Read path: lock-free load (ArcSwap)
25/// Write path: atomic replacement after building a new snapshot
26pub struct SubscriberIndex {
27    // Use starshard for sharding to reduce lock competition when the number of buckets is large
28    inner: ShardedHashMap<String, Arc<ArcSwap<BucketRulesSnapshot<DynRulesContainer>>>>,
29    // Cache an "empty rule container" for empty snapshots (avoids building every time)
30    empty_rules: Arc<DynRulesContainer>,
31}
32
33/// Avoid deriving fields that do not support Debug
34impl fmt::Debug for SubscriberIndex {
35    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
36        f.debug_struct("SubscriberIndex").finish_non_exhaustive()
37    }
38}
39
40impl SubscriberIndex {
41    /// Create a new SubscriberIndex.
42    ///
43    /// # Arguments
44    /// * `empty_rules` - An Arc to an empty rules container used for empty snapshots
45    ///
46    /// Returns a new instance of SubscriberIndex.
47    pub fn new(empty_rules: Arc<DynRulesContainer>) -> Self {
48        Self {
49            inner: ShardedHashMap::new(DEFAULT_SHARDS),
50            empty_rules,
51        }
52    }
53
54    /// Get the current snapshot of a bucket.
55    /// If it does not exist, return empty snapshot.
56    ///
57    /// # Arguments
58    /// * `bucket` - The name of the bucket to load.
59    ///
60    /// Returns the snapshot reference for the specified bucket.
61    pub fn load_snapshot(&self, bucket: &str) -> BucketSnapshotRef {
62        match self.inner.get(&bucket.to_string()) {
63            Some(cell) => cell.load_full(),
64            None => Arc::new(BucketRulesSnapshot::empty(self.empty_rules.clone())),
65        }
66    }
67
68    /// Quickly determine whether the bucket has a subscription to an event.
69    /// This judgment can be consistent with subsequent rule matching when reading the same snapshot.
70    ///
71    /// # Arguments
72    /// * `bucket` - The name of the bucket to check.
73    /// * `event` - The event name to check for subscriptions.
74    ///
75    /// Returns `true` if there are subscribers for the event, `false` otherwise.
76    #[inline]
77    pub fn has_subscriber(&self, bucket: &str, event: &EventName) -> bool {
78        let snap = self.load_snapshot(bucket);
79        if snap.event_mask == 0 {
80            return false;
81        }
82        snap.has_event(event)
83    }
84
85    /// Atomically update a bucket's snapshot (whole package replacement).
86    ///
87    /// - The caller first builds the complete `BucketRulesSnapshot` (including event\_mask and rules).
88    /// - This method ensures that the read path will not observe intermediate states.
89    ///
90    /// # Arguments
91    /// * `bucket` - The name of the bucket to update.
92    /// * `new_snapshot` - The new snapshot to store for the bucket.
93    pub fn store_snapshot(&self, bucket: &str, new_snapshot: BucketRulesSnapshot<DynRulesContainer>) {
94        let key = bucket.to_string();
95
96        // Atomic get-or-create of the bucket's cell. The previous `get()` then
97        // `insert()` was a TOCTOU: two concurrent first-writers for the same bucket
98        // could both observe `None`, each build a distinct `ArcSwap` cell, and both
99        // `insert` — the second insert overwrites the first cell, so the snapshot
100        // stored into the discarded cell is silently lost. `compute_if_absent` holds
101        // the shard write lock across the check-and-insert, so every caller shares the
102        // one winning cell and no snapshot is dropped (backlog#984).
103        let empty_rules = self.empty_rules.clone();
104        let cell = self
105            .inner
106            .compute_if_absent(key, || Arc::new(ArcSwap::from_pointee(BucketRulesSnapshot::empty(empty_rules.clone()))));
107
108        cell.store(Arc::new(new_snapshot));
109    }
110
111    /// Delete the bucket's subscription view (make it empty).
112    ///
113    /// # Arguments
114    /// * `bucket` - The name of the bucket to clear.
115    pub fn clear_bucket(&self, bucket: &str) {
116        if let Some(cell) = self.inner.get(&bucket.to_string()) {
117            cell.store(Arc::new(BucketRulesSnapshot::empty(self.empty_rules.clone())));
118        }
119    }
120}
121
122impl Default for SubscriberIndex {
123    fn default() -> Self {
124        Self::new(Arc::new(EmptyRules) as Arc<DynRulesContainer>)
125    }
126}
127
128/// A minimal empty rules container used for empty snapshots and tests.
129#[derive(Debug)]
130struct EmptyRules;
131
132impl crate::rules::subscriber_snapshot::RulesContainer for EmptyRules {
133    type Rule = dyn crate::rules::subscriber_snapshot::RuleEvents;
134    fn iter_rules<'a>(&'a self) -> Box<dyn Iterator<Item = &'a Self::Rule> + 'a> {
135        Box::new(std::iter::empty())
136    }
137}
138
139#[cfg(test)]
140mod tests {
141    use super::*;
142    use rustfs_s3_types::EventName;
143
144    fn snapshot_with_mask(mask: u64) -> BucketRulesSnapshot<DynRulesContainer> {
145        BucketRulesSnapshot {
146            event_mask: mask,
147            rules: Arc::new(EmptyRules) as Arc<DynRulesContainer>,
148        }
149    }
150
151    #[test]
152    fn store_then_load_roundtrips_snapshot() {
153        let index = SubscriberIndex::default();
154        assert!(!index.has_subscriber("bucket", &EventName::ObjectCreatedPut));
155
156        index.store_snapshot("bucket", snapshot_with_mask(EventName::ObjectCreatedPut.mask()));
157        assert!(index.has_subscriber("bucket", &EventName::ObjectCreatedPut));
158
159        index.clear_bucket("bucket");
160        assert!(!index.has_subscriber("bucket", &EventName::ObjectCreatedPut));
161    }
162
163    /// Regression test for backlog#984 (subscriber_index TOCTOU): many tasks
164    /// concurrently perform the first write for the *same* new bucket. The old
165    /// `get()`-then-`insert()` path could have concurrent first-writers each build
166    /// a distinct cell and clobber one another in the map, orphaning a stored
167    /// snapshot. With the atomic `compute_if_absent` upsert every writer shares the
168    /// one winning cell, so the final snapshot is always a real, non-empty store —
169    /// never the discarded empty default.
170    #[tokio::test(flavor = "multi_thread", worker_threads = 8)]
171    async fn concurrent_first_writes_share_one_cell() {
172        let mask = EventName::ObjectCreatedPut.mask();
173        for _round in 0..64 {
174            let index = Arc::new(SubscriberIndex::default());
175            const WRITERS: usize = 16;
176
177            let mut handles = Vec::with_capacity(WRITERS);
178            for _ in 0..WRITERS {
179                let index = index.clone();
180                handles.push(tokio::spawn(async move {
181                    index.store_snapshot("shared-bucket", snapshot_with_mask(mask));
182                }));
183            }
184            for handle in handles {
185                handle.await.expect("writer task must not panic");
186            }
187
188            assert!(
189                index.has_subscriber("shared-bucket", &EventName::ObjectCreatedPut),
190                "a concurrently-stored snapshot must survive; none was lost to a clobbered cell"
191            );
192        }
193    }
194}