Foundatio Documentation

Foundatio's IResiliencePolicy is benchmarked against Polly's ResiliencePipeline. Foundatio is optimized for high-frequency operations and low-latency requirements, particularly when retries are involved.

Key Performance Advantages

• Synchronous Execution: Foundatio is significantly faster when retries or results are involved (up to 5.3x faster than Polly). Foundatio maintains 0 bytes of allocation for all synchronous scenarios.
• Asynchronous Execution: Foundatio is 3.0x to 3.8x faster than Polly when retries or results are involved. Both libraries incur similar async state machine overhead (64 B).
• Zero-Allocation Patterns: Foundatio's state-based overloads achieve true zero-allocation execution. In contrast, Polly's state-based pattern still allocates approximately 88 bytes.

Summary Table: Foundatio Advantage

The RedisHybridCacheClient implements a two-layer caching architecture to optimize performance:

1. L1 Cache (Local In-Memory): Provides extremely low latency for frequent reads.
2. L2 Cache (Redis Distributed): Acts as the source of truth for all instances.

Read Flow

Request $\rightarrow$ Check L1. If Hit: Return. If Miss: Check L2. If L2 Hit: Store in L1 and Return.

Write Flow (Distributed-First)

Write to L2 (Redis) first. If successful, update L1 locally and publish an invalidation message via Redis pub/sub. Other instances receive this message and clear only the specific affected keys from their local L1 caches.

Key Features

• Automatic Sync: Uses Redis pub/sub to keep L1 caches consistent across instances.
• Prefix Removal: RemoveByPrefixAsync("user:") clears all user:* keys across all instances.
• Full Flush: RemoveAllAsync() clears the entire L1 cache on all instances.

WARNING

By default, all instances share the same Redis pub/sub topic for invalidation. In high-write scenarios, consider using separate topics per feature area.

var hybridCache = new RedisHybridCacheClient(
    redisConfig => redisConfig.ConnectionMultiplexer(redis).LoggerFactory(loggerFactory),
    localConfig => localConfig.MaxItems(1000)
);

// When you update a value, all instances are notified via pub/sub
await hybridCache.SetAsync("config:app", newConfig);

Foundatio queues use two different identifiers that serve distinct roles. Understanding the difference is critical for data routing and cross-process communication.

Queue Name

• Purpose: Identifies the queue in the backing store (e.g., Redis key prefix, SQS queue name).
• Stability: Stable across restarts.
• Sharing: Shared across processes. Two processes with the same Name will read from and write to the same data.
• Routing: All distributed implementations (Redis, SQS, Azure Service Bus, Azure Storage) use Name for data routing.

Queue ID

• Purpose: A runtime instance identifier used exclusively for logging and diagnostics.
• Stability: Not stable (uses a random suffix by default).
• Sharing: Not shared across processes; it has no effect on data routing or the backing store.
• Use Case: Allows multiple queue instances within the same process (like priority queues) to produce distinguishable logs.

To ensure reliability and correctness, follow these patterns when implementing jobs:

1. Propagate Cancellation Tokens: Always pass context.CancellationToken to async calls and check it in loops to ensure graceful shutdown.
2. Renew Locks: For long-running jobs using distributed locks, call context.RenewLockAsync() periodically to prevent the lock from expiring mid-run.
3. Ensure Idempotency: Jobs may be interrupted (crashes, deployments). Design them to track progress (e.g., via external state) so they can resume without re-processing completed work.
4. Handle Errors Correctly:
   • Return JobResult.FailedWithMessage(msg) for transient errors to trigger framework retries.
   • Return JobResult.Success for permanent errors (after logging) to prevent infinite retry loops.
5. Use Structured Logging: Use _logger.BeginScope to correlate log entries with specific work items (e.g., OrderId).

Foundatio uses an abstraction layer for serialization, allowing you to swap implementations (like JSON or binary) without changing your business logic.

• ISerializer: The base interface providing Deserialize(Stream data, Type objectType) and Serialize(object? value, Stream output).
• ITextSerializer: A marker interface for serializers that produce human-readable text (e.g., JSON, XML). Text serializers use UTF-8 encoding for string conversions in extension methods.

Binary serializers (like MessagePack) implement ISerializer but not ITextSerializer. When using string-based extension methods with binary serializers, strings are treated as Base64-encoded data, whereas text serializers treat them as UTF-8.

public interface ISerializer
{
    object? Deserialize(Stream data, Type objectType);
    void Serialize(object? value, Stream output);
}

public interface ITextSerializer : ISerializer { }