safe_memoize 1.0.0 → 1.2.0

data/lib/safe_memoize/stores/base.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Stores
+    # Abstract base class for SafeMemoize cache store adapters.
+    #
+    # Subclass this and implement all abstract methods to plug in a custom backend
+    # (Redis, Memcached, Rails.cache, etc.). The {Stores::Memory} class is the
+    # built-in reference implementation.
+    #
+    # @abstract
+    #
+    # @example Minimal inline implementation
+    #   class MyStore < SafeMemoize::Stores::Base
+    #     def initialize = (@h = {})
+    #     def read(key) = @h.fetch(key, MISS)
+    #     def write(key, value, expires_in: nil) = (@h[key] = value)
+    #     def delete(key) = @h.delete(key)
+    #     def clear = @h.clear
+    #     def keys = @h.keys
+    #   end
+    class Base
+      # Sentinel returned by {#read} to signal a cache miss.
+      #
+      # Distinct from +nil+ and +false+, which are valid cached values.
+      MISS = Object.new.freeze
+
+      # Read a value from the store.
+      #
+      # @param key [Object] cache key
+      # @return [Object] the stored value, or {MISS} if absent or expired
+      # @abstract
+      def read(key)
+        raise NotImplementedError, "#{self.class}#read must be implemented"
+      end
+
+      # Write a value to the store.
+      #
+      # @param key [Object] cache key
+      # @param value [Object] value to cache (may be +nil+ or +false+)
+      # @param expires_in [Numeric, nil] seconds until expiry; +nil+ means no expiry
+      # @return [void]
+      # @abstract
+      def write(key, value, expires_in: nil)
+        raise NotImplementedError, "#{self.class}#write must be implemented"
+      end
+
+      # Delete a single entry.
+      #
+      # @param key [Object] cache key
+      # @return [void]
+      # @abstract
+      def delete(key)
+        raise NotImplementedError, "#{self.class}#delete must be implemented"
+      end
+
+      # Remove all entries from the store.
+      #
+      # @return [void]
+      # @abstract
+      def clear
+        raise NotImplementedError, "#{self.class}#clear must be implemented"
+      end
+
+      # Return all live (non-expired) keys.
+      #
+      # @return [Array<Object>]
+      # @abstract
+      def keys
+        raise NotImplementedError, "#{self.class}#keys must be implemented"
+      end
+
+      # Check whether a live entry exists for the given key.
+      #
+      # The default delegates to {#read}; subclasses may override for stores
+      # with a native existence check.
+      #
+      # @param key [Object]
+      # @return [Boolean]
+      def exist?(key)
+        read(key) != MISS
+      end
+    end
+  end
+end

