feat: Valkey cache for search results

- Add internal/cache package using go-redis/v9 (Valkey-compatible)
- Cache keys are deterministic SHA-256 hashes of search parameters
- Cache wraps the Search() method: check cache → miss → execute → store
- Gracefully disabled if Valkey is unreachable or unconfigured
- Configurable TTL (default 5m), address, password, and DB index
- Environment variable overrides: VALKEY_ADDRESS, VALKEY_PASSWORD,
  VALKEY_DB, VALKEY_CACHE_TTL
- Structured JSON logging via slog throughout cache layer
- Refactored service.go: extract executeSearch() from Search() for clarity
- Update config.example.toml with [cache] section
- Add cache package tests (key generation, nop behavior)

internal/cache/cache.go

@@ -0,0 +1,162 @@
+package cache
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"github.com/ashie/gosearch/internal/contracts"
+	"github.com/redis/go-redis/v9"
+)
+
+// Config holds Valkey/Redis connection settings.
+type Config struct {
+	// Address is the Valkey server address (e.g. "localhost:6379").
+	Address string
+	// Password for authentication (empty = no auth).
+	Password string
+	// Database index (default 0).
+	DB int
+	// Default TTL for cached search results.
+	DefaultTTL time.Duration
+}
+
+// Cache provides a Valkey-backed cache for search responses.
+// It is safe for concurrent use.
+// If the Valkey connection is nil or fails, cache operations are no-ops.
+type Cache struct {
+	client *redis.Client
+	ttl    time.Duration
+	logger *slog.Logger
+}
+
+// New creates a new Cache. If cfg.Address is empty, returns a no-op cache.
+func New(cfg Config, logger *slog.Logger) *Cache {
+	if logger == nil {
+		logger = slog.Default()
+	}
+
+	if cfg.Address == "" {
+		logger.Debug("cache disabled: no valkey address configured")
+		return &Cache{logger: logger}
+	}
+
+	ttl := cfg.DefaultTTL
+	if ttl <= 0 {
+		ttl = 5 * time.Minute
+	}
+
+	client := redis.NewClient(&redis.Options{
+		Addr:     cfg.Address,
+		Password: cfg.Password,
+		DB:       cfg.DB,
+	})
+
+	// Verify connectivity with a short timeout.
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	if err := client.Ping(ctx).Err(); err != nil {
+		logger.Warn("cache disabled: valkey ping failed", "addr", cfg.Address, "error", err)
+		return &Cache{logger: logger}
+	}
+
+	logger.Info("cache connected", "addr", cfg.Address, "db", cfg.DB, "ttl", ttl)
+	return &Cache{client: client, ttl: ttl, logger: logger}
+}
+
+// Enabled returns true if the cache has a live Valkey connection.
+func (c *Cache) Enabled() bool {
+	return c.client != nil
+}
+
+// Get retrieves a cached search response. Returns (response, true) on hit,
+// (zero, false) on miss or error.
+func (c *Cache) Get(ctx context.Context, key string) (contracts.SearchResponse, bool) {
+	if !c.Enabled() {
+		return contracts.SearchResponse{}, false
+	}
+
+	fullKey := "gosearch:" + key
+
+	data, err := c.client.Get(ctx, fullKey).Bytes()
+	if err != nil {
+		if err != redis.Nil {
+			c.logger.Debug("cache miss (error)", "key", fullKey, "error", err)
+		}
+		return contracts.SearchResponse{}, false
+	}
+
+	var resp contracts.SearchResponse
+	if err := json.Unmarshal(data, &resp); err != nil {
+		c.logger.Warn("cache hit but unmarshal failed", "key", fullKey, "error", err)
+		return contracts.SearchResponse{}, false
+	}
+
+	c.logger.Debug("cache hit", "key", fullKey)
+	return resp, true
+}
+
+// Set stores a search response in the cache with the default TTL.
+func (c *Cache) Set(ctx context.Context, key string, resp contracts.SearchResponse) {
+	if !c.Enabled() {
+		return
+	}
+
+	data, err := json.Marshal(resp)
+	if err != nil {
+		c.logger.Warn("cache set: marshal failed", "key", key, "error", err)
+		return
+	}
+
+	fullKey := "gosearch:" + key
+	if err := c.client.Set(ctx, fullKey, data, c.ttl).Err(); err != nil {
+		c.logger.Warn("cache set failed", "key", fullKey, "error", err)
+	}
+}
+
+// Invalidate removes a specific key from the cache.
+func (c *Cache) Invalidate(ctx context.Context, key string) {
+	if !c.Enabled() {
+		return
+	}
+	fullKey := "gosearch:" + key
+	c.client.Del(ctx, fullKey)
+}
+
+// Close closes the Valkey connection.
+func (c *Cache) Close() error {
+	if c.client == nil {
+		return nil
+	}
+	return c.client.Close()
+}
+
+// Key generates a deterministic cache key from search parameters.
+// The key is a SHA-256 hash of the normalized parameters, prefixed for readability.
+func Key(req contracts.SearchRequest) string {
+	h := sha256.New()
+
+	fmt.Fprintf(h, "q=%s|", req.Query)
+	fmt.Fprintf(h, "format=%s|", req.Format)
+	fmt.Fprintf(h, "pageno=%d|", req.Pageno)
+	fmt.Fprintf(h, "safesearch=%d|", req.Safesearch)
+	fmt.Fprintf(h, "lang=%s|", req.Language)
+
+	if req.TimeRange != nil {
+		fmt.Fprintf(h, "tr=%s|", *req.TimeRange)
+	}
+
+	for _, e := range req.Engines {
+		fmt.Fprintf(h, "e=%s|", e)
+	}
+	for _, cat := range req.Categories {
+		fmt.Fprintf(h, "c=%s|", cat)
+	}
+
+	return hex.EncodeToString(h.Sum(nil))[:32]
+}

