StackExchange.Redis.Extensions

StackExchange.Redis.Extensions provides high-level implementations for various Redis data structures and features:

• Object Management: Add, retrieve, replace, and remove complex objects.
• Hashes: Standard hash operations and Hash Field Expiry (requires Redis 7.4+).
• Advanced Data Types:
  • GeoSpatial Indexes for location-based data.
  • VectorSet for AI/ML similarity search (requires Redis 8.0+).
  • Redis Streams for message streaming.
  • HyperLogLog for probabilistic cardinality estimation.
  • Bitmaps for bit-level analytics and feature flags.
• Messaging & Scripting:
  • Pub/Sub Messaging.
  • Lua Scripting for server-side execution.
• Concurrency: Distributed Lock implementation using IAsyncDisposable.

The library extends standard Redis capabilities with the following features:

• Complex Objects: Add, retrieve, and remove complex objects.
• Object Management: Replace objects and work with multiple items.
• Customization: Use custom serializers and optional compression.
• Messaging: Pub/Sub events.
• Advanced Operations:
  • Search keys into Redis
  • Store multiple objects with a single roundtrip
  • Get Redis Server information
  • Set operations (Add / Remove / Member)
  • Geo commands
  • Stream commands
  • Hash commands (including Hash Field Expiry)
  • Tag-based operations
• Infrastructure Support:
  • Async methods
  • Keyspace isolation
  • Support for multiple databases

HyperLogLog is a probabilistic data structure used to estimate the cardinality (unique count) of a set with minimal memory (~12 KB per key). It is ideal for high-scale scenarios like counting unique visitors or events where an approximate count is acceptable.

Key characteristics:

• Memory Efficiency: Constant memory usage regardless of the number of elements.
• Accuracy: Standard error rate of approximately 0.81%.
• Serialization: Values are processed through the configured ISerializer before being added to the structure.

Compression is applied transparently to all cached data. The library uses a decorator pattern where a CompressedSerializer wraps an ISerializer and an ICompressor.

Data Flow:

1. Write: Your Object $\rightarrow$ ISerializer (byte array) $\rightarrow$ ICompressor (compressed bytes) $\rightarrow$ Redis.
2. Read: Redis $\rightarrow$ compressed bytes $\rightarrow$ ICompressor (byte array) $\rightarrow$ ISerializer (Your Object).

This reduces Redis memory usage and network bandwidth by compressing data after serialization but before storage.

If a KeyPrefix is configured in your Redis settings, it is automatically applied to Pub/Sub channels using the underlying ChannelPrefix mechanism.

Important: Do not manually add the prefix to your channel names in your code; the library handles this automatically. For example, if KeyPrefix is set to "myapp:", publishing to "orders" will actually target the Redis channel "myapp:orders".

// Config: KeyPrefix = "myapp:"
await redis.PublishAsync("orders", message);
// Actual Redis channel: "myapp:orders"

The library follows a layered architecture designed for dependency injection and connection pooling:

1. Application Layer: Your code interacts with high-level abstractions.
2. DI Layer: ASP.NET Core DI manages the lifecycle of clients.
3. Factory Layer: IRedisClientFactory produces either a default IRedisClient or specific named instances.
4. Client Layer: IRedisClient provides access to the database.
5. Database Layer: IRedisDatabase is the primary interface for operations. It utilizes a Connection Pool Manager to manage multiple connections (using strategies like LeastLoaded or RoundRobin) to the Redis server.
6. Serialization Layer: IRedisDatabase uses an ISerializer (which can be a CompressedSerializer wrapping an inner serializer like System.Text.Json or Newtonsoft) to handle object conversion before sending data to the Redis server.

The library wraps Redis's native GeoSpatial commands.

• Data Model: Geo members are string identifiers (e.g., IDs or names). Coordinates are stored internally by Redis as sorted set scores.
• Complex Objects: Since members are strings, if you need to associate complex objects with a location, you should store those objects under a separate Redis key derived from the member name.
• Command Mapping:
  • GeoAddAsync $\rightarrow$ GEOADD (uses Redis Sorted Sets)
  • GeoSearchAsync $\rightarrow$ GEOSEARCH
  • GeoDistanceAsync $\rightarrow$ GEODIST
  • GeoPositionAsync $\rightarrow$ GEOPOS

When using Redis-based distributed locking, keep the following in mind:

• Holder Identity: The lock value acts as a holder identifier. Only the holder with the matching value can release or extend the lock.
• Automatic Values: LockAcquireAsync generates a random GUID as the lock value automatically.
• Retry Defaults: The default retry delay is 200ms with 3 retries.
• Failure Handling: LockAcquireAsync returns null (not an exception) when the lock cannot be acquired.
• Deadlock Prevention: Always set a reasonable expiry to prevent deadlocks if the holder crashes.
• Cluster Support: This is a single-instance lock implementation. For multi-instance Redis (Cluster), consider using the Redlock algorithm.

The library supports multiple serialization formats to handle complex objects in Redis. You should select the one that best fits your performance and compatibility requirements:

• System.Text.Json (Recommended)
• Newtonsoft Json.NET
• MemoryPack
• MsgPack
• Protobuf

You can also implement a Custom Serializer if the built-in options do not meet your needs.

The library manages a pool of connections. When an operation requests a connection via GetConnection(), it uses one of two strategies:

• LeastLoaded (default): Picks the connected connection with the fewest outstanding commands.
• RoundRobin: Randomly selects among connected connections.

The pool automatically skips disconnected connections and falls back gracefully when all connections are down.