Tyto.Caching.Backplane 0.0.1-alpha.100

📡 Tyto.Caching.Backplane

Tyto.Caching.Backplane provides multi-node distributed L1 cache synchronization for Tyto.Caching. It uses a lightweight pub/sub backplane (e.g., Redis Pub/Sub, InMemory) to broadcast cache invalidation messages across all server replicas in a cluster, eliminating stale data in local memory caches.

🌟 Why Do You Need a Backplane?

In a multi-instance/microservice environment:

1. When Node 1 updates or invalidates a cached entity (InvalidateAsync), it removes the key from its local L1 memory cache and the shared L2 distributed cache (Redis).
2. However, Node 2 and Node 3 still hold the old, stale data in their local in-memory (L1) caches until their TTL expires.
3. Tyto.Caching.Backplane solves this by instantly broadcasting a lightweight invalidation message to all active replicas. Upon receiving the message, all other nodes evict the specific key from their local L1 memory cache.

                  ┌─────────────────────────────────┐
                  │   Node 1 (Initiates Invalidate) │
                  │  - Removes from local L1        │
                  │  - Removes from L2 (Redis)      │
                  │  - Publishes to Backplane       │
                  └────────────────┬────────────────┘
                                   │
                     (Backplane Invalidation Msg)
                                   ▼
         ┌─────────────────────────┴─────────────────────────┐
         ▼                                                   ▼
┌─────────────────────────────────┐         ┌─────────────────────────────────┐
│             Node 2              │         │             Node 3              │
│ - Receives message              │         │ - Receives message              │
│ - Evicts key from local L1      │         │ - Evicts key from local L1      │
└─────────────────────────────────┘         └─────────────────────────────────┘

✨ Key Features

• Sub-Millisecond L1 Cache Consistency: Synchronize in-memory caches across infinite cluster nodes with zero polling overhead.
• Transparent Decorator: Plugs seamlessly into Tyto.Caching's pipeline via ICacheFeature without changing your application code.
• Provider Agnostic: Works with any IBackplaneBus provider (Redis Pub/Sub, RabbitMQ, or InMemory for integration testing).
• Zero Key Drift: Employs Tyto's centralized ICacheKeyGenerator to ensure published keys match the exact hash/prefix format across all layers.
• Warmup Integration: Ensures channel subscriptions are established at application startup via CacheWarmupBackgroundService, preventing missed invalidations during deployment rollouts.
• Full Observability: Emits structured OpenTelemetry metrics and logs (tyto.caching.backplane.messages.received.total, trace events).

📦 Installation

Install the package alongside your preferred Backplane transport:

dotnet add package Tyto.Caching.Backplane
dotnet add package Tyto.Backplane.Redis

🚀 Quick Start

1. Register Services (Program.cs)

Enable distributed caching, configure your backplane bus, and attach .WithBackplane():

var builder = WebApplication.CreateBuilder(args);

builder.AddTyto(tyto =>
{
    // 1. Configure the underlying Backplane Transport (e.g., Redis Pub/Sub)
    tyto.AddRedisBackplane(options =>
    {
        options.Configuration = "localhost:6379";
    });

    // 2. Configure Caching with Backplane support
    tyto.AddDistributedCaching(caching =>
    {
        // Register L1 & L2 Cache Providers
        caching.AddInMemoryProvider("LocalMem");
        caching.AddRedisProvider("GlobalRedis", "localhost:6379");

        // Enable Backplane Synchronization Feature
        caching.WithBackplane();

        // Register a Hybrid Profile
        caching.AddProfile<string, UserDto>("UserProfile", options =>
        {
            options.L1ProviderName = "LocalMem";
            options.L2ProviderName = "GlobalRedis";
            options.DefaultAbsoluteExpiration = TimeSpan.FromHours(1);
            
            // Optional: Custom channel name (defaults to "caching:{ProfileName}")
            options.BackplaneChannelName = "caching:users";
        });
    });
});

💻 Usage in Application Code

Your domain and application code remain 100% clean and unaware of the backplane. Simply interact with ICache<TKey, TValue>:

public class UserService(ICache<string, UserDto> cache, UserRepository repo)
{
    public async Task<UserDto?> GetUserAsync(string userId, CancellationToken ct)
    {
        // Served instantly from L1 (Memory) or L2 (Redis)
        return await cache.GetOrSetAsync(userId, () => repo.FindByIdAsync(userId, ct));
    }

    public async Task UpdateUserAsync(UserDto user, CancellationToken ct)
    {
        await repo.UpdateAsync(user, ct);

        // 1. Evicts from local L1
        // 2. Evicts from shared L2
        // 3. Automatically broadcasts to all other nodes via Backplane!
        await cache.InvalidateAsync(user.Id);
    }
}

⚙️ How It Works Internally

1. Decoration: When .WithBackplane() is enabled, CacheFactory wraps the base hybrid/memory cache with BackplaneCacheDecorator<TKey, TValue>.
2. Channel Subscription: During initialization, the decorator subscribes to caching:{ProfileName} via IBackplaneBus.
3. Invalidation Flow:
   • Calling cache.InvalidateAsync(key) invokes the underlying cache manager to remove the item from local L1 and L2.
   • It formats the key using ICacheKeyGenerator (e.g., tyto:UserProfile:UserDto:12345).
   • It publishes an InvalidationMessage { Key = "..." } to the profile's backplane channel.
4. Broadcast Reception:
   • Other instances listening on caching:{ProfileName} receive the payload.
   • Each receiving node calls _l1Provider.RemoveAsync(receivedKey) to evict the entry from its local RAM without touching L2.

📊 Observability & Diagnostics

Tyto Backplane publishes detailed structured logs and OpenTelemetry counters:

• Metrics Counter: tyto.caching.backplane.messages.received.total (Tags: ProfileName)
• Tracing Activity: Cache.BackplaneMessageReceived
• Key Log Events:
  • [UserProfile] Invalidating key '...' and publishing invalidation message to backplane.
  • [UserProfile] Published invalidation for key '...'.
  • [UserProfile] Subscribed to backplane channel 'caching:UserProfile' for cache invalidation.
  • [UserProfile] Received invalidation message for key '...'. Removing from L1 cache.

📄 License

This project is licensed under the MIT License.