Struct Foyer 

pub struct Foyer { /* private fields */ }

Available on crate feature services-foyer only.

foyer backend support.

Foyer Service

foyer is a high-performance hybrid cache library that supports both in-memory and on-disk caching.

This service provides foyer as a volatile KV storage backend. Data stored may be evicted when the cache is full.

Capabilities

This service can be used to:

• stat
• read
• write
• delete
• list (not supported)
• blocking (not supported)

Configuration

Foyer service can be configured in two ways:

1. Pre-configured cache: Pass a fully configured HybridCache instance for maximum control
2. Auto-configured cache: Use builder methods to configure memory and disk caching

Auto-configured Cache Options

When using the builder API without providing a pre-built cache, the following options are available:

• memory: Memory cache capacity (default: 1 GiB)
• disk_path: Directory path for disk cache (enables hybrid caching)
• disk_capacity: Total disk cache capacity
• disk_file_size: Individual cache file size (default: 1 MiB)
• recover_mode: Recovery mode on startup - “none” (default), “quiet”, or “strict”
• shards: Number of cache shards for concurrency (default: 1)

Example

Via Pre-configured Cache

use opendal::Operator;
use opendal_service_foyer::Foyer;
use opendal_service_foyer::FoyerKey;
use opendal_service_foyer::FoyerValue;
use foyer::{HybridCacheBuilder, Engine};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a foyer HybridCache with full control
    let cache = HybridCacheBuilder::new()
        .memory(64 * 1024 * 1024) // 64MB memory cache
        .storage(Engine::Large(Default::default()))
        .build()
        .await?;

    // Create operator
    let op = Operator::new(Foyer::new().cache(cache))?
        .finish();

    // Use it like any other OpenDAL operator
    op.write("key", "value").await?;
    let value = op.read("key").await?;

    Ok(())
}

Via Auto-configuration (Hybrid Cache)

use opendal::Operator;
use opendal_service_foyer::Foyer;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create operator with hybrid cache (memory + disk)
    let op = Operator::new(
        Foyer::new()
            .memory(64 * 1024 * 1024)           // 64MB memory
            .disk_path("/tmp/foyer_cache")      // Enable disk cache
            .disk_capacity(1024 * 1024 * 1024)  // 1GB disk
            .disk_file_size(1024 * 1024)        // 1MB per file
            .recover_mode("quiet")              // Recover on restart
            .shards(4)                          // 4 shards for concurrency
    )?
    .finish();

    op.write("key", "value").await?;
    let value = op.read("key").await?;

    Ok(())
}

Via URI

use opendal::Operator;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Memory-only cache via URI
    let op = Operator::from_uri("foyer:///?memory=67108864")?;

    // Hybrid cache via URI
    let op = Operator::from_uri(
        "foyer:///cache?memory=67108864&disk_path=/tmp/foyer&disk_capacity=1073741824"
    )?;

    Ok(())
}

Notes

• Data Volatility: Foyer is a cache, not persistent storage. Data may be evicted at any time when the cache reaches its capacity limit.
• Hybrid Caching: When disk_path is configured, cold data automatically moves from memory to disk as the memory cache fills up.
• Recovery Modes:
  • "none": Don’t restore data from disk on restart (volatile cache)
  • "quiet": Restore data and skip any corrupted entries
  • "strict": Restore data and fail on any corruption
• No List Support: Foyer does not support efficient key iteration, so the list operation is not available.
• Async Only: Foyer is async-only, blocking operations are not supported.

Implementations

impl FoyerBuilder

pub fn new() -> FoyerBuilder

Create a new FoyerBuilder with default settings.

The cache will be lazily initialized when first accessed if not provided via Self::cache.

Example

use opendal_service_foyer::Foyer;

let builder = Foyer::new()
    .memory(64 * 1024 * 1024)
    .root("/cache");

pub fn name(self, name: &str) -> FoyerBuilder

Set the name of this cache instance.

pub fn cache(self, cache: HybridCache<FoyerKey, FoyerValue>) -> FoyerBuilder

Set a pre-built [foyer::HybridCache] instance.

If provided, this cache will be used directly. Otherwise, a cache will be lazily initialized using the configured memory size.

Example

use opendal_service_foyer::Foyer;
use foyer::{HybridCacheBuilder, Engine};

let cache = HybridCacheBuilder::new()
    .memory(64 * 1024 * 1024)
    .storage(Engine::Large(Default::default()))
    .build()
    .await?;

let builder = Foyer::new().cache(cache);

pub fn root(self, path: &str) -> FoyerBuilder

Set the root path of this backend.

All operations will be relative to this root path.

pub fn memory(self, size: usize) -> FoyerBuilder

Set the memory capacity in bytes for the cache.

This is used when the cache is lazily initialized (i.e., when no pre-built cache is provided via Self::cache).

Default is 1 GiB (1024 * 1024 * 1024 bytes).

pub fn disk_path(self, path: &str) -> FoyerBuilder

Set the disk cache directory path.

Enables hybrid cache with disk storage. When memory cache is full, data will be persisted to this directory.

pub fn disk_capacity(self, size: usize) -> FoyerBuilder

Set the disk cache total capacity in bytes.

Only used when disk_path is set.

pub fn disk_file_size(self, size: usize) -> FoyerBuilder

Set the individual cache file size in bytes.

Default is 1 MiB (1024 * 1024 bytes). Only used when disk_path is set.

pub fn recover_mode(self, mode: &str) -> FoyerBuilder

Set the recovery mode when starting the cache.

Valid values: “none” (default), “quiet”, “strict”.

• “none”: Don’t recover from disk
• “quiet”: Recover and skip errors
• “strict”: Recover and panic on errors

pub fn shards(self, count: usize) -> FoyerBuilder

Set the number of shards for concurrent access.

Default is 1. Higher values improve concurrency but increase overhead.

Trait Implementations

impl Builder for FoyerBuilder

type Config = FoyerConfig

Associated configuration for this builder.

fn build(self) -> Result<impl Access, Error>

Consume the accessor builder to build a service.

impl Debug for FoyerBuilder

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

Formats the value using the given formatter.

impl Default for FoyerBuilder

fn default() -> FoyerBuilder

Returns the “default value” for a type.