rustfs/crates/common/README.md

RustFS Common - Shared Components

Common types, utilities, and shared components for RustFS distributed object storage

📖 Documentation · 🐛 Bug Reports · 💬 Discussions

---

📖 Overview

RustFS Common provides shared components, types, and utilities used across all RustFS modules. This foundational library ensures consistency, reduces code duplication, and provides essential building blocks for the RustFS distributed object storage system.

Note: This is a foundational submodule of RustFS that provides essential shared components for the distributed object storage system. For the complete RustFS experience, please visit the main RustFS repository.

✨ Features

🔧 Core Types

• Common Data Structures: Shared types and enums
• Error Handling: Unified error types and utilities
• Result Types: Consistent result handling patterns
• Constants: System-wide constants and defaults

🛠️ Utilities

• Async Helpers: Common async patterns and utilities
• Serialization: Shared serialization utilities
• Logging: Common logging and tracing setup
• Metrics: Shared metrics and observability

🌐 Network Components

• gRPC Common: Shared gRPC types and utilities
• Protocol Helpers: Common protocol implementations
• Connection Management: Shared connection utilities
• Request/Response Types: Common API types

📦 Installation

Add this to your Cargo.toml:

[dependencies]
rustfs-common = "0.1.0"

🔧 Usage

Basic Common Types

use rustfs_common::{Result, Error, ObjectInfo, BucketInfo};

fn main() -> Result<()> {
    // Use common result type
    let result = some_operation()?;

    // Use common object info
    let object = ObjectInfo {
        name: "example.txt".to_string(),
        size: 1024,
        etag: "d41d8cd98f00b204e9800998ecf8427e".to_string(),
        last_modified: chrono::Utc::now(),
        content_type: "text/plain".to_string(),
    };

    println!("Object: {} ({} bytes)", object.name, object.size);
    Ok(())
}

Error Handling

use rustfs_common::{Error, ErrorKind, Result};

fn example_operation() -> Result<String> {
    // Different error types
    match some_condition {
        true => Ok("Success".to_string()),
        false => Err(Error::new(
            ErrorKind::InvalidInput,
            "Invalid operation parameters"
        )),
    }
}

fn handle_errors() {
    match example_operation() {
        Ok(value) => println!("Success: {}", value),
        Err(e) => {
            match e.kind() {
                ErrorKind::InvalidInput => println!("Input error: {}", e),
                ErrorKind::NotFound => println!("Not found: {}", e),
                ErrorKind::PermissionDenied => println!("Access denied: {}", e),
                _ => println!("Other error: {}", e),
            }
        }
    }
}

Async Utilities

use rustfs_common::async_utils::{timeout_with_default, retry_with_backoff, spawn_task};
use std::time::Duration;

async fn async_operations() -> Result<()> {
    // Timeout with default value
    let result = timeout_with_default(
        Duration::from_secs(5),
        expensive_operation(),
        "default_value".to_string()
    ).await;

    // Retry with exponential backoff
    let result = retry_with_backoff(
        3, // max attempts
        Duration::from_millis(100), // initial delay
        || async { fallible_operation().await }
    ).await?;

    // Spawn background task
    spawn_task("background-worker", async {
        background_work().await;
    });

    Ok(())
}

Metrics and Observability

use rustfs_common::metrics::{Counter, Histogram, Gauge, MetricsRegistry};

fn setup_metrics() -> Result<()> {
    let registry = MetricsRegistry::new();

    // Create metrics
    let requests_total = Counter::new("requests_total", "Total number of requests")?;
    let request_duration = Histogram::new(
        "request_duration_seconds",
        "Request duration in seconds"
    )?;
    let active_connections = Gauge::new(
        "active_connections",
        "Number of active connections"
    )?;

    // Register metrics
    registry.register(Box::new(requests_total))?;
    registry.register(Box::new(request_duration))?;
    registry.register(Box::new(active_connections))?;

    Ok(())
}

gRPC Common Types

use rustfs_common::grpc::{GrpcResult, GrpcError, TonicStatus};
use tonic::{Request, Response, Status};

async fn grpc_service_example(
    request: Request<MyRequest>
) -> GrpcResult<MyResponse> {
    let req = request.into_inner();

    // Validate request
    if req.name.is_empty() {
        return Err(GrpcError::invalid_argument("Name cannot be empty"));
    }

    // Process request
    let response = MyResponse {
        result: format!("Processed: {}", req.name),
        status: "success".to_string(),
    };

    Ok(Response::new(response))
}

// Error conversion
impl From<Error> for Status {
    fn from(err: Error) -> Self {
        match err.kind() {
            ErrorKind::NotFound => Status::not_found(err.to_string()),
            ErrorKind::PermissionDenied => Status::permission_denied(err.to_string()),
            ErrorKind::InvalidInput => Status::invalid_argument(err.to_string()),
            _ => Status::internal(err.to_string()),
        }
    }
}

🏗️ Architecture

Common Module Structure

Common Architecture:
┌─────────────────────────────────────────────────────────────┐
│                    Public API Layer                         │
├─────────────────────────────────────────────────────────────┤
│  Core Types    │   Error Types   │   Result Types           │
├─────────────────────────────────────────────────────────────┤
│  Async Utils   │   Metrics       │   gRPC Common            │
├─────────────────────────────────────────────────────────────┤
│  Constants     │   Serialization │   Logging                │
├─────────────────────────────────────────────────────────────┤
│              Foundation Types                                │
└─────────────────────────────────────────────────────────────┘

Core Components

Component	Purpose	Usage
Types	Common data structures	Shared across all modules
Errors	Unified error handling	Consistent error reporting
Async Utils	Async patterns	Common async operations
Metrics	Observability	Performance monitoring
gRPC	Protocol support	Service communication

🧪 Testing

Run the test suite:

# Run all tests
cargo test

# Test specific components
cargo test types
cargo test errors
cargo test async_utils

📋 Requirements

• Rust: 1.70.0 or later
• Platforms: Linux, macOS, Windows
• Dependencies: Minimal, focused on essential functionality

🌍 Related Projects

This module is part of the RustFS ecosystem:

• RustFS Main - Core distributed storage system
• RustFS Utils - Utility functions
• RustFS Config - Configuration management

📚 Documentation

For comprehensive documentation, visit:

• RustFS Documentation
• Common API Reference

🔗 Links

• Documentation - Complete RustFS manual
• Changelog - Release notes and updates
• GitHub Discussions - Community support

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

---

RustFS is a trademark of RustFS, Inc.
All other trademarks are the property of their respective owners.

Made with 🔧 by the RustFS Team