MohamedHabib.Abp.Caching.RedHatDataGrid 1.0.0

ABP Framework - Red Hat Data Grid Caching Module

A production-ready distributed caching module for ABP Framework that integrates with Red Hat Data Grid (Infinispan). This module provides seamless integration with ABP's IDistributedCache interface, supporting both standard and typed caching with automatic serialization, retry policies, and health checks.

Features

• ✅ Full ABP Framework Integration - Seamlessly replaces the default distributed cache
• ✅ Type-Safe Caching - Support for both IDistributedCache and IDistributedCache<T>
• ✅ Multi-Tenancy Support - Built-in cache key prefixing for tenant isolation
• ✅ Automatic Retry Policies - Powered by Polly for resilient connections
• ✅ Health Checks - Built-in ASP.NET Core health check integration
• ✅ Auto Cache Creation - Automatically creates caches when they don't exist
• ✅ Multiple Cache Support - Work with multiple named caches
• ✅ Production Ready - Comprehensive error handling and logging
• ✅ REST API v2 - Uses Red Hat Data Grid REST API for broad compatibility
• ✅ Configurable - Extensive configuration options for all scenarios
• ✅ SSL/TLS Support - Support for secure connections with certificate validation
• ✅ Digest Authentication - Built-in authentication support

Installation

Install the NuGet package:

dotnet add package Volo.Abp.Caching.RedHatDataGrid

Or using Package Manager Console:

Install-Package Volo.Abp.Caching.RedHatDataGrid

Quick Start

1. Add Module Dependency

Add AbpRedHatDataGridModule to your module's dependencies:

using Volo.Volo.Abp.Caching.RedHatDataGrid;

[DependsOn(
    typeof(AbpRedHatDataGridModule)
    // ... other dependencies
)]
public class YourModule : AbpModule
{
    // ...
}

2. Configure Settings

Add Red Hat Data Grid configuration to your appsettings.json:

{
  "RedHatDataGrid": {
    "BaseUrl": "http://localhost:11222",
    "Username": "admin",
    "Password": "password",
    "DefaultCacheName": "my-app-cache",
    "CacheKeyPrefix": "MyApp",
    "AutoCreateCache": true,
    "DefaultAbsoluteExpirationSeconds": 3600,
    "DefaultSlidingExpirationSeconds": 600,
    "EnableHealthChecks": true
  }
}

3. Use in Your Code

The module automatically replaces IDistributedCache, so you can use it immediately:

public class UserService : ITransientDependency
{
    private readonly IDistributedCache<UserDto> _cache;

    public UserService(IDistributedCache<UserDto> cache)
    {
        _cache = cache;
    }

    public async Task<UserDto> GetUserAsync(Guid userId)
    {
        return await _cache.GetOrAddAsync(
            userId.ToString(),
            async () => await LoadUserFromDatabaseAsync(userId),
            () => new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(30)
            }
        );
    }
}

Configuration Options

Complete Configuration Reference

{
  "RedHatDataGrid": {
    // Connection Settings
    "BaseUrl": "http://localhost:11222",
    "Username": "admin",
    "Password": "password",
    "ValidateSslCertificate": true,
    "RequestTimeoutSeconds": 30,
    
    // Cache Settings
    "DefaultCacheName": "default-cache",
    "CacheTemplate": "distributed-cache",
    "AutoCreateCache": true,
    "ContentType": "application/octet-stream",
    "CacheKeyPrefix": "MyApp",
    
    // Expiration Settings
    "DefaultAbsoluteExpirationSeconds": 3600,
    "DefaultSlidingExpirationSeconds": 600,
    
    // Resilience Settings
    "RetryCount": 3,
    "RetryDelayMilliseconds": 1000,
    "HideErrors": true,
    
    // Health Check Settings
    "EnableHealthChecks": true,
    "HealthCheckTimeoutSeconds": 5
  }
}

Configuration Options Explained

Usage Examples

Basic Caching

public class ProductService : ITransientDependency
{
    private readonly IDistributedCache _cache;

    public ProductService(IDistributedCache cache)
    {
        _cache = cache;
    }

