cache.go

// Package cache provides a generic, TTL-based, in-memory key-value cache

// with background expiry sweeping and configurable expiration strategies.

package cache

import (

	"context"

	"errors"

	"sync"

	"time"

	"go.bigb.es/auxilia/collect"

	"go.bigb.es/auxilia/fn"

)

const (

	// NoExpiration indicates that an item should never expire.

	NoExpiration time.Duration = -2

	// DefaultExpiration indicates that an item should use the cache's default expiration.

	DefaultExpiration time.Duration = -1

)

var (

	// ErrNotExists is returned when an operation requires a key that is not present.

	ErrNotExists = errors.New("cache: record does not exist")

	// ErrAlreadyExists is returned when an insert finds the key already present.

	ErrAlreadyExists = errors.New("cache: record already exists")

)

// DeletionCause indicates why an item was removed from the cache.

type DeletionCause int

const (

	_ DeletionCause = iota

	// Evicted means the item was removed because it expired.

	Evicted

	// Deleted means the item was removed by an explicit Delete call.

	Deleted

)

// ExpirationPolicy controls how the cache determines whether an item has

// expired. Use WriteTTL, SlidingTTL, or NewExpirationPolicy to create a

// policy.

type ExpirationPolicy struct {

	// isExpired reports whether an item has expired given its write-time

	// deadline, last-access time, and resolved TTL.

	isExpired   func(expiration time.Time, lastAccess time.Time, ttl time.Duration) bool

	touchOnRead bool // when true, reads update LastAccess

}

// NewExpirationPolicy creates a custom ExpirationPolicy.

func NewExpirationPolicy(fn func(expiration time.Time, lastAccess time.Time, ttl time.Duration) bool, touchOnRead bool) ExpirationPolicy {

	return ExpirationPolicy{

		isExpired:   fn,

		touchOnRead: touchOnRead,

	}

}

// WriteTTL returns an ExpirationPolicy that expires items based on their

// write-time deadline (the default behaviour).

func WriteTTL() ExpirationPolicy {

	return ExpirationPolicy{

		isExpired: func(expiration time.Time, _ time.Time, _ time.Duration) bool {

			if expiration.IsZero() {

				return false

			}

			return time.Now().After(expiration)

		},

	}

}

// SlidingTTL returns an ExpirationPolicy that resets the expiration window

// on every read (Get, GetWithExpiration, GetOrInsert).

func SlidingTTL() ExpirationPolicy {

	return ExpirationPolicy{

		isExpired: func(expiration time.Time, lastAccess time.Time, ttl time.Duration) bool {

			if expiration.IsZero() {

				return false

			}

			return time.Now().After(lastAccess.Add(ttl))

		},

		touchOnRead: true,

	}

}

// Item wraps a cached value with an absolute expiration timestamp.

type Item[V any] struct {

	Object     V

	Expiration time.Time     // absolute write-time deadline; zero means no expiration

	LastAccess time.Time     // last access time; used by SlidingTTL

	TTL        time.Duration // resolved TTL used to compute Expiration

}

type keyAndValue[K comparable, V any] struct {

	key   K

	value V

}

// cache is the internal unexported implementation.

type cache[K comparable, V any] struct {

	defaultExpiration time.Duration

	items             map[K]Item[V]

	mu                sync.RWMutex

	onDeletion        func(K, V, DeletionCause)

	policy            ExpirationPolicy

	touchOnRead       bool // when true, reads update LastAccess (e.g. SlidingTTL)

}

// Cache is the exported handle embedding *cache plus janitor.

type Cache[K comparable, V any] struct {

	*cache[K, V]

	janitor *janitor[K, V]

}

func (c *cache[K, V]) isExpired(item Item[V]) bool {

	return c.policy.isExpired(item.Expiration, item.LastAccess, item.TTL)

}

func (c *cache[K, V]) resolveTTL(d time.Duration) time.Duration {

	if d == DefaultExpiration {

		return c.defaultExpiration

	}

	return d

}

func (c *cache[K, V]) getExpiration(d time.Duration) time.Time {

	d = c.resolveTTL(d)

	if d > 0 {

		return time.Now().Add(d)

	}

	return time.Time{}

}

func (c *cache[K, V]) set(k K, x V, d time.Duration) {

	resolved := c.resolveTTL(d)

	now := time.Now()

	c.items[k] = Item[V]{

		Object:     x,

		Expiration: c.getExpiration(d),

		LastAccess: now,

		TTL:        resolved,

	}

}

