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}