v4: the 4.0 core, surface and alpha branch (tracking)

.github/actions/run-tests/action.yml

@@ -79,6 +79,33 @@ runs:
         --logger trx
         --logger "GitHubActions;summary-include-passed=false;summary-include-skipped=false"
         --results-directory ./test-results/
+        --blame-hang-timeout 10m
+        --blame-hang-dump-type none
+        /p:CI=true
+
+    # Neither of these needs a server, and between them they took about four seconds - but nothing ran
+    # them until now, so a namespace rename silently broke all 18 SER309 tests and nobody found out.
+    - name: RESPite.Tests
+      shell: bash
+      run: >-
+        dotnet test tests/RESPite.Tests/RESPite.Tests.csproj
+        --no-build
+        -c Release
+        -f net10.0
+        --logger trx
+        --logger "GitHubActions;summary-include-passed=false;summary-include-skipped=false"
+        --results-directory ./test-results/
+        /p:CI=true
+
+    - name: StackExchange.Redis.Build.Tests
+      shell: bash
+      run: >-
+        dotnet test tests/StackExchange.Redis.Build.Tests/StackExchange.Redis.Build.Tests.csproj
+        --no-build
+        -c Release
+        --logger trx
+        --logger "GitHubActions;summary-include-passed=false;summary-include-skipped=false"
+        --results-directory ./test-results/
         /p:CI=true
 
     - uses: dorny/test-reporter@v3

.github/workflows/CI.yml

@@ -4,7 +4,7 @@ run-name: "CI${{ github.event.inputs.client-libs-test-image-tag != '' && format(
 on:
   pull_request:
   push:
-    branches: [ 'main', 'v3' ]
+    branches: [ 'main', 'v3', 'v4' ]
     paths:
       - '**'
       - '!/docs/*' # Don't run workflow when files are only in the /docs directory
@@ -145,23 +145,33 @@ jobs:
           TOPOLOGY='${{ github.event.inputs.windows-topology || 'full' }}'
           echo "topology: $TOPOLOGY"
 
-          redis-server ../Basic/primary-6379.conf &
-          redis-server ../Basic/replica-6380.conf &
-          redis-server ../Basic/secure-6381.conf &
-          redis-server ../Failover/primary-6382.conf &
-          redis-server ../Failover/replica-6383.conf &
+          # Replicas load the initial sync from the socket, never from disk. These data directories
+          # sit on the Windows mount (/mnt/...), where a replica receives the RDB to a file and then
+          # fails to load it ("Failed trying to load the MASTER synchronization DB from disk"), retrying
+          # forever - so no replica on this job had ever synced. That went unnoticed while the client
+          # read replicas from CLUSTER NODES, which lists them regardless; CLUSTER SLOTS rightly leaves
+          # out a replica that has never synced, so the new core saw a cluster with no replicas.
+          LOAD="--repl-diskless-load swapdb"
+
+          redis-server ../Basic/primary-6379.conf $LOAD &
+          redis-server ../Basic/replica-6380.conf $LOAD &
+          redis-server ../Basic/secure-6381.conf $LOAD &
+          redis-server ../Failover/primary-6382.conf $LOAD &
+          redis-server ../Failover/replica-6383.conf $LOAD &
           PORTS="6379 6380 6381 6382 6383"
+          REPLICAS="6380 6383"
 
           if [ "$TOPOLOGY" = "full" ]; then
             for p in 7000 7001 7002 7003 7004 7005; do
-              redis-server "../Cluster/cluster-$p.conf" --dir ../Cluster &
+              redis-server "../Cluster/cluster-$p.conf" --dir ../Cluster $LOAD &
             done
-            redis-server ../Sentinel/redis-7010.conf &
-            redis-server ../Sentinel/redis-7011.conf &
+            redis-server ../Sentinel/redis-7010.conf $LOAD &
+            redis-server ../Sentinel/redis-7011.conf $LOAD &
             for p in 26379 26380 26381; do
               redis-server "../Sentinel/sentinel-$p.conf" --sentinel &
             done
             PORTS="$PORTS 7000 7001 7002 7003 7004 7005 7010 7011 26379 26380 26381"
