Skip to main content

rustfs_test_utils/
lib.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
15#![recursion_limit = "256"]
16
17//! Shared test bootstrap helpers for RustFS integration tests
18//! (backlog#1153 infra-1).
19//!
20//! This crate is a **dev-dependency only**: it must never appear in any
21//! crate's `[dependencies]`. It owns the ~50-line "build a real temp-disk
22//! `ECStore`" bootstrap that used to be copy-pasted (and drift) across the
23//! heal/iam/scanner integration tests.
24//!
25//! Single-process integration scope only — multi-node / chaos harnesses are
26//! out of scope (backlog#1100).
27
28#[cfg(test)]
29mod data_usage_snapshot_tests;
30mod ecstore_test_compat;
31
32use std::path::PathBuf;
33use std::sync::{Arc, Once};
34
35#[cfg(feature = "put-object-commit-barrier")]
36use ecstore_test_compat::fixture::ecstore_set_disk;
37use ecstore_test_compat::fixture::{
38    BucketOperations as _, BucketOptions, ECStore, Endpoint, EndpointServerPools, Endpoints, MakeBucketOptions, ObjectIO as _,
39    PoolEndpoints, PutObjReader, SelectObjectSnapshot, init_bucket_metadata_sys, init_local_disks,
40};
41use tokio_util::sync::CancellationToken;
42
43static INIT_TRACING: Once = Once::new();
44
45#[cfg(feature = "put-object-commit-barrier")]
46pub struct PutObjectCommitBarrier(ecstore_set_disk::test_util::PutObjectCommitBarrier);
47
48#[cfg(feature = "put-object-commit-barrier")]
49impl PutObjectCommitBarrier {
50    pub fn before_namespace(bucket: &str, object: &str) -> Self {
51        Self(ecstore_set_disk::test_util::PutObjectCommitBarrier::install(
52            bucket,
53            object,
54            ecstore_set_disk::test_util::PutObjectCommitPause::BeforeNamespace,
55        ))
56    }
57
58    pub async fn wait_until_paused(&self) {
59        self.0.wait_until_paused().await;
60    }
61
62    pub async fn release_and_wait_until_namespace_pending(&self) {
63        self.0.release_and_wait_until_namespace_pending().await;
64    }
65}
66
67/// Install the standard test tracing subscriber once per process
68/// (`RUST_LOG`-driven). Safe to call from every test; later calls are no-ops.
69pub fn init_tracing() {
70    INIT_TRACING.call_once(|| {
71        let _ = tracing_subscriber::fmt()
72            .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
73            .with_timer(tracing_subscriber::fmt::time::UtcTime::rfc_3339())
74            .with_thread_names(true)
75            .try_init();
76    });
77}
78
79/// A real single-pool, single-set `ECStore` built over per-test temp-dir
80/// "disks". Build one with [`TestECStoreEnv::builder`].
81///
82/// The environment intentionally does **not** delete `temp_root` on drop:
83/// the historical bootstraps leaked their uuid-suffixed temp dirs so a failed
84/// test's on-disk state stays inspectable, and several heal tests keep
85/// manipulating `disk_paths` after setup. Callers that own the directory
86/// lifetime (e.g. via `tempfile::TempDir`) should pass it through
87/// [`TestECStoreEnvBuilder::base_dir`].
88pub struct TestECStoreEnv {
89    /// Root directory holding the disk directories.
90    pub temp_root: PathBuf,
91    /// The per-disk directories (`disk1`..`diskN`) under `temp_root`.
92    pub disk_paths: Vec<PathBuf>,
93    /// The store, bootstrapped exactly like the historical test setups:
94    /// `init_local_disks` + `ECStore::new` on `127.0.0.1:0` (random port keeps
95    /// nextest's process-per-test parallelism safe).
96    pub ecstore: Arc<ECStore>,
97    /// The single-pool, single-set topology the store was built from.
98    ///
99    /// The bootstrap does **not** publish it on the instance context (server
100    /// startup is what calls `set_endpoints`, and that write is once-only), so
101    /// a test that needs `get_global_endpoints` to resolve — admin server-info
102    /// and other topology readers — publishes this value itself.
103    pub endpoint_pools: EndpointServerPools,
104}
105
106impl TestECStoreEnv {
107    pub fn builder() -> TestECStoreEnvBuilder {
108        TestECStoreEnvBuilder::default()
109    }
110
111    /// Create a bucket, optionally with S3 versioning enabled at creation
112    /// time (without this a second PUT overwrites in place and DELETE removes
113    /// the object outright — no old versions or delete-marker-latest exist).
114    pub async fn make_bucket(&self, bucket: &str, versioned: bool) {
115        self.ecstore
116            .make_bucket(
117                bucket,
118                &MakeBucketOptions {
119                    versioning_enabled: versioned,
120                    ..Default::default()
121                },
122            )
123            .await
124            .unwrap_or_else(|e| panic!("failed to create test bucket {bucket}: {e:?}"));
125    }
126
127    /// Write one complete object body through the real ECStore test backend.
128    pub async fn put_object_bytes(&self, bucket: &str, object: &str, bytes: Vec<u8>) {
129        let mut reader = PutObjReader::from_vec(bytes);
130        self.ecstore
131            .put_object(bucket, object, &mut reader, &Default::default())
132            .await
133            .unwrap_or_else(|e| panic!("failed to write test object {bucket}/{object}: {e:?}"));
134    }
135
136    /// Prepare the lock-backed object snapshot used by SelectObjectContent tests.
137    ///
138    /// The concrete ECStore snapshot type stays behind this crate's test
139    /// compatibility boundary; consumers can pass the inferred value directly
140    /// to the S3 Select API without importing ECStore facade paths.
141    pub async fn prepare_select_object_snapshot(&self, bucket: &str, object: &str) -> Arc<SelectObjectSnapshot> {
142        Arc::new(
143            self.ecstore
144                .prepare_select_object_snapshot(bucket, object, &Default::default(), &Default::default())
145                .await
146                .unwrap_or_else(|e| panic!("failed to prepare test object snapshot {bucket}/{object}: {e:?}")),
147        )
148    }
149}
150
151/// Builder for [`TestECStoreEnv`]. Defaults reproduce the historical heal
152/// bootstrap: 4 disks, one pool, one set, bucket-metadata system initialized.
153pub struct TestECStoreEnvBuilder {
154    disk_count: usize,
155    prefix: String,
156    base_dir: Option<PathBuf>,
157    init_bucket_metadata: bool,
158}
159
160impl Default for TestECStoreEnvBuilder {
161    fn default() -> Self {
162        Self {
163            disk_count: 4,
164            prefix: "rustfs_test_utils".to_string(),
165            base_dir: None,
166            init_bucket_metadata: true,
167        }
168    }
169}
170
171impl TestECStoreEnvBuilder {
172    /// Number of disk directories in the single erasure set (default 4).
173    pub fn disk_count(mut self, n: usize) -> Self {
174        self.disk_count = n;
175        self
176    }
177
178    /// Temp-dir name prefix, e.g. `rustfs_heal_b5_test` (a uuid suffix is
179    /// always appended). Ignored when [`base_dir`](Self::base_dir) is set.
180    pub fn prefix(mut self, prefix: &str) -> Self {
181        self.prefix = prefix.to_string();
182        self
183    }
184
185    /// Use a caller-owned directory (e.g. a `tempfile::TempDir` path) instead
186    /// of creating `/tmp/<prefix>_<uuid>`. The caller keeps cleanup ownership.
187    pub fn base_dir(mut self, dir: impl Into<PathBuf>) -> Self {
188        self.base_dir = Some(dir.into());
189        self
190    }
191
192    /// Whether to run `init_bucket_metadata_sys` after the store comes up
193    /// (default `true`, as the heal bootstraps did).
194    pub fn init_bucket_metadata(mut self, yes: bool) -> Self {
195        self.init_bucket_metadata = yes;
196        self
197    }
198
199    /// Build the environment. Panics on any bootstrap failure — this is test
200    /// scaffolding, and a broken environment must fail the test loudly.
201    pub async fn build(self) -> TestECStoreEnv {
202        init_tracing();
203
204        let temp_root = match &self.base_dir {
205            Some(dir) => dir.clone(),
206            None => {
207                let root = PathBuf::from(format!("/tmp/{}_{}", self.prefix, uuid::Uuid::new_v4()));
208                if root.exists() {
209                    tokio::fs::remove_dir_all(&root).await.ok();
210                }
211                root
212            }
213        };
214        tokio::fs::create_dir_all(&temp_root).await.expect("create test temp root");
215
216        let disk_paths: Vec<PathBuf> = (1..=self.disk_count).map(|i| temp_root.join(format!("disk{i}"))).collect();
217        for disk_path in &disk_paths {
218            tokio::fs::create_dir_all(disk_path).await.expect("create test disk dir");
219        }
220
221        let mut endpoints = Vec::new();
222        for (i, disk_path) in disk_paths.iter().enumerate() {
223            let mut endpoint = Endpoint::try_from(disk_path.to_str().expect("utf-8 disk path")).expect("parse disk endpoint");
224            endpoint.set_pool_index(0);
225            endpoint.set_set_index(0);
226            endpoint.set_disk_index(i);
227            endpoints.push(endpoint);
228        }
229
230        let pool_endpoints = PoolEndpoints {
231            legacy: false,
232            set_count: 1,
233            drives_per_set: self.disk_count,
234            endpoints: Endpoints::from(endpoints),
235            cmd_line: "test".to_string(),
236            platform: format!("OS: {} | Arch: {}", std::env::consts::OS, std::env::consts::ARCH),
237        };
238        let endpoint_pools = EndpointServerPools::from(vec![pool_endpoints]);
239
240        init_local_disks(endpoint_pools.clone()).await.expect("init local disks");
241
242        // Port 0 keeps ECStore-backed integration binaries parallel-safe under
243        // nextest: no fixed peer port is ever shared between test processes.
244        let server_addr: std::net::SocketAddr = "127.0.0.1:0".parse().expect("parse test addr");
245        let ecstore = ECStore::new(server_addr, endpoint_pools.clone(), CancellationToken::new())
246            .await
247            .expect("build test ECStore");
248
249        // The production bootstrap only persists pool.bin from the elected
250        // first cluster node.  Test stores intentionally have no cluster
251        // election, but heal-format still requires that durable fence before
252        // it can write any disk format.  Materialize the validated topology
253        // here so the shared fixture models a ready single-node store.
254        let mut pool_meta = ecstore.pool_meta.read().await.clone();
255        pool_meta.dont_save = false;
256        pool_meta
257            .save(ecstore.pools.clone())
258            .await
259            .expect("persist test pool metadata");
260
261        if self.init_bucket_metadata {
262            let buckets_list = ecstore
263                .list_bucket(&BucketOptions {
264                    no_metadata: true,
265                    ..Default::default()
266                })
267                .await
268                .expect("list buckets for metadata init");
269            let buckets = buckets_list.into_iter().map(|v| v.name).collect();
270            init_bucket_metadata_sys(ecstore.clone(), buckets).await;
271        }
272
273        TestECStoreEnv {
274            temp_root,
275            disk_paths,
276            ecstore,
277            endpoint_pools,
278        }
279    }
280}