Pervaxis.Genesis.Caching.AWS 2.0.0

Pervaxis.Genesis.Caching.AWS

AWS ElastiCache (Redis) caching provider for the Pervaxis Genesis platform.

Overview

Pervaxis.Genesis.Caching.AWS implements the ICache abstraction from Pervaxis.Core.Abstractions using StackExchange.Redis as the Redis client. It supports AWS ElastiCache clusters and local Redis instances (including LocalStack).

Installation

<PackageReference Include="Pervaxis.Genesis.Caching.AWS" Version="1.0.0" />

GitHub Packages feed — add the following to your nuget.config:

<add key="github" value="https://nuget.pkg.github.com/clarivex-tech/index.json" />

Configuration

appsettings.json

{
  "Caching": {
    "ConnectionString": "my-cluster.abc123.cache.amazonaws.com:6379",
    "Region": "ap-south-1",
    "UseSsl": true,
    "DefaultExpiry": "01:00:00",
    "KeyPrefix": "myapp",
    "Database": 0,
    "ConnectTimeoutMs": 5000,
    "SyncTimeoutMs": 5000,
    "AbortOnConnectFail": false
  }
}

Option properties

Resilience configuration

The Caching provider includes built-in resilience policies (retry, circuit breaker, timeout) powered by Polly v8 to handle transient AWS failures gracefully.

Resilience options

Example configuration

{
  "Caching": {
    "ConnectionString": "my-cluster.cache.amazonaws.com:6379",
    "Region": "ap-south-1",
    "Resilience": {
      "Enabled": true,
      "RetryCount": 3,
      "RetryDelayMs": 1000,
      "CircuitBreakerFailureThreshold": 0.5,
      "CircuitBreakerDurationSeconds": 60,
      "TimeoutSeconds": 30
    }
  }
}

Transient errors handled

The resilience pipeline automatically retries these transient AWS and network errors:

• Throttling: HTTP 429, ThrottlingException, RequestLimitExceeded
• Service errors: HTTP 500, 503, ServiceUnavailable, InternalServerError
• Network errors: IOException, SocketException, HttpRequestException
• Timeouts: TimeoutException, RequestTimeout

Disabling resilience

To disable resilience (e.g., for testing):

{
  "Caching": {
    "Resilience": {
      "Enabled": false
    }
  }
}

Registration

IConfiguration overload

builder.Services.AddGenesisCaching(
    builder.Configuration.GetSection("Caching"));

Action overload

builder.Services.AddGenesisCaching(options =>
{
    options.ConnectionString = "localhost:6379";
    options.Region = "ap-south-1";
    options.UseSsl = false;
    options.DefaultExpiry = TimeSpan.FromMinutes(30);
});

The provider is registered as a Singleton (ICache → ElastiCacheProvider). The underlying Redis connection uses Lazy<IConnectionMultiplexer> so it is created on first use.

Usage

Inject ICache wherever caching is needed:

public class ProductService(ICache cache)
{
    private const string Prefix = "products";

    public async Task<Product?> GetProductAsync(int id, CancellationToken ct = default)
    {
        var key = $"{Prefix}:{id}";

        var cached = await cache.GetAsync<Product>(key, ct);
        if (cached is not null)
        {
            return cached;
        }

        var product = await _repository.FindAsync(id, ct);
        if (product is not null)
        {
            await cache.SetAsync(key, product, TimeSpan.FromMinutes(15), ct);
        }

        return product;
    }

    public async Task InvalidateAsync(int id, CancellationToken ct = default)
        => await cache.RemoveAsync($"{Prefix}:{id}", ct);
}

Available operations

All methods accept an optional CancellationToken and throw GenesisException on Redis errors.

Local Development with LocalStack

{
  "Caching": {
    "ConnectionString": "localhost:6379",
    "Region": "us-east-1",
    "UseSsl": false,
    "UseLocalEmulator": true
  }
}

Start Redis locally:

docker run -d -p 6379:6379 redis:7-alpine

Or with LocalStack:

localstack start
awslocal elasticache create-replication-group \
  --replication-group-id local-cluster \
  --replication-group-description "Local dev"

IAM Permissions

The AWSSDK.ElastiCache package is included for optional configuration discovery (e.g. listing cluster endpoints at startup). The Redis operations themselves go directly over the TCP connection and do not require IAM permissions.

If you use the AWS SDK for endpoint discovery, the following permissions are required:

{
  "Effect": "Allow",
  "Action": [
    "elasticache:DescribeReplicationGroups",
    "elasticache:DescribeCacheClusters"
  ],
  "Resource": "*"
}

Serialization

Values are serialized to JSON using System.Text.Json with PropertyNameCaseInsensitive = true. Ensure your cached types are JSON-serializable.

Troubleshooting