func (c *cache[K, V]) get(k K) (V, bool) {

	item, found := c.items[k]

	if !found {

		return fn.Zero[V](), false

	}

	if c.isExpired(item) {

		return fn.Zero[V](), false

	}

	return item.Object, true

}

func (c *cache[K, V]) touchAccess(k K) {

	if item, found := c.items[k]; found {

		item.LastAccess = time.Now()

		c.items[k] = item

	}

}

func (c *cache[K, V]) delete(key K) (V, bool, bool) {

	item, found := c.items[key]

	if !found {

		return fn.Zero[V](), false, false

	}

	delete(c.items, key)

	if c.onDeletion != nil {

		return item.Object, true, true

	}

	return fn.Zero[V](), true, false

}

// Set stores the value x for the key k with the given expiration duration.

func (c *cache[K, V]) Set(k K, x V, d time.Duration) {

	c.mu.Lock()

	c.set(k, x, d)

	c.mu.Unlock()

}

// SetDefault stores the value x for the key k using the cache's default

// expiration.

func (c *cache[K, V]) SetDefault(k K, x V) {

	c.Set(k, x, DefaultExpiration)

}

// Add inserts x for k only if k is absent or expired. It returns

// ErrAlreadyExists if a live entry already exists.

func (c *cache[K, V]) Add(k K, x V, d time.Duration) error {

	c.mu.Lock()

	_, found := c.get(k)

	if found {

		c.mu.Unlock()

		return ErrAlreadyExists

	}

	c.set(k, x, d)

	c.mu.Unlock()

	return nil

}

// Replace updates the value for k only if k is present and unexpired. It

// returns ErrNotExists if the key is missing or expired.

func (c *cache[K, V]) Replace(k K, x V, d time.Duration) error {

	c.mu.Lock()

	_, found := c.get(k)

	if !found {

		c.mu.Unlock()

		return ErrNotExists

	}

	c.set(k, x, d)

	c.mu.Unlock()

	return nil

}

// Touch refreshes the expiration on an existing non-expired item. It returns

// true if the key was found and refreshed.

func (c *cache[K, V]) Touch(k K, d time.Duration) bool {

	c.mu.Lock()

	item, found := c.items[k]

	if !found {

		c.mu.Unlock()

		return false

	}

	if c.isExpired(item) {

		c.mu.Unlock()

		return false

	}

	resolved := c.resolveTTL(d)

	item.Expiration = c.getExpiration(d)

	item.LastAccess = time.Now()

	item.TTL = resolved

	c.items[k] = item

	c.mu.Unlock()

	return true

}

// GetWithTouch atomically retrieves the value for k and refreshes its

// expiration. Returns (zero, false) if the key is missing or expired.

func (c *cache[K, V]) GetWithTouch(k K, d time.Duration) (V, bool) {

	c.mu.Lock()

	item, found := c.items[k]

	if !found {

		c.mu.Unlock()

		return fn.Zero[V](), false

	}

	if c.isExpired(item) {

		c.mu.Unlock()

		return fn.Zero[V](), false

	}

	resolved := c.resolveTTL(d)

	item.Expiration = c.getExpiration(d)

	item.LastAccess = time.Now()

	item.TTL = resolved

	c.items[k] = item

	c.mu.Unlock()

	return item.Object, true

}

// Delete removes the key k from the cache. If an onDeletion callback is

// registered, it is called after the lock is released.

func (c *cache[K, V]) Delete(k K) {

	c.mu.Lock()

	v, present, hasCallback := c.delete(k)

	c.mu.Unlock()

	if present && hasCallback {

		c.onDeletion(k, v, Deleted)

	}

}

// DeleteExpired removes all expired items from the cache. If an onDeletion

// callback is registered, it is called for each evicted item after the lock

// is released.

func (c *cache[K, V]) DeleteExpired() {

	var evicted []keyAndValue[K, V]

	c.mu.Lock()

	for k, item := range c.items {

		if c.isExpired(item) {

			v, _, hasCallback := c.delete(k)

			if hasCallback {

				evicted = append(evicted, keyAndValue[K, V]{key: k, value: v})

			}

		}

	}

	c.mu.Unlock()

	for _, kv := range evicted {

		c.onDeletion(kv.key, kv.value, Evicted)

	}

}

// Flush removes all items from the cache.

