redis-memo 0.1.0 → 1.0.0

data/lib/redis_memo/memoizable.rb

@@ -1,119 +1,156 @@
 # frozen_string_literal: true
 
+require_relative 'util'
+
+# A +RedisMemo::Memoizable+ is a unit which represent a dependency on a memoized method.
+# Dependencies can be declared recursively as a DAG (directed acyclic graph), meaning
+# that a +RedisMemo::Memoizable+ object can have other +RedisMemo::Memoizable+ dependencies.
+#
+# @example
+#   memo = RedisMemo::Memoizable.new(a: 1) do
+#     depends_on RedisMemo::Memoizable.new(b: 3)
+#     depends_on RedisMemo::Memoizable.new(c: 4)
+#   end
+#
+#   memoize_method :method_name do
+#     depends_on memo
+#   end
+#
+# RedisMemo will recursively extract all the dependencies in the DAG when computing a
+# memoized method's versioned cache key.
 class RedisMemo::Memoizable
   require_relative 'memoizable/dependency'
   require_relative 'memoizable/invalidation'
 
+  # @return [Hash] prop values on the current memoizable
   attr_accessor :props
+
+  # @return [Proc] A proc representing other memoizables that this object depends on.
   attr_reader :depends_on
 
+  # Creates a new +RedisMemo::Memoizable+ object.
+  #
+  # @param props [Hash]
+  # @yield depends_on A dependency block representing other +RedisMemo::Memoizable+s
+  #        that this object depends on.
   def initialize(**props, &depends_on)
     @props = props
     @depends_on = depends_on
     @cache_key = nil
   end
 
+  # Add extra props on the current RedisMemo::Memoizable+ object.
+  #
+  # @params args [Hash]
   def extra_props(**args)
     instance = dup
     instance.props = props.dup.merge(**args)
     instance
   end
 