data/lib/safe_memoize/stores/memory.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module SafeMemoize
+  module Stores
+    # Default in-process cache store backed by a plain +Hash+.
+    #
+    # Thread-safe via an internal +Mutex+. Supports per-entry TTL with lazy
+    # expiry: stale entries are not proactively removed but are treated as
+    # misses on read and excluded from {#keys}.
+    class Memory < Base
+      def initialize
+        @data = {}
+        @mutex = Mutex.new
+      end
+
+      # @param key [Object]
+      # @return [Object] stored value, or {MISS} if absent or expired
+      def read(key)
+        @mutex.synchronize do
+          entry = @data[key]
+          return MISS unless entry
+          return MISS if expired?(entry)
+
+          entry[:value]
+        end
+      end
+
+      # @param key [Object]
+      # @param value [Object]
+      # @param expires_in [Numeric, nil] seconds until expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        expires_at = expires_in ? now + expires_in.to_f : nil
+
+        @mutex.synchronize do
+          @data[key] = {value: value, expires_at: expires_at, cached_at: now}
+        end
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @mutex.synchronize { @data.delete(key) }
+      end
+
+      # Removes all entries.
+      # @return [void]
+      def clear
+        @mutex.synchronize { @data.clear }
+      end
+
+      # Returns all live (non-expired) keys.
+      # @return [Array<Object>]
+      def keys
+        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @mutex.synchronize do
+          @data.filter_map { |k, entry| k unless entry[:expires_at] && entry[:expires_at] <= now }
+        end
+      end
+
+      private
+
+      def expired?(entry)
+        expires_at = entry[:expires_at]
+        expires_at && expires_at <= Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/safe_memoize/stores/rails_cache.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "safe_memoize"
+
+module SafeMemoize
+  module Stores
+    # Cache store adapter backed by any +ActiveSupport::Cache::Store+.
+    #
+    # Not auto-required. Add to your Rails initializer:
+    #   require "safe_memoize/stores/rails_cache"
+    #
+    # Compatible with any +ActiveSupport::Cache::Store+ implementation
+    # (+MemoryStore+, +FileStore+, +MemCacheStore+, +RedisCacheStore+, etc.)
+    # and with +Rails.cache+ directly.
+    #
+    # Because +ActiveSupport::Cache+ returns +nil+ for both a cache miss and
+    # a cached +nil+ value, this adapter wraps every value in a two-element
+    # sentinel envelope before writing. The envelope is transparent to callers.
+    #
+    # TTL is forwarded as +expires_in:+ to the cache, so the underlying store
+    # manages expiry natively — there is no lazy-expiry overhead on read.
+    #
+    # {#clear} uses +delete_matched+ scoped to the adapter's namespace, so it
+    # never clears entries belonging to other parts of the application. The
+    # backend must respond to +delete_matched+ (all standard Rails cache stores
+    # do); a +NotImplementedError+ is raised if it does not.
+    #
+    # {#keys} returns an empty array — +ActiveSupport::Cache::Store+ does not
+    # expose a standard key enumeration API. Override the method if your
+    # backend supports it.
+    #
+    # @example Basic setup
+    #   # config/initializers/safe_memoize.rb
+    #   require "safe_memoize/stores/rails_cache"
+    #
+    #   MEMO_STORE = SafeMemoize::Stores::RailsCache.new(Rails.cache)
+    #
+    #   class MyService
+    #     prepend SafeMemoize
+    #     def fetch(id) = http_get(id)
+    #     memoize :fetch, store: MEMO_STORE, ttl: 300
+    #   end
+    #
+    # @example Dedicated cache store (recommended for production)
+    #   MEMO_STORE = SafeMemoize::Stores::RailsCache.new(
+    #     ActiveSupport::Cache::RedisCacheStore.new(url: ENV["REDIS_URL"]),
+    #     namespace: "myapp:memo"
+    #   )
+    class RailsCache < Base
+      # Tag prepended to every stored value so cached +nil+/+false+ are
+      # distinguishable from a cache miss.
+      VALUE_TAG = "safe_memoize:v1"
+
+      # @param cache [ActiveSupport::Cache::Store] the cache store to use;
+      #   typically +Rails.cache+ or a dedicated store instance
+      # @param namespace [String] key prefix used to scope all entries;
+      #   defaults to +"safe_memoize"+
+      def initialize(cache, namespace: "safe_memoize")
+        @cache = cache
+        @namespace = namespace
+      end
+
+      # @param key [Object] cache key (serialized with Marshal + Base64)
+      # @return [Object] the stored value, or {MISS} if absent or unrecognised
+      def read(key)
+        raw = @cache.read(cache_key(key))
+        return MISS unless raw.is_a?(Array) && raw.length == 2 && raw[0] == VALUE_TAG
+
+        raw[1]
+      end
+
+      # @param key [Object] cache key
+      # @param value [Object] value to store (may be +nil+ or +false+)
+      # @param expires_in [Numeric, nil] TTL in seconds forwarded to the cache
+      #   as +expires_in:+; +nil+ means no expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        opts = expires_in ? {expires_in: expires_in} : {}
+        @cache.write(cache_key(key), [VALUE_TAG, value], **opts)
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @cache.delete(cache_key(key))
+      end
+
+      # Removes all entries written by this adapter (scoped to the namespace).
+      #
+      # Delegates to +delete_matched+ on the underlying store; raises
+      # +NotImplementedError+ if the store does not support it.
+      #
+      # @return [void]
+      # @raise [NotImplementedError] if the backing store does not respond to
+      #   +delete_matched+
+      def clear
+        unless @cache.respond_to?(:delete_matched)
+          raise NotImplementedError,
+            "#{@cache.class} does not support delete_matched — " \
+            "implement clear manually or use a store that supports it (e.g. MemoryStore, RedisCacheStore)"
+        end
+        @cache.delete_matched(/\A#{Regexp.escape(@namespace)}:/)
+      end
+
+      # Returns an empty array.
+      #
+      # +ActiveSupport::Cache::Store+ does not expose a key enumeration API.
+      # Override this method if your backend supports key listing.
+      #
+      # @return [Array]
+      def keys
+        []
+      end
+
+      # @param key [Object]
+      # @return [Boolean]
+      def exist?(key)
+        @cache.exist?(cache_key(key))
+      end
+
+      private
+
+      def cache_key(key)
+        "#{@namespace}:#{[Marshal.dump(key)].pack("m0")}"
+      end
+    end
+  end
+end

data/lib/safe_memoize/stores/redis.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "safe_memoize"
+
+module SafeMemoize
+  module Stores
+    # Cache store adapter backed by Redis.
+    #
+    # Not auto-required. Add to your application:
+    #   require "safe_memoize/stores/redis"
+    #
+    # Requires a Redis-compatible client that responds to +#get+, +#set+,
+    # +#del+, and +#scan_each+. Compatible with the +redis+ gem (v4+) and
+    # any drop-in replacement.
+    #
+    # Values and keys are serialized with +Marshal+ (Base64-encoded via
+    # +Array#pack("m0")+) so that any Ruby object, including +nil+ and
+    # +false+, can be stored and retrieved faithfully. TTL is forwarded to
+    # Redis as the +PX+ option (milliseconds, rounded up to the nearest
+    # millisecond; minimum 1 ms) to preserve sub-second precision.
+    #
+    # @example Basic setup
+    #   require "redis"
+    #   require "safe_memoize/stores/redis"
+    #
+    #   REDIS_STORE = SafeMemoize::Stores::Redis.new(::Redis.new)
+    #
+    #   class MyService
+    #     prepend SafeMemoize
+    #     def fetch(id) = http_get(id)
+    #     memoize :fetch, store: REDIS_STORE, ttl: 300
+    #   end
+    #
+    # @example With a custom namespace
+    #   STORE = SafeMemoize::Stores::Redis.new(::Redis.new, namespace: "myapp:memo")
+    class Redis < Base
+      # @param client [Object] a Redis-compatible client responding to
+      #   +#get+, +#set+, +#del+, and +#scan_each+
+      # @param namespace [String] key prefix used to scope all entries in Redis;
+      #   defaults to +"safe_memoize"+
+      def initialize(client, namespace: "safe_memoize")
+        @client = client
+        @namespace = namespace
+      end
+
+      # @param key [Object] cache key (serialized with Marshal + Base64)
+      # @return [Object] the stored value, or {MISS} if absent
+      def read(key)
+        raw = @client.get(redis_key(key))
+        return MISS if raw.nil?
+
+        Marshal.load(raw) # rubocop:disable Security/MarshalLoad
+      rescue TypeError, ArgumentError
+        MISS
+      end
+
+      # @param key [Object] cache key
+      # @param value [Object] value to store (may be +nil+ or +false+)
+      # @param expires_in [Numeric, nil] TTL in seconds forwarded to Redis as +PX+
+      #   (milliseconds, rounded up; minimum 1 ms); +nil+ means no expiry
+      # @return [void]
+      def write(key, value, expires_in: nil)
+        raw = Marshal.dump(value)
+        if expires_in
+          @client.set(redis_key(key), raw, px: [(expires_in * 1000).ceil, 1].max)
+        else
+          @client.set(redis_key(key), raw)
+        end
+      end
+
+      # @param key [Object]
+      # @return [void]
+      def delete(key)
+        @client.del(redis_key(key))
+      end
+
+      # Removes all entries written by this adapter (scoped to the namespace).
+      # Uses +SCAN+ internally to avoid blocking Redis.
+      # @return [void]
+      def clear
+        to_delete = []
+        @client.scan_each(match: "#{@namespace}:*") { |k| to_delete << k }
+        @client.del(*to_delete) unless to_delete.empty?
+      end
+
+      # Returns all live keys in the namespace, deserialized back to their
+      # original Ruby form. Entries that cannot be deserialized are silently
+      # skipped. Because Redis handles TTL natively, every key returned by
+      # +SCAN+ is live.
+      #
+      # @return [Array<Object>]
+      def keys
+        prefix = "#{@namespace}:"
+        result = []
+        @client.scan_each(match: "#{@namespace}:*") do |rk|
+          encoded = rk.delete_prefix(prefix)
+          result << Marshal.load(encoded.unpack1("m0")) # rubocop:disable Security/MarshalLoad
+        rescue ArgumentError, TypeError
+          # skip keys that cannot be deserialized (e.g. written by another serializer)
+        end
+        result
+      end
+
+      private
+
+      def redis_key(key)
+        "#{@namespace}:#{[Marshal.dump(key)].pack("m0")}"
+      end
+    end
+  end
+end

data/lib/safe_memoize/version.rb

@@ -2,5 +2,5 @@
 
 module SafeMemoize
   # The current gem version string.
-  VERSION = "1.0.0"
+  VERSION = "1.2.0"
 end

data/lib/safe_memoize.rb

@@ -2,8 +2,11 @@
 
 require_relative "safe_memoize/version"
 require_relative "safe_memoize/configuration"
+require_relative "safe_memoize/stores/base"
+require_relative "safe_memoize/stores/memory"
 require_relative "safe_memoize/adapters/statsd"
 require_relative "safe_memoize/adapters/opentelemetry"
+require_relative "safe_memoize/adapters/concurrent_ruby"
 require_relative "safe_memoize/class_methods"
 require_relative "safe_memoize/public_methods"
 require_relative "safe_memoize/cache_store_methods"
@@ -15,6 +18,8 @@ require_relative "safe_memoize/public_metrics_methods"
 require_relative "safe_memoize/custom_key_methods"
 require_relative "safe_memoize/public_custom_key_methods"
 require_relative "safe_memoize/lru_methods"
+require_relative "safe_memoize/fiber_local_methods"
+require_relative "safe_memoize/ractor_shared_methods"
 require_relative "safe_memoize/instance_methods"
 
 # Thread-safe memoization for Ruby that correctly handles +nil+ and +false+ values.

data/sig/safe_memoize.rbs

@@ -32,13 +32,16 @@ module SafeMemoize
     attr_accessor active_support_notifications: bool
     attr_accessor statsd_client: untyped
     attr_accessor opentelemetry_tracer: untyped
+    attr_accessor default_store: Stores::Base?
 
     def initialize: () -> void
   end
 
   module ClassMethods
-    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?) -> void
-    def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?) -> void
+    def memoize: (Symbol | String method_name, ?ttl: Numeric?, ?max_size: Integer?, ?ttl_refresh: bool, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?store: Stores::Base?, ?fiber_local: bool, ?ractor_safe: bool) -> void
+    def safe_memoize_store: () -> Stores::Base?
+    def safe_memoize_store=: (Stores::Base?) -> Stores::Base?
+    def memoize_all: (?except: Array[Symbol | String], ?only: Array[Symbol | String], ?include_protected: bool, ?include_private: bool, ?ttl: Numeric?, ?max_size: Integer?, ?if: (^(untyped result) -> boolish)?, ?unless: (^(untyped result) -> boolish)?, ?shared: bool, ?key: (^(*untyped args, **untyped kwargs) -> untyped)?, ?fiber_local: bool) -> void
     def reset_shared_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
     def reset_all_shared_memos: () -> void
     def shared_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