func (c *cache[K, V]) Flush() {

	c.mu.Lock()

	c.items = make(map[K]Item[V])

	c.mu.Unlock()

}

// Get returns the value for k if it exists and is not expired. The second

// return value indicates whether the key was found. Expired items are not

// deleted by Get.

func (c *cache[K, V]) Get(k K) (V, bool) {

	if c.touchOnRead {

		c.mu.Lock()

		v, found := c.get(k)

		if found {

			c.touchAccess(k)

		}

		c.mu.Unlock()

		return v, found

	}

	c.mu.RLock()

	v, found := c.get(k)

	c.mu.RUnlock()

	return v, found

}

// GetWithExpiration returns the value and expiration time for k. The third

// return value indicates whether the key was found and unexpired. A zero

// expiration time means the item does not expire.

func (c *cache[K, V]) GetWithExpiration(k K) (V, time.Time, bool) {

	if c.touchOnRead {

		c.mu.Lock()

		item, found := c.items[k]

		if !found {

			c.mu.Unlock()

			return fn.Zero[V](), time.Time{}, false

		}

		if c.isExpired(item) {

			c.mu.Unlock()

			return fn.Zero[V](), time.Time{}, false

		}

		c.touchAccess(k)

		c.mu.Unlock()

		return item.Object, item.Expiration, true

	}

	c.mu.RLock()

	item, found := c.items[k]

	if !found {

		c.mu.RUnlock()

		return fn.Zero[V](), time.Time{}, false

	}

	if c.isExpired(item) {

		c.mu.RUnlock()

		return fn.Zero[V](), time.Time{}, false

	}

	c.mu.RUnlock()

	return item.Object, item.Expiration, true

}

// ItemList returns a snapshot of all non-expired items in the cache.

func (c *cache[K, V]) ItemList() map[K]Item[V] {

	c.mu.RLock()

	rv := make(map[K]Item[V], len(c.items))

	for k, item := range c.items {

		if !c.isExpired(item) {

			rv[k] = item

		}

	}

	c.mu.RUnlock()

	return rv

}

// ItemIterator returns a lazy iterator over all non-expired items in the

// cache. The iterator yields collect.Tuple2 pairs of (key, Item).

func (c *cache[K, V]) ItemIterator() collect.ListIterator[collect.Tuple2[K, Item[V]]] {

	c.mu.RLock()

	keys := make([]K, 0, len(c.items))

	for k := range c.items {

		keys = append(keys, k)

	}

	c.mu.RUnlock()

	pos := 0

	return collect.NewListIterator(func() (collect.Tuple2[K, Item[V]], bool) {

		for pos < len(keys) {

			k := keys[pos]

			pos++

			c.mu.RLock()

			item, found := c.items[k]

			c.mu.RUnlock()

			if found && !c.isExpired(item) {

				return collect.NewTuple2(k, item), true

			}

		}

		return fn.Zero[collect.Tuple2[K, Item[V]]](), false

	}, len(keys))

}

// ItemCount returns the number of items in the cache, including expired items

// that have not yet been swept.

func (c *cache[K, V]) ItemCount() int {

	c.mu.RLock()

	n := len(c.items)

	c.mu.RUnlock()

	return n

}

// GetOrInsert atomically retrieves the value for k or inserts insertV if k is

// missing or expired. It returns the value and true if the key was already

// present and valid, or (insertV, false) if the value was inserted. Eviction

// callbacks fire after the lock is released.

func (c *cache[K, V]) GetOrInsert(k K, insertV V, insertD time.Duration) (V, bool) {

	var evicted *keyAndValue[K, V]

	c.mu.Lock()

	item, found := c.items[k]

	if found && !c.isExpired(item) {

		if c.touchOnRead {

			c.touchAccess(k)

		}

		c.mu.Unlock()

		return item.Object, true

	}

	if found {

		// expired — evict

		v, _, hasCallback := c.delete(k)

		if hasCallback {

			evicted = &keyAndValue[K, V]{key: k, value: v}

		}

	}

	c.set(k, insertV, insertD)

	c.mu.Unlock()

	if evicted != nil {

		c.onDeletion(evicted.key, evicted.value, Evicted)

	}

	return insertV, false

}

// OnDeletion sets the deletion callback. Deprecated: use OnDeletionAppend.

func (c *cache[K, V]) OnDeletion(f func(K, V, DeletionCause)) {

	c.mu.Lock()

	c.onDeletion = f

	c.mu.Unlock()

}

// OnDeletionAppend prepends f in front of the existing callback chain. If f