+            REPLICAS="$REPLICAS 7003 7004 7005 7011"
           fi
 
           # Poll rather than `sleep 5`: on a fast machine this returns almost immediately, and on a
@@ -197,11 +207,53 @@ jobs:
             exit 1
           fi
 
+          # ...and a replica that is listening but has never synced is just as misleading, and quieter:
+          # replica-routing tests then pass or fail on what the client happens to read, not on the
+          # client. Fatal for the same reason as above.
+          unsynced=""
+          for p in $REPLICAS; do
+            synced=""
+            for _ in $(seq 1 30); do
+              if redis-cli -p "$p" INFO replication 2>/dev/null | grep -q "master_link_status:up"; then
+                synced="yes"; break
+              fi
+              sleep 1
+            done
+            if [ -n "$synced" ]; then
+              echo "replica $p synced"
+            else
+              echo "replica $p DID NOT SYNC:"
+              redis-cli -p "$p" INFO replication 2>&1 || true
+              unsynced="$unsynced $p"
+            fi
+          done
+          if [ -n "$unsynced" ]; then
+            echo "::error::replicas not synced:$unsynced"
+            exit 1
+          fi
+
+          # CLUSTER SLOTS lists a replica only once its primary has heard, by gossip, that it has an
+          # offset - a second or so after the sync above. Wait for all six nodes to be listed.
+          if [ "$TOPOLOGY" = "full" ]; then
+            listed=0
+            for _ in $(seq 1 30); do
+              listed=$(redis-cli -p 7000 CLUSTER SLOTS 2>/dev/null | grep -c '^700[0-5]$' || true)
+              [ "$listed" -ge 6 ] && break
+              sleep 1
+            done
+            echo "CLUSTER SLOTS lists $listed of 6 nodes"
+            if [ "$listed" -lt 6 ]; then
+              redis-cli -p 7000 CLUSTER NODES 2>&1 || true
+              echo "::error::CLUSTER SLOTS does not list every replica"
+              exit 1
+            fi
+          fi
+
       - name: .NET Build
         run: dotnet build Build.csproj -c Release /p:CI=true
       # The analyzer and the props that configures it reach consumers only through the package, and a
       # packaging regression is silent: no diagnostics, ever, for anybody, with a build that still succeeds.
-      # The real pack below runs only on pushes to main/v3, so check it here where PRs will see it too.
+      # The real pack below runs only on pushes to main/v3/v4, so check it here where PRs will see it too.
       - name: Verify package contents
         run: |
           $out = "${env:GITHUB_WORKSPACE}\.packcheck"
@@ -222,10 +274,14 @@ jobs:
             exit 1
           }
       - name: StackExchange.Redis.Tests