internal/cache/cache_test.go

@@ -0,0 +1,77 @@
+package cache
+
+import (
+	"testing"
+
+	"github.com/ashie/gosearch/internal/contracts"
+)
+
+func TestKey_Deterministic(t *testing.T) {
+	req := contracts.SearchRequest{
+		Format:     contracts.FormatJSON,
+		Query:      "kafka metamorphosis",
+		Pageno:     1,
+		Safesearch: 0,
+		Language:   "auto",
+		Engines:    []string{"wikipedia", "braveapi"},
+		Categories: []string{"general"},
+	}
+
+	key1 := Key(req)
+	key2 := Key(req)
+
+	if key1 != key2 {
+		t.Errorf("Key should be deterministic: %q != %q", key1, key2)
+	}
+	if len(key1) != 32 {
+		t.Errorf("expected 32-char key, got %d", len(key1))
+	}
+}
+
+func TestKey_DifferentQueries(t *testing.T) {
+	reqA := contracts.SearchRequest{Query: "kafka", Format: contracts.FormatJSON}
+	reqB := contracts.SearchRequest{Query: "orwell", Format: contracts.FormatJSON}
+
+	if Key(reqA) == Key(reqB) {
+		t.Error("different queries should produce different keys")
+	}
+}
+
+func TestKey_DifferentPageno(t *testing.T) {
+	req1 := contracts.SearchRequest{Query: "test", Pageno: 1}
+	req2 := contracts.SearchRequest{Query: "test", Pageno: 2}
+
+	if Key(req1) == Key(req2) {
+		t.Error("different pageno should produce different keys")
+	}
+}
+
+func TestKey_DifferentEngines(t *testing.T) {
+	req1 := contracts.SearchRequest{Query: "test", Engines: []string{"wikipedia"}}
+	req2 := contracts.SearchRequest{Query: "test", Engines: []string{"braveapi"}}
+
+	if Key(req1) == Key(req2) {
+		t.Error("different engines should produce different keys")
+	}
+}
+
+func TestKey_TimeRange(t *testing.T) {
+	req1 := contracts.SearchRequest{Query: "test"}
+	req2 := contracts.SearchRequest{Query: "test", TimeRange: strPtr("week")}
+
+	if Key(req1) == Key(req2) {
+		t.Error("with/without time_range should produce different keys")
+	}
+}
+
+func TestNew_NopWithoutAddress(t *testing.T) {
+	c := New(Config{}, nil)
+	if c.Enabled() {
+		t.Error("cache should be disabled when no address is configured")
+	}
+	if err := c.Close(); err != nil {
+		t.Errorf("Close on nop cache should not error: %v", err)
+	}
+}
+
+func strPtr(s string) *string { return &s }

internal/config/config.go

@@ -11,9 +11,10 @@ import (
 
 // Config is the top-level configuration for the gosearch service.
 type Config struct {
-	Server  ServerConfig  `toml:"server"`
+	Server   ServerConfig   `toml:"server"`
 	Upstream UpstreamConfig `toml:"upstream"`
-	Engines EnginesConfig `toml:"engines"`
+	Engines  EnginesConfig  `toml:"engines"`
+	Cache    CacheConfig    `toml:"cache"`
 }
 
 type ServerConfig struct {
@@ -26,11 +27,19 @@ type UpstreamConfig struct {
 }
 
 type EnginesConfig struct {
-	LocalPorted []string   `toml:"local_ported"`
+	LocalPorted []string    `toml:"local_ported"`
 	Brave       BraveConfig `toml:"brave"`
 	Qwant       QwantConfig `toml:"qwant"`
 }
 
+// CacheConfig holds Valkey/Redis cache settings.
+type CacheConfig struct {
+	Address    string `toml:"address"`     // Valkey server address (e.g. "localhost:6379")
+	Password   string `toml:"password"`    // Auth password (empty = none)
+	DB         int    `toml:"db"`          // Database index (default 0)
+	DefaultTTL string `toml:"default_ttl"` // Cache TTL (e.g. "5m", default "5m")
+}
+
 type BraveConfig struct {
 	APIKey       string `toml:"api_key"`
 	AccessToken  string `toml:"access_token"`
@@ -71,6 +80,10 @@ func defaultConfig() *Config {
 				ResultsPerPage: 10,
 			},
 		},
+		Cache: CacheConfig{
+			DB:         0,
+			DefaultTTL: "5m",
+		},
 	}
 }
 