    public async Task<string> GetProductNameAsync(int productId)
    {
        var key = $"product:{productId}:name";
        var cachedName = await _cache.GetStringAsync(key);
        
        if (cachedName != null)
        {
            return cachedName;
        }

        var name = await LoadProductNameFromDatabase(productId);
        
        await _cache.SetStringAsync(
            key, 
            name,
            new DistributedCacheEntryOptions
            {
                AbsoluteExpirationRelativeToNow = TimeSpan.FromHours(1)
            }
        );

        return name;
    }
}

Type-Safe Caching

public class OrderService : ITransientDependency
{
    private readonly IDistributedCache<OrderDto> _orderCache;

    public OrderService(IDistributedCache<OrderDto> orderCache)
    {
        _orderCache = orderCache;
    }

    public async Task<OrderDto> GetOrderAsync(Guid orderId)
    {
        // GetOrAddAsync handles serialization automatically
        return await _orderCache.GetOrAddAsync(
            orderId.ToString(),
            async () => await LoadOrderFromDatabase(orderId),
            () => new DistributedCacheEntryOptions
            {
                SlidingExpiration = TimeSpan.FromMinutes(15)
            }
        );
    }

    public async Task InvalidateOrderAsync(Guid orderId)
    {
        await _orderCache.RemoveAsync(orderId.ToString());
    }
}

Manual Configuration

You can also configure options in code:

public override void ConfigureServices(ServiceConfigurationContext context)
{
    context.Services.ConfigureRedHatDataGrid(options =>
    {
        options.BaseUrl = "https://datagrid.example.com:11222";
        options.Username = "admin";
        options.Password = Environment.GetEnvironmentVariable("DATAGRID_PASSWORD");
        options.DefaultCacheName = "production-cache";
        options.CacheKeyPrefix = "MyApp";
        options.ValidateSslCertificate = true;
        options.HideErrors = true;
    });
}

Health Checks

The module automatically registers a health check when EnableHealthChecks is true. You can use it with ASP.NET Core health check endpoints:

public override void OnApplicationInitialization(ApplicationInitializationContext context)
{
    var app = context.GetApplicationBuilder();
    
    app.UseRouting();
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHealthChecks("/health");
        endpoints.MapHealthChecks("/health/ready", new HealthCheckOptions
        {
            Predicate = check => check.Tags.Contains("ready")
        });
    });
}

The health check will:

• ✅ Verify connectivity to Red Hat Data Grid
• ✅ Include cache statistics (size, etc.)
• ✅ Timeout after configured seconds
• ✅ Provide detailed diagnostic information

Docker Setup for Development

Run Red Hat Data Grid locally using Docker:

docker run -it --rm \
  -p 11222:11222 \
  -e USER=admin \
  -e PASS=password \
  quay.io/infinispan/server:15.0

Or using Docker Compose:

version: '3.8'

services:
  datagrid:
    image: quay.io/infinispan/server:15.0
    ports:
      - "11222:11222"
    environment:
      - USER=admin
      - PASS=password

Access the Web Console at: http://localhost:11222/console

Production Deployment

Kubernetes Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  appsettings.Production.json: |
    {
      "RedHatDataGrid": {
        "BaseUrl": "http://datagrid-service:11222",
        "Username": "admin",
        "DefaultCacheName": "production-cache",
        "CacheKeyPrefix": "MyApp:Prod",
        "ValidateSslCertificate": true,
        "HideErrors": true,
        "EnableHealthChecks": true
      }
    }
---
apiVersion: v1
kind: Secret
metadata:
  name: datagrid-credentials
type: Opaque
stringData:
  password: your-secure-password

Environment Variables

You can override settings using environment variables:

RedHatDataGrid__BaseUrl=http://datagrid:11222
RedHatDataGrid__Username=admin
RedHatDataGrid__Password=secret123
RedHatDataGrid__DefaultCacheName=prod-cache

Advanced Features

Multiple Cache Support

public class MultiCacheService : ITransientDependency
{
    private readonly IRedHatDataGridCacheClient _cacheClient;

    public MultiCacheService(IRedHatDataGridCacheClient cacheClient)
    {
        _cacheClient = cacheClient;
    }

    public async Task UseDifferentCachesAsync()
    {
        // Use different caches for different data types
        await _cacheClient.SetAsync("users-cache", "user:1", data);
        await _cacheClient.SetAsync("products-cache", "product:1", data);
        await _cacheClient.SetAsync("orders-cache", "order:1", data);
    }

