// Package queryserving contains optional derived-data accelerators. None owns // business state, permissions or task mutations; every failure is a cache miss. package queryserving import ( "bytes" "context" "crypto/sha256" "encoding/hex" "encoding/json" "errors" "sync" "sync/atomic" "time" valkey "github.com/valkey-io/valkey-go" ) const MaxValueBytes = 4 << 20 type Cache interface { Get(context.Context, string) ([]byte, bool) Put(context.Context, string, []byte, time.Duration) } // Key includes the schema/database namespace supplied by the caller and only // hashes its remaining identity; no customer names or query text become keys. func Key(namespace string, identity ...any) string { b, _ := json.Marshal(identity) sum := sha256.Sum256(b) return namespace + ":" + hex.EncodeToString(sum[:]) } type Valkey struct { client valkey.Client prefix string until atomic.Int64 Hits, Misses, Errors atomic.Uint64 } func NewValkey(address, namespace string) (*Valkey, error) { opt, err := valkey.ParseURL(address) if err != nil { return nil, errors.New("invalid shared cache configuration") } opt.DisableCache = true // no implicit client-side cache or permission reuse opt.Dialer.Timeout = 200 * time.Millisecond opt.ConnWriteTimeout = 200 * time.Millisecond opt.DisableRetry = true opt.PipelineMultiplex = -1 opt.BlockingPoolSize = 4 opt.ReadBufferEachConn = 64 << 10 opt.WriteBufferEachConn = 64 << 10 client, err := valkey.NewClient(opt) if err != nil { return nil, errors.New("shared cache unavailable") } return &Valkey{client: client, prefix: Key("droboticflow-query/v1", namespace)}, nil } // ManagedValkey connects asynchronously so an absent cache at startup cannot // delay or fail API availability. Connections are retried without request load. type ManagedValkey struct { mu sync.RWMutex value *Valkey cancel context.CancelFunc done chan struct{} } func NewManagedValkey(address, namespace string) (*ManagedValkey, error) { if _, err := valkey.ParseURL(address); err != nil { return nil, errors.New("invalid shared cache configuration") } ctx, cancel := context.WithCancel(context.Background()) m := &ManagedValkey{cancel: cancel, done: make(chan struct{})} go func() { defer close(m.done) for { v, err := NewValkey(address, namespace) if err == nil { m.mu.Lock() if ctx.Err() == nil { m.value = v m.mu.Unlock() <-ctx.Done() v.Close() return } m.mu.Unlock() v.Close() return } select { case <-ctx.Done(): return case <-time.After(time.Second): } } }() return m, nil } func (m *ManagedValkey) Get(ctx context.Context, key string) ([]byte, bool) { m.mu.RLock() v := m.value m.mu.RUnlock() if v == nil { return nil, false } return v.Get(ctx, key) } func (m *ManagedValkey) Put(ctx context.Context, key string, b []byte, ttl time.Duration) { m.mu.RLock() v := m.value m.mu.RUnlock() if v != nil { v.Put(ctx, key, b, ttl) } } func (m *ManagedValkey) Close() { m.cancel(); <-m.done } func (m *ManagedValkey) Ready() bool { m.mu.RLock(); defer m.mu.RUnlock(); return m.value != nil } func (v *Valkey) Close() { v.client.Close() } func (v *Valkey) failed() { v.Errors.Add(1); v.until.Store(time.Now().Add(time.Second).UnixNano()) } func (v *Valkey) Get(ctx context.Context, key string) ([]byte, bool) { parent := ctx if parent.Err() != nil { return nil, false } if time.Now().UnixNano() < v.until.Load() { v.Misses.Add(1) return nil, false } ctx, cancel := context.WithTimeout(ctx, 40*time.Millisecond) defer cancel() b, err := v.client.Do(ctx, v.client.B().Get().Key(v.prefix+":"+key).Build()).AsBytes() if err != nil { if !valkey.IsValkeyNil(err) && parent.Err() == nil { v.failed() } v.Misses.Add(1) return nil, false } decoded, valid := decodeCacheValue(key, b) if !valid { v.Misses.Add(1) return nil, false } v.Hits.Add(1) return decoded, true } func (v *Valkey) Put(ctx context.Context, key string, b []byte, ttl time.Duration) { parent := ctx if parent.Err() != nil { return } if len(b) > MaxValueBytes || ttl <= 0 || time.Now().UnixNano() < v.until.Load() { return } ctx, cancel := context.WithTimeout(ctx, 40*time.Millisecond) defer cancel() encoded := encodeCacheValue(key, b) if err := v.client.Do(ctx, v.client.B().Set().Key(v.prefix+":"+key).Value(string(encoded)).Px(ttl).Build()).Error(); err != nil { if parent.Err() == nil { v.failed() } } } func GetJSON(ctx context.Context, c Cache, key string, value any) bool { if c == nil { return false } b, ok := c.Get(ctx, key) return ok && json.Unmarshal(b, value) == nil } func PutJSON(ctx context.Context, c Cache, key string, value any, ttl time.Duration) { if c == nil { return } b, err := json.Marshal(value) if err == nil { c.Put(ctx, key, b, ttl) } } func (m *ManagedValkey) Statistics() map[string]uint64 { m.mu.RLock() v := m.value m.mu.RUnlock() if v == nil { return map[string]uint64{} } return map[string]uint64{"hits": v.Hits.Load(), "misses": v.Misses.Load(), "errors": v.Errors.Load()} } func encodeCacheValue(key string, b []byte) []byte { sum := sha256.Sum256(append([]byte(key+"\x00"), b...)) return append(append([]byte("DFQ1"), sum[:]...), b...) } func decodeCacheValue(key string, b []byte) ([]byte, bool) { if len(b) < 36 || len(b) > MaxValueBytes+36 || string(b[:4]) != "DFQ1" { return nil, false } sum := sha256.Sum256(append([]byte(key+"\x00"), b[36:]...)) if !bytes.Equal(sum[:], b[4:36]) { return nil, false } return append([]byte(nil), b[36:]...), true }