// is nil the callback is disabled entirely.

func (c *cache[K, V]) OnDeletionAppend(f func(K, V, DeletionCause)) {

	c.mu.Lock()

	if f == nil {

		c.onDeletion = nil

		c.mu.Unlock()

		return

	}

	prev := c.onDeletion

	if prev == nil {

		c.onDeletion = f

	} else {

		c.onDeletion = func(k K, v V, cause DeletionCause) {

			f(k, v, cause)

			prev(k, v, cause)

		}

	}

	c.mu.Unlock()

}

// Start starts the background janitor goroutine for periodic expiry sweeping.

func (c *Cache[K, V]) Start(ctx context.Context) {

	c.janitor.Start(ctx)

}

// Stop stops the background janitor goroutine.

func (c *Cache[K, V]) Stop() {

	c.janitor.Stop()

}

func newCache[K comparable, V any](defaultExpiration time.Duration, items map[K]Item[V], policy ExpirationPolicy) *cache[K, V] {

	if defaultExpiration == 0 {

		defaultExpiration = NoExpiration

	}

	if items == nil {

		items = make(map[K]Item[V])

	}

	if policy.isExpired == nil {

		policy = WriteTTL()

	}

	return &cache[K, V]{

		defaultExpiration: defaultExpiration,

		items:             items,

		policy:            policy,

		touchOnRead:       policy.touchOnRead,

	}

}

func newCacheWithJanitor[K comparable, V any](ctx context.Context, defaultExpiration, cleanupInterval time.Duration, items map[K]Item[V], started bool, policy ExpirationPolicy) *Cache[K, V] {

	c := newCache(defaultExpiration, items, policy)

	j := newJanitor(c, cleanupInterval)

	C := &Cache[K, V]{cache: c, janitor: j}

	if started {

		j.Start(ctx)

	}

	return C

}

// New creates a new Cache with the given default expiration and cleanup

// interval. The background janitor is started immediately with

// context.Background.

func New[K comparable, V any](defaultExpiration, cleanupInterval time.Duration) *Cache[K, V] {

	return newCacheWithJanitor[K, V](context.Background(), defaultExpiration, cleanupInterval, nil, true, ExpirationPolicy{})

}

// NewWithPolicy creates a new Cache with the given default expiration, cleanup

// interval, and expiration policy. The background janitor is started

// immediately with context.Background.

func NewWithPolicy[K comparable, V any](defaultExpiration, cleanupInterval time.Duration, policy ExpirationPolicy) *Cache[K, V] {

	return newCacheWithJanitor[K, V](context.Background(), defaultExpiration, cleanupInterval, nil, true, policy)

}

// NewInitialized creates a new Cache with the given default expiration and

// cleanup interval but does NOT start the background janitor. The caller must

// call Start to begin periodic expiry sweeping.

func NewInitialized[K comparable, V any](defaultExpiration, cleanupInterval time.Duration) *Cache[K, V] {

	return newCacheWithJanitor[K, V](context.Background(), defaultExpiration, cleanupInterval, nil, false, ExpirationPolicy{})

}

// NewInitializedWithPolicy creates a new Cache with the given default

// expiration, cleanup interval, and expiration policy but does NOT start the

// background janitor. The caller must call Start to begin periodic expiry

// sweeping.

func NewInitializedWithPolicy[K comparable, V any](defaultExpiration, cleanupInterval time.Duration, policy ExpirationPolicy) *Cache[K, V] {

	return newCacheWithJanitor[K, V](context.Background(), defaultExpiration, cleanupInterval, nil, false, policy)

}

// NewFromItems creates a new Cache pre-seeded with items. The background

// janitor is started immediately with context.Background.

func NewFromItems[K comparable, V any](defaultExpiration, cleanupInterval time.Duration, items map[K]Item[V]) *Cache[K, V] {

	return newCacheWithJanitor(context.Background(), defaultExpiration, cleanupInterval, items, true, ExpirationPolicy{})

}

// NewFromItemsWithPolicy creates a new Cache pre-seeded with items and using

// the given expiration policy. The background janitor is started immediately

// with context.Background.

func NewFromItemsWithPolicy[K comparable, V any](defaultExpiration, cleanupInterval time.Duration, items map[K]Item[V], policy ExpirationPolicy) *Cache[K, V] {

	return newCacheWithJanitor(context.Background(), defaultExpiration, cleanupInterval, items, true, policy)

}