@@ -186,6 +189,37 @@ module SafeMemoize
     def lru_clear_all: () -> void
   end
 
+  module FiberLocalMethods
+    FIBER_STORE_KEY: Symbol
+
+    def fiber_local_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
+    def reset_fiber_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
+    def reset_all_fiber_memos: () -> void
+
+    private
+
+    def fiber_root_store!: () -> Hash[untyped, untyped]
+    def fiber_memo_store!: () -> { cache: Hash[memo_key, memo_record], lru: Hash[Symbol, Hash[memo_key, true]] }
+    def fiber_memo_cache!: () -> Hash[memo_key, memo_record]
+    def fiber_memo_lru!: () -> Hash[Symbol, Hash[memo_key, true]]
+    def fiber_root_store_or_nil: () -> Hash[untyped, untyped]?
+    def fiber_memo_store_or_nil: () -> { cache: Hash[memo_key, memo_record], lru: Hash[Symbol, Hash[memo_key, true]] }?
+    def fiber_memo_cache_or_nil: () -> Hash[memo_key, memo_record]?
+    def fiber_memo_lru_or_nil: () -> Hash[Symbol, Hash[memo_key, true]]?
+  end
+
+  module RactorSharedMethods
+    def reset_ractor_memo: (Symbol | String method_name, *untyped args, **untyped kwargs) -> void
+    def reset_all_ractor_memos: () -> void
+    def ractor_memoized?: (Symbol | String method_name, *untyped args, **untyped kwargs) -> bool
+    def ractor_memo_count: (?(Symbol | String) method_name) -> Integer
+
+    private
+
+    def __ractor_cache_send__: (untyped supervisor, Symbol op, *untyped args) -> untyped
+    def __safe_memo_ractor_supervisor__: () -> untyped
+  end
+
   module InstanceMethods
     include PublicMethods
     include CacheStoreMethods
@@ -197,6 +231,33 @@ module SafeMemoize
     include CustomKeyMethods
     include PublicCustomKeyMethods
     include LruMethods
+    include FiberLocalMethods
+  end
+
+  module Stores
+    class Base
+      MISS: Object
+
+      def read: (untyped key) -> untyped
+      def write: (untyped key, untyped value, ?expires_in: Numeric?) -> void
+      def delete: (untyped key) -> void
+      def clear: () -> void
+      def keys: () -> Array[untyped]
+      def exist?: (untyped key) -> bool
+    end
+
+    class Memory < Base
+      def initialize: () -> void
+      def read: (untyped key) -> untyped
+      def write: (untyped key, untyped value, ?expires_in: Numeric?) -> void
+      def delete: (untyped key) -> void
+      def clear: () -> void
+      def keys: () -> Array[untyped]
+
+      private
+
+      def expired?: ({ expires_at: Float?, value: untyped, cached_at: Float }) -> bool
+    end
   end
 
   module Adapters
@@ -210,6 +271,17 @@ module SafeMemoize
       SPAN_NAME: String
       def self.trace: (untyped tracer, Symbol | String method_name, String? class_name) { () -> untyped } -> untyped
     end
+
+    class ConcurrentRuby < Stores::Base
+      def initialize: () -> void
+      def read: (untyped key) -> untyped
+      def write: (untyped key, untyped value, ?expires_in: Numeric?) -> void
+      def delete: (untyped key) -> void
+      def clear: () -> void
+      def keys: () -> Array[untyped]
+      private
+      def expired?: ({ expires_at: Float?, value: untyped, cached_at: Float }) -> bool
+    end
   end
 
   module Rails

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: safe_memoize
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -52,6 +52,7 @@ files:
 - benchmarks/benchmark.rb
 - codecov.yml
 - lib/safe_memoize.rb
+- lib/safe_memoize/adapters/concurrent_ruby.rb
 - lib/safe_memoize/adapters/opentelemetry.rb
 - lib/safe_memoize/adapters/statsd.rb
 - lib/safe_memoize/cache_metrics_methods.rb
@@ -60,6 +61,7 @@ files:
 - lib/safe_memoize/class_methods.rb
 - lib/safe_memoize/configuration.rb
 - lib/safe_memoize/custom_key_methods.rb
+- lib/safe_memoize/fiber_local_methods.rb
 - lib/safe_memoize/hooks_methods.rb
 - lib/safe_memoize/inspection_methods.rb
 - lib/safe_memoize/instance_methods.rb
@@ -67,10 +69,15 @@ files:
 - lib/safe_memoize/public_custom_key_methods.rb
 - lib/safe_memoize/public_methods.rb
 - lib/safe_memoize/public_metrics_methods.rb
+- lib/safe_memoize/ractor_shared_methods.rb
 - lib/safe_memoize/rails.rb
 - lib/safe_memoize/rails/middleware.rb
 - lib/safe_memoize/rails/request_scoped.rb
 - lib/safe_memoize/release_tooling.rb
+- lib/safe_memoize/stores/base.rb
+- lib/safe_memoize/stores/memory.rb
+- lib/safe_memoize/stores/rails_cache.rb
+- lib/safe_memoize/stores/redis.rb
 - lib/safe_memoize/version.rb
 - rbi/safe_memoize.rbi
 - sig/safe_memoize.rbs