s3-pricing

A high-performance Rust library for fetching and caching AWS S3 pricing information dynamically using the AWS Pricing API.

🚀 Features

• Real-time Pricing: Fetch up-to-date S3 pricing directly from AWS Pricing API
• Intelligent Caching: Automatic caching with negative result caching to minimize API calls
• Comprehensive Coverage: Support for all S3 storage classes and AWS regions (global and China)
• Multiple Price Types:
  • Storage costs (per GB-month)
  • API request costs (Class A: PUT/COPY/POST/LIST, Class B: GET/SELECT)
  • Data transfer costs (to internet and cross-region)
• High Performance: Optimized with static filter caching and early-return algorithms
• Error Handling: Type-safe region validation and descriptive error messages
• Async/Await: Built on tokio for non-blocking operations
• China Regions: Full support for AWS China regions (cn-north-1, cn-northwest-1) with CNY pricing

📦 Installation

Add this to your Cargo.toml:

[dependencies]
s3-pricing = "0.1.0"
tokio = { version = "1.50", features = ["full"] }
anyhow = "1.0"

🚀 Quick Start

use s3_pricing::S3PricingClient;
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // Create a new pricing client (uses default AWS credentials)
    let client = S3PricingClient::new(None).await?;
    
    // Get storage price for STANDARD class in us-east-1
    let price = client.get_storage_price("us-east-1", "STANDARD").await?;
    println!("S3 STANDARD storage: ${:.4} per GB-month", price);
    
    // Get Class A request price (PUT, COPY, POST, LIST)
    let put_price = client.get_class_a_request_price("us-east-1", "STANDARD").await?;
    println!("PUT requests: ${:.10} per request (${:.4} per 1,000)", put_price, put_price * 1000.0);
    
    // Get Class B request price (GET, SELECT)
    let get_price = client.get_class_b_request_price("us-east-1", "STANDARD").await?;
    println!("GET requests: ${:.10} per request (${:.4} per 10,000)", get_price, get_price * 10000.0);
    
    // Get data transfer to internet price
    let transfer_price = client.get_data_transfer_price("us-east-1").await?;
    println!("Data transfer to internet: ${:.4} per GB", transfer_price);
    
    // Get cross-region transfer price
    let cross_region_price = client.get_cross_region_transfer_price("us-east-1", "eu-west-1").await?;
    println!("Transfer us-east-1 → eu-west-1: ${:.4} per GB", cross_region_price);
    
    // Display formatted pricing information
    client.display_pricing("us-east-1", "STANDARD", None).await?;
    client.display_pricing("eu-west-1", "GLACIER", Some(&"us-east-1".to_string())).await?;
    
    Ok(())
}

📚 Usage

AWS Credentials

The library automatically resolves AWS credentials using the standard AWS SDK credential chain:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
2. Shared credentials file (~/.aws/credentials)
3. AWS SSO profiles
4. IAM roles for EC2 instances
5. IAM roles for ECS tasks

You can optionally specify a named profile:

let client = S3PricingClient::new(Some("my-profile")).await?;

Supported S3 Storage Classes

• STANDARD - Standard S3 storage
• STANDARD_IA - Standard Infrequent Access
• ONEZONE_IA - One Zone Infrequent Access
• INTELLIGENT_TIERING - Intelligent-Tiering
• GLACIER / GLACIER_FLEXIBLE_RETRIEVAL - Glacier Flexible Retrieval
• DEEP_ARCHIVE - Glacier Deep Archive
• GLACIER_IR / GLACIER_INSTANT_RETRIEVAL - Glacier Instant Retrieval
• EXPRESS_ONEZONE - S3 Express One Zone
• REDUCED_REDUNDANCY - Reduced Redundancy (legacy)

Supported AWS Regions

All AWS regions are supported, including:

• Global Regions: US, Europe, Asia Pacific, Middle East, Africa, South America, Canada
  • Pricing in USD
  • Endpoint: api.pricing.us-east-1.amazonaws.com
• China Regions: cn-north-1 (Beijing), cn-northwest-1 (Ningxia)
  • Pricing in CNY
  • Endpoint: api.pricing.cn-northwest-1.amazonaws.com.cn

Pricing Methods

Storage Pricing

let price = client.get_storage_price("us-east-1", "STANDARD_IA").await?;
// Returns price per GB-month in USD

Request Pricing

// Class A: PUT, COPY, POST, LIST
let put_price = client.get_class_a_request_price("us-east-1", "STANDARD").await?;

// Class B: GET, SELECT, and all other operations
let get_price = client.get_class_b_request_price("us-east-1", "STANDARD").await?;

