feature: Valkey cache integration by daric93 · Pull Request #1263 · gorse-io/gorse

daric93 · 2026-05-05T20:32:58Z

Summary

Fixes: #1260

Adds Valkey as a cache storage backend using the valkey-go client. Supports both standalone and cluster modes with TLS.

What's included

Full Database interface implementation in storage/cache/valkey.go — scores (documents), time series, key-value, and queue operations
FT.SEARCH-based document queries using Valkey Search (TAG + NUMERIC fields)
Time series storage using sorted set + hash with Go-side bucket aggregation
URL schemes: valkey://, valkeys://, valkey+cluster://, valkeys+cluster://
Config validation and documentation updates
Comprehensive test suite (unit, integration, benchmarks)
Docker Compose service using valkey/valkey-bundle:unstable (includes valkey-search)

Design decisions

Uses valkey-go (official Valkey client) rather than a Redis client for forward compatibility
Cluster mode deletes keys one-at-a-time to avoid CROSSSLOT errors
Valkey-specific escapeTag() function escapes all TAG special characters to prevent query injection
Thin wrapper methods (vDel, vHSet, vZAdd, vHGetAll) centralize cluster/standalone branching
DeleteScores loop has a max iteration guard (100) to prevent infinite loops
UpdateScores skips the non-atomic Exists check — HSet directly on keys found via FT.SEARCH

Why valkey-go over valkey-glide

The initial implementation used valkey-glide, but it requires CGo — it wraps a Rust core library via FFI. Gorse builds all default Docker images and release binaries with CGO_ENABLED=0 to produce fully static binaries that run in minimal FROM scratch containers (see every Dockerfile and build_release.yml). Enabling CGo would require a C toolchain in the build environment, a libc at runtime, break the FROM scratch pattern, increase image sizes, and complicate multi-arch cross-compilation.

valkey-go is a pure Go client with no CGo dependency, so it works with CGO_ENABLED=0 out of the box.

Testing

Inherits full baseTestSuite (TestDocument, TestPurge, TestTimeSeries, TestScanScores, etc.)
Valkey-specific tests: escape characters, pagination with tied scores, URL parsing
Benchmarks: document CRUD, time series ingest (single/batch), time series queries (small/large/wide range)
Requires Valkey with search module (port 6380 via docker-compose)

Changed files

File	Change
`storage/cache/valkey.go`	New — full cache backend implementation
`storage/cache/valkey_test.go`	New — tests and benchmarks
`storage/scheme.go`	Add Valkey URL prefix constants
`storage/docker-compose.yml`	Add Valkey service
`config/config.go`	Accept Valkey prefixes in validation
`config/config.toml`	Document Valkey connection strings
`config/config_test.go`	Validate Valkey prefixes
`storage/cache/database_test.go`	Add time series benchmarks
`go.mod` / `go.sum`	Add valkey-go dependency

Implement Valkey as a first-class cache store backend using valkey-glide Go client. This enables Gorse users to use Valkey as an alternative to Redis for the cache layer. Changes: - Add valkey://, valkeys://, valkey+cluster://, valkeys+cluster:// URL prefix constants and config validation - Implement full cache.Database interface in storage/cache/valkey.go using valkey-glide v2 client (standalone + cluster modes) - Time series implemented via Sorted Set + Hash with Go-side bucket aggregation (no TimeSeries module dependency) - Score/document operations use valkey-search FT.* commands via CustomCommand - Add integration test suite embedding baseTestSuite - Add integration report with analysis and task breakdown Signed-off-by: Daria Korenieva <daric2612@gmail.com>

Add valkey/valkey-bundle:unstable (valkey-search 1.2.0+ with full-text search support) to storage/docker-compose.yml on port 6380. Update default test URI to valkey://127.0.0.1:6380/. Signed-off-by: Daria Korenieva <daric2612@gmail.com>