v4: CountMinSketch on the SE.Redis v4 command-group surface (spike) - #577

Draft, for review of the shape rather than for merge: this is the first module (the smallest, Count-Min Sketch) migrated to the StackExchange.Redis v4 command-group surface. Built against 4.0.86-alpha.

What changes for callers

Nothing existing breaks: db.CMS(), ICmsCommands, ICmsCommandsAsync, Pipeline.Cms and Transaction.Cms keep their signatures and behaviour. The new surface sits beside them. This section is what a caller sees when they move.

Reaching the commands

// before: a method on IDatabase, returning a class
var cms = db.CMS();

// after: a property on anything with a keyspace context, returning a struct
var cms = db.CountMinSketch;           // IDatabase
var cms = batch.CountMinSketch;        // IBatch
var cms = tran.CountMinSketch;         // ITransaction
var cms = db.Context.AppendKeyPrefix("tenant:42:").CountMinSketch;   // a prefixed context

• The group is a readonly struct holding only the context. Getting it allocates nothing; take it at the call site rather than storing it.
• One accessor covers IDatabase, IBatch, ITransaction and RespDatabaseContext, so a prefixed, blocking or cache-adjusted context reaches the same commands.
• db.CountMinSketch is a C# 14 extension property. On an older language version (the .NET 8 SDK defaults to C# 12), add using NRedisStack.Downlevel; and write db.CountMinSketch() instead. Do not import that namespace on C# 14, where both in scope is CS9339.

Method shape

Every command is asynchronous and follows one pattern:

ValueTask<TResult> XxxAsync(/* command arguments */,
    CommandFlags flags = CommandFlags.None,
    CancellationToken cancellationToken = default)

• ValueTask, not Task. A result already known (a client-side cache hit) completes without allocating. Await it once; do not store it to await twice. db.AsTask(...) gives a Task that carries the database's AsyncState and marks faults observed; prefer it over .AsTask() if you need a Task.
• No synchronous twins. To block, make the context blocking once and read the result: db.Context.Blocking().CountMinSketch.InfoAsync(key).GetAwaiter().GetResult(). Every send through that context completes on the calling thread; no thread-pool hop. A batch or transaction cannot block (nothing is sent until it executes).
• CommandFlags on every call. Fire-and-forget, replica preference, NoClientCache, and retry categories all work as on the core API. Each command already declares its own retry category; a category you pass wins.
• CancellationToken on every call. It cancels the wait: a command not yet written is never sent; one already written still runs on the server and its reply is discarded.

Return types

using var counts = await db.CountMinSketch.QueryAsync(key, ["foo", "bar"]);
long foo = counts.Span[0];          // or counts.ToArray() if you need to keep it

A ReadOnlyLease<T> is a pooled buffer, valid until disposed. From a client-side cache hit it is a read-only view over the shared entry; disposing it does not affect other readers.

Arguments

• Keys are RedisKey. MergeAsync(RedisKey destination, ReadOnlySpan<RedisKey> sources, ReadOnlySpan<long> weights = default, ...). The legacy Merge took these as RedisValue, so cluster routing and key prefixing never saw them; that is fixed in both surfaces (the legacy proxy converts). The legacy numKeys parameter is gone from the new surface and validated against the source count on the old one.
• Spans, not arrays. QueryAsync(key, ReadOnlySpan<RedisValue>) and IncrByAsync(key, ReadOnlySpan<(RedisValue Item, long Increment)>). Arrays and collection expressions convert implicitly: QueryAsync(key, ["foo", "bar"]), IncrByAsync(key, [("foo", 5), ("bar", 15)]). The legacy Tuple<RedisValue, long>[] form stays on db.CMS().
• Empty input short-circuits. QueryAsync(key, []) and IncrByAsync(key, []) return an empty lease with no round trip (the key need not exist). MergeAsync with no sources, or with weights that do not match the sources one for one, throws ArgumentException before sending.

Client-side caching

QUERY and INFO are declared read-only, so with ConfigurationOptions.ClientCache set (RESP3) they are served from the local cache and invalidated by any INCRBY, MERGE or DEL on the key, including from other clients. Opt a call out with CommandFlags.NoClientCache, or a context with WithoutCache() / WithMaxCacheAge(...). See docs/ClientSideCaching.md in StackExchange.Redis.

Deprecated

CmsCommandBuilder and its SerializedCommand output are [Obsolete]. They still work, but the new surface has no builder layer, and every module will follow.

What the migration looks like

Files worth reading in order:

1. src/NRedisStack/CountMinSketch/CountMinSketch.cs - the struct and the one generic accessor.
2. src/NRedisStack/CountMinSketch/CountMinSketch.Methods.cs - the six commands. Four are one interpolated string; INCRBY (multi) and MERGE use Compose; WEIGHTS is a [Resp] generated fragment (the generator ships in the SE.Redis package and runs here unchanged).
3. CmsCommands.cs / CmsCommandsAsync.cs - the legacy proxies. One line each; the group is resolved once in the constructor.
4. tests/.../CountMinSketchGroupTests.cs - new surface, RESP2+RESP3, standalone+cluster, prefixed context, batch.
5. tests/.../CountMinSketchCachingTests.cs - client-side caching over a module command: read-only opt-in is cached, cache key covers value args, local and remote invalidation both reach a module key (RedisBloom does signal key modification).

Decisions taken

• Accessor spelled out (CountMinSketch, not Cms).
• New surface is ValueTask-only, no sync twins (results may complete synchronously from the client-side cache). Legacy API keeps Task<T> / sync shapes untouched.
• InitByDim/InitByProb/Merge on the new surface return ValueTask, not a bool that could only be true.
• CmsCommandBuilder is [Obsolete]. The builder surface has no v4 equivalent; expect this across all modules.
• Library-name announcement is unchanged (still via the legacy proxies). SE.Redis's intended mechanism is db.Context.Multiplexer?.AddLibraryNameSuffix(...), but it is a suffix with no override or opt-out, where today's logic replaces the name and offers both; deciding that is separate.

Behaviour changes in the legacy surface

• Merge: destination/sources were RedisValue, so cluster routing never saw a key. Now converted to RedisKey; numKeys is validated against the source count rather than passed through.

Found along the way (fed back to SE.Redis; all address

• Needed a public sync path → Blocking().
• Needed a public ValueTask→Task bridge that carries AsyncState and marks faults observed → db.AsTask(...). - Needed RespDatabaseContext to be an `IRespKeyspaceTar prefixed context → done.
• Still internal, not needed yet: RespHandlers.Inbuilt<T>. No non-nullable numeric AppendFormatted overloads (deliberate; only visible in Compose loops).
• Test-side: xunit v3's span Assert.Equal overloads bind to collection expressions, so Assert.Equal([1,2], await ...) is CS4007. Hoist into
  a typed local.

Test run

dotnet test -f net8.0 with REDIS_VERSION=8.10.0 againuster: CMS legacy, group, caching, pipeline, transactionand WithRetry tests all pass (109 passed, 6 skipped - the skips are pre-existing ExampleTests/TestModulesPipeline). Library builds with 0 warnings on all five TFMs.

Commits

• cb8cb46 Move to StackExchange.Redis 4.0.86-alpha
• 3bae19c CountMinSketch: first module on the v4 command-group surface
• af86fed CountMinSketch proxies: resolve the group onc

Not in scope

Any other module. Next candidate by the same recipe: TopK