Class: Woods::Cache::CacheStore Abstract

Inherits:
Object
  • Object
show all
Defined in:
lib/woods/cache/cache_store.rb

Overview

This class is abstract.

Subclass and override all public methods.

Abstract cache store interface.

All cache backends must implement these methods. The interface is modeled after ActiveSupport::Cache::Store for familiarity but kept minimal.

Direct Known Subclasses

InMemory, RedisCacheStore, SolidCacheStore

Instance Method Summary collapse

Instance Method Details

#clear(namespace: nil) ⇒ void

This method returns an undefined value.

Clear cached entries. If namespace is given, only clear that domain.

Parameters:

  • namespace (Symbol, nil) (defaults to: nil) —

    Cache domain to clear, or nil for all

Raises:

  • (NotImplementedError) 


78
79
80
 
# File 'lib/woods/cache/cache_store.rb', line 78

def clear(namespace: nil)
  raise NotImplementedError
end

#delete(key) ⇒ void

This method returns an undefined value.

Delete a key from the cache.

Parameters:

  • key (String) —

    Cache key

Raises:

  • (NotImplementedError) 


62
63
64
 
# File 'lib/woods/cache/cache_store.rb', line 62

def delete(key)
  raise NotImplementedError
end

#exist?(key) ⇒ Boolean

Check if a key exists and is not expired.

Parameters:

  • key (String) —

    Cache key

Returns:

  • (Boolean)

Raises:

  • (NotImplementedError) 


70
71
72
 
# File 'lib/woods/cache/cache_store.rb', line 70

def exist?(key)
  raise NotImplementedError
end

#fetch(key, ttl: nil) { ... } ⇒ Object

Note:

nil is treated as a cache miss. If the wrapped operation legitimately returns nil, every call will re-execute the block. Custom backend implementers should preserve this semantic — do not return nil for keys that were written with a non-nil value. This is acceptable for the built-in use cases (embeddings and formatted context are never nil).

Read-through cache: return cached value or execute block and cache result.

Parameters:

  • key (String) —

    Cache key

  • ttl (Integer, nil) (defaults to: nil) —

    TTL in seconds

Yields:

  • Block that computes the value on cache miss

Returns:

  • (Object) —

    Cached or freshly computed value



94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/woods/cache/cache_store.rb', line 94

def fetch(key, ttl: nil)
  cached = read(key)
  return cached unless cached.nil?

  value = yield
  begin
    write(key, value, ttl: ttl)
  rescue StandardError => e
    logger.warn("[Woods] CacheStore#fetch write failed for #{key}: #{e.message}")
  end
  value
end

#read(key) ⇒ Object?

Read a value from the cache.

Parameters:

  • key (String) —

    Cache key

Returns:

  • (Object, nil) —

    Cached value or nil if missing/expired

Raises:

  • (NotImplementedError) 


44
45
46
 
# File 'lib/woods/cache/cache_store.rb', line 44

def read(key)
  raise NotImplementedError
end

#write(key, value, ttl: nil) ⇒ void

This method returns an undefined value.

Write a value to the cache.

Parameters:

  • key (String) —

    Cache key

  • value (Object) —

    Value to cache (must be JSON-serializable)

  • ttl (Integer, nil) (defaults to: nil) —

    Time-to-live in seconds (nil = use domain default)

Raises:

  • (NotImplementedError) 


54
55
56
 
# File 'lib/woods/cache/cache_store.rb', line 54

def write(key, value, ttl: nil)
  raise NotImplementedError
end