Data Transfer Pricing

// Transfer to internet
let internet_price = client.get_data_transfer_price("us-east-1").await?;

// Cross-region transfer
let cross_region = client.get_cross_region_transfer_price("us-east-1", "eu-west-1").await?;

Display Formatted Pricing

// Display with internet transfer pricing
client.display_pricing("us-east-1", "STANDARD", None).await?;

// Display with cross-region transfer pricing
let dest = "eu-west-1".to_string();
client.display_pricing("us-east-1", "STANDARD", Some(&dest)).await?;

AWS China Regions

AWS China regions require a separate client instance using new_china():

use s3_pricing::S3PricingClient;

// For global AWS regions (USD pricing)
let client = S3PricingClient::new(None).await?;
let price_usd = client.get_storage_price("us-east-1", "STANDARD").await?;
println!("US East: ${:.4} per GB-month", price_usd);

// For AWS China regions (CNY pricing)
let china_client = S3PricingClient::new_china(None).await?;
let price_cny = china_client.get_storage_price("cn-north-1", "STANDARD").await?;
println!("China (Beijing): ¥{:.4} per GB-month", price_cny);

// Display formatted pricing for China regions
china_client.display_pricing("cn-north-1", "STANDARD", None).await?;

Check if a Region is a China Region

use s3_pricing::S3PricingClient;

if S3PricingClient::is_china_region("cn-north-1") {
    // Use new_china() for CNY pricing
}

if S3PricingClient::is_china_region("us-east-1") {
    // false - use new() for USD pricing
}

Note: AWS China regions require AWS credentials configured for the China partition. The pricing API endpoint is api.pricing.cn-northwest-1.amazonaws.com.cn.

⚙️ Configuration

Cache Behavior

The library uses a two-tier caching strategy:

1. Positive Cache: Successful price lookups cached with 1-hour TTL
2. Negative Cache: Failed lookups cached with 5-minute TTL to prevent repeated API calls

Cache capacity:

• Positive cache: 1000 entries
• Negative cache: 500 entries

Performance Optimizations

• Static Filter Caching: Commonly used filters are cached using OnceLock
• Early Return: Price extraction returns immediately when first-tier price is found
• Efficient JSON Parsing: Uses serde_json::Value for filtering instead of string matching
• Region Validation: Type-safe region validation catches errors early

🔍 Examples

Compare Pricing Across Regions

use s3_pricing::S3PricingClient;
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    let client = S3PricingClient::new(None).await?;
    let regions = ["us-east-1", "eu-west-1", "ap-northeast-1"];
    
    for region in &regions {
        let price = client.get_storage_price(region, "STANDARD").await?;
        println!("{}: ${:.4} per GB-month", region, price);
    }
    
    Ok(())
}

Multi-Storage Class Comparison

#[tokio::main]
async fn main() -> Result<()> {
    let client = S3PricingClient::new(None).await?;
    let storage_classes = ["STANDARD", "STANDARD_IA", "GLACIER"];
    
    for class in &storage_classes {
        client.display_pricing("us-east-1", class, None).await?;
    }
    
    Ok(())
}

🛠️ Development

Prerequisites

• Rust 1.93.0 or later
• AWS credentials configured

Building from Source

git clone https://github.com/bartleboeuf/s3-pricing.git
cd s3-pricing
cargo build

Running Tests

cargo test

Code Quality

# Run clippy for linting
cargo clippy -- -D warnings

# Format code
cargo fmt

📊 Performance Benchmarks

⚠️ Important Notes

• Pricing API Endpoints:
  • Global regions: api.pricing.us-east-1.amazonaws.com
  • China regions: api.pricing.cn-northwest-1.amazonaws.com.cn
• Currency: Prices are returned in USD for global regions, CNY for China regions.
• Pricing Tiers: The library returns first-tier (base) pricing where available.
• Cache TTL: Prices are cached for 1 hour. Restart the application to fetch fresh data.
• China Regions: Requires AWS credentials configured for the China partition.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

• Documentation: docs.rs/s3-pricing
• Issues: GitHub Issues
• Repository: github.com/bartleboeuf/s3-pricing

🙏 Acknowledgments

• Built on the AWS SDK for Rust
• Caching powered by quick-cache
• Error handling with anyhow

📦 Dependencies

• aws-sdk-pricing - AWS Pricing API client
• aws-config - AWS configuration and credentials
• tokio - Async runtime
• serde_json - JSON parsing
• anyhow - Error handling
• quick_cache - Fast in-memory caching

Last updated: March 14, 2026