fn to_filemeta_err(err: Error) -> rustfs_filemeta::Error {
err.narrow_to_filemeta().unwrap_or_else(rustfs_filemeta::Error::other)
}
use crate::bucket::lifecycle::bucket_lifecycle_ops::free_version_remote_tuple_matches;
use crate::bucket::metadata_sys::{
get_versioning_config, has_authoritative_never_versioned_state, has_authoritative_never_versioned_state_in,
};
use crate::bucket::utils::check_list_objs_args;
use crate::bucket::versioning::VersioningApi;
use crate::cache_value::metacache_set::{
FallbackClaimTracker, ListPathRawOptions, list_path_raw_with_claim_tracker, list_path_raw_with_partial_result,
};
use crate::core::sets::Sets;
use crate::disk::error::DiskError;
use crate::disk::{DiskAPI, DiskInfo, DiskStore, RUSTFS_META_BUCKET, WalkDirOptions};
use crate::error::{
Error, Result, StorageError, is_all_disk_not_found, is_all_not_found, is_all_volume_not_found, to_object_err,
};
use crate::object_api::{ObjectInfo, ObjectOptions};
use crate::set_disk::SetDisks;
use crate::storage_api_contracts::{
list::{
ListObjectsInfo as StorageListObjectsInfo, StorageListObjectVersionsInfo, StorageListObjectsV2Info,
StorageObjectInfoOrErr, StorageWalkOptions, VersionMarker, WalkVersionsSortOrder,
},
object::ObjectOperations as _,
};
use crate::store::ECStore;
use crate::store::utils::is_reserved_or_invalid_bucket;
use base64_simd::STANDARD as BASE64_STANDARD;
use bytes::Bytes;
use futures::future::join_all;
use rand::seq::SliceRandom;
use rustfs_filemeta::{
FileMeta, FileMetaShallowVersion, MetaCacheEntries, MetaCacheEntriesSorted, MetaCacheEntriesSortedResult, MetaCacheEntry,
MetacacheReader, MetadataResolutionParams, is_io_eof,
};
use rustfs_io_metrics::{
LIST_OBJECTS_GATHER_OUTCOME_INPUT_CLOSED, LIST_OBJECTS_GATHER_OUTCOME_LIMIT_REACHED, LIST_OBJECTS_SOURCE_WALKER,
ListObjectsGatherObservation, ListObjectsIndexPageObservation,
};
use rustfs_utils::path::{self, SLASH_SEPARATOR, base_dir_from_prefix};
use std::cmp::Reverse;
use std::collections::{BinaryHeap, HashMap, HashSet};
use std::future::Future;
use std::path::{Path, PathBuf};
use std::sync::{
Arc,
atomic::{AtomicBool, AtomicU64, Ordering},
};
use std::time::{Duration, SystemTime, UNIX_EPOCH};
use tokio::io::duplex;
use tokio::sync::broadcast::{self};
use tokio::sync::mpsc::{self, Receiver, Sender};
use tokio::sync::{OnceCell, RwLock};
use tokio::task::{JoinHandle, JoinSet};
use tokio_util::sync::CancellationToken;
use tracing::{Instrument, debug, error, info, warn};
use uuid::Uuid;
const MAX_OBJECT_LIST: i32 = 1000;
const METACACHE_SHARE_PREFIX: bool = false;
fn duration_millis(duration: Duration) -> u64 {
u64::try_from(duration.as_millis()).unwrap_or(u64::MAX)
}
type ListObjectsInfo = StorageListObjectsInfo<ObjectInfo>;
type ListObjectsV2Info = StorageListObjectsV2Info<ObjectInfo>;
type ListObjectVersionsInfo = StorageListObjectVersionsInfo<ObjectInfo>;
type ObjectInfoOrErr = StorageObjectInfoOrErr<ObjectInfo, Error>;
type WalkOptions = StorageWalkOptions<fn(&rustfs_filemeta::FileInfo) -> bool>;
fn recursive_walk_list_path_options(bucket: String, prefix: &str, opts: &WalkOptions) -> ListPathOptions {
let mut list_options = ListPathOptions {
bucket,
prefix: prefix.to_owned(),
marker: opts.marker.clone(),
limit: i32::try_from(opts.limit).unwrap_or(i32::MAX),
ask_disks: opts.ask_disks.clone(),
incl_deleted: true,
recursive: true,
versioned: true,
walkdir_timeout: opts.walkdir_timeout,
walkdir_stall_timeout: opts.walkdir_stall_timeout,
..Default::default()
};
list_options.base_dir = base_dir_from_prefix(prefix);
list_options.set_filter();
list_options
}
struct ListObjectVersionsInput<'a> {
bucket: &'a str,
prefix: &'a str,
marker: Option<String>,
version_marker: Option<String>,
delimiter: Option<String>,
max_keys: i32,
include_version_purge: bool,
}
const LIST_MERGED_INPUT_BUFFER: usize = 1;
fn list_merged_entry_channel() -> (Sender<MetaCacheEntry>, Receiver<MetaCacheEntry>) {
mpsc::channel(LIST_MERGED_INPUT_BUFFER)
}
fn normalize_max_keys(max_keys: i32) -> i32 {
max_keys.min(MAX_OBJECT_LIST)
}
fn ensure_non_empty_listing_disks(bucket: &str, path: &str, disks: &[DiskStore]) -> Result<()> {
if disks.is_empty() {
warn!(
bucket = %bucket,
path = %path,
"listing candidate disks collapsed to empty set"
);
return Err(StorageError::ErasureReadQuorum);
}
Ok(())
}
fn walk_result_from_set_errors(errs: &[Option<Error>]) -> Result<()> {
if is_all_not_found(errs) {
if is_all_volume_not_found(errs) {
return Err(StorageError::VolumeNotFound);
}
return Ok(());
}
if is_all_disk_not_found(errs) {
return Err(StorageError::DiskNotFound);
}
for err in errs.iter().flatten() {
if err == &Error::Unexpected || err.is_not_found() {
continue;
}
return Err(err.clone());
}
Ok(())
}
pub fn max_keys_plus_one(max_keys: i32, add_one: bool) -> i32 {
let mut max_keys = max_keys;
if !(0..=MAX_OBJECT_LIST).contains(&max_keys) {
max_keys = MAX_OBJECT_LIST;
}
if add_one {
max_keys += 1;
}
max_keys
}
fn list_versions_scan_limit(max_keys: i32, has_version_marker: bool) -> i32 {
if max_keys <= 0 {
return 0;
}
max_keys_plus_one(max_keys, true) + i32::from(has_version_marker)
}
#[derive(Debug, Clone, Copy, Eq, PartialEq)]
enum GatherResultsState {
LimitReached,
InputClosed,
ConsumerGone,
}
#[derive(Clone)]
struct ListPathLogContext {
bucket: String,
base_dir: String,
prefix: String,
marker: String,
limit: i32,
}
impl ListPathLogContext {
fn from_options(opts: &ListPathOptions) -> Self {
Self {
bucket: opts.bucket.clone(),
base_dir: opts.base_dir.clone(),
prefix: opts.prefix.clone(),
marker: opts.marker.clone().unwrap_or_default(),
limit: opts.limit,
}
}
}
fn log_list_path_worker_error<E>(component: &'static str, stage: &'static str, context: &ListPathLogContext, err: &E)
where
E: std::fmt::Display + ?Sized,
{
error!(
component,
stage,
bucket = %context.bucket,
prefix = %context.prefix,
base_dir = %context.base_dir,
limit = context.limit,
marker = %context.marker,
error = %err,
"list_path worker failed"
);
}
fn log_list_path_finished(
component: &'static str,
context: &ListPathLogContext,
elapsed_ms: f64,
candidate_count: usize,
has_error: bool,
) {
debug!(
component,
bucket = %context.bucket,
prefix = %context.prefix,
base_dir = %context.base_dir,
limit = context.limit,
marker = %context.marker,
candidate_count,
has_error,
elapsed_ms,
"list_path finished"
);
}
#[derive(Debug, Default, Clone)]
pub struct ListPathOptions {
pub id: Option<String>,
pub bucket: String,
pub base_dir: String,
pub prefix: String,
pub filter_prefix: Option<String>,
pub marker: Option<String>,
pub include_marker: bool,
pub limit: i32,
pub ask_disks: String,
pub incl_deleted: bool,
pub skip_hidden_prefix_check: bool,
pub recursive: bool,
pub separator: Option<String>,
pub create: bool,
pub include_directories: bool,
pub transient: bool,
pub versioned: bool,
pub stop_disk_at_limit: bool,
pub pool_idx: Option<usize>,
pub set_idx: Option<usize>,
pub cursor_source: Option<ListSourceMode>,
pub cursor_generation: Option<String>,
pub walkdir_timeout: Option<Duration>,
pub walkdir_stall_timeout: Option<Duration>,
pub producer_limit_reached: Option<Arc<AtomicBool>>,
}
fn ensure_producer_limit_state(options: &mut ListPathOptions) -> Arc<AtomicBool> {
let state = options
.producer_limit_reached
.clone()
.unwrap_or_else(|| Arc::new(AtomicBool::new(false)));
options.producer_limit_reached = Some(state.clone());
state
}
async fn can_skip_hidden_prefix_check(options: &ListPathOptions) -> bool {
if options.recursive || options.incl_deleted || options.versioned {
return false;
}
has_authoritative_never_versioned_state(&options.bucket)
.await
.unwrap_or(false)
}
fn should_purge_empty_directory_listing(
prefix: &str,
marker: Option<&str>,
max_keys: i32,
incl_deleted: bool,
result: &ListObjectsInfo,
) -> bool {
!prefix.is_empty()
&& prefix.ends_with(SLASH_SEPARATOR)
&& marker.is_none()
&& max_keys > 0
&& !incl_deleted
&& !result.is_truncated
&& result.objects.is_empty()
&& result.prefixes.is_empty()
}
fn should_purge_empty_recursive_bucket_listing(
prefix: &str,
delimiter: Option<&str>,
marker: Option<&str>,
max_keys: i32,
incl_deleted: bool,
result: &ListObjectsInfo,
) -> bool {
prefix.is_empty()
&& delimiter.is_none()
&& marker.is_none()
&& max_keys > 0
&& !incl_deleted
&& !result.is_truncated
&& result.objects.is_empty()
&& result.prefixes.is_empty()
}
const MARKER_TAG_VERSION: &str = "v2";
const LEGACY_MARKER_TAG_VERSIONS: &[&str] = &["v1", MARKER_TAG_VERSION];
const LIST_CACHE_MARKER_PREFIX: &str = "[rustfs_cache:";
const LIST_CURSOR_SOURCE_WALKER: &str = "walker";
const LIST_CURSOR_SOURCE_INDEX_KEY_ONLY: &str = "index_key_only";
const LIST_CURSOR_SOURCE_INDEX_VERIFIED_PAGE: &str = "index_verified_page";
const LIST_CURSOR_SOURCE_INDEX_METADATA_FAST: &str = "index_metadata_fast";
const LIST_CURSOR_GENERATION_LIVE: &str = "live";
const DEFAULT_API_LIST_QUORUM: &str = "strict";
const ENV_API_LIST_OBJECTS_QUORUM: &str = "RUSTFS_LIST_OBJECTS_QUORUM";
const DEFAULT_API_LIST_OBJECTS_QUORUM: &str = "optimal";
const ENV_API_LIST_OBJECTS_INDEX_MODE: &str = "RUSTFS_LIST_OBJECTS_INDEX_MODE";
const ENV_API_LIST_OBJECTS_INDEX_PROVIDER: &str = "RUSTFS_LIST_OBJECTS_INDEX_PROVIDER";
const ENV_API_LIST_OBJECTS_INDEX_PROVIDER_PATH: &str = "RUSTFS_LIST_OBJECTS_INDEX_PROVIDER_PATH";
const ENV_API_LIST_OBJECTS_INDEX_PROVIDER_GENERATION: &str = "RUSTFS_LIST_OBJECTS_INDEX_PROVIDER_GENERATION";
const ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_PATH: &str = "RUSTFS_LIST_OBJECTS_NAMESPACE_JOURNAL_PATH";
#[cfg(any(test, feature = "list-chaos"))]
const ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED: &str = "RUSTFS_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED";
#[cfg(any(test, feature = "list-chaos"))]
const ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET: &str = "RUSTFS_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET";
#[cfg(any(test, feature = "list-chaos"))]
const ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_SEQUENCE: &str = "RUSTFS_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_SEQUENCE";
#[cfg(any(test, feature = "list-chaos"))]
const ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS: &str = "RUSTFS_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS";
const ENV_API_LIST_OBJECTS_METADATA_FAST_ENABLED: &str = "RUSTFS_LIST_OBJECTS_METADATA_FAST_ENABLED";
const ENV_API_LIST_OBJECTS_METADATA_FAST_STALENESS_MS: &str = "RUSTFS_LIST_OBJECTS_METADATA_FAST_STALENESS_MS";
const MAX_LIST_OBJECTS_METADATA_FAST_STALENESS_MS: u64 = 60_000;
const LIST_OBJECTS_INDEX_PROVIDER_WALKER_KEY_ONLY: &str = "walker_key_only";
const LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY: &str = "persistent_key_only";
const LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY_DEFAULT_GENERATION: &str = "persistent-key-only";
const PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION: u8 = 2;
const PERSISTENT_KEY_ONLY_INDEX_HEADER: &str = "# rustfs-listobjects-key-only-v2";
const PERSISTENT_KEY_ONLY_INDEX_BUCKET_HEADER: &str = "# bucket=";
const PERSISTENT_KEY_ONLY_INDEX_GENERATION_HEADER: &str = "# generation=";
const PERSISTENT_KEY_ONLY_INDEX_CHECKPOINT_HEADER: &str = "# checkpoint_high_water_mark=";
const PERSISTENT_KEY_ONLY_INDEX_OBJECT_PREFIX: &str = "# object\t";
const LIST_OBJECTS_NAMESPACE_JOURNAL_HEADER: &str = "# rustfs-listobjects-namespace-journal-v1";
const LIST_OBJECTS_NAMESPACE_JOURNAL_BUCKET_HEADER: &str = "# bucket=";
const LIST_OBJECTS_NAMESPACE_JOURNAL_HIGH_WATER_MARK_HEADER: &str = "# high_water_mark=";
const LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_HEADER: &str = "# status=";
const LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_HEALTHY: &str = "healthy";
const LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_DEGRADED: &str = "degraded";
const LIST_OBJECTS_NAMESPACE_JOURNAL_DEFAULT_DIR: &str = "namespace-mutation-journal";
const LIST_OBJECTS_NAMESPACE_JOURNAL_SYSTEM_PREFIX: &str = "listobjects/ns-journal/v1";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ListSourceMode {
Walker,
IndexKeyOnly,
IndexVerifiedPage,
IndexMetadataFast,
}
impl ListSourceMode {
fn cursor_value(self) -> &'static str {
match self {
Self::Walker => LIST_CURSOR_SOURCE_WALKER,
Self::IndexKeyOnly => LIST_CURSOR_SOURCE_INDEX_KEY_ONLY,
Self::IndexVerifiedPage => LIST_CURSOR_SOURCE_INDEX_VERIFIED_PAGE,
Self::IndexMetadataFast => LIST_CURSOR_SOURCE_INDEX_METADATA_FAST,
}
}
fn from_cursor_value(source: &str) -> Option<Self> {
match source {
LIST_CURSOR_SOURCE_WALKER => Some(Self::Walker),
LIST_CURSOR_SOURCE_INDEX_KEY_ONLY => Some(Self::IndexKeyOnly),
LIST_CURSOR_SOURCE_INDEX_VERIFIED_PAGE => Some(Self::IndexVerifiedPage),
LIST_CURSOR_SOURCE_INDEX_METADATA_FAST => Some(Self::IndexMetadataFast),
_ => None,
}
}
fn metadata_authority(self) -> ListMetadataAuthority {
match self {
Self::Walker => ListMetadataAuthority::LiveXlMeta,
Self::IndexKeyOnly | Self::IndexVerifiedPage => ListMetadataAuthority::LiveVerifiedIndexCandidate,
Self::IndexMetadataFast => ListMetadataAuthority::IndexSnapshotEventuallyConsistent,
}
}
fn requires_live_metadata_verification(self) -> bool {
matches!(self, Self::IndexKeyOnly | Self::IndexVerifiedPage)
}
fn can_satisfy_strong_listing(self) -> bool {
!matches!(self.metadata_authority(), ListMetadataAuthority::IndexSnapshotEventuallyConsistent)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ListMetadataAuthority {
LiveXlMeta,
LiveVerifiedIndexCandidate,
IndexSnapshotEventuallyConsistent,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ListIndexFallbackReason {
Disabled,
Rebuilding,
Unhealthy,
Lagging,
Degraded,
MissingGeneration,
GenerationMismatch,
UnsupportedRequest,
MetadataFastUnavailable,
}
impl ListIndexFallbackReason {
fn metric_label(self) -> &'static str {
match self {
Self::Disabled => "disabled",
Self::Rebuilding => "rebuilding",
Self::Unhealthy => "unhealthy",
Self::Lagging => "lagging",
Self::Degraded => "degraded",
Self::MissingGeneration => "missing_generation",
Self::GenerationMismatch => "generation_mismatch",
Self::UnsupportedRequest => "unsupported_request",
Self::MetadataFastUnavailable => "metadata_fast_unavailable",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ListObjectsIndexProviderKind {
WalkerKeyOnly,
PersistentKeyOnly,
}
impl ListObjectsIndexProviderKind {
fn metric_label(self) -> &'static str {
match self {
Self::WalkerKeyOnly => LIST_OBJECTS_INDEX_PROVIDER_WALKER_KEY_ONLY,
Self::PersistentKeyOnly => LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY,
}
}
}
fn list_objects_index_provider_metric_label(provider: Option<ListObjectsIndexProviderKind>) -> &'static str {
provider.map(ListObjectsIndexProviderKind::metric_label).unwrap_or("none")
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct ListObjectsIndexProviderState {
kind: ListObjectsIndexProviderKind,
lifecycle: ListIndexLifecycle,
persistent_path: Option<PathBuf>,
persistent_generation: Option<String>,
}
impl ListObjectsIndexProviderState {
fn walker_key_only() -> Self {
let mut lifecycle = ListIndexLifecycle::disabled(0);
lifecycle.begin_rebuild(LIST_CURSOR_GENERATION_LIVE, 0);
lifecycle.checkpoint_rebuild(0);
let _ = lifecycle.publish_rebuild();
Self {
kind: ListObjectsIndexProviderKind::WalkerKeyOnly,
lifecycle,
persistent_path: None,
persistent_generation: None,
}
}
fn persistent_key_only(path: Option<PathBuf>, generation: Option<String>) -> Self {
let mut lifecycle = ListIndexLifecycle::disabled(0);
if path.as_ref().is_some_and(|path| !path.as_os_str().is_empty()) {
lifecycle.begin_rebuild(
generation
.as_deref()
.unwrap_or(LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY_DEFAULT_GENERATION),
0,
);
} else {
lifecycle.mark_degraded();
}
Self {
kind: ListObjectsIndexProviderKind::PersistentKeyOnly,
lifecycle,
persistent_path: path,
persistent_generation: generation,
}
}
fn health_snapshot(&self) -> ListIndexHealthSnapshot {
self.lifecycle.health_snapshot()
}
}
#[derive(Debug, Clone)]
struct PersistentKeyOnlyIndexCache {
path: PathBuf,
len: u64,
modified: Option<SystemTime>,
index: Arc<PersistentKeyOnlyIndex>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct PersistentKeyOnlyIndex {
format_version: u8,
bucket: Option<String>,
generation: String,
checkpoint_high_water_mark: u64,
keys: Arc<Vec<String>>,
objects: Arc<Vec<PersistentListMetadataObject>>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct PersistentListMetadataObject {
name: String,
size: i64,
mod_time: Option<time::OffsetDateTime>,
etag: Option<String>,
storage_class: Option<String>,
}
impl PersistentListMetadataObject {
fn from_object_info(object: &ObjectInfo) -> Self {
Self {
name: object.name.clone(),
size: object.size,
mod_time: object.mod_time,
etag: object.etag.clone(),
storage_class: object.storage_class.clone(),
}
}
fn to_object_info(&self, bucket: &str) -> ObjectInfo {
ObjectInfo {
bucket: bucket.to_owned(),
name: self.name.clone(),
size: self.size,
mod_time: self.mod_time,
etag: self.etag.clone(),
storage_class: self.storage_class.clone(),
is_latest: true,
..Default::default()
}
}
}
static PERSISTENT_KEY_ONLY_INDEX_CACHE: OnceCell<RwLock<Option<PersistentKeyOnlyIndexCache>>> = OnceCell::const_new();
static LIST_OBJECTS_NAMESPACE_JOURNAL_LOCK: OnceCell<RwLock<()>> = OnceCell::const_new();
static LIST_OBJECTS_MUTATION_SEQUENCE: AtomicU64 = AtomicU64::new(0);
static SCANNER_NAMESPACE_MUTATION_GENERATION: AtomicU64 = AtomicU64::new(0);
static LIST_OBJECTS_BUCKET_MUTATION_SEQUENCE: OnceCell<RwLock<HashMap<String, u64>>> = OnceCell::const_new();
static LIST_OBJECTS_NAMESPACE_JOURNAL_DEGRADED_BUCKETS: OnceCell<RwLock<HashSet<String>>> = OnceCell::const_new();
#[cfg(any(test, feature = "list-chaos"))]
static LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_CONFIG: OnceCell<Option<NamespaceMutationJournalChaosConfig>> = OnceCell::const_new();
#[cfg(any(test, feature = "list-chaos"))]
static LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_APPLIED: OnceCell<RwLock<HashSet<String>>> = OnceCell::const_new();
async fn persistent_key_only_index_cache() -> &'static RwLock<Option<PersistentKeyOnlyIndexCache>> {
PERSISTENT_KEY_ONLY_INDEX_CACHE
.get_or_init(|| async { RwLock::new(None) })
.await
}
async fn list_objects_namespace_journal_lock() -> &'static RwLock<()> {
LIST_OBJECTS_NAMESPACE_JOURNAL_LOCK
.get_or_init(|| async { RwLock::new(()) })
.await
}
async fn list_objects_bucket_mutation_sequence() -> &'static RwLock<HashMap<String, u64>> {
LIST_OBJECTS_BUCKET_MUTATION_SEQUENCE
.get_or_init(|| async { RwLock::new(HashMap::new()) })
.await
}
async fn list_objects_namespace_journal_degraded_buckets() -> &'static RwLock<HashSet<String>> {
LIST_OBJECTS_NAMESPACE_JOURNAL_DEGRADED_BUCKETS
.get_or_init(|| async { RwLock::new(HashSet::new()) })
.await
}
#[cfg(any(test, feature = "list-chaos"))]
async fn list_objects_namespace_journal_chaos_config() -> Option<&'static NamespaceMutationJournalChaosConfig> {
LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_CONFIG
.get_or_init(|| async { namespace_mutation_journal_chaos_config_from_env() })
.await
.as_ref()
}
#[cfg(any(test, feature = "list-chaos"))]
async fn list_objects_namespace_journal_chaos_applied() -> &'static RwLock<HashSet<String>> {
LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_APPLIED
.get_or_init(|| async { RwLock::new(HashSet::new()) })
.await
}
fn advance_global_list_objects_mutation_sequence(sequence: u64) -> u64 {
let mut current = LIST_OBJECTS_MUTATION_SEQUENCE.load(Ordering::Acquire);
loop {
if current >= sequence {
return current;
}
match LIST_OBJECTS_MUTATION_SEQUENCE.compare_exchange(current, sequence, Ordering::AcqRel, Ordering::Acquire) {
Ok(_) => return sequence,
Err(observed) => current = observed,
}
}
}
async fn advance_list_objects_mutation_sequence(bucket: &str, sequence: u64) -> u64 {
let sequence = advance_global_list_objects_mutation_sequence(sequence);
let sequences = list_objects_bucket_mutation_sequence().await;
let mut sequences = sequences.write().await;
sequences
.entry(bucket.to_owned())
.and_modify(|current| *current = (*current).max(sequence))
.or_insert(sequence);
sequence
}
pub(super) fn scanner_namespace_mutation_generation() -> u64 {
SCANNER_NAMESPACE_MUTATION_GENERATION.load(Ordering::Acquire)
}
pub(crate) fn observe_scanner_namespace_mutations(bucket: &str, delta: u64) {
if bucket == RUSTFS_META_BUCKET {
return;
}
let _ = SCANNER_NAMESPACE_MUTATION_GENERATION
.try_update(Ordering::AcqRel, Ordering::Acquire, |current| Some(current.saturating_add(delta)));
}
pub(crate) async fn observe_list_objects_mutation(store: &ECStore, bucket: &str) -> u64 {
observe_list_objects_mutations(store, bucket, 1).await.unwrap_or_default()
}
pub(super) async fn observe_list_objects_mutations(store: &ECStore, bucket: &str, count: usize) -> Option<u64> {
observe_list_objects_mutations_with_store(Some(store), bucket, count).await
}
async fn observe_list_objects_mutations_with_store(store: Option<&ECStore>, bucket: &str, count: usize) -> Option<u64> {
if count == 0 {
return None;
}
let delta = u64::try_from(count).unwrap_or(u64::MAX);
observe_scanner_namespace_mutations(bucket, delta);
let next = LIST_OBJECTS_MUTATION_SEQUENCE
.fetch_add(delta, Ordering::AcqRel)
.saturating_add(delta);
let sequences = list_objects_bucket_mutation_sequence().await;
let mut sequences = sequences.write().await;
sequences
.entry(bucket.to_owned())
.and_modify(|current| *current = (*current).max(next))
.or_insert(next);
persist_observed_list_objects_mutation(store, bucket, next).await;
Some(next)
}
#[cfg(test)]
async fn current_list_objects_mutation_sequence(bucket: &str) -> u64 {
current_list_objects_mutation_snapshot(None, bucket).await.high_water_mark
}
#[cfg(test)]
async fn reset_list_objects_mutation_sequences_for_test() {
LIST_OBJECTS_MUTATION_SEQUENCE.store(0, Ordering::Release);
SCANNER_NAMESPACE_MUTATION_GENERATION.store(0, Ordering::Release);
let sequences = list_objects_bucket_mutation_sequence().await;
sequences.write().await.clear();
let degraded = list_objects_namespace_journal_degraded_buckets().await;
degraded.write().await.clear();
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum NamespaceMutationJournalStatus {
Healthy,
Degraded,
}
impl NamespaceMutationJournalStatus {
#[cfg(any(test, feature = "list-chaos"))]
fn from_env_value(value: &str) -> Option<Self> {
if value.eq_ignore_ascii_case(LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_HEALTHY) {
Some(Self::Healthy)
} else if value.eq_ignore_ascii_case(LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_DEGRADED) {
Some(Self::Degraded)
} else {
None
}
}
#[cfg(any(test, feature = "list-chaos"))]
fn env_value(self) -> &'static str {
match self {
Self::Healthy => LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_HEALTHY,
Self::Degraded => LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_DEGRADED,
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct NamespaceMutationJournalState {
bucket: Option<String>,
high_water_mark: u64,
status: NamespaceMutationJournalStatus,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct NamespaceMutationJournalSnapshot {
high_water_mark: u64,
degraded: bool,
}
#[cfg(any(test, feature = "list-chaos"))]
#[derive(Debug, Clone, PartialEq, Eq)]
struct NamespaceMutationJournalChaosConfig {
bucket: String,
status: NamespaceMutationJournalStatus,
sequence: Option<u64>,
}
#[derive(Clone)]
enum NamespaceMutationJournalBackend<'a> {
System(&'a ECStore),
LocalPath(PathBuf),
}
fn parse_namespace_mutation_journal_state(contents: &str) -> Option<NamespaceMutationJournalState> {
let mut bucket = None;
let mut high_water_mark = None;
let mut status = NamespaceMutationJournalStatus::Healthy;
for line in contents.lines() {
let line = line.trim_end_matches('\r');
if line.is_empty() || line == LIST_OBJECTS_NAMESPACE_JOURNAL_HEADER {
continue;
}
if let Some(value) = line.strip_prefix(LIST_OBJECTS_NAMESPACE_JOURNAL_BUCKET_HEADER) {
if !value.is_empty() {
bucket = Some(value.to_owned());
}
continue;
}
if let Some(value) = line.strip_prefix(LIST_OBJECTS_NAMESPACE_JOURNAL_HIGH_WATER_MARK_HEADER) {
high_water_mark = value.parse::<u64>().ok();
continue;
}
if let Some(value) = line.strip_prefix(LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_HEADER) {
status = match value {
LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_HEALTHY => NamespaceMutationJournalStatus::Healthy,
LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_DEGRADED => NamespaceMutationJournalStatus::Degraded,
_ => return None,
};
}
}
high_water_mark.map(|high_water_mark| NamespaceMutationJournalState {
bucket,
high_water_mark,
status,
})
}
fn encode_namespace_mutation_journal_state(bucket: &str, sequence: u64, degraded: bool) -> String {
let mut contents = String::new();
contents.push_str(LIST_OBJECTS_NAMESPACE_JOURNAL_HEADER);
contents.push('\n');
contents.push_str(LIST_OBJECTS_NAMESPACE_JOURNAL_BUCKET_HEADER);
contents.push_str(bucket);
contents.push('\n');
contents.push_str(LIST_OBJECTS_NAMESPACE_JOURNAL_HIGH_WATER_MARK_HEADER);
contents.push_str(&sequence.to_string());
contents.push('\n');
contents.push_str(LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_HEADER);
contents.push_str(if degraded {
LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_DEGRADED
} else {
LIST_OBJECTS_NAMESPACE_JOURNAL_STATUS_HEALTHY
});
contents.push('\n');
contents
}
fn namespace_mutation_journal_path(root: &Path, bucket: &str) -> PathBuf {
root.join(format!("{bucket}.state"))
}
fn namespace_mutation_journal_system_path(bucket: &str) -> String {
format!("{LIST_OBJECTS_NAMESPACE_JOURNAL_SYSTEM_PREFIX}/{bucket}/state")
}
fn list_objects_namespace_journal_root_from_env() -> Option<PathBuf> {
std::env::var_os(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_PATH)
.map(PathBuf::from)
.filter(|path| !path.as_os_str().is_empty())
}
#[cfg(any(test, feature = "list-chaos"))]
fn namespace_mutation_journal_chaos_enabled_from_env() -> bool {
std::env::var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED)
.ok()
.is_some_and(|value| value == "1" || value.eq_ignore_ascii_case("on") || value.eq_ignore_ascii_case("true"))
}
#[cfg(any(test, feature = "list-chaos"))]
fn namespace_mutation_journal_chaos_bucket_from_env() -> Option<String> {
std::env::var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET)
.ok()
.filter(|bucket| !bucket.is_empty())
}
#[cfg(any(test, feature = "list-chaos"))]
fn namespace_mutation_journal_chaos_sequence_from_env() -> Option<u64> {
std::env::var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_SEQUENCE)
.ok()
.and_then(|value| value.parse::<u64>().ok())
}
#[cfg(any(test, feature = "list-chaos"))]
fn namespace_mutation_journal_chaos_status_from_env() -> Option<NamespaceMutationJournalStatus> {
std::env::var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS)
.ok()
.and_then(|value| NamespaceMutationJournalStatus::from_env_value(&value))
}
#[cfg(any(test, feature = "list-chaos"))]
fn namespace_mutation_journal_chaos_config_from_env() -> Option<NamespaceMutationJournalChaosConfig> {
if !namespace_mutation_journal_chaos_enabled_from_env() {
return None;
}
let Some(bucket) = namespace_mutation_journal_chaos_bucket_from_env() else {
warn!(
bucket_env = ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET,
"list objects namespace journal chaos is enabled without a target bucket; skipping injection"
);
return None;
};
let Some(status) = namespace_mutation_journal_chaos_status_from_env() else {
warn!(
status_env = ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS,
"list objects namespace journal chaos is enabled with an invalid status; skipping injection"
);
return None;
};
Some(NamespaceMutationJournalChaosConfig {
bucket,
status,
sequence: namespace_mutation_journal_chaos_sequence_from_env(),
})
}
#[cfg(any(test, feature = "list-chaos"))]
fn namespace_mutation_journal_chaos_applied_key(bucket: &str, status: NamespaceMutationJournalStatus) -> String {
let mut key = String::with_capacity(bucket.len() + 1 + status.env_value().len());
key.push_str(bucket);
key.push(':');
key.push_str(status.env_value());
key
}
#[cfg(not(any(test, feature = "list-chaos")))]
#[inline]
async fn maybe_apply_system_namespace_mutation_journal_chaos(_store: &ECStore, _bucket: &str, _default_sequence: u64) {}
#[cfg(any(test, feature = "list-chaos"))]
async fn maybe_apply_system_namespace_mutation_journal_chaos(store: &ECStore, bucket: &str, default_sequence: u64) {
let Some(config) = list_objects_namespace_journal_chaos_config().await else {
return;
};
if config.bucket != bucket {
return;
};
if list_objects_namespace_journal_root_from_env().is_some() {
warn!(
bucket = %bucket,
status = config.status.env_value(),
"list objects namespace journal chaos requires the quorum-backed system journal; skipping local journal override"
);
return;
}
let applied_key = namespace_mutation_journal_chaos_applied_key(bucket, config.status);
let applied = list_objects_namespace_journal_chaos_applied().await;
{
let applied = applied.read().await;
if applied.contains(&applied_key) {
return;
}
}
let sequence = config.sequence.unwrap_or(default_sequence);
let result = match config.status {
NamespaceMutationJournalStatus::Healthy => {
write_namespace_mutation_journal_state(NamespaceMutationJournalBackend::System(store), bucket, sequence, true)
.await
.map(|_| ())
}
NamespaceMutationJournalStatus::Degraded => {
write_namespace_mutation_journal_degraded_state(NamespaceMutationJournalBackend::System(store), bucket, sequence)
.await
}
};
match result {
Ok(()) => {
applied.write().await.insert(applied_key);
warn!(
bucket = %bucket,
sequence,
status = config.status.env_value(),
"applied controlled list objects namespace journal chaos state"
);
}
Err(err) => {
warn!(
bucket = %bucket,
sequence,
status = config.status.env_value(),
error = %err,
"failed to apply controlled list objects namespace journal chaos state"
);
}
}
}
fn list_objects_namespace_journal_root_from_provider_path(provider_path: &Path) -> Option<PathBuf> {
provider_path
.parent()
.filter(|parent| !parent.as_os_str().is_empty())
.map(|parent| parent.join(LIST_OBJECTS_NAMESPACE_JOURNAL_DEFAULT_DIR))
}
fn list_objects_namespace_journal_backend<'a>(
store: Option<&'a ECStore>,
provider_path: Option<&Path>,
) -> Option<NamespaceMutationJournalBackend<'a>> {
if let Some(root) = list_objects_namespace_journal_root_from_env() {
return Some(NamespaceMutationJournalBackend::LocalPath(root));
}
if let Some(store) = store {
return Some(NamespaceMutationJournalBackend::System(store));
}
provider_path
.and_then(list_objects_namespace_journal_root_from_provider_path)
.map(NamespaceMutationJournalBackend::LocalPath)
}
fn list_objects_namespace_journal_write_quorum(total_disks: usize) -> usize {
(total_disks / 2) + 1
}
fn validate_namespace_mutation_journal_state(bucket: &str, contents: &str) -> Result<NamespaceMutationJournalState> {
let Some(state) = parse_namespace_mutation_journal_state(contents) else {
return Err(Error::other("list objects namespace mutation journal state is corrupt"));
};
if state
.bucket
.as_deref()
.is_some_and(|persisted_bucket| persisted_bucket != bucket)
{
return Err(Error::other("list objects namespace mutation journal bucket mismatch"));
}
Ok(state)
}
async fn system_namespace_mutation_journal_state_candidates(
store: &ECStore,
bucket: &str,
) -> Result<Vec<Option<NamespaceMutationJournalState>>> {
if store.pools.is_empty() {
return Err(Error::other("list objects namespace mutation journal has no storage pools"));
}
let path = namespace_mutation_journal_system_path(bucket);
let mut states = Vec::with_capacity(store.pools.len());
for pool in &store.pools {
let set = pool.get_disks_by_key(bucket);
let disks = set.disk_inventory().await;
let quorum = list_objects_namespace_journal_write_quorum(set.set_drive_count);
let mut successes = 0usize;
let mut pool_state: Option<NamespaceMutationJournalState> = None;
let mut futures = Vec::with_capacity(disks.len());
for disk in disks.into_iter().flatten() {
let path = path.clone();
futures.push(async move { disk.read_all(RUSTFS_META_BUCKET, &path).await });
}
for result in join_all(futures).await {
match result {
Ok(bytes) => {
successes += 1;
let contents = String::from_utf8_lossy(&bytes);
let state = validate_namespace_mutation_journal_state(bucket, contents.as_ref())?;
match pool_state.as_ref() {
Some(current)
if current.high_water_mark > state.high_water_mark
|| (current.high_water_mark == state.high_water_mark
&& current.status == NamespaceMutationJournalStatus::Degraded) => {}
_ => {
pool_state = Some(state);
}
}
}
Err(DiskError::FileNotFound) => {
successes += 1;
}
Err(err) => {
debug!(
bucket = %bucket,
path = %path,
error = %err,
"failed to read namespace mutation journal state from disk"
);
}
}
}
if successes < quorum {
return Err(Error::other("list objects namespace mutation journal read quorum was not met"));
}
states.push(pool_state);
}
Ok(states)
}
async fn load_system_namespace_mutation_journal_state(
store: &ECStore,
bucket: &str,
) -> Result<Option<NamespaceMutationJournalState>> {
let mut merged: Option<NamespaceMutationJournalState> = None;
let mut saw_state = false;
for state in system_namespace_mutation_journal_state_candidates(store, bucket).await? {
let Some(state) = state else {
continue;
};
saw_state = true;
match merged.as_ref() {
Some(current)
if current.high_water_mark > state.high_water_mark
|| (current.high_water_mark == state.high_water_mark
&& current.status == NamespaceMutationJournalStatus::Degraded) => {}
_ => merged = Some(state),
}
}
Ok(saw_state.then_some(merged).flatten())
}
async fn write_system_namespace_mutation_journal_state(
store: &ECStore,
bucket: &str,
sequence: u64,
degraded: bool,
) -> Result<()> {
if store.pools.is_empty() {
return Err(Error::other("list objects namespace mutation journal has no storage pools"));
}
let path = namespace_mutation_journal_system_path(bucket);
let contents = Bytes::from(encode_namespace_mutation_journal_state(bucket, sequence, degraded));
for pool in &store.pools {
let set = pool.get_disks_by_key(bucket);
let disks = set.disk_inventory().await;
let quorum = list_objects_namespace_journal_write_quorum(set.set_drive_count);
let mut futures = Vec::with_capacity(disks.len());
for disk in disks.into_iter().flatten() {
let path = path.clone();
let contents = contents.clone();
futures.push(async move { disk.write_all(RUSTFS_META_BUCKET, &path, contents).await });
}
let successes = join_all(futures).await.into_iter().filter(|result| result.is_ok()).count();
if successes < quorum {
return Err(Error::other("list objects namespace mutation journal write quorum was not met"));
}
}
Ok(())
}
async fn load_local_namespace_mutation_journal_state(root: &Path, bucket: &str) -> Result<Option<NamespaceMutationJournalState>> {
let journal_path = namespace_mutation_journal_path(root, bucket);
let lock = list_objects_namespace_journal_lock().await;
let _guard = lock.read().await;
let contents = match tokio::fs::read_to_string(&journal_path).await {
Ok(contents) => contents,
Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(err) => return Err(Error::Io(err)),
};
validate_namespace_mutation_journal_state(bucket, &contents).map(Some)
}
async fn load_namespace_mutation_journal_state(
backend: NamespaceMutationJournalBackend<'_>,
bucket: &str,
) -> Result<Option<NamespaceMutationJournalState>> {
match backend {
NamespaceMutationJournalBackend::System(store) => load_system_namespace_mutation_journal_state(store, bucket).await,
NamespaceMutationJournalBackend::LocalPath(root) => load_local_namespace_mutation_journal_state(&root, bucket).await,
}
}
async fn write_local_namespace_mutation_journal_state(
root: &Path,
bucket: &str,
sequence: u64,
clear_degraded: bool,
) -> Result<NamespaceMutationJournalSnapshot> {
let journal_path = namespace_mutation_journal_path(root, bucket);
let lock = list_objects_namespace_journal_lock().await;
let guard = lock.write().await;
let persisted_state = match tokio::fs::read_to_string(&journal_path).await {
Ok(contents) => {
let state = validate_namespace_mutation_journal_state(bucket, &contents)?;
Some(state)
}
Err(err) if err.kind() == std::io::ErrorKind::NotFound => None,
Err(err) => return Err(Error::Io(err)),
};
let persisted_sequence = persisted_state.as_ref().map(|state| state.high_water_mark).unwrap_or(0);
let degraded = persisted_state
.as_ref()
.is_some_and(|state| state.status == NamespaceMutationJournalStatus::Degraded)
&& !clear_degraded;
let sequence = sequence.max(persisted_sequence);
if let Some(parent) = journal_path.parent()
&& !parent.as_os_str().is_empty()
{
tokio::fs::create_dir_all(parent).await.map_err(Error::Io)?;
}
let contents = encode_namespace_mutation_journal_state(bucket, sequence, degraded);
let tmp_path = journal_path.with_extension("tmp");
tokio::fs::write(&tmp_path, contents).await.map_err(Error::Io)?;
tokio::fs::rename(&tmp_path, &journal_path).await.map_err(Error::Io)?;
drop(guard);
if clear_degraded {
let degraded = list_objects_namespace_journal_degraded_buckets().await;
degraded.write().await.remove(bucket);
}
Ok(NamespaceMutationJournalSnapshot {
high_water_mark: sequence,
degraded,
})
}
async fn write_namespace_mutation_journal_state(
backend: NamespaceMutationJournalBackend<'_>,
bucket: &str,
sequence: u64,
clear_degraded: bool,
) -> Result<NamespaceMutationJournalSnapshot> {
let persisted_state = load_namespace_mutation_journal_state(backend.clone(), bucket).await?;
let persisted_sequence = persisted_state.as_ref().map(|state| state.high_water_mark).unwrap_or(0);
let degraded = persisted_state
.as_ref()
.is_some_and(|state| state.status == NamespaceMutationJournalStatus::Degraded)
&& !clear_degraded;
let sequence = sequence.max(persisted_sequence);
match backend {
NamespaceMutationJournalBackend::System(store) => {
write_system_namespace_mutation_journal_state(store, bucket, sequence, degraded).await?;
}
NamespaceMutationJournalBackend::LocalPath(root) => {
return write_local_namespace_mutation_journal_state(&root, bucket, sequence, clear_degraded).await;
}
}
if clear_degraded {
let degraded = list_objects_namespace_journal_degraded_buckets().await;
degraded.write().await.remove(bucket);
}
Ok(NamespaceMutationJournalSnapshot {
high_water_mark: sequence,
degraded,
})
}
async fn mark_namespace_mutation_journal_degraded(store: Option<&ECStore>, bucket: &str, sequence: u64) {
let degraded = list_objects_namespace_journal_degraded_buckets().await;
degraded.write().await.insert(bucket.to_owned());
if let Some(backend) = list_objects_namespace_journal_backend(store, None)
&& let Err(err) = write_namespace_mutation_journal_degraded_state(backend, bucket, sequence).await
{
warn!(
bucket = %bucket,
sequence,
error = %err,
"failed to persist degraded namespace mutation journal state"
);
}
}
async fn write_local_namespace_mutation_journal_degraded_state(root: &Path, bucket: &str, sequence: u64) -> Result<()> {
let journal_path = namespace_mutation_journal_path(root, bucket);
let lock = list_objects_namespace_journal_lock().await;
let _guard = lock.write().await;
let persisted_sequence = match tokio::fs::read_to_string(&journal_path).await {
Ok(contents) => parse_namespace_mutation_journal_state(&contents)
.filter(|state| {
state
.bucket
.as_deref()
.is_none_or(|persisted_bucket| persisted_bucket == bucket)
})
.map(|state| state.high_water_mark)
.unwrap_or(0),
Err(err) if err.kind() == std::io::ErrorKind::NotFound => 0,
Err(err) => return Err(Error::Io(err)),
};
let sequence = sequence.max(persisted_sequence);
if let Some(parent) = journal_path.parent()
&& !parent.as_os_str().is_empty()
{
tokio::fs::create_dir_all(parent).await.map_err(Error::Io)?;
}
let contents = encode_namespace_mutation_journal_state(bucket, sequence, true);
let tmp_path = journal_path.with_extension("tmp");
tokio::fs::write(&tmp_path, contents).await.map_err(Error::Io)?;
tokio::fs::rename(&tmp_path, &journal_path).await.map_err(Error::Io)?;
Ok(())
}
async fn write_namespace_mutation_journal_degraded_state(
backend: NamespaceMutationJournalBackend<'_>,
bucket: &str,
sequence: u64,
) -> Result<()> {
let persisted_state = load_namespace_mutation_journal_state(backend.clone(), bucket).await?;
let sequence = sequence.max(persisted_state.map(|state| state.high_water_mark).unwrap_or(0));
match backend {
NamespaceMutationJournalBackend::System(store) => {
write_system_namespace_mutation_journal_state(store, bucket, sequence, true).await
}
NamespaceMutationJournalBackend::LocalPath(root) => {
write_local_namespace_mutation_journal_degraded_state(&root, bucket, sequence).await
}
}
}
async fn current_list_objects_mutation_snapshot(store: Option<&ECStore>, bucket: &str) -> NamespaceMutationJournalSnapshot {
let sequences = list_objects_bucket_mutation_sequence().await;
let in_memory_sequence = {
let sequences = sequences.read().await;
sequences.get(bucket).copied().unwrap_or(0)
};
let degraded = list_objects_namespace_journal_degraded_buckets().await;
let in_memory_degraded = {
let degraded = degraded.read().await;
degraded.contains(bucket)
};
let Some(backend) = list_objects_namespace_journal_backend(store, None) else {
return NamespaceMutationJournalSnapshot {
high_water_mark: in_memory_sequence,
degraded: in_memory_degraded,
};
};
match load_namespace_mutation_journal_state(backend, bucket).await {
Ok(Some(state)) => {
advance_list_objects_mutation_sequence(bucket, state.high_water_mark).await;
NamespaceMutationJournalSnapshot {
high_water_mark: in_memory_sequence.max(state.high_water_mark),
degraded: in_memory_degraded || state.status == NamespaceMutationJournalStatus::Degraded,
}
}
Ok(None) => NamespaceMutationJournalSnapshot {
high_water_mark: in_memory_sequence,
degraded: in_memory_degraded,
},
Err(err) => {
warn!(
bucket = %bucket,
error = %err,
"list objects namespace mutation journal could not be loaded; falling back to walker"
);
let degraded = list_objects_namespace_journal_degraded_buckets().await;
degraded.write().await.insert(bucket.to_owned());
NamespaceMutationJournalSnapshot {
high_water_mark: in_memory_sequence,
degraded: true,
}
}
}
}
async fn invalidate_persistent_key_only_index(path: &Path) {
match tokio::fs::remove_file(path).await {
Ok(()) => {}
Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
Err(err) => {
warn!(
index_path = %path.display(),
error = %err,
"failed to remove persistent key-only index after mutation checkpoint persist failure"
);
}
}
let cache = persistent_key_only_index_cache().await;
let mut cached = cache.write().await;
if cached.as_ref().is_some_and(|cached| cached.path == path) {
*cached = None;
}
}
async fn persist_observed_list_objects_mutation(store: Option<&ECStore>, bucket: &str, sequence: u64) {
if is_reserved_or_invalid_bucket(bucket, false) {
return;
}
let Some(path) = list_objects_index_provider_path_from_env().filter(|_| {
matches!(
list_objects_index_provider_from_env(),
Some(ListObjectsIndexProviderKind::PersistentKeyOnly)
)
}) else {
return;
};
let Some(backend) = list_objects_namespace_journal_backend(store, Some(&path)) else {
return;
};
if let Err(err) = write_namespace_mutation_journal_state(backend, bucket, sequence, false).await {
warn!(
bucket = %bucket,
sequence,
error = %err,
"namespace mutation journal commit failed; degrading persistent key-only provider"
);
mark_namespace_mutation_journal_degraded(store, bucket, sequence).await;
invalidate_persistent_key_only_index(&path).await;
}
}
fn encode_persistent_list_metadata_string(value: &str) -> String {
BASE64_STANDARD.encode_to_string(value.as_bytes())
}
fn decode_persistent_list_metadata_string(value: &str) -> Option<String> {
let bytes = BASE64_STANDARD.decode_to_vec(value).ok()?;
String::from_utf8(bytes).ok()
}
fn encode_optional_persistent_list_metadata_string(value: Option<&str>) -> String {
value
.map(encode_persistent_list_metadata_string)
.unwrap_or_else(|| "-".to_owned())
}
fn decode_optional_persistent_list_metadata_string(value: &str) -> Option<Option<String>> {
if value == "-" {
Some(None)
} else {
decode_persistent_list_metadata_string(value).map(Some)
}
}
fn encode_persistent_list_metadata_object(object: &PersistentListMetadataObject) -> String {
let mut line = String::new();
line.push_str(PERSISTENT_KEY_ONLY_INDEX_OBJECT_PREFIX);
line.push_str(&encode_persistent_list_metadata_string(&object.name));
line.push('\t');
line.push_str(&object.size.to_string());
line.push('\t');
line.push_str(
&object
.mod_time
.map(|mod_time| mod_time.unix_timestamp_nanos().to_string())
.unwrap_or_else(|| "-".to_owned()),
);
line.push('\t');
line.push_str(&encode_optional_persistent_list_metadata_string(object.etag.as_deref()));
line.push('\t');
line.push_str(&encode_optional_persistent_list_metadata_string(object.storage_class.as_deref()));
line
}
fn parse_persistent_list_metadata_object(line: &str) -> Option<PersistentListMetadataObject> {
let value = line.strip_prefix(PERSISTENT_KEY_ONLY_INDEX_OBJECT_PREFIX)?;
let mut fields = value.split('\t');
let name = decode_persistent_list_metadata_string(fields.next()?)?;
let size = fields.next()?.parse::<i64>().ok()?;
let mod_time = match fields.next()? {
"-" => None,
value => Some(time::OffsetDateTime::from_unix_timestamp_nanos(value.parse::<i128>().ok()?).ok()?),
};
let etag = decode_optional_persistent_list_metadata_string(fields.next()?)?;
let storage_class = decode_optional_persistent_list_metadata_string(fields.next()?)?;
if fields.next().is_some() {
return None;
}
Some(PersistentListMetadataObject {
name,
size,
mod_time,
etag,
storage_class,
})
}
fn parse_persistent_key_only_index(contents: &str) -> PersistentKeyOnlyIndex {
let mut format_version = 0;
let mut bucket = None;
let mut generation = None;
let mut checkpoint_high_water_mark = None;
let mut keys = Vec::new();
let mut objects = Vec::new();
for line in contents.lines() {
let line = line.trim_end_matches('\r');
if line.is_empty() {
continue;
}
if line == PERSISTENT_KEY_ONLY_INDEX_HEADER {
format_version = PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION;
continue;
}
if let Some(object) = parse_persistent_list_metadata_object(line) {
keys.push(object.name.clone());
objects.push(object);
continue;
}
if let Some(value) = line.strip_prefix(PERSISTENT_KEY_ONLY_INDEX_BUCKET_HEADER) {
if !value.is_empty() {
bucket = Some(value.to_owned());
}
continue;
}
if let Some(value) = line.strip_prefix(PERSISTENT_KEY_ONLY_INDEX_GENERATION_HEADER) {
if is_valid_list_objects_index_generation(value) {
generation = Some(value.to_owned());
}
continue;
}
if let Some(value) = line.strip_prefix(PERSISTENT_KEY_ONLY_INDEX_CHECKPOINT_HEADER) {
checkpoint_high_water_mark = value.parse::<u64>().ok();
continue;
}
if line.starts_with('#') {
continue;
}
keys.push(line.to_owned());
}
keys.sort_unstable();
keys.dedup();
objects.sort_unstable_by(|left, right| left.name.cmp(&right.name));
objects.dedup_by(|left, right| left.name == right.name);
let checkpoint_high_water_mark = checkpoint_high_water_mark.unwrap_or_else(|| u64::try_from(keys.len()).unwrap_or(u64::MAX));
PersistentKeyOnlyIndex {
format_version,
bucket,
generation: generation.unwrap_or_else(|| LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY_DEFAULT_GENERATION.to_owned()),
checkpoint_high_water_mark,
keys: Arc::new(keys),
objects: Arc::new(objects),
}
}
fn persistent_key_only_index_health(
index: &PersistentKeyOnlyIndex,
mutation_snapshot: NamespaceMutationJournalSnapshot,
) -> ListIndexHealthSnapshot {
let mut lifecycle = ListIndexLifecycle::disabled(0);
let mutation_high_water_mark = mutation_snapshot.high_water_mark.max(index.checkpoint_high_water_mark);
lifecycle.begin_rebuild(&index.generation, mutation_high_water_mark);
lifecycle.checkpoint_rebuild(index.checkpoint_high_water_mark);
let _ = lifecycle.publish_rebuild();
if mutation_snapshot.degraded {
lifecycle.mark_degraded();
return lifecycle.health_snapshot();
}
lifecycle.observe_mutation_high_water_mark(mutation_high_water_mark);
lifecycle.health_snapshot()
}
fn persistent_key_only_index_matches_provider(
index: &PersistentKeyOnlyIndex,
bucket: &str,
provider_state: &ListObjectsIndexProviderState,
) -> bool {
if index.format_version != PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION {
return false;
}
if index.bucket.as_deref().is_some_and(|index_bucket| index_bucket != bucket) {
return false;
}
provider_state
.persistent_generation
.as_deref()
.is_none_or(|generation| index.generation == generation)
}
fn persistent_key_only_index_has_complete_metadata_snapshot(index: &PersistentKeyOnlyIndex) -> bool {
index.keys.len() == index.objects.len()
&& index
.keys
.iter()
.zip(index.objects.iter())
.all(|(key, object)| key == &object.name)
}
fn generated_persistent_key_only_generation(configured: Option<&str>) -> String {
if let Some(configured) = configured
&& is_valid_list_objects_index_generation(configured)
{
return configured.to_owned();
}
let millis = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map(|duration| duration.as_millis())
.unwrap_or(0);
format!("{LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY_DEFAULT_GENERATION}-{millis}")
}
async fn write_persistent_key_only_index_with_metadata(
store: Option<&ECStore>,
path: &Path,
bucket: &str,
generation: &str,
checkpoint_high_water_mark: u64,
keys: &[String],
objects: &[PersistentListMetadataObject],
) -> Result<PersistentKeyOnlyIndex> {
if let Some(parent) = path.parent()
&& !parent.as_os_str().is_empty()
{
tokio::fs::create_dir_all(parent).await.map_err(Error::Io)?;
}
let mut keys = keys.to_vec();
keys.sort_unstable();
keys.dedup();
let mut objects = objects.to_vec();
objects.sort_unstable_by(|left, right| left.name.cmp(&right.name));
objects.dedup_by(|left, right| left.name == right.name);
let mut contents = String::new();
contents.push_str(PERSISTENT_KEY_ONLY_INDEX_HEADER);
contents.push('\n');
contents.push_str(PERSISTENT_KEY_ONLY_INDEX_BUCKET_HEADER);
contents.push_str(bucket);
contents.push('\n');
contents.push_str(PERSISTENT_KEY_ONLY_INDEX_GENERATION_HEADER);
contents.push_str(generation);
contents.push('\n');
contents.push_str(PERSISTENT_KEY_ONLY_INDEX_CHECKPOINT_HEADER);
contents.push_str(&checkpoint_high_water_mark.to_string());
contents.push('\n');
for key in &keys {
contents.push_str(key);
contents.push('\n');
}
for object in &objects {
contents.push_str(&encode_persistent_list_metadata_object(object));
contents.push('\n');
}
let Some(journal_backend) = list_objects_namespace_journal_backend(store, Some(path)) else {
return Err(Error::other("list objects namespace mutation journal path is not configured"));
};
let tmp_path = path.with_extension("tmp");
tokio::fs::write(&tmp_path, contents).await.map_err(Error::Io)?;
write_namespace_mutation_journal_state(journal_backend, bucket, checkpoint_high_water_mark, true).await?;
tokio::fs::rename(&tmp_path, path).await.map_err(Error::Io)?;
Ok(PersistentKeyOnlyIndex {
format_version: PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION,
bucket: Some(bucket.to_owned()),
generation: generation.to_owned(),
checkpoint_high_water_mark,
keys: Arc::new(keys),
objects: Arc::new(objects),
})
}
async fn load_persistent_key_only_index(store: Option<&ECStore>, path: &Path) -> Result<Arc<PersistentKeyOnlyIndex>> {
let metadata = tokio::fs::metadata(path).await.map_err(Error::Io)?;
let len = metadata.len();
let modified = metadata.modified().ok();
let cache = persistent_key_only_index_cache().await;
{
let cached = cache.read().await;
if let Some(cached) = cached.as_ref()
&& cached.path == path
&& cached.len == len
&& cached.modified == modified
{
return Ok(cached.index.clone());
}
}
let contents = tokio::fs::read_to_string(path).await.map_err(Error::Io)?;
let index = Arc::new(parse_persistent_key_only_index(&contents));
if let Some(bucket) = index.bucket.as_deref() {
let restored_sequence = match list_objects_namespace_journal_backend(store, Some(path)) {
Some(journal_backend) => load_namespace_mutation_journal_state(journal_backend, bucket)
.await?
.map(|state| state.high_water_mark)
.unwrap_or(index.checkpoint_high_water_mark)
.max(index.checkpoint_high_water_mark),
None => index.checkpoint_high_water_mark,
};
advance_list_objects_mutation_sequence(bucket, restored_sequence).await;
}
let mut cached = cache.write().await;
*cached = Some(PersistentKeyOnlyIndexCache {
path: path.to_path_buf(),
len,
modified,
index: index.clone(),
});
Ok(index)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ListIndexSourceDecision {
UseIndex(ListSourceMode),
FallbackToWalker(ListIndexFallbackReason),
}
trait ListMetadataIndexHealth {
fn fallback_reason(&self) -> Option<ListIndexFallbackReason>;
}
fn select_list_index_provider_source_mode(
opts: &ListPathOptions,
requested: ListSourceMode,
health: &ListIndexHealthSnapshot,
) -> ListIndexSourceDecision {
let mut parsed_opts = opts.clone();
parsed_opts.parse_marker();
if parsed_opts
.cursor_source
.is_some_and(|source| source != requested && source != ListSourceMode::Walker)
{
return ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::UnsupportedRequest);
}
if let Some(cursor_generation) = parsed_opts.cursor_generation.as_deref()
&& health
.active_generation
.as_deref()
.is_some_and(|active_generation| cursor_generation != active_generation)
{
return ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::GenerationMismatch);
}
select_list_index_source_mode(Some(requested), health.active_generation.as_deref(), health)
}
fn select_list_index_source_mode(
requested: Option<ListSourceMode>,
generation: Option<&str>,
health: &dyn ListMetadataIndexHealth,
) -> ListIndexSourceDecision {
let Some(mode) = requested else {
return ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::Disabled);
};
if mode == ListSourceMode::Walker {
return ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::Disabled);
}
if generation.is_none_or(str::is_empty) {
return ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::MissingGeneration);
}
if let Some(reason) = health.fallback_reason() {
return ListIndexSourceDecision::FallbackToWalker(reason);
}
ListIndexSourceDecision::UseIndex(mode)
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum ListIndexLifecycleState {
Disabled,
Rebuilding,
Healthy,
Lagging,
Degraded,
}
impl ListIndexLifecycleState {
fn fallback_reason(self) -> Option<ListIndexFallbackReason> {
match self {
Self::Disabled => Some(ListIndexFallbackReason::Disabled),
Self::Rebuilding => Some(ListIndexFallbackReason::Rebuilding),
Self::Healthy => None,
Self::Lagging => Some(ListIndexFallbackReason::Lagging),
Self::Degraded => Some(ListIndexFallbackReason::Degraded),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct ListIndexHealthSnapshot {
state: ListIndexLifecycleState,
active_generation: Option<String>,
staging_generation: Option<String>,
checkpoint_high_water_mark: u64,
mutation_high_water_mark: u64,
mutation_lag: u64,
fallback_reason: Option<ListIndexFallbackReason>,
}
impl ListMetadataIndexHealth for ListIndexHealthSnapshot {
fn fallback_reason(&self) -> Option<ListIndexFallbackReason> {
self.fallback_reason
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct ListIndexLifecycle {
state: ListIndexLifecycleState,
active_generation: Option<String>,
staging_generation: Option<String>,
checkpoint_high_water_mark: u64,
mutation_high_water_mark: u64,
max_allowed_lag: u64,
}
impl ListIndexLifecycle {
fn disabled(max_allowed_lag: u64) -> Self {
Self {
state: ListIndexLifecycleState::Disabled,
active_generation: None,
staging_generation: None,
checkpoint_high_water_mark: 0,
mutation_high_water_mark: 0,
max_allowed_lag,
}
}
fn begin_rebuild(&mut self, generation: impl Into<String>, current_high_water_mark: u64) {
self.state = ListIndexLifecycleState::Rebuilding;
self.staging_generation = Some(generation.into());
self.mutation_high_water_mark = current_high_water_mark;
}
fn checkpoint_rebuild(&mut self, checkpoint_high_water_mark: u64) {
if self.state == ListIndexLifecycleState::Rebuilding && self.staging_generation.is_some() {
self.checkpoint_high_water_mark = checkpoint_high_water_mark;
}
}
fn publish_rebuild(&mut self) -> bool {
let Some(generation) = self.staging_generation.take() else {
return false;
};
self.active_generation = Some(generation);
self.state = ListIndexLifecycleState::Healthy;
self.mutation_high_water_mark = self.checkpoint_high_water_mark;
true
}
fn observe_mutation_high_water_mark(&mut self, mutation_high_water_mark: u64) {
self.mutation_high_water_mark = self.mutation_high_water_mark.max(mutation_high_water_mark);
if matches!(self.state, ListIndexLifecycleState::Healthy | ListIndexLifecycleState::Lagging)
&& self.mutation_lag() > self.max_allowed_lag
{
self.state = ListIndexLifecycleState::Lagging;
}
}
fn mark_degraded(&mut self) {
self.state = ListIndexLifecycleState::Degraded;
}
fn mutation_lag(&self) -> u64 {
self.mutation_high_water_mark.saturating_sub(self.checkpoint_high_water_mark)
}
fn health_snapshot(&self) -> ListIndexHealthSnapshot {
ListIndexHealthSnapshot {
state: self.state,
active_generation: self.active_generation.clone(),
staging_generation: self.staging_generation.clone(),
checkpoint_high_water_mark: self.checkpoint_high_water_mark,
mutation_high_water_mark: self.mutation_high_water_mark,
mutation_lag: self.mutation_lag(),
fallback_reason: self.state.fallback_reason(),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct ListContinuationV2 {
version: &'static str,
id: Option<String>,
pool_idx: Option<usize>,
set_idx: Option<usize>,
source: Option<ListSourceMode>,
generation: Option<String>,
}
impl ListContinuationV2 {
fn encode_marker(&self, marker: &str) -> String {
let mut marker_tag = String::with_capacity(marker.len() + 64);
marker_tag.push_str(marker);
marker_tag.push_str(LIST_CACHE_MARKER_PREFIX);
marker_tag.push_str(self.version);
match &self.id {
Some(id) => {
marker_tag.push_str(",id:");
marker_tag.push_str(id);
}
None => marker_tag.push_str(",return:"),
}
if let Some(pool_idx) = self.pool_idx {
marker_tag.push_str(",p:");
marker_tag.push_str(&pool_idx.to_string());
}
if let Some(set_idx) = self.set_idx {
marker_tag.push_str(",s:");
marker_tag.push_str(&set_idx.to_string());
}
if let Some(source) = &self.source {
marker_tag.push_str(",src:");
marker_tag.push_str(source.cursor_value());
}
if let Some(generation) = &self.generation {
marker_tag.push_str(",gen:");
marker_tag.push_str(generation);
}
marker_tag.push(']');
marker_tag
}
fn parse(marker_tag: &str) -> Option<(Self, bool)> {
let mut parsed = Self {
version: MARKER_TAG_VERSION,
id: None,
pool_idx: None,
set_idx: None,
source: None,
generation: None,
};
let mut has_list_cache = false;
let mut should_create = false;
for tag in marker_tag.split(',') {
let Some((key, value)) = tag.split_once(':') else {
continue;
};
match key {
"rustfs_cache" => {
match value {
"v1" => parsed.version = "v1",
MARKER_TAG_VERSION => parsed.version = MARKER_TAG_VERSION,
_ => return None,
}
has_list_cache = true;
}
"id" => {
parsed.id = Some(value.to_owned());
}
"return" => {
parsed.id = Some(Uuid::new_v4().to_string());
should_create = true;
}
"p" => match value.parse::<usize>() {
Ok(res) => parsed.pool_idx = Some(res),
Err(_) => {
parsed.id = Some(Uuid::new_v4().to_string());
should_create = true;
}
},
"s" => match value.parse::<usize>() {
Ok(res) => parsed.set_idx = Some(res),
Err(_) => {
parsed.id = Some(Uuid::new_v4().to_string());
should_create = true;
}
},
"src" => {
parsed.source = Some(ListSourceMode::from_cursor_value(value)?);
}
"gen" => {
if value.is_empty() {
return None;
}
parsed.generation = Some(value.to_owned());
}
_ => (),
}
}
if has_list_cache && LEGACY_MARKER_TAG_VERSIONS.contains(&parsed.version) {
Some((parsed, should_create))
} else {
None
}
}
}
pub(crate) fn list_marker_key(marker: &str) -> &str {
marker
.rfind(LIST_CACHE_MARKER_PREFIX)
.filter(|start_idx| marker[*start_idx..].ends_with(']'))
.map_or(marker, |start_idx| &marker[..start_idx])
}
fn normalize_list_quorum(value: &str) -> &'static str {
let value = value.trim();
if value.eq_ignore_ascii_case("disk") {
"disk"
} else if value.eq_ignore_ascii_case("reduced") {
"reduced"
} else if value.eq_ignore_ascii_case("optimal") {
"optimal"
} else if value.eq_ignore_ascii_case("auto") {
"auto"
} else {
DEFAULT_API_LIST_QUORUM
}
}
fn list_objects_quorum_from_env() -> String {
let value = rustfs_utils::get_env_str(ENV_API_LIST_OBJECTS_QUORUM, DEFAULT_API_LIST_OBJECTS_QUORUM);
normalize_list_quorum(&value).to_owned()
}
fn list_objects_index_mode_from_env() -> Option<ListSourceMode> {
let value = rustfs_utils::get_env_str(ENV_API_LIST_OBJECTS_INDEX_MODE, "");
let value = value.trim();
if value.eq_ignore_ascii_case(LIST_CURSOR_SOURCE_INDEX_KEY_ONLY) || value.eq_ignore_ascii_case("key_only") {
Some(ListSourceMode::IndexKeyOnly)
} else if value.eq_ignore_ascii_case(LIST_CURSOR_SOURCE_INDEX_VERIFIED_PAGE) || value.eq_ignore_ascii_case("verified_page") {
Some(ListSourceMode::IndexVerifiedPage)
} else if value.eq_ignore_ascii_case(LIST_CURSOR_SOURCE_INDEX_METADATA_FAST) || value.eq_ignore_ascii_case("metadata_fast") {
Some(ListSourceMode::IndexMetadataFast)
} else {
None
}
}
fn list_objects_metadata_fast_guardrails_from_env() -> Option<u64> {
let enabled = rustfs_utils::get_env_str(ENV_API_LIST_OBJECTS_METADATA_FAST_ENABLED, "");
let enabled = enabled.trim();
if !(enabled == "1"
|| enabled.eq_ignore_ascii_case("true")
|| enabled.eq_ignore_ascii_case("yes")
|| enabled.eq_ignore_ascii_case("on"))
{
return None;
}
let staleness = rustfs_utils::get_env_str(ENV_API_LIST_OBJECTS_METADATA_FAST_STALENESS_MS, "");
let staleness_ms = staleness.trim().parse::<u64>().ok()?;
(1..=MAX_LIST_OBJECTS_METADATA_FAST_STALENESS_MS)
.contains(&staleness_ms)
.then_some(staleness_ms)
}
fn list_objects_index_provider_from_env() -> Option<ListObjectsIndexProviderKind> {
let value = rustfs_utils::get_env_str(ENV_API_LIST_OBJECTS_INDEX_PROVIDER, "");
let value = value.trim();
if value.eq_ignore_ascii_case(LIST_OBJECTS_INDEX_PROVIDER_WALKER_KEY_ONLY) {
Some(ListObjectsIndexProviderKind::WalkerKeyOnly)
} else if value.eq_ignore_ascii_case(LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY)
|| value.eq_ignore_ascii_case("persisted_key_only")
{
Some(ListObjectsIndexProviderKind::PersistentKeyOnly)
} else {
None
}
}
fn list_objects_index_provider_path_from_env() -> Option<PathBuf> {
let value = rustfs_utils::get_env_str(ENV_API_LIST_OBJECTS_INDEX_PROVIDER_PATH, "");
let value = value.trim();
if value.is_empty() { None } else { Some(PathBuf::from(value)) }
}
fn is_valid_list_objects_index_generation(value: &str) -> bool {
let value = value.trim();
!value.is_empty() && !value.contains([',', ':', '[', ']'])
}
fn list_objects_index_provider_generation_from_env() -> Option<String> {
let value = rustfs_utils::get_env_str(ENV_API_LIST_OBJECTS_INDEX_PROVIDER_GENERATION, "");
let value = value.trim();
is_valid_list_objects_index_generation(value).then(|| value.to_owned())
}
fn list_objects_index_provider_state_from_env() -> Option<ListObjectsIndexProviderState> {
list_objects_index_provider_from_env().map(|kind| match kind {
ListObjectsIndexProviderKind::WalkerKeyOnly => ListObjectsIndexProviderState::walker_key_only(),
ListObjectsIndexProviderKind::PersistentKeyOnly => ListObjectsIndexProviderState::persistent_key_only(
list_objects_index_provider_path_from_env(),
list_objects_index_provider_generation_from_env(),
),
})
}
fn record_list_objects_index_fallback(mode: ListSourceMode, reason: ListIndexFallbackReason) {
rustfs_io_metrics::record_list_objects_index_fallback(mode.cursor_value(), reason.metric_label());
}
fn append_list_cache_id_to_marker(marker: String, cache_id: Option<&str>) -> String {
let Some(id) = cache_id else {
return marker;
};
ListContinuationV2 {
version: MARKER_TAG_VERSION,
id: Some(id.to_owned()),
pool_idx: None,
set_idx: None,
source: Some(ListSourceMode::Walker),
generation: Some(LIST_CURSOR_GENERATION_LIVE.to_owned()),
}
.encode_marker(&marker)
}
fn last_scanned_entry_name(entries: Option<&MetaCacheEntriesSorted>) -> Option<String> {
entries.and_then(|entries| entries.entries().last().map(|entry| entry.name.clone()))
}
fn build_list_next_marker(objects: &[ObjectInfo], prefixes: &[String], cache_id: Option<&str>) -> Option<String> {
if let Some(last) = objects.last() {
Some(append_list_cache_id_to_marker(last.name.clone(), cache_id))
} else {
prefixes
.last()
.map(|marker| append_list_cache_id_to_marker(marker.clone(), cache_id))
}
}
fn build_list_versions_next_marker(
objects: &[ObjectInfo],
prefixes: &[String],
cache_id: Option<&str>,
) -> (Option<String>, Option<String>) {
if let Some(last) = objects.last() {
let version_marker = if last.is_dir && last.mod_time.is_none() {
None
} else {
Some(
last.version_id
.filter(|v| !v.is_nil())
.map(|v| v.to_string())
.unwrap_or_else(|| "null".to_string()),
)
};
(Some(append_list_cache_id_to_marker(last.name.clone(), cache_id)), version_marker)
} else if let Some(last_prefix) = prefixes.last() {
(Some(append_list_cache_id_to_marker(last_prefix.clone(), cache_id)), None)
} else {
(None, None)
}
}
fn list_objects_paginate(
get_objects: Vec<ObjectInfo>,
delimiter: &Option<String>,
max_keys: i32,
disk_has_more: bool,
cache_id: Option<&str>,
include_version_id: bool,
last_scanned_key: Option<&str>,
) -> (Vec<ObjectInfo>, Vec<String>, bool, Option<String>, Option<String>) {
let mut get_objects = get_objects;
let mut is_truncated = false;
let mut next_marker = None;
let mut next_version_idmarker = None;
if max_keys <= 0 {
get_objects.clear();
} else if get_objects.len() > max_keys as usize {
is_truncated = true;
get_objects.truncate(max_keys as usize);
}
if is_truncated {
if include_version_id {
(next_marker, next_version_idmarker) = build_list_versions_next_marker(&get_objects, &[], cache_id);
} else {
next_marker = build_list_next_marker(&get_objects, &[], cache_id);
}
}
let mut prefixes: Vec<String> = Vec::new();
let mut prefix_set: HashSet<String> = HashSet::new();
let mut objects = Vec::with_capacity(get_objects.len());
for obj in get_objects {
if delimiter.is_some() {
if obj.is_dir && obj.mod_time.is_none() {
if prefix_set.insert(obj.name.clone()) {
prefixes.push(obj.name);
}
} else {
objects.push(obj);
}
} else {
objects.push(obj);
}
}
if !is_truncated && disk_has_more && !include_version_id {
let visible_count = objects.len() + prefixes.len();
let should_truncate = if delimiter.is_none() {
visible_count > 0
} else {
visible_count >= max_keys as usize
};
if should_truncate {
is_truncated = true;
if include_version_id {
(next_marker, next_version_idmarker) = build_list_versions_next_marker(&objects, &prefixes, cache_id);
} else {
next_marker = build_list_next_marker(&objects, &prefixes, cache_id);
}
} else if delimiter.is_some()
&& let Some(last_scanned) = last_scanned_key
{
is_truncated = true;
next_marker = Some(append_list_cache_id_to_marker(last_scanned.to_owned(), cache_id));
}
}
(objects, prefixes, is_truncated, next_marker, next_version_idmarker)
}
enum VerifiedIndexVisibleEntry {
Object(Box<ObjectInfo>),
Prefix(String),
}
impl VerifiedIndexVisibleEntry {
fn marker(&self) -> &str {
match self {
Self::Object(object) => &object.name,
Self::Prefix(prefix) => prefix,
}
}
}
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
struct VerifiedIndexCandidateStats {
candidate_keys: usize,
skipped_keys: usize,
common_prefixes: usize,
live_verify_attempts: usize,
live_verify_hits: usize,
live_verify_misses: usize,
}
struct VerifiedIndexCandidateResult {
info: ListObjectsInfo,
stats: VerifiedIndexCandidateStats,
}
#[cfg(test)]
async fn list_objects_from_verified_index_candidates<F, Fut>(
prefix: &str,
marker: Option<&str>,
delimiter: &Option<String>,
max_keys: i32,
candidate_keys: &[String],
live_verify: F,
) -> Result<ListObjectsInfo>
where
F: FnMut(String) -> Fut,
Fut: Future<Output = Result<Option<ObjectInfo>>>,
{
Ok(list_objects_from_verified_index_candidates_with_optional_stats(
prefix,
marker,
delimiter,
max_keys,
candidate_keys,
false,
live_verify,
)
.await?
.info)
}
#[cfg(test)]
async fn list_objects_from_verified_index_candidates_with_stats<F, Fut>(
prefix: &str,
marker: Option<&str>,
delimiter: &Option<String>,
max_keys: i32,
candidate_keys: &[String],
live_verify: F,
) -> Result<VerifiedIndexCandidateResult>
where
F: FnMut(String) -> Fut,
Fut: Future<Output = Result<Option<ObjectInfo>>>,
{
list_objects_from_verified_index_candidates_with_optional_stats(
prefix,
marker,
delimiter,
max_keys,
candidate_keys,
true,
live_verify,
)
.await
}
async fn list_objects_from_verified_index_candidates_with_optional_stats<F, Fut>(
prefix: &str,
marker: Option<&str>,
delimiter: &Option<String>,
max_keys: i32,
candidate_keys: &[String],
collect_stats: bool,
mut live_verify: F,
) -> Result<VerifiedIndexCandidateResult>
where
F: FnMut(String) -> Fut,
Fut: Future<Output = Result<Option<ObjectInfo>>>,
{
let max_keys = normalize_max_keys(max_keys);
let mut stats = if collect_stats {
VerifiedIndexCandidateStats {
candidate_keys: candidate_keys.len(),
..Default::default()
}
} else {
VerifiedIndexCandidateStats::default()
};
if max_keys <= 0 {
return Ok(VerifiedIndexCandidateResult {
info: ListObjectsInfo::default(),
stats,
});
}
let page_limit = usize::try_from(max_keys_plus_one(max_keys, true)).unwrap_or(usize::MAX);
let mut visible_entries = Vec::new();
let mut prefix_set = HashSet::new();
for key in candidate_keys {
if marker.is_some_and(|marker| key.as_str() <= marker) || !key.starts_with(prefix) {
if collect_stats {
stats.skipped_keys += 1;
}
continue;
}
if let Some(separator) = delimiter
&& !separator.is_empty()
{
let suffix = key.trim_start_matches(prefix);
if let Some((common_prefix, _)) = suffix.split_once(separator) {
let common_prefix = format!("{prefix}{common_prefix}{separator}");
if prefix_set.insert(common_prefix.clone()) {
if collect_stats {
stats.common_prefixes += 1;
}
visible_entries.push(VerifiedIndexVisibleEntry::Prefix(common_prefix));
}
if visible_entries.len() >= page_limit {
break;
}
continue;
}
}
if collect_stats {
stats.live_verify_attempts += 1;
}
match live_verify(key.clone()).await? {
Some(object) => {
if collect_stats {
stats.live_verify_hits += 1;
}
visible_entries.push(VerifiedIndexVisibleEntry::Object(Box::new(object)));
if visible_entries.len() >= page_limit {
break;
}
}
None => {
if collect_stats {
stats.live_verify_misses += 1;
}
}
}
}
let max_keys_len = usize::try_from(max_keys).unwrap_or(usize::MAX);
let is_truncated = visible_entries.len() > max_keys_len;
if is_truncated {
visible_entries.truncate(max_keys_len);
}
let next_marker = if is_truncated {
visible_entries.last().map(|entry| entry.marker().to_owned())
} else {
None
};
let mut objects = Vec::new();
let mut prefixes = Vec::new();
for entry in visible_entries {
match entry {
VerifiedIndexVisibleEntry::Object(object) => objects.push(*object),
VerifiedIndexVisibleEntry::Prefix(prefix) => prefixes.push(prefix),
}
}
Ok(VerifiedIndexCandidateResult {
info: ListObjectsInfo {
is_truncated,
next_marker,
objects,
prefixes,
},
stats,
})
}
fn list_objects_from_metadata_snapshot_candidates(
bucket: &str,
prefix: &str,
marker: Option<&str>,
delimiter: &Option<String>,
max_keys: i32,
candidate_objects: &[PersistentListMetadataObject],
) -> VerifiedIndexCandidateResult {
let max_keys = normalize_max_keys(max_keys);
let mut stats = VerifiedIndexCandidateStats {
candidate_keys: candidate_objects.len(),
..Default::default()
};
if max_keys <= 0 {
return VerifiedIndexCandidateResult {
info: ListObjectsInfo::default(),
stats,
};
}
let page_limit = usize::try_from(max_keys_plus_one(max_keys, true)).unwrap_or(usize::MAX);
let mut visible_entries = Vec::new();
let mut prefix_set = HashSet::new();
for object in candidate_objects {
if marker.is_some_and(|marker| object.name.as_str() <= marker) || !object.name.starts_with(prefix) {
stats.skipped_keys += 1;
continue;
}
if let Some(separator) = delimiter
&& !separator.is_empty()
{
let suffix = object.name.trim_start_matches(prefix);
if let Some((common_prefix, _)) = suffix.split_once(separator) {
let common_prefix = format!("{prefix}{common_prefix}{separator}");
if prefix_set.insert(common_prefix.clone()) {
stats.common_prefixes += 1;
visible_entries.push(VerifiedIndexVisibleEntry::Prefix(common_prefix));
}
if visible_entries.len() >= page_limit {
break;
}
continue;
}
}
visible_entries.push(VerifiedIndexVisibleEntry::Object(Box::new(object.to_object_info(bucket))));
if visible_entries.len() >= page_limit {
break;
}
}
let max_keys_len = usize::try_from(max_keys).unwrap_or(usize::MAX);
let is_truncated = visible_entries.len() > max_keys_len;
if is_truncated {
visible_entries.truncate(max_keys_len);
}
let next_marker = if is_truncated {
visible_entries.last().map(|entry| entry.marker().to_owned())
} else {
None
};
let mut objects = Vec::new();
let mut prefixes = Vec::new();
for entry in visible_entries {
match entry {
VerifiedIndexVisibleEntry::Object(object) => objects.push(*object),
VerifiedIndexVisibleEntry::Prefix(prefix) => prefixes.push(prefix),
}
}
VerifiedIndexCandidateResult {
info: ListObjectsInfo {
is_truncated,
next_marker,
objects,
prefixes,
},
stats,
}
}
fn list_metadata_resolution_params(
bucket: String,
listing_quorum: usize,
latest_object_quorum: usize,
versioned: bool,
write_quorum_slack: usize,
) -> MetadataResolutionParams {
let quorum = if versioned {
listing_quorum
} else {
latest_object_quorum.max(listing_quorum)
};
let mut resolver = MetadataResolutionParams {
dir_quorum: quorum,
obj_quorum: quorum,
bucket,
write_quorum_slack,
..Default::default()
};
if !versioned {
resolver.requested_versions = 1;
}
resolver
}
fn resolve_listing_entries(
entries: MetaCacheEntries,
resolver: MetadataResolutionParams,
enforce_write_quorum: bool,
) -> Option<MetaCacheEntry> {
if enforce_write_quorum {
entries.resolve_with_write_quorum(resolver)
} else {
entries.resolve(resolver)
}
}
enum ListingEntryResolution {
Resolved(MetaCacheEntry),
NeedsSupplement(MetaCacheEntry, Option<MetaCacheEntry>),
Rejected,
}
#[derive(Clone)]
struct FallbackListingEntry {
endpoint: String,
entry: MetaCacheEntry,
}
type FallbackListingEntries = HashMap<String, Vec<FallbackListingEntry>>;
#[derive(Clone)]
struct ListingSupplementOptions {
bucket: String,
path: String,
recursive: bool,
incl_deleted: bool,
skip_hidden_prefix_check: bool,
filter_prefix: Option<String>,
forward_to: Option<String>,
per_disk_limit: i32,
skip_total_timeout: bool,
walkdir_timeout: Option<Duration>,
walkdir_stall_timeout: Option<Duration>,
}
struct ListingReconciler {
set: SetDisks,
primary_disks: Arc<Vec<DiskStore>>,
fallback_disks: Arc<Vec<DiskStore>>,
}
impl ListingReconciler {
async fn read_after_namespace_barrier(
&self,
bucket: &str,
object: &str,
) -> std::result::Result<(MetaCacheEntries, usize), DiskError> {
let disks = self
.primary_disks
.iter()
.chain(self.fallback_disks.iter())
.cloned()
.map(Some)
.collect::<Vec<_>>();
self.set
.read_listing_metadata_after_namespace_barrier(&disks, bucket, object)
.await
.map_err(|_| DiskError::ErasureReadQuorum)
}
}
struct ListingSupplement {
options: ListingSupplementOptions,
fallback_disks: Arc<Vec<DiskStore>>,
claim_tracker: FallbackClaimTracker,
entries: Option<Arc<OnceCell<FallbackListingEntries>>>,
reconciler: Option<ListingReconciler>,
}
impl ListingSupplement {
#[cfg(test)]
fn new(
options: ListingSupplementOptions,
fallback_disks: Arc<Vec<DiskStore>>,
claim_tracker: FallbackClaimTracker,
) -> Arc<Self> {
Self::new_inner(options, fallback_disks, claim_tracker, None)
}
fn new_with_reconciler(
options: ListingSupplementOptions,
fallback_disks: Arc<Vec<DiskStore>>,
claim_tracker: FallbackClaimTracker,
set: SetDisks,
primary_disks: Arc<Vec<DiskStore>>,
) -> Arc<Self> {
let reconciler = ListingReconciler {
set,
primary_disks,
fallback_disks: fallback_disks.clone(),
};
Self::new_inner(options, fallback_disks, claim_tracker, Some(reconciler))
}
fn new_inner(
options: ListingSupplementOptions,
fallback_disks: Arc<Vec<DiskStore>>,
claim_tracker: FallbackClaimTracker,
reconciler: Option<ListingReconciler>,
) -> Arc<Self> {
let entries: Option<Arc<OnceCell<FallbackListingEntries>>> = if options.per_disk_limit > 0 {
Some(Arc::new(OnceCell::new()))
} else {
None
};
Arc::new(Self {
options,
fallback_disks,
claim_tracker,
entries,
reconciler,
})
}
fn is_empty(&self) -> bool {
self.fallback_disks.is_empty()
}
async fn reconcile_object(
&self,
object: &str,
resolver: MetadataResolutionParams,
enforce_write_quorum: bool,
) -> std::result::Result<Option<MetaCacheEntry>, DiskError> {
let Some(reconciler) = &self.reconciler else {
return Ok(None);
};
let (entries, confirmed_absent) = reconciler.read_after_namespace_barrier(&self.options.bucket, object).await?;
if let Some(entry) = resolve_listing_entries(entries, resolver.clone(), enforce_write_quorum) {
return Ok(Some(entry));
}
if confirmed_absent >= resolver.obj_quorum {
return Ok(None);
}
Err(DiskError::ErasureReadQuorum)
}
async fn entries_for(&self, object: &str) -> Vec<Option<MetaCacheEntry>> {
if self.fallback_disks.is_empty() {
return Vec::new();
}
let claimed_keys = self.claim_tracker.claimed_keys().await;
let Some(entries) = &self.entries else {
return self.read_object_entries(object, &claimed_keys).await;
};
let entries = entries.get_or_init(|| self.load_entries()).await;
let claimed_keys = self.claim_tracker.claimed_keys().await;
fallback_entries_for_object(entries, object, &claimed_keys)
}
async fn load_entries(&self) -> FallbackListingEntries {
let claimed_keys = self.claim_tracker.claimed_keys().await;
let futures = self.fallback_disks.iter().filter_map(|disk| {
let endpoint = disk.endpoint().to_string();
if claimed_keys.contains(&endpoint) {
return None;
}
Some(read_fallback_listing_disk(disk.clone(), endpoint, self.options.clone()))
});
let per_disk_entries = join_all(futures).await;
let entry_count = per_disk_entries.iter().map(Vec::len).sum();
let mut entries = FallbackListingEntries::with_capacity(entry_count);
for disk_entries in per_disk_entries {
for entry in disk_entries {
entries.entry(entry.entry.name.clone()).or_default().push(entry);
}
}
entries
}
async fn read_object_entries(&self, object: &str, claimed_keys: &HashSet<String>) -> Vec<Option<MetaCacheEntry>> {
let futures = self.fallback_disks.iter().filter_map(|disk| {
let endpoint = disk.endpoint().to_string();
if claimed_keys.contains(&endpoint) {
return None;
}
Some(read_fallback_object_disk(
disk.clone(),
endpoint,
self.options.bucket.clone(),
object.to_owned(),
))
});
let entries = join_all(futures).await;
let claimed_keys = self.claim_tracker.claimed_keys().await;
entries
.into_iter()
.flatten()
.filter(|entry| !claimed_keys.contains(&entry.endpoint))
.map(|entry| Some(entry.entry))
.collect()
}
}
fn fallback_entries_for_object(
entries: &FallbackListingEntries,
object: &str,
claimed_keys: &HashSet<String>,
) -> Vec<Option<MetaCacheEntry>> {
entries
.get(object)
.into_iter()
.flat_map(|entries| entries.iter())
.filter(|entry| !claimed_keys.contains(&entry.endpoint))
.map(|entry| Some(entry.entry.clone()))
.collect()
}
async fn read_fallback_listing_disk(
disk: DiskStore,
endpoint: String,
options: ListingSupplementOptions,
) -> Vec<FallbackListingEntry> {
let (rd, mut wr) = duplex(64);
let walk_endpoint = endpoint.clone();
let mut walk_jobs = JoinSet::new();
walk_jobs.spawn(async move {
disk.walk_dir(
WalkDirOptions {
bucket: options.bucket,
base_dir: options.path,
recursive: options.recursive,
incl_deleted: options.incl_deleted,
skip_hidden_prefix_check: options.skip_hidden_prefix_check,
report_notfound: false,
filter_prefix: options.filter_prefix,
forward_to: options.forward_to,
limit: options.per_disk_limit,
skip_total_timeout: options.skip_total_timeout,
timeout_ms: options.walkdir_timeout.map(duration_millis),
stall_timeout_ms: options.walkdir_stall_timeout.map(duration_millis),
..Default::default()
},
&mut wr,
)
.await
});
let mut reader = MetacacheReader::new(rd);
let mut entries = Vec::new();
let mut stream_ok = true;
loop {
match reader.peek().await {
Ok(Some(entry)) => {
entries.push(FallbackListingEntry {
endpoint: endpoint.clone(),
entry,
});
if let Err(err) = reader.skip(1).await {
debug!(
endpoint = %endpoint,
error = ?err,
"fallback listing supplement stream failed while advancing reader"
);
stream_ok = false;
break;
}
}
Ok(None) => break,
Err(err) if err == rustfs_filemeta::Error::Unexpected || is_io_eof(&err) => break,
Err(err) => {
debug!(
endpoint = %endpoint,
error = ?err,
"fallback listing supplement stream failed while reading entry"
);
stream_ok = false;
break;
}
}
}
drop(reader);
match walk_jobs.join_next().await {
Some(Ok(Ok(()))) if stream_ok => entries,
Some(Ok(Ok(()))) => Vec::new(),
Some(Ok(Err(err))) => {
debug!(
endpoint = %walk_endpoint,
error = ?err,
"fallback listing supplement walk_dir failed"
);
Vec::new()
}
Some(Err(err)) => {
debug!(
endpoint = %walk_endpoint,
error = ?err,
"fallback listing supplement task failed"
);
Vec::new()
}
None => Vec::new(),
}
}
async fn read_fallback_object_disk(
disk: DiskStore,
endpoint: String,
bucket: String,
object: String,
) -> Option<FallbackListingEntry> {
match disk.read_xl(&bucket, &object, false).await {
Ok(raw) if raw.buf.is_empty() => None,
Ok(raw) => Some(FallbackListingEntry {
endpoint,
entry: MetaCacheEntry {
name: object,
metadata: raw.buf,
cached: None,
reusable: false,
},
}),
Err(err) if DiskError::is_err_object_not_found(&err) || DiskError::is_err_version_not_found(&err) => None,
Err(err) => {
debug!(
endpoint = %endpoint,
bucket = %bucket,
object = %object,
error = ?err,
"fallback listing supplement read_xl failed"
);
None
}
}
}
fn version_requires_supplement(
version_required_quorum: usize,
reader_disks: usize,
selected_object_versions: usize,
requested_versions: usize,
) -> bool {
reader_disks < version_required_quorum && (requested_versions == 0 || selected_object_versions < requested_versions)
}
fn cached_entry_needs_supplement(
cached: &FileMeta,
reader_disks: usize,
resolver: &MetadataResolutionParams,
enforce_write_quorum: bool,
) -> bool {
if !enforce_write_quorum {
return false;
}
let mut selected_object_versions = 0;
for version in cached.versions.iter() {
let required_quorum = version
.write_quorum(resolver.obj_quorum)
.saturating_sub(resolver.write_quorum_slack)
.max(resolver.obj_quorum);
if version_requires_supplement(required_quorum, reader_disks, selected_object_versions, resolver.requested_versions) {
return true;
}
if !version.header.free_version() {
selected_object_versions += 1;
}
if resolver.requested_versions > 0 && selected_object_versions == resolver.requested_versions {
break;
}
}
false
}
#[derive(Debug, PartialEq, Eq)]
enum ListingSupplementTarget {
Directory(String),
Object(String),
}
impl ListingSupplementTarget {
fn name(&self) -> &str {
match self {
Self::Directory(name) | Self::Object(name) => name,
}
}
}
fn listing_entries_supplement_target(
entries: &MetaCacheEntries,
resolver: &MetadataResolutionParams,
enforce_write_quorum: bool,
) -> Option<ListingSupplementTarget> {
if !enforce_write_quorum {
return None;
}
if let Some(directory) = entries.0.iter().flatten().find(|entry| entry.is_dir()) {
let directory_copies = entries
.0
.iter()
.flatten()
.filter(|entry| entry.is_dir() && entry.name == directory.name)
.count();
if directory_copies < resolver.dir_quorum {
return Some(ListingSupplementTarget::Directory(directory.name.clone()));
}
}
for (idx, entry) in entries.0.iter().enumerate() {
let Some(entry) = entry.as_ref().filter(|entry| entry.is_object()) else {
continue;
};
if entries.0[..idx]
.iter()
.flatten()
.any(|previous| previous.name == entry.name && previous.is_object())
{
continue;
}
let reader_disks = entries
.0
.iter()
.filter(|candidate| {
candidate
.as_ref()
.is_some_and(|candidate| candidate.name == entry.name && candidate.is_object())
})
.count();
let entries_disagree = entries.0.iter().flatten().any(|candidate| {
candidate.name == entry.name && candidate.is_object() && !entry.matches(Some(candidate), resolver.strict).1
});
if entries_disagree {
return Some(ListingSupplementTarget::Object(entry.name.clone()));
}
let mut entry = entry.clone();
if let Ok(cached) = entry.xl_meta()
&& cached_entry_needs_supplement(&cached, reader_disks, resolver, enforce_write_quorum)
{
return Some(ListingSupplementTarget::Object(entry.name));
}
}
None
}
async fn resolve_listing_entries_with_supplement(
entries: MetaCacheEntries,
resolver: MetadataResolutionParams,
enforce_write_quorum: bool,
supplement: Arc<ListingSupplement>,
) -> std::result::Result<Option<MetaCacheEntry>, DiskError> {
if let Some(target) = listing_entries_supplement_target(&entries, &resolver, enforce_write_quorum) {
let mut candidates = entries.0;
if !supplement.is_empty() {
candidates.extend(supplement.entries_for(target.name()).await);
}
if let Some(entry) = resolve_listing_entries(MetaCacheEntries(candidates), resolver.clone(), enforce_write_quorum) {
return Ok(Some(entry));
}
return match target {
ListingSupplementTarget::Directory(_) => Ok(None),
ListingSupplementTarget::Object(object) => supplement.reconcile_object(&object, resolver, enforce_write_quorum).await,
};
}
Ok(resolve_listing_entries(entries, resolver, enforce_write_quorum))
}
async fn resolve_agreed_listing_entry_with_supplement(
entry: MetaCacheEntry,
reader_disks: usize,
resolver: MetadataResolutionParams,
enforce_write_quorum: bool,
supplement: Arc<ListingSupplement>,
) -> Option<MetaCacheEntry> {
if supplement.is_empty() {
return None;
}
let mut candidates = Vec::with_capacity(reader_disks);
candidates.resize(reader_disks, Some(entry.clone()));
candidates.extend(supplement.entries_for(&entry.name).await);
resolve_listing_entries(MetaCacheEntries(candidates), resolver, enforce_write_quorum)
}
fn listing_entry_with_selected_versions(
mut entry: MetaCacheEntry,
meta_ver: u8,
data: rustfs_filemeta::InlineData,
selected_versions: Vec<FileMetaShallowVersion>,
) -> Option<MetaCacheEntry> {
let merged_cached = FileMeta {
meta_ver,
data,
versions: selected_versions,
};
let metadata = merged_cached.marshal_msg().ok()?;
entry.metadata = metadata;
entry.cached = Some(merged_cached);
Some(entry)
}
fn resolve_agreed_listing_entry(
mut entry: MetaCacheEntry,
reader_disks: usize,
resolver: MetadataResolutionParams,
enforce_write_quorum: bool,
) -> ListingEntryResolution {
if !enforce_write_quorum {
return ListingEntryResolution::Resolved(entry);
}
if entry.is_dir() {
return if reader_disks >= resolver.dir_quorum {
ListingEntryResolution::Resolved(entry)
} else {
ListingEntryResolution::Rejected
};
}
if reader_disks < resolver.obj_quorum {
return ListingEntryResolution::Rejected;
}
let cached = match entry.xl_meta() {
Ok(cached) => cached,
Err(_) if resolver.obj_quorum <= 1 => return ListingEntryResolution::Resolved(entry),
Err(_) => return ListingEntryResolution::Rejected,
};
let mut selected_versions = Vec::new();
let mut selected_object_versions = 0;
let mut first_selected_idx = None;
let mut needs_supplement = false;
for (idx, version) in cached.versions.iter().enumerate() {
let required_quorum = version
.write_quorum(resolver.obj_quorum)
.saturating_sub(resolver.write_quorum_slack)
.max(resolver.obj_quorum);
if reader_disks < required_quorum {
needs_supplement |=
version_requires_supplement(required_quorum, reader_disks, selected_object_versions, resolver.requested_versions);
continue;
}
if first_selected_idx.is_none() {
first_selected_idx = Some(idx);
}
if !version.header.free_version() {
selected_object_versions += 1;
}
selected_versions.push(version.clone());
if resolver.requested_versions > 0 && selected_object_versions == resolver.requested_versions {
break;
}
}
if needs_supplement {
let fallback = if selected_versions.is_empty() {
None
} else if selected_versions.len() == cached.versions.len() {
Some(entry.clone())
} else {
listing_entry_with_selected_versions(entry.clone(), cached.meta_ver, cached.data, selected_versions)
};
return ListingEntryResolution::NeedsSupplement(entry, fallback);
}
if selected_versions.is_empty() {
return ListingEntryResolution::Rejected;
}
let selected_latest = first_selected_idx == Some(0)
&& resolver.requested_versions == 1
&& selected_versions
.first()
.is_some_and(|version| !version.header.free_version());
if selected_latest || selected_versions.len() == cached.versions.len() {
return ListingEntryResolution::Resolved(entry);
}
listing_entry_with_selected_versions(entry, cached.meta_ver, cached.data, selected_versions)
.map(ListingEntryResolution::Resolved)
.unwrap_or(ListingEntryResolution::Rejected)
}
fn latest_listing_object_quorum(
listing_quorum: usize,
drive_count: usize,
parity_count: usize,
enforce_write_quorum: bool,
unreachable_disks: usize,
) -> usize {
latest_listing_required_object_quorum(listing_quorum, drive_count, parity_count, enforce_write_quorum, unreachable_disks)
}
fn latest_listing_required_object_quorum(
listing_quorum: usize,
drive_count: usize,
parity_count: usize,
enforce_write_quorum: bool,
unreachable_disks: usize,
) -> usize {
if !enforce_write_quorum {
return listing_quorum;
}
let read_quorum = drive_count.saturating_sub(parity_count);
write_quorum_for_drive_count(drive_count, parity_count)
.saturating_sub(unreachable_disks)
.max(read_quorum)
.max(listing_quorum)
}
fn latest_listing_write_quorum_slack(enforce_write_quorum: bool, drive_count: usize, online_disks: usize) -> usize {
if !enforce_write_quorum {
return 0;
}
drive_count.saturating_sub(online_disks)
}
fn enforce_latest_listing_write_quorum(strict_latest: bool, ask_disks: &str) -> bool {
strict_latest && !matches!(normalize_list_quorum(ask_disks), "disk" | "reduced")
}
#[cfg(test)]
fn latest_listing_allow_agreed_objects(enforce_write_quorum: bool, reader_disks: usize, object_quorum: usize) -> bool {
!enforce_write_quorum || reader_disks >= object_quorum
}
fn latest_listing_raw_min_disks(listing_quorum: usize, object_quorum: usize, enforce_write_quorum: bool) -> usize {
if enforce_write_quorum { object_quorum } else { listing_quorum }
}
fn positive_ask_disks(ask_disks: i32) -> Option<usize> {
usize::try_from(ask_disks).ok().filter(|asked| *asked > 0)
}
fn listing_quorum_from_ask_disks(ask_disks: i32) -> usize {
positive_ask_disks(ask_disks)
.map(|asked| asked.div_ceil(2))
.unwrap_or_default()
}
fn bounded_usize_to_i32(value: usize) -> i32 {
i32::try_from(value).unwrap_or(i32::MAX)
}
fn clamp_ask_disks_to_available(ask_disks: i32, available_disks: usize) -> i32 {
ask_disks.min(bounded_usize_to_i32(available_disks))
}
fn expand_ask_disks_for_object_quorum(ask_disks: i32, available_disks: usize, object_quorum: usize) -> i32 {
let Some(asked_disks) = positive_ask_disks(ask_disks) else {
return ask_disks;
};
bounded_usize_to_i32(asked_disks.max(object_quorum).min(available_disks))
}
fn write_quorum_for_drive_count(drive_count: usize, parity_count: usize) -> usize {
if drive_count == 0 {
return 0;
}
let data_drives = drive_count.saturating_sub(parity_count);
if data_drives == parity_count {
data_drives.saturating_add(1)
} else {
data_drives
}
}
fn parse_version_marker(marker: String) -> Result<VersionMarker> {
Ok(VersionMarker::parse(marker)?)
}
fn version_marker_for_entries(
entries: Option<&MetaCacheEntriesSorted>,
key_marker: Option<&str>,
version_marker: Option<VersionMarker>,
) -> Option<VersionMarker> {
let marker = version_marker?;
let Some(key_marker) = key_marker else {
return Some(marker);
};
entries
.and_then(|entries| entries.entries().first().map(|entry| entry.name.as_str() == key_marker))
.unwrap_or_default()
.then_some(marker)
}
impl ListPathOptions {
pub fn set_filter(&mut self) {
if METACACHE_SHARE_PREFIX {
return;
}
if self.prefix == self.base_dir {
return;
}
let s = SLASH_SEPARATOR.chars().next().unwrap_or_default();
self.filter_prefix = {
let fp = self.prefix.trim_start_matches(&self.base_dir).trim_matches(s);
if fp.contains(s) || fp.is_empty() {
None
} else {
Some(fp.to_owned())
}
}
}
pub fn parse_marker(&mut self) {
let Some(marker) = self.marker.clone() else {
return;
};
let Some(start_idx) = marker.rfind(LIST_CACHE_MARKER_PREFIX) else {
return;
};
let Some(end_offset) = marker[start_idx..].rfind(']') else {
return;
};
let end_idx = start_idx + end_offset;
let tag_body = &marker[start_idx + 1..end_idx];
let Some((continuation, should_create)) = ListContinuationV2::parse(tag_body) else {
return;
};
self.marker = Some(marker[..start_idx].to_owned());
self.id = continuation.id;
self.pool_idx = continuation.pool_idx;
self.set_idx = continuation.set_idx;
self.cursor_source = continuation.source;
self.cursor_generation = continuation.generation;
if should_create {
self.create = true;
}
}
pub fn encode_marker(&mut self, marker: &str) -> String {
ListContinuationV2 {
version: MARKER_TAG_VERSION,
id: self.id.clone(),
pool_idx: self.pool_idx,
set_idx: self.set_idx,
source: Some(ListSourceMode::Walker),
generation: Some(LIST_CURSOR_GENERATION_LIVE.to_owned()),
}
.encode_marker(marker)
}
}
impl ECStore {
async fn collect_persistent_key_only_index_objects(
self: Arc<Self>,
opts: &ListPathOptions,
) -> Result<Vec<PersistentListMetadataObject>> {
let mut marker = None;
let mut objects = Vec::new();
loop {
let previous_marker = marker.clone();
let page_opts = ListPathOptions {
bucket: opts.bucket.clone(),
prefix: String::new(),
marker: marker.clone(),
separator: None,
limit: max_keys_plus_one(MAX_OBJECT_LIST, true),
ask_disks: list_objects_quorum_from_env(),
incl_deleted: false,
cursor_source: Some(ListSourceMode::Walker),
cursor_generation: Some(LIST_CURSOR_GENERATION_LIVE.to_owned()),
..Default::default()
};
let mut list_result = self
.clone()
.list_path(&page_opts)
.await
.unwrap_or_else(|err| MetaCacheEntriesSortedResult {
err: Some(to_filemeta_err(err)),
..Default::default()
});
let reached_end = match list_result.err.take() {
Some(rustfs_filemeta::Error::Unexpected) => true,
Some(err) => return Err(Error::from(err)),
None => false,
};
if let Some(result) = list_result.entries.as_mut() {
result.forward_past(marker.clone());
}
let page_keys = list_result
.entries
.as_ref()
.map(|entries| {
entries
.entries()
.into_iter()
.map(|entry| entry.name.clone())
.collect::<Vec<_>>()
})
.unwrap_or_default();
if page_keys.is_empty() {
break;
}
if let Some(entries) = list_result.entries.as_ref() {
let page_objects = ObjectInfo::from_meta_cache_entries_sorted_infos(entries, &opts.bucket, "", None).await;
objects.extend(page_objects.iter().map(PersistentListMetadataObject::from_object_info));
}
marker = page_keys.last().cloned();
if marker == previous_marker {
return Err(Error::other("persistent key-only index rebuild marker did not advance"));
}
if reached_end {
break;
}
}
Ok(objects)
}
async fn rebuild_persistent_key_only_index(
self: Arc<Self>,
opts: &ListPathOptions,
path: &Path,
configured_generation: Option<&str>,
) -> Result<Arc<PersistentKeyOnlyIndex>> {
let generation = generated_persistent_key_only_generation(configured_generation);
const MAX_REBUILD_ATTEMPTS: usize = 3;
for attempt in 1..=MAX_REBUILD_ATTEMPTS {
let start_sequence = current_list_objects_mutation_snapshot(Some(self.as_ref()), &opts.bucket).await;
if start_sequence.degraded {
return Err(Error::other("list objects namespace mutation journal is degraded"));
}
let objects = self.clone().collect_persistent_key_only_index_objects(opts).await?;
let keys = objects.iter().map(|object| object.name.clone()).collect::<Vec<_>>();
let end_sequence = current_list_objects_mutation_snapshot(Some(self.as_ref()), &opts.bucket).await;
if end_sequence.degraded {
return Err(Error::other("list objects namespace mutation journal is degraded"));
}
if start_sequence.high_water_mark == end_sequence.high_water_mark {
write_persistent_key_only_index_with_metadata(
Some(self.as_ref()),
path,
&opts.bucket,
&generation,
end_sequence.high_water_mark,
&keys,
&objects,
)
.await?;
return load_persistent_key_only_index(Some(self.as_ref()), path).await;
}
debug!(
bucket = %opts.bucket,
attempt,
start_sequence = start_sequence.high_water_mark,
end_sequence = end_sequence.high_water_mark,
"persistent key-only index rebuild raced with object mutations"
);
}
Err(Error::other(
"persistent key-only index rebuild could not reach a stable mutation checkpoint",
))
}
async fn prepare_persistent_key_only_index(
self: Arc<Self>,
opts: &ListPathOptions,
provider_state: &ListObjectsIndexProviderState,
) -> Result<Arc<PersistentKeyOnlyIndex>> {
let Some(path) = provider_state.persistent_path.as_ref() else {
return Err(Error::other("persistent key-only provider path is not configured"));
};
match load_persistent_key_only_index(Some(self.as_ref()), path).await {
Ok(index) if persistent_key_only_index_matches_provider(&index, &opts.bucket, provider_state) => {
let current_sequence = current_list_objects_mutation_snapshot(Some(self.as_ref()), &opts.bucket).await;
if !current_sequence.degraded && current_sequence.high_water_mark <= index.checkpoint_high_water_mark {
Ok(index)
} else {
self.rebuild_persistent_key_only_index(opts, path, provider_state.persistent_generation.as_deref())
.await
}
}
Ok(_) => {
self.rebuild_persistent_key_only_index(opts, path, provider_state.persistent_generation.as_deref())
.await
}
Err(Error::Io(err)) if err.kind() == std::io::ErrorKind::NotFound => {
self.rebuild_persistent_key_only_index(opts, path, provider_state.persistent_generation.as_deref())
.await
}
Err(err) => Err(err),
}
}
async fn list_objects_from_metadata_fast_provider(
self: Arc<Self>,
provider_opts: &ListPathOptions,
provider_state: &ListObjectsIndexProviderState,
provider_label: &'static str,
max_keys: i32,
list_metrics_enabled: bool,
) -> Result<Option<ListObjectsInfo>> {
let staleness_ms = match list_objects_metadata_fast_guardrails_from_env() {
Some(staleness_ms) => staleness_ms,
None => {
if list_metrics_enabled {
record_list_objects_index_fallback(ListSourceMode::IndexMetadataFast, ListIndexFallbackReason::Disabled);
}
return Ok(None);
}
};
if provider_state.kind != ListObjectsIndexProviderKind::PersistentKeyOnly {
if list_metrics_enabled {
record_list_objects_index_fallback(
ListSourceMode::IndexMetadataFast,
ListIndexFallbackReason::UnsupportedRequest,
);
}
return Ok(None);
}
let Some(path) = provider_state.persistent_path.as_ref() else {
if list_metrics_enabled {
record_list_objects_index_fallback(ListSourceMode::IndexMetadataFast, ListIndexFallbackReason::Degraded);
}
return Ok(None);
};
let index = match self
.clone()
.prepare_persistent_key_only_index(provider_opts, provider_state)
.await
{
Ok(index) => index,
Err(err) => {
if list_metrics_enabled {
record_list_objects_index_fallback(ListSourceMode::IndexMetadataFast, ListIndexFallbackReason::Unhealthy);
}
debug!(
bucket = %provider_opts.bucket,
prefix = %provider_opts.prefix,
source = ListSourceMode::IndexMetadataFast.cursor_value(),
provider = provider_state.kind.metric_label(),
path = %path.display(),
error = %err,
"list_objects metadata-fast provider failed to prepare snapshot"
);
return Ok(None);
}
};
if !persistent_key_only_index_has_complete_metadata_snapshot(&index) {
if list_metrics_enabled {
record_list_objects_index_fallback(
ListSourceMode::IndexMetadataFast,
ListIndexFallbackReason::MetadataFastUnavailable,
);
}
debug!(
bucket = %provider_opts.bucket,
prefix = %provider_opts.prefix,
source = ListSourceMode::IndexMetadataFast.cursor_value(),
provider = provider_state.kind.metric_label(),
indexed_keys = index.keys.len(),
snapshot_objects = index.objects.len(),
"list_objects metadata-fast provider has no complete metadata snapshot"
);
return Ok(None);
}
maybe_apply_system_namespace_mutation_journal_chaos(
self.as_ref(),
&provider_opts.bucket,
index.checkpoint_high_water_mark,
)
.await;
let current_sequence = current_list_objects_mutation_snapshot(Some(self.as_ref()), &provider_opts.bucket).await;
let health = persistent_key_only_index_health(&index, current_sequence);
match select_list_index_provider_source_mode(provider_opts, ListSourceMode::IndexMetadataFast, &health) {
ListIndexSourceDecision::FallbackToWalker(reason) => {
if list_metrics_enabled {
record_list_objects_index_fallback(ListSourceMode::IndexMetadataFast, reason);
}
debug!(
bucket = %provider_opts.bucket,
prefix = %provider_opts.prefix,
source = ListSourceMode::IndexMetadataFast.cursor_value(),
provider = provider_state.kind.metric_label(),
staleness_ms,
reason = reason.metric_label(),
"list_objects metadata-fast provider fell back to walker"
);
return Ok(None);
}
ListIndexSourceDecision::UseIndex(_) => {}
}
let verified = list_objects_from_metadata_snapshot_candidates(
&provider_opts.bucket,
&provider_opts.prefix,
provider_opts.marker.as_deref(),
&provider_opts.separator,
max_keys,
index.objects.as_slice(),
);
let stats = verified.stats;
let mut result = verified.info;
if list_metrics_enabled {
rustfs_io_metrics::record_list_objects_index_served(ListObjectsIndexPageObservation {
source: ListSourceMode::IndexMetadataFast.cursor_value(),
provider: provider_label,
candidate_keys: stats.candidate_keys,
live_verify_attempts: 0,
live_verify_hits: 0,
live_verify_misses: 0,
returned_objects: result.objects.len(),
returned_prefixes: result.prefixes.len(),
is_truncated: result.is_truncated,
});
}
if let Some(next_marker) = result.next_marker.take() {
result.next_marker = Some(
ListContinuationV2 {
version: MARKER_TAG_VERSION,
id: None,
pool_idx: None,
set_idx: None,
source: Some(ListSourceMode::IndexMetadataFast),
generation: health.active_generation,
}
.encode_marker(&next_marker),
);
}
Ok(Some(result))
}
async fn list_objects_from_opt_in_key_only_provider(
self: Arc<Self>,
opts: &ListPathOptions,
mode: ListSourceMode,
max_keys: i32,
incl_deleted: bool,
) -> Result<Option<ListObjectsInfo>> {
let list_metrics_enabled = rustfs_io_metrics::get_stage_metrics_enabled();
let provider_state = list_objects_index_provider_state_from_env();
let provider = provider_state.as_ref().map(|state| state.kind);
let provider_label = if list_metrics_enabled {
list_objects_index_provider_metric_label(provider)
} else {
"none"
};
if list_metrics_enabled {
rustfs_io_metrics::record_list_objects_index_attempt(
mode.cursor_value(),
provider_label,
!opts.prefix.is_empty(),
opts.separator.as_ref().is_some_and(|separator| !separator.is_empty()),
opts.marker.is_some(),
);
}
if incl_deleted
|| (mode != ListSourceMode::IndexMetadataFast
&& (!mode.can_satisfy_strong_listing() || !mode.requires_live_metadata_verification()))
{
if list_metrics_enabled {
record_list_objects_index_fallback(mode, ListIndexFallbackReason::UnsupportedRequest);
}
return Ok(None);
}
if is_reserved_or_invalid_bucket(&opts.bucket, false) {
if list_metrics_enabled {
record_list_objects_index_fallback(mode, ListIndexFallbackReason::UnsupportedRequest);
}
return Ok(None);
}
let Some(provider_state) = provider_state else {
if list_metrics_enabled {
record_list_objects_index_fallback(mode, ListIndexFallbackReason::Disabled);
}
return Ok(None);
};
let mut provider_opts = opts.clone();
provider_opts.parse_marker();
if mode == ListSourceMode::IndexMetadataFast {
return self
.list_objects_from_metadata_fast_provider(
&provider_opts,
&provider_state,
provider_label,
max_keys,
list_metrics_enabled,
)
.await;
}
let (candidate_keys, health) = match provider_state.kind {
ListObjectsIndexProviderKind::WalkerKeyOnly => {
let health = provider_state.health_snapshot();
match select_list_index_provider_source_mode(&provider_opts, mode, &health) {
ListIndexSourceDecision::FallbackToWalker(reason) => {
if list_metrics_enabled {
record_list_objects_index_fallback(mode, reason);
}
debug!(
bucket = %opts.bucket,
prefix = %opts.prefix,
source = mode.cursor_value(),
reason = reason.metric_label(),
"list_objects opt-in index path fell back to walker"
);
return Ok(None);
}
ListIndexSourceDecision::UseIndex(_) => {}
}
provider_opts.cursor_source = Some(mode);
provider_opts.cursor_generation = health.active_generation.clone();
let mut list_result =
self.clone()
.list_path(&provider_opts)
.await
.unwrap_or_else(|err| MetaCacheEntriesSortedResult {
err: Some(to_filemeta_err(err)),
..Default::default()
});
if let Some(err) = list_result.err.take()
&& err != rustfs_filemeta::Error::Unexpected
{
if list_metrics_enabled {
record_list_objects_index_fallback(mode, ListIndexFallbackReason::Unhealthy);
}
return Ok(None);
}
if let Some(result) = list_result.entries.as_mut() {
result.forward_past(provider_opts.marker.clone());
}
let candidate_keys = Arc::new(
list_result
.entries
.as_ref()
.map(|entries| {
entries
.entries()
.into_iter()
.map(|entry| entry.name.clone())
.collect::<Vec<_>>()
})
.unwrap_or_default(),
);
(candidate_keys, health)
}
ListObjectsIndexProviderKind::PersistentKeyOnly => {
let Some(path) = provider_state.persistent_path.as_ref() else {
if list_metrics_enabled {
record_list_objects_index_fallback(mode, ListIndexFallbackReason::Degraded);
}
return Ok(None);
};
match self
.clone()
.prepare_persistent_key_only_index(&provider_opts, &provider_state)
.await
{
Ok(index) => {
let current_sequence =
current_list_objects_mutation_snapshot(Some(self.as_ref()), &provider_opts.bucket).await;
let health = persistent_key_only_index_health(&index, current_sequence);
match select_list_index_provider_source_mode(&provider_opts, mode, &health) {
ListIndexSourceDecision::FallbackToWalker(reason) => {
if list_metrics_enabled {
record_list_objects_index_fallback(mode, reason);
}
debug!(
bucket = %opts.bucket,
prefix = %opts.prefix,
source = mode.cursor_value(),
provider = provider_state.kind.metric_label(),
reason = reason.metric_label(),
"list_objects persistent key-only provider fell back to walker"
);
return Ok(None);
}
ListIndexSourceDecision::UseIndex(_) => {}
}
provider_opts.cursor_source = Some(mode);
provider_opts.cursor_generation = health.active_generation.clone();
(index.keys.clone(), health)
}
Err(err) => {
if list_metrics_enabled {
record_list_objects_index_fallback(mode, ListIndexFallbackReason::Unhealthy);
}
debug!(
bucket = %opts.bucket,
prefix = %opts.prefix,
source = mode.cursor_value(),
provider = provider_state.kind.metric_label(),
path = %path.display(),
error = %err,
"list_objects persistent key-only provider failed to load candidates"
);
return Ok(None);
}
}
}
};
let bucket = provider_opts.bucket.clone();
let verified = list_objects_from_verified_index_candidates_with_optional_stats(
&provider_opts.prefix,
provider_opts.marker.as_deref(),
&provider_opts.separator,
max_keys,
candidate_keys.as_slice(),
list_metrics_enabled,
|key| {
let store = self.clone();
let bucket = bucket.clone();
async move {
match store
.get_object_info(
&bucket,
&key,
&ObjectOptions {
no_lock: true,
..Default::default()
},
)
.await
{
Ok(object) => Ok(Some(object)),
Err(err) if err.is_not_found() => Ok(None),
Err(err) => {
if list_metrics_enabled {
rustfs_io_metrics::record_list_objects_index_live_verify_failure(
mode.cursor_value(),
"read_error",
);
}
Err(err)
}
}
}
},
)
.await?;
let stats = verified.stats;
let mut result = verified.info;
if list_metrics_enabled {
rustfs_io_metrics::record_list_objects_index_served(ListObjectsIndexPageObservation {
source: mode.cursor_value(),
provider: provider_label,
candidate_keys: stats.candidate_keys,
live_verify_attempts: stats.live_verify_attempts,
live_verify_hits: stats.live_verify_hits,
live_verify_misses: stats.live_verify_misses,
returned_objects: result.objects.len(),
returned_prefixes: result.prefixes.len(),
is_truncated: result.is_truncated,
});
}
if let Some(next_marker) = result.next_marker.take() {
result.next_marker = Some(
ListContinuationV2 {
version: MARKER_TAG_VERSION,
id: None,
pool_idx: None,
set_idx: None,
source: Some(mode),
generation: health.active_generation,
}
.encode_marker(&next_marker),
);
}
Ok(Some(result))
}
#[allow(clippy::too_many_arguments)]
pub async fn inner_list_objects_v2(
self: Arc<Self>,
bucket: &str,
prefix: &str,
continuation_token: Option<String>,
delimiter: Option<String>,
max_keys: i32,
_fetch_owner: bool,
start_after: Option<String>,
incl_deleted: bool,
) -> Result<ListObjectsV2Info> {
let marker = {
if continuation_token.is_none() {
start_after
} else {
continuation_token.clone()
}
};
let loi = self
.list_objects_generic(bucket, prefix, marker, delimiter, max_keys, incl_deleted)
.await?;
Ok(ListObjectsV2Info {
is_truncated: loi.is_truncated,
continuation_token,
next_continuation_token: loi.next_marker,
objects: loi.objects,
prefixes: loi.prefixes,
})
}
pub async fn list_objects_generic(
self: Arc<Self>,
bucket: &str,
prefix: &str,
marker: Option<String>,
delimiter: Option<String>,
max_keys: i32,
incl_deleted: bool,
) -> Result<ListObjectsInfo> {
let max_keys = normalize_max_keys(max_keys);
let effective_max_keys = if max_keys <= 0 { 0 } else { max_keys_plus_one(max_keys, true) };
let mut opts = ListPathOptions {
bucket: bucket.to_owned(),
prefix: prefix.to_owned(),
separator: delimiter.clone(),
limit: effective_max_keys,
marker,
incl_deleted,
ask_disks: list_objects_quorum_from_env(),
..Default::default()
};
opts.parse_marker();
let key_only_result = if let Some(mode) = list_objects_index_mode_from_env() {
self.clone()
.list_objects_from_opt_in_key_only_provider(&opts, mode, max_keys, incl_deleted)
.await?
} else {
None
};
let result = if let Some(result) = key_only_result {
result
} else {
let mut list_result = self
.clone()
.list_path(&opts)
.await
.unwrap_or_else(|err| MetaCacheEntriesSortedResult {
err: Some(to_filemeta_err(err)),
..Default::default()
});
let next_cache_id = list_result.entries.as_ref().and_then(|entries| entries.list_id.clone());
let disk_has_more = list_result.err.is_none();
if let Some(err) = list_result.err.take()
&& err != rustfs_filemeta::Error::Unexpected
{
return Err(to_object_err(err.into(), vec![bucket, prefix]));
}
if let Some(result) = list_result.entries.as_mut() {
result.forward_past(opts.marker.clone());
}
let last_scanned_key = last_scanned_entry_name(list_result.entries.as_ref());
let get_objects = ObjectInfo::from_meta_cache_entries_sorted_infos(
&list_result.entries.unwrap_or_default(),
bucket,
prefix,
delimiter.clone(),
)
.await;
let (objects, prefixes, is_truncated, next_marker, next_version_idmarker) = list_objects_paginate(
get_objects,
&delimiter,
max_keys,
disk_has_more,
next_cache_id.as_deref(),
false,
last_scanned_key.as_deref(),
);
let _ = next_version_idmarker;
ListObjectsInfo {
is_truncated,
next_marker,
objects,
prefixes,
}
};
let purge_exact_prefix =
should_purge_empty_directory_listing(prefix, opts.marker.as_deref(), max_keys, incl_deleted, &result);
let purge_empty_bucket = should_purge_empty_recursive_bucket_listing(
prefix,
delimiter.as_deref(),
opts.marker.as_deref(),
max_keys,
incl_deleted,
&result,
);
if (purge_exact_prefix || purge_empty_bucket)
&& has_authoritative_never_versioned_state_in(&self.ctx, bucket)
.await
.unwrap_or(false)
{
if purge_exact_prefix {
self.purge_orphan_dir_object(bucket, prefix).await;
} else {
self.purge_orphan_dir_objects_in_bucket(bucket).await;
}
}
Ok(result)
}
pub async fn inner_list_object_versions(
self: Arc<Self>,
bucket: &str,
prefix: &str,
marker: Option<String>,
version_marker: Option<String>,
delimiter: Option<String>,
max_keys: i32,
) -> Result<ListObjectVersionsInfo> {
self.inner_list_object_versions_with_projection(ListObjectVersionsInput {
bucket,
prefix,
marker,
version_marker,
delimiter,
max_keys,
include_version_purge: false,
})
.await
}
pub(crate) async fn list_object_versions_for_lifecycle(
self: Arc<Self>,
bucket: &str,
prefix: &str,
marker: Option<String>,
version_marker: Option<String>,
delimiter: Option<String>,
max_keys: i32,
) -> Result<ListObjectVersionsInfo> {
self.inner_list_object_versions_with_projection(ListObjectVersionsInput {
bucket,
prefix,
marker,
version_marker,
delimiter,
max_keys,
include_version_purge: true,
})
.await
}
async fn inner_list_object_versions_with_projection(
self: Arc<Self>,
input: ListObjectVersionsInput<'_>,
) -> Result<ListObjectVersionsInfo> {
let ListObjectVersionsInput {
bucket,
prefix,
marker,
version_marker,
delimiter,
max_keys,
include_version_purge,
} = input;
let max_keys = normalize_max_keys(max_keys);
if marker.is_none() && version_marker.is_some() {
return Err(StorageError::NotImplemented);
}
let has_version_marker = version_marker.is_some();
let version_marker = if let Some(marker) = version_marker {
Some(parse_version_marker(marker)?)
} else {
None
};
let effective_max_keys = list_versions_scan_limit(max_keys, has_version_marker);
let mut opts = ListPathOptions {
bucket: bucket.to_owned(),
prefix: prefix.to_owned(),
separator: delimiter.clone(),
limit: effective_max_keys,
marker,
incl_deleted: true,
ask_disks: list_objects_quorum_from_env(),
versioned: true,
include_marker: has_version_marker,
..Default::default()
};
opts.parse_marker();
let mut list_result = self
.list_path(&opts)
.await
.unwrap_or_else(|err| MetaCacheEntriesSortedResult {
err: Some(to_filemeta_err(err)),
..Default::default()
});
let next_cache_id = list_result.entries.as_ref().and_then(|entries| entries.list_id.clone());
let disk_has_more = list_result.err.is_none();
if let Some(err) = list_result.err.take()
&& err != rustfs_filemeta::Error::Unexpected
{
return Err(to_object_err(err.into(), vec![bucket, prefix]));
}
if let Some(result) = list_result.entries.as_mut()
&& !has_version_marker
{
result.forward_past(opts.marker.clone());
}
let version_marker = version_marker_for_entries(list_result.entries.as_ref(), opts.marker.as_deref(), version_marker);
let last_scanned_key = last_scanned_entry_name(list_result.entries.as_ref());
let entries = list_result.entries.unwrap_or_default();
let get_objects = if include_version_purge {
ObjectInfo::from_meta_cache_entries_sorted_versions_for_lifecycle(
&entries,
bucket,
prefix,
delimiter.clone(),
version_marker,
)
.await
} else {
ObjectInfo::from_meta_cache_entries_sorted_versions(&entries, bucket, prefix, delimiter.clone(), version_marker).await
};
let (objects, prefixes, is_truncated, next_marker, next_version_idmarker) = list_objects_paginate(
get_objects,
&delimiter,
max_keys,
disk_has_more,
next_cache_id.as_deref(),
true,
last_scanned_key.as_deref(),
);
Ok(ListObjectVersionsInfo {
is_truncated,
next_marker,
next_version_idmarker,
objects,
prefixes,
})
}
pub async fn list_path(self: Arc<Self>, o: &ListPathOptions) -> Result<MetaCacheEntriesSortedResult> {
let list_path_started = std::time::Instant::now();
check_list_objs_args(&o.bucket, &o.prefix, &o.marker)?;
let mut o = o.clone();
o.marker = o.marker.filter(|v| v >= &o.prefix);
if let Some(marker) = &o.marker
&& !o.prefix.is_empty()
&& !marker.starts_with(&o.prefix)
{
return Err(Error::Unexpected);
}
if o.limit == 0 {
return Err(Error::Unexpected);
}
if o.prefix.starts_with(SLASH_SEPARATOR) {
return Err(Error::Unexpected);
}
let slash_separator = Some(SLASH_SEPARATOR.to_owned());
o.include_directories = o.separator == slash_separator;
if (o.separator == slash_separator || o.separator.is_none()) && !o.recursive {
o.recursive = o.separator != slash_separator;
o.separator = slash_separator;
} else {
o.recursive = true
}
o.skip_hidden_prefix_check = can_skip_hidden_prefix_check(&o).await;
o.parse_marker();
if o.base_dir.is_empty() {
o.base_dir = base_dir_from_prefix(&o.prefix);
}
o.transient = o.transient || is_reserved_or_invalid_bucket(&o.bucket, false);
o.set_filter();
if o.transient {
o.create = false;
}
let log_context = ListPathLogContext::from_options(&o);
let cancel = CancellationToken::new();
let _cancel_guard = cancel.clone().drop_guard();
ensure_producer_limit_state(&mut o);
let (err_tx, mut err_rx) = broadcast::channel::<Arc<Error>>(1);
let (sender, recv) = mpsc::channel(o.limit as usize);
let store = self.clone();
let opts = o.clone();
let cancel_rx1 = cancel.clone();
let cancel_rx1_for_err = cancel_rx1.clone();
let err_tx1 = err_tx.clone();
let job1_context = log_context.clone();
let job1 = tokio::spawn(
async move {
let mut opts = opts;
opts.stop_disk_at_limit = true;
if let Err(err) = store.list_merged(cancel_rx1, opts, sender).await
&& !cancel_rx1_for_err.is_cancelled()
{
log_list_path_worker_error("store", "list_merged", &job1_context, &err);
let _ = err_tx1.send(Arc::new(err));
}
}
.instrument(tracing::Span::current()),
);
let cancel_rx2 = cancel.clone();
let (result_tx, mut result_rx) = mpsc::channel(1);
let err_tx2 = err_tx.clone();
let opts = o.clone();
let job2_context = log_context.clone();
let job2 = tokio::spawn(
async move {
match gather_results(cancel_rx2, opts, recv, result_tx).await {
Ok(GatherResultsState::LimitReached) => cancel.cancel(),
Ok(GatherResultsState::InputClosed) => {}
Ok(GatherResultsState::ConsumerGone) => cancel.cancel(),
Err(err) => {
log_list_path_worker_error("store", "gather_results", &job2_context, &err);
let _ = err_tx2.send(Arc::new(err));
cancel.cancel();
}
}
}
.instrument(tracing::Span::current()),
);
let mut result = {
tokio::select! {
res = err_rx.recv() =>{
match res{
Ok(err) => {
log_list_path_worker_error("store", "worker_error", &log_context, err.as_ref());
MetaCacheEntriesSortedResult{ entries: None, err: Some(to_filemeta_err(err.as_ref().clone())) }
},
Err(err) => {
log_list_path_worker_error("store", "error_channel_closed", &log_context, &err);
MetaCacheEntriesSortedResult{ entries: None, err: Some(rustfs_filemeta::Error::other(err)) }
},
}
},
Some(result) = result_rx.recv()=>{
result
}
}
};
join_all(vec![job1, job2]).await;
if let Ok(err) = err_rx.try_recv() {
log_list_path_worker_error("store", "trailing_worker_error", &log_context, err.as_ref());
result.err = Some(to_filemeta_err(err.as_ref().clone()));
}
if result.err.is_some() {
log_list_path_finished("store", &log_context, list_path_started.elapsed().as_secs_f64() * 1000.0, 0, true);
return Ok(result);
}
if let Some(entries) = result.entries.as_mut() {
entries.reuse = true;
let truncated = !entries.entries().is_empty() || result.err.is_none();
entries.o.0.truncate(o.limit as usize);
if !o.transient && truncated {
entries.list_id = if let Some(id) = o.id {
Some(id)
} else {
Some(Uuid::new_v4().to_string())
}
}
if !truncated {
result.err = Some(rustfs_filemeta::Error::Unexpected);
}
}
rustfs_io_metrics::record_stage_duration(
"store_list_objects_list_path",
list_path_started.elapsed().as_secs_f64() * 1000.0,
);
log_list_path_finished(
"store",
&log_context,
list_path_started.elapsed().as_secs_f64() * 1000.0,
result
.entries
.as_ref()
.map(|entries| entries.entries().len())
.unwrap_or_default(),
result.err.is_some(),
);
Ok(result)
}
async fn list_merged(
&self,
rx: CancellationToken,
opts: ListPathOptions,
sender: Sender<MetaCacheEntry>,
) -> Result<Vec<ObjectInfo>> {
let merge_started = std::time::Instant::now();
debug!(
list_path_limit = opts.limit,
recursive = opts.recursive,
pool_count = self.pools.len(),
requested_marker = %opts.marker.as_deref().unwrap_or(""),
"store list_merged started"
);
let rx = rx.child_token();
let mut futures = Vec::new();
let mut inputs = Vec::new();
for sets in self.pools.iter() {
for set in sets.disk_set.iter() {
let (send, recv) = list_merged_entry_channel();
inputs.push(recv);
let opts = opts.clone();
let rx_clone = rx.clone();
futures.push(set.list_path(rx_clone, opts, send));
}
}
let merge_task = spawn_listing_merge(rx, inputs, sender);
let results = join_all(futures).await;
merge_task.await.map_err(Error::from)??;
let mut all_at_eof = true;
let mut errs = Vec::new();
for result in results {
if let Err(err) = result {
all_at_eof = false;
errs.push(Some(err));
} else {
errs.push(None);
}
}
if is_all_not_found(&errs) {
return Ok(Vec::new());
}
for err in errs.iter() {
if let Some(err) = err {
if err == &Error::Unexpected {
continue;
}
return Err(err.clone());
} else {
all_at_eof = false;
continue;
}
}
rustfs_io_metrics::record_stage_duration(
"store_list_objects_list_merged",
merge_started.elapsed().as_secs_f64() * 1000.0,
);
debug!(
set_pair_count = self.pools.len(),
all_at_eof = all_at_eof,
error_count = errs.iter().filter(|err| err.is_some()).count(),
"store list_merged finished"
);
_ = all_at_eof;
Ok(Vec::new())
}
#[allow(unused_assignments)]
pub async fn walk_internal(
self: Arc<Self>,
rx: CancellationToken,
bucket: &str,
prefix: &str,
result: Sender<ObjectInfoOrErr>,
opts: WalkOptions,
) -> Result<()> {
check_list_objs_args(bucket, prefix, &None)?;
let rx = rx.child_token();
let mut futures = Vec::new();
let mut inputs = Vec::new();
for eset in self.pools.iter() {
for set in eset.disk_set.iter() {
let (mut disks, infos, _) = set.get_online_disks_with_healing_and_info(true).await;
let online_disks = disks.len();
let opts = opts.clone();
let (sender, list_out_rx) = mpsc::channel::<MetaCacheEntry>(1);
inputs.push(list_out_rx);
let rx_clone = rx.clone();
futures.push(async move {
let mut ask_disks = get_list_quorum(&opts.ask_disks, set.set_drive_count as i32);
if ask_disks == -1 {
let new_disks = get_quorum_disks(&disks, &infos, disks.len().div_ceil(2));
if !new_disks.is_empty() {
disks = new_disks;
} else {
ask_disks = get_list_quorum("strict", set.set_drive_count as i32);
}
}
if set.set_drive_count == 4 {
ask_disks = bounded_usize_to_i32(disks.len());
} else if ask_disks > bounded_usize_to_i32(disks.len()) {
ask_disks = clamp_ask_disks_to_available(ask_disks, disks.len());
}
let listing_quorum = listing_quorum_from_ask_disks(ask_disks);
let enforce_write_quorum = enforce_latest_listing_write_quorum(opts.latest_only, &opts.ask_disks);
let write_quorum_parity = set.default_parity_count;
let write_quorum_slack =
latest_listing_write_quorum_slack(enforce_write_quorum, set.set_drive_count, online_disks);
let required_obj_quorum = latest_listing_required_object_quorum(
listing_quorum,
set.set_drive_count,
write_quorum_parity,
enforce_write_quorum,
write_quorum_slack,
);
ask_disks = expand_ask_disks_for_object_quorum(ask_disks, disks.len(), required_obj_quorum);
let fallback_disks = {
if let Some(asked_disks) = positive_ask_disks(ask_disks)
&& disks.len() > asked_disks
{
let mut rand = rand::rng();
disks.shuffle(&mut rand);
disks.split_off(asked_disks)
} else {
Vec::new()
}
};
let fallback_disks = Arc::new(fallback_disks);
let disks = Arc::new(disks);
let claim_tracker = FallbackClaimTracker::default();
let obj_quorum = latest_listing_object_quorum(
listing_quorum,
set.set_drive_count,
write_quorum_parity,
enforce_write_quorum,
write_quorum_slack,
);
let raw_min_disks = latest_listing_raw_min_disks(listing_quorum, obj_quorum, enforce_write_quorum);
let resolver = list_metadata_resolution_params(
bucket.to_owned(),
listing_quorum,
obj_quorum,
!opts.latest_only,
write_quorum_slack,
);
let agreed_resolver = resolver.clone();
let partial_resolver = resolver.clone();
let reader_disks = disks.len();
let path = base_dir_from_prefix(prefix);
ensure_non_empty_listing_disks(bucket, &path, &disks).map_err(to_filemeta_err)?;
let mut filter_prefix = {
prefix
.trim_start_matches(&path)
.trim_start_matches(SLASH_SEPARATOR)
.trim_end_matches(SLASH_SEPARATOR)
.to_owned()
};
if filter_prefix == path {
filter_prefix = "".to_owned();
}
let tx1 = sender.clone();
let tx2 = sender.clone();
let supplement = ListingSupplement::new_with_reconciler(
ListingSupplementOptions {
bucket: bucket.to_owned(),
path: path.clone(),
recursive: true,
incl_deleted: !opts.latest_only,
skip_hidden_prefix_check: false,
filter_prefix: Some(filter_prefix.clone()),
forward_to: opts.marker.clone(),
per_disk_limit: bounded_usize_to_i32(opts.limit),
skip_total_timeout: opts.walkdir_timeout.is_none(),
walkdir_timeout: opts.walkdir_timeout,
walkdir_stall_timeout: opts.walkdir_stall_timeout,
},
fallback_disks.clone(),
claim_tracker.clone(),
set.as_ref().clone(),
disks.clone(),
);
let agreed_supplement = supplement.clone();
let partial_supplement = supplement;
list_path_raw_with_partial_result(
rx_clone,
ListPathRawOptions {
disks: disks.iter().cloned().map(Some).collect(),
fallback_disks: fallback_disks.iter().cloned().map(Some).collect(),
bucket: bucket.to_owned(),
path,
recursive: true,
incl_deleted: !opts.latest_only,
filter_prefix: Some(filter_prefix),
forward_to: opts.marker.clone(),
min_disks: raw_min_disks,
per_disk_limit: bounded_usize_to_i32(opts.limit),
skip_walkdir_total_timeout: opts.walkdir_timeout.is_none(),
walkdir_timeout: opts.walkdir_timeout,
walkdir_stall_timeout: opts.walkdir_stall_timeout,
agreed: Some(Box::new(move |entry: MetaCacheEntry| {
Box::pin({
let value = tx1.clone();
let resolver = agreed_resolver.clone();
let supplement = agreed_supplement.clone();
async move {
let entry = match resolve_agreed_listing_entry(
entry,
reader_disks,
resolver.clone(),
enforce_write_quorum,
) {
ListingEntryResolution::Resolved(entry) => entry,
ListingEntryResolution::NeedsSupplement(entry, fallback) => {
let Some(entry) = resolve_agreed_listing_entry_with_supplement(
entry,
reader_disks,
resolver,
enforce_write_quorum,
supplement,
)
.await
.or(fallback) else {
return;
};
entry
}
ListingEntryResolution::Rejected => return,
};
if entry.is_dir() {
return;
}
if let Err(err) = value.send(entry).await {
error!("list_path send fail {:?}", err);
}
}
})
})),
finished: None,
..Default::default()
},
claim_tracker,
Box::new(move |entries: MetaCacheEntries, _: &[Option<DiskError>]| {
Box::pin({
let value = tx2.clone();
let resolver = partial_resolver.clone();
let supplement = partial_supplement.clone();
async move {
if let Some(entry) = resolve_listing_entries_with_supplement(
entries,
resolver,
enforce_write_quorum,
supplement,
)
.await?
&& let Err(err) = value.send(entry).await
{
error!("list_path send fail {:?}", err);
}
Ok(())
}
})
}),
)
.await
});
}
}
let (merge_tx, mut merge_rx) = mpsc::channel::<MetaCacheEntry>(100);
let bucket = bucket.to_owned();
let bucket_clone = bucket.clone();
let vcf = match get_versioning_config(&bucket).await {
Ok((res, _)) => Some(res),
Err(_) => None,
};
tokio::spawn(
async move {
let mut sent_err = false;
while let Some(entry) = merge_rx.recv().await {
if opts.latest_only {
let fi = match entry.to_fileinfo(&bucket_clone) {
Ok(res) => res,
Err(err) => {
if !sent_err {
let item = ObjectInfoOrErr {
item: None,
err: Some(err.into()),
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
sent_err = true;
return;
}
continue;
}
};
if let Some(filter) = opts.filter {
if filter(&fi) {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(&fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
} else {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(&fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
continue;
}
let mut fvs = match if opts.include_free_versions {
entry.file_info_versions_with_free_versions(&bucket_clone)
} else {
entry.file_info_versions(&bucket_clone)
} {
Ok(res) => res,
Err(err) => {
let item = ObjectInfoOrErr {
item: None,
err: Some(err.into()),
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
return;
}
};
if opts.versions_sort == WalkVersionsSortOrder::Ascending {
fvs.versions.reverse();
}
for fi in fvs.versions.iter() {
if let Some(filter) = opts.filter {
if filter(fi) {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
} else {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
}
if opts.include_free_versions {
for fi in fvs.free_versions.iter() {
if let Some(filter) = opts.filter {
if filter(fi) {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
} else {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
}
}
}
}
.instrument(tracing::Span::current()),
);
let merge_task = spawn_listing_merge(rx, inputs, merge_tx);
let walk_started = std::time::Instant::now();
let walk_results = join_all(futures).await;
merge_task.await.map_err(Error::from)??;
let mut errs = Vec::new();
for walk_result in walk_results {
match walk_result {
Ok(()) => errs.push(None),
Err(err) => errs.push(Some(err.into())),
}
}
rustfs_io_metrics::record_stage_duration(
"store_list_objects_walk_internal",
walk_started.elapsed().as_secs_f64() * 1000.0,
);
let result = walk_result_from_set_errors(&errs);
if let Err(err) = &result {
error!(
bucket = %bucket,
prefix = %prefix,
error = ?err,
set_errors = ?errs,
"walk_internal list_path_raw tasks failed"
);
}
result
}
}
async fn gather_results(
rx: CancellationToken,
opts: ListPathOptions,
recv: Receiver<MetaCacheEntry>,
results_tx: Sender<MetaCacheEntriesSortedResult>,
) -> Result<GatherResultsState> {
let mut recv = recv;
let mut entries = Vec::new();
let list_metrics_enabled = rustfs_io_metrics::get_stage_metrics_enabled();
let gather_started = list_metrics_enabled.then(std::time::Instant::now);
let mut scanned_entries = 0usize;
let mut candidate_entries = 0usize;
while let Some(mut entry) = recv.recv().await {
scanned_entries += 1;
#[cfg(windows)]
{
entry.name = entry.name.replace("\\", "/");
}
if let Some(marker) = &opts.marker
&& ((!opts.include_marker && &entry.name <= marker) || (opts.include_marker && &entry.name < marker))
{
continue;
}
if !entry.name.starts_with(&opts.prefix) {
continue;
}
if let Some(separator) = &opts.separator
&& !opts.recursive
&& !entry.is_in_dir(&opts.prefix, separator)
{
continue;
}
let is_object = entry.is_object();
let is_latest_delete_marker = is_object && entry.is_latest_delete_marker();
if !opts.include_directories && (entry.is_dir() || (!opts.versioned && is_latest_delete_marker)) {
continue;
}
if !opts.incl_deleted && is_latest_delete_marker {
continue;
}
entries.push(Some(entry));
candidate_entries += 1;
if opts.limit > 0 && entries.len() >= opts.limit as usize {
rx.cancel();
let filtered = scanned_entries.saturating_sub(candidate_entries);
if let Some(started) = gather_started {
let duration_ms = started.elapsed().as_secs_f64() * 1000.0;
rustfs_io_metrics::record_list_objects_gather(ListObjectsGatherObservation {
source: LIST_OBJECTS_SOURCE_WALKER,
outcome: LIST_OBJECTS_GATHER_OUTCOME_LIMIT_REACHED,
limit: opts.limit,
scanned_entries,
returned_entries: candidate_entries,
duration_ms,
has_prefix: !opts.prefix.is_empty(),
has_delimiter: opts.separator.as_ref().is_some_and(|separator| !separator.is_empty()),
has_marker: opts.marker.is_some(),
});
rustfs_io_metrics::record_stage_duration("store_list_objects_gather", duration_ms);
}
debug!(
bucket = %opts.bucket,
prefix = %opts.prefix,
limit = opts.limit,
scanned_entries = scanned_entries,
returned_entries = candidate_entries,
filtered_entries = filtered,
marker = %opts.marker.as_deref().unwrap_or(""),
"list_objects gather_results reached page limit and cancelled upstream listing"
);
if results_tx
.send(MetaCacheEntriesSortedResult {
entries: Some(MetaCacheEntriesSorted {
o: MetaCacheEntries(entries),
..Default::default()
}),
err: None,
})
.await
.is_err()
{
debug!(
bucket = %opts.bucket,
prefix = %opts.prefix,
"list_objects gather_results consumer disconnected before limited page delivery"
);
return Ok(GatherResultsState::ConsumerGone);
}
return Ok(GatherResultsState::LimitReached);
}
}
let producer_limit_reached = opts
.producer_limit_reached
.as_ref()
.is_some_and(|reached| reached.load(Ordering::Acquire));
let filtered = scanned_entries.saturating_sub(candidate_entries);
if let Some(started) = gather_started {
let duration_ms = started.elapsed().as_secs_f64() * 1000.0;
rustfs_io_metrics::record_list_objects_gather(ListObjectsGatherObservation {
source: LIST_OBJECTS_SOURCE_WALKER,
outcome: LIST_OBJECTS_GATHER_OUTCOME_INPUT_CLOSED,
limit: opts.limit,
scanned_entries,
returned_entries: candidate_entries,
duration_ms,
has_prefix: !opts.prefix.is_empty(),
has_delimiter: opts.separator.as_ref().is_some_and(|separator| !separator.is_empty()),
has_marker: opts.marker.is_some(),
});
rustfs_io_metrics::record_stage_duration("store_list_objects_gather", duration_ms);
}
debug!(
bucket = %opts.bucket,
prefix = %opts.prefix,
scanned_entries = scanned_entries,
returned_entries = candidate_entries,
filtered_entries = filtered,
marker = %opts.marker.as_deref().unwrap_or(""),
"list_objects gather_results drained all candidates without hitting limit"
);
if results_tx
.send(MetaCacheEntriesSortedResult {
entries: Some(MetaCacheEntriesSorted {
o: MetaCacheEntries(entries),
..Default::default()
}),
err: (!producer_limit_reached).then_some(rustfs_filemeta::Error::Unexpected),
})
.await
.is_err()
{
debug!(
bucket = %opts.bucket,
prefix = %opts.prefix,
"list_objects gather_results consumer disconnected before eof page delivery"
);
return Ok(GatherResultsState::ConsumerGone);
}
Ok(GatherResultsState::InputClosed)
}
struct MergeHead {
entry: MetaCacheEntry,
idx: usize,
}
impl MergeHead {
fn new(entry: MetaCacheEntry, idx: usize) -> Self {
let mut entry = entry;
let cleaned = path::clean(&entry.name);
if !cleaned.is_empty() && cleaned != "." && cleaned != entry.name {
let canonical = if entry.name.ends_with(SLASH_SEPARATOR) {
format!("{cleaned}{SLASH_SEPARATOR}")
} else {
cleaned
};
if canonical != entry.name {
entry.name = canonical;
}
}
Self { entry, idx }
}
fn sort_key(&self) -> &str {
&self.entry.name
}
}
impl PartialEq for MergeHead {
fn eq(&self, other: &Self) -> bool {
self.cmp(other) == std::cmp::Ordering::Equal
}
}
impl Eq for MergeHead {}
impl PartialOrd for MergeHead {
fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
Some(self.cmp(other))
}
}
impl Ord for MergeHead {
fn cmp(&self, other: &Self) -> std::cmp::Ordering {
self.sort_key().cmp(other.sort_key()).then_with(|| self.idx.cmp(&other.idx))
}
}
enum MergePoll {
Entry(Box<MergeHead>),
Closed,
Cancelled,
}
async fn poll_merge_head(rx: &CancellationToken, in_channels: &mut [Receiver<MetaCacheEntry>], idx: usize) -> MergePoll {
tokio::select! {
entry = in_channels[idx].recv() => match entry {
Some(entry) => MergePoll::Entry(Box::new(MergeHead::new(entry, idx))),
None => MergePoll::Closed,
},
_ = rx.cancelled() => MergePoll::Cancelled,
}
}
async fn send_or_cancel(rx: &CancellationToken, out_channel: &Sender<MetaCacheEntry>, entry: MetaCacheEntry) -> Result<bool> {
tokio::select! {
result = out_channel.send(entry) => Ok(result.is_ok()),
_ = rx.cancelled() => Ok(false),
}
}
fn merge_object_entry_versions(first: &mut MetaCacheEntry, others: impl Iterator<Item = MetaCacheEntry>) -> Result<()> {
let name = first.name.clone();
let mut versions: HashMap<(Option<Uuid>, bool), (FileMetaShallowVersion, ObjectInfo)> = HashMap::new();
for mut entry in std::iter::once(std::mem::take(first)).chain(others) {
let meta = match entry.cached.take() {
Some(meta) => meta,
None => FileMeta::load(&entry.metadata).map_err(|_| Error::FileCorrupt)?,
};
if meta.versions.is_empty() {
return Err(Error::FileCorrupt);
}
for version in meta.versions {
let parsed = version.parse_version_meta().map_err(|_| Error::FileCorrupt)?;
if !parsed.valid() || parsed.version_type != version.header.version_type {
return Err(Error::FileCorrupt);
}
let fi = parsed.into_fileinfo("", &name, true).map_err(|_| Error::FileCorrupt)?;
let version_id = fi.version_id.filter(|id| !id.is_nil());
if version_id != version.header.version_id.filter(|id| !id.is_nil())
|| fi.mod_time != version.header.mod_time
|| fi.tier_free_version() != version.header.free_version()
{
return Err(Error::FileCorrupt);
}
let info = ObjectInfo::from_file_info(&fi, "", &name, true);
let identity = (version_id, version.header.free_version());
match versions.entry(identity) {
std::collections::hash_map::Entry::Vacant(slot) => {
slot.insert((version, info));
}
std::collections::hash_map::Entry::Occupied(mut slot) => {
let (previous, previous_info) = slot.get();
if version_id.is_none() && info.mod_time != previous_info.mod_time {
if info.mod_time > previous_info.mod_time {
slot.insert((version, info));
}
continue;
}
let equivalent = if info.delete_marker && previous_info.delete_marker {
super::object::is_equivalent_data_movement_delete_marker(&info, previous_info)
} else {
crate::data_movement::is_equivalent_data_movement_object_identity(&info, previous_info, true, true)
};
if !equivalent {
return Err(Error::FileCorrupt);
}
if version.meta < previous.meta {
slot.insert((version, info));
}
}
}
}
}
let mut live_remote_references = HashMap::<String, HashMap<String, Vec<ObjectInfo>>>::new();
for (_, info) in versions.values() {
if !info.transitioned_object.free_version && info.transitioned_object.status == rustfs_filemeta::TRANSITION_COMPLETE {
live_remote_references
.entry(info.transitioned_object.tier.clone())
.or_default()
.entry(info.transitioned_object.name.clone())
.or_default()
.push(info.clone());
}
}
versions.retain(|_, (_, info)| {
!info.transitioned_object.free_version
|| !live_remote_references
.get(info.transitioned_object.tier.as_str())
.and_then(|by_name| by_name.get(info.transitioned_object.name.as_str()))
.is_some_and(|candidates| {
candidates
.iter()
.any(|live| free_version_remote_tuple_matches(info, live).unwrap_or(false))
})
});
let mut merged = FileMeta::new();
merged.versions = versions.into_values().map(|(version, _)| version).collect();
merged.versions.sort_by(|a, b| {
if a.header.sorts_before(&b.header) {
std::cmp::Ordering::Less
} else if b.header.sorts_before(&a.header) {
std::cmp::Ordering::Greater
} else {
std::cmp::Ordering::Equal
}
});
let metadata = merged.marshal_msg()?;
*first = MetaCacheEntry {
name,
metadata,
cached: Some(merged),
reusable: true,
};
Ok(())
}
fn spawn_listing_merge(
rx: CancellationToken,
inputs: Vec<Receiver<MetaCacheEntry>>,
sender: Sender<MetaCacheEntry>,
) -> JoinHandle<Result<()>> {
tokio::spawn(
async move {
let result = merge_entry_channels(rx.clone(), inputs, sender, 1).await;
if result.is_err() {
rx.cancel();
}
result
}
.instrument(tracing::Span::current()),
)
}
async fn merge_entry_channels(
rx: CancellationToken,
in_channels: Vec<Receiver<MetaCacheEntry>>,
out_channel: Sender<MetaCacheEntry>,
read_quorum: usize,
) -> Result<()> {
if in_channels.is_empty() {
return Ok(());
}
rustfs_io_metrics::record_list_objects_merge(LIST_OBJECTS_SOURCE_WALKER, in_channels.len(), read_quorum);
let mut in_channels = in_channels;
if in_channels.len() == 1 {
loop {
tokio::select! {
has_entry = in_channels[0].recv()=>{
if let Some(entry) = has_entry{
if !send_or_cancel(&rx, &out_channel, entry).await? {
return Ok(());
}
} else {
return Ok(())
}
},
_ = rx.cancelled()=>{
info!("merge_entry_channels rx.recv() cancel");
return Ok(())
},
}
}
}
let mut heap: BinaryHeap<Reverse<Box<MergeHead>>> = BinaryHeap::with_capacity(in_channels.len());
for idx in 0..in_channels.len() {
match poll_merge_head(&rx, &mut in_channels, idx).await {
MergePoll::Entry(head) => heap.push(Reverse(head)),
MergePoll::Closed => {}
MergePoll::Cancelled => {
info!("merge_entry_channels rx.recv() cancel");
return Ok(());
}
}
}
let mut last_emitted = String::new();
let mut group: Vec<Box<MergeHead>> = Vec::new();
let mut object_entries: Vec<MetaCacheEntry> = Vec::new();
let mut refill: Vec<usize> = Vec::with_capacity(in_channels.len());
while let Some(Reverse(first)) = heap.pop() {
group.clear();
refill.clear();
refill.push(first.idx);
while heap.peek().is_some_and(|Reverse(next)| next.sort_key() == first.sort_key()) {
let Some(Reverse(next)) = heap.pop() else { break };
refill.push(next.idx);
group.push(next);
}
let mut dir_winner: Option<Box<MergeHead>> = None;
let mut object_winner: Option<Box<MergeHead>> = None;
for head in std::iter::once(first).chain(group.drain(..)) {
if head.entry.is_dir() {
if dir_winner.is_none() {
dir_winner = Some(head);
}
} else if let Some(winner) = object_winner.as_ref() {
if head.entry.is_object() {
if winner.entry.is_object() {
object_entries.push(head.entry);
} else {
object_winner = Some(head);
}
}
} else {
object_winner = Some(head);
}
}
if !object_entries.is_empty()
&& let Some(winner) = object_winner.as_mut()
{
merge_object_entry_versions(&mut winner.entry, object_entries.drain(..))?;
}
if let Some(head) = object_winner.or(dir_winner)
&& head.entry.name != last_emitted
{
last_emitted.clear();
last_emitted.push_str(&head.entry.name);
let MergeHead { entry, .. } = *head;
if !send_or_cancel(&rx, &out_channel, entry).await? {
return Ok(());
}
}
for &idx in &refill {
match poll_merge_head(&rx, &mut in_channels, idx).await {
MergePoll::Entry(head) => heap.push(Reverse(head)),
MergePoll::Closed => {}
MergePoll::Cancelled => {
info!("merge_entry_channels rx.recv() cancel");
return Ok(());
}
}
}
}
Ok(())
}
impl Sets {
#[allow(clippy::too_many_arguments)]
pub async fn inner_list_objects_v2(
self: Arc<Self>,
bucket: &str,
prefix: &str,
continuation_token: Option<String>,
delimiter: Option<String>,
max_keys: i32,
_fetch_owner: bool,
start_after: Option<String>,
incl_deleted: bool,
) -> Result<ListObjectsV2Info> {
let marker = if continuation_token.is_none() {
start_after
} else {
continuation_token.clone()
};
let loi = self
.list_objects_generic(bucket, prefix, marker, delimiter, max_keys, incl_deleted)
.await?;
Ok(ListObjectsV2Info {
is_truncated: loi.is_truncated,
continuation_token,
next_continuation_token: loi.next_marker,
objects: loi.objects,
prefixes: loi.prefixes,
})
}
pub async fn list_objects_generic(
self: Arc<Self>,
bucket: &str,
prefix: &str,
marker: Option<String>,
delimiter: Option<String>,
max_keys: i32,
incl_deleted: bool,
) -> Result<ListObjectsInfo> {
let max_keys = normalize_max_keys(max_keys);
let effective_max_keys = if max_keys <= 0 { 0 } else { max_keys_plus_one(max_keys, true) };
let mut opts = ListPathOptions {
bucket: bucket.to_owned(),
prefix: prefix.to_owned(),
separator: delimiter.clone(),
limit: effective_max_keys,
marker,
incl_deleted,
ask_disks: list_objects_quorum_from_env(),
..Default::default()
};
opts.parse_marker();
let mut list_result = self
.list_path(&opts)
.await
.unwrap_or_else(|err| MetaCacheEntriesSortedResult {
err: Some(to_filemeta_err(err)),
..Default::default()
});
let next_cache_id = list_result.entries.as_ref().and_then(|entries| entries.list_id.clone());
let disk_has_more = list_result.err.is_none();
if let Some(err) = list_result.err.take()
&& err != rustfs_filemeta::Error::Unexpected
{
return Err(to_object_err(err.into(), vec![bucket, prefix]));
}
if let Some(result) = list_result.entries.as_mut() {
result.forward_past(opts.marker);
}
let last_scanned_key = last_scanned_entry_name(list_result.entries.as_ref());
let get_objects = ObjectInfo::from_meta_cache_entries_sorted_infos(
&list_result.entries.unwrap_or_default(),
bucket,
prefix,
delimiter.clone(),
)
.await;
let (objects, prefixes, is_truncated, next_marker, next_version_idmarker) = list_objects_paginate(
get_objects,
&delimiter,
max_keys,
disk_has_more,
next_cache_id.as_deref(),
false,
last_scanned_key.as_deref(),
);
let _ = next_version_idmarker;
Ok(ListObjectsInfo {
is_truncated,
next_marker,
objects,
prefixes,
})
}
pub async fn inner_list_object_versions(
self: Arc<Self>,
bucket: &str,
prefix: &str,
marker: Option<String>,
version_marker: Option<String>,
delimiter: Option<String>,
max_keys: i32,
) -> Result<ListObjectVersionsInfo> {
let max_keys = normalize_max_keys(max_keys);
if marker.is_none() && version_marker.is_some() {
return Err(StorageError::NotImplemented);
}
let has_version_marker = version_marker.is_some();
let version_marker = if let Some(marker) = version_marker {
Some(parse_version_marker(marker)?)
} else {
None
};
let effective_max_keys = list_versions_scan_limit(max_keys, has_version_marker);
let mut opts = ListPathOptions {
bucket: bucket.to_owned(),
prefix: prefix.to_owned(),
separator: delimiter.clone(),
limit: effective_max_keys,
marker,
incl_deleted: true,
ask_disks: list_objects_quorum_from_env(),
versioned: true,
include_marker: has_version_marker,
..Default::default()
};
opts.parse_marker();
let mut list_result = self
.list_path(&opts)
.await
.unwrap_or_else(|err| MetaCacheEntriesSortedResult {
err: Some(to_filemeta_err(err)),
..Default::default()
});
let next_cache_id = list_result.entries.as_ref().and_then(|entries| entries.list_id.clone());
let disk_has_more = list_result.err.is_none();
if let Some(err) = list_result.err.take()
&& err != rustfs_filemeta::Error::Unexpected
{
return Err(to_object_err(err.into(), vec![bucket, prefix]));
}
if let Some(result) = list_result.entries.as_mut()
&& !has_version_marker
{
result.forward_past(opts.marker.clone());
}
let version_marker = version_marker_for_entries(list_result.entries.as_ref(), opts.marker.as_deref(), version_marker);
let last_scanned_key = last_scanned_entry_name(list_result.entries.as_ref());
let get_objects = ObjectInfo::from_meta_cache_entries_sorted_versions(
&list_result.entries.unwrap_or_default(),
bucket,
prefix,
delimiter.clone(),
version_marker,
)
.await;
let (objects, prefixes, is_truncated, next_marker, next_version_idmarker) = list_objects_paginate(
get_objects,
&delimiter,
max_keys,
disk_has_more,
next_cache_id.as_deref(),
true,
last_scanned_key.as_deref(),
);
Ok(ListObjectVersionsInfo {
is_truncated,
next_marker,
next_version_idmarker,
objects,
prefixes,
})
}
pub async fn list_path(self: Arc<Self>, o: &ListPathOptions) -> Result<MetaCacheEntriesSortedResult> {
check_list_objs_args(&o.bucket, &o.prefix, &o.marker)?;
let list_path_started = std::time::Instant::now();
let mut o = o.clone();
o.marker = o.marker.filter(|v| v >= &o.prefix);
if let Some(marker) = &o.marker
&& !o.prefix.is_empty()
&& !marker.starts_with(&o.prefix)
{
return Err(Error::Unexpected);
}
if o.limit == 0 {
return Err(Error::Unexpected);
}
if o.prefix.starts_with(SLASH_SEPARATOR) {
return Err(Error::Unexpected);
}
let slash_separator = Some(SLASH_SEPARATOR.to_owned());
o.include_directories = o.separator == slash_separator;
if (o.separator == slash_separator || o.separator.is_none()) && !o.recursive {
o.recursive = o.separator != slash_separator;
o.separator = slash_separator;
} else {
o.recursive = true;
}
o.skip_hidden_prefix_check = can_skip_hidden_prefix_check(&o).await;
o.parse_marker();
if o.base_dir.is_empty() {
o.base_dir = base_dir_from_prefix(&o.prefix);
}
o.transient = o.transient || is_reserved_or_invalid_bucket(&o.bucket, false);
o.set_filter();
if o.transient {
o.create = false;
}
let log_context = ListPathLogContext::from_options(&o);
let cancel = CancellationToken::new();
let _cancel_guard = cancel.clone().drop_guard();
let (err_tx, mut err_rx) = broadcast::channel::<Arc<Error>>(1);
let (sender, recv) = mpsc::channel(o.limit as usize);
ensure_producer_limit_state(&mut o);
let sets = self.clone();
let opts = o.clone();
let cancel_rx1 = cancel.clone();
let cancel_rx1_for_err = cancel_rx1.clone();
let err_tx1 = err_tx.clone();
let job1_context = log_context.clone();
let job1 = tokio::spawn(
async move {
let mut opts = opts;
opts.stop_disk_at_limit = true;
if let Err(err) = sets.list_merged(cancel_rx1, opts, sender).await
&& !cancel_rx1_for_err.is_cancelled()
{
log_list_path_worker_error("sets", "list_merged", &job1_context, &err);
let _ = err_tx1.send(Arc::new(err));
}
}
.instrument(tracing::Span::current()),
);
let cancel_rx2 = cancel.clone();
let (result_tx, mut result_rx) = mpsc::channel(1);
let err_tx2 = err_tx.clone();
let opts = o.clone();
let job2_context = log_context.clone();
let job2 = tokio::spawn(
async move {
match gather_results(cancel_rx2, opts, recv, result_tx).await {
Ok(GatherResultsState::LimitReached) => cancel.cancel(),
Ok(GatherResultsState::InputClosed) => {}
Ok(GatherResultsState::ConsumerGone) => cancel.cancel(),
Err(err) => {
log_list_path_worker_error("sets", "gather_results", &job2_context, &err);
let _ = err_tx2.send(Arc::new(err));
cancel.cancel();
}
}
}
.instrument(tracing::Span::current()),
);
let mut result = tokio::select! {
res = err_rx.recv() => {
match res {
Ok(err) => {
log_list_path_worker_error("sets", "worker_error", &log_context, err.as_ref());
MetaCacheEntriesSortedResult { entries: None, err: Some(to_filemeta_err(err.as_ref().clone())) }
},
Err(err) => {
log_list_path_worker_error("sets", "error_channel_closed", &log_context, &err);
MetaCacheEntriesSortedResult { entries: None, err: Some(rustfs_filemeta::Error::other(err)) }
},
}
}
Some(result) = result_rx.recv() => result,
};
join_all(vec![job1, job2]).await;
if let Ok(err) = err_rx.try_recv() {
log_list_path_worker_error("sets", "trailing_worker_error", &log_context, err.as_ref());
result.err = Some(to_filemeta_err(err.as_ref().clone()));
}
if result.err.is_some() {
log_list_path_finished("sets", &log_context, list_path_started.elapsed().as_secs_f64() * 1000.0, 0, true);
return Ok(result);
}
if let Some(entries) = result.entries.as_mut() {
entries.reuse = true;
let truncated = !entries.entries().is_empty() || result.err.is_none();
entries.o.0.truncate(o.limit as usize);
if !o.transient && truncated {
entries.list_id = if let Some(id) = o.id {
Some(id)
} else {
Some(Uuid::new_v4().to_string())
};
}
if !truncated {
result.err = Some(rustfs_filemeta::Error::Unexpected);
}
}
log_list_path_finished(
"sets",
&log_context,
list_path_started.elapsed().as_secs_f64() * 1000.0,
result
.entries
.as_ref()
.map(|entries| entries.entries().len())
.unwrap_or_default(),
result.err.is_some(),
);
Ok(result)
}
async fn list_merged(
&self,
rx: CancellationToken,
opts: ListPathOptions,
sender: Sender<MetaCacheEntry>,
) -> Result<Vec<ObjectInfo>> {
let merge_started = std::time::Instant::now();
debug!(
list_path_limit = opts.limit,
recursive = opts.recursive,
set_count = self.disk_set.len(),
requested_marker = %opts.marker.as_deref().unwrap_or(""),
"sets list_merged started"
);
let rx = rx.child_token();
let mut futures = Vec::new();
let mut inputs = Vec::new();
for set in &self.disk_set {
let (send, recv) = list_merged_entry_channel();
inputs.push(recv);
let opts = opts.clone();
let rx_clone = rx.clone();
let set = set.clone();
futures.push(async move { set.list_path(rx_clone, opts, send).await });
}
let merge_task = spawn_listing_merge(rx, inputs, sender);
let results = join_all(futures).await;
merge_task.await.map_err(Error::from)??;
let mut all_at_eof = true;
let mut errs = Vec::new();
for result in results {
if let Err(err) = result {
all_at_eof = false;
errs.push(Some(err));
} else {
errs.push(None);
}
}
if is_all_not_found(&errs) {
return Ok(Vec::new());
}
for err in &errs {
if let Some(err) = err {
if err == &Error::Unexpected {
continue;
}
return Err(err.clone());
} else {
all_at_eof = false;
}
}
rustfs_io_metrics::record_stage_duration("sets_list_objects_list_merged", merge_started.elapsed().as_secs_f64() * 1000.0);
debug!(
set_count = self.disk_set.len(),
all_at_eof = all_at_eof,
error_count = errs.iter().filter(|err| err.is_some()).count(),
"sets list_merged finished"
);
_ = all_at_eof;
Ok(Vec::new())
}
#[allow(unused_assignments)]
pub async fn walk_internal(
self: Arc<Self>,
rx: CancellationToken,
bucket: &str,
prefix: &str,
result: Sender<ObjectInfoOrErr>,
opts: WalkOptions,
) -> Result<()> {
check_list_objs_args(bucket, prefix, &None)?;
let rx = rx.child_token();
let mut futures = Vec::new();
let mut inputs = Vec::new();
for set in &self.disk_set {
let (mut disks, infos, _) = set.get_online_disks_with_healing_and_info(true).await;
let online_disks = disks.len();
let opts = opts.clone();
let (sender, list_out_rx) = mpsc::channel::<MetaCacheEntry>(1);
inputs.push(list_out_rx);
let rx_clone = rx.clone();
let set = set.clone();
futures.push(async move {
let mut ask_disks = get_list_quorum(&opts.ask_disks, set.set_drive_count as i32);
if ask_disks == -1 {
let new_disks = get_quorum_disks(&disks, &infos, disks.len().div_ceil(2));
if !new_disks.is_empty() {
disks = new_disks;
} else {
ask_disks = get_list_quorum("strict", set.set_drive_count as i32);
}
}
if set.set_drive_count == 4 {
ask_disks = bounded_usize_to_i32(disks.len());
} else if ask_disks > bounded_usize_to_i32(disks.len()) {
ask_disks = clamp_ask_disks_to_available(ask_disks, disks.len());
}
let listing_quorum = listing_quorum_from_ask_disks(ask_disks);
let enforce_write_quorum = enforce_latest_listing_write_quorum(opts.latest_only, &opts.ask_disks);
let write_quorum_parity = set.default_parity_count;
let write_quorum_slack =
latest_listing_write_quorum_slack(enforce_write_quorum, set.set_drive_count, online_disks);
let required_obj_quorum = latest_listing_required_object_quorum(
listing_quorum,
set.set_drive_count,
write_quorum_parity,
enforce_write_quorum,
write_quorum_slack,
);
ask_disks = expand_ask_disks_for_object_quorum(ask_disks, disks.len(), required_obj_quorum);
let fallback_disks = if let Some(asked_disks) = positive_ask_disks(ask_disks)
&& disks.len() > asked_disks
{
let mut rand = rand::rng();
disks.shuffle(&mut rand);
disks.split_off(asked_disks)
} else {
Vec::new()
};
let fallback_disks = Arc::new(fallback_disks);
let disks = Arc::new(disks);
let claim_tracker = FallbackClaimTracker::default();
let obj_quorum = latest_listing_object_quorum(
listing_quorum,
set.set_drive_count,
write_quorum_parity,
enforce_write_quorum,
write_quorum_slack,
);
let raw_min_disks = latest_listing_raw_min_disks(listing_quorum, obj_quorum, enforce_write_quorum);
let resolver = list_metadata_resolution_params(
bucket.to_owned(),
listing_quorum,
obj_quorum,
!opts.latest_only,
write_quorum_slack,
);
let agreed_resolver = resolver.clone();
let partial_resolver = resolver.clone();
let reader_disks = disks.len();
let path = base_dir_from_prefix(prefix);
ensure_non_empty_listing_disks(bucket, &path, &disks).map_err(to_filemeta_err)?;
let mut filter_prefix = prefix
.trim_start_matches(&path)
.trim_start_matches(SLASH_SEPARATOR)
.trim_end_matches(SLASH_SEPARATOR)
.to_owned();
if filter_prefix == path {
filter_prefix = "".to_owned();
}
let tx1 = sender.clone();
let tx2 = sender.clone();
let supplement = ListingSupplement::new_with_reconciler(
ListingSupplementOptions {
bucket: bucket.to_owned(),
path: path.clone(),
recursive: true,
incl_deleted: !opts.latest_only,
skip_hidden_prefix_check: false,
filter_prefix: Some(filter_prefix.clone()),
forward_to: opts.marker.clone(),
per_disk_limit: bounded_usize_to_i32(opts.limit),
skip_total_timeout: opts.walkdir_timeout.is_none(),
walkdir_timeout: opts.walkdir_timeout,
walkdir_stall_timeout: opts.walkdir_stall_timeout,
},
fallback_disks.clone(),
claim_tracker.clone(),
set.as_ref().clone(),
disks.clone(),
);
let agreed_supplement = supplement.clone();
let partial_supplement = supplement;
list_path_raw_with_partial_result(
rx_clone,
ListPathRawOptions {
disks: disks.iter().cloned().map(Some).collect(),
fallback_disks: fallback_disks.iter().cloned().map(Some).collect(),
bucket: bucket.to_owned(),
path,
recursive: true,
incl_deleted: !opts.latest_only,
filter_prefix: Some(filter_prefix),
forward_to: opts.marker.clone(),
min_disks: raw_min_disks,
per_disk_limit: bounded_usize_to_i32(opts.limit),
skip_walkdir_total_timeout: opts.walkdir_timeout.is_none(),
walkdir_timeout: opts.walkdir_timeout,
walkdir_stall_timeout: opts.walkdir_stall_timeout,
agreed: Some(Box::new(move |entry: MetaCacheEntry| {
Box::pin({
let value = tx1.clone();
let resolver = agreed_resolver.clone();
let supplement = agreed_supplement.clone();
async move {
let entry = match resolve_agreed_listing_entry(
entry,
reader_disks,
resolver.clone(),
enforce_write_quorum,
) {
ListingEntryResolution::Resolved(entry) => entry,
ListingEntryResolution::NeedsSupplement(entry, fallback) => {
let Some(entry) = resolve_agreed_listing_entry_with_supplement(
entry,
reader_disks,
resolver,
enforce_write_quorum,
supplement,
)
.await
.or(fallback) else {
return;
};
entry
}
ListingEntryResolution::Rejected => return,
};
if entry.is_dir() {
return;
}
if let Err(err) = value.send(entry).await {
error!("list_path send fail {:?}", err);
}
}
})
})),
finished: None,
..Default::default()
},
claim_tracker,
Box::new(move |entries: MetaCacheEntries, _: &[Option<DiskError>]| {
Box::pin({
let value = tx2.clone();
let resolver = partial_resolver.clone();
let supplement = partial_supplement.clone();
async move {
if let Some(entry) =
resolve_listing_entries_with_supplement(entries, resolver, enforce_write_quorum, supplement)
.await?
&& let Err(err) = value.send(entry).await
{
error!("list_path send fail {:?}", err);
}
Ok(())
}
})
}),
)
.await
});
}
let (merge_tx, mut merge_rx) = mpsc::channel::<MetaCacheEntry>(100);
let bucket = bucket.to_owned();
let bucket_clone = bucket.clone();
let vcf = match get_versioning_config(&bucket).await {
Ok((res, _)) => Some(res),
Err(_) => None,
};
tokio::spawn(
async move {
let mut sent_err = false;
while let Some(entry) = merge_rx.recv().await {
if opts.latest_only {
let fi = match entry.to_fileinfo(&bucket_clone) {
Ok(res) => res,
Err(err) => {
if !sent_err {
let item = ObjectInfoOrErr {
item: None,
err: Some(err.into()),
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
sent_err = true;
return;
}
continue;
}
};
if let Some(filter) = opts.filter {
if filter(&fi) {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(&fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
} else {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(&fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
continue;
}
let fvs = match if opts.include_free_versions {
entry.file_info_versions_with_free_versions(&bucket_clone)
} else {
entry.file_info_versions(&bucket_clone)
} {
Ok(res) => res,
Err(err) => {
let item = ObjectInfoOrErr {
item: None,
err: Some(err.into()),
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
return;
}
};
for fi in &fvs.versions {
if let Some(filter) = opts.filter {
if filter(fi) {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
} else {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
}
if opts.include_free_versions {
for fi in &fvs.free_versions {
if let Some(filter) = opts.filter {
if filter(fi) {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
} else {
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_clone, &fi.name, {
if let Some(v) = &vcf { v.versioned(&fi.name) } else { false }
})),
err: None,
};
if let Err(err) = result.send(item).await {
error!("walk result send err {:?}", err);
}
}
}
}
}
}
.instrument(tracing::Span::current()),
);
let merge_task = spawn_listing_merge(rx, inputs, merge_tx);
let walk_started = std::time::Instant::now();
let walk_results = join_all(futures).await;
merge_task.await.map_err(Error::from)??;
let mut errs = Vec::new();
for walk_result in walk_results {
match walk_result {
Ok(()) => errs.push(None),
Err(err) => errs.push(Some(err.into())),
}
}
rustfs_io_metrics::record_stage_duration(
"sets_list_objects_walk_internal",
walk_started.elapsed().as_secs_f64() * 1000.0,
);
let result = walk_result_from_set_errors(&errs);
if let Err(err) = &result {
error!(
bucket = %bucket,
prefix = %prefix,
error = ?err,
set_errors = ?errs,
"walk_internal list_path_raw tasks failed"
);
}
result
}
}
impl SetDisks {
pub(crate) async fn inner_list_object_versions_for_recursive_delete(
self: Arc<Self>,
bucket: &str,
prefix: &str,
marker: Option<String>,
version_marker: Option<String>,
max_keys: i32,
) -> Result<ListObjectVersionsInfo> {
let max_keys = normalize_max_keys(max_keys);
if marker.is_none() && version_marker.is_some() {
return Err(StorageError::NotImplemented);
}
let has_version_marker = version_marker.is_some();
let version_marker = version_marker.map(parse_version_marker).transpose()?;
let effective_max_keys = list_versions_scan_limit(max_keys, has_version_marker);
let mut opts = ListPathOptions {
bucket: bucket.to_owned(),
prefix: prefix.to_owned(),
limit: effective_max_keys,
marker,
incl_deleted: true,
ask_disks: list_objects_quorum_from_env(),
versioned: true,
include_marker: has_version_marker,
..Default::default()
};
opts.parse_marker();
let mut list_result = self
.list_path_result(&opts)
.await
.unwrap_or_else(|err| MetaCacheEntriesSortedResult {
err: Some(to_filemeta_err(err)),
..Default::default()
});
let next_cache_id = list_result.entries.as_ref().and_then(|entries| entries.list_id.clone());
let disk_has_more = list_result.err.is_none();
if let Some(err) = list_result.err.take()
&& err != rustfs_filemeta::Error::Unexpected
{
return Err(to_object_err(err.into(), vec![bucket, prefix]));
}
if let Some(result) = list_result.entries.as_mut()
&& !has_version_marker
{
result.forward_past(opts.marker.clone());
}
let version_marker = version_marker_for_entries(list_result.entries.as_ref(), opts.marker.as_deref(), version_marker);
let last_scanned_key = last_scanned_entry_name(list_result.entries.as_ref());
let entries = list_result.entries.unwrap_or_default();
let get_objects = ObjectInfo::from_meta_cache_entries_sorted_versions_for_recursive_delete(
&entries,
bucket,
prefix,
None,
version_marker,
)
.await?;
let (objects, prefixes, is_truncated, next_marker, next_version_idmarker) = list_objects_paginate(
get_objects,
&None,
max_keys,
disk_has_more,
next_cache_id.as_deref(),
true,
last_scanned_key.as_deref(),
);
Ok(ListObjectVersionsInfo {
is_truncated,
next_marker,
next_version_idmarker,
objects,
prefixes,
})
}
#[allow(clippy::too_many_arguments)]
pub async fn inner_list_objects_v2(
self: Arc<Self>,
bucket: &str,
prefix: &str,
continuation_token: Option<String>,
delimiter: Option<String>,
max_keys: i32,
_fetch_owner: bool,
start_after: Option<String>,
incl_deleted: bool,
) -> Result<ListObjectsV2Info> {
let marker = if continuation_token.is_none() {
start_after
} else {
continuation_token.clone()
};
let loi = self
.list_objects_generic(bucket, prefix, marker, delimiter, max_keys, incl_deleted)
.await?;
Ok(ListObjectsV2Info {
is_truncated: loi.is_truncated,
continuation_token,
next_continuation_token: loi.next_marker,
objects: loi.objects,
prefixes: loi.prefixes,
})
}
pub async fn list_objects_generic(
self: Arc<Self>,
bucket: &str,
prefix: &str,
marker: Option<String>,
delimiter: Option<String>,
max_keys: i32,
incl_deleted: bool,
) -> Result<ListObjectsInfo> {
let max_keys = normalize_max_keys(max_keys);
let effective_max_keys = if max_keys <= 0 { 0 } else { max_keys_plus_one(max_keys, true) };
let mut opts = ListPathOptions {
bucket: bucket.to_owned(),
prefix: prefix.to_owned(),
separator: delimiter.clone(),
limit: effective_max_keys,
marker,
incl_deleted,
ask_disks: list_objects_quorum_from_env(),
..Default::default()
};
opts.parse_marker();
let mut list_result = self
.list_path_result(&opts)
.await
.unwrap_or_else(|err| MetaCacheEntriesSortedResult {
err: Some(to_filemeta_err(err)),
..Default::default()
});
let next_cache_id = list_result.entries.as_ref().and_then(|entries| entries.list_id.clone());
let disk_has_more = list_result.err.is_none();
if let Some(err) = list_result.err.take()
&& err != rustfs_filemeta::Error::Unexpected
{
return Err(to_object_err(err.into(), vec![bucket, prefix]));
}
if let Some(result) = list_result.entries.as_mut() {
result.forward_past(opts.marker);
}
let last_scanned_key = last_scanned_entry_name(list_result.entries.as_ref());
let get_objects = ObjectInfo::from_meta_cache_entries_sorted_infos(
&list_result.entries.unwrap_or_default(),
bucket,
prefix,
delimiter.clone(),
)
.await;
let (objects, prefixes, is_truncated, next_marker, _next_version_idmarker) = list_objects_paginate(
get_objects,
&delimiter,
max_keys,
disk_has_more,
next_cache_id.as_deref(),
false,
last_scanned_key.as_deref(),
);
Ok(ListObjectsInfo {
is_truncated,
next_marker,
objects,
prefixes,
})
}
pub async fn inner_list_object_versions(
self: Arc<Self>,
bucket: &str,
prefix: &str,
marker: Option<String>,
version_marker: Option<String>,
delimiter: Option<String>,
max_keys: i32,
) -> Result<ListObjectVersionsInfo> {
let max_keys = normalize_max_keys(max_keys);
if marker.is_none() && version_marker.is_some() {
return Err(StorageError::NotImplemented);
}
let has_version_marker = version_marker.is_some();
let version_marker = if let Some(marker) = version_marker {
Some(parse_version_marker(marker)?)
} else {
None
};
let effective_max_keys = list_versions_scan_limit(max_keys, has_version_marker);
let mut opts = ListPathOptions {
bucket: bucket.to_owned(),
prefix: prefix.to_owned(),
separator: delimiter.clone(),
limit: effective_max_keys,
marker,
incl_deleted: true,
ask_disks: list_objects_quorum_from_env(),
versioned: true,
include_marker: has_version_marker,
..Default::default()
};
opts.parse_marker();
let mut list_result = self
.list_path_result(&opts)
.await
.unwrap_or_else(|err| MetaCacheEntriesSortedResult {
err: Some(to_filemeta_err(err)),
..Default::default()
});
let next_cache_id = list_result.entries.as_ref().and_then(|entries| entries.list_id.clone());
let disk_has_more = list_result.err.is_none();
if let Some(err) = list_result.err.take()
&& err != rustfs_filemeta::Error::Unexpected
{
return Err(to_object_err(err.into(), vec![bucket, prefix]));
}
if let Some(result) = list_result.entries.as_mut()
&& !has_version_marker
{
result.forward_past(opts.marker.clone());
}
let version_marker = version_marker_for_entries(list_result.entries.as_ref(), opts.marker.as_deref(), version_marker);
let last_scanned_key = last_scanned_entry_name(list_result.entries.as_ref());
let get_objects = ObjectInfo::from_meta_cache_entries_sorted_versions(
&list_result.entries.unwrap_or_default(),
bucket,
prefix,
delimiter.clone(),
version_marker,
)
.await;
let (objects, prefixes, is_truncated, next_marker, next_version_idmarker) = list_objects_paginate(
get_objects,
&delimiter,
max_keys,
disk_has_more,
next_cache_id.as_deref(),
true,
last_scanned_key.as_deref(),
);
Ok(ListObjectVersionsInfo {
is_truncated,
next_marker,
next_version_idmarker,
objects,
prefixes,
})
}
pub async fn walk_internal(
self: Arc<Self>,
rx: CancellationToken,
bucket: &str,
prefix: &str,
result: Sender<ObjectInfoOrErr>,
opts: WalkOptions,
) -> Result<()> {
check_list_objs_args(bucket, prefix, &None)?;
let (entry_tx, mut entry_rx) = mpsc::channel::<MetaCacheEntry>(100);
let bucket_name = bucket.to_owned();
let bucket_name_for_list = bucket_name.clone();
let versioning_config = match get_versioning_config(&bucket_name).await {
Ok((res, _)) => Some(res),
Err(_) => None,
};
let result_task = tokio::spawn(
async move {
while let Some(entry) = entry_rx.recv().await {
if opts.latest_only {
let fi = match entry.to_fileinfo(&bucket_name) {
Ok(res) => res,
Err(err) => {
let item = ObjectInfoOrErr {
item: None,
err: Some(err.into()),
};
let _ = result.send(item).await;
return;
}
};
if let Some(filter) = opts.filter
&& !filter(&fi)
{
continue;
}
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(&fi, &bucket_name, &fi.name, {
if let Some(v) = &versioning_config {
v.versioned(&fi.name)
} else {
false
}
})),
err: None,
};
let _ = result.send(item).await;
continue;
}
let versions = match if opts.include_free_versions {
entry.file_info_versions_with_free_versions(&bucket_name)
} else {
entry.file_info_versions(&bucket_name)
} {
Ok(res) => res,
Err(err) => {
let item = ObjectInfoOrErr {
item: None,
err: Some(err.into()),
};
let _ = result.send(item).await;
return;
}
};
for fi in &versions.versions {
if let Some(filter) = opts.filter
&& !filter(fi)
{
continue;
}
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_name, &fi.name, {
if let Some(v) = &versioning_config {
v.versioned(&fi.name)
} else {
false
}
})),
err: None,
};
let _ = result.send(item).await;
}
if opts.include_free_versions {
for fi in &versions.free_versions {
if let Some(filter) = opts.filter
&& !filter(fi)
{
continue;
}
let item = ObjectInfoOrErr {
item: Some(ObjectInfo::from_file_info(fi, &bucket_name, &fi.name, {
if let Some(v) = &versioning_config {
v.versioned(&fi.name)
} else {
false
}
})),
err: None,
};
let _ = result.send(item).await;
}
}
}
}
.instrument(tracing::Span::current()),
);
let list_options = recursive_walk_list_path_options(bucket_name_for_list, prefix, &opts);
let list_result = self.list_path(rx, list_options, entry_tx).await;
let _ = result_task.await;
match list_result {
Ok(()) => Ok(()),
Err(err) => walk_result_from_set_errors(&[Some(err)]),
}
}
pub async fn list_path_result(self: Arc<Self>, o: &ListPathOptions) -> Result<MetaCacheEntriesSortedResult> {
check_list_objs_args(&o.bucket, &o.prefix, &o.marker)?;
let list_path_started = std::time::Instant::now();
let mut o = o.clone();
o.marker = o.marker.filter(|v| v >= &o.prefix);
if let Some(marker) = &o.marker
&& !o.prefix.is_empty()
&& !marker.starts_with(&o.prefix)
{
return Err(Error::Unexpected);
}
if o.limit == 0 {
return Err(Error::Unexpected);
}
if o.prefix.starts_with(SLASH_SEPARATOR) {
return Err(Error::Unexpected);
}
let slash_separator = Some(SLASH_SEPARATOR.to_owned());
o.include_directories = o.separator == slash_separator;
if (o.separator == slash_separator || o.separator.is_none()) && !o.recursive {
o.recursive = o.separator != slash_separator;
o.separator = slash_separator;
} else {
o.recursive = true;
}
o.skip_hidden_prefix_check = can_skip_hidden_prefix_check(&o).await;
o.parse_marker();
if o.base_dir.is_empty() {
o.base_dir = base_dir_from_prefix(&o.prefix);
}
o.transient = o.transient || is_reserved_or_invalid_bucket(&o.bucket, false);
o.set_filter();
if o.transient {
o.create = false;
}
let log_context = ListPathLogContext::from_options(&o);
let cancel = CancellationToken::new();
let _cancel_guard = cancel.clone().drop_guard();
let (err_tx, mut err_rx) = broadcast::channel::<Arc<Error>>(1);
let (sender, recv) = mpsc::channel(o.limit as usize);
ensure_producer_limit_state(&mut o);
let set = self.clone();
let opts = o.clone();
let cancel_rx1 = cancel.clone();
let cancel_rx1_for_err = cancel_rx1.clone();
let err_tx1 = err_tx.clone();
let job1_context = log_context.clone();
let job1 = tokio::spawn(
async move {
let mut opts = opts;
opts.stop_disk_at_limit = true;
if let Err(err) = set.list_path(cancel_rx1, opts, sender).await
&& !cancel_rx1_for_err.is_cancelled()
{
log_list_path_worker_error("set_disks", "list_path", &job1_context, &err);
let _ = err_tx1.send(Arc::new(err));
}
}
.instrument(tracing::Span::current()),
);
let cancel_rx2 = cancel.clone();
let (result_tx, mut result_rx) = mpsc::channel(1);
let err_tx2 = err_tx.clone();
let opts = o.clone();
let job2_context = log_context.clone();
let job2 = tokio::spawn(
async move {
match gather_results(cancel_rx2, opts, recv, result_tx).await {
Ok(GatherResultsState::LimitReached) => cancel.cancel(),
Ok(GatherResultsState::InputClosed) => {}
Ok(GatherResultsState::ConsumerGone) => cancel.cancel(),
Err(err) => {
log_list_path_worker_error("set_disks", "gather_results", &job2_context, &err);
let _ = err_tx2.send(Arc::new(err));
cancel.cancel();
}
}
}
.instrument(tracing::Span::current()),
);
let mut result = tokio::select! {
res = err_rx.recv() => {
match res {
Ok(err) => {
log_list_path_worker_error("set_disks", "worker_error", &log_context, err.as_ref());
MetaCacheEntriesSortedResult { entries: None, err: Some(to_filemeta_err(err.as_ref().clone())) }
},
Err(err) => {
log_list_path_worker_error("set_disks", "error_channel_closed", &log_context, &err);
MetaCacheEntriesSortedResult { entries: None, err: Some(rustfs_filemeta::Error::other(err)) }
},
}
}
Some(result) = result_rx.recv() => result,
};
join_all(vec![job1, job2]).await;
if let Ok(err) = err_rx.try_recv() {
log_list_path_worker_error("set_disks", "trailing_worker_error", &log_context, err.as_ref());
result.err = Some(to_filemeta_err(err.as_ref().clone()));
}
if result.err.is_some() {
log_list_path_finished("set_disks", &log_context, list_path_started.elapsed().as_secs_f64() * 1000.0, 0, true);
return Ok(result);
}
if let Some(entries) = result.entries.as_mut() {
entries.reuse = true;
let truncated = !entries.entries().is_empty() || result.err.is_none();
entries.o.0.truncate(o.limit as usize);
if !o.transient && truncated {
entries.list_id = if let Some(id) = o.id {
Some(id)
} else {
Some(Uuid::new_v4().to_string())
};
}
if !truncated {
result.err = Some(rustfs_filemeta::Error::Unexpected);
}
}
rustfs_io_metrics::record_stage_duration(
"sets_list_objects_list_path",
list_path_started.elapsed().as_secs_f64() * 1000.0,
);
log_list_path_finished(
"set_disks",
&log_context,
list_path_started.elapsed().as_secs_f64() * 1000.0,
result
.entries
.as_ref()
.map(|entries| entries.entries().len())
.unwrap_or_default(),
result.err.is_some(),
);
Ok(result)
}
async fn list_versions_authoritatively(
&self,
rx: CancellationToken,
opts: ListPathOptions,
sender: Sender<MetaCacheEntry>,
) -> Result<()> {
let (disks, _, _) = self.get_online_disks_with_healing_and_info(true).await;
let disk_count = self.set_drive_count;
let parity = self.default_parity_count;
let read_quorum = if parity == 0 { disk_count } else { disk_count.div_ceil(2) };
if disk_count == 0 || disks.len() < read_quorum {
return Err(DiskError::ErasureReadQuorum.into());
}
let first_error = Arc::new(tokio::sync::Mutex::new(None));
let error_sink = Arc::clone(&first_error);
let bucket = opts.bucket.clone();
let cancel = rx.clone();
let result = list_path_raw_with_claim_tracker(
rx,
ListPathRawOptions {
disks: disks.into_iter().map(Some).collect(),
bucket: opts.bucket,
path: opts.base_dir,
recursive: opts.recursive,
incl_deleted: true,
skip_hidden_prefix_check: opts.skip_hidden_prefix_check,
filter_prefix: opts.filter_prefix,
forward_to: opts.marker,
min_disks: read_quorum,
preserve_replica_metadata: true,
per_disk_limit: 0,
skip_walkdir_total_timeout: true,
walkdir_timeout: opts.walkdir_timeout,
walkdir_stall_timeout: opts.walkdir_stall_timeout,
partial: Some(Box::new(move |entries, errors| {
let resolved = Self::resolve_listed_versions(&bucket, entries, errors, disk_count, parity);
let sender = sender.clone();
let cancel = cancel.clone();
let first_error = Arc::clone(&error_sink);
Box::pin(async move {
match resolved {
Ok(Some(entry)) => {
let _ = send_or_cancel(&cancel, &sender, entry).await;
}
Ok(None) => {}
Err(error) => {
first_error.lock().await.get_or_insert(error);
}
}
})
})),
..Default::default()
},
FallbackClaimTracker::default(),
)
.await;
if let Some(error) = first_error.lock().await.take() {
return Err(error.into());
}
result.map_err(Into::into)
}
pub async fn list_path(&self, rx: CancellationToken, opts: ListPathOptions, sender: Sender<MetaCacheEntry>) -> Result<()> {
if opts.versioned {
return self.list_versions_authoritatively(rx, opts, sender).await;
}
let list_path_started = std::time::Instant::now();
let (mut disks, infos, _) = self.get_online_disks_with_healing_and_info(true).await;
let online_disks = disks.len();
let mut ask_disks = get_list_quorum(&opts.ask_disks, self.set_drive_count as i32);
if ask_disks == -1 {
let new_disks = get_quorum_disks(&disks, &infos, disks.len().div_ceil(2));
if !new_disks.is_empty() {
disks = new_disks;
ask_disks = 1;
} else {
ask_disks = get_list_quorum("strict", self.set_drive_count as i32);
}
}
if self.set_drive_count == 4 {
ask_disks = bounded_usize_to_i32(disks.len());
} else if ask_disks > bounded_usize_to_i32(disks.len()) {
ask_disks = clamp_ask_disks_to_available(ask_disks, disks.len());
}
let listing_quorum = listing_quorum_from_ask_disks(ask_disks);
ensure_non_empty_listing_disks(&opts.bucket, &opts.base_dir, &disks)?;
let enforce_write_quorum = enforce_latest_listing_write_quorum(!opts.versioned, &opts.ask_disks);
let write_quorum_parity = self.default_parity_count;
let write_quorum_slack = latest_listing_write_quorum_slack(enforce_write_quorum, self.set_drive_count, online_disks);
let required_obj_quorum = latest_listing_required_object_quorum(
listing_quorum,
self.set_drive_count,
write_quorum_parity,
enforce_write_quorum,
write_quorum_slack,
);
ask_disks = expand_ask_disks_for_object_quorum(ask_disks, disks.len(), required_obj_quorum);
let mut fallback_disks = Vec::new();
if let Some(asked_disks) = positive_ask_disks(ask_disks)
&& disks.len() > asked_disks
{
let mut rand = rand::rng();
disks.shuffle(&mut rand);
fallback_disks = disks.split_off(asked_disks);
}
let fallback_disks = Arc::new(fallback_disks);
let disks = Arc::new(disks);
let claim_tracker = FallbackClaimTracker::default();
let bucket = opts.bucket.clone();
let base_dir = opts.base_dir.clone();
let latest_object_quorum = latest_listing_object_quorum(
listing_quorum,
self.set_drive_count,
write_quorum_parity,
enforce_write_quorum,
write_quorum_slack,
);
let raw_min_disks = latest_listing_raw_min_disks(listing_quorum, latest_object_quorum, enforce_write_quorum);
let resolver = list_metadata_resolution_params(
bucket.clone(),
listing_quorum,
latest_object_quorum,
opts.versioned,
write_quorum_slack,
);
let agreed_resolver = resolver.clone();
let partial_resolver = resolver.clone();
let reader_disks = disks.len();
debug!(
bucket = %bucket,
prefix = %base_dir,
set_drive_count = self.set_drive_count,
asked_disks = ask_disks,
listing_quorum = listing_quorum,
latest_object_quorum = latest_object_quorum,
write_quorum_slack = write_quorum_slack,
raw_min_disks = raw_min_disks,
fallback_disks = fallback_disks.len(),
limit = opts.limit,
stop_disk_at_limit = opts.stop_disk_at_limit,
"set_disks list_path selected listing quorum and fallback disks"
);
let limit = {
if opts.limit > 0 && opts.stop_disk_at_limit {
opts.limit + 4 + (opts.limit / 16)
} else {
0
}
};
let tx1 = sender.clone();
let tx2 = sender.clone();
let cancel_for_send1 = rx.clone();
let cancel_for_send2 = rx.clone();
let supplement = ListingSupplement::new_with_reconciler(
ListingSupplementOptions {
bucket: bucket.clone(),
path: opts.base_dir.clone(),
recursive: opts.recursive,
incl_deleted: opts.incl_deleted,
skip_hidden_prefix_check: opts.skip_hidden_prefix_check,
filter_prefix: opts.filter_prefix.clone(),
forward_to: opts.marker.clone(),
per_disk_limit: limit,
skip_total_timeout: true,
walkdir_timeout: opts.walkdir_timeout,
walkdir_stall_timeout: opts.walkdir_stall_timeout,
},
fallback_disks.clone(),
claim_tracker.clone(),
self.clone(),
disks.clone(),
);
let agreed_supplement = supplement.clone();
let partial_supplement = supplement;
let result = list_path_raw_with_partial_result(
rx,
ListPathRawOptions {
disks: disks.iter().cloned().map(Some).collect(),
fallback_disks: fallback_disks.iter().cloned().map(Some).collect(),
bucket: opts.bucket,
path: opts.base_dir,
recursive: opts.recursive,
incl_deleted: opts.incl_deleted,
skip_hidden_prefix_check: opts.skip_hidden_prefix_check,
filter_prefix: opts.filter_prefix,
forward_to: opts.marker,
min_disks: raw_min_disks,
per_disk_limit: limit,
producer_limit_reached: opts.producer_limit_reached.clone(),
skip_walkdir_total_timeout: true,
walkdir_timeout: opts.walkdir_timeout,
walkdir_stall_timeout: opts.walkdir_stall_timeout,
agreed: Some(Box::new(move |entry: MetaCacheEntry| {
Box::pin({
let value = tx1.clone();
let cancel_token = cancel_for_send1.clone();
let resolver = agreed_resolver.clone();
let supplement = agreed_supplement.clone();
async move {
if cancel_token.is_cancelled() {
return;
}
let entry =
match resolve_agreed_listing_entry(entry, reader_disks, resolver.clone(), enforce_write_quorum) {
ListingEntryResolution::Resolved(entry) => entry,
ListingEntryResolution::NeedsSupplement(entry, fallback) => {
if cancel_token.is_cancelled() {
return;
}
let Some(entry) = resolve_agreed_listing_entry_with_supplement(
entry,
reader_disks,
resolver,
enforce_write_quorum,
supplement,
)
.await
.or(fallback) else {
return;
};
entry
}
ListingEntryResolution::Rejected => return,
};
if let Err(err) = send_or_cancel(&cancel_token, &value, entry).await
&& !cancel_token.is_cancelled()
{
error!("list_path send fail {:?}", err);
}
}
})
})),
finished: None,
..Default::default()
},
claim_tracker,
Box::new(move |entries: MetaCacheEntries, _: &[Option<DiskError>]| {
Box::pin({
let value = tx2.clone();
let resolver = partial_resolver.clone();
let cancel_token = cancel_for_send2.clone();
let supplement = partial_supplement.clone();
async move {
if cancel_token.is_cancelled() {
return Ok(());
}
if let Some(entry) =
resolve_listing_entries_with_supplement(entries, resolver, enforce_write_quorum, supplement).await?
&& let Err(err) = send_or_cancel(&cancel_token, &value, entry).await
&& !cancel_token.is_cancelled()
{
error!("list_path send fail {:?}", err);
}
Ok(())
}
})
}),
)
.await;
rustfs_io_metrics::record_stage_duration(
"set_disks_list_objects_list_path",
list_path_started.elapsed().as_secs_f64() * 1000.0,
);
if let Err(ref err) = result {
debug!(
bucket = %bucket,
path = %base_dir,
disk_count = disks.len(),
fallback_disks = fallback_disks.len(),
asked_disks = ask_disks,
listing_quorum = listing_quorum,
stop_disk_at_limit = opts.stop_disk_at_limit,
limit = opts.limit,
per_disk_limit = limit,
elapsed_ms = list_path_started.elapsed().as_secs_f64() * 1000.0,
list_error = %err,
"set_disks list_path finished with error"
);
} else {
debug!(
bucket = %bucket,
path = %base_dir,
disk_count = disks.len(),
fallback_disks = fallback_disks.len(),
asked_disks = ask_disks,
listing_quorum = listing_quorum,
stop_disk_at_limit = opts.stop_disk_at_limit,
limit = opts.limit,
per_disk_limit = limit,
elapsed_ms = list_path_started.elapsed().as_secs_f64() * 1000.0,
"set_disks list_path finished"
);
}
result.map_err(Error::from)
}
}
fn get_list_quorum(quorum: &str, drive_count: i32) -> i32 {
match quorum {
"disk" => 1,
"reduced" => 2,
"optimal" => (drive_count + 1) / 2,
"auto" => -1,
_ => drive_count, }
}
fn get_quorum_disk_infos(disks: &[DiskStore], infos: &[DiskInfo], read_quorum: usize) -> (Vec<DiskStore>, Vec<DiskInfo>) {
let common_mutations = calc_common_counter(infos, read_quorum);
let mut new_disks = Vec::new();
let mut new_infos = Vec::new();
for (i, info) in infos.iter().enumerate() {
let mutations = info.metrics.total_deletes + info.metrics.total_writes;
if mutations >= common_mutations {
new_disks.push(disks[i].clone());
new_infos.push(infos[i].clone());
}
}
(new_disks, new_infos)
}
fn get_quorum_disks(disks: &[DiskStore], infos: &[DiskInfo], read_quorum: usize) -> Vec<DiskStore> {
let (new_disks, _) = get_quorum_disk_infos(disks, infos, read_quorum);
new_disks
}
fn calc_common_counter(infos: &[DiskInfo], read_quorum: usize) -> u64 {
let mut max = 0;
let mut common_count = 0;
let mut signature_map: HashMap<u64, usize> = HashMap::new();
for info in infos {
if !info.error.is_empty() {
continue;
}
let mutations = info.metrics.total_deletes + info.metrics.total_writes;
*signature_map.entry(mutations).or_insert(0) += 1;
}
for (&ops, &count) in &signature_map {
if max < count && common_count < ops {
max = count;
common_count = ops;
}
}
if max < read_quorum {
return 0;
}
common_count
}
#[cfg(test)]
mod test {
use super::{
ENV_API_LIST_OBJECTS_INDEX_MODE, ENV_API_LIST_OBJECTS_INDEX_PROVIDER, ENV_API_LIST_OBJECTS_INDEX_PROVIDER_GENERATION,
ENV_API_LIST_OBJECTS_INDEX_PROVIDER_PATH, ENV_API_LIST_OBJECTS_METADATA_FAST_ENABLED,
ENV_API_LIST_OBJECTS_METADATA_FAST_STALENESS_MS, ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET,
ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_SEQUENCE,
ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS, ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_PATH,
ENV_API_LIST_OBJECTS_QUORUM, FallbackListingEntries, FallbackListingEntry, GatherResultsState,
LIST_CURSOR_GENERATION_LIVE, LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY,
LIST_OBJECTS_INDEX_PROVIDER_WALKER_KEY_ONLY, ListIndexFallbackReason, ListIndexLifecycle, ListIndexLifecycleState,
ListIndexSourceDecision, ListMetadataAuthority, ListMetadataIndexHealth, ListObjectsIndexProviderKind,
ListObjectsIndexProviderState, ListObjectsInfo, ListPathOptions, ListPathRawOptions, ListSourceMode,
ListingEntryResolution, ListingSupplement, ListingSupplementOptions, ListingSupplementTarget, MAX_OBJECT_LIST,
NamespaceMutationJournalBackend, NamespaceMutationJournalSnapshot, NamespaceMutationJournalStatus,
PERSISTENT_KEY_ONLY_INDEX_BUCKET_HEADER, PERSISTENT_KEY_ONLY_INDEX_CHECKPOINT_HEADER,
PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION, PERSISTENT_KEY_ONLY_INDEX_GENERATION_HEADER, PERSISTENT_KEY_ONLY_INDEX_HEADER,
PersistentKeyOnlyIndex, PersistentListMetadataObject, RUSTFS_META_BUCKET, VerifiedIndexCandidateStats, VersionMarker,
cached_entry_needs_supplement, current_list_objects_mutation_sequence, encode_persistent_list_metadata_object,
enforce_latest_listing_write_quorum, expand_ask_disks_for_object_quorum, fallback_entries_for_object, gather_results,
latest_listing_allow_agreed_objects, latest_listing_object_quorum, latest_listing_raw_min_disks,
latest_listing_required_object_quorum, latest_listing_write_quorum_slack, list_marker_key, list_merged_entry_channel,
list_metadata_resolution_params, list_objects_from_metadata_snapshot_candidates,
list_objects_from_verified_index_candidates, list_objects_from_verified_index_candidates_with_optional_stats,
list_objects_from_verified_index_candidates_with_stats, list_objects_index_mode_from_env,
list_objects_index_provider_from_env, list_objects_index_provider_state_from_env,
list_objects_metadata_fast_guardrails_from_env, list_objects_paginate, list_objects_quorum_from_env,
listing_entries_supplement_target, load_namespace_mutation_journal_state, load_persistent_key_only_index,
max_keys_plus_one, merge_entry_channels, namespace_mutation_journal_chaos_bucket_from_env,
namespace_mutation_journal_chaos_config_from_env, namespace_mutation_journal_chaos_enabled_from_env,
namespace_mutation_journal_chaos_sequence_from_env, namespace_mutation_journal_chaos_status_from_env,
normalize_list_quorum, observe_list_objects_mutations_with_store, parse_namespace_mutation_journal_state,
parse_persistent_key_only_index, parse_persistent_list_metadata_object, parse_version_marker,
persist_observed_list_objects_mutation, persistent_key_only_index_has_complete_metadata_snapshot,
persistent_key_only_index_health, persistent_key_only_index_matches_provider, recursive_walk_list_path_options,
reset_list_objects_mutation_sequences_for_test, resolve_agreed_listing_entry, resolve_listing_entries,
resolve_listing_entries_with_supplement, scanner_namespace_mutation_generation, select_list_index_provider_source_mode,
select_list_index_source_mode, send_or_cancel, should_purge_empty_directory_listing, version_marker_for_entries,
walk_result_from_set_errors, write_namespace_mutation_journal_state, write_persistent_key_only_index_with_metadata,
};
use crate::bucket::replication::ReplicationState;
use crate::cache_value::metacache_set::{FallbackClaimTracker, TestReaderBehavior, list_path_raw};
use crate::disk::{DeleteOptions, DiskAPI, DiskOption, STORAGE_FORMAT_FILE, endpoint::Endpoint, error::DiskError, new_disk};
use crate::error::{Result, StorageError};
use crate::object_api::ObjectInfo;
use crate::set_disk::{SetDisks, hermetic_set_disks_isolated};
use bytes::Bytes;
use rustfs_filemeta::{
FileInfo, FileMeta, FileMetaVersion, MetaCacheEntries, MetaCacheEntriesSorted, MetaCacheEntry, MetaDeleteMarker,
ObjectPartInfo, VersionType,
};
use std::collections::{HashMap, HashSet};
use std::path::PathBuf;
use std::sync::atomic::AtomicBool;
use std::sync::{Arc, Mutex};
use std::time::Duration;
use tokio::sync::mpsc;
use tokio::time::timeout;
use tokio_util::sync::CancellationToken;
use tracing_subscriber::fmt::MakeWriter;
#[test]
fn recursive_walk_list_options_scope_scan_to_requested_prefix() {
let options =
recursive_walk_list_path_options("bucket".to_owned(), "photos/2026/000001.jpg", &super::WalkOptions::default());
assert_eq!(options.base_dir, "photos/2026/");
assert_eq!(options.filter_prefix.as_deref(), Some("000001.jpg"));
let directory_options =
recursive_walk_list_path_options("bucket".to_owned(), "photos/2026/", &super::WalkOptions::default());
assert_eq!(directory_options.base_dir, "photos/2026/");
assert_eq!(directory_options.filter_prefix, None);
let object_options = recursive_walk_list_path_options("bucket".to_owned(), "object.jpg", &super::WalkOptions::default());
assert_eq!(object_options.base_dir, "");
assert_eq!(object_options.filter_prefix.as_deref(), Some("object.jpg"));
}
#[derive(Clone, Default)]
struct CapturedLogs {
buffer: Arc<Mutex<Vec<u8>>>,
}
struct CapturedLogWriter {
buffer: Arc<Mutex<Vec<u8>>>,
}
impl CapturedLogs {
fn contents(&self) -> String {
let buffer = self
.buffer
.lock()
.expect("captured logs mutex should not be poisoned")
.clone();
String::from_utf8(buffer).expect("captured logs should be valid UTF-8")
}
}
impl std::io::Write for CapturedLogWriter {
fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
self.buffer
.lock()
.expect("captured logs mutex should not be poisoned")
.extend_from_slice(buf);
Ok(buf.len())
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
impl<'a> MakeWriter<'a> for CapturedLogs {
type Writer = CapturedLogWriter;
fn make_writer(&'a self) -> Self::Writer {
CapturedLogWriter {
buffer: Arc::clone(&self.buffer),
}
}
}
use uuid::Uuid;
struct TestIndexHealth {
reason: Option<ListIndexFallbackReason>,
}
impl ListMetadataIndexHealth for TestIndexHealth {
fn fallback_reason(&self) -> Option<ListIndexFallbackReason> {
self.reason
}
}
fn test_meta_entry(name: &str) -> MetaCacheEntry {
MetaCacheEntry {
name: name.to_owned(),
..Default::default()
}
}
#[tokio::test]
async fn list_merged_entry_channel_backpressures_after_one_head() {
let (tx, mut rx) = list_merged_entry_channel();
tx.try_send(test_meta_entry("object-a"))
.expect("first merge head should fit in the input buffer");
match tx.try_send(test_meta_entry("object-b")) {
Err(tokio::sync::mpsc::error::TrySendError::Full(entry)) => assert_eq!(entry.name, "object-b"),
other => panic!("second merge head should wait for the k-way merge refill, got {other:?}"),
}
assert_eq!(rx.recv().await.expect("first merge head should remain available").name, "object-a");
tx.try_send(test_meta_entry("object-b"))
.expect("input buffer should accept the next head after refill");
}
fn test_live_object_info(name: &str, etag: &str) -> ObjectInfo {
let mut fi = FileInfo {
name: name.to_owned(),
size: 1,
mod_time: Some(time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp")),
..Default::default()
};
fi.metadata.insert("etag".to_string(), etag.to_string());
ObjectInfo::from_file_info(&fi, "bucket", name, false)
}
fn test_object_meta_entry(name: &str) -> MetaCacheEntry {
let mut meta = FileMeta::new();
let mut metadata = HashMap::new();
metadata.insert("etag".to_string(), "etag".to_string());
let mut fi = FileInfo::new(name, 2, 2);
fi.erasure.index = 1;
fi.data_dir = Some(Uuid::from_u128(0x1234));
fi.volume = "bucket".to_owned();
fi.name = name.to_owned();
fi.size = 1;
fi.parts = vec![ObjectPartInfo {
number: 1,
size: 1,
actual_size: 1,
..Default::default()
}];
fi.mod_time = Some(time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp"));
fi.metadata = metadata;
meta.add_version(fi).expect("test metadata should accept object version");
let metadata = meta.marshal_msg().expect("test metadata should marshal");
MetaCacheEntry {
name: name.to_owned(),
metadata,
cached: Some(meta),
reusable: false,
}
}
fn test_unversioned_object_meta_entry(
name: &str,
mod_time: time::OffsetDateTime,
etag: &str,
data_dir: Uuid,
) -> MetaCacheEntry {
let mut meta = FileMeta::new();
let mut fi = FileInfo::new(name, 2, 2);
fi.erasure.index = 1;
fi.data_dir = Some(data_dir);
fi.volume = "bucket".to_owned();
fi.name = name.to_owned();
fi.size = 1;
fi.parts = vec![ObjectPartInfo {
number: 1,
size: 1,
actual_size: 1,
..Default::default()
}];
fi.mod_time = Some(mod_time);
fi.metadata.insert("etag".to_string(), etag.to_string());
meta.add_version(fi).expect("test metadata should accept unversioned object");
let metadata = meta.marshal_msg().expect("test metadata should marshal");
MetaCacheEntry {
name: name.to_owned(),
metadata,
cached: Some(meta),
reusable: false,
}
}
fn test_pending_version_purge_meta_entry(bucket: &str, name: &str) -> (MetaCacheEntry, Uuid) {
let version_id = Uuid::from_u128(0x1234_5678_9abc_def0_1234_5678_9abc_def0);
let data_dir = Uuid::from_u128(0xabcd_ef12_3456_7890_abcd_ef12_3456_7890);
let mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let mut meta = FileMeta::new();
let mut fi = FileInfo::new(name, 2, 2);
fi.erasure.index = 1;
fi.data_dir = Some(data_dir);
fi.volume = bucket.to_owned();
fi.name = name.to_owned();
fi.version_id = Some(version_id);
fi.size = 1;
fi.parts = vec![ObjectPartInfo {
number: 1,
size: 1,
actual_size: 1,
..Default::default()
}];
fi.mod_time = Some(mod_time);
fi.metadata.insert("etag".to_string(), "pending-purge-etag".to_string());
meta.add_version(fi)
.expect("test metadata should accept pending-purge object version");
meta.delete_version(&FileInfo {
volume: bucket.to_owned(),
name: name.to_owned(),
version_id: Some(version_id),
replication_state_internal: Some(crate::bucket::replication::replication_state_to_filemeta(&ReplicationState {
version_purge_status_internal: Some("arn:target-a=PENDING;".to_string()),
purge_targets: crate::bucket::replication::version_purge_statuses_map("arn:target-a=PENDING;"),
..Default::default()
})),
..Default::default()
})
.expect("version purge status should be persisted");
let metadata = meta.marshal_msg().expect("test metadata should marshal");
(
MetaCacheEntry {
name: name.to_owned(),
metadata,
cached: Some(meta),
reusable: false,
},
data_dir,
)
}
fn test_null_version_meta_entry(name: &str, mod_time: time::OffsetDateTime) -> MetaCacheEntry {
let mut fi = FileInfo::new(name, 2, 2);
fi.erasure.index = 1;
fi.data_dir = Some(Uuid::from_u128(0x5678));
fi.volume = "bucket".to_owned();
fi.name = name.to_owned();
fi.version_id = None;
fi.versioned = false;
fi.size = 1;
fi.parts = vec![ObjectPartInfo {
number: 1,
size: 1,
actual_size: 1,
..Default::default()
}];
fi.mod_time = Some(mod_time);
fi.metadata.insert("etag".to_string(), "null-etag".to_string());
let mut meta = FileMeta::new();
meta.add_version(fi).expect("test metadata should accept null object version");
let metadata = meta.marshal_msg().expect("test metadata should marshal");
MetaCacheEntry {
name: name.to_owned(),
metadata,
cached: Some(meta),
reusable: false,
}
}
#[test]
fn fallback_entries_for_object_filters_claimed_physical_disks() {
let mut entries = FallbackListingEntries::new();
entries.insert(
"object".to_string(),
vec![
FallbackListingEntry {
endpoint: "disk-a".to_string(),
entry: test_meta_entry("object"),
},
FallbackListingEntry {
endpoint: "disk-b".to_string(),
entry: test_meta_entry("object"),
},
],
);
let claimed = HashSet::from(["disk-a".to_string()]);
let candidates = fallback_entries_for_object(&entries, "object", &claimed);
assert_eq!(candidates.len(), 1);
assert_eq!(candidates[0].as_ref().map(|entry| entry.name.as_str()), Some("object"));
}
#[test]
fn listing_supplement_uses_page_cache_only_for_bounded_walks() {
let bounded = ListingSupplement::new(
ListingSupplementOptions {
bucket: "bucket".to_string(),
path: String::new(),
recursive: true,
incl_deleted: false,
skip_hidden_prefix_check: false,
filter_prefix: None,
forward_to: None,
per_disk_limit: 100,
skip_total_timeout: true,
walkdir_timeout: None,
walkdir_stall_timeout: None,
},
Arc::new(Vec::new()),
FallbackClaimTracker::default(),
);
let unbounded = ListingSupplement::new(
ListingSupplementOptions {
bucket: "bucket".to_string(),
path: String::new(),
recursive: true,
incl_deleted: false,
skip_hidden_prefix_check: false,
filter_prefix: None,
forward_to: None,
per_disk_limit: 0,
skip_total_timeout: false,
walkdir_timeout: None,
walkdir_stall_timeout: None,
},
Arc::new(Vec::new()),
FallbackClaimTracker::default(),
);
assert!(bounded.entries.is_some());
assert!(bounded.options.skip_total_timeout);
assert!(unbounded.entries.is_none());
assert!(!unbounded.options.skip_total_timeout);
}
#[tokio::test]
async fn listing_supplement_unbounded_reads_object_metadata_from_fallback_disk() {
let tempdir = tempfile::tempdir().expect("tempdir should be created");
let endpoint =
Endpoint::try_from(tempdir.path().to_str().expect("tempdir path should be utf8")).expect("endpoint should parse");
let disk = new_disk(
&endpoint,
&DiskOption {
cleanup: false,
health_check: false,
},
)
.await
.expect("local disk should be created");
disk.make_volume("bucket").await.expect("test bucket should be created");
let mut fi = FileInfo::new("object", 1, 1);
fi.volume = "bucket".to_owned();
fi.name = "object".to_owned();
fi.size = 1;
fi.parts = vec![ObjectPartInfo {
number: 1,
size: 1,
actual_size: 1,
..Default::default()
}];
fi.fresh = true;
fi.erasure.index = 1;
fi.mod_time = Some(time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp"));
fi.metadata.insert("etag".to_owned(), "object-etag".to_owned());
disk.write_metadata("", "bucket", "object", fi)
.await
.expect("test metadata should be written");
let supplement = ListingSupplement::new(
ListingSupplementOptions {
bucket: "bucket".to_string(),
path: String::new(),
recursive: true,
incl_deleted: false,
skip_hidden_prefix_check: false,
filter_prefix: None,
forward_to: None,
per_disk_limit: 0,
skip_total_timeout: false,
walkdir_timeout: None,
walkdir_stall_timeout: None,
},
Arc::new(vec![disk]),
FallbackClaimTracker::default(),
);
let entries = supplement.entries_for("object").await;
assert!(supplement.entries.is_none());
assert_eq!(entries.len(), 1);
let entry = entries
.into_iter()
.next()
.and_then(|entry| entry)
.expect("fallback object metadata should be returned");
let info = entry.to_fileinfo("bucket").expect("fallback metadata should decode");
assert_eq!(entry.name, "object");
assert_eq!(info.metadata.get("etag").map(String::as_str), Some("object-etag"));
}
fn test_object_meta_entry_with_erasure_versions(
name: &str,
versions: &[(time::OffsetDateTime, &str, usize, usize)],
) -> MetaCacheEntry {
let mut meta = FileMeta::new();
for (idx, (mod_time, etag, data_blocks, parity_blocks)) in versions.iter().enumerate() {
let mut metadata = HashMap::new();
metadata.insert("etag".to_string(), (*etag).to_string());
let mut fi = FileInfo::new(name, *data_blocks, *parity_blocks);
fi.erasure.index = 1;
fi.data_dir = Some(Uuid::from_u128(0x1234));
fi.volume = "bucket".to_owned();
fi.name = name.to_owned();
let version_idx = u128::try_from(idx + 1).expect("test version index should fit u128");
fi.version_id = Some(Uuid::from_u128(version_idx));
fi.versioned = true;
fi.size = 1;
fi.parts = vec![ObjectPartInfo {
number: 1,
size: 1,
actual_size: 1,
..Default::default()
}];
fi.mod_time = Some(*mod_time);
fi.metadata = metadata;
meta.add_version(fi).expect("test metadata should accept object version");
}
let metadata = meta.marshal_msg().expect("test metadata should marshal");
MetaCacheEntry {
name: name.to_owned(),
metadata,
cached: Some(meta),
reusable: false,
}
}
fn test_delete_marker_meta_entry(name: &str, mod_time: time::OffsetDateTime) -> MetaCacheEntry {
let mut meta = FileMeta::new();
let delete_marker = FileMetaVersion {
version_type: VersionType::Delete,
object: None,
delete_marker: Some(MetaDeleteMarker {
version_id: Some(Uuid::from_u128(0x44444444555566667777888888888888)),
mod_time: Some(mod_time),
meta_sys: HashMap::new(),
}),
legacy_object: None,
write_version: 1,
uses_legacy_checksum: false,
};
meta.versions.push(
delete_marker
.try_into()
.expect("test delete marker should convert to shallow version"),
);
let metadata = meta.marshal_msg().expect("test delete marker metadata should marshal");
MetaCacheEntry {
name: name.to_owned(),
metadata,
cached: Some(meta),
reusable: false,
}
}
fn test_transitioned_meta_entry(name: &str, remote_object: &str, delete_source: bool) -> MetaCacheEntry {
let mut source = FileInfo::new(name, 2, 2);
source.volume = "bucket".to_string();
source.name = name.to_string();
source.version_id = Some(Uuid::from_u128(1));
source.versioned = true;
source.size = 1;
source.mod_time = Some(time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp"));
source.transition_status = rustfs_filemeta::TRANSITION_COMPLETE.to_string();
source.transition_tier = "WARM".to_string();
source.transitioned_objname = remote_object.to_string();
source.transition_version = Some("remote-version".to_string());
source.transition_version_state = rustfs_filemeta::TransitionVersionState::Exact;
rustfs_utils::http::metadata_compat::insert_str(
&mut source.metadata,
rustfs_utils::http::metadata_compat::SUFFIX_TRANSITION_TIER_DESTINATION_ID,
"00".repeat(32),
);
let mut meta = FileMeta::new();
meta.add_version(source.clone())
.expect("test metadata should accept transitioned source");
if delete_source {
let mut delete = FileInfo {
name: name.to_string(),
version_id: source.version_id,
..Default::default()
};
delete.set_tier_free_version_id(&Uuid::from_u128(2).to_string());
meta.delete_version(&delete)
.expect("transitioned delete should create a free-version owner");
}
let metadata = meta.marshal_msg().expect("test transitioned metadata should marshal");
MetaCacheEntry {
name: name.to_string(),
metadata,
cached: Some(meta),
reusable: false,
}
}
fn test_object_with_delete_marker_meta_entry(
name: &str,
object_mod_time: time::OffsetDateTime,
delete_mod_time: time::OffsetDateTime,
) -> MetaCacheEntry {
let mut object = test_object_meta_entry_with_erasure_versions(name, &[(object_mod_time, "object-etag", 4, 2)]);
let delete = test_delete_marker_meta_entry(name, delete_mod_time);
let mut metadata = object.cached.take().expect("test object metadata should be cached");
let delete_version = delete
.cached
.expect("test delete marker metadata should be cached")
.versions
.into_iter()
.next()
.expect("test delete marker should contain one version");
metadata.versions.insert(0, delete_version);
let encoded = metadata.marshal_msg().expect("test metadata should marshal");
MetaCacheEntry {
name: name.to_owned(),
metadata: encoded,
cached: Some(metadata),
reusable: false,
}
}
fn test_dir_meta_entry(name: &str) -> MetaCacheEntry {
MetaCacheEntry {
name: name.to_owned(),
..Default::default()
}
}
fn sorted_entries(names: &[&str]) -> MetaCacheEntriesSorted {
MetaCacheEntriesSorted {
o: MetaCacheEntries(names.iter().map(|name| Some(test_meta_entry(name))).collect()),
..Default::default()
}
}
#[tokio::test]
async fn list_path_gather_results_returns_after_limit_without_waiting_for_input_close() {
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, mut result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
entry_tx
.send(test_meta_entry("obj-a"))
.await
.expect("test entry should be queued");
let handle = tokio::spawn(gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
limit: 1,
incl_deleted: true,
..Default::default()
},
entry_rx,
result_tx,
));
let result = timeout(Duration::from_secs(1), result_rx.recv())
.await
.expect("limited result should be sent promptly")
.expect("limited result should be present");
assert_eq!(result.entries.unwrap().entries().len(), 1);
let state = timeout(Duration::from_secs(1), handle)
.await
.expect("gather_results should finish after sending a limited result")
.expect("gather_results task should not panic")
.expect("gather_results should succeed");
assert_eq!(state, GatherResultsState::LimitReached);
assert!(cancel.is_cancelled());
}
#[tokio::test]
async fn list_path_gather_results_keeps_marker_entry_for_version_marker_listing() {
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, mut result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
entry_tx
.send(test_meta_entry("obj-a"))
.await
.expect("first test entry should be queued");
entry_tx
.send(test_meta_entry("obj-b"))
.await
.expect("second test entry should be queued");
let handle = tokio::spawn(gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
marker: Some("obj-a".to_owned()),
include_marker: true,
limit: 2,
incl_deleted: true,
versioned: true,
..Default::default()
},
entry_rx,
result_tx,
));
let result = timeout(Duration::from_secs(1), result_rx.recv())
.await
.expect("limited result should be sent promptly")
.expect("limited result should be present");
let entries = result.entries.unwrap();
let names = entries
.entries()
.into_iter()
.map(|entry| entry.name.as_str())
.collect::<Vec<_>>();
assert_eq!(names, ["obj-a", "obj-b"]);
let state = timeout(Duration::from_secs(1), handle)
.await
.expect("gather_results should finish after sending a limited result")
.expect("gather_results task should not panic")
.expect("gather_results should succeed");
assert_eq!(state, GatherResultsState::LimitReached);
assert!(cancel.is_cancelled());
}
#[test]
fn list_versions_pagination_scan_limit_boundaries() {
for has_version_marker in [false, true] {
assert_eq!(super::list_versions_scan_limit(-1, has_version_marker), 0);
assert_eq!(super::list_versions_scan_limit(0, has_version_marker), 0);
let marker_slot = i32::from(has_version_marker);
assert_eq!(super::list_versions_scan_limit(1, has_version_marker), 2 + marker_slot);
assert_eq!(super::list_versions_scan_limit(MAX_OBJECT_LIST, has_version_marker), 1001 + marker_slot);
assert_eq!(super::list_versions_scan_limit(i32::MAX, has_version_marker), 1001 + marker_slot);
}
}
#[tokio::test]
async fn list_versions_pagination_does_not_require_an_empty_final_page() {
use crate::bucket::metadata_sys::{init_bucket_metadata_sys, test_support::isolated_store_over_temp_disks};
use crate::storage_api_contracts::bucket::{BucketOperations as _, MakeBucketOptions};
let (dirs, store) = isolated_store_over_temp_disks().await;
let bucket = "version-pagination-bucket";
init_bucket_metadata_sys(store.clone(), Vec::new()).await;
store
.make_bucket(bucket, &MakeBucketOptions::default())
.await
.expect("pagination bucket should be created");
let mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
for kind in ["objects", "deletes", "null", "mixed", "delimiter"] {
let count = if kind == "mixed" { 5 } else { 10 };
let mut expected = Vec::new();
for index in 0..count {
let name = if kind == "delimiter" && index % 2 == 1 {
format!("{kind}/testobject-{index:02}/child")
} else {
format!("{kind}/testobject-{index:02}")
};
let entry = match kind {
"deletes" => test_delete_marker_meta_entry(&name, mod_time),
"null" => test_null_version_meta_entry(&name, mod_time),
"mixed" => test_object_with_delete_marker_meta_entry(&name, mod_time, mod_time + time::Duration::SECOND),
_ => test_object_meta_entry_with_erasure_versions(&name, &[(mod_time, "etag", 2, 2)]),
};
for dir in &dirs {
let object_dir = dir.path().join(bucket).join(&name);
tokio::fs::create_dir_all(&object_dir)
.await
.expect("pagination object directory should be created");
tokio::fs::write(object_dir.join(STORAGE_FORMAT_FILE), &entry.metadata)
.await
.expect("pagination metadata should be written");
}
if kind == "delimiter" && index % 2 == 1 {
expected.push((name.trim_end_matches("child").to_owned(), None, false));
} else {
let versions = entry.file_info_versions(bucket).expect("fixture versions should decode");
expected.extend(
versions
.versions
.iter()
.map(|version| (name.clone(), version.version_id, version.deleted)),
);
}
}
let prefix = format!("{kind}/");
let delimiter = (kind == "delimiter").then(|| "/".to_owned());
for (layer, max_keys) in [(0, 0), (0, 1), (0, 5), (0, 9), (0, 10), (0, 11), (1, 5), (2, 5), (3, 5)] {
if layer == 3 && delimiter.is_some() {
continue;
}
let mut marker = None;
let mut version_marker = None;
let expected_pages = if max_keys == 0 {
1
} else {
10usize.div_ceil(usize::try_from(max_keys).expect("positive page size"))
};
let mut actual = Vec::new();
for page in 0..expected_pages {
let result = match layer {
0 => {
store
.clone()
.inner_list_object_versions(bucket, &prefix, marker, version_marker, delimiter.clone(), max_keys)
.await
}
1 => {
store.pools[0]
.clone()
.inner_list_object_versions(bucket, &prefix, marker, version_marker, delimiter.clone(), max_keys)
.await
}
2 => {
store.pools[0].disk_set[0]
.clone()
.inner_list_object_versions(bucket, &prefix, marker, version_marker, delimiter.clone(), max_keys)
.await
}
_ => {
store.pools[0].disk_set[0]
.clone()
.inner_list_object_versions_for_recursive_delete(
bucket,
&prefix,
marker,
version_marker,
max_keys,
)
.await
}
}
.expect("version page should list successfully");
let page_size = usize::try_from(max_keys).expect("nonnegative page size");
assert_eq!(
result.objects.len() + result.prefixes.len(),
(10 - page * page_size).min(page_size),
"{kind}, layer {layer}, max_keys {max_keys}, page {page}"
);
let has_more = page + 1 < expected_pages;
assert_eq!(result.is_truncated, has_more, "{kind}, layer {layer}, max_keys {max_keys}, page {page}");
assert_eq!(
result.next_marker.is_some(),
has_more,
"key marker must exist only when another page exists"
);
if !has_more {
assert!(
result.next_version_idmarker.is_none(),
"the final page must not advertise a version marker"
);
}
actual.extend(
result
.objects
.into_iter()
.map(|object| (object.name, object.version_id, object.delete_marker)),
);
actual.extend(result.prefixes.into_iter().map(|prefix| (prefix, None, false)));
marker = result.next_marker;
version_marker = result.next_version_idmarker;
}
actual.sort();
let mut expected = if max_keys == 0 { Vec::new() } else { expected.clone() };
expected.sort();
assert_eq!(actual, expected, "{kind}, layer {layer}, max_keys {max_keys}");
}
}
}
#[test]
fn version_marker_is_applied_only_when_key_marker_entry_is_present() {
let version_marker = Some(VersionMarker::Null);
let listed_after_deleted_marker = sorted_entries(&["obj-b", "obj-c"]);
assert_eq!(
version_marker_for_entries(Some(&listed_after_deleted_marker), Some("obj-a"), version_marker),
None
);
let listed_with_marker = sorted_entries(&["obj-a", "obj-b"]);
assert_eq!(
version_marker_for_entries(Some(&listed_with_marker), Some("obj-a"), version_marker),
version_marker
);
}
#[tokio::test]
async fn list_path_gather_results_skips_marker_entry_by_default() {
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, mut result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
entry_tx
.send(test_meta_entry("obj-a"))
.await
.expect("first test entry should be queued");
entry_tx
.send(test_meta_entry("obj-b"))
.await
.expect("second test entry should be queued");
drop(entry_tx);
let handle = tokio::spawn(gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
marker: Some("obj-a".to_owned()),
limit: 2,
incl_deleted: true,
..Default::default()
},
entry_rx,
result_tx,
));
let result = timeout(Duration::from_secs(1), result_rx.recv())
.await
.expect("eof result should be sent promptly")
.expect("eof result should be present");
let entries = result.entries.unwrap();
let names = entries
.entries()
.into_iter()
.map(|entry| entry.name.as_str())
.collect::<Vec<_>>();
assert_eq!(names, ["obj-b"]);
assert!(result.err.is_some());
let state = timeout(Duration::from_secs(1), handle)
.await
.expect("gather_results should finish after input closes")
.expect("gather_results task should not panic")
.expect("gather_results should succeed");
assert_eq!(state, GatherResultsState::InputClosed);
assert!(!cancel.is_cancelled());
}
#[tokio::test]
async fn list_path_gather_results_filters_delete_marker_after_name_filters() {
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, mut result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
let mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_500).expect("valid timestamp");
entry_tx
.send(test_delete_marker_meta_entry("obj-a", mod_time))
.await
.expect("delete marker should be queued");
entry_tx
.send(test_object_meta_entry("obj-b"))
.await
.expect("object should be queued");
drop(entry_tx);
let handle = tokio::spawn(gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
marker: Some("obj-a".to_owned()),
limit: 2,
incl_deleted: false,
..Default::default()
},
entry_rx,
result_tx,
));
let result = timeout(Duration::from_secs(1), result_rx.recv())
.await
.expect("result should be sent promptly")
.expect("result should be present");
let entries = result.entries.unwrap();
let names = entries
.entries()
.into_iter()
.map(|entry| entry.name.as_str())
.collect::<Vec<_>>();
assert_eq!(names, ["obj-b"]);
let state = timeout(Duration::from_secs(1), handle)
.await
.expect("gather_results should finish")
.expect("gather_results task should not panic")
.expect("gather_results should succeed");
assert_eq!(state, GatherResultsState::InputClosed);
assert!(!cancel.is_cancelled());
}
#[tokio::test]
async fn list_path_gather_results_skips_directory_delete_marker_by_default() {
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, mut result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
let mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_500).expect("valid timestamp");
entry_tx
.send(test_delete_marker_meta_entry("folder/", mod_time))
.await
.expect("directory delete marker should be queued");
entry_tx
.send(test_object_meta_entry("visible"))
.await
.expect("visible object should be queued");
drop(entry_tx);
let handle = tokio::spawn(gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
separator: Some("/".to_owned()),
include_directories: true,
limit: 2,
..Default::default()
},
entry_rx,
result_tx,
));
let result = timeout(Duration::from_secs(1), result_rx.recv())
.await
.expect("eof result should be sent promptly")
.expect("eof result should be present");
let entries = result.entries.expect("result entries should be present");
let names = entries
.entries()
.into_iter()
.map(|entry| entry.name.clone())
.collect::<Vec<_>>();
assert_eq!(names, ["visible".to_string()]);
let state = timeout(Duration::from_secs(1), handle)
.await
.expect("gather_results should finish after input closes")
.expect("gather_results task should not panic")
.expect("gather_results should succeed");
assert_eq!(state, GatherResultsState::InputClosed);
assert!(!cancel.is_cancelled());
}
#[tokio::test]
async fn list_path_gather_results_reports_consumer_gone_when_receiver_dropped_at_limit() {
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
entry_tx
.send(test_meta_entry("obj-a"))
.await
.expect("test entry should be queued");
drop(result_rx);
let state = timeout(
Duration::from_secs(1),
gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
limit: 1,
incl_deleted: true,
..Default::default()
},
entry_rx,
result_tx,
),
)
.await
.expect("gather_results should finish promptly when the consumer is gone")
.expect("consumer disconnect must be a benign completion, not an error");
assert_eq!(state, GatherResultsState::ConsumerGone);
assert!(cancel.is_cancelled());
}
#[tokio::test]
async fn list_path_gather_results_reports_consumer_gone_when_receiver_dropped_at_eof() {
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
entry_tx
.send(test_meta_entry("obj-a"))
.await
.expect("test entry should be queued");
drop(entry_tx);
drop(result_rx);
let state = timeout(
Duration::from_secs(1),
gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
limit: 8,
incl_deleted: true,
..Default::default()
},
entry_rx,
result_tx,
),
)
.await
.expect("gather_results should finish promptly when the consumer is gone")
.expect("consumer disconnect must be a benign completion, not an error");
assert_eq!(state, GatherResultsState::ConsumerGone);
assert!(!cancel.is_cancelled());
}
#[tokio::test]
async fn list_path_gather_results_preserves_bounded_producer_after_filtering() {
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, mut result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
let producer_limit_reached = Arc::new(AtomicBool::new(true));
entry_tx
.send(test_meta_entry("outside-prefix"))
.await
.expect("filtered test entry should be queued");
drop(entry_tx);
let handle = tokio::spawn(gather_results(
cancel,
ListPathOptions {
bucket: "bucket".to_owned(),
prefix: "requested/".to_owned(),
limit: 8,
incl_deleted: true,
producer_limit_reached: Some(producer_limit_reached),
..Default::default()
},
entry_rx,
result_tx,
));
let result = result_rx.recv().await.expect("bounded producer result should be delivered");
assert!(result.entries.expect("entries should be present").entries().is_empty());
assert!(result.err.is_none(), "bounded producer must not be reported as EOF");
assert_eq!(
handle
.await
.expect("gather task should not panic")
.expect("gather should succeed"),
GatherResultsState::InputClosed
);
}
#[tokio::test]
async fn list_path_gather_results_send_success_delivers_state_specific_err_sentinel() {
{
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, mut result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
entry_tx
.send(test_meta_entry("obj-a"))
.await
.expect("test entry should be queued");
let handle = tokio::spawn(gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
limit: 1,
incl_deleted: true,
..Default::default()
},
entry_rx,
result_tx,
));
let result = timeout(Duration::from_secs(1), result_rx.recv())
.await
.expect("limited result should be sent promptly")
.expect("limited result should be present");
assert_eq!(result.entries.expect("limit payload delivers entries").entries().len(), 1);
assert!(result.err.is_none(), "limit-reached payload must carry no err sentinel");
let state = timeout(Duration::from_secs(1), handle)
.await
.expect("gather_results should finish")
.expect("gather_results task should not panic")
.expect("a successful send must not surface as an error");
assert_eq!(state, GatherResultsState::LimitReached);
}
{
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, mut result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
entry_tx
.send(test_meta_entry("obj-a"))
.await
.expect("test entry should be queued");
drop(entry_tx);
let handle = tokio::spawn(gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
limit: 8,
incl_deleted: true,
..Default::default()
},
entry_rx,
result_tx,
));
let result = timeout(Duration::from_secs(1), result_rx.recv())
.await
.expect("eof result should be sent promptly")
.expect("eof result should be present");
assert_eq!(result.entries.expect("eof payload delivers entries").entries().len(), 1);
assert!(result.err.is_some(), "eof payload must carry the sentinel err the wrapper relies on");
let state = timeout(Duration::from_secs(1), handle)
.await
.expect("gather_results should finish")
.expect("gather_results task should not panic")
.expect("a successful send must not surface as an error");
assert_eq!(state, GatherResultsState::InputClosed);
}
}
#[tokio::test(flavor = "current_thread")]
async fn list_path_gather_results_consumer_gone_emits_no_worker_failure_log() {
let logs = CapturedLogs::default();
let subscriber = tracing_subscriber::fmt()
.with_max_level(tracing::Level::DEBUG)
.with_writer(logs.clone())
.with_ansi(false)
.without_time()
.finish();
let _guard = tracing::subscriber::set_default(subscriber);
let (entry_tx, entry_rx) = mpsc::channel(4);
let (result_tx, result_rx) = mpsc::channel(1);
let cancel = CancellationToken::new();
entry_tx
.send(test_meta_entry("obj-a"))
.await
.expect("test entry should be queued");
drop(entry_tx);
drop(result_rx);
let state = timeout(
Duration::from_secs(1),
gather_results(
cancel.clone(),
ListPathOptions {
bucket: "bucket".to_owned(),
limit: 8,
incl_deleted: true,
..Default::default()
},
entry_rx,
result_tx,
),
)
.await
.expect("gather_results should finish promptly when the consumer is gone")
.expect("consumer disconnect must be a benign completion, not an error");
assert_eq!(state, GatherResultsState::ConsumerGone);
let captured = logs.contents();
assert!(captured.contains("consumer disconnected"));
assert!(!captured.contains("list_path worker failed"));
}
#[test]
fn list_path_forward_past_is_idempotent_for_same_marker() {
let mut first_page = sorted_entries(&["obj-0001", "obj-0002", "obj-0003", "obj-0004"]);
first_page.forward_past(Some("obj-0002".to_string()));
let first_page_names = first_page
.entries()
.into_iter()
.map(|entry| entry.name.clone())
.collect::<Vec<_>>();
let mut second_page = sorted_entries(&["obj-0001", "obj-0002", "obj-0003", "obj-0004"]);
second_page.forward_past(Some("obj-0002".to_string()));
let second_page_names = second_page
.entries()
.into_iter()
.map(|entry| entry.name.clone())
.collect::<Vec<_>>();
assert_eq!(first_page_names, second_page_names);
assert_eq!(first_page_names, vec!["obj-0003".to_string(), "obj-0004".to_string()]);
}
#[test]
fn list_path_forward_past_keeps_source_switch_page_boundary() {
let mut walker_page_after_index = sorted_entries(&["obj-0001", "obj-0002", "obj-0003", "obj-0004"]);
walker_page_after_index.forward_past(Some("obj-0002".to_string()));
let page_names = walker_page_after_index
.entries()
.into_iter()
.map(|entry| entry.name.clone())
.collect::<Vec<_>>();
assert_eq!(page_names, vec!["obj-0003".to_string(), "obj-0004".to_string()]);
}
#[test]
fn list_path_parse_marker_replay_still_stable() {
let marker = "photos/2026/image.jpg[rustfs_cache:v1,id:list-cache-id,p:3,s:7]".to_string();
let mut parsed = ListPathOptions {
marker: Some(marker),
..Default::default()
};
parsed.parse_marker();
assert_eq!(parsed.marker.as_deref(), Some("photos/2026/image.jpg"));
assert_eq!(parsed.id.as_deref(), Some("list-cache-id"));
assert_eq!(parsed.pool_idx, Some(3));
assert_eq!(parsed.set_idx, Some(7));
let base_marker = parsed.marker.clone().expect("marker should parse");
let replay_marker = parsed.encode_marker(base_marker.as_str());
let mut replay = ListPathOptions {
marker: Some(replay_marker),
..Default::default()
};
replay.parse_marker();
assert_eq!(replay.marker.as_deref(), Some("photos/2026/image.jpg"));
assert_eq!(replay.id.as_deref(), Some("list-cache-id"));
assert_eq!(replay.pool_idx, Some(3));
assert_eq!(replay.set_idx, Some(7));
assert!(!replay.create);
}
fn folded_prefix_object(name: &str) -> ObjectInfo {
ObjectInfo {
is_dir: true,
name: name.to_owned(),
..Default::default()
}
}
fn plain_object(name: &str) -> ObjectInfo {
ObjectInfo {
name: name.to_owned(),
mod_time: Some(time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp")),
..Default::default()
}
}
fn fold_delimiter_page(raw: &[String], prefix: &str, delimiter: &str) -> Vec<ObjectInfo> {
let mut out = Vec::new();
let mut prev_prefix = String::new();
for name in raw {
let remaining = name.strip_prefix(prefix).unwrap_or(name.as_str());
if let Some(idx) = remaining.find(delimiter) {
let cut = prefix.len() + idx + delimiter.len();
let curr = name[..cut].to_string();
if curr == prev_prefix {
continue;
}
prev_prefix = curr.clone();
out.push(folded_prefix_object(&curr));
} else {
out.push(plain_object(name));
}
}
out
}
#[test]
fn build_list_versions_next_marker_reports_null_for_nil_version_id() {
let null_version = ObjectInfo {
name: "obj-a".to_owned(),
version_id: Some(uuid::Uuid::nil()),
..Default::default()
};
let real_version = ObjectInfo {
name: "obj-b".to_owned(),
version_id: Some(uuid::Uuid::from_u128(7)),
..Default::default()
};
let (next_marker, next_version_idmarker) = super::build_list_versions_next_marker(&[null_version], &[], None);
assert_eq!(next_marker.as_deref(), Some("obj-a"));
assert_eq!(next_version_idmarker.as_deref(), Some("null"));
let (_, next_version_idmarker) = super::build_list_versions_next_marker(&[real_version], &[], None);
assert_eq!(next_version_idmarker.as_deref(), Some(uuid::Uuid::from_u128(7).to_string().as_str()));
}
#[test]
fn list_objects_paginate_delimiter_refold_reports_truncation_with_raw_marker() {
let delimiter = Some("-".to_string());
let get_objects = vec![folded_prefix_object("data-")];
let (objects, prefixes, is_truncated, next_marker, _v) = list_objects_paginate(
get_objects,
&delimiter,
1000,
true, None,
false,
Some("data-1001"), );
assert!(objects.is_empty());
assert_eq!(prefixes, vec!["data-".to_string()]);
assert!(is_truncated, "re-folded page with more on disk must be truncated");
assert_eq!(next_marker.as_deref(), Some("data-1001"));
}
#[test]
fn list_objects_paginate_delimiter_refold_no_marker_when_disk_exhausted() {
let delimiter = Some("-".to_string());
let get_objects = vec![folded_prefix_object("data-")];
let (_objects, prefixes, is_truncated, next_marker, _v) =
list_objects_paginate(get_objects, &delimiter, 1000, false, None, false, Some("data-1001"));
assert_eq!(prefixes, vec!["data-".to_string()]);
assert!(!is_truncated);
assert!(next_marker.is_none());
}
#[test]
fn list_objects_paginate_no_delimiter_ignores_raw_scanned_key() {
let get_objects = vec![plain_object("obj-0001"), plain_object("obj-0002")];
let (objects, prefixes, is_truncated, next_marker, _v) =
list_objects_paginate(get_objects, &None, 1000, true, None, false, Some("zzz-unrelated"));
assert_eq!(objects.len(), 2);
assert!(prefixes.is_empty());
assert!(is_truncated);
assert_eq!(next_marker.as_deref(), Some("obj-0002"));
}
#[test]
fn list_objects_paginate_delimiter_refold_paginates_all_prefixes_finitely() {
use std::collections::BTreeSet;
let mut all: Vec<String> = Vec::new();
for i in 1..=5000 {
all.push(format!("data-{i:04}"));
}
for i in 1..=100 {
all.push(format!("other-{i:04}"));
}
all.sort();
let delimiter = Some("-".to_string());
let max_keys = 1000i32;
let limit = max_keys_plus_one(max_keys, true) as usize;
let mut marker: Option<String> = None;
let mut seen_prefixes: BTreeSet<String> = BTreeSet::new();
let mut pages = 0;
loop {
pages += 1;
assert!(pages <= 64, "pagination did not terminate (possible infinite loop)");
let start = match &marker {
Some(m) => all.partition_point(|k| k.as_str() <= m.as_str()),
None => 0,
};
let window: Vec<String> = all[start..].iter().take(limit).cloned().collect();
let disk_has_more = window.len() == limit;
let last_scanned = window.last().cloned();
let get_objects = fold_delimiter_page(&window, "", "-");
let (objects, prefixes, is_truncated, next_marker, _v) =
list_objects_paginate(get_objects, &delimiter, max_keys, disk_has_more, None, false, last_scanned.as_deref());
assert!(objects.is_empty(), "every key folds into a common prefix");
for prefix in prefixes {
seen_prefixes.insert(prefix);
}
if !is_truncated {
assert!(next_marker.is_none());
break;
}
let next = next_marker.expect("truncated page must carry a continuation marker");
if let Some(prev) = &marker {
assert!(next.as_str() > prev.as_str(), "next_marker must strictly advance to stay finite");
}
marker = Some(next);
}
let expected: BTreeSet<String> = ["data-".to_string(), "other-".to_string()].into_iter().collect();
assert_eq!(seen_prefixes, expected, "pagination must cover every common prefix");
}
#[test]
fn test_max_keys_plus_one_caps_before_lookahead() {
assert_eq!(max_keys_plus_one(999, true), 1000);
assert_eq!(max_keys_plus_one(MAX_OBJECT_LIST, true), MAX_OBJECT_LIST + 1);
assert_eq!(max_keys_plus_one(MAX_OBJECT_LIST + 1, true), MAX_OBJECT_LIST + 1);
assert_eq!(max_keys_plus_one(i32::MAX, true), MAX_OBJECT_LIST + 1);
assert_eq!(max_keys_plus_one(-1, true), MAX_OBJECT_LIST + 1);
}
#[test]
fn normalize_list_quorum_accepts_supported_values() {
assert_eq!(normalize_list_quorum("strict"), "strict");
assert_eq!(normalize_list_quorum("disk"), "disk");
assert_eq!(normalize_list_quorum("reduced"), "reduced");
assert_eq!(normalize_list_quorum("optimal"), "optimal");
assert_eq!(normalize_list_quorum("auto"), "auto");
assert_eq!(normalize_list_quorum(" OPTIMAL "), "optimal");
}
#[test]
fn normalize_list_quorum_falls_back_to_strict() {
assert_eq!(normalize_list_quorum(""), "strict");
assert_eq!(normalize_list_quorum("unknown"), "strict");
}
#[test]
#[serial_test::serial]
fn list_objects_quorum_from_env_defaults_to_optimal() {
temp_env::with_var_unset(ENV_API_LIST_OBJECTS_QUORUM, || {
assert_eq!(list_objects_quorum_from_env(), "optimal");
});
}
#[test]
#[serial_test::serial]
fn list_objects_quorum_from_env_honors_supported_value() {
temp_env::with_var(ENV_API_LIST_OBJECTS_QUORUM, Some("strict"), || {
assert_eq!(list_objects_quorum_from_env(), "strict");
});
}
#[test]
#[serial_test::serial]
fn list_objects_index_mode_from_env_defaults_to_walker() {
temp_env::with_var_unset(ENV_API_LIST_OBJECTS_INDEX_MODE, || {
assert_eq!(list_objects_index_mode_from_env(), None);
});
}
#[test]
#[serial_test::serial]
fn list_objects_index_mode_from_env_accepts_key_only_aliases() {
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_MODE, Some("key_only"), || {
assert_eq!(list_objects_index_mode_from_env(), Some(ListSourceMode::IndexKeyOnly));
});
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_MODE, Some("index_key_only"), || {
assert_eq!(list_objects_index_mode_from_env(), Some(ListSourceMode::IndexKeyOnly));
});
}
#[test]
#[serial_test::serial]
fn list_objects_index_mode_from_env_accepts_verified_page_aliases() {
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_MODE, Some("verified_page"), || {
assert_eq!(list_objects_index_mode_from_env(), Some(ListSourceMode::IndexVerifiedPage));
});
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_MODE, Some("index_verified_page"), || {
assert_eq!(list_objects_index_mode_from_env(), Some(ListSourceMode::IndexVerifiedPage));
});
}
#[test]
#[serial_test::serial]
fn list_objects_index_mode_from_env_accepts_metadata_fast_without_guardrails() {
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_MODE, Some("index_metadata_fast"), || {
temp_env::with_var_unset(ENV_API_LIST_OBJECTS_METADATA_FAST_ENABLED, || {
temp_env::with_var_unset(ENV_API_LIST_OBJECTS_METADATA_FAST_STALENESS_MS, || {
assert_eq!(list_objects_metadata_fast_guardrails_from_env(), None);
assert_eq!(list_objects_index_mode_from_env(), Some(ListSourceMode::IndexMetadataFast));
});
});
});
}
#[test]
#[serial_test::serial]
fn list_objects_index_mode_from_env_accepts_metadata_fast_without_sla() {
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_MODE, Some("metadata_fast"), || {
temp_env::with_var(ENV_API_LIST_OBJECTS_METADATA_FAST_ENABLED, Some("true"), || {
temp_env::with_var_unset(ENV_API_LIST_OBJECTS_METADATA_FAST_STALENESS_MS, || {
assert_eq!(list_objects_metadata_fast_guardrails_from_env(), None);
assert_eq!(list_objects_index_mode_from_env(), Some(ListSourceMode::IndexMetadataFast));
});
});
});
}
#[test]
#[serial_test::serial]
fn list_objects_index_mode_from_env_accepts_metadata_fast_with_sla_guardrails() {
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_MODE, Some("index_metadata_fast"), || {
temp_env::with_var(ENV_API_LIST_OBJECTS_METADATA_FAST_ENABLED, Some("true"), || {
temp_env::with_var(ENV_API_LIST_OBJECTS_METADATA_FAST_STALENESS_MS, Some("5000"), || {
assert_eq!(list_objects_metadata_fast_guardrails_from_env(), Some(5000));
assert_eq!(list_objects_index_mode_from_env(), Some(ListSourceMode::IndexMetadataFast));
});
});
});
}
#[test]
#[serial_test::serial]
fn list_objects_index_mode_from_env_accepts_metadata_fast_over_sla_budget() {
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_MODE, Some("index_metadata_fast"), || {
temp_env::with_var(ENV_API_LIST_OBJECTS_METADATA_FAST_ENABLED, Some("true"), || {
temp_env::with_var(ENV_API_LIST_OBJECTS_METADATA_FAST_STALENESS_MS, Some("60001"), || {
assert_eq!(list_objects_metadata_fast_guardrails_from_env(), None);
assert_eq!(list_objects_index_mode_from_env(), Some(ListSourceMode::IndexMetadataFast));
});
});
});
}
#[test]
fn persistent_list_metadata_object_round_trips_encoded_snapshot() {
let object = PersistentListMetadataObject {
name: "photos/2026/img\t01.jpg".to_string(),
size: 42,
mod_time: Some(time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp")),
etag: Some("etag-42".to_string()),
storage_class: Some("STANDARD".to_string()),
};
let encoded = encode_persistent_list_metadata_object(&object);
let parsed = parse_persistent_list_metadata_object(&encoded).expect("metadata object should parse");
assert_eq!(parsed, object);
}
#[test]
fn persistent_key_only_index_parses_legacy_keys_and_metadata_snapshots() {
let object = PersistentListMetadataObject {
name: "object-b".to_string(),
size: 7,
mod_time: None,
etag: Some("etag-b".to_string()),
storage_class: None,
};
let contents = format!(
"{PERSISTENT_KEY_ONLY_INDEX_HEADER}\n\
{PERSISTENT_KEY_ONLY_INDEX_BUCKET_HEADER}bucket\n\
{PERSISTENT_KEY_ONLY_INDEX_GENERATION_HEADER}generation-42\n\
{PERSISTENT_KEY_ONLY_INDEX_CHECKPOINT_HEADER}9\n\
object-a\n\
{}\n",
encode_persistent_list_metadata_object(&object)
);
let index = parse_persistent_key_only_index(&contents);
assert_eq!(index.bucket.as_deref(), Some("bucket"));
assert_eq!(index.generation, "generation-42");
assert_eq!(index.checkpoint_high_water_mark, 9);
assert_eq!(index.keys.as_slice(), &["object-a".to_string(), "object-b".to_string()]);
assert_eq!(index.objects.as_slice(), &[object]);
assert!(!persistent_key_only_index_has_complete_metadata_snapshot(&index));
}
#[test]
fn metadata_snapshot_candidates_page_without_live_verification() {
let objects = vec![
PersistentListMetadataObject {
name: "photos/2026/a.jpg".to_string(),
size: 1,
mod_time: None,
etag: Some("etag-a".to_string()),
storage_class: Some("STANDARD".to_string()),
},
PersistentListMetadataObject {
name: "photos/2026/nested/b.jpg".to_string(),
size: 2,
mod_time: None,
etag: Some("etag-b".to_string()),
storage_class: Some("STANDARD".to_string()),
},
PersistentListMetadataObject {
name: "photos/2026/z.jpg".to_string(),
size: 3,
mod_time: None,
etag: Some("etag-z".to_string()),
storage_class: Some("STANDARD".to_string()),
},
];
let result = list_objects_from_metadata_snapshot_candidates(
"bucket",
"photos/2026/",
Some("photos/2026/a.jpg"),
&Some("/".to_string()),
2,
&objects,
);
assert_eq!(result.stats.candidate_keys, 3);
assert_eq!(result.stats.live_verify_attempts, 0);
assert_eq!(
result
.info
.objects
.iter()
.map(|object| object.name.as_str())
.collect::<Vec<_>>(),
["photos/2026/z.jpg"]
);
assert_eq!(result.info.objects[0].etag.as_deref(), Some("etag-z"));
assert_eq!(result.info.prefixes, vec!["photos/2026/nested/".to_string()]);
assert!(!result.info.is_truncated);
}
#[test]
fn metadata_fast_requires_complete_metadata_snapshot() {
let index = PersistentKeyOnlyIndex {
format_version: PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION,
bucket: Some("bucket".to_string()),
generation: "generation-42".to_string(),
checkpoint_high_water_mark: 42,
keys: Arc::new(vec!["a".to_string(), "b".to_string()]),
objects: Arc::new(vec![PersistentListMetadataObject {
name: "a".to_string(),
size: 1,
mod_time: None,
etag: None,
storage_class: None,
}]),
};
assert!(!persistent_key_only_index_has_complete_metadata_snapshot(&index));
let complete = PersistentKeyOnlyIndex {
format_version: PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION,
bucket: Some("bucket".to_string()),
generation: "generation-42".to_string(),
checkpoint_high_water_mark: 42,
keys: Arc::new(vec!["a".to_string()]),
objects: Arc::new(vec![PersistentListMetadataObject {
name: "a".to_string(),
size: 1,
mod_time: None,
etag: None,
storage_class: None,
}]),
};
assert!(persistent_key_only_index_has_complete_metadata_snapshot(&complete));
}
#[test]
#[serial_test::serial]
fn list_objects_index_provider_from_env_is_default_off() {
temp_env::with_var_unset(ENV_API_LIST_OBJECTS_INDEX_PROVIDER, || {
assert_eq!(list_objects_index_provider_from_env(), None);
assert_eq!(list_objects_index_provider_state_from_env(), None);
});
}
#[test]
#[serial_test::serial]
fn list_objects_index_provider_from_env_publishes_live_generation_when_enabled() {
temp_env::with_var(
ENV_API_LIST_OBJECTS_INDEX_PROVIDER,
Some(LIST_OBJECTS_INDEX_PROVIDER_WALKER_KEY_ONLY),
|| {
assert_eq!(list_objects_index_provider_from_env(), Some(ListObjectsIndexProviderKind::WalkerKeyOnly));
let health = list_objects_index_provider_state_from_env()
.expect("walker provider should be configured")
.health_snapshot();
assert_eq!(health.state, ListIndexLifecycleState::Healthy);
assert_eq!(health.active_generation.as_deref(), Some(LIST_CURSOR_GENERATION_LIVE));
assert_eq!(health.fallback_reason, None);
},
);
}
#[test]
#[serial_test::serial]
fn list_objects_index_provider_from_env_accepts_persistent_key_only() {
temp_env::with_var(
ENV_API_LIST_OBJECTS_INDEX_PROVIDER,
Some(LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY),
|| {
assert_eq!(
list_objects_index_provider_from_env(),
Some(ListObjectsIndexProviderKind::PersistentKeyOnly)
);
},
);
}
#[test]
#[serial_test::serial]
fn list_objects_index_provider_state_degrades_persistent_without_path() {
temp_env::with_var(
ENV_API_LIST_OBJECTS_INDEX_PROVIDER,
Some(LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY),
|| {
temp_env::with_var_unset(ENV_API_LIST_OBJECTS_INDEX_PROVIDER_PATH, || {
let provider = list_objects_index_provider_state_from_env().expect("persistent provider should be selected");
let health = provider.health_snapshot();
assert_eq!(provider.kind, ListObjectsIndexProviderKind::PersistentKeyOnly);
assert_eq!(provider.persistent_path, None);
assert_eq!(health.state, ListIndexLifecycleState::Degraded);
assert_eq!(health.fallback_reason, Some(ListIndexFallbackReason::Degraded));
});
},
);
}
#[test]
#[serial_test::serial]
fn list_objects_index_provider_state_rebuilds_persistent_until_index_is_loaded() {
let index_path = "/tmp/rustfs-listobjects-key-only.index";
temp_env::with_var(
ENV_API_LIST_OBJECTS_INDEX_PROVIDER,
Some(LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY),
|| {
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_PROVIDER_PATH, Some(index_path), || {
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_PROVIDER_GENERATION, Some("bench-20260706"), || {
let provider =
list_objects_index_provider_state_from_env().expect("persistent provider should be selected");
let health = provider.health_snapshot();
assert_eq!(provider.kind, ListObjectsIndexProviderKind::PersistentKeyOnly);
assert_eq!(provider.persistent_path.as_deref(), Some(std::path::Path::new(index_path)));
assert_eq!(provider.persistent_generation.as_deref(), Some("bench-20260706"));
assert_eq!(health.state, ListIndexLifecycleState::Rebuilding);
assert_eq!(health.staging_generation.as_deref(), Some("bench-20260706"));
assert_eq!(health.fallback_reason, Some(ListIndexFallbackReason::Rebuilding));
});
});
},
);
}
#[test]
fn parse_persistent_key_only_index_sorts_and_deduplicates_keys() {
let index = parse_persistent_key_only_index(
"# rustfs-listobjects-key-only-v1\n\
# bucket=photos\n\
# generation=bench-20260706\n\
# checkpoint_high_water_mark=99\n\
photos/c.jpg\n\
photos/a.jpg\r\n\
\n\
photos/b.jpg\n\
photos/a.jpg\n",
);
assert_eq!(index.bucket.as_deref(), Some("photos"));
assert_eq!(index.generation, "bench-20260706");
assert_eq!(index.checkpoint_high_water_mark, 99);
assert_eq!(
index.keys.as_slice(),
vec![
"photos/a.jpg".to_string(),
"photos/b.jpg".to_string(),
"photos/c.jpg".to_string()
]
);
}
#[test]
fn parse_namespace_mutation_journal_state_reads_bucket_and_high_water_mark() {
let state = parse_namespace_mutation_journal_state(
"# rustfs-listobjects-namespace-journal-v1\n\
# bucket=photos\n\
# high_water_mark=123\n\
# status=healthy\n",
)
.expect("journal state should parse");
assert_eq!(state.bucket.as_deref(), Some("photos"));
assert_eq!(state.high_water_mark, 123);
assert_eq!(state.status, NamespaceMutationJournalStatus::Healthy);
}
#[test]
fn namespace_mutation_journal_chaos_env_accepts_controlled_status() {
temp_env::with_var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS, Some("degraded"), || {
assert_eq!(
namespace_mutation_journal_chaos_status_from_env(),
Some(NamespaceMutationJournalStatus::Degraded)
);
});
temp_env::with_var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS, Some("HEALTHY"), || {
assert_eq!(
namespace_mutation_journal_chaos_status_from_env(),
Some(NamespaceMutationJournalStatus::Healthy)
);
});
temp_env::with_var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS, Some("unknown"), || {
assert_eq!(namespace_mutation_journal_chaos_status_from_env(), None);
});
}
#[test]
fn namespace_mutation_journal_chaos_env_requires_explicit_enable() {
temp_env::with_var_unset(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, || {
assert!(!namespace_mutation_journal_chaos_enabled_from_env());
});
temp_env::with_var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, Some("true"), || {
assert!(namespace_mutation_journal_chaos_enabled_from_env());
});
temp_env::with_var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, Some("1"), || {
assert!(namespace_mutation_journal_chaos_enabled_from_env());
});
temp_env::with_var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, Some("on"), || {
assert!(namespace_mutation_journal_chaos_enabled_from_env());
});
temp_env::with_var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, Some("false"), || {
assert!(!namespace_mutation_journal_chaos_enabled_from_env());
});
}
#[test]
fn namespace_mutation_journal_chaos_env_reads_bucket_and_sequence() {
temp_env::with_vars(
[
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET, Some("bench-bucket")),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_SEQUENCE, Some("42")),
],
|| {
assert_eq!(namespace_mutation_journal_chaos_bucket_from_env().as_deref(), Some("bench-bucket"));
assert_eq!(namespace_mutation_journal_chaos_sequence_from_env(), Some(42));
},
);
temp_env::with_var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_SEQUENCE, Some("not-a-number"), || {
assert_eq!(namespace_mutation_journal_chaos_sequence_from_env(), None);
});
}
#[test]
fn namespace_mutation_journal_chaos_config_requires_enable_bucket_and_status() {
temp_env::with_vars(
[
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, Some("true")),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET, Some("bench-bucket")),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS, Some("degraded")),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_SEQUENCE, Some("42")),
],
|| {
let config = namespace_mutation_journal_chaos_config_from_env().expect("enabled chaos config should parse");
assert_eq!(config.bucket, "bench-bucket");
assert_eq!(config.status, NamespaceMutationJournalStatus::Degraded);
assert_eq!(config.sequence, Some(42));
},
);
temp_env::with_vars(
[
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, Some("false")),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET, Some("bench-bucket")),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS, Some("degraded")),
],
|| {
assert_eq!(namespace_mutation_journal_chaos_config_from_env(), None);
},
);
temp_env::with_vars(
[
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, Some("true")),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET, Some("bench-bucket")),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS, Some("invalid")),
],
|| {
assert_eq!(namespace_mutation_journal_chaos_config_from_env(), None);
},
);
temp_env::with_vars(
[
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_ENABLED, Some("true")),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_BUCKET, None::<&str>),
(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_CHAOS_STATUS, Some("degraded")),
],
|| {
assert_eq!(namespace_mutation_journal_chaos_config_from_env(), None);
},
);
}
#[tokio::test]
async fn namespace_mutation_journal_write_never_regresses() {
let tempdir = tempfile::tempdir().expect("tempdir should be created");
let journal_root = tempdir.path().join("namespace-mutation-journal");
assert_eq!(
write_namespace_mutation_journal_state(
NamespaceMutationJournalBackend::LocalPath(journal_root.clone()),
"bucket",
7,
false,
)
.await
.expect("journal sequence should be written")
.high_water_mark,
7
);
assert_eq!(
write_namespace_mutation_journal_state(
NamespaceMutationJournalBackend::LocalPath(journal_root.clone()),
"bucket",
3,
false,
)
.await
.expect("journal sequence should not regress")
.high_water_mark,
7
);
}
#[test]
#[serial_test::serial]
fn observed_mutation_persists_namespace_journal_high_water() {
let tempdir = tempfile::tempdir().expect("tempdir should be created");
let index_path = tempdir.path().join("persistent-key-only.index");
let journal_root = tempdir.path().join("namespace-mutation-journal");
let index_path = index_path.to_str().expect("index path should be utf8");
let journal_root = journal_root.to_str().expect("journal path should be utf8");
temp_env::with_var(
ENV_API_LIST_OBJECTS_INDEX_PROVIDER,
Some(LIST_OBJECTS_INDEX_PROVIDER_PERSISTENT_KEY_ONLY),
|| {
temp_env::with_var(ENV_API_LIST_OBJECTS_INDEX_PROVIDER_PATH, Some(index_path), || {
temp_env::with_var(ENV_API_LIST_OBJECTS_NAMESPACE_JOURNAL_PATH, Some(journal_root), || {
let runtime = tokio::runtime::Runtime::new().expect("tokio runtime should start");
runtime.block_on(async {
reset_list_objects_mutation_sequences_for_test().await;
persist_observed_list_objects_mutation(None, "bucket", 11).await;
let state = load_namespace_mutation_journal_state(
NamespaceMutationJournalBackend::LocalPath(std::path::PathBuf::from(journal_root)),
"bucket",
)
.await
.expect("journal state should load")
.expect("journal state should exist");
assert_eq!(state.high_water_mark, 11);
assert_eq!(state.status, NamespaceMutationJournalStatus::Healthy);
assert_eq!(current_list_objects_mutation_sequence("bucket").await, 11);
});
});
});
},
);
}
#[tokio::test]
#[serial_test::serial]
async fn persistent_key_only_index_load_recovers_mutation_sequence_from_journal() {
let tempdir = tempfile::tempdir().expect("tempdir should be created");
let index_path = tempdir.path().join("persistent-key-only.index");
let journal_root = tempdir.path().join("namespace-mutation-journal");
let keys = vec!["object-a".to_string(), "object-b".to_string()];
write_persistent_key_only_index_with_metadata(None, &index_path, "bucket", "generation-42", 5, &keys, &[])
.await
.expect("index should be written");
write_namespace_mutation_journal_state(NamespaceMutationJournalBackend::LocalPath(journal_root), "bucket", 9, false)
.await
.expect("journal sequence should be written");
reset_list_objects_mutation_sequences_for_test().await;
let index = load_persistent_key_only_index(None, &index_path)
.await
.expect("index should load");
assert_eq!(index.checkpoint_high_water_mark, 5);
assert_eq!(current_list_objects_mutation_sequence("bucket").await, 9);
}
#[test]
fn persistent_key_only_index_provider_match_rejects_configured_generation_mismatch() {
let index = PersistentKeyOnlyIndex {
format_version: PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION,
bucket: Some("bucket".to_string()),
generation: "generation-old".to_string(),
checkpoint_high_water_mark: 42,
keys: Arc::new(vec!["a".to_string(), "b".to_string()]),
objects: Arc::new(Vec::new()),
};
let matching_provider = ListObjectsIndexProviderState::persistent_key_only(
Some(PathBuf::from("/tmp/persistent-key-only.index")),
Some("generation-old".to_string()),
);
let mismatching_provider = ListObjectsIndexProviderState::persistent_key_only(
Some(PathBuf::from("/tmp/persistent-key-only.index")),
Some("generation-new".to_string()),
);
assert!(persistent_key_only_index_matches_provider(&index, "bucket", &matching_provider));
assert!(!persistent_key_only_index_matches_provider(&index, "bucket", &mismatching_provider));
assert!(!persistent_key_only_index_matches_provider(&index, "other-bucket", &matching_provider));
}
#[test]
fn persistent_key_only_index_provider_match_rejects_legacy_format_without_configured_generation() {
let legacy = parse_persistent_key_only_index(&format!(
"# rustfs-listobjects-key-only-v1\n\
{PERSISTENT_KEY_ONLY_INDEX_BUCKET_HEADER}bucket\n\
{PERSISTENT_KEY_ONLY_INDEX_GENERATION_HEADER}generation-old\n\
{PERSISTENT_KEY_ONLY_INDEX_CHECKPOINT_HEADER}42\n\
# object\tbGVnYWN5\t1\t-\t-\tU1RBTkRBUkRfSUE=\n"
));
let provider =
ListObjectsIndexProviderState::persistent_key_only(Some(PathBuf::from("/tmp/persistent-key-only.index")), None);
assert_eq!(legacy.format_version, 0);
assert!(!persistent_key_only_index_matches_provider(&legacy, "bucket", &provider));
}
#[test]
fn current_persistent_snapshot_preserves_an_effective_transition_tier_name() {
let object = PersistentListMetadataObject::from_object_info(&ObjectInfo {
bucket: "bucket".to_string(),
name: "transitioned".to_string(),
storage_class: Some("STANDARD_IA".to_string()),
..Default::default()
});
let index = parse_persistent_key_only_index(&format!(
"{PERSISTENT_KEY_ONLY_INDEX_HEADER}\n\
{PERSISTENT_KEY_ONLY_INDEX_BUCKET_HEADER}bucket\n\
{PERSISTENT_KEY_ONLY_INDEX_GENERATION_HEADER}generation-current\n\
{PERSISTENT_KEY_ONLY_INDEX_CHECKPOINT_HEADER}42\n\
{}\n",
encode_persistent_list_metadata_object(&object)
));
let provider =
ListObjectsIndexProviderState::persistent_key_only(Some(PathBuf::from("/tmp/persistent-key-only.index")), None);
assert_eq!(index.format_version, PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION);
assert!(persistent_key_only_index_matches_provider(&index, "bucket", &provider));
assert_eq!(index.objects[0].to_object_info("bucket").storage_class.as_deref(), Some("STANDARD_IA"));
}
#[test]
fn persistent_key_only_index_health_uses_snapshot_generation_and_checkpoint() {
let index = PersistentKeyOnlyIndex {
format_version: PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION,
bucket: Some("bucket".to_string()),
generation: "generation-42".to_string(),
checkpoint_high_water_mark: 42,
keys: Arc::new(vec!["a".to_string(), "b".to_string()]),
objects: Arc::new(Vec::new()),
};
let health = persistent_key_only_index_health(
&index,
NamespaceMutationJournalSnapshot {
high_water_mark: 42,
degraded: false,
},
);
assert_eq!(health.state, ListIndexLifecycleState::Healthy);
assert_eq!(health.active_generation.as_deref(), Some("generation-42"));
assert_eq!(health.checkpoint_high_water_mark, 42);
assert_eq!(health.mutation_high_water_mark, 42);
assert_eq!(health.fallback_reason, None);
}
#[test]
fn persistent_key_only_index_health_reports_lagging_mutation_checkpoint() {
let index = PersistentKeyOnlyIndex {
format_version: PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION,
bucket: Some("bucket".to_string()),
generation: "generation-42".to_string(),
checkpoint_high_water_mark: 42,
keys: Arc::new(vec!["a".to_string(), "b".to_string()]),
objects: Arc::new(Vec::new()),
};
let health = persistent_key_only_index_health(
&index,
NamespaceMutationJournalSnapshot {
high_water_mark: 43,
degraded: false,
},
);
assert_eq!(health.state, ListIndexLifecycleState::Lagging);
assert_eq!(health.active_generation.as_deref(), Some("generation-42"));
assert_eq!(health.checkpoint_high_water_mark, 42);
assert_eq!(health.mutation_high_water_mark, 43);
assert_eq!(health.mutation_lag, 1);
assert_eq!(health.fallback_reason, Some(ListIndexFallbackReason::Lagging));
}
#[test]
fn persistent_key_only_index_health_reports_degraded_journal() {
let index = PersistentKeyOnlyIndex {
format_version: PERSISTENT_KEY_ONLY_INDEX_FORMAT_VERSION,
bucket: Some("bucket".to_string()),
generation: "generation-42".to_string(),
checkpoint_high_water_mark: 42,
keys: Arc::new(vec!["a".to_string(), "b".to_string()]),
objects: Arc::new(Vec::new()),
};
let health = persistent_key_only_index_health(
&index,
NamespaceMutationJournalSnapshot {
high_water_mark: 42,
degraded: true,
},
);
assert_eq!(health.state, ListIndexLifecycleState::Degraded);
assert_eq!(health.fallback_reason, Some(ListIndexFallbackReason::Degraded));
}
#[tokio::test]
#[serial_test::serial]
async fn list_objects_mutation_sequence_advances_per_bucket() {
reset_list_objects_mutation_sequences_for_test().await;
assert_eq!(current_list_objects_mutation_sequence("bucket-a").await, 0);
assert_eq!(observe_list_objects_mutations_with_store(None, "bucket-a", 1).await, Some(1));
assert_eq!(observe_list_objects_mutations_with_store(None, "bucket-a", 2).await, Some(3));
assert_eq!(current_list_objects_mutation_sequence("bucket-a").await, 3);
assert_eq!(current_list_objects_mutation_sequence("bucket-b").await, 0);
assert_eq!(observe_list_objects_mutations_with_store(None, "bucket-b", 0).await, None);
assert_eq!(current_list_objects_mutation_sequence("bucket-b").await, 0);
}
#[tokio::test]
#[serial_test::serial]
async fn scanner_namespace_generation_tracks_only_user_namespace_mutations() {
reset_list_objects_mutation_sequences_for_test().await;
assert_eq!(scanner_namespace_mutation_generation(), 0);
assert_eq!(observe_list_objects_mutations_with_store(None, RUSTFS_META_BUCKET, 3).await, Some(3));
assert_eq!(scanner_namespace_mutation_generation(), 0);
assert_eq!(observe_list_objects_mutations_with_store(None, "photos", 2).await, Some(5));
assert_eq!(scanner_namespace_mutation_generation(), 2);
}
#[test]
fn empty_directory_listing_purge_requires_complete_first_page_of_prefix() {
let empty = ListObjectsInfo::default();
assert!(should_purge_empty_directory_listing("ghost/", None, 1, false, &empty));
assert!(should_purge_empty_directory_listing("ghost/", None, 1000, false, &empty));
assert!(!should_purge_empty_directory_listing("ghost", None, 1, false, &empty));
assert!(!should_purge_empty_directory_listing("ghost/", Some("marker"), 1, false, &empty));
assert!(!should_purge_empty_directory_listing("ghost/", None, 0, false, &empty));
assert!(!should_purge_empty_directory_listing("ghost/", None, 1, true, &empty));
let mut live = ListObjectsInfo::default();
live.objects.push(ObjectInfo::default());
assert!(!should_purge_empty_directory_listing("ghost/", None, 1, false, &live));
let mut prefixed = ListObjectsInfo::default();
prefixed.prefixes.push("ghost/child/".to_owned());
assert!(!should_purge_empty_directory_listing("ghost/", None, 1, false, &prefixed));
let truncated = ListObjectsInfo {
is_truncated: true,
..Default::default()
};
assert!(!should_purge_empty_directory_listing("ghost/", None, 1, false, &truncated));
}
#[test]
fn recursive_bucket_orphan_purge_requires_an_empty_complete_root_scan() {
let empty = ListObjectsInfo::default();
assert!(super::should_purge_empty_recursive_bucket_listing("", None, None, 1, false, &empty));
assert!(!super::should_purge_empty_recursive_bucket_listing(
"ghost/", None, None, 1, false, &empty
));
assert!(!super::should_purge_empty_recursive_bucket_listing("", Some("/"), None, 1, false, &empty));
assert!(!super::should_purge_empty_recursive_bucket_listing(
"",
None,
Some("marker"),
1,
false,
&empty
));
assert!(!super::should_purge_empty_recursive_bucket_listing("", None, None, 0, false, &empty));
assert!(!super::should_purge_empty_recursive_bucket_listing("", None, None, 1, true, &empty));
let live = ListObjectsInfo {
objects: vec![ObjectInfo::default()],
..Default::default()
};
assert!(!super::should_purge_empty_recursive_bucket_listing("", None, None, 1, false, &live));
let incomplete = ListObjectsInfo {
is_truncated: true,
..Default::default()
};
assert!(!super::should_purge_empty_recursive_bucket_listing("", None, None, 1, false, &incomplete));
}
#[tokio::test]
async fn empty_recursive_listing_purges_committed_delete_residue() {
use crate::bucket::metadata_sys::{init_bucket_metadata_sys, test_support::isolated_store_over_temp_disks};
use crate::storage_api_contracts::bucket::{BucketOperations as _, MakeBucketOptions};
let (dirs, store) = isolated_store_over_temp_disks().await;
let bucket = "listing-purge-bucket";
init_bucket_metadata_sys(store.clone(), Vec::new()).await;
store
.make_bucket(bucket, &MakeBucketOptions::default())
.await
.expect("bucket should be created with authoritative metadata");
let data_dir = uuid::Uuid::new_v4();
let transaction = uuid::Uuid::new_v4();
for dir in &dirs {
let residue = dir
.path()
.join(bucket)
.join("ghost")
.join("nested")
.join("object")
.join(data_dir.to_string());
tokio::fs::create_dir_all(&residue)
.await
.expect("committed delete residue should be created");
tokio::fs::write(residue.join("part.1"), b"stale")
.await
.expect("stale part should be written");
tokio::fs::write(
residue.join(format!("{}{}", crate::disk::local::DELETE_DATA_DIR_MARKER_PREFIX, transaction)),
[],
)
.await
.expect("committed delete marker should be written");
}
let result = store
.list_objects_generic(bucket, "ghost/", None, None, 1, false)
.await
.expect("empty recursive listing should succeed");
assert!(result.objects.is_empty());
assert!(result.prefixes.is_empty());
for dir in &dirs {
assert!(
!dir.path().join(bucket).join("ghost").exists(),
"the empty listing should reclaim its committed delete residue"
);
}
}
#[tokio::test]
async fn empty_recursive_bucket_listing_purges_orphan_directory_prefixes() {
use crate::bucket::metadata_sys::{init_bucket_metadata_sys, test_support::isolated_store_over_temp_disks};
use crate::storage_api_contracts::bucket::{BucketOperations as _, MakeBucketOptions};
let (dirs, store) = isolated_store_over_temp_disks().await;
let bucket = "recursive-bucket-orphan-purge";
init_bucket_metadata_sys(store.clone(), Vec::new()).await;
store
.make_bucket(bucket, &MakeBucketOptions::default())
.await
.expect("bucket should be created with authoritative metadata");
for dir in &dirs {
tokio::fs::create_dir_all(dir.path().join(bucket).join("ghost").join("nested").join("leaf"))
.await
.expect("metadata-less orphan directory tree should be created");
}
let result = store
.clone()
.list_objects_generic(bucket, "", None, None, 1000, false)
.await
.expect("recursive bucket listing should succeed");
assert!(result.objects.is_empty(), "orphan directories are not S3 objects");
assert!(result.prefixes.is_empty(), "a delimiter-less listing has no CommonPrefixes");
for dir in &dirs {
assert!(
!dir.path().join(bucket).join("ghost").exists(),
"an empty recursive bucket scan should reclaim its metadata-less orphan prefix"
);
}
let versioned_bucket = "recursive-bucket-versioned-orphan";
store
.make_bucket(versioned_bucket, &MakeBucketOptions::default())
.await
.expect("versioned test bucket should be created");
store
.update_bucket_metadata_config(
versioned_bucket,
crate::bucket::metadata::BUCKET_VERSIONING_CONFIG,
b"<VersioningConfiguration><Status>Enabled</Status></VersioningConfiguration>".to_vec(),
)
.await
.expect("bucket versioning should be enabled");
for dir in &dirs {
tokio::fs::create_dir_all(dir.path().join(versioned_bucket).join("ghost").join("nested").join("leaf"))
.await
.expect("versioned bucket orphan tree should be created");
}
store
.clone()
.list_objects_generic(versioned_bucket, "", None, None, 1000, false)
.await
.expect("recursive versioned bucket listing should succeed");
for dir in &dirs {
assert!(
dir.path().join(versioned_bucket).join("ghost").exists(),
"root recursive LIST must not purge orphan residue in a versioned bucket"
);
}
}
#[tokio::test]
async fn list_objects_exact_prefix_paginates_across_storage_layers() {
use crate::bucket::metadata_sys::{init_bucket_metadata_sys, test_support::isolated_store_over_temp_disks};
use crate::object_api::{ObjectOptions, PutObjReader};
use crate::storage_api_contracts::bucket::{BucketOperations as _, MakeBucketOptions};
use crate::storage_api_contracts::object::{ObjectIO as _, ObjectOperations as _};
let (_dirs, store) = isolated_store_over_temp_disks().await;
let bucket = "exact-prefix-pagination-bucket";
init_bucket_metadata_sys(store.clone(), Vec::new()).await;
store
.make_bucket(bucket, &MakeBucketOptions::default())
.await
.expect("exact-prefix pagination bucket should be created");
for name in ["a", "ab"] {
store.pools[0]
.put_object(
bucket,
name,
&mut PutObjReader::from_vec(b"pagination fixture".to_vec()),
&ObjectOptions {
no_lock: true,
..Default::default()
},
)
.await
.expect("pagination fixture object should be written");
let info = store
.get_object_info(
bucket,
name,
&ObjectOptions {
no_lock: true,
..Default::default()
},
)
.await
.expect("exact-prefix fixture must be readable by object lookup");
assert!(!info.delete_marker && info.version_purge_status.is_empty());
}
for layer in 0..3 {
for (prefix, expected) in [("a", vec!["a", "ab"]), ("ab", vec!["ab"]), ("missing", vec![])] {
let mut marker = None;
for page in 0..expected.len().max(1) {
let result = match layer {
0 => {
store
.clone()
.list_objects_generic(bucket, prefix, marker.clone(), None, 1, false)
.await
}
1 => {
store.pools[0]
.clone()
.list_objects_generic(bucket, prefix, marker.clone(), None, 1, false)
.await
}
_ => {
store.pools[0].disk_set[0]
.clone()
.list_objects_generic(bucket, prefix, marker.clone(), None, 1, false)
.await
}
}
.expect("exact-prefix page should list successfully");
let names: Vec<_> = result.objects.iter().map(|object| object.name.as_str()).collect();
let expected_page: Vec<_> = expected.get(page).copied().into_iter().collect();
assert_eq!(names, expected_page, "layer {layer}, prefix {prefix}, page {page}");
assert!(result.prefixes.is_empty(), "recursive listing should not return common prefixes");
let has_more = page + 1 < expected.len();
assert_eq!(result.is_truncated, has_more, "layer {layer}, prefix {prefix}, page {page}");
assert_eq!(result.next_marker.is_some(), has_more, "only non-final pages should carry a marker");
if has_more {
assert_ne!(result.next_marker, marker, "pagination marker must advance");
}
marker = result.next_marker;
}
}
}
}
#[tokio::test]
async fn list_objects_hides_pending_version_purge_across_walk_and_exact_prefix() {
use crate::bucket::metadata_sys::{init_bucket_metadata_sys, test_support::isolated_store_over_temp_disks};
use crate::storage_api_contracts::bucket::{BucketOperations as _, MakeBucketOptions};
let (dirs, store) = isolated_store_over_temp_disks().await;
let bucket = "pending-purge-listing-bucket";
let object = "spilo/_permtest";
init_bucket_metadata_sys(store.clone(), Vec::new()).await;
store
.make_bucket(bucket, &MakeBucketOptions::default())
.await
.expect("bucket should be created with authoritative metadata");
let (entry, data_dir) = test_pending_version_purge_meta_entry(bucket, object);
for dir in &dirs {
let object_dir = dir.path().join(bucket).join(object);
tokio::fs::create_dir_all(object_dir.join(data_dir.to_string()))
.await
.expect("pending-purge object data directory should be created");
tokio::fs::write(object_dir.join(data_dir.to_string()).join("part.1"), b"x")
.await
.expect("pending-purge object part should be written");
tokio::fs::write(object_dir.join(STORAGE_FORMAT_FILE), &entry.metadata)
.await
.expect("pending-purge metadata should be written");
}
let recursive = store
.clone()
.list_objects_generic(bucket, "", None, None, 1000, false)
.await
.expect("recursive listing should succeed");
assert!(
recursive.objects.is_empty(),
"recursive ListObjectsV2 should hide pending version-purge entries"
);
assert!(
recursive.prefixes.is_empty(),
"recursive ListObjectsV2 should not synthesize prefixes from hidden entries"
);
let exact = store
.list_objects_generic(bucket, object, None, None, 1, false)
.await
.expect("exact-prefix listing should succeed");
assert!(
exact.objects.is_empty(),
"exact-prefix max_keys=1 listing should hide pending version-purge entries"
);
assert!(exact.prefixes.is_empty());
}
#[tokio::test]
async fn empty_delimiter_listing_hides_and_purges_committed_delete_residue() {
use crate::bucket::metadata_sys::{init_bucket_metadata_sys, test_support::isolated_store_over_temp_disks};
use crate::storage_api_contracts::bucket::{BucketOperations as _, MakeBucketOptions};
let (dirs, store) = isolated_store_over_temp_disks().await;
let bucket = "listing-purge-delimiter-bucket";
init_bucket_metadata_sys(store.clone(), Vec::new()).await;
store
.make_bucket(bucket, &MakeBucketOptions::default())
.await
.expect("bucket should be created with authoritative metadata");
let data_dir = uuid::Uuid::new_v4();
let transaction = uuid::Uuid::new_v4();
for dir in &dirs {
let residue = dir
.path()
.join(bucket)
.join("metrics")
.join("2026")
.join("object.parquet")
.join(data_dir.to_string());
tokio::fs::create_dir_all(&residue)
.await
.expect("committed delete residue should be created");
tokio::fs::write(residue.join("part.1"), b"stale")
.await
.expect("stale part should be written");
tokio::fs::write(
residue.join(format!("{}{}", crate::disk::local::DELETE_DATA_DIR_MARKER_PREFIX, transaction)),
[],
)
.await
.expect("committed delete marker should be written");
}
let result = store
.clone()
.list_objects_generic(bucket, "metrics/2026/", None, Some("/".to_owned()), 1000, false)
.await
.expect("delimiter listing should succeed");
assert!(result.objects.is_empty());
assert!(result.prefixes.is_empty(), "delete residue must not surface as a prefix");
for dir in &dirs {
assert!(
!dir.path().join(bucket).join("metrics").join("2026").exists(),
"the empty delimiter listing should reclaim the committed delete residue under it"
);
}
}
#[tokio::test]
async fn empty_delimiter_listing_of_residue_ancestor_hides_and_purges_whole_tree() {
use crate::bucket::metadata_sys::{init_bucket_metadata_sys, test_support::isolated_store_over_temp_disks};
use crate::storage_api_contracts::bucket::{BucketOperations as _, MakeBucketOptions};
let (dirs, store) = isolated_store_over_temp_disks().await;
let bucket = "listing-purge-ancestor-bucket";
init_bucket_metadata_sys(store.clone(), Vec::new()).await;
store
.make_bucket(bucket, &MakeBucketOptions::default())
.await
.expect("bucket should be created with authoritative metadata");
let data_dir = uuid::Uuid::new_v4();
let transaction = uuid::Uuid::new_v4();
for dir in &dirs {
let residue = dir
.path()
.join(bucket)
.join("metrics/kubelet/2026/08/28/23/74992556388248657933757.parquet")
.join(data_dir.to_string());
tokio::fs::create_dir_all(&residue)
.await
.expect("committed delete residue should be created");
tokio::fs::write(residue.join("part.1"), b"stale")
.await
.expect("stale part should be written");
tokio::fs::write(
residue.join(format!("{}{}", crate::disk::local::DELETE_DATA_DIR_MARKER_PREFIX, transaction)),
[],
)
.await
.expect("committed delete marker should be written");
}
let result = store
.clone()
.list_objects_generic(bucket, "metrics/", None, Some("/".to_owned()), 1000, false)
.await
.expect("delimiter listing should succeed");
assert!(result.objects.is_empty());
assert!(result.prefixes.is_empty(), "ancestors of delete residue must not surface as prefixes");
for dir in &dirs {
assert!(
!dir.path().join(bucket).join("metrics").exists(),
"the empty delimiter listing should reclaim the committed delete residue tree under it"
);
}
}
#[tokio::test]
async fn empty_delimiter_listing_of_mixed_residue_ancestor_reclaims_only_committed_subtree() {
use crate::bucket::metadata_sys::{init_bucket_metadata_sys, test_support::isolated_store_over_temp_disks};
use crate::storage_api_contracts::bucket::{BucketOperations as _, MakeBucketOptions};
let (dirs, store) = isolated_store_over_temp_disks().await;
let bucket = "listing-purge-mixed-bucket";
init_bucket_metadata_sys(store.clone(), Vec::new()).await;
store
.make_bucket(bucket, &MakeBucketOptions::default())
.await
.expect("bucket should be created with authoritative metadata");
let committed_dir = uuid::Uuid::new_v4();
let unmarked_dir = uuid::Uuid::new_v4();
let transaction = uuid::Uuid::new_v4();
for dir in &dirs {
let committed = dir
.path()
.join(bucket)
.join("metrics/cpu/2026/08/28/22/a.parquet")
.join(committed_dir.to_string());
tokio::fs::create_dir_all(&committed)
.await
.expect("committed delete residue should be created");
tokio::fs::write(committed.join("part.1"), b"stale")
.await
.expect("stale part should be written");
tokio::fs::write(
committed.join(format!("{}{}", crate::disk::local::DELETE_DATA_DIR_MARKER_PREFIX, transaction)),
[],
)
.await
.expect("committed delete marker should be written");
let unmarked = dir
.path()
.join(bucket)
.join("metrics/kubelet/2026/08/28/23/74992556388248657933757.parquet")
.join(unmarked_dir.to_string());
tokio::fs::create_dir_all(&unmarked)
.await
.expect("unmarked residue should be created");
tokio::fs::write(unmarked.join("part.1"), b"stale")
.await
.expect("stale part should be written");
}
let result = store
.clone()
.list_objects_generic(bucket, "metrics/", None, Some("/".to_owned()), 1000, false)
.await
.expect("delimiter listing should succeed");
assert!(result.objects.is_empty());
assert!(result.prefixes.is_empty(), "neither residue subtree may surface as a prefix");
for dir in &dirs {
let metrics = dir.path().join(bucket).join("metrics");
assert!(
!metrics.join("cpu").exists(),
"the committed subtree must be reclaimed even though a sibling subtree is blocked"
);
assert!(
metrics
.join("kubelet/2026/08/28/23/74992556388248657933757.parquet")
.join(unmarked_dir.to_string())
.join("part.1")
.exists(),
"residue without a committed marker must survive the purge"
);
}
}
#[test]
fn list_objects_index_provider_state_uses_lifecycle_active_generation() {
let provider = ListObjectsIndexProviderState::walker_key_only();
let health = provider.health_snapshot();
assert_eq!(provider.kind, ListObjectsIndexProviderKind::WalkerKeyOnly);
assert_eq!(health.state, ListIndexLifecycleState::Healthy);
assert_eq!(health.staging_generation, None);
assert_eq!(health.active_generation.as_deref(), Some(LIST_CURSOR_GENERATION_LIVE));
assert_eq!(
select_list_index_source_mode(Some(ListSourceMode::IndexKeyOnly), health.active_generation.as_deref(), &health),
ListIndexSourceDecision::UseIndex(ListSourceMode::IndexKeyOnly)
);
}
#[tokio::test]
async fn list_objects_verified_index_candidates_use_live_metadata_only() {
let candidates = vec![
"photos/2026/a.jpg".to_string(),
"photos/2026/b.jpg".to_string(),
"photos/2026/c.jpg".to_string(),
];
let result =
list_objects_from_verified_index_candidates("photos/2026/", None, &None, 100, &candidates, |key| async move {
Ok(Some(test_live_object_info(&key, "live-etag")))
})
.await
.expect("verified candidate listing should succeed");
assert_eq!(result.objects.len(), 3);
assert!(
result
.objects
.iter()
.all(|object| object.etag.as_deref() == Some("live-etag"))
);
assert!(result.prefixes.is_empty());
assert!(!result.is_truncated);
}
#[tokio::test]
async fn list_objects_verified_index_candidates_apply_marker_and_delimiter_boundaries() {
let candidates = vec![
"photos/2025/old.jpg".to_string(),
"photos/2026/a.jpg".to_string(),
"photos/2026/archive/b.jpg".to_string(),
"photos/2026/archive/c.jpg".to_string(),
"photos/2026/d.jpg".to_string(),
];
let result = list_objects_from_verified_index_candidates(
"photos/2026/",
Some("photos/2026/a.jpg"),
&Some("/".to_string()),
100,
&candidates,
|key| async move { Ok(Some(test_live_object_info(&key, "live-etag"))) },
)
.await
.expect("verified candidate listing should succeed");
assert_eq!(
result.objects.iter().map(|object| object.name.as_str()).collect::<Vec<_>>(),
vec!["photos/2026/d.jpg"]
);
assert_eq!(result.prefixes, vec!["photos/2026/archive/".to_string()]);
assert!(!result.is_truncated);
}
#[tokio::test]
async fn list_objects_verified_index_candidates_use_common_prefix_as_page_marker() {
let candidates = vec![
"photos/2026/archive/b.jpg".to_string(),
"photos/2026/archive/c.jpg".to_string(),
"photos/2026/d.jpg".to_string(),
];
let result = list_objects_from_verified_index_candidates(
"photos/2026/",
None,
&Some("/".to_string()),
1,
&candidates,
|key| async move { Ok(Some(test_live_object_info(&key, "live-etag"))) },
)
.await
.expect("verified candidate listing should succeed");
assert!(result.objects.is_empty());
assert_eq!(result.prefixes, vec!["photos/2026/archive/".to_string()]);
assert!(result.is_truncated);
assert_eq!(result.next_marker.as_deref(), Some("photos/2026/archive/"));
}
#[tokio::test]
async fn list_objects_verified_index_candidates_drop_deleted_or_failed_live_verifications() {
let candidates = vec!["photos/2026/a.jpg".to_string(), "photos/2026/deleted.jpg".to_string()];
let result =
list_objects_from_verified_index_candidates("photos/2026/", None, &None, 100, &candidates, |key| async move {
if key.ends_with("deleted.jpg") {
Ok(None)
} else {
Ok(Some(test_live_object_info(&key, "live-etag")))
}
})
.await
.expect("verified candidate listing should succeed");
assert_eq!(result.objects.len(), 1);
assert_eq!(result.objects[0].name, "photos/2026/a.jpg");
}
#[tokio::test]
async fn list_objects_verified_index_candidates_ignore_stale_delete_markers() {
let candidates = vec![
"photos/2026/live.jpg".to_string(),
"photos/2026/stale-delete-marker.jpg".to_string(),
];
let result =
list_objects_from_verified_index_candidates("photos/2026/", None, &None, 100, &candidates, |key| async move {
if key.ends_with("stale-delete-marker.jpg") {
Ok(None)
} else {
Ok(Some(test_live_object_info(&key, "live-etag")))
}
})
.await
.expect("verified candidate listing should succeed");
assert_eq!(
result.objects.iter().map(|object| object.name.as_str()).collect::<Vec<_>>(),
vec!["photos/2026/live.jpg"]
);
}
#[tokio::test]
async fn list_objects_verified_index_candidates_return_overwritten_live_metadata() {
let candidates = vec!["photos/2026/overwritten.jpg".to_string()];
let result =
list_objects_from_verified_index_candidates("photos/2026/", None, &None, 100, &candidates, |key| async move {
Ok(Some(test_live_object_info(&key, "new-live-etag")))
})
.await
.expect("verified candidate listing should succeed");
assert_eq!(result.objects.len(), 1);
assert_eq!(result.objects[0].etag.as_deref(), Some("new-live-etag"));
}
#[tokio::test]
async fn list_objects_verified_index_candidates_include_completed_multipart_after_live_verify() {
let candidates = vec!["photos/2026/multipart-complete.bin".to_string()];
let result =
list_objects_from_verified_index_candidates("photos/2026/", None, &None, 100, &candidates, |key| async move {
Ok(Some(test_live_object_info(&key, "completed-multipart-etag")))
})
.await
.expect("verified candidate listing should succeed");
assert_eq!(result.objects.len(), 1);
assert_eq!(result.objects[0].name, "photos/2026/multipart-complete.bin");
assert_eq!(result.objects[0].etag.as_deref(), Some("completed-multipart-etag"));
}
#[tokio::test]
async fn list_objects_verified_index_candidates_report_verification_stats() {
let candidates = vec![
"photos/2025/old.jpg".to_string(),
"photos/2026/a.jpg".to_string(),
"photos/2026/archive/b.jpg".to_string(),
"photos/2026/deleted.jpg".to_string(),
];
let result = list_objects_from_verified_index_candidates_with_stats(
"photos/2026/",
Some("photos/2026/a.jpg"),
&Some("/".to_string()),
100,
&candidates,
|key| async move {
if key.ends_with("deleted.jpg") {
Ok(None)
} else {
Ok(Some(test_live_object_info(&key, "live-etag")))
}
},
)
.await
.expect("verified candidate listing should succeed");
assert!(result.info.objects.is_empty());
assert_eq!(result.info.prefixes, vec!["photos/2026/archive/".to_string()]);
assert_eq!(result.stats.candidate_keys, 4);
assert_eq!(result.stats.skipped_keys, 2);
assert_eq!(result.stats.common_prefixes, 1);
assert_eq!(result.stats.live_verify_attempts, 1);
assert_eq!(result.stats.live_verify_hits, 0);
assert_eq!(result.stats.live_verify_misses, 1);
}
#[tokio::test]
async fn list_objects_verified_index_candidates_skip_stats_when_disabled() {
let candidates = vec!["photos/2026/a.jpg".to_string(), "photos/2026/deleted.jpg".to_string()];
let result = list_objects_from_verified_index_candidates_with_optional_stats(
"photos/2026/",
None,
&None,
100,
&candidates,
false,
|key| async move {
if key.ends_with("deleted.jpg") {
Ok(None)
} else {
Ok(Some(test_live_object_info(&key, "live-etag")))
}
},
)
.await
.expect("verified candidate listing should succeed");
assert_eq!(result.info.objects.len(), 1);
assert_eq!(result.stats, VerifiedIndexCandidateStats::default());
}
#[test]
fn list_index_provider_selection_rejects_generation_mismatch() {
let mut lifecycle = ListIndexLifecycle::disabled(10);
lifecycle.begin_rebuild("generation-2", 100);
lifecycle.checkpoint_rebuild(100);
assert!(lifecycle.publish_rebuild());
let health = lifecycle.health_snapshot();
let opts = ListPathOptions {
marker: Some("photos/2026/a.jpg[rustfs_cache:v2,id:list-cache-id,src:index_key_only,gen:generation-1]".to_string()),
..Default::default()
};
assert_eq!(
select_list_index_provider_source_mode(&opts, ListSourceMode::IndexKeyOnly, &health),
ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::GenerationMismatch)
);
}
#[test]
fn list_index_provider_selection_falls_back_when_degraded() {
let mut lifecycle = ListIndexLifecycle::disabled(10);
lifecycle.begin_rebuild("generation-1", 100);
lifecycle.checkpoint_rebuild(100);
assert!(lifecycle.publish_rebuild());
lifecycle.mark_degraded();
let health = lifecycle.health_snapshot();
assert_eq!(
select_list_index_provider_source_mode(&ListPathOptions::default(), ListSourceMode::IndexKeyOnly, &health),
ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::Degraded)
);
}
#[test]
fn metadata_fast_provider_selection_falls_back_when_checkpoint_lags() {
let mut lifecycle = ListIndexLifecycle::disabled(0);
lifecycle.begin_rebuild("generation-1", 100);
lifecycle.checkpoint_rebuild(100);
assert!(lifecycle.publish_rebuild());
lifecycle.observe_mutation_high_water_mark(101);
let health = lifecycle.health_snapshot();
assert_eq!(
select_list_index_provider_source_mode(&ListPathOptions::default(), ListSourceMode::IndexMetadataFast, &health),
ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::Lagging)
);
}
#[test]
fn list_metadata_resolution_params_limits_plain_listing_to_latest_version() {
let resolver = list_metadata_resolution_params("bucket".to_string(), 2, 3, false, 0);
assert_eq!(resolver.dir_quorum, 3);
assert_eq!(resolver.obj_quorum, 3);
assert_eq!(resolver.bucket, "bucket");
assert_eq!(resolver.requested_versions, 1);
}
#[test]
fn version_listing_rejects_stale_markers_at_full_set_read_quorum() {
let marker = test_delete_marker_meta_entry(
"marker.bin",
time::OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("valid fixture time"),
);
let sampled = MetaCacheEntries((0..8).map(|slot| (slot < 4).then(|| marker.clone())).collect());
assert!(
resolve_listing_entries(sampled, list_metadata_resolution_params("bucket".into(), 4, 12, true, 0), false).is_some(),
"the former sampled resolver accepts the four stale replicas"
);
for copies in [1, 4, 7, 8, 9, 16] {
let entries = MetaCacheEntries((0..16).map(|slot| (slot < copies).then(|| marker.clone())).collect());
let resolved = SetDisks::resolve_listed_versions("bucket", entries, &vec![None; 16], 16, 4)
.expect("known marker replicas and exact absence must be decidable");
assert_eq!(resolved.is_some(), copies >= 8, "marker copies: {copies}");
}
}
#[test]
fn version_listing_checks_history_after_a_quorum_marker() {
let time = time::OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("valid fixture time");
let mut marker = test_delete_marker_meta_entry("history.bin", time + time::Duration::seconds(1));
let history = test_object_meta_entry_with_erasure_versions("history.bin", &[(time, "old", 12, 4)]);
marker
.cached
.as_mut()
.expect("marker fixture")
.versions
.extend(history.cached.expect("history fixture").versions);
marker.metadata = marker
.cached
.as_ref()
.expect("combined fixture")
.marshal_msg()
.expect("encode history");
for copies in [8, 11, 12, 16] {
let entries = MetaCacheEntries((0..16).map(|slot| (slot < copies).then(|| marker.clone())).collect());
let resolved = SetDisks::resolve_listed_versions("bucket", entries, &vec![None; 16], 16, 4)
.expect("known history must resolve")
.expect("marker has read quorum");
let versions = resolved.file_info_versions("bucket").expect("read selected history").versions;
assert!(versions[0].deleted, "marker must remain latest");
assert_eq!(versions.len(), if copies >= 12 { 2 } else { 1 });
}
}
#[test]
fn version_listing_preserves_metadata_uncertainty() {
let marker = test_delete_marker_meta_entry(
"marker.bin",
time::OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("valid fixture time"),
);
let entries = MetaCacheEntries(vec![Some(marker); 4]);
assert!(matches!(
SetDisks::resolve_listed_versions("bucket", entries, &vec![None; 4], 16, 4),
Err(DiskError::ErasureReadQuorum)
));
}
#[test]
fn version_listing_tolerates_corrupt_replicas_only_with_version_quorum() {
let entry = test_object_meta_entry_with_erasure_versions(
"readable.bin",
&[(time::OffsetDateTime::from_unix_timestamp(1_700_000_000).unwrap(), "current", 12, 4)],
);
let corrupt = MetaCacheEntry {
name: entry.name.clone(),
metadata: vec![0xff],
..Default::default()
};
for copies in [11, 12, 15] {
let entries = MetaCacheEntries(
(0..16)
.map(|slot| Some(if slot < copies { entry.clone() } else { corrupt.clone() }))
.collect(),
);
let resolved = SetDisks::resolve_listed_versions("bucket", entries, &vec![None; 16], 16, 4);
if copies >= 12 {
assert!(resolved.unwrap().is_some(), "a readable version must tolerate corrupt replicas");
} else {
assert!(resolved.is_err(), "corruption cannot establish the missing version's absence");
}
}
}
#[tokio::test]
async fn version_listing_does_not_expose_four_stale_marker_replicas() {
let bucket = "version-list-stale-marker";
let (dirs, set) = crate::ecstore_validation_blackbox::make_local_set_disks(16, 4).await;
let marker = test_delete_marker_meta_entry(
"marker.bin",
time::OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("valid fixture time"),
);
let current = test_object_meta_entry_with_erasure_versions(
"new.bin",
&[(
time::OffsetDateTime::from_unix_timestamp(1_700_000_000).expect("valid fixture time")
+ time::Duration::seconds(1),
"new",
12,
4,
)],
);
for (slot, dir) in dirs.iter().enumerate() {
let current_dir = dir.path().join(bucket).join("new.bin");
tokio::fs::create_dir_all(¤t_dir)
.await
.expect("create current object directory");
tokio::fs::write(current_dir.join("xl.meta"), ¤t.metadata)
.await
.expect("persist current version");
if slot < 4 {
let stale_dir = dir.path().join(bucket).join("marker.bin");
tokio::fs::create_dir_all(&stale_dir)
.await
.expect("create stale marker directory");
tokio::fs::write(stale_dir.join("xl.meta"), &marker.metadata)
.await
.expect("persist stale marker");
}
}
for quorum_mode in ["disk", "reduced", "optimal", "strict"] {
let (sender, mut receiver) = mpsc::channel(1);
let walk = set.list_path(
CancellationToken::new(),
ListPathOptions {
bucket: bucket.to_string(),
versioned: true,
incl_deleted: true,
recursive: true,
ask_disks: quorum_mode.to_string(),
limit: 100,
..Default::default()
},
sender,
);
let drain = async {
let mut names = Vec::new();
while let Some(entry) = receiver.recv().await {
if !entry.is_dir() {
names.push(entry.name);
}
}
names
};
let (result, names) = timeout(Duration::from_secs(10), async { tokio::join!(walk, drain) })
.await
.expect("native listing must terminate");
result.expect("all drives are readable");
assert_eq!(names, ["new.bin"], "version authority cannot depend on {quorum_mode} sampling");
}
for dir in dirs.iter().take(4) {
assert_eq!(
tokio::fs::read(dir.path().join(bucket).join("marker.bin/xl.meta"))
.await
.expect("listing must preserve unresolved physical marker"),
marker.metadata
);
}
}
#[test]
fn list_metadata_resolution_params_keeps_all_versions_for_version_listing() {
let resolver = list_metadata_resolution_params("bucket".to_string(), 3, 5, true, 0);
assert_eq!(resolver.dir_quorum, 3);
assert_eq!(resolver.obj_quorum, 3);
assert_eq!(resolver.bucket, "bucket");
assert_eq!(resolver.requested_versions, 0);
}
#[test]
fn latest_listing_object_quorum_uses_write_quorum_for_strict_latest_listing() {
let required_quorum = latest_listing_required_object_quorum(2, 8, 4, true, 0);
let ask_disks = expand_ask_disks_for_object_quorum(4, 8, required_quorum);
assert_eq!(required_quorum, 5);
assert_eq!(ask_disks, 5);
assert_eq!(latest_listing_object_quorum(2, 8, 4, true, 0), 5);
}
#[test]
fn latest_listing_object_quorum_calculates_low_parity_write_quorum() {
let required_quorum = latest_listing_required_object_quorum(2, 8, 1, true, 0);
let ask_disks = expand_ask_disks_for_object_quorum(4, 8, required_quorum);
assert_eq!(required_quorum, 7);
assert_eq!(ask_disks, 7);
assert_eq!(latest_listing_object_quorum(2, 8, 1, true, 0), 7);
}
#[test]
fn latest_listing_object_quorum_keeps_reduced_and_versioned_listing_quorum() {
assert!(!enforce_latest_listing_write_quorum(true, "reduced"));
assert!(!enforce_latest_listing_write_quorum(true, "disk"));
assert!(enforce_latest_listing_write_quorum(true, "optimal"));
assert!(!enforce_latest_listing_write_quorum(false, "optimal"));
assert_eq!(latest_listing_required_object_quorum(1, 4, 2, false, 0), 1);
assert_eq!(latest_listing_object_quorum(1, 4, 2, false, 0), 1);
assert_eq!(latest_listing_required_object_quorum(2, 4, 2, false, 0), 2);
assert_eq!(latest_listing_object_quorum(2, 4, 2, false, 0), 2);
assert_eq!(expand_ask_disks_for_object_quorum(2, 4, 2), 2);
}
#[test]
fn latest_listing_object_quorum_relaxes_write_quorum_by_unreachable_drives() {
let slack = latest_listing_write_quorum_slack(true, 4, 3);
assert_eq!(slack, 1);
assert_eq!(latest_listing_required_object_quorum(2, 4, 2, true, slack), 2);
assert_eq!(latest_listing_required_object_quorum(2, 4, 2, true, 0), 3);
let slack = latest_listing_write_quorum_slack(true, 4, 2);
assert_eq!(slack, 2);
assert_eq!(latest_listing_required_object_quorum(1, 4, 2, true, slack), 2);
assert_eq!(latest_listing_write_quorum_slack(false, 4, 2), 0);
}
#[test]
fn latest_listing_resolves_degraded_object_when_a_set_drive_is_unreachable() {
let mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let entry = test_object_meta_entry_with_erasure_versions("object", &[(mod_time, "etag", 2, 2)]);
let entries = || MetaCacheEntries(vec![Some(entry.clone()), Some(entry.clone()), None]);
let slack = latest_listing_write_quorum_slack(true, 4, 3);
let obj_quorum = latest_listing_object_quorum(2, 4, 2, true, slack);
assert_eq!(obj_quorum, 2);
let resolver = list_metadata_resolution_params("bucket".to_string(), 2, obj_quorum, false, slack);
let resolved = resolve_listing_entries(entries(), resolver, true)
.expect("object committed at write quorum should stay listable with one holder drive offline");
assert_eq!(resolved.name, "object");
let strict_quorum = latest_listing_object_quorum(2, 4, 2, true, 0);
let strict_resolver = list_metadata_resolution_params("bucket".to_string(), 2, strict_quorum, false, 0);
assert!(resolve_listing_entries(entries(), strict_resolver, true).is_none());
}
#[test]
fn agreed_listing_entry_relaxes_write_quorum_by_unreachable_drives() {
let mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let entry = test_object_meta_entry_with_erasure_versions("object", &[(mod_time, "etag", 2, 2)]);
let mut resolver = list_metadata_resolution_params("bucket".to_string(), 2, 2, false, 1);
assert!(matches!(
resolve_agreed_listing_entry(entry.clone(), 2, resolver.clone(), true),
ListingEntryResolution::Resolved(_)
));
resolver.write_quorum_slack = 0;
assert!(matches!(
resolve_agreed_listing_entry(entry, 2, resolver, true),
ListingEntryResolution::NeedsSupplement(_, _)
));
}
#[test]
fn cached_entry_supplement_check_honors_write_quorum_slack() {
let mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let mut entry = test_object_meta_entry_with_erasure_versions("object", &[(mod_time, "etag", 2, 2)]);
let cached = entry.xl_meta().expect("test entry should decode");
let mut resolver = list_metadata_resolution_params("bucket".to_string(), 2, 2, false, 1);
assert!(!cached_entry_needs_supplement(&cached, 2, &resolver, true));
resolver.write_quorum_slack = 0;
assert!(cached_entry_needs_supplement(&cached, 2, &resolver, true));
}
#[test]
fn latest_listing_object_quorum_requires_write_quorum_when_degraded_cannot_satisfy_it() {
let required_quorum = latest_listing_required_object_quorum(2, 8, 4, true, 0);
let ask_disks = expand_ask_disks_for_object_quorum(4, 4, required_quorum);
assert_eq!(required_quorum, 5);
assert_eq!(ask_disks, 4);
assert_eq!(latest_listing_object_quorum(2, 8, 4, true, 0), 5);
}
#[tokio::test]
async fn latest_listing_supplements_a_split_delete_marker_sample() {
let object_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let delete_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_400).expect("valid timestamp");
let stale = test_object_meta_entry_with_erasure_versions("object", &[(object_mod_time, "object-etag", 4, 2)]);
let deleted = test_object_with_delete_marker_meta_entry("object", object_mod_time, delete_mod_time);
let entries = MetaCacheEntries(vec![
Some(stale.clone()),
Some(stale.clone()),
Some(deleted.clone()),
Some(deleted.clone()),
]);
let resolver = list_metadata_resolution_params("bucket".to_string(), 2, 4, false, 0);
assert_eq!(
listing_entries_supplement_target(&entries, &resolver, true),
Some(ListingSupplementTarget::Object("object".to_string()))
);
assert_eq!(listing_entries_supplement_target(&entries, &resolver, false), None);
let mut primary = resolve_listing_entries(MetaCacheEntries(entries.0.clone()), resolver.clone(), true)
.expect("the partial sample should fall back to the stale object version");
assert!(!primary.is_latest_delete_marker());
let mut fallback_disks = Vec::new();
let mut fallback_tempdirs = Vec::new();
for _ in 0..2 {
let tempdir = tempfile::tempdir().expect("fallback tempdir should be created");
let endpoint =
Endpoint::try_from(tempdir.path().to_str().expect("fallback path should be utf8")).expect("valid endpoint");
let disk = new_disk(
&endpoint,
&DiskOption {
cleanup: false,
health_check: false,
},
)
.await
.expect("fallback disk should be created");
disk.make_volume("bucket").await.expect("fallback bucket should be created");
disk.write_all(
"bucket",
&format!("object/{STORAGE_FORMAT_FILE}"),
bytes::Bytes::copy_from_slice(&deleted.metadata),
)
.await
.expect("fallback metadata should be written");
fallback_disks.push(disk);
fallback_tempdirs.push(tempdir);
}
let supplement = ListingSupplement::new(
ListingSupplementOptions {
bucket: "bucket".to_string(),
path: String::new(),
recursive: true,
incl_deleted: false,
skip_hidden_prefix_check: false,
filter_prefix: None,
forward_to: None,
per_disk_limit: 100,
skip_total_timeout: true,
walkdir_timeout: None,
walkdir_stall_timeout: None,
},
Arc::new(fallback_disks),
FallbackClaimTracker::default(),
);
let mut supplemented = resolve_listing_entries_with_supplement(entries, resolver, true, supplement)
.await
.expect("supplemented metadata should not remain ambiguous")
.expect("the supplemented sample should resolve the committed delete marker");
assert!(supplemented.is_latest_delete_marker());
}
#[tokio::test]
async fn latest_listing_fails_closed_for_unversioned_two_by_two_metadata_split() {
async fn collect_listing(set: &Arc<SetDisks>, bucket: &str) -> (crate::error::Result<()>, Vec<String>) {
let (sender, mut receiver) = mpsc::channel(4);
let walk = set.list_path(
CancellationToken::new(),
ListPathOptions {
bucket: bucket.to_string(),
recursive: true,
ask_disks: "optimal".to_string(),
limit: 100,
..Default::default()
},
sender,
);
let drain = async {
let mut names = Vec::new();
while let Some(entry) = receiver.recv().await {
if !entry.is_dir() {
names.push(entry.name);
}
}
names
};
tokio::join!(walk, drain)
}
let bucket = "list-two-by-two-overwrite";
let object = "object";
let old_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let new_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_400).expect("valid timestamp");
let old = test_unversioned_object_meta_entry(object, old_mod_time, "old-etag", Uuid::from_u128(1));
let new = test_unversioned_object_meta_entry(object, new_mod_time, "new-etag", Uuid::from_u128(2));
let (_temp_dirs, disks, set) = hermetic_set_disks_isolated(4).await;
for (index, disk) in disks.iter().enumerate() {
disk.make_volume(bucket).await.expect("bucket volume should be created");
let metadata = if index < 2 { &old.metadata } else { &new.metadata };
disk.write_all(bucket, &format!("{object}/{STORAGE_FORMAT_FILE}"), Bytes::copy_from_slice(metadata))
.await
.expect("split metadata should be written");
}
let (split_result, split_names) = collect_listing(&set, bucket).await;
assert!(
matches!(split_result, Err(StorageError::ErasureReadQuorum)),
"an unresolved 2+2 generation must fail the listing, got {split_result:?}"
);
assert!(split_names.is_empty(), "an unresolved key must not be emitted from either generation");
disks[0]
.write_all(bucket, &format!("{object}/{STORAGE_FORMAT_FILE}"), Bytes::copy_from_slice(&new.metadata))
.await
.expect("third new-generation copy should be written");
let (committed_result, committed_names) = collect_listing(&set, bucket).await;
committed_result.expect("a 3+1 committed generation should list successfully");
assert_eq!(committed_names, [object.to_string()]);
for disk in disks.iter().skip(1) {
disk.delete(
bucket,
object,
DeleteOptions {
recursive: true,
immediate: true,
..Default::default()
},
)
.await
.expect("quorum deletion should remove the object copy");
}
let (deleted_result, deleted_names) = collect_listing(&set, bucket).await;
deleted_result.expect("a quorum-deleted object should remain a successful empty listing");
assert!(deleted_names.is_empty(), "one stale copy must not resurrect a quorum-deleted object");
}
#[tokio::test]
async fn latest_listing_supplement_checks_fallback_disks_for_common_prefix_quorum() {
let mut fallback_disks = Vec::new();
let mut fallback_tempdirs = Vec::new();
for index in 0..4 {
let tempdir = tempfile::tempdir().expect("fallback tempdir should be created");
let endpoint = Endpoint::try_from(tempdir.path().to_str().expect("fallback path should be utf8"))
.expect("fallback endpoint should parse");
let disk = new_disk(
&endpoint,
&DiskOption {
cleanup: false,
health_check: false,
},
)
.await
.expect("fallback disk should be created");
disk.make_volume("bucket").await.expect("fallback bucket should be created");
for copies in [3, 4] {
if index < copies {
let object = format!("quux-{copies}/thud");
let entry = test_object_meta_entry(&object);
disk.write_all("bucket", &format!("{object}/{STORAGE_FORMAT_FILE}"), bytes::Bytes::from(entry.metadata))
.await
.expect("fallback child metadata should be written");
}
}
fallback_disks.push(disk);
fallback_tempdirs.push(tempdir);
}
let supplement = ListingSupplement::new(
ListingSupplementOptions {
bucket: "bucket".to_owned(),
path: String::new(),
recursive: false,
incl_deleted: false,
skip_hidden_prefix_check: false,
filter_prefix: None,
forward_to: None,
per_disk_limit: 100,
skip_total_timeout: true,
walkdir_timeout: None,
walkdir_stall_timeout: None,
},
Arc::new(fallback_disks),
FallbackClaimTracker::default(),
);
let resolver = list_metadata_resolution_params("bucket".to_owned(), 4, 12, false, 0);
for fallback_copies in [3, 4] {
let prefix = format!("quux-{fallback_copies}/");
let mut primary = vec![Some(test_dir_meta_entry(&prefix)); 8];
primary.extend([None, None, None, None]);
let entry =
resolve_listing_entries_with_supplement(MetaCacheEntries(primary), resolver.clone(), true, supplement.clone())
.await
.expect("directory supplementation should not fail");
assert_eq!(
entry.map(|entry| entry.name),
(fallback_copies == 4).then_some(prefix),
"the common prefix needs all twelve copies, including fallback disks"
);
}
}
#[test]
fn latest_listing_supplement_keeps_a_subquorum_delete_marker_hidden() {
let object_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let delete_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_400).expect("valid timestamp");
let stale = test_object_meta_entry_with_erasure_versions("object", &[(object_mod_time, "object-etag", 4, 2)]);
let deleted = test_object_with_delete_marker_meta_entry("object", object_mod_time, delete_mod_time);
let resolver = list_metadata_resolution_params("bucket".to_string(), 2, 4, false, 0);
let entries = MetaCacheEntries(vec![
Some(stale.clone()),
Some(stale.clone()),
Some(stale.clone()),
Some(deleted.clone()),
]);
assert_eq!(
listing_entries_supplement_target(&entries, &resolver, true),
Some(ListingSupplementTarget::Object("object".to_string()))
);
let mut resolved = resolve_listing_entries(
MetaCacheEntries(vec![
Some(stale.clone()),
Some(stale.clone()),
Some(stale),
Some(deleted.clone()),
Some(deleted.clone()),
Some(deleted),
]),
resolver,
true,
)
.expect("the previous object version should remain visible below delete-marker write quorum");
assert!(!resolved.is_latest_delete_marker());
}
#[tokio::test]
async fn latest_listing_agreed_path_requires_enough_readers_for_write_quorum() {
let entry = test_object_meta_entry("object");
let seen = Arc::new(Mutex::new(Vec::new()));
let seen_clone = seen.clone();
let allow_agreed_objects = latest_listing_allow_agreed_objects(true, 4, 5);
let raw_min_disks = latest_listing_raw_min_disks(2, 5, true);
assert!(!allow_agreed_objects);
assert_eq!(raw_min_disks, 5);
let err = list_path_raw(
CancellationToken::new(),
ListPathRawOptions {
disks: vec![None, None, None, None],
min_disks: raw_min_disks,
test_reader_behaviors: vec![TestReaderBehavior::Entries(vec![entry.clone()]); 4],
agreed: Some(Box::new(move |entry: MetaCacheEntry| {
let seen = seen_clone.clone();
Box::pin(async move {
if !allow_agreed_objects && !entry.is_dir() {
return;
}
seen.lock().expect("seen mutex poisoned").push(entry.name);
})
})),
..Default::default()
},
)
.await
.expect_err("latest listing should fail when selected readers cannot satisfy write quorum");
assert_eq!(err, DiskError::ErasureReadQuorum);
assert!(seen.lock().expect("seen mutex poisoned").is_empty());
let seen = Arc::new(Mutex::new(Vec::new()));
let seen_clone = seen.clone();
let allow_agreed_objects = latest_listing_allow_agreed_objects(true, 5, 5);
let raw_min_disks = latest_listing_raw_min_disks(3, 5, true);
assert!(allow_agreed_objects);
assert_eq!(raw_min_disks, 5);
list_path_raw(
CancellationToken::new(),
ListPathRawOptions {
disks: vec![None, None, None, None, None],
min_disks: raw_min_disks,
test_reader_behaviors: vec![TestReaderBehavior::Entries(vec![entry]); 5],
agreed: Some(Box::new(move |entry: MetaCacheEntry| {
let seen = seen_clone.clone();
Box::pin(async move {
if !allow_agreed_objects && !entry.is_dir() {
return;
}
seen.lock().expect("seen mutex poisoned").push(entry.name);
})
})),
..Default::default()
},
)
.await
.expect("write-quorum all-agree listing should complete");
assert_eq!(seen.lock().expect("seen mutex poisoned").as_slice(), &["object".to_string()]);
}
#[tokio::test]
async fn latest_listing_agreed_path_reconciles_low_parity_partial_latest() {
let old_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let new_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_400).expect("valid timestamp");
let entry = test_object_meta_entry_with_erasure_versions(
"object",
&[(old_mod_time, "old-etag", 4, 4), (new_mod_time, "new-etag", 7, 1)],
);
let fallback_old_entry = test_object_meta_entry_with_erasure_versions("object", &[(old_mod_time, "old-etag", 4, 4)]);
let resolver = list_metadata_resolution_params("bucket".to_string(), 3, 5, false, 0);
let seen = Arc::new(Mutex::new(Vec::new()));
let seen_clone = seen.clone();
list_path_raw(
CancellationToken::new(),
ListPathRawOptions {
disks: vec![None, None, None, None, None],
min_disks: 5,
test_reader_behaviors: vec![TestReaderBehavior::Entries(vec![entry]); 5],
agreed: Some(Box::new(move |entry: MetaCacheEntry| {
let seen = seen_clone.clone();
let resolver = resolver.clone();
let fallback_old_entry = fallback_old_entry.clone();
Box::pin(async move {
let entry = match resolve_agreed_listing_entry(entry, 5, resolver.clone(), true) {
ListingEntryResolution::Resolved(entry) => entry,
ListingEntryResolution::NeedsSupplement(entry, _) => {
let mut candidates = vec![Some(entry); 5];
candidates.extend(vec![Some(fallback_old_entry); 2]);
let Some(entry) = resolve_listing_entries(MetaCacheEntries(candidates), resolver, true) else {
return;
};
entry
}
ListingEntryResolution::Rejected => return,
};
let info = entry.to_fileinfo("bucket").expect("resolved entry should decode");
seen.lock().expect("seen mutex poisoned").push((
entry.name,
info.mod_time,
info.metadata.get("etag").cloned(),
));
})
})),
..Default::default()
},
)
.await
.expect("all-agree listing should complete");
assert_eq!(
seen.lock().expect("seen mutex poisoned").as_slice(),
&[("object".to_string(), Some(old_mod_time), Some("old-etag".to_string()))]
);
}
#[tokio::test]
async fn latest_listing_agreed_path_falls_back_to_previous_version_without_supplement() {
let old_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let new_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_400).expect("valid timestamp");
let entry = test_object_meta_entry_with_erasure_versions(
"object",
&[(old_mod_time, "old-etag", 4, 4), (new_mod_time, "new-etag", 7, 1)],
);
let resolver = list_metadata_resolution_params("bucket".to_string(), 3, 5, false, 0);
let seen = Arc::new(Mutex::new(Vec::new()));
let seen_clone = seen.clone();
list_path_raw(
CancellationToken::new(),
ListPathRawOptions {
disks: vec![None, None, None, None, None],
min_disks: 5,
test_reader_behaviors: vec![TestReaderBehavior::Entries(vec![entry]); 5],
agreed: Some(Box::new(move |entry: MetaCacheEntry| {
let seen = seen_clone.clone();
let resolver = resolver.clone();
Box::pin(async move {
let entry = match resolve_agreed_listing_entry(entry, 5, resolver, true) {
ListingEntryResolution::Resolved(entry) => entry,
ListingEntryResolution::NeedsSupplement(_, Some(entry)) => entry,
ListingEntryResolution::NeedsSupplement(_, None) | ListingEntryResolution::Rejected => {
return;
}
};
let info = entry.to_fileinfo("bucket").expect("resolved entry should decode");
seen.lock().expect("seen mutex poisoned").push((
entry.name,
info.mod_time,
info.metadata.get("etag").cloned(),
));
})
})),
..Default::default()
},
)
.await
.expect("all-agree listing should complete");
assert_eq!(
seen.lock().expect("seen mutex poisoned").as_slice(),
&[("object".to_string(), Some(old_mod_time), Some("old-etag".to_string()))]
);
}
#[tokio::test]
async fn latest_listing_agreed_path_supplements_committed_low_parity_latest() {
let new_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_400).expect("valid timestamp");
let entry = test_object_meta_entry_with_erasure_versions("object", &[(new_mod_time, "new-etag", 7, 1)]);
let fallback_entry = entry.clone();
let resolver = list_metadata_resolution_params("bucket".to_string(), 3, 5, false, 0);
let seen = Arc::new(Mutex::new(Vec::new()));
let seen_clone = seen.clone();
list_path_raw(
CancellationToken::new(),
ListPathRawOptions {
disks: vec![None, None, None, None, None],
min_disks: 5,
test_reader_behaviors: vec![TestReaderBehavior::Entries(vec![entry]); 5],
agreed: Some(Box::new(move |entry: MetaCacheEntry| {
let seen = seen_clone.clone();
let resolver = resolver.clone();
let fallback_entry = fallback_entry.clone();
Box::pin(async move {
let ListingEntryResolution::NeedsSupplement(entry, _) =
resolve_agreed_listing_entry(entry, 5, resolver.clone(), true)
else {
return;
};
let mut candidates = vec![Some(entry); 5];
candidates.extend(vec![Some(fallback_entry); 2]);
let resolved = resolve_listing_entries(MetaCacheEntries(candidates), resolver, true)
.expect("supplemented low-parity latest should satisfy object write quorum");
let info = resolved.to_fileinfo("bucket").expect("resolved entry should decode");
seen.lock().expect("seen mutex poisoned").push((
resolved.name,
info.mod_time,
info.metadata.get("etag").cloned(),
));
})
})),
..Default::default()
},
)
.await
.expect("all-agree listing should complete");
assert_eq!(
seen.lock().expect("seen mutex poisoned").as_slice(),
&[("object".to_string(), Some(new_mod_time), Some("new-etag".to_string()))]
);
}
#[tokio::test]
async fn latest_listing_agreed_directory_requires_write_quorum() {
let entry = test_dir_meta_entry("prefix/");
let raw_min_disks = latest_listing_raw_min_disks(2, 5, true);
let err = list_path_raw(
CancellationToken::new(),
ListPathRawOptions {
disks: vec![None, None, None, None],
min_disks: raw_min_disks,
test_reader_behaviors: vec![TestReaderBehavior::Entries(vec![entry]); 4],
agreed: Some(Box::new(move |_| Box::pin(async {}))),
..Default::default()
},
)
.await
.expect_err("latest listing should not expose prefixes below write quorum");
assert_eq!(err, DiskError::ErasureReadQuorum);
}
#[test]
fn test_null_version_marker_handling() {
let parsed = parse_version_marker("null".to_string()).expect("null marker should parse");
assert_eq!(parsed, VersionMarker::Null);
let valid_uuid = "550e8400-e29b-41d4-a716-446655440000";
let parsed = parse_version_marker(valid_uuid.to_string()).expect("uuid marker should parse");
assert_eq!(parsed, VersionMarker::Version(Uuid::parse_str(valid_uuid).unwrap()));
}
#[test]
fn test_next_version_idmarker_null_string() {
let version_id: Option<Uuid> = None;
let next_version_idmarker = version_id.map(|v| v.to_string()).unwrap_or_else(|| "null".to_string());
assert_eq!(next_version_idmarker, "null");
let version_id: Option<Uuid> = Some(Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000").unwrap());
let next_version_idmarker = version_id.map(|v| v.to_string()).unwrap_or_else(|| "null".to_string());
assert_eq!(next_version_idmarker, "550e8400-e29b-41d4-a716-446655440000");
}
#[test]
fn test_version_marker_round_trip() {
let server_response = "null";
let client_request = server_response;
let parsed = parse_version_marker(client_request.to_string()).expect("null marker should parse");
assert_eq!(parsed, VersionMarker::Null);
let uuid_str = "550e8400-e29b-41d4-a716-446655440000";
let server_response = uuid_str;
let client_request = server_response;
let parsed = parse_version_marker(client_request.to_string()).expect("uuid marker should parse");
assert_eq!(parsed, VersionMarker::Version(Uuid::parse_str(uuid_str).unwrap()));
}
#[test]
fn list_path_marker_round_trip_preserves_set_index() {
let mut opts = ListPathOptions {
id: Some("list-cache-id".to_string()),
pool_idx: Some(3),
set_idx: Some(7),
..Default::default()
};
let marker = opts.encode_marker("photos/2026/image.jpg");
let expected_marker = format!(
"photos/2026/image.jpg[rustfs_cache:{},id:list-cache-id,p:3,s:7,src:walker,gen:live]",
super::MARKER_TAG_VERSION
);
assert_eq!(marker, expected_marker);
let mut parsed = ListPathOptions {
marker: Some(marker),
..Default::default()
};
parsed.parse_marker();
assert_eq!(parsed.marker.as_deref(), Some("photos/2026/image.jpg"));
assert_eq!(parsed.id.as_deref(), Some("list-cache-id"));
assert_eq!(parsed.pool_idx, Some(3));
assert_eq!(parsed.set_idx, Some(7));
assert_eq!(parsed.cursor_source, Some(ListSourceMode::Walker));
assert_eq!(parsed.cursor_generation.as_deref(), Some("live"));
assert!(!parsed.create);
}
#[test]
fn list_path_marker_parser_preserves_source_aware_cursor_fields() {
let mut parsed = ListPathOptions {
marker: Some(
"photos/2026/image.jpg[rustfs_cache:v2,id:list-cache-id,p:3,s:7,src:index_key_only,gen:generation-42]"
.to_string(),
),
..Default::default()
};
parsed.parse_marker();
assert_eq!(parsed.marker.as_deref(), Some("photos/2026/image.jpg"));
assert_eq!(parsed.id.as_deref(), Some("list-cache-id"));
assert_eq!(parsed.pool_idx, Some(3));
assert_eq!(parsed.set_idx, Some(7));
assert_eq!(parsed.cursor_source, Some(ListSourceMode::IndexKeyOnly));
assert_eq!(parsed.cursor_generation.as_deref(), Some("generation-42"));
assert!(!parsed.create);
}
#[test]
fn list_source_modes_expose_metadata_authority_boundaries() {
assert_eq!(ListSourceMode::Walker.metadata_authority(), ListMetadataAuthority::LiveXlMeta);
assert_eq!(
ListSourceMode::IndexKeyOnly.metadata_authority(),
ListMetadataAuthority::LiveVerifiedIndexCandidate
);
assert_eq!(
ListSourceMode::IndexVerifiedPage.metadata_authority(),
ListMetadataAuthority::LiveVerifiedIndexCandidate
);
assert_eq!(
ListSourceMode::IndexMetadataFast.metadata_authority(),
ListMetadataAuthority::IndexSnapshotEventuallyConsistent
);
assert!(ListSourceMode::IndexKeyOnly.requires_live_metadata_verification());
assert!(ListSourceMode::IndexVerifiedPage.requires_live_metadata_verification());
assert!(!ListSourceMode::IndexMetadataFast.requires_live_metadata_verification());
assert!(!ListSourceMode::IndexMetadataFast.can_satisfy_strong_listing());
}
#[test]
fn list_index_source_selection_falls_back_until_request_is_healthy_and_versioned() {
let healthy = TestIndexHealth { reason: None };
let unhealthy = TestIndexHealth {
reason: Some(ListIndexFallbackReason::Unhealthy),
};
assert_eq!(
select_list_index_source_mode(None, Some("generation-1"), &healthy),
ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::Disabled)
);
assert_eq!(
select_list_index_source_mode(Some(ListSourceMode::Walker), Some("generation-1"), &healthy),
ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::Disabled)
);
assert_eq!(
select_list_index_source_mode(Some(ListSourceMode::IndexKeyOnly), None, &healthy),
ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::MissingGeneration)
);
assert_eq!(
select_list_index_source_mode(Some(ListSourceMode::IndexKeyOnly), Some(""), &healthy),
ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::MissingGeneration)
);
assert_eq!(
select_list_index_source_mode(Some(ListSourceMode::IndexKeyOnly), Some("generation-1"), &unhealthy),
ListIndexSourceDecision::FallbackToWalker(ListIndexFallbackReason::Unhealthy)
);
assert_eq!(
select_list_index_source_mode(Some(ListSourceMode::IndexVerifiedPage), Some("generation-1"), &healthy),
ListIndexSourceDecision::UseIndex(ListSourceMode::IndexVerifiedPage)
);
}
#[test]
fn list_index_lifecycle_rebuild_requires_publish_before_health() {
let mut lifecycle = ListIndexLifecycle::disabled(10);
lifecycle.begin_rebuild("generation-1", 100);
lifecycle.checkpoint_rebuild(80);
let snapshot = lifecycle.health_snapshot();
assert_eq!(snapshot.state, ListIndexLifecycleState::Rebuilding);
assert_eq!(snapshot.active_generation, None);
assert_eq!(snapshot.staging_generation.as_deref(), Some("generation-1"));
assert_eq!(snapshot.checkpoint_high_water_mark, 80);
assert_eq!(snapshot.fallback_reason, Some(ListIndexFallbackReason::Rebuilding));
assert!(lifecycle.publish_rebuild());
let snapshot = lifecycle.health_snapshot();
assert_eq!(snapshot.state, ListIndexLifecycleState::Healthy);
assert_eq!(snapshot.active_generation.as_deref(), Some("generation-1"));
assert_eq!(snapshot.staging_generation, None);
assert_eq!(snapshot.fallback_reason, None);
}
#[test]
fn list_index_lifecycle_reports_lagging_and_fallback_reason() {
let mut lifecycle = ListIndexLifecycle::disabled(10);
lifecycle.begin_rebuild("generation-1", 100);
lifecycle.checkpoint_rebuild(100);
assert!(lifecycle.publish_rebuild());
lifecycle.observe_mutation_high_water_mark(115);
let snapshot = lifecycle.health_snapshot();
assert_eq!(snapshot.state, ListIndexLifecycleState::Lagging);
assert_eq!(snapshot.mutation_lag, 15);
assert_eq!(snapshot.fallback_reason, Some(ListIndexFallbackReason::Lagging));
}
#[test]
fn list_index_lifecycle_reports_degraded_as_fallback() {
let mut lifecycle = ListIndexLifecycle::disabled(10);
lifecycle.begin_rebuild("generation-1", 100);
lifecycle.checkpoint_rebuild(100);
assert!(lifecycle.publish_rebuild());
lifecycle.mark_degraded();
let degraded = lifecycle.health_snapshot();
assert_eq!(degraded.state, ListIndexLifecycleState::Degraded);
assert_eq!(degraded.fallback_reason, Some(ListIndexFallbackReason::Degraded));
}
#[test]
fn list_path_marker_parser_rejects_unknown_cursor_source() {
let original = "photos/2026/image.jpg[rustfs_cache:v2,id:list-cache-id,src:unknown,gen:generation-42]";
let mut parsed = ListPathOptions {
marker: Some(original.to_string()),
..Default::default()
};
parsed.parse_marker();
assert_eq!(parsed.marker.as_deref(), Some(original));
assert!(parsed.id.is_none());
assert!(parsed.cursor_source.is_none());
assert!(parsed.cursor_generation.is_none());
assert!(!parsed.create);
}
#[test]
fn list_path_marker_parser_uses_trailing_cache_tag() {
let mut parsed = ListPathOptions {
marker: Some(format!(
"photos/[archive]/image.jpg[rustfs_cache:{},id:list-cache-id,p:3,s:7]",
super::MARKER_TAG_VERSION
)),
..Default::default()
};
parsed.parse_marker();
assert_eq!(parsed.marker.as_deref(), Some("photos/[archive]/image.jpg"));
assert_eq!(parsed.id.as_deref(), Some("list-cache-id"));
assert_eq!(parsed.pool_idx, Some(3));
assert_eq!(parsed.set_idx, Some(7));
}
#[test]
fn list_marker_key_strips_only_trailing_cache_tag() {
assert_eq!(
list_marker_key("photos/2026/image.jpg[rustfs_cache:v2,id:list-cache-id,src:walker,gen:live]"),
"photos/2026/image.jpg"
);
assert_eq!(
list_marker_key("photos/[rustfs_cache:v2]/image.jpg"),
"photos/[rustfs_cache:v2]/image.jpg"
);
assert_eq!(
list_marker_key("photos/image.jpg[rustfs_cache:v2,id:list-cache-id"),
"photos/image.jpg[rustfs_cache:v2,id:list-cache-id"
);
}
#[test]
fn list_path_marker_parser_return_tag_forces_cache_refresh() {
let mut parsed = ListPathOptions {
marker: Some("photos/2026/image.jpg[rustfs_cache:v2,return:,p:3,s:7]".to_string()),
..Default::default()
};
parsed.parse_marker();
assert_eq!(parsed.marker.as_deref(), Some("photos/2026/image.jpg"));
assert!(parsed.id.is_some());
assert_eq!(parsed.pool_idx, Some(3));
assert_eq!(parsed.set_idx, Some(7));
assert!(parsed.create);
}
#[test]
fn list_path_marker_parser_recovers_from_corrupt_set_index() {
let mut parsed = ListPathOptions {
marker: Some("photos/2026/image.jpg[rustfs_cache:v2,id:list-cache-id,p:3,s:not-a-number]".to_string()),
..Default::default()
};
parsed.parse_marker();
assert_eq!(parsed.marker.as_deref(), Some("photos/2026/image.jpg"));
assert!(parsed.id.is_some());
assert_ne!(parsed.id.as_deref(), Some("list-cache-id"));
assert!(parsed.create);
assert_eq!(parsed.pool_idx, Some(3));
assert!(parsed.set_idx.is_none());
}
#[test]
fn list_path_marker_parser_accepts_legacy_v1_tag() {
let mut parsed = ListPathOptions {
marker: Some("photos/2026/image.jpg[rustfs_cache:v1,id:legacy-cache-id,p:4,s:1]".to_string()),
..Default::default()
};
parsed.parse_marker();
assert_eq!(parsed.marker.as_deref(), Some("photos/2026/image.jpg"));
assert_eq!(parsed.id.as_deref(), Some("legacy-cache-id"));
assert_eq!(parsed.pool_idx, Some(4));
assert_eq!(parsed.set_idx, Some(1));
assert!(parsed.cursor_source.is_none());
assert!(parsed.cursor_generation.is_none());
assert!(!parsed.create);
}
#[test]
fn list_path_marker_parser_ignores_unsupported_cache_tag_version() {
let marker = "photos/image.jpg[rustfs_cache:v0,id:list-cache-id,p:3,s:7]".to_string();
let mut parsed = ListPathOptions {
marker: Some(marker.clone()),
..Default::default()
};
parsed.parse_marker();
assert_eq!(parsed.marker.as_deref(), Some(marker.as_str()));
assert!(parsed.id.is_none());
assert!(parsed.pool_idx.is_none());
assert!(parsed.set_idx.is_none());
assert!(!parsed.create);
}
#[test]
fn walk_result_from_set_errors_returns_non_eof_error() {
let err = walk_result_from_set_errors(&[Some(StorageError::Unexpected), Some(StorageError::FileAccessDenied)])
.expect_err("walk should fail when any set reports a real listing error");
assert_eq!(err, StorageError::FileAccessDenied);
}
#[test]
fn walk_result_from_set_errors_prefers_real_error_over_not_found() {
let err = walk_result_from_set_errors(&[
Some(StorageError::VolumeNotFound),
Some(StorageError::DiskNotFound),
Some(StorageError::FileAccessDenied),
])
.expect_err("walk should report the real listing error");
assert_eq!(err, StorageError::FileAccessDenied);
}
#[test]
fn walk_result_from_set_errors_preserves_volume_not_found() {
let err = walk_result_from_set_errors(&[Some(StorageError::VolumeNotFound), Some(StorageError::VolumeNotFound)])
.expect_err("all volume-not-found set errors should remain visible");
assert_eq!(err, StorageError::VolumeNotFound);
}
#[test]
fn walk_result_from_set_errors_allows_missing_entries() {
walk_result_from_set_errors(&[Some(StorageError::FileNotFound), Some(StorageError::VolumeNotFound)])
.expect("missing objects under an existing listing path should not fail the walk");
}
#[test]
fn walk_result_from_set_errors_ignores_only_unexpected_and_successes() {
walk_result_from_set_errors(&[None, Some(StorageError::Unexpected)])
.expect("successful sets and unexpected EOF-style markers should not fail the walk");
}
#[test]
fn walk_result_from_set_errors_surfaces_full_offline() {
let err = walk_result_from_set_errors(&[Some(StorageError::DiskNotFound), Some(StorageError::DiskNotFound)])
.expect_err("all sets unreachable must surface an availability error, not an empty listing");
assert_eq!(err, StorageError::DiskNotFound);
}
#[test]
fn walk_result_from_set_errors_tolerates_partial_offline() {
walk_result_from_set_errors(&[None, Some(StorageError::DiskNotFound)])
.expect("a partial outage with a healthy set must not fail the walk");
}
#[tokio::test]
async fn merge_entry_channels_produces_sorted_unique_output_from_two_channels() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx_a.send(test_meta_entry("obj-a")).await.unwrap();
tx_a.send(test_meta_entry("obj-c")).await.unwrap();
tx_a.send(test_meta_entry("obj-e")).await.unwrap();
drop(tx_a);
tx_b.send(test_meta_entry("obj-b")).await.unwrap();
tx_b.send(test_meta_entry("obj-d")).await.unwrap();
drop(tx_b);
let rx = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(rx, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
assert_eq!(results, vec!["obj-a", "obj-b", "obj-c", "obj-d", "obj-e"]);
}
#[tokio::test]
async fn merge_entry_channels_deduplicates_entries_across_channels() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx_a.send(test_meta_entry("obj-a")).await.unwrap();
tx_a.send(test_meta_entry("obj-c")).await.unwrap();
drop(tx_a);
tx_b.send(test_meta_entry("obj-a")).await.unwrap();
tx_b.send(test_meta_entry("obj-b")).await.unwrap();
drop(tx_b);
let rx = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(rx, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
assert_eq!(results, vec!["obj-a", "obj-b", "obj-c"]);
}
#[tokio::test]
async fn merge_entry_channels_preserves_cross_pool_delete_marker_versions() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (tx_c, rx_c) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(4);
let mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_500).expect("valid timestamp");
let stale_mod_time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let stale_object = test_object_meta_entry_with_erasure_versions("obj-a", &[(stale_mod_time, "stale-etag", 4, 2)]);
tx_a.send(test_delete_marker_meta_entry("obj-a", mod_time))
.await
.expect("first delete marker should queue");
tx_b.send(test_delete_marker_meta_entry("obj-a", mod_time))
.await
.expect("second delete marker should queue");
tx_c.send(stale_object).await.expect("stale object should queue");
drop(tx_a);
drop(tx_b);
drop(tx_c);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx_a, rx_b, rx_c], out_tx, 2));
let mut merged = timeout(Duration::from_secs(1), out_rx.recv())
.await
.expect("merged entry should be emitted promptly")
.expect("merged entry should be present");
assert_eq!(merged.name, "obj-a");
assert!(
merged.is_latest_delete_marker(),
"a newer marker must remain current across independently resolved pools"
);
let versions = merged.file_info_versions("bucket").expect("merged versions should decode");
assert_eq!(versions.versions.len(), 2, "retain the historical object and deduplicate the marker");
assert!(versions.versions[0].deleted && versions.versions[0].is_latest);
assert!(!versions.versions[1].deleted && !versions.versions[1].is_latest);
assert!(
matches!(timeout(Duration::from_secs(1), out_rx.recv()).await, Ok(None)),
"merge should not emit a duplicate entry for the same key"
);
handle
.await
.expect("merge task should not panic")
.expect("merge task should succeed");
}
fn rewrite_test_version(mut entry: MetaCacheEntry, change: impl FnOnce(&mut FileMetaVersion)) -> MetaCacheEntry {
let meta = entry.cached.as_mut().expect("test metadata should be decoded");
assert_eq!(meta.versions.len(), 1);
let mut version = meta.versions[0].parse_version_meta().expect("test version should decode");
change(&mut version);
meta.versions[0] = version.try_into().expect("test version should encode");
entry.metadata = meta.marshal_msg().expect("test metadata should encode");
entry
}
async fn merge_test_object_entries(entries: Vec<MetaCacheEntry>) -> Result<MetaCacheEntry> {
let mut inputs = Vec::with_capacity(entries.len());
for entry in entries {
let (sender, receiver) = mpsc::channel(1);
sender.send(entry).await.expect("fixture entry should queue");
inputs.push(receiver);
}
let (sender, mut receiver) = mpsc::channel(1);
let task = tokio::spawn(merge_entry_channels(CancellationToken::new(), inputs, sender, 1));
let entry = receiver.recv().await;
task.await.expect("merge must not panic")?;
Ok(entry.expect("a valid same-key group must produce an entry"))
}
#[tokio::test]
async fn merge_entry_channels_orders_complete_histories_independently_of_pool_order() {
let time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let first = test_object_meta_entry_with_erasure_versions("key", &[(time, "first", 4, 2)]);
let second = rewrite_test_version(
test_object_meta_entry_with_erasure_versions("key", &[(time, "second", 4, 2)]),
|version| version.object.as_mut().expect("object version").version_id = Some(Uuid::from_u128(2)),
);
let marker = test_delete_marker_meta_entry("key", time + time::Duration::seconds(1));
let inputs = [first, second, marker];
let mut expected = None;
for order in [[0, 1, 2], [0, 2, 1], [1, 0, 2], [1, 2, 0], [2, 0, 1], [2, 1, 0]] {
let entry = merge_test_object_entries(order.map(|index| inputs[index].clone()).to_vec())
.await
.expect("disjoint version chains should merge");
let versions = entry.file_info_versions("bucket").expect("merged versions should decode");
assert_eq!(versions.versions.len(), 3);
assert!(versions.versions[0].deleted && versions.versions[0].is_latest);
assert!(
versions.versions[1..]
.iter()
.all(|version| !version.deleted && !version.is_latest)
);
assert!(versions.versions.iter().all(|version| version.num_versions == 3));
let identities = versions.versions.iter().map(|version| version.version_id).collect::<Vec<_>>();
assert!(identities.contains(&Some(Uuid::from_u128(1))));
assert!(identities.contains(&Some(Uuid::from_u128(2))));
if let Some(expected) = &expected {
assert_eq!(&identities, expected, "equal-time versions must have stable pagination order");
} else {
expected = Some(identities);
}
}
}
#[tokio::test]
async fn merge_entry_channels_key_only_candidates_do_not_override_version_metadata() {
let time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let marker = test_delete_marker_meta_entry("key", time);
for entries in [
vec![test_meta_entry("key"), marker.clone()],
vec![marker.clone(), test_meta_entry("key")],
] {
let mut merged = merge_test_object_entries(entries)
.await
.expect("merge a name with resolved metadata");
assert!(merged.is_latest_delete_marker());
assert_eq!(merged.file_info_versions("bucket").expect("decode marker").versions.len(), 1);
}
}
#[tokio::test]
async fn merge_entry_channels_accepts_equivalent_migrated_coding_and_data_dirs() {
let time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let first = test_object_meta_entry_with_erasure_versions("key", &[(time, "same-etag", 4, 2)]);
let second = rewrite_test_version(
test_object_meta_entry_with_erasure_versions("key", &[(time, "same-etag", 6, 2)]),
|version| version.object.as_mut().expect("object version").data_dir = Some(Uuid::from_u128(42)),
);
let forward = merge_test_object_entries(vec![first.clone(), second.clone()])
.await
.expect("valid migration copies");
let reverse = merge_test_object_entries(vec![second, first])
.await
.expect("reversed migration copies");
assert_eq!(forward.metadata, reverse.metadata, "representation must not depend on channel order");
let versions = forward.file_info_versions("bucket").expect("merged metadata should decode");
assert_eq!(versions.versions.len(), 1);
assert_eq!(versions.versions[0].metadata.get("etag").map(String::as_str), Some("same-etag"));
}
#[tokio::test]
async fn merge_entry_channels_defers_free_version_while_same_remote_source_is_live() {
let live = test_transitioned_meta_entry("key", "remote/shared", false);
let free = test_transitioned_meta_entry("key", "remote/shared", true);
for inputs in [vec![live.clone(), free.clone()], vec![free.clone(), live.clone()]] {
let merged = merge_test_object_entries(inputs)
.await
.expect("same remote source and cleanup owner should merge");
let versions = merged
.file_info_versions_with_free_versions("bucket")
.expect("merged transition history should decode");
assert_eq!(versions.versions.len(), 1);
assert!(versions.free_versions.is_empty(), "a live remote reference must defer cleanup discovery");
}
let unrelated = test_transitioned_meta_entry("key", "remote/other", false);
let merged = merge_test_object_entries(vec![free, unrelated])
.await
.expect("unrelated remote references should merge");
let versions = merged
.file_info_versions_with_free_versions("bucket")
.expect("merged transition history should decode");
assert_eq!(versions.versions.len(), 1);
assert_eq!(versions.free_versions.len(), 1, "an unrelated source must not suppress cleanup");
}
#[tokio::test]
async fn merge_entry_channels_rejects_conflicting_version_identity_and_metadata() {
let time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let original = test_object_meta_entry_with_erasure_versions("key", &[(time, "original", 4, 2)]);
for key in [
"etag",
"x-amz-tagging",
"x-amz-object-lock-mode",
"x-amz-object-lock-retain-until-date",
] {
let changed = rewrite_test_version(original.clone(), |version| {
version
.object
.as_mut()
.expect("object version")
.meta_user
.insert(key.to_string(), "changed".to_string());
});
for pair in [[original.clone(), changed.clone()], [changed, original.clone()]] {
let err = merge_test_object_entries(pair.to_vec())
.await
.expect_err("conflicting copies must fail");
assert_eq!(err, StorageError::FileCorrupt, "conflict in {key} must not become arbitrary metadata");
}
}
let marker = rewrite_test_version(test_delete_marker_meta_entry("key", time), |version| {
version.delete_marker.as_mut().expect("delete marker").version_id = Some(Uuid::from_u128(1));
});
assert_eq!(
merge_test_object_entries(vec![original, marker])
.await
.expect_err("UUID type conflict"),
StorageError::FileCorrupt
);
}
#[tokio::test]
async fn merge_entry_channels_reconciles_null_overwrite_without_losing_uuid_history() {
let time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let history = test_object_meta_entry_with_erasure_versions("key", &[(time, "history", 4, 2)]);
let old_null = rewrite_test_version(history.clone(), |version| {
version.object.as_mut().expect("null object").version_id = None;
});
let marker = rewrite_test_version(test_delete_marker_meta_entry("key", time + time::Duration::seconds(1)), |version| {
version.delete_marker.as_mut().expect("null marker").version_id = Some(Uuid::nil());
});
for inputs in [
vec![old_null.clone(), marker.clone(), history.clone()],
vec![history, marker, old_null],
] {
let entry = merge_test_object_entries(inputs)
.await
.expect("new null slot should replace old null slot");
let versions = entry.file_info_versions("bucket").expect("null versions should decode");
assert_eq!(versions.versions.len(), 2);
assert!(versions.versions[0].deleted && versions.versions[0].is_latest);
assert!(versions.versions[0].version_id.is_none_or(|id| id.is_nil()));
assert_eq!(versions.versions[1].version_id, Some(Uuid::from_u128(1)));
}
}
#[tokio::test]
async fn merge_entry_channels_rejects_corrupt_version_headers_and_empty_stacks() {
let time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let original = test_object_meta_entry_with_erasure_versions("key", &[(time, "etag", 4, 2)]);
for empty in [false, true] {
let mut corrupt = original.clone();
let meta = corrupt.cached.as_mut().expect("fixture metadata");
if empty {
meta.versions.clear();
} else {
meta.versions[0].header.version_id = Some(Uuid::from_u128(99));
}
corrupt.metadata = meta.marshal_msg().expect("encode corrupt fixture");
assert_eq!(
merge_test_object_entries(vec![original.clone(), corrupt])
.await
.expect_err("corrupt candidate must fail"),
StorageError::FileCorrupt
);
}
let mut malformed = original.clone();
malformed.cached = None;
malformed.metadata = vec![0xff];
assert_eq!(
merge_test_object_entries(vec![original, malformed])
.await
.expect_err("malformed metadata must fail"),
StorageError::FileCorrupt
);
}
#[tokio::test]
async fn merge_entry_channels_does_not_combine_subquorum_markers_across_erasure_sets() {
let time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let old = test_object_meta_entry_with_erasure_versions("key", &[(time, "history", 4, 2)]);
let marked = test_object_with_delete_marker_meta_entry("key", time, time + time::Duration::seconds(1));
let mut inputs = Vec::new();
for marker_copies in [1, 2] {
let resolver = list_metadata_resolution_params("bucket".to_string(), 3, 3, true, 0);
let copies = (0..3)
.map(|index| Some(if index < marker_copies { marked.clone() } else { old.clone() }))
.collect();
let entry = resolve_listing_entries(MetaCacheEntries(copies), resolver, false)
.expect("each set independently retains its quorum-backed history");
inputs.push(entry);
}
let merged = merge_test_object_entries(inputs).await.expect("merge resolved histories");
let versions = merged.file_info_versions("bucket").expect("decode merged history");
assert_eq!(
versions.versions.len(),
1,
"three marker copies across two EC domains do not form a quorum"
);
assert!(!versions.versions[0].deleted);
}
#[tokio::test]
async fn listing_merge_preserves_error_after_partial_output_without_cancelling_request() {
let time = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let (first_tx, first_rx) = mpsc::channel(2);
let (second_tx, second_rx) = mpsc::channel(1);
first_tx.send(test_meta_entry("a/")).await.expect("queue preceding prefix");
first_tx
.send(test_object_meta_entry_with_erasure_versions("b", &[(time, "one", 4, 2)]))
.await
.expect("queue first copy");
second_tx
.send(test_object_meta_entry_with_erasure_versions("b", &[(time, "two", 4, 2)]))
.await
.expect("queue conflicting copy");
drop(first_tx);
drop(second_tx);
let request = CancellationToken::new();
let workers = request.child_token();
let (sender, mut receiver) = mpsc::channel(1);
let task = super::spawn_listing_merge(workers.clone(), vec![first_rx, second_rx], sender);
assert_eq!(receiver.recv().await.expect("preceding result should arrive").name, "a/");
assert!(receiver.recv().await.is_none());
assert_eq!(
task.await
.expect("merge task must not panic")
.expect_err("conflict must propagate"),
StorageError::FileCorrupt
);
assert!(workers.is_cancelled(), "failed merge must stop the disk producers");
assert!(!request.is_cancelled(), "the API must still observe the merge error");
}
#[tokio::test]
async fn merge_entry_channels_handles_single_channel() {
let (tx, rx) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx.send(test_meta_entry("obj-a")).await.unwrap();
tx.send(test_meta_entry("obj-b")).await.unwrap();
drop(tx);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
assert_eq!(results, vec!["obj-a", "obj-b"]);
}
#[tokio::test]
async fn merge_entry_channels_treats_dropped_output_receiver_as_completion() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, out_rx) = mpsc::channel(1);
tx_a.send(test_meta_entry("obj-a")).await.unwrap();
tx_b.send(test_meta_entry("obj-b")).await.unwrap();
drop(tx_a);
drop(tx_b);
drop(out_rx);
let result = timeout(
Duration::from_secs(1),
merge_entry_channels(CancellationToken::new(), vec![rx_a, rx_b], out_tx, 1),
)
.await
.expect("merge should stop promptly when its consumer disconnects");
assert!(result.is_ok(), "consumer disconnect must not surface as a merge worker error");
}
#[test]
fn walk_ascending_versions_contract_reverses_newest_first_metadata() {
let older = time::OffsetDateTime::from_unix_timestamp(1_705_312_300).expect("valid timestamp");
let newer = time::OffsetDateTime::from_unix_timestamp(1_705_312_500).expect("valid timestamp");
let entry =
test_object_meta_entry_with_erasure_versions("obj-a", &[(older, "etag-old", 4, 2), (newer, "etag-new", 4, 2)]);
let fvs = entry.file_info_versions("bucket").expect("versions should parse");
assert_eq!(fvs.versions.len(), 2, "both versions should be visible");
assert!(
fvs.versions[0].mod_time >= fvs.versions[1].mod_time,
"file_info_versions must yield newest-first"
);
assert!(fvs.versions[0].is_latest, "the first (newest) version carries is_latest");
let mut ascending = fvs.versions;
ascending.reverse();
assert!(
ascending[0].mod_time <= ascending[1].mod_time,
"reversing newest-first output must produce ascending mod_time order"
);
assert!(
ascending.last().expect("versions present").is_latest,
"ascending emission ends with the latest version"
);
}
#[tokio::test]
async fn merge_entry_channels_merges_interleaved_channels_in_global_order() {
let mut txs = Vec::new();
let mut rxs = Vec::new();
for _ in 0..4 {
let (tx, rx) = mpsc::channel(16);
txs.push(tx);
rxs.push(rx);
}
let names: Vec<String> = (0..24).map(|i| format!("obj-{i:02}")).collect();
for (i, name) in names.iter().enumerate() {
txs[i % 4].send(test_meta_entry(name)).await.unwrap();
}
for tx in txs.iter().take(3) {
tx.send(test_meta_entry("obj-99")).await.unwrap();
}
drop(txs);
let (out_tx, mut out_rx) = mpsc::channel(64);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, rxs, out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
let mut expected = names;
expected.push("obj-99".to_owned());
assert_eq!(results, expected);
}
#[tokio::test]
async fn merge_entry_channels_emits_when_cleaned_order_differs_from_raw_order() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx_a.send(test_meta_entry("a/b")).await.unwrap();
drop(tx_a);
tx_b.send(test_meta_entry("a//c")).await.unwrap();
drop(tx_b);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
assert_eq!(
results,
vec!["a/b", "a/c"],
"distinct keys must both be emitted, canonicalized, in canonical order"
);
}
#[tokio::test]
async fn merge_entry_channels_prefix_dir_sorts_after_sibling_keys() {
let (tx_a, rx_a) = mpsc::channel(8);
let (tx_b, rx_b) = mpsc::channel(8);
let (out_tx, mut out_rx) = mpsc::channel(16);
tx_a.send(test_object_meta_entry("a")).await.unwrap();
tx_a.send(test_object_meta_entry("a.txt")).await.unwrap();
tx_a.send(test_dir_meta_entry("a/")).await.unwrap();
drop(tx_a);
tx_b.send(test_dir_meta_entry("a/")).await.unwrap();
drop(tx_b);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push((entry.name.clone(), entry.is_dir()));
}
handle.await.unwrap().unwrap();
assert_eq!(
results,
vec![("a".to_owned(), false), ("a.txt".to_owned(), false), ("a/".to_owned(), true),],
"the prefix dir must sort after raw-smaller siblings and be emitted exactly once"
);
}
#[tokio::test]
async fn merge_entry_channels_collapses_canonical_duplicates_from_one_channel_across_rounds() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx_a.send(test_meta_entry("a//b")).await.unwrap();
tx_a.send(test_meta_entry("a/b")).await.unwrap();
drop(tx_a);
tx_b.send(test_meta_entry("z")).await.unwrap();
drop(tx_b);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
assert_eq!(
results,
vec!["a/b", "z"],
"canonical duplicates arriving in consecutive rounds must collapse to one emission"
);
}
#[tokio::test]
async fn merge_entry_channels_lagging_dir_marker_collapses_into_emitted_prefix() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx_a.send(test_dir_meta_entry("folder/")).await.unwrap();
tx_a.send(test_object_meta_entry("folder/")).await.unwrap();
drop(tx_a);
tx_b.send(test_dir_meta_entry("folder/")).await.unwrap();
drop(tx_b);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
assert_eq!(results, vec!["folder/"], "the same S3 key must be emitted exactly once");
}
#[tokio::test]
async fn merge_entry_channels_object_and_same_named_prefix_dir_coexist() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx_a.send(test_dir_meta_entry("a/")).await.unwrap();
drop(tx_a);
tx_b.send(test_object_meta_entry("a")).await.unwrap();
drop(tx_b);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push((entry.name.clone(), entry.is_object(), entry.is_dir()));
}
handle.await.unwrap().unwrap();
assert_eq!(
results,
vec![("a".to_owned(), true, false), ("a/".to_owned(), false, true)],
"the object `a` and the prefix dir `a/` are distinct keys and must both survive"
);
}
#[tokio::test]
async fn merge_entry_channels_object_and_prefix_dir_coexist_from_one_channel() {
let (tx, rx) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx.send(test_object_meta_entry("a")).await.unwrap();
tx.send(test_dir_meta_entry("a/")).await.unwrap();
drop(tx);
let (tx_empty, rx_empty) = mpsc::channel(4);
drop(tx_empty);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx, rx_empty], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push((entry.name.clone(), entry.is_object(), entry.is_dir()));
}
handle.await.unwrap().unwrap();
assert_eq!(results, vec![("a".to_owned(), true, false), ("a/".to_owned(), false, true)],);
}
#[tokio::test]
async fn merge_entry_channels_directory_marker_object_shadows_prefix_dir() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx_a.send(test_dir_meta_entry("folder/")).await.unwrap();
drop(tx_a);
tx_b.send(test_object_meta_entry("folder/")).await.unwrap();
drop(tx_b);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
assert!(entry.is_object(), "the directory-marker object must shadow the same-named prefix dir");
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
assert_eq!(results, vec!["folder/"]);
}
#[tokio::test]
async fn merge_entry_channels_collapses_equivalent_prefix_dirs() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx_a.send(test_dir_meta_entry("x/")).await.unwrap();
drop(tx_a);
tx_b.send(test_dir_meta_entry("x/")).await.unwrap();
drop(tx_b);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
assert_eq!(results, vec!["x/"]);
}
#[tokio::test]
async fn merge_entry_channels_normalizes_uncleaned_names_before_grouping() {
let (tx_a, rx_a) = mpsc::channel(4);
let (tx_b, rx_b) = mpsc::channel(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
tx_a.send(test_meta_entry("a//b")).await.unwrap();
drop(tx_a);
tx_b.send(test_meta_entry("a/b")).await.unwrap();
drop(tx_b);
let cancel = CancellationToken::new();
let handle = tokio::spawn(merge_entry_channels(cancel, vec![rx_a, rx_b], out_tx, 1));
let mut results = Vec::new();
while let Some(entry) = out_rx.recv().await {
results.push(entry.name.clone());
}
handle.await.unwrap().unwrap();
assert_eq!(results, vec!["a/b"]);
}
#[tokio::test]
async fn merge_entry_channels_respects_cancellation() {
let (tx, rx) = mpsc::channel::<MetaCacheEntry>(4);
let (out_tx, mut out_rx) = mpsc::channel(8);
let cancel = CancellationToken::new();
let cancel_clone = cancel.clone();
let handle = tokio::spawn(merge_entry_channels(cancel_clone, vec![rx], out_tx, 1));
tx.send(test_meta_entry("a")).await.unwrap();
let received = timeout(Duration::from_millis(500), out_rx.recv())
.await
.expect("should receive entry before cancellation")
.map(|e| e.name);
assert_eq!(received, Some("a".to_string()));
cancel.cancel();
let result = timeout(Duration::from_secs(2), handle)
.await
.expect("merge should not hang after cancellation")
.expect("task should not panic");
assert!(result.is_ok(), "merge should return Ok on cancellation");
drop(tx);
}
#[tokio::test]
async fn merge_entry_channels_respects_cancellation_with_multiple_live_channels() {
let (tx_a, rx_a) = mpsc::channel::<MetaCacheEntry>(4);
let (tx_b, rx_b) = mpsc::channel::<MetaCacheEntry>(4);
let (out_tx, _out_rx) = mpsc::channel(8);
let cancel = CancellationToken::new();
let cancel_clone = cancel.clone();
let handle = tokio::spawn(merge_entry_channels(cancel_clone, vec![rx_a, rx_b], out_tx, 1));
cancel.cancel();
let result = timeout(Duration::from_secs(2), handle)
.await
.expect("multi-channel merge should not hang after cancellation")
.expect("task should not panic");
assert!(result.is_ok(), "multi-channel merge should return Ok on cancellation");
drop(tx_a);
drop(tx_b);
}
#[tokio::test]
async fn merge_entry_channels_respects_cancellation_when_output_is_full() {
let (tx_a, rx_a) = mpsc::channel::<MetaCacheEntry>(4);
let (tx_b, rx_b) = mpsc::channel::<MetaCacheEntry>(4);
let (out_tx, _out_rx) = mpsc::channel(1);
out_tx
.send(test_meta_entry("already-buffered"))
.await
.expect("output channel should accept initial entry");
tx_a.send(test_meta_entry("a"))
.await
.expect("input channel a should accept entry");
tx_b.send(test_meta_entry("b"))
.await
.expect("input channel b should accept entry");
let cancel = CancellationToken::new();
let cancel_clone = cancel.clone();
let handle = tokio::spawn(merge_entry_channels(cancel_clone, vec![rx_a, rx_b], out_tx, 1));
cancel.cancel();
let result = timeout(Duration::from_secs(2), handle)
.await
.expect("merge should not hang when output is full and cancellation fires")
.expect("task should not panic");
assert!(result.is_ok(), "merge should return Ok when cancelled during output send");
drop(tx_a);
drop(tx_b);
}
#[tokio::test]
async fn send_or_cancel_returns_false_when_cancelled_while_output_is_full() {
let (out_tx, _out_rx) = mpsc::channel::<MetaCacheEntry>(1);
out_tx
.send(test_meta_entry("already-buffered"))
.await
.expect("output channel should accept initial entry");
let cancel = CancellationToken::new();
let cancel_clone = cancel.clone();
let handle = tokio::spawn(async move { send_or_cancel(&cancel_clone, &out_tx, test_meta_entry("next")).await });
cancel.cancel();
let result = timeout(Duration::from_secs(2), handle)
.await
.expect("send_or_cancel should not hang when cancellation wins over backpressure")
.expect("task should not panic")
.expect("send_or_cancel should succeed");
assert!(!result, "send_or_cancel should report cancellation instead of a successful send");
}
}