    public async Task<long> GetCacheSizeAsync(string cacheName)
    {
        return await _cacheClient.GetCacheSizeAsync(cacheName);
    }

    public async Task ClearCacheAsync(string cacheName)
    {
        await _cacheClient.ClearCacheAsync(cacheName);
    }
}

Cache Statistics

public class CacheMonitoringService : ITransientDependency
{
    private readonly IRedHatDataGridCacheClient _cacheClient;
    private readonly ILogger<CacheMonitoringService> _logger;

    public async Task LogCacheStatisticsAsync()
    {
        var stats = await _cacheClient.GetCacheStatisticsAsync("my-cache");
        _logger.LogInformation("Cache Statistics: {Stats}", stats);
        
        var size = await _cacheClient.GetCacheSizeAsync("my-cache");
        _logger.LogInformation("Cache Size: {Size} entries", size);
    }
}

Troubleshooting

Connection Issues

Problem: Unable to connect to Red Hat Data Grid

Solutions:

1. Verify Data Grid is running: curl http://localhost:11222/rest/v2/server
2. Check username/password in configuration
3. Verify firewall rules allow connection
4. Check application logs for detailed error messages

Cache Not Working

Problem: Data not being cached or retrieved

Solutions:

1. Enable debug logging to see cache operations
2. Verify AutoCreateCache is true or cache exists
3. Check cache key prefix configuration
4. Verify expiration settings are appropriate

Performance Issues

Problem: Slow cache operations

Solutions:

1. Increase RequestTimeoutSeconds
2. Reduce RetryCount if not needed
3. Use local Data Grid instance for development
4. Consider network latency between app and Data Grid
5. Check Data Grid server performance

Health Check Failing

Problem: Health check reports unhealthy

Solutions:

1. Check Data Grid server status
2. Verify network connectivity
3. Increase HealthCheckTimeoutSeconds
4. Check authentication credentials
5. Review application and Data Grid logs

Migration from Other Cache Providers

From Redis

Simply replace the Redis module with this module and update configuration:

[DependsOn(
-   typeof(AbpCachingStackExchangeRedisModule)
+   typeof(AbpRedHatDataGridModule)
)]
public class YourModule : AbpModule

Update appsettings.json:

-"Redis": {
-  "Configuration": "localhost:6379"
-}
+"RedHatDataGrid": {
+  "BaseUrl": "http://localhost:11222",
+  "Username": "admin",
+  "Password": "password"
+}

No code changes required! The module implements the same IDistributedCache interface.

Performance Considerations

• Cache Key Length: Keep cache keys reasonably short
• Serialization: Type-safe caching uses JSON serialization
• TTL Settings: Balance between freshness and cache hits
• Network Latency: Deploy Data Grid close to your application
• Batch Operations: Use typed caching for better performance
• Connection Pooling: HttpClient factory handles connection reuse

Requirements

• .NET 6.0, 7.0, 8.0, or 9.0
• ABP Framework 8.3 or later
• Red Hat Data Grid 8.0+ or Infinispan 14+

Compatibility

This module is compatible with:

• ✅ Red Hat Data Grid 8.x, 9.x
• ✅ Infinispan 14.x, 15.x
• ✅ ABP Framework 8.3+
• ✅ .NET 6.0, 7.0, 8.0, 9.0

Multi-Target Framework Support

The package is built for multiple target frameworks, ensuring compatibility across different .NET versions:

• net6.0 - .NET 6.0 LTS
• net7.0 - .NET 7.0
• net8.0 - .NET 8.0 LTS
• net9.0 - .NET 9.0

Your application will automatically use the appropriate version based on your target framework.

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

License

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

Support

• Documentation: Full Documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Related Links

• ABP Framework
• Red Hat Data Grid
• Infinispan
• Infinispan Getting Started Guide - Quick setup and basic usage
• Red Hat Data Grid REST API Documentation - Complete REST API v2 reference

Acknowledgments

Built with ❤️ for the ABP Framework community.

Note: This is an unofficial community module and is not affiliated with or endorsed by Red Hat, Inc. or ABP.io.