@@ -99,6 +112,18 @@ func applyEnvOverrides(cfg *Config) {
 	if v := os.Getenv("BRAVE_ACCESS_TOKEN"); v != "" {
 		cfg.Engines.Brave.AccessToken = v
 	}
+	if v := os.Getenv("VALKEY_ADDRESS"); v != "" {
+		cfg.Cache.Address = v
+	}
+	if v := os.Getenv("VALKEY_PASSWORD"); v != "" {
+		cfg.Cache.Password = v
+	}
+	if v := os.Getenv("VALKEY_DB"); v != "" {
+		fmt.Sscanf(v, "%d", &cfg.Cache.DB)
+	}
+	if v := os.Getenv("VALKEY_CACHE_TTL"); v != "" {
+		cfg.Cache.DefaultTTL = v
+	}
 }
 
 // HTTPTimeout parses the configured timeout string into a time.Duration.
@@ -114,6 +139,14 @@ func (c *Config) LocalPortedCSV() string {
 	return strings.Join(c.Engines.LocalPorted, ",")
 }
 
+// CacheTTL parses the configured cache TTL string into a time.Duration.
+func (c *Config) CacheTTL() time.Duration {
+	if d, err := time.ParseDuration(c.Cache.DefaultTTL); err == nil && d > 0 {
+		return d
+	}
+	return 5 * time.Minute
+}
+
 func splitCSV(s string) []string {
 	if s == "" {
 		return nil

internal/search/service.go

@@ -6,6 +6,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/ashie/gosearch/internal/cache"
 	"github.com/ashie/gosearch/internal/contracts"
 	"github.com/ashie/gosearch/internal/engines"
 	"github.com/ashie/gosearch/internal/upstream"
@@ -14,12 +15,14 @@ import (
 type ServiceConfig struct {
 	UpstreamURL string
 	HTTPTimeout time.Duration
+	Cache       *cache.Cache
 }
 
 type Service struct {
 	upstreamClient *upstream.Client
 	planner        *engines.Planner
 	localEngines   map[string]engines.Engine
+	cache          *cache.Cache
 }
 
 func NewService(cfg ServiceConfig) *Service {
@@ -42,6 +45,7 @@ func NewService(cfg ServiceConfig) *Service {
 		upstreamClient: up,
 		planner:        engines.NewPlannerFromEnv(),
 		localEngines:  engines.NewDefaultPortedEngines(httpClient),
+		cache:          cfg.Cache,
 	}
 }
 
@@ -50,7 +54,34 @@ func NewService(cfg ServiceConfig) *Service {
 //
 // Individual engine failures are reported as unresponsive_engines rather
 // than aborting the entire search.
+//
+// If a Valkey cache is configured and contains a cached response for this
+// request, the cached result is returned without hitting any engines.
 func (s *Service) Search(ctx context.Context, req SearchRequest) (SearchResponse, error) {
+	// Check cache first.
+	if s.cache != nil {
+		cacheKey := cache.Key(req)
+		if cached, hit := s.cache.Get(ctx, cacheKey); hit {
+			return cached, nil
+		}
+	}
+
+	merged, err := s.executeSearch(ctx, req)
+	if err != nil {
+		return SearchResponse{}, err
+	}
+
+	// Store in cache.
+	if s.cache != nil {
+		cacheKey := cache.Key(req)
+		s.cache.Set(ctx, cacheKey, merged)
+	}
+
+	return merged, nil
+}
+
+// executeSearch runs the actual engine queries and merges results.
+func (s *Service) executeSearch(ctx context.Context, req SearchRequest) (SearchResponse, error) {
 	localEngineNames, upstreamEngineNames, _ := s.planner.Plan(req)
 
 	// Run all local engines concurrently.
@@ -176,5 +207,3 @@ func shouldFallbackToUpstream(engineName string, r contracts.SearchResponse) boo
 	}
 	return len(r.Results) == 0 && len(r.Answers) == 0 && len(r.Infoboxes) == 0
 }
-
-