+        # A hung test otherwise holds the job until GitHub's six-hour limit, and says nothing about which
+        # test it was. --blame-hang names it (in the run's Sequence file and the log) and kills it, so the
+        # rest still report; the step timeout is the backstop if even that does not return.
+        timeout-minutes: 30
         run: |
           $exitCode = 0
           foreach ($tfm in @("net10.0", "net481")) {
-            dotnet test tests/StackExchange.Redis.Tests/StackExchange.Redis.Tests.csproj --no-build -c Release -f $tfm --logger trx --logger GitHubActions --results-directory ./test-results/ /p:CI=true
+            dotnet test tests/StackExchange.Redis.Tests/StackExchange.Redis.Tests.csproj --no-build -c Release -f $tfm --logger trx --logger GitHubActions --results-directory ./test-results/ --blame-hang-timeout 10m --blame-hang-dump-type none /p:CI=true
             if ($LASTEXITCODE -ne 0) {
               $exitCode = $LASTEXITCODE
             }

.github/workflows/release.yml

@@ -68,6 +68,8 @@ jobs:
       with:
         name: packages
         path: .nupkgs/*.nupkg
+        include-hidden-files: true # .nupkgs is a dot-folder, which upload-artifact skips by default
+        if-no-files-found: error   # a dry run that uploads nothing should fail, not pass
     - name: NuGet login (OIDC to temp API key)
       if: github.event_name == 'release'
       uses: NuGet/login@v1

.gitignore

@@ -34,3 +34,6 @@ BenchmarkDotNet.Artifacts/
 
 # local planning/design notes (not for publication)
 planning/
+
+# agent worktrees (see .claude/); these are separate checkouts, never repo content
+.claude/worktrees/

Directory.Build.props

@@ -1,4 +1,4 @@
-<Project>
+<Project>
   <PropertyGroup>
     <VersionPrefix>2.0.0</VersionPrefix>
     <Copyright>2014 - $([System.DateTime]::Now.Year) Stack Exchange, Inc.</Copyright>
@@ -10,9 +10,11 @@
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <CodeAnalysisRuleset>$(MSBuildThisFileDirectory)Shared.ruleset</CodeAnalysisRuleset>
     <MSBuildWarningsAsMessages>NETSDK1069</MSBuildWarningsAsMessages>
-    <!-- SER001/SER002/SER003/SER006/SER007/SER008/SER010 retired (vector sets, Redis 8.4/8.6/8.8/8.10 features,
-         geo-redundant failover and maintenance notifications, no longer experimental); IDs reserved, see Experiments.cs -->
-    <NoWarn>$(NoWarn);NU5105;NU1507;SER004;SER005;SER009</NoWarn>
+    <!-- SER001/SER002/SER003/SER006/SER007/SER008/SER010/SER013 retired (vector sets, Redis 8.4/8.6/8.8/8.10
+         features, geo-redundant failover, maintenance notifications, and the interpolated writer, no longer
+         experimental); IDs reserved, see Experiments.cs.
+         SER011 is deliberately absent: hand-written RespFragment is meant to be seen at every call site. -->
+    <NoWarn>$(NoWarn);NU5105;NU1507;SER004;SER005;SER009;SER012;SER014</NoWarn>
     <PackageReleaseNotes>https://github.com/StackExchange/StackExchange.Redis/releases</PackageReleaseNotes>
     <PackageProjectUrl>https://seredis.dev/</PackageProjectUrl>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>

Directory.Packages.props

@@ -44,7 +44,8 @@
     <PackageVersion Include="Nerdbank.GitVersioning" Version="3.9.50" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
     <PackageVersion Include="NSubstitute" Version="5.3.0" />
-    <PackageVersion Include="StackExchange.Redis" Version="2.13.17" />
+    <!-- the current shipped v3: what the *Baseline projects and RESPite.Benchmark (TargetVer=3) compare against -->
+    <PackageVersion Include="StackExchange.Redis" Version="3.3.1" />
     <PackageVersion Include="StackExchange.Redis.StrongName" Version="1.2.6" />
     <PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.556" />
     <PackageVersion Include="System.Collections.Immutable" Version="10.0.5" />

design/admitsim.py

@@ -0,0 +1,131 @@
+"""Single-threaded model of the v4 client cache under RespFest's Zipf stream: no Redis, no .NET, no concurrency.
+
+Written to ask whether default ~= OnFirstMiss at 64 callers came from the access stream or from parallelism: the
+stream (it reproduces 72.5% either way, with zero refusals), and through it a doorkeeper that aged only by first
+sightings. `count_all` is the fix: every miss ages the filter.
+
+Model (mirrors RespClientCache):
+  * doorkeeper: 2^20-bit Bloom filter, two probes from a 32-bit hash, cleared after 131,072 first sightings - or,
+    with count_all, 131,072 misses (sized from MaxBytes / EntryOverheadBytes = 32 MiB / 256)
+  * storage: slabs in fill order; the oldest slab is evicted whole when over budget; hits touch nothing
+  * budget: 32 MiB counting whole 1 MiB slabs plus 256 bytes per live entry
+"""
+import random
+import sys
+
+sys.path.insert(0, "/home/marc/code/RespFest")
+from harness.keyseq import zipf  # noqa: E402
+
+import struct  # noqa: E402
+
+KEYSPACE = 200_000
+SLAB = 1 << 20
+ENTRY = 1024 + 30  # reply + key, both stored in the slab
+OVERHEAD = 256
+BUDGET = 32 << 20
+BITS = 1 << 20
+CLEAR_AFTER = BITS // 8
+
+rng = random.Random(1)
+HASH = [rng.getrandbits(32) for _ in range(KEYSPACE)]  # a well-mixed hash per request
+
+
+def run(stream, n_ops, measure_from, admission, clear_after=CLEAR_AFTER, count_all=False):
+    words = bytearray(BITS // 8)
+    recorded = 0
+    live = {}  # key -> slab id
+    slabs = {}  # slab id -> list of keys stored there
+    oldest = 0
+    current = 0
+    used = 0  # bytes used in the current slab
+    slabs[0] = []
+    live_count = 0
+    hits = misses = stores = refused = 0
+
+    def seen_before(h):
+        nonlocal recorded, words
+        a = h & (BITS - 1)
+        b = ((h >> 16) | (h << 16)) & 0xFFFFFFFF & (BITS - 1)
+        if words[a >> 3] >> (a & 7) & 1 and words[b >> 3] >> (b & 7) & 1:
+            if count_all:  # age by every query, not only by first sightings
+                recorded += 1
+                if recorded >= clear_after:
+                    recorded = 0
+                    words = bytearray(BITS // 8)
+            return True
+        words[a >> 3] |= 1 << (a & 7)
+        words[b >> 3] |= 1 << (b & 7)
+        recorded += 1
+        if recorded >= clear_after:
+            recorded = 0
+            words = bytearray(BITS // 8)
+        return False
+
+    for t in range(n_ops):
+        k = stream(t)
+        measuring = t >= measure_from
+        if k in live:
+            if measuring:
+                hits += 1
+            continue
+        if measuring:
+            misses += 1
+        if admission != "first" and not seen_before(HASH[k]):
+            if measuring:
+                refused += 1
+            continue
+        # store into the current slab
+        if used + ENTRY > SLAB:
+            current += 1
+            slabs[current] = []
+            used = 0
+        slabs[current].append(k)
+        used += ENTRY
+        live[k] = current
+        live_count += 1
+        if measuring:
+            stores += 1
+        # evict oldest sealed slabs while over budget
+        while (current - oldest + 1) * SLAB + live_count * OVERHEAD > BUDGET and oldest < current:
+            for victim in slabs.pop(oldest):
+                if live.get(victim) == oldest:
+                    del live[victim]
+                    live_count -= 1
+            oldest += 1
+    total = hits + misses
+    return hits / total, stores, refused, len(live)
+
+
+def true_zipf(count, seed):
+    """Independent Zipf(0.99) draws over the keyspace: no table, so nothing replays."""
+    import bisect
+    cumulative, total = [], 0.0
+    for rank in range(1, KEYSPACE + 1):
+        total += rank ** -0.99
+        cumulative.append(total)
+    r = random.Random(seed)
+    return [min(bisect.bisect_left(cumulative, r.random() * total), KEYSPACE - 1) for _ in range(count)]
+
+
+def main():
+    seq = struct.unpack(f"<{1 << 20}I", zipf(KEYSPACE, 0.99, length=1 << 20, seed=20261010))  # the league's 1M table
+    fresh = true_zipf(13_000_000, 11)
+    k = 13_000_000
+    cases = [
+        ("true zipf, 13M", lambda t: fresh[t]),
+        ("1M table x64 callers", lambda t: seq[((t % 64) * 16384 + t // 64) % len(seq)]),
+    ]
+    policies = [
+        ("first", {}),
+        ("repeat: clear @131k new (today)", {}),
+        ("repeat: clear @131k misses", {"count_all": True}),
+        ("repeat: clear @64k misses", {"count_all": True, "clear_after": 65536}),
+        ("repeat: clear @256k misses", {"count_all": True, "clear_after": 262144}),
+    ]
+    for name, stream in cases:
+        for policy, kw in policies:
+            hit, stores, refused, size = run(stream, k, k // 3, "first" if policy == "first" else "repeat", **kw)
+            print(f"{name:22} {policy:34} hit {hit:6.1%}  stores {stores:>9,}  refused {refused:>9,}", flush=True)
+
+
+main()