refactor: flatten test harness storage compat aliases (#3596)

* refactor: flatten test harness storage compat aliases * refactor: flatten rustfs storage compat aliases (#3597) * refactor: prune runtime storage compat surface (#3598) * refactor: flatten runtime secondary storage compat (#3599) * docs: add scheduler placement profiling baselines (#3600) * feat: add observability topology capability contracts (#3601)
2026-08-14 00:53:14 +00:00 · 2026-06-19 08:30:47 +08:00
parent b1c6578df1
commit ada6f7587e
87 changed files with 1551 additions and 990 deletions
@@ -0,0 +1,113 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::fmt;
+
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum CapabilityState {
+    Supported,
+    Unsupported,
+    Disabled,
+    #[default]
+    Unknown,
+}
+
+impl CapabilityState {
+    pub const fn is_supported(self) -> bool {
+        matches!(self, Self::Supported)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct CapabilityStatus {
+    pub state: CapabilityState,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub reason: Option<String>,
+}
+
+impl CapabilityStatus {
+    pub const fn new(state: CapabilityState) -> Self {
+        Self { state, reason: None }
+    }
+
+    pub const fn supported() -> Self {
+        Self::new(CapabilityState::Supported)
+    }
+
+    pub const fn unsupported() -> Self {
+        Self::new(CapabilityState::Unsupported)
+    }
+
+    pub const fn disabled() -> Self {
+        Self::new(CapabilityState::Disabled)
+    }
+
+    pub const fn unknown() -> Self {
+        Self::new(CapabilityState::Unknown)
+    }
+
+    pub fn with_reason(mut self, reason: impl Into<String>) -> Self {
+        self.reason = Some(reason.into());
+        self
+    }
+}
+
+impl Default for CapabilityStatus {
+    fn default() -> Self {
+        Self::unknown()
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum CapabilitySnapshotError {
+    Unavailable,
+    Unsupported,
+    InvalidSnapshot(String),
+}
+
+impl fmt::Display for CapabilitySnapshotError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Unavailable => f.write_str("capability snapshot unavailable"),
+            Self::Unsupported => f.write_str("capability snapshot unsupported"),
+            Self::InvalidSnapshot(reason) => write!(f, "invalid capability snapshot: {reason}"),
+        }
+    }
+}
+
+impl std::error::Error for CapabilitySnapshotError {}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn capability_status_serializes_unknown_and_unsupported_states() {
+        let unknown = CapabilityStatus::unknown();
+        let unsupported = CapabilityStatus::unsupported().with_reason("target does not expose profiler");
+
+        let encoded = serde_json::to_string(&(unknown, unsupported)).expect("serialize capability statuses");
+        let decoded: (CapabilityStatus, CapabilityStatus) =
+            serde_json::from_str(&encoded).expect("deserialize capability statuses");
+
+        assert_eq!(decoded.0.state, CapabilityState::Unknown);
+        assert_eq!(decoded.1.state, CapabilityState::Unsupported);
+        assert_eq!(decoded.1.reason.as_deref(), Some("target does not expose profiler"));
+        assert!(!decoded.1.state.is_supported());
+    }
+}
@@ -16,12 +16,16 @@

 pub mod admin;
 pub mod bucket;
+pub mod capability;
 pub mod error;
 pub mod multipart;
 pub mod object;
+pub mod observability;
+pub mod topology;

 pub use admin::{DiskSetSelector, StorageAdminApi};
 pub use bucket::{BucketInfo, BucketOperations, BucketOptions, DeleteBucketOptions, MakeBucketOptions, SRBucketDeleteOp};
+pub use capability::{CapabilitySnapshotError, CapabilityState, CapabilityStatus};
 pub use error::{StorageErrorCode, StorageResult};
 pub use multipart::{CompletePart, ListMultipartsInfo, ListPartsInfo, MultipartInfo, MultipartUploadResult, PartInfo};
 pub use object::{DeletedObject, ObjectToDelete};
@@ -31,3 +35,10 @@ pub use object::{HealOperations, MultipartOperations, NamespaceLocking, ObjectIO
 pub use object::{ListObjectVersionsInfo, ListObjectsInfo, ListObjectsV2Info, ListOperations, ObjectInfoOrErr};
 pub use object::{ObjectPreconditionError, ObjectPreconditionPart, ObjectPreconditionState};
 pub use object::{VersionMarker, WalkOptions, WalkVersionsSortOrder};
+pub use observability::{
+    MemorySamplingState, ObservabilitySnapshot, ObservabilitySnapshotProvider, PlatformSupport, UserspaceProfilingCapability,
+};
+pub use topology::{
+    DiskCapabilities, TopologyCapabilities, TopologyDisk, TopologyLabels, TopologyPool, TopologySet, TopologySnapshot,
+    TopologySnapshotProvider,
+};
@@ -0,0 +1,102 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::fmt::Debug;
+
+use serde::{Deserialize, Serialize};
+
+use crate::{CapabilitySnapshotError, CapabilityStatus};
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct ObservabilitySnapshot {
+    pub runtime_telemetry: CapabilityStatus,
+    pub userspace_profiling: UserspaceProfilingCapability,
+    pub memory_sampling: MemorySamplingState,
+    pub platform: PlatformSupport,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct UserspaceProfilingCapability {
+    pub cpu: CapabilityStatus,
+    pub memory: CapabilityStatus,
+    pub continuous_cpu: CapabilityStatus,
+    pub periodic_cpu: CapabilityStatus,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct MemorySamplingState {
+    pub process: CapabilityStatus,
+    pub system: CapabilityStatus,
+    pub cgroup: CapabilityStatus,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct PlatformSupport {
+    pub target_triple: Option<String>,
+    pub os: Option<String>,
+    pub arch: Option<String>,
+    pub allocator: CapabilityStatus,
+    pub ebpf: CapabilityStatus,
+    pub numa: CapabilityStatus,
+}
+
+#[async_trait::async_trait]
+pub trait ObservabilitySnapshotProvider: Send + Sync + Debug {
+    async fn observability_snapshot(&self) -> Result<ObservabilitySnapshot, CapabilitySnapshotError>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::CapabilityState;
+
+    #[test]
+    fn observability_snapshot_preserves_unknown_and_unsupported_states() {
+        let snapshot = ObservabilitySnapshot {
+            runtime_telemetry: CapabilityStatus::unknown(),
+            userspace_profiling: UserspaceProfilingCapability {
+                cpu: CapabilityStatus::unsupported().with_reason("unsupported target"),
+                memory: CapabilityStatus::disabled(),
+                continuous_cpu: CapabilityStatus::unknown(),
+                periodic_cpu: CapabilityStatus::supported(),
+            },
+            memory_sampling: MemorySamplingState {
+                process: CapabilityStatus::supported(),
+                system: CapabilityStatus::supported(),
+                cgroup: CapabilityStatus::unknown(),
+            },
+            platform: PlatformSupport {
+                target_triple: Some("x86_64-unknown-linux-gnu".to_owned()),
+                os: Some("linux".to_owned()),
+                arch: Some("x86_64".to_owned()),
+                allocator: CapabilityStatus::supported(),
+                ebpf: CapabilityStatus::unknown(),
+                numa: CapabilityStatus::unsupported(),
+            },
+        };
+
+        let encoded = serde_json::to_string(&snapshot).expect("serialize observability snapshot");
+        let decoded: ObservabilitySnapshot = serde_json::from_str(&encoded).expect("deserialize observability snapshot");
+
+        assert_eq!(decoded.runtime_telemetry.state, CapabilityState::Unknown);
+        assert_eq!(decoded.userspace_profiling.cpu.state, CapabilityState::Unsupported);
+        assert_eq!(decoded.userspace_profiling.memory.state, CapabilityState::Disabled);
+        assert_eq!(decoded.platform.numa.state, CapabilityState::Unsupported);
+        assert_eq!(decoded.platform.ebpf.state, CapabilityState::Unknown);
+    }
+}
@@ -0,0 +1,153 @@
+// Copyright 2024 RustFS Team
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use std::collections::BTreeMap;
+use std::fmt::Debug;
+
+use serde::{Deserialize, Serialize};
+
+use crate::{CapabilitySnapshotError, CapabilityStatus};
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct TopologySnapshot {
+    pub pools: Vec<TopologyPool>,
+    pub capabilities: TopologyCapabilities,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct TopologyCapabilities {
+    pub profiling: CapabilityStatus,
+    pub numa: CapabilityStatus,
+    pub failure_domain_labels: CapabilityStatus,
+    pub media_labels: CapabilityStatus,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct TopologyPool {
+    pub pool_index: usize,
+    pub pool_id: Option<String>,
+    pub labels: TopologyLabels,
+    pub sets: Vec<TopologySet>,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct TopologySet {
+    pub pool_index: usize,
+    pub set_index: usize,
+    pub set_id: Option<String>,
+    pub labels: TopologyLabels,
+    pub disks: Vec<TopologyDisk>,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct TopologyDisk {
+    pub pool_index: usize,
+    pub set_index: usize,
+    pub disk_index: usize,
+    pub disk_id: Option<String>,
+    pub labels: TopologyLabels,
+    pub capabilities: DiskCapabilities,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct TopologyLabels {
+    pub zone: Option<String>,
+    pub rack: Option<String>,
+    pub node: Option<String>,
+    pub media: Option<String>,
+    pub numa_node: Option<String>,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub additional: BTreeMap<String, String>,
+}
+
+#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct DiskCapabilities {
+    pub media_type: CapabilityStatus,
+    pub failure_domain: CapabilityStatus,
+    pub numa: CapabilityStatus,
+    pub profiling: CapabilityStatus,
+}
+
+#[async_trait::async_trait]
+pub trait TopologySnapshotProvider: Send + Sync + Debug {
+    async fn topology_snapshot(&self) -> Result<TopologySnapshot, CapabilitySnapshotError>;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::CapabilityState;
+
+    #[test]
+    fn topology_snapshot_allows_missing_and_extra_labels() {
+        let raw = r#"{
+            "pools": [{
+                "pool_index": 0,
+                "pool_id": null,
+                "labels": {
+                    "additional": {
+                        "room": "a"
+                    }
+                },
+                "sets": [{
+                    "pool_index": 0,
+                    "set_index": 1,
+                    "set_id": null,
+                    "labels": {},
+                    "disks": [{
+                        "pool_index": 0,
+                        "set_index": 1,
+                        "disk_index": 2,
+                        "disk_id": "disk-2",
+                        "labels": {
+                            "media": "ssd",
+                            "additional": {
+                                "slot": "nvme0"
+                            }
+                        },
+                        "capabilities": {
+                            "media_type": { "state": "supported" },
+                            "failure_domain": { "state": "unknown" },
+                            "numa": { "state": "unsupported", "reason": "not reported" },
+                            "profiling": { "state": "disabled" }
+                        }
+                    }]
+                }]
+            }],
+            "capabilities": {
+                "profiling": { "state": "supported" },
+                "numa": { "state": "unknown" },
+                "failure_domain_labels": { "state": "supported" },
+                "media_labels": { "state": "supported" }
+            }
+        }"#;
+
+        let snapshot: TopologySnapshot = serde_json::from_str(raw).expect("deserialize topology snapshot");
+        let disk = &snapshot.pools[0].sets[0].disks[0];
+
+        assert_eq!(snapshot.pools[0].labels.zone, None);
+        assert_eq!(snapshot.pools[0].labels.additional.get("room").map(String::as_str), Some("a"));
+        assert_eq!(disk.labels.media.as_deref(), Some("ssd"));
+        assert_eq!(disk.labels.additional.get("slot").map(String::as_str), Some("nvme0"));
+        assert_eq!(disk.capabilities.numa.state, CapabilityState::Unsupported);
+        assert_eq!(disk.capabilities.profiling.state, CapabilityState::Disabled);
+    }
+}