RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
Migrate cache backend from Valkey 8 to apache/kvrocks:2.16.0 (#19374)
xugangqianga36615c6fab2
diff --git a/.github/workflows/kvrocks-parity.yml b/.github/workflows/kvrocks-parity.ymlnew file mode 100644index 0000000000..8c8c3a4fd0--- /dev/null+++ b/.github/workflows/kvrocks-parity.yml@@ -0,0 +1,67 @@+name: Kvrocks Parity++# Regression fence for the Valkey -> apache/kvrocks:2.16.0 migration. Runs the+# //go:build integration parity tests (internal/engine/redis, internal/agent/canvas)+# against a real Kvrocks instance. These tests are NOT part of the default+# `go test` run, so this workflow is what actually executes them in CI.+on:+ push:+ branches: [main]+ pull_request:+ workflow_dispatch:++# Only one in-flight run per ref; cancel superseded runs on PR pushes.+concurrency:+ group: kvrocks-parity-${{ github.ref }}+ cancel-in-progress: true++jobs:+ kvrocks-parity:+ runs-on: ubuntu-latest+ env:+ # CI=true makes the parity tests hard-fail (not skip) if Kvrocks is absent.+ CI: "true"+ KV_PASSWORD: ci-test-pass+ steps:+ - uses: actions/checkout@v4++ - uses: actions/setup-go@v5+ with:+ go-version: "1.26"+ cache: true++ # Pinned to 2.16.0+ on purpose (TTL contract + no maxmemory). Reuse the repo+ # entrypoint script so this job also exercises the deployment's conf renderer.+ # `-e REDIS_PASSWORD` forwards the password into the container so the+ # entrypoint can render requirepass; without it Kvrocks starts open and the+ # parity tests fail to AUTH.+ - name: Start Kvrocks+ run: |+ docker run -d --name kvrocks -p 6379:6379 -e REDIS_PASSWORD \+ -v "${{ github.workspace }}/docker/kvrocks-entrypoint.sh:/etc/kvrocks/entrypoint.sh:ro" \+ --user 0:0 --entrypoint /bin/sh apache/kvrocks:2.16.0 -c "/etc/kvrocks/entrypoint.sh"+ env:+ REDIS_PASSWORD: ci-test-pass++ - name: Wait for Kvrocks+ env:+ REDIS_PASSWORD: ci-test-pass+ run: |+ for i in $(seq 1 30); do+ if docker exec kvrocks redis-cli -a "${REDIS_PASSWORD}" ping 2>/dev/null | grep -q PONG; then+ echo "Kvrocks ready"; break+ fi+ sleep 1+ done++ - name: Run parity tests+ run: |+ CGO_ENABLED=0 go test -tags integration -count=1 -timeout 300s \+ ./internal/engine/redis/... ./internal/agent/canvas/...+ env:+ KV_ADDR: "localhost:6379"+ KV_PASSWORD: ci-test-pass++ - name: Stop Kvrocks+ if: always()+ run: docker rm -f kvrocksdiff --git a/docker/docker-compose-base.yml b/docker/docker-compose-base.ymlindex 751451035b..5dce3477c1 100644--- a/docker/docker-compose-base.yml+++ b/docker/docker-compose-base.yml@@ -267,7 +267,9 @@ services:retries: 120redis:- # swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/valkey/valkey:8+ # Valkey 8 is the cache/queue backend for the Python services. The Go+ # services use a separate `kvrocks` service (defined below) so the Python+ # path is left unchanged by the Valkey -> apache/kvrocks migration.image: valkey/valkey:8command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}", "--maxmemory", "128mb", "--maxmemory-policy", "volatile-lru"]env_file: .env@@ -284,6 +286,42 @@ services:timeout: 10sretries: 120+ kvrocks:+ # Apache Kvrocks: a RocksDB-backed, Redis-protocol-compatible store used+ # ONLY by the Go services (ragflow-cpu / ragflow-gpu), which override+ # REDIS_HOST=kvrocks in docker-compose-go.yml. The Python services keep+ # using the `redis` (Valkey) service above, so this is a dual-backend setup.+ # Pinned to 2.16.0+ on purpose (see docker/kvrocks-entrypoint.sh): older+ # tags such as kvrocks/kvrocks:latest (== 2.0.6) carry a TTL contract bug+ # that breaks the RunTracker CAS lease, and they reject the Redis-style+ # maxmemory/maxmemory-policy settings.+ image: apache/kvrocks:2.16.0+ # Kvrocks' config file does not expand ${ENV} and its CLI rejects+ # `--requirepass` as a flag, so the entrypoint renders the config (including+ # the password from REDIS_PASSWORD) at startup. `user: "0"` lets it write the+ # config and the RocksDB data dir regardless of the mounted volume ownership.+ entrypoint: ["/bin/sh", "/etc/kvrocks/entrypoint.sh"]+ user: "0:0"+ env_file: .env+ # No host port publish: the Go services reach Kvrocks over the internal+ # docker network at `kvrocks:6379`. Gated to the Go stack profile so the+ # Python-only stack does not spin up an unused container.+ profiles:+ - ragflow-go+ volumes:+ - kvrocks_data:/var/lib/kvrocks+ - ./kvrocks-entrypoint.sh:/etc/kvrocks/entrypoint.sh:ro+ networks:+ - ragflow+ restart: unless-stopped+ healthcheck:+ # The Kvrocks image ships redis-cli and requirepass is enforced, so ping+ # with the password. (The image has no nc, so a raw-tcp probe is wrong.)+ test: ["CMD", "redis-cli", "-a", "${REDIS_PASSWORD}", "ping"]+ interval: 10s+ timeout: 10s+ retries: 120+jaeger:profiles:- jaeger@@ -426,6 +464,8 @@ volumes:driver: localredis_data:driver: local+ kvrocks_data:+ driver: localtei_data:driver: localkibana_data:diff --git a/docker/docker-compose-go.yml b/docker/docker-compose-go.ymlindex aa8915c847..4ad60768c5 100644--- a/docker/docker-compose-go.yml+++ b/docker/docker-compose-go.yml@@ -69,6 +69,10 @@ services:- ./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template- ./entrypoint-go.sh:/ragflow/entrypoint.shenv_file: .env-go+ # Route the Go services' cache/queue backend to the separate Kvrocks service+ # (overriding REDIS_HOST=redis from .env-go). The Python services keep Valkey.+ environment:+ - REDIS_HOST=kvrocksnetworks:- ragflowrestart: unless-stopped@@ -125,6 +129,10 @@ services:- ./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template- ./entrypoint.sh:/ragflow/entrypoint.shenv_file: .env-go+ # Route the Go services' cache/queue backend to the separate Kvrocks service+ # (overriding REDIS_HOST=redis from .env-go). The Python services keep Valkey.+ environment:+ - REDIS_HOST=kvrocksnetworks:- ragflowrestart: unless-stoppeddiff --git a/docker/kvrocks-entrypoint.sh b/docker/kvrocks-entrypoint.shnew file mode 100755index 0000000000..56353d4526--- /dev/null+++ b/docker/kvrocks-entrypoint.sh@@ -0,0 +1,38 @@+#!/bin/sh+# Kvrocks entrypoint for the RAGFlow cache service.+#+# Kvrocks 2.16.0 does NOT support ${ENV} expansion inside its config file and+# rejects `--requirepass` as a CLI flag (gflags intercepts the config key before+# Kvrocks' own handler runs). To preserve the password-based auth from the+# previous Valkey deployment without committing the secret, we render the config+# from the REDIS_PASSWORD environment variable (injected via the compose+# env_file) at container start.+#+# This service is configured with `user: "0"` so the entrypoint can write the+# generated config and the RocksDB data directory regardless of the mounted+# volume's ownership; kvrocks then runs as root. (The upstream image normally+# drops to an unprivileged user via its own entrypoint, which we override here.)+#+# Config keys verified against apache/kvrocks:2.16.0:+# bind, port, dir, requirepass+# Intentionally omitted (invalid in kvrocks 2.16.0): maxmemory, maxmemory-policy.+set -eu++# REDIS_PASSWORD is mandatory: the previous Valkey deployment always required it,+# and an unauthenticated cache/queue backend is a security exposure. Refuse to+# start rather than silently run open.+: "${REDIS_PASSWORD:?REDIS_PASSWORD must be set (inject via compose env_file or -e)}"++# KVROCKS_DIR overrides the RocksDB data/config dir (defaults to the compose+# mount point). Test harnesses use it to redirect writes to a temp dir.+KVROCKS_DIR="${KVROCKS_DIR:-/var/lib/kvrocks}"+mkdir -p "$KVROCKS_DIR"++{+ echo "bind 0.0.0.0"+ echo "port 6379"+ echo "dir $KVROCKS_DIR"+ printf 'requirepass %s\n' "$REDIS_PASSWORD"+} > "$KVROCKS_DIR/kvrocks.conf"++exec kvrocks -c "$KVROCKS_DIR/kvrocks.conf" --dir "$KVROCKS_DIR"diff --git a/helm/values.yaml b/helm/values.yamlindex e5b5dec0f6..353a8f25b6 100644--- a/helm/values.yaml+++ b/helm/values.yaml@@ -222,6 +222,12 @@ mysql:service:type: ClusterIP+# NOTE: The docker-compose deployment migrated from Valkey 8 to+# apache/kvrocks:2.16.0 (see docker/kvrocks-entrypoint.sh). This Helm/Kubernetes+# path is intentionally LEFT on Valkey: the template invokes `redis-server`+# directly with Valkey-specific flags (helm/templates/redis.yaml), which Kvrocks+# rejects. A Kvrocks-on-K8s migration is a separate workstream and must rewrite+# the redis template, not just swap this image.redis:enabled: trueimage:diff --git a/internal/agent/canvas/kvrocks_runtracker_parity_test.go b/internal/agent/canvas/kvrocks_runtracker_parity_test.gonew file mode 100644index 0000000000..89fe4d68b8--- /dev/null+++ b/internal/agent/canvas/kvrocks_runtracker_parity_test.go@@ -0,0 +1,225 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++//go:build integration++// Package canvas holds the RunTracker CAS regression guard for the+// Valkey→Kvrocks migration. RunTracker relies on four inline Lua scripts that+// use HGET/HSET/DEL/EXISTS/SET(PX)/PEXPIRE to implement a distributed+// active-run lease. These scripts must behave identically on Kvrocks 2.16.0,+// otherwise the agent runtime could lose its single-owner guarantee or fail to+// cancel/stale-clean runs. This file drives the real RunTracker against a live+// apache/kvrocks:2.16.0 and asserts the lease semantics.+//+// Run (KV_ADDR/KV_PASSWORD mirror the redis parity test):+//+// KV_ADDR=localhost:6379 KV_PASSWORD=<pw> bash build.sh --test-integration ./internal/agent/canvas/...+package canvas++import (+ "os"+ "testing"+ "time"++ "github.com/redis/go-redis/v9"+)++func newKVRunTracker(t *testing.T) (*RunTracker, *redis.Client) {+ t.Helper()+ addr := os.Getenv("KV_ADDR")+ if addr == "" {+ if os.Getenv("CI") != "" {+ t.Fatal("KV_ADDR not set: RunTracker Kvrocks parity tests require a live apache/kvrocks:2.16.0 in CI")+ }+ t.Skip("KV_ADDR not set; skipping RunTracker Kvrocks parity test")+ }+ client := redis.NewClient(&redis.Options{+ Addr: addr,+ Password: os.Getenv("KV_PASSWORD"),+ })+ t.Cleanup(func() { _ = client.Close() })+ if err := client.Ping(t.Context()).Err(); err != nil {+ t.Fatalf("kvrocks ping %s: %v", addr, err)+ }+ return NewRunTrackerWithClient(client, 30*time.Second), client+}++// TestRunTrackerKvrocksCAS walks every RunTracker Lua script against Kvrocks+// and asserts the single-owner lease contract holds.+func TestRunTrackerKvrocksCAS(t *testing.T) {+ rt, client := newKVRunTracker(t)+ ctx := t.Context()+ const (+ userID = "u1"+ canvasID = "c1"+ runA = "run-a"+ runB = "run-b"+ tokenA = "tok-a"+ tokenB = "tok-b"+ wrongTok = "tok-z"+ sessionID = "kvp-session-1"+ )++ cleanup := func() {+ client.Del(ctx, activeSessionKey(sessionID), cancelKey(sessionID))+ }+ t.Cleanup(cleanup)++ t.Run("RegisterExclusivity", func(t *testing.T) {+ cleanup()+ ok, err := rt.RegisterActiveSession(ctx, ActiveSession{+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,+ })+ if err != nil {+ t.Fatalf("register A: %v", err)+ }+ if !ok {+ t.Fatal("register A returned false, want true (first owner)")+ }+ got, err := rt.GetActiveSession(ctx, sessionID)+ if err != nil {+ t.Fatalf("get A: %v", err)+ }+ if got == nil || got.RunID != runA || got.Token != tokenA {+ t.Fatalf("get A = %+v, want RunID=run-a Token=tok-a", got)+ }+ // A second, different owner must be rejected while A holds the lease.+ ok, err = rt.RegisterActiveSession(ctx, ActiveSession{+ SessionID: sessionID, Token: tokenB, UserID: userID, CanvasID: canvasID, RunID: runB,+ })+ if err != nil {+ t.Fatalf("register B: %v", err)+ }+ if ok {+ t.Fatal("register B returned true, want false (lease already owned by A)")+ }+ got, _ = rt.GetActiveSession(ctx, sessionID)+ if got.RunID != runA {+ t.Fatalf("after rejected B, active RunID = %s, want run-a", got.RunID)+ }+ })++ t.Run("ReleaseWrongTokenKeepsLease", func(t *testing.T) {+ cleanup()+ if ok, _ := rt.RegisterActiveSession(ctx, ActiveSession{+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,+ }); !ok {+ t.Fatal("register A failed")+ }+ ok, err := rt.ReleaseActiveSession(ctx, sessionID, wrongTok)+ if err != nil {+ t.Fatalf("release wrong: %v", err)+ }+ if ok {+ t.Fatal("release with wrong token succeeded, want false")+ }+ if got, _ := rt.GetActiveSession(ctx, sessionID); got == nil {+ t.Fatal("lease lost after wrong-token release, want retained")+ }+ })++ t.Run("ReleaseThenReRegister", func(t *testing.T) {+ cleanup()+ if ok, _ := rt.RegisterActiveSession(ctx, ActiveSession{+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,+ }); !ok {+ t.Fatal("register A failed")+ }+ ok, err := rt.ReleaseActiveSession(ctx, sessionID, tokenA)+ if err != nil {+ t.Fatalf("release A: %v", err)+ }+ if !ok {+ t.Fatal("release A returned false, want true")+ }+ // After release, a new owner may take over.+ ok, err = rt.RegisterActiveSession(ctx, ActiveSession{+ SessionID: sessionID, Token: tokenB, UserID: userID, CanvasID: canvasID, RunID: runB,+ })+ if err != nil {+ t.Fatalf("register B after release: %v", err)+ }+ if !ok {+ t.Fatal("register B after release returned false, want true")+ }+ got, _ := rt.GetActiveSession(ctx, sessionID)+ if got.RunID != runB || got.Token != tokenB {+ t.Fatalf("after re-register, active = %+v, want RunID=run-b Token=tok-b", got)+ }+ })++ t.Run("RefreshLease", func(t *testing.T) {+ cleanup()+ if ok, _ := rt.RegisterActiveSession(ctx, ActiveSession{+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,+ }); !ok {+ t.Fatal("register A failed")+ }+ ok, err := rt.RefreshActiveSession(ctx, sessionID, tokenA)+ if err != nil {+ t.Fatalf("refresh A: %v", err)+ }+ if !ok {+ t.Fatal("refresh with correct token returned false, want true")+ }+ ok, err = rt.RefreshActiveSession(ctx, sessionID, wrongTok)+ if err != nil {+ t.Fatalf("refresh wrong: %v", err)+ }+ if ok {+ t.Fatal("refresh with wrong token returned true, want false")+ }+ })++ t.Run("CancelMarker", func(t *testing.T) {+ cleanup()+ if ok, _ := rt.RegisterActiveSession(ctx, ActiveSession{+ SessionID: sessionID, Token: tokenA, UserID: userID, CanvasID: canvasID, RunID: runA,+ }); !ok {+ t.Fatal("register A failed")+ }+ // Wrong token must not publish a cancel marker.+ ok, err := rt.RequestCancelActiveSession(ctx, sessionID, wrongTok)+ if err != nil {+ t.Fatalf("cancel wrong: %v", err)+ }+ if ok {+ t.Fatal("cancel with wrong token returned true, want false")+ }+ if n, _ := client.Exists(ctx, cancelKey(sessionID)).Result(); n != 0 {+ t.Fatal("cancel marker set by wrong token, want absent")+ }+ // Correct token publishes a PX-scoped cancel marker.+ ok, err = rt.RequestCancelActiveSession(ctx, sessionID, tokenA)+ if err != nil {+ t.Fatalf("cancel A: %v", err)+ }+ if !ok {+ t.Fatal("cancel with correct token returned false, want true")+ }+ if n, _ := client.Exists(ctx, cancelKey(sessionID)).Result(); n != 1 {+ t.Fatal("cancel marker not present after correct cancel")+ }+ ttl, err := client.TTL(ctx, cancelKey(sessionID)).Result()+ if err != nil {+ t.Fatalf("cancel marker TTL: %v", err)+ }+ // RequestCancelTTL is 24h; the marker must carry a positive expiry.+ if ttl <= 0 {+ t.Fatalf("cancel marker TTL = %v, want > 0", ttl)+ }+ })+}diff --git a/internal/engine/redis/kvrocks_config_test.go b/internal/engine/redis/kvrocks_config_test.gonew file mode 100644index 0000000000..278c68bfd5--- /dev/null+++ b/internal/engine/redis/kvrocks_config_test.go@@ -0,0 +1,84 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++// Package redis holds deployment-config regression guards for the+// Valkey->Kvrocks migration. These are plain unit tests (no external service):+// they assert that the deployment artifacts (CI workflow, compose file) encode+// the required fixes so a future edit cannot silently regress the migration.+package redis++import (+ "os"+ "path/filepath"+ "runtime"+ "strings"+ "testing"+)++// repoRoot walks up from this source file to the module root (go.mod).+func repoRoot(t *testing.T) string {+ t.Helper()+ _, file, _, ok := runtime.Caller(0)+ if !ok {+ t.Fatal("runtime.Caller failed")+ }+ dir := filepath.Dir(file)+ for {+ if _, err := os.Stat(filepath.Join(dir, "go.mod")); err == nil {+ return dir+ }+ parent := filepath.Dir(dir)+ if parent == dir {+ t.Fatal("repo root (go.mod) not found")+ }+ dir = parent+ }+}++func readFile(t *testing.T, path string) string {+ t.Helper()+ b, err := os.ReadFile(path)+ if err != nil {+ t.Fatalf("read %s: %v", path, err)+ }+ return string(b)+}++// TestKvrocksDeploymentConfig guards the deployment artifacts that the parity+// integration tests cannot reach on their own: the CI workflow must forward the+// password into the container, and the compose healthcheck must authenticate+// now that requirepass is enforced.+func TestKvrocksDeploymentConfig(t *testing.T) {+ root := repoRoot(t)++ t.Run("WorkflowForwardsRedisPassword", func(t *testing.T) {+ wf := readFile(t, filepath.Join(root, ".github/workflows/kvrocks-parity.yml"))+ if !strings.Contains(wf, "-e REDIS_PASSWORD") {+ t.Fatal("kvrocks-parity.yml: the docker run must forward REDIS_PASSWORD into the container (-e REDIS_PASSWORD); without it Kvrocks starts unauthenticated and the parity tests fail to AUTH")+ }+ })++ t.Run("ComposeHealthcheckAuthenticates", func(t *testing.T) {+ compose := readFile(t, filepath.Join(root, "docker/docker-compose-base.yml"))+ // requirepass is enforced, so the healthcheck must authenticate. The+ // Kvrocks image ships redis-cli (but not nc), so the probe is+ // `redis-cli -a ${REDIS_PASSWORD} ping`. A bare PING would be rejected+ // and mark the service permanently unhealthy.+ if !strings.Contains(compose, "redis-cli") || !strings.Contains(compose, "${REDIS_PASSWORD}") {+ t.Fatal("docker-compose redis healthcheck must use `redis-cli -a ${REDIS_PASSWORD} ping` (the Kvrocks image has no nc); a bare PING fails now that requirepass is enforced")+ }+ })+}diff --git a/internal/engine/redis/kvrocks_deploy_test.go b/internal/engine/redis/kvrocks_deploy_test.gonew file mode 100644index 0000000000..8fc22224c2--- /dev/null+++ b/internal/engine/redis/kvrocks_deploy_test.go@@ -0,0 +1,110 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++//go:build integration++package redis++import (+ "os"+ "os/exec"+ "path/filepath"+ "strings"+ "testing"++ "github.com/redis/go-redis/v9"+)++// TestKvrocksEntrypointRequiresPassword drives the real entrypoint script with a+// stub `kvrocks` on PATH so we can assert its pre-exec behavior without a real+// Kvrocks binary. It guards Improvement 1: the entrypoint must refuse to start+// without REDIS_PASSWORD (the previous Valkey deployment always required it) and+// must render requirepass from it.+func TestKvrocksEntrypointRequiresPassword(t *testing.T) {+ root := repoRoot(t)+ ep := filepath.Join(root, "docker/kvrocks-entrypoint.sh")+ if _, err := os.Stat(ep); err != nil {+ t.Fatalf("entrypoint not found: %v", err)+ }++ // runEntrypoint executes the entrypoint with a stub `kvrocks` on PATH and a+ // temp KVROCKS_DIR, injecting (or omitting) REDIS_PASSWORD.+ runEntrypoint := func(t *testing.T, password string) error {+ t.Helper()+ dir := t.TempDir()+ stub := filepath.Join(dir, "kvrocks")+ if err := os.WriteFile(stub, []byte("#!/bin/sh\n"), 0o755); err != nil {+ t.Fatal(err)+ }+ cmd := exec.Command("sh", ep)+ env := []string{+ "PATH=" + dir + ":" + os.Getenv("PATH"),+ "KVROCKS_DIR=" + dir,+ "HOME=" + dir,+ }+ if password != "" {+ env = append(env, "REDIS_PASSWORD="+password)+ }+ cmd.Env = env+ return cmd.Run()+ }++ t.Run("MissingPasswordFails", func(t *testing.T) {+ if err := runEntrypoint(t, ""); err == nil {+ t.Fatal("entrypoint should fail (non-zero) when REDIS_PASSWORD is unset")+ }+ })++ t.Run("RendersRequirepass", func(t *testing.T) {+ dir := t.TempDir()+ stub := filepath.Join(dir, "kvrocks")+ if err := os.WriteFile(stub, []byte("#!/bin/sh\n"), 0o755); err != nil {+ t.Fatal(err)+ }+ cmd := exec.Command("sh", ep)+ cmd.Env = []string{+ "PATH=" + dir + ":" + os.Getenv("PATH"),+ "KVROCKS_DIR=" + dir,+ "HOME=" + dir,+ "REDIS_PASSWORD=ci-test-pass",+ }+ if err := cmd.Run(); err != nil {+ t.Fatalf("entrypoint failed with password set: %v", err)+ }+ conf, err := os.ReadFile(filepath.Join(dir, "kvrocks.conf"))+ if err != nil {+ t.Fatalf("read conf: %v", err)+ }+ if !strings.Contains(string(conf), "requirepass ci-test-pass") {+ t.Fatalf("conf missing requirepass: %q", string(conf))+ }+ })+}++// TestKvrocksRequirepassEnforced asserts that the live Kvrocks enforces+// requirepass: a client without a password cannot PING. This is the runtime+// contract that Blocker A (workflow must forward -e REDIS_PASSWORD) and+// Improvement 1 (entrypoint requires the password) both produce.+func TestKvrocksRequirepassEnforced(t *testing.T) {+ _ = newKVClient(t) // ensures a live, password-protected Kvrocks+ ctx := t.Context()+ addr := os.Getenv("KV_ADDR")+ noAuth := redis.NewClient(&redis.Options{Addr: addr})+ defer func() { _ = noAuth.Close() }()+ if err := noAuth.Ping(ctx).Err(); err == nil {+ t.Fatal("PING without password succeeded; requirepass not enforced")+ }+}diff --git a/internal/engine/redis/kvrocks_parity_test.go b/internal/engine/redis/kvrocks_parity_test.gonew file mode 100644index 0000000000..ee640698c6--- /dev/null+++ b/internal/engine/redis/kvrocks_parity_test.go@@ -0,0 +1,371 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++//go:build integration++// Package redis holds the regression guard for the Valkey→Kvrocks migration.+// These tests drive the real application Client (internal/engine/redis) against+// a live apache/kvrocks:2.16.0 instance and assert that every command family+// the codebase relies on behaves compatibly with Redis/Valkey. They are the+// "no regression" guard: if a future Kvrocks bump or config change breaks any+// contract the app depends on, these tests turn red.+//+// Run (mirrors the deployment: the entrypoint renders the config, including the+// password from REDIS_PASSWORD, at startup):+//+// docker run -d -p 6379:6379 \+// -v $(pwd)/docker/kvrocks-entrypoint.sh:/etc/kvrocks/entrypoint.sh:ro \+// -e REDIS_PASSWORD=<pw> --user 0:0 --entrypoint /bin/sh \+// apache/kvrocks:2.16.0 -c "/etc/kvrocks/entrypoint.sh"+// KV_ADDR=localhost:6379 KV_PASSWORD=<pw> bash build.sh --test-integration ./internal/engine/redis/...+//+// Without KV_ADDR the test skips locally for convenience, but fails hard (CI=true)+// so a misconfigured CI job never turns green without a live Kvrocks.+package redis++import (+ "os"+ "testing"+ "time"++ "github.com/google/uuid"+ "github.com/redis/go-redis/v9"+)++// newKVClient wires a Client against a live Kvrocks.+//+// Guard policy: the parity tests are a regression fence, so a missing backend+// must be loud, not silent. KV_ADDR unset in CI (CI=true) is a misconfigured+// job and fails hard; unset outside CI simply skips (local convenience). A set+// but unreachable KV_ADDR always fails (the Ping below), so a CI run that forgot+// to start Kvrocks can never pass green.+func newKVClient(t *testing.T) *Client {+ t.Helper()+ addr := os.Getenv("KV_ADDR")+ if addr == "" {+ if os.Getenv("CI") != "" {+ t.Fatal("KV_ADDR not set: Kvrocks parity tests require a live apache/kvrocks:2.16.0 in CI")+ }+ t.Skip("KV_ADDR not set; skipping Kvrocks parity test (needs apache/kvrocks:2.16.0)")+ }+ c := &Client{+ client: redis.NewClient(&redis.Options{+ Addr: addr,+ Password: os.Getenv("KV_PASSWORD"),+ }),+ luaDeleteIfEqual: redis.NewScript(luaDeleteIfEqualScript),+ luaTokenBucket: redis.NewScript(luaTokenBucketScript),+ }+ t.Cleanup(func() { _ = c.client.Close() })+ if err := c.client.Ping(t.Context()).Err(); err != nil {+ t.Fatalf("kvrocks ping %s: %v", addr, err)+ }+ return c+}++// TestKvrocksParity exercises the full command surface the application uses.+// It is one test with subtests so a single backend connection is reused.+func TestKvrocksParity(t *testing.T) {+ c := newKVClient(t)+ ctx := t.Context()+ // One-shot unique prefix: Kvrocks data persists across test processes, so+ // a fresh prefix each run prevents cross-run key collisions.+ prefix := "kvp:" + uuid.NewString() + ":"++ t.Run("String", func(t *testing.T) {+ k := prefix + "str"+ if !c.Set(ctx, k, "v1", time.Minute) {+ t.Fatal("Set failed")+ }+ if v, _ := c.Get(ctx, k); v != "v1" {+ t.Fatalf("Get = %q, want v1", v)+ }+ if ok, _ := c.Exist(ctx, k); !ok {+ t.Fatal("Exist = false, want true")+ }+ // SetNX must not overwrite an existing key.+ if c.SetNX(ctx, k, "v2", time.Minute) {+ t.Fatal("SetNX overwrote existing key")+ }+ if v, _ := c.Get(ctx, k); v != "v1" {+ t.Fatalf("SetNX side effect: Get = %q, want v1", v)+ }+ if n, _ := c.IncrBy(ctx, k+"-c", 5); n != 5 {+ t.Fatalf("IncrBy = %d, want 5", n)+ }+ if n, _ := c.IncrBy(ctx, k+"-c", 3); n != 8 {+ t.Fatalf("IncrBy = %d, want 8", n)+ }+ if n, _ := c.DecrBy(ctx, k+"-c", 2); n != 6 {+ t.Fatalf("DecrBy = %d, want 6", n)+ }+ if !c.Expire(ctx, k, 10*time.Second) {+ t.Fatal("Expire failed")+ }+ if tt := c.TTL(ctx, k); tt <= 0 || tt > 10*time.Second {+ t.Fatalf("TTL = %v, want (0,10s]", tt)+ }+ if !c.Delete(ctx, k) {+ t.Fatal("Delete failed")+ }+ if ok, _ := c.Exist(ctx, k); ok {+ t.Fatal("Exist = true after Delete, want false")+ }+ })++ t.Run("Hash", func(t *testing.T) {+ k := prefix + "hash"+ c.client.Del(ctx, k)+ if err := c.client.HSet(ctx, k, map[string]any{+ "a": "1", "b": "2",+ }).Err(); err != nil {+ t.Fatalf("HSet: %v", err)+ }+ got, err := c.client.HGetAll(ctx, k).Result()+ if err != nil {+ t.Fatalf("HGetAll: %v", err)+ }+ if got["a"] != "1" || got["b"] != "2" {+ t.Fatalf("HGetAll = %v, want a=1 b=2", got)+ }+ // TokenBucket Lua exercises HMGET/HMSET/EXPIRE inside Kvrocks.+ tb := &TokenBucket{client: c, key: k + "-tb", capacity: 2, rate: 0.1}+ if ok, _ := tb.Allow(ctx, 1); !ok {+ t.Fatal("TokenBucket first call denied, want allowed")+ }+ if ok, _ := tb.Allow(ctx, 1); !ok {+ t.Fatal("TokenBucket second call denied, want allowed")+ }+ if ok, _ := tb.Allow(ctx, 1); ok {+ t.Fatal("TokenBucket third call allowed, want denied (bucket exhausted)")+ }+ })++ t.Run("Set", func(t *testing.T) {+ k := prefix + "set"+ c.client.Del(ctx, k)+ if !c.SAdd(ctx, k, "m1") {+ t.Fatal("SAdd m1 failed")+ }+ if !c.SAdd(ctx, k, "m2") {+ t.Fatal("SAdd m2 failed")+ }+ if !c.SIsMember(ctx, k, "m1") {+ t.Fatal("SIsMember m1 = false, want true")+ }+ if c.SIsMember(ctx, k, "mX") {+ t.Fatal("SIsMember mX = true, want false")+ }+ members, err := c.SMembers(ctx, k)+ if err != nil {+ t.Fatalf("SMembers: %v", err)+ }+ if len(members) != 2 {+ t.Fatalf("SMembers len = %d, want 2", len(members))+ }+ if !c.SRem(ctx, k, "m1") {+ t.Fatal("SRem m1 failed")+ }+ if c.SIsMember(ctx, k, "m1") {+ t.Fatal("SIsMember m1 = true after SRem, want false")+ }+ })++ t.Run("ZSet", func(t *testing.T) {+ k := prefix + "zset"+ c.client.Del(ctx, k)+ if !c.ZAdd(ctx, k, "a", 1) {+ t.Fatal("ZAdd a failed")+ }+ if !c.ZAdd(ctx, k, "b", 5) {+ t.Fatal("ZAdd b failed")+ }+ if !c.ZAdd(ctx, k, "c", 10) {+ t.Fatal("ZAdd c failed")+ }+ if n := c.ZCount(ctx, k, 0, 6); n != 2 {+ t.Fatalf("ZCount(0,6) = %d, want 2", n)+ }+ got, err := c.ZRangeByScore(ctx, k, 0, 6)+ if err != nil {+ t.Fatalf("ZRangeByScore: %v", err)+ }+ if len(got) != 2 || got[0] != "a" || got[1] != "b" {+ t.Fatalf("ZRangeByScore = %v, want [a b]", got)+ }+ popped, err := c.ZPopMin(ctx, k, 1)+ if err != nil {+ t.Fatalf("ZPopMin: %v", err)+ }+ if len(popped) != 1 || popped[0].Member.(string) != "a" {+ t.Fatalf("ZPopMin = %v, want [a]", popped)+ }+ // After ZPopMin removed "a"(score 1), remaining b(5) and c(10).+ // Removing the [0,6] range must drop only "b" -> 1 removed.+ if n := c.ZRemRangeByScore(ctx, k, 0, 6); n != 1 {+ t.Fatalf("ZRemRangeByScore(0,6) = %d, want 1", n)+ }+ })++ t.Run("Stream", func(t *testing.T) {+ q := prefix + "stream"+ c.client.Del(ctx, q)+ if !c.QueueProduct(ctx, q, map[string]string{"hello": "world"}) {+ t.Fatal("QueueProduct failed")+ }+ // Consumer group creation is implicit in QueueConsumer.+ msg, err := c.QueueConsumer(ctx, q, "grp", "cons", "")+ if err != nil {+ t.Fatalf("QueueConsumer: %v", err)+ }+ if msg == nil {+ t.Fatal("QueueConsumer returned nil message")+ }+ // QueueProduct stored {"hello":"world"} under the stream "message"+ // field; GetMessage() returns the JSON-decoded payload map.+ if got := msg.GetMessage()["hello"]; got != "world" {+ t.Fatalf("consumed payload hello = %v, want world", got)+ }+ if !msg.Ack(ctx) {+ t.Fatal("Ack failed")+ }+ pending, err := c.GetPendingMsg(ctx, q, "grp")+ if err != nil {+ t.Fatalf("GetPendingMsg: %v", err)+ }+ if len(pending) != 0 {+ t.Fatalf("GetPendingMsg len = %d, want 0 (acked)", len(pending))+ }+ // XRange round-trips the stored entry (RequeueMsg path).+ ranged, err := c.client.XRange(ctx, q, "-", "+").Result()+ if err != nil {+ t.Fatalf("XRange: %v", err)+ }+ if len(ranged) == 0 {+ t.Fatal("XRange returned no entries")+ }+ })++ t.Run("LuaDeleteIfEqual", func(t *testing.T) {+ k := prefix + "die"+ c.client.Del(ctx, k)+ if !c.Set(ctx, k, "expect", time.Minute) {+ t.Fatal("Set failed")+ }+ // Wrong expected value must not delete.+ if c.DeleteIfEqual(ctx, k, "wrong") {+ t.Fatal("DeleteIfEqual deleted on wrong value")+ }+ if ok, _ := c.Exist(ctx, k); !ok {+ t.Fatal("key gone after wrong DeleteIfEqual")+ }+ // Correct expected value deletes.+ if !c.DeleteIfEqual(ctx, k, "expect") {+ t.Fatal("DeleteIfEqual failed on correct value")+ }+ if ok, _ := c.Exist(ctx, k); ok {+ t.Fatal("key still present after correct DeleteIfEqual")+ }+ })++ t.Run("TokenBucketStrict", func(t *testing.T) {+ // EvalTokenBucketStrict is the fail-closed counterpart used by the webhook+ // rate limiter (agent_webhook_security.go). It shares the TokenBucket Lua+ // but must surface its result/errors to the caller rather than silently+ // passing traffic. Verify the allow/deny sequence on Kvrocks.+ k := prefix + "tbs"+ c.client.Del(ctx, k)+ ok, err := c.EvalTokenBucketStrict(ctx, k, 2, 0.1)+ if err != nil {+ t.Fatalf("call 1: %v", err)+ }+ if !ok {+ t.Fatal("call 1: expected allowed")+ }+ if ok, err = c.EvalTokenBucketStrict(ctx, k, 2, 0.1); err != nil || !ok {+ t.Fatalf("call 2: ok=%v err=%v, want allowed", ok, err)+ }+ ok, err = c.EvalTokenBucketStrict(ctx, k, 2, 0.1)+ if err != nil {+ t.Fatalf("call 3: %v", err)+ }+ if ok {+ t.Fatal("call 3: expected denied (bucket exhausted), got allowed")+ }+ })++ t.Run("PipelineSetNX", func(t *testing.T) {+ k := prefix + "pipe"+ c.client.Del(ctx, k)+ if !c.Transaction(ctx, k, "v", time.Minute) {+ t.Fatal("Transaction (pipeline SetNX) failed")+ }+ // Second call hits an existing key: SetNX inside the pipeline does not+ // overwrite, so the value must remain "v" (Transaction returns on+ // Exec success, not SetNX success — assert the value, not the bool).+ c.Transaction(ctx, k, "v2", time.Minute)+ if v, _ := c.Get(ctx, k); v != "v" {+ t.Fatalf("pipeline SetNX overwrote existing key: Get = %q, want v", v)+ }+ })++ t.Run("TTLContract", func(t *testing.T) {+ // Kvrocks >= 2.11 reads metadata.Expired() on the read path, so a key+ // whose TTL elapsed must report EXISTS=0 immediately (no 2-3s+ // compaction lag). This is the exact bug that 2.0.6 had and that+ // motivated pinning apache/kvrocks:2.16.0. Guard it.+ k := prefix + "ttl"+ c.client.Del(ctx, k)+ if !c.Set(ctx, k, "x", 1200*time.Millisecond) {+ t.Fatal("Set with TTL failed")+ }+ if ok, _ := c.Exist(ctx, k); !ok {+ t.Fatal("key should exist before TTL elapses")+ }+ time.Sleep(1500 * time.Millisecond)+ if ok, _ := c.Exist(ctx, k); ok {+ t.Fatal("EXISTS=1 long after TTL elapsed: Kvrocks read-path expiry broken (regression of 2.0.6 bug)")+ }+ if tt := c.TTL(ctx, k); tt != -2 {+ t.Fatalf("TTL = %v, want -2 (key gone)", tt)+ }+ })++ t.Run("Auth", func(t *testing.T) {+ // The live client authenticated at connect time. A second client with+ // a wrong password must fail to PING (NOAUTH), proving requirepass is+ // enforced — important because Kvrocks rejects multi-user ACLs.+ pw := os.Getenv("KV_PASSWORD")+ if pw == "" {+ t.Skip("KV_PASSWORD empty; auth-enforcement check skipped")+ }+ bad := redis.NewClient(&redis.Options{Addr: os.Getenv("KV_ADDR"), Password: "definitely-wrong"})+ defer func() { _ = bad.Close() }()+ if err := bad.Ping(ctx).Err(); err == nil {+ t.Fatal("PING with wrong password succeeded; requirepass not enforced")+ }+ })++ t.Run("Info", func(t *testing.T) {+ // Info must not panic on Kvrocks' differently-shaped INFO output.+ info := c.Info(ctx)+ if info == nil {+ t.Fatal("Info returned nil")+ }+ // server_mode is empty on Kvrocks (field name differs) — that is+ // acceptable and only affects monitoring, not functionality.+ })+}