From 27b8592879d88478cff81cbedbb9f03726f42c39 Mon Sep 17 00:00:00 2001 From: Zhengchao An Date: Sun, 28 Jun 2026 19:12:02 +0800 Subject: [PATCH] docs: add documentation to storage-api public types (#741) (#4007) docs: add documentation to storage-api public types Add doc comments to public structs, enums, and traits in storage-api crate to improve documentation coverage. Refs #741 --- crates/storage-api/src/bucket.rs | 25 +++++++++++++++++++++++++ crates/storage-api/src/error.rs | 5 +++++ crates/storage-api/src/observability.rs | 23 +++++++++++++++++++++++ 3 files changed, 53 insertions(+) diff --git a/crates/storage-api/src/bucket.rs b/crates/storage-api/src/bucket.rs index 639f57e0c..1774fa8ad 100644 --- a/crates/storage-api/src/bucket.rs +++ b/crates/storage-api/src/bucket.rs @@ -17,44 +17,69 @@ use std::fmt::Debug; use serde::{Deserialize, Serialize}; use time::OffsetDateTime; +/// Options for creating a new bucket. #[derive(Debug, Default, Serialize, Deserialize)] pub struct MakeBucketOptions { + /// Enable object lock for the bucket. pub lock_enabled: bool, + /// Enable versioning for the bucket. pub versioning_enabled: bool, + /// Force creation even if bucket already exists. pub force_create: bool, + /// Optional creation timestamp. pub created_at: Option, + /// Skip acquiring namespace lock. pub no_lock: bool, } +/// Operation to perform on a bucket during site replication delete. #[derive(Debug, Default, Clone, PartialEq)] pub enum SRBucketDeleteOp { + /// No operation. #[default] NoOp, + /// Mark the bucket for deletion. MarkDelete, + /// Purge the bucket and all its contents. Purge, } +/// Options for deleting a bucket. #[derive(Debug, Default, Clone)] pub struct DeleteBucketOptions { + /// Skip acquiring namespace lock. pub no_lock: bool, + /// Do not recreate bucket on failure. pub no_recreate: bool, + /// Force deletion even if bucket is not empty. pub force: bool, + /// Site replication delete operation. pub srdelete_op: SRBucketDeleteOp, } +/// Options for querying bucket information. #[derive(Debug, Default, Serialize, Deserialize)] pub struct BucketOptions { + /// Include deleted buckets in results. pub deleted: bool, + /// Use cached bucket information. pub cached: bool, + /// Skip loading bucket metadata. pub no_metadata: bool, } +/// Information about a bucket. #[derive(Debug, Clone, Serialize, Deserialize, Default)] pub struct BucketInfo { + /// Bucket name. pub name: String, + /// Creation timestamp. pub created: Option, + /// Deletion timestamp (if deleted). pub deleted: Option, + /// Whether versioning is enabled. pub versioning: bool, + /// Whether object locking is enabled. pub object_locking: bool, } diff --git a/crates/storage-api/src/error.rs b/crates/storage-api/src/error.rs index a647894c8..c5bf13b65 100644 --- a/crates/storage-api/src/error.rs +++ b/crates/storage-api/src/error.rs @@ -14,8 +14,13 @@ //! Stable storage error contracts shared across storage consumers. +/// Result type alias for storage operations. pub type StorageResult = core::result::Result; +/// Error codes for storage operations. +/// +/// These codes provide a stable, cross-crate error classification +/// that can be serialized and transmitted between nodes. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum StorageErrorCode { Io, diff --git a/crates/storage-api/src/observability.rs b/crates/storage-api/src/observability.rs index e6356bbae..26faa9092 100644 --- a/crates/storage-api/src/observability.rs +++ b/crates/storage-api/src/observability.rs @@ -18,45 +18,68 @@ use serde::{Deserialize, Serialize}; use crate::{CapabilitySnapshotError, CapabilityStatus}; +/// Snapshot of observability capabilities and state. #[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct ObservabilitySnapshot { + /// Runtime telemetry capabilities. pub runtime_telemetry: CapabilityStatus, + /// Userspace profiling capabilities. pub userspace_profiling: UserspaceProfilingCapability, + /// Memory sampling state. pub memory_sampling: MemorySamplingState, + /// Platform support information. pub platform: PlatformSupport, } +/// Capabilities for userspace profiling. #[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct UserspaceProfilingCapability { + /// CPU profiling capability. pub cpu: CapabilityStatus, + /// Memory profiling capability. pub memory: CapabilityStatus, + /// Continuous CPU profiling capability. pub continuous_cpu: CapabilityStatus, + /// Periodic CPU profiling capability. pub periodic_cpu: CapabilityStatus, } +/// State of memory sampling capabilities. #[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct MemorySamplingState { + /// Process-level memory sampling. pub process: CapabilityStatus, + /// System-level memory sampling. pub system: CapabilityStatus, + /// Cgroup-level memory sampling. pub cgroup: CapabilityStatus, } +/// Platform support information. #[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)] #[serde(deny_unknown_fields)] pub struct PlatformSupport { + /// Target triple (e.g., x86_64-unknown-linux-gnu). pub target_triple: Option, + /// Operating system. pub os: Option, + /// Architecture. pub arch: Option, + /// Memory allocator capability. pub allocator: CapabilityStatus, + /// eBPF support. pub ebpf: CapabilityStatus, + /// NUMA support. pub numa: CapabilityStatus, } +/// Provider for observability snapshots. #[async_trait::async_trait] pub trait ObservabilitySnapshotProvider: Send + Sync + Debug { + /// Get a snapshot of observability capabilities and state. async fn observability_snapshot(&self) -> Result; }