Struct CacheControl 

pub struct CacheControl {
    pub max_age: u64,
    pub key: String,
}

HTTP cache control configuration for optimizing response caching.

The CacheControl struct encapsulates caching metadata used to optimize HTTP response delivery through strategic cache management. It provides fine-grained control over cache behavior including cache duration and cache key generation for efficient content delivery.

Purpose

This struct enables:

• Cache Duration Control: Setting appropriate cache lifetimes via max_age
• Cache Key Management: Generating unique identifiers for cached content
• Performance Optimization: Reducing server load through intelligent caching
• CDN Integration: Supporting Content Delivery Network caching strategies

Cache Strategy

The cache control system implements a dual-approach strategy:

1. Time-based Expiration: Uses max_age for cache lifetime management
2. Content-based Invalidation: Uses key for cache versioning and invalidation

Integration with Response

When attached to a Response, the CacheControl struct automatically:

• Sets appropriate HTTP cache headers (Cache-Control, ETag, etc.)
• Generates cache keys for storage systems
• Enables conditional requests (304 Not Modified responses)
• Supports cache invalidation strategies

Examples

Basic Cache Control

use ignitia::{Response, CacheControl};

let cache_control = CacheControl {
    max_age: 3600, // 1 hour
    key: "user_profile_123".to_string(),
};

let response = Response::json(user_data)?
    .with_cache_control(cache_control);

Static Asset Caching

// Long-term caching for static assets
let static_cache = CacheControl {
    max_age: 31536000, // 1 year
    key: format!("static_{}_{}", filename, version_hash),
};

API Response Caching

// Short-term caching for API responses
let api_cache = CacheControl {
    max_age: 300, // 5 minutes
    key: format!("api_{}_{}_{}", endpoint, user_id, timestamp),
};

Dynamic Content Caching

// User-specific content with medium cache duration
let user_cache = CacheControl {
    max_age: 1800, // 30 minutes
    key: format!("content_{}_{}", content_id, last_modified),
};

Fields

max_age: u64

Maximum age for cached content in seconds.

This field determines how long the content should be considered fresh by browsers, CDNs, and intermediate caches. The value directly maps to the HTTP Cache-Control: max-age= directive.

Common Values

• 0: No caching (always revalidate)
• 300: 5 minutes (dynamic API responses)
• 3600: 1 hour (semi-static content)
• 86400: 24 hours (daily updated content)
• 31536000: 1 year (static assets with versioning)

Performance Considerations

• Longer cache times reduce server load but may serve stale content
• Shorter cache times ensure freshness but increase server requests
• Consider content update frequency when setting values

Examples

// No caching for sensitive data
let sensitive = CacheControl { max_age: 0, key: "...".to_string() };

// Medium caching for API responses
let api = CacheControl { max_age: 600, key: "...".to_string() };

// Long caching for static assets
let static_content = CacheControl { max_age: 2592000, key: "...".to_string() };

key: String

Unique identifier for cache entry management and invalidation.

The cache key serves multiple purposes in the caching infrastructure:

• Uniqueness: Ensures different content versions are cached separately
• Invalidation: Enables targeted cache clearing when content changes
• Versioning: Supports content versioning through key changes
• Debugging: Provides identifiable cache entries for troubleshooting

Key Generation Strategies

Content-Based Keys

Include content identifiers that change when content changes:

let key = format!("article_{}_{}", article_id, last_modified_timestamp);

User-Specific Keys

Include user context for personalized content:

let key = format!("dashboard_{}_{}_{}", user_id, role, preferences_hash);

Version-Based Keys

Include application or content version for cache busting:

let key = format!("api_response_{}_v{}", endpoint, api_version);

Hierarchical Keys

Use hierarchical structure for organized cache management:

let key = format!("app:{}:user:{}:page:{}", app_version, user_id, page_id);

Best Practices

• Include all relevant context that affects content
• Use consistent naming conventions across the application
• Include version or timestamp information for automatic invalidation
• Keep keys reasonably short while maintaining uniqueness
• Avoid sensitive information in cache keys

Performance Notes

• Shorter keys reduce memory overhead in cache systems
• Consistent key patterns improve cache hit rates
• Include enough context to avoid cache collisions
• Consider key distribution for cache sharding strategies

Trait Implementations

impl Clone for CacheControl

fn clone(&self) -> CacheControl

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CacheControl

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.