+  # Computes the checksum of the memoizable's prop values, and returns it as the cache key.
   def cache_key
     @cache_key ||= [
       self.class.name,
-      RedisMemo.checksum(
-        RedisMemo.deep_sort_hash(@props).to_json,
+      RedisMemo::Util.checksum(
+        RedisMemo::Util.deep_sort_hash(@props).to_json,
       ),
     ].join(':')
   end
 
-  # Calculate the checksums for all memoizable groups in one Redis round trip
-  def self.checksums(instances_groups)
-    dependents_cache_keys = []
-    cache_key_groups = instances_groups.map do |instances|
-      cache_keys = instances.map(&:cache_key)
-      dependents_cache_keys += cache_keys
-      cache_keys
-    end
-
-    dependents_cache_keys.uniq!
-    dependents_versions = find_or_create_versions(dependents_cache_keys)
-    version_hash = dependents_cache_keys.zip(dependents_versions).to_h
-
-    cache_key_groups.map do |cache_keys|
-      RedisMemo.checksum(version_hash.slice(*cache_keys).to_json)
-    end
-  end
-
+  # Invalidates the list of +RedisMemo::Memoizable+ objects by bumping the version stored
+  # in Redis.
+  #
+  # @param instances [Array[RedisMemo::Memoizable]]
   def self.invalidate(instances)
     instances.each do |instance|
       cache_key = instance.cache_key
-      RedisMemo::Memoizable::Invalidation.bump_version_later(
+      RedisMemo::Memoizable::Invalidation.__send__(
+        :bump_version_later,
         cache_key,
-        RedisMemo.uuid,
+        RedisMemo::Util.uuid,
       )
     end
 
     RedisMemo::Memoizable::Invalidation.drain_invalidation_queue
   end
 
-  private
-
-  def self.find_or_create_versions(keys)
-    need_to_bump_versions = false
-
-    # Must check the local pending_memo_versions first in order to generate
-    # memo checksums. The pending_memo_versions are the expected versions that
-    # would be used if a transaction commited. With checksums consistent of
-    # pending versions, the method results would only be visible after a
-    # transaction commited (we bump the pending_memo_versions on redis as an
-    # after_commit callback)
-    if RedisMemo::AfterCommit.in_transaction?
-      memo_versions = RedisMemo::AfterCommit.pending_memo_versions.slice(*keys)
-    else
-      memo_versions = {}
-    end
+  class << self
+    private
 
-    keys_to_fetch = keys
-    keys_to_fetch -= memo_versions.keys unless memo_versions.empty?
+    def checksums(instances_groups)
+      dependents_cache_keys = []
+      cache_key_groups = instances_groups.map do |instances|
+        cache_keys = instances.map(&:cache_key)
+        dependents_cache_keys += cache_keys
+        cache_keys
+      end
 
-    cached_versions =
-      if keys_to_fetch.empty?
-        {}
-      else
-        RedisMemo::Cache.read_multi(
-          *keys_to_fetch,
-          raw: true,
-          raise_error: true,
-        )
+      dependents_cache_keys.uniq!
+      dependents_versions = find_or_create_versions(dependents_cache_keys)
+      version_hash = dependents_cache_keys.zip(dependents_versions).to_h
+
+      cache_key_groups.map do |cache_keys|
+        RedisMemo::Util.checksum(version_hash.slice(*cache_keys).to_json)
       end
-    memo_versions.merge!(cached_versions) unless cached_versions.empty?
-
-    versions = keys.map do |key|
-      version = memo_versions[key]
-      if version.nil?
-        # If a version does not exist, we assume it's because the version has
-        # expired due to TTL or it's evicted by a cache eviction policy. In
-        # this case, we will create a new version and use it for memoizing the
-        # cached result.
-        need_to_bump_versions = true
-
-        new_version = RedisMemo.uuid
-        RedisMemo::Memoizable::Invalidation.bump_version_later(
-          key,
-          new_version,
-          previous_version: '',
-        )
-        new_version
+    end
+
+    def find_or_create_versions(keys)
+      need_to_bump_versions = false
+
+      # Must check the local pending_memo_versions first in order to generate
+      # memo checksums. The pending_memo_versions are the expected versions that
+      # would be used if a transaction commited. With checksums consistent of
+      # pending versions, the method results would only be visible after a
+      # transaction commited (we bump the pending_memo_versions on redis as an
+      # after_commit callback)
+      if RedisMemo::AfterCommit.in_transaction?
+        memo_versions = RedisMemo::AfterCommit.pending_memo_versions.slice(*keys)
       else
-        version
+        memo_versions = {}
+      end
+
+      keys_to_fetch = keys
+      keys_to_fetch -= memo_versions.keys unless memo_versions.empty?
+
+      cached_versions =
+        if keys_to_fetch.empty?
+          {}
+        else
+          RedisMemo::Cache.read_multi(
+            *keys_to_fetch,
+            raw: true,
+            raise_error: true,
+          )
+        end
+      memo_versions.merge!(cached_versions) unless cached_versions.empty?
+
+      versions = keys.map do |key|
+        version = memo_versions[key]
+        if version.nil?
+          # If a version does not exist, we assume it's because the version has
+          # expired due to TTL or it's evicted by a cache eviction policy. In
+          # this case, we will create a new version and use it for memoizing the
+          # cached result.
+          need_to_bump_versions = true
+
+          new_version = RedisMemo::Util.uuid
+          RedisMemo::Memoizable::Invalidation.__send__(
+            :bump_version_later,
+            key,
+            new_version,
+            previous_version: '',
+          )
+          new_version
+        else
+          version
+        end
       end
-    end
 
-    # Flush out the versions to Redis (async) if we created new versions
-    RedisMemo::Memoizable::Invalidation.drain_invalidation_queue if need_to_bump_versions
+      # Flush out the versions to Redis (async) if we created new versions
+      RedisMemo::Memoizable::Invalidation.drain_invalidation_queue if need_to_bump_versions
 
-    versions
+      versions
+    end
   end
 end

data/lib/redis_memo/memoizable/bump_version.lua

@@ -0,0 +1,39 @@
+--[[
+Script to bump the version of a memoizable's cache key.
+
+RedisMemo can be used safely within transactions because it implements multi
+version concurrency control (MVCC).
+
+Before bumping dependency versions, RedisMemo will save its current version
+prior to the update. While bumping the version on Redis, RedisMemo would check
+if the current version still matches the expectation (in a Lua script to ensure atomicity).
+If not, we would use a different version that has not been used before, thus
+we have automatically invalidated the records that are being updated by overlapping
+transactions.
+
+Note: When Redis memory is full, bumping versions only works on Redis versions 6.x.
+Prior versions of Redis have a bug in Lua where an OOM error is thrown instead of
+eviction when Redis memory is full https://github.com/redis/redis/issues/6565
+
+--   KEYS = cache_key
+--   ARGV = [expected_prev_version desired_new_version version_on_mismatch ttl]
+--]]
+local key = KEYS[1]
+local expected_prev_version,
+      desired_new_version,
+      version_on_mismatch,
+      ttl = unpack(ARGV)
+
+local actual_prev_version = redis.call('get', key)
+local new_version = version_on_mismatch
+local px = {}
+
+if (not actual_prev_version and expected_prev_version == '') or expected_prev_version == actual_prev_version then
+  new_version = desired_new_version
+end
+
+if ttl ~= '' then
+  px = {'px', ttl}
+end
+
+return redis.call('set', key, new_version, unpack(px))

data/lib/redis_memo/memoizable/dependency.rb

@@ -12,13 +12,14 @@ class RedisMemo::Memoizable::Dependency
     @nodes.values
   end
 
-  def depends_on(dependency, **conditions)
+  def depends_on(dependency)
     case dependency
     when self.class
       nodes.merge!(dependency.nodes)
     when RedisMemo::Memoizable
       memo = dependency
       return if nodes.include?(memo.cache_key)
+
       nodes[memo.cache_key] = memo
 
       if memo.depends_on
@@ -40,25 +41,24 @@ class RedisMemo::Memoizable::Dependency
         end
       end
     else
-      raise(
-        RedisMemo::ArgumentError,
-        "Invalid dependency #{dependency}"
-      )
+      raise RedisMemo::ArgumentError.new("Invalid dependency #{dependency}")
     end
   end
 
-  private
-
   def self.extract_from_relation(relation)
+    connection = ActiveRecord::Base.connection
+    unless connection.respond_to?(:dependency_of)
+      raise RedisMemo::WithoutMemoization.new('Caching active record queries is currently disabled on RedisMemo')
+    end
+
     # Extract the dependent memos of an Arel without calling exec_query to actually execute the query
     RedisMemo::MemoizeQuery::CachedSelect.with_new_query_context do
-      connection = ActiveRecord::Base.connection
-      query, binds, _ = connection.send(:to_sql_and_binds, relation.arel)
+      query, binds, = connection.__send__(:to_sql_and_binds, relation.arel)
       RedisMemo::MemoizeQuery::CachedSelect.current_query = relation.arel
       is_query_cached = RedisMemo::MemoizeQuery::CachedSelect.extract_bind_params(query)
 
       unless is_query_cached
-        raise RedisMemo::WithoutMemoization, 'Arel query is not cached using RedisMemo'
+        raise RedisMemo::WithoutMemoization.new('Arel query is not cached using RedisMemo')
       end
 
       connection.dependency_of(:exec_query, query, nil, binds)

data/lib/redis_memo/memoizable/invalidation.rb

@@ -1,7 +1,10 @@
 # frozen_string_literal: true
+
+require 'digest'
 require_relative '../after_commit'
 require_relative '../cache'
 
+# Module containing the logic to perform invalidation on +RedisMemo::Memoizable+s.
 module RedisMemo::Memoizable::Invalidation
   class Task
     attr_reader :key
@@ -44,36 +47,9 @@ module RedisMemo::Memoizable::Invalidation
   # operations that triggered the invalidation has not yet happened.
   @@invalidation_queue = Queue.new
 
-  def self.bump_version_later(key, version, previous_version: nil)
-    if RedisMemo::AfterCommit.in_transaction?
-      previous_version ||= RedisMemo::AfterCommit.pending_memo_versions[key]
-    end
-
-    local_cache = RedisMemo::Cache.local_cache
-    if previous_version.nil? && local_cache&.include?(key)
-      previous_version = local_cache[key]
-    elsif RedisMemo::AfterCommit.in_transaction?
-      # Fill an expected previous version so the later calculation results
-      # based on this version can still be rolled out if this version
-      # does not change
-      previous_version ||= RedisMemo::Cache.read_multi(
-        key,
-        raw: true,
-      )[key]
-    end
-
-    local_cache&.send(:[]=, key, version)
-    if RedisMemo::AfterCommit.in_transaction?
-      RedisMemo::AfterCommit.bump_memo_version_after_commit(
-        key,
-        version,
-        previous_version: previous_version,
-      )
-    else
-      @@invalidation_queue << Task.new(key, version, previous_version)
-    end
-  end
-
+  # Drains the invalidation queue by bumping the versions of all memoizable cache
+  # keys currently in the queue. Performs invalidation asynchronously if an async
+  # handler is configured; otherwise, invaidation is done synchronously.
   def self.drain_invalidation_queue
     async_handler = RedisMemo::DefaultOptions.async
     if async_handler.nil?
@@ -85,41 +61,15 @@ module RedisMemo::Memoizable::Invalidation
     end
   end
 
-  LUA_BUMP_VERSION = <<~LUA
-    local key = KEYS[1]
-    local expected_prev_version,
-          desired_new_version,
-          version_on_mismatch,
-          ttl = unpack(ARGV)
-
-    local actual_prev_version = redis.call('get', key)
-    local new_version = version_on_mismatch
-    local px = {}
-
-    if (not actual_prev_version and expected_prev_version == '') or expected_prev_version == actual_prev_version then
-      new_version = desired_new_version
-    end
-
-    if ttl ~= '' then
-      px = {'px', ttl}
-    end
-
-    return redis.call('set', key, new_version, unpack(px))
-  LUA
-
-  def self.bump_version(task)
-    RedisMemo::Tracer.trace('redis_memo.memoizable.bump_version', task.key) do
-      ttl = RedisMemo::DefaultOptions.expires_in
-      ttl = (ttl * 1000.0).to_i if ttl
-      RedisMemo::Cache.redis.eval(
-        LUA_BUMP_VERSION,
-        keys: [task.key],
-        argv: [task.previous_version, task.version, RedisMemo.uuid, ttl],
-      )
-      RedisMemo::Tracer.set_tag(enqueue_to_finish: task.duration)
-    end
-  end
+  LUA_BUMP_VERSION = File.read(
+    File.join(File.dirname(__FILE__), 'bump_version.lua'),
+  )
+  private_constant :LUA_BUMP_VERSION
 
+  # Drains the invalidation queue synchronously by bumping the versions of all
+  # memoizable cache keys currently in the queue. If invalidation on a cache key
+  # fails due to transient Redis errors, the key is put back into the invalidation
+  # queue and retried on the next invalidation queue drain.
   def self.drain_invalidation_queue_now
     retry_queue = []
     until @@invalidation_queue.empty?
@@ -127,16 +77,68 @@ module RedisMemo::Memoizable::Invalidation
       begin
         bump_version(task)
       rescue SignalException, Redis::BaseConnectionError,
-             ::ConnectionPool::TimeoutError
+             ::ConnectionPool::TimeoutError => error
+
+        RedisMemo::DefaultOptions.redis_error_handler&.call(error, __method__)
+        RedisMemo::DefaultOptions.logger&.warn(error.full_message)
         retry_queue << task
       end
     end
   ensure
-    retry_queue.each { |task| @@invalidation_queue << task }
+    retry_queue.each { |t| @@invalidation_queue << t }
   end
 
   at_exit do
     # The best effort
     drain_invalidation_queue_now
   end
+
+  class << self
+    private
+
+    def bump_version_later(key, version, previous_version: nil)
+      if RedisMemo::AfterCommit.in_transaction?
+        previous_version ||= RedisMemo::AfterCommit.pending_memo_versions[key]
+      end
+
+      local_cache = RedisMemo::Cache.local_cache
+      if previous_version.nil? && local_cache&.include?(key)
+        previous_version = local_cache[key]
+      elsif RedisMemo::AfterCommit.in_transaction?
+        # Fill an expected previous version so the later calculation results
+        # based on this version can still be rolled out if this version
+        # does not change
+        previous_version ||= RedisMemo::Cache.read_multi(
+          key,
+          raw: true,
+        )[key]
+      end
+
+      local_cache&.__send__(:[]=, key, version)
+      if RedisMemo::AfterCommit.in_transaction?
+        RedisMemo::AfterCommit.bump_memo_version_after_commit(
+          key,
+          version,
+          previous_version: previous_version,
+        )
+      else
+        @@invalidation_queue << Task.new(key, version, previous_version)
+      end
+    end
+
+    def bump_version(task)
+      RedisMemo::Tracer.trace('redis_memo.memoizable.bump_version', task.key) do
+        ttl = RedisMemo::DefaultOptions.expires_in
+        ttl = (ttl * 1000.0).to_i if ttl
+        @@bump_version_sha ||= Digest::SHA1.hexdigest(LUA_BUMP_VERSION)
+        RedisMemo::Cache.redis.run_script(
+          LUA_BUMP_VERSION,
+          @@bump_version_sha,
+          keys: [task.key],
+          argv: [task.previous_version, task.version, RedisMemo::Util.uuid, ttl],
+        )
+        RedisMemo::Tracer.set_tag(enqueue_to_finish: task.duration)
+      end
+    end
+  end
 end