init

Author: nikolaydubina

.github/workflows/test.yml

@@ -0,0 +1,47 @@
+name: test
+
+on: [push]
+
+permissions: read-all
+
+jobs:
+  build:
+    name: test
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    services:
+      redis:
+        image: redis:latest
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 6379:6379
+        env:
+          REDIS_PASSWORD: testpassword
+
+    steps:
+      - name: code
+        uses: actions/checkout@v4
+
+      - name: go
+        uses: actions/setup-go@v5
+        with:
+          go-version: ^1.24
+
+      - name: test
+        env:
+          REDIS_ADDR: localhost:6379
+          REDIS_PASSWORD: testpassword
+        run: |
+          go get -v -t -d ./...
+          go test -short -cover -coverprofile=coverage.out -covermode=atomic ./...
+
+      - name: codecov.io coverage
+        uses: codecov/[email protected]
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: coverage.out

README.md

@@ -1 +1 @@
-# redis-suggest
+Go Redis `FT.SUGADD`, `FT.SUGGET`, `FT.SUGLEN`, `FT.SUGLEN`

go.mod

@@ -0,0 +1,10 @@
+module github.com/ndx-technologies/go-redis-suggest
+
+go 1.24.0
+
+require github.com/redis/go-redis/v9 v9.7.1
+
+require (
+	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+)

go.sum

@@ -0,0 +1,6 @@
+github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
+github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f h1:lO4WD4F/rVNCu3HqELle0jiPLLBs70cWOduZpkS1E78=
+github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/redis/go-redis/v9 v9.7.1 h1:4LhKRCIduqXqtvCUlaq9c8bdHOkICjDMrr1+Zb3osAc=
+github.com/redis/go-redis/v9 v9.7.1/go.mod h1:f6zhXITC7JUJIlPEiBOTXxJgPLdZcA93GewI7inzyWw=

suggestion.go

@@ -0,0 +1,98 @@
+package redissug
+
+import (
+	"context"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// RedisSuggestionClient that provides SUG commands.
+type RedisSuggestionClient struct {
+	DB *redis.Client
+}
+
+type Suggestion struct {
+	Text    string
+	Payload string
+}
+
+// SugAdd returns current size of suggestion dictionary
+func (s RedisSuggestionClient) SugAdd(ctx context.Context, key string, suggestion string, score float64, incr bool, payload string) (int, error) {
+	args := []any{"FT.SUGADD", key, suggestion, score}
+
+	if incr {
+		args = append(args, "INCR")
+	}
+
+	if payload != "" {
+		args = append(args, "PAYLOAD", payload)
+	}
+
+	return s.DB.Do(ctx, args...).Int()
+}
+
+type SugGetOptions struct {
+	Fuzzy        bool
+	WithPayloads bool
+}
+
+// SugGet returns suggestions sorted from highest score to lowest score.
+// Scores may not be the same as the scores used in SugAdd, which is why they are not exposed.
+func (s RedisSuggestionClient) SugGet(ctx context.Context, key string, prefix string, max int, opts SugGetOptions) ([]Suggestion, error) {
+	args := []any{"FT.SUGGET", key, prefix}
+
+	if opts.Fuzzy {
+		args = append(args, "FUZZY")
+	}
+	if opts.WithPayloads {
+		args = append(args, "WITHPAYLOADS")
+	}
+	if max > 0 {
+		args = append(args, "MAX", max)
+	}
+
+	result, err := s.DB.Do(ctx, args...).Slice()
+	if err != nil {
+		return nil, err
+	}
+
+	suggestions := make([]Suggestion, 0, max)
+
+	for i := 0; i < len(result); {
+		var s Suggestion
+
+		s.Text, _ = result[i].(string)
+		i++
+
+		if opts.WithPayloads {
+			s.Payload, _ = result[i].(string)
+			i++
+		}
+
+		suggestions = append(suggestions, s)
+	}
+
+	return suggestions, nil
+}
+
+// SugDel deletes a suggestion from a suggestion index
+func (s RedisSuggestionClient) SugDel(ctx context.Context, key string, suggestion string) error {
+	v, err := s.DB.Do(ctx, "FT.SUGDEL", key, suggestion).Int()
+	if err != nil {
+		return err
+	}
+	if v == 0 {
+		return redis.Nil
+	}
+	return nil
+}
+
+// SugLen returns size of an auto-complete suggestion dictionary
+func (s RedisSuggestionClient) SugLen(ctx context.Context, key string) (int, error) {
+	return s.DB.Do(ctx, "FT.SUGLEN", key).Int()
+}
+
+func (s RedisSuggestionClient) DelAll(ctx context.Context, keys ...string) error {
+	_, err := s.DB.Del(ctx, keys...).Result()
+	return err
+}

suggestion_test.go

@@ -0,0 +1,207 @@
+package redissug_test
+
+import (
+	"context"
+	"math/rand"
+	"os"
+	"slices"
+	"strconv"
+	"testing"
+
+	"github.com/redis/go-redis/v9"
+
+	redissug "github.com/ndx-technologies/go-redis-suggest"
+)
+
+func TestRedisSuggest(t *testing.T) {
+	if testing.Short() {
+		t.Skip("network; redis;")
+	}
+
+	addr := os.Getenv("REDIS_ADDR")
+	if addr == "" {
+		addr = "localhost:6379"
+	}
+
+	rdb := redis.NewClient(&redis.Options{
+		Addr:     addr,
+		Password: os.Getenv("REDIS_PASSWORD"),
+	})
+
+	ctx := t.Context()
+	id := "test-sug:" + strconv.Itoa(rand.Int())
+	s := redissug.RedisSuggestionClient{DB: rdb}
+	t.Cleanup(func() { s.DelAll(context.Background(), id) })
+
+	t.Run("when adding suggestions", func(t *testing.T) {
+		size, err := s.SugAdd(ctx, id, "text", 1, false, "payload1")
+		if err != nil {
+			t.Error("SugAdd failed:", err)
+		}
+		if size != 1 {
+			t.Error("expected size 1, got", size)
+		}
+
+		size, err = s.SugAdd(ctx, id, "test", 2, false, "payload2")
+		if err != nil {
+			t.Error("SugAdd failed:", err)
+		}
+		if size != 2 {
+			t.Error("expected size 2, got", size)
+		}
+
+		size, err = s.SugAdd(ctx, id, "tent", 2, false, "")
+		if err != nil {
+			t.Error("SugAdd failed:", err)
+		}
+		if size != 3 {
+			t.Error("expected size 3, got", size)
+		}
+
+		size, err = s.SugAdd(ctx, id, "tent", 1, true, "")
+		if err != nil {
+			t.Error("SugAdd failed:", err)
+		}
+		if size != 3 {
+			t.Error("expected size 3, got", size)
+		}
+
+		t.Run("when getting length, then 3", func(t *testing.T) {
+			count, err := s.SugLen(ctx, id)
+			if err != nil {
+				t.Error("SugLen failed:", err)
+			}
+			if count != 3 {
+				t.Error("expected count 3, got", count)
+			}
+		})
+
+		t.Run("when prefix, then return all matched in highest to lowest score order", func(t *testing.T) {
+			suggestions, err := s.SugGet(ctx, id, "te", 10, redissug.SugGetOptions{})
+			if err != nil {
+				t.Error("SugGet failed:", err)
+			}
+			exp := []redissug.Suggestion{{Text: "tent"}, {Text: "test"}, {Text: "text"}}
+			if !slices.Equal(suggestions, exp) {
+				t.Error("expected", exp, "got", suggestions)
+			}
+		})
+
+		t.Run("when exact prefix, then only exact is returned", func(t *testing.T) {
+			suggestions, err := s.SugGet(ctx, id, "tex", 10, redissug.SugGetOptions{})
+			if err != nil {
+				t.Error("SugGet failed:", err)
+			}
+			exp := []redissug.Suggestion{{Text: "text"}}
+			if !slices.Equal(suggestions, exp) {
+				t.Error("expected", exp, "got", suggestions)
+			}
+		})
+
+		t.Run("when fuzzy prefix, then multiple returned", func(t *testing.T) {
+			suggestions, err := s.SugGet(ctx, id, "tex", 10, redissug.SugGetOptions{Fuzzy: true})
+			if err != nil {
+				t.Error("SugGet failed:", err)
+			}
+			exp := []redissug.Suggestion{{Text: "text"}, {Text: "tent"}, {Text: "test"}}
+			if !slices.Equal(suggestions, exp) {
+				t.Error("expected", exp, "got", suggestions)
+			}
+		})
+
+		t.Run("when getting with payloads, then payloads are returned", func(t *testing.T) {
+			suggestions, err := s.SugGet(ctx, id, "te", 10, redissug.SugGetOptions{WithPayloads: true})
+			if err != nil {
+				t.Error("SugGet failed:", err)
+			}
+			exp := []redissug.Suggestion{{Text: "tent"}, {Text: "test", Payload: "payload2"}, {Text: "text", Payload: "payload1"}}
+			if !slices.Equal(suggestions, exp) {
+				t.Error("expected", exp, "got", suggestions)
+			}
+		})
+
+		t.Run("when adding same suggestion with different score and payload", func(t *testing.T) {
+			size, err := s.SugAdd(ctx, id, "text", 5, false, "new_payload")
+			if err != nil {
+				t.Error("SugAdd failed:", err)
+			}
+			if size != 3 {
+				t.Error("expected size 3, got", size)
+			}
+
+			t.Run("then new payload is set", func(t *testing.T) {
+				suggestions, err := s.SugGet(ctx, id, "tex", 10, redissug.SugGetOptions{WithPayloads: true})
+				if err != nil {
+					t.Error("SugGet failed:", err)
+				}
+				exp := []redissug.Suggestion{{Text: "text", Payload: "new_payload"}}
+				if !slices.Equal(suggestions, exp) {
+					t.Error("expected", exp, "got", suggestions)
+				}
+			})
+		})
+	})
+
+	t.Run("when deleting suggestion", func(t *testing.T) {
+		if err := s.SugDel(ctx, id, "test"); err != nil {
+			t.Error("SugDel failed:", err)
+		}
+
+		t.Run("when deleting non existing, then no error and ok", func(t *testing.T) {
+			if err := s.SugDel(ctx, id, "asdf"); err != redis.Nil {
+				t.Error("expected redis.Nil, got", err)
+			}
+		})
+
+		t.Run("when getting suggestions, then no deleted entry", func(t *testing.T) {
+			suggestions, err := s.SugGet(ctx, id, "te", 10, redissug.SugGetOptions{})
+			if err != nil {
+				t.Error("SugGet failed:", err)
+			}
+			exp := []redissug.Suggestion{{Text: "text"}, {Text: "tent"}}
+			if !slices.Equal(suggestions, exp) {
+				t.Error("expected", exp, "got", suggestions)
+			}
+		})
+
+		t.Run("then length is decremented", func(t *testing.T) {
+			count, err := s.SugLen(ctx, id)
+			if err != nil {
+				t.Error("SugLen failed:", err)
+			}
+			if count != 2 {
+				t.Error("expected count 2, got", count)
+			}
+		})
+	})
+
+	t.Run("when non existing key", func(t *testing.T) {
+		nonExistentKey := "non-existent:" + strconv.Itoa(rand.Int())
+
+		t.Run("when getting suggestions, then redis.Nil", func(t *testing.T) {
+			suggestions, err := s.SugGet(ctx, nonExistentKey, "te", 10, redissug.SugGetOptions{})
+			if err != redis.Nil {
+				t.Error("expected redis.Nil, got", err)
+			}
+			if len(suggestions) != 0 {
+				t.Error("expected empty slice, got", suggestions)
+			}
+		})
+
+		t.Run("when getting length, then 0", func(t *testing.T) {
+			count, err := s.SugLen(ctx, nonExistentKey)
+			if err != nil {
+				t.Error("SugLen failed:", err)
+			}
+			if count != 0 {
+				t.Error("expected count 0, got", count)
+			}
+		})
+
+		t.Run("when deleting non existing, then redis nil", func(t *testing.T) {
+			if err := s.SugDel(ctx, nonExistentKey, "asdf"); err != redis.Nil {
+				t.Error("expected redis.Nil, got", err)
+			}
+		})
+	})
+}