solid_cache 0.1.0

data/lib/solid_cache/cluster/expiry.rb

@@ -0,0 +1,61 @@
+require "concurrent/atomic/atomic_fixnum"
+
+module SolidCache
+  class Cluster
+    module Expiry
+      # For every write that we do, we attempt to delete EXPIRY_MULTIPLIER times as many records.
+      # This ensures there is downward pressure on the cache size while there is valid data to delete
+      EXPIRY_MULTIPLIER = 1.25
+
+      attr_reader :expiry_batch_size, :expiry_method, :expire_every, :max_age, :max_entries
+
+      def initialize(options = {})
+        super(options)
+        @expiry_batch_size = options.fetch(:expiry_batch_size, 100)
+        @expiry_method = options.fetch(:expiry_method, :thread)
+        @expire_every = [ (expiry_batch_size / EXPIRY_MULTIPLIER).floor, 1 ].max
+        @max_age = options.fetch(:max_age, 2.weeks.to_i)
+        @max_entries = options.fetch(:max_entries, nil)
+
+        raise ArgumentError, "Expiry method must be one of `:thread` or `:job`" unless [ :thread, :job ].include?(expiry_method)
+      end
+
+      def track_writes(count)
+        expire_later if expiry_counter.count(count)
+      end
+
+      private
+        def expire_later
+          if expiry_method == :job
+            ExpiryJob.perform_later(expiry_batch_size, shard: Entry.current_shard, max_age: max_age, max_entries: max_entries)
+          else
+            async { Entry.expire(expiry_batch_size, max_age: max_age, max_entries: max_entries) }
+          end
+        end
+
+        def expiry_counter
+          @expiry_counters ||= connection_names.to_h { |connection_name| [ connection_name, Counter.new(expire_every) ] }
+          @expiry_counters[Entry.current_shard]
+        end
+
+        class Counter
+          attr_reader :expire_every, :counter
+
+          def initialize(expire_every)
+            @expire_every = expire_every
+            @counter = Concurrent::AtomicFixnum.new(rand(expire_every).to_i)
+          end
+
+          def count(count)
+            value = counter.increment(count)
+            new_multiple_of_expire_every?(value - count, value)
+          end
+
+          private
+            def new_multiple_of_expire_every?(first_value, second_value)
+              first_value / expire_every != second_value / expire_every
+            end
+        end
+    end
+  end
+end

data/lib/solid_cache/cluster/stats.rb

@@ -0,0 +1,32 @@
+module SolidCache
+  class Cluster
+    module Stats
+      def initialize(options = {})
+        super()
+      end
+
+      def stats
+        stats = {
+          connections: connections.count,
+          connection_stats: connections_stats
+        }
+      end
+
+      private
+        def connections_stats
+          with_each_connection.to_h { |connection| [ Entry.current_shard, connection_stats ] }
+        end
+
+        def connection_stats
+          oldest_created_at = Entry.order(:id).pick(:created_at)
+
+          {
+            max_age: max_age,
+            oldest_age: oldest_created_at ? Time.now - oldest_created_at : nil,
+            max_entries: max_entries,
+            entries: Entry.id_range
+          }
+        end
+    end
+  end
+end

data/lib/solid_cache/cluster.rb

@@ -0,0 +1,14 @@
+
+module SolidCache
+  class Cluster
+    include Connections, Execution, Expiry, Stats
+
+    def initialize(options = {})
+      super(options)
+    end
+
+    def setup!
+      super
+    end
+  end
+end

data/lib/solid_cache/connections/sharded.rb

@@ -0,0 +1,40 @@
+module SolidCache
+  module Connections
+    class Sharded
+      attr_reader :names, :nodes, :consistent_hash
+
+      def initialize(names, nodes)
+        @names = names
+        @nodes = nodes
+        @consistent_hash = MaglevHash.new(@nodes.keys)
+      end
+
+      def with_each(&block)
+        return enum_for(:with_each) unless block_given?
+
+        names.each { |name| with(name, &block) }
+      end
+
+      def with(name, &block)
+        Record.with_shard(name, &block)
+      end
+
+      def with_connection_for(key, &block)
+        with(shard_for(key), &block)
+      end
+
+      def assign(keys)
+        keys.group_by { |key| shard_for(key.is_a?(Hash) ? key[:key] : key) }
+      end
+
+      def count
+        names.count
+      end
+
+      private
+        def shard_for(key)
+          nodes[consistent_hash.node(key)]
+        end
+    end
+  end
+end

data/lib/solid_cache/connections/single.rb

@@ -0,0 +1,37 @@
+module SolidCache
+  module Connections
+    class Single
+      attr_reader :name
+
+      def initialize(name)
+        @name = name
+      end
+
+      def with_each(&block)
+        return enum_for(:with_each) unless block_given?
+
+        with(name, &block)
+      end
+
+      def with(name, &block)
+        Record.with_shard(name, &block)
+      end
+
+      def with_connection_for(key, &block)
+        with(name, &block)
+      end
+
+      def assign(keys)
+        { name => keys }
+      end
+
+      def count
+        1
+      end
+
+      def names
+        [ name ]
+      end
+    end
+  end
+end

data/lib/solid_cache/connections/unmanaged.rb

@@ -0,0 +1,31 @@
+module SolidCache
+  module Connections
+    class Unmanaged
+      def with_each
+        return enum_for(:with_each) unless block_given?
+
+        yield
+      end
+
+      def with(name)
+        yield
+      end
+
+      def with_connection_for(key)
+        yield
+      end
+
+      def assign(keys)
+        { default: keys }
+      end
+
+      def count
+        1
+      end
+
+      def names
+        [ :default ]
+      end
+    end
+  end
+end

data/lib/solid_cache/connections.rb

@@ -0,0 +1,31 @@
+module SolidCache
+  module Connections
+    def self.from_config(options)
+      if options.present? || SolidCache.all_shards_config.present?
+        case options
+        when NilClass
+          names = SolidCache.all_shard_keys
+          nodes = names.to_h { |name| [ name, name ] }
+        when Array
+          names = options
+          nodes = names.to_h { |name| [ name, name ] }
+        when Hash
+          names = options.keys
+          nodes = options.invert
+        end
+
+        if (unknown_shards = names - SolidCache.all_shard_keys).any?
+          raise ArgumentError, "Unknown #{"shard".pluralize(unknown_shards)}: #{unknown_shards.join(", ")}"
+        end
+
+        if names.size == 1
+          Single.new(names.first)
+        else
+          Sharded.new(names, nodes)
+        end
+      else
+        Unmanaged.new
+      end
+    end
+  end
+end

data/lib/solid_cache/engine.rb

@@ -0,0 +1,20 @@
+require "active_support"
+
+module SolidCache
+  class Engine < ::Rails::Engine
+    isolate_namespace SolidCache
+
+    config.solid_cache = ActiveSupport::OrderedOptions.new
+
+    initializer "solid_cache", before: :run_prepare_callbacks do |app|
+      config.solid_cache.executor ||= app.executor
+
+      SolidCache.executor = config.solid_cache.executor
+      SolidCache.connects_to = config.solid_cache.connects_to
+    end
+
+    config.after_initialize do
+      Rails.cache.setup! if Rails.cache.is_a?(Store)
+    end
+  end
+end

data/lib/solid_cache/maglev_hash.rb

@@ -0,0 +1,77 @@
+# See https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/44824.pdf
+
+module SolidCache
+  class MaglevHash
+    attr_reader :nodes
+
+    #  Must be prime
+    TABLE_SIZE = 2053
+
+    def initialize(nodes)
+      raise ArgumentError, "No nodes specified" if nodes.count == 0
+      raise ArgumentError, "Maximum node count is #{TABLE_SIZE}" if nodes.count > TABLE_SIZE
+
+      @nodes = nodes.uniq.sort
+      @lookup = build_lookup
+    end
+
+    def node(key)
+      nodes[lookup[quick_hash(key) % TABLE_SIZE]]
+    end
+
+    private
+      attr_reader :lookup, :node_count
+
+      def build_lookup
+        lookup = Array.new(TABLE_SIZE, nil)
+
+        node_preferences = nodes.map { |node| build_preferences(node) }
+        node_count = nodes.count
+
+        TABLE_SIZE.times do |i|
+          node_index = i % node_count
+          preferences = node_preferences[node_index]
+          slot = preferences.preferred_free_slot(lookup)
+          lookup[slot] = node_index
+        end
+
+        lookup
+      end
+
+      def build_preferences(node)
+        offset = md5(node, :offset) % TABLE_SIZE
+        skip = md5(node, :skip) % (TABLE_SIZE - 1) + 1
+
+        Preferences.new(offset, skip)
+      end
+
+      def md5(*args)
+        ::Digest::MD5.digest(args.join).unpack1("L>")
+      end
+
+      def quick_hash(key)
+        Zlib.crc32(key.to_s)
+      end
+
+      class Preferences
+        def initialize(offset, skip)
+          @preferred_slots = TABLE_SIZE.times.map { |i| (offset + i * skip) % TABLE_SIZE }
+          @rank = 0
+        end
+
+        def preferred_free_slot(lookup)
+          loop do
+            slot = next_slot
+            return slot if lookup[slot].nil?
+          end
+        end
+
+        private
+          attr_reader :rank, :preferred_slots
+
+          def next_slot
+            preferred_slots[rank].tap { @rank += 1 }
+          end
+      end
+  end
+end

data/lib/solid_cache/store/api.rb

@@ -0,0 +1,153 @@
+module SolidCache
+  class Store
+    module Api
+      DEFAULT_MAX_KEY_BYTESIZE = 1024
+      SQL_WILDCARD_CHARS = [ "_", "%" ]
+
+      attr_reader :max_key_bytesize
+
+      def initialize(options = {})
+        super(options)
+
+        @max_key_bytesize = options.fetch(:max_key_bytesize, DEFAULT_MAX_KEY_BYTESIZE)
+      end
+
+      def delete_matched(matcher, options = {})
+        instrument :delete_matched, matcher do
+          raise ArgumentError, "Only strings are supported: #{matcher.inspect}" unless String === matcher
+          raise ArgumentError, "Strings cannot start with wildcards" if SQL_WILDCARD_CHARS.include?(matcher[0])
+
+          options ||= {}
+          batch_size = options.fetch(:batch_size, 1000)
+
+          matcher = namespace_key(matcher, options)
+
+          entry_delete_matched(matcher, batch_size)
+        end
+      end
+
+      def increment(name, amount = 1, options = nil)
+        options = merged_options(options)
+        key = normalize_key(name, options)
+
+        entry_increment(key, amount)
+      end
+
+      def decrement(name, amount = 1, options = nil)
+        options = merged_options(options)
+        key = normalize_key(name, options)
+
+        entry_decrement(key, amount)
+      end
+
+      def cleanup(options = nil)
+        raise NotImplementedError.new("#{self.class.name} does not support cleanup")
+      end
+
+      def clear(options = nil)
+        entry_clear
+      end
+
+      private
+        def read_entry(key, **options)
+          deserialize_entry(read_serialized_entry(key, **options), **options)
+        end
+
+        def read_serialized_entry(key, raw: false, **options)
+          entry_read(key)
+        end
+
+        def write_entry(key, entry, raw: false, **options)
+          payload = serialize_entry(entry, raw: raw, **options)
+          # No-op for us, but this writes it to the local cache
+          write_serialized_entry(key, payload, raw: raw, **options)
+
+          entry_write(key, payload)
+        end
+
+        def write_serialized_entry(key, payload, raw: false, unless_exist: false, expires_in: nil, race_condition_ttl: nil, **options)
+          true
+        end
+
+        def read_serialized_entries(keys)
+          entry_read_multi(keys).reduce(&:merge!)
+        end
+
+        def read_multi_entries(names, **options)
+          keys_and_names = names.to_h { |name| [ normalize_key(name, options), name ] }
+          serialized_entries = read_serialized_entries(keys_and_names.keys)
+
+          keys_and_names.each_with_object({}) do |(key, name), results|
+            serialized_entry = serialized_entries[key]
+            entry = deserialize_entry(serialized_entry, **options)
+
+            next unless entry
+
+            version = normalize_version(name, options)
+
+            if entry.expired?
+              delete_entry(key, **options)
+            elsif !entry.mismatched?(version)
+              results[name] = entry.value
+            end
+          end
+        end
+
+        def write_multi_entries(entries, expires_in: nil, **options)
+          if entries.any?
+            serialized_entries = serialize_entries(entries, **options)
+            # to add them to the local cache
+            serialized_entries.each do |entries|
+              write_serialized_entry(entries[:key], entries[:value])
+            end
+
+            entry_write_multi(serialized_entries).all?
+          end
+        end
+
+        def delete_entry(key, **options)
+          entry_delete(key)
+        end
+
+        def delete_multi_entries(entries, **options)
+          entries.count { |key| delete_entry(key, **options) }
+        end
+
+        def serialize_entry(entry, raw: false, **options)
+          if raw
+            entry.value.to_s
+          else
+            super(entry, raw: raw, **options)
+          end
+        end
+
+        def serialize_entries(entries, **options)
+          entries.map do |key, entry|
+            { key: key, value: serialize_entry(entry, **options) }
+          end
+        end
+
+        def deserialize_entry(payload, raw: false, **)
+          if payload && raw
+            ActiveSupport::Cache::Entry.new(payload)
+          else
+            super(payload)
+          end
+        end
+
+        def normalize_key(key, options)
+          truncate_key super&.b
+        end
+
+        def truncate_key(key)
+          if key && key.bytesize > max_key_bytesize
+            suffix = ":hash:#{ActiveSupport::Digest.hexdigest(key)}"
+            truncate_at = max_key_bytesize - suffix.bytesize
+            "#{key.byteslice(0, truncate_at)}#{suffix}".b
+          else
+            key
+          end
+        end
+    end
+  end
+end

data/lib/solid_cache/store/clusters.rb

@@ -0,0 +1,85 @@
+module SolidCache
+  class Store
+    module Clusters
+      attr_reader :primary_cluster, :clusters
+
+      def initialize(options = {})
+        super(options)
+
+        clusters_options = options.fetch(:clusters) { [ options.fetch(:cluster, {}) ] }
+
+        @clusters = clusters_options.map.with_index do |cluster_options, index|
+          Cluster.new(options.merge(cluster_options).merge(async_writes: index != 0))
+        end
+
+        @primary_cluster = clusters.first
+      end
+
+      def setup!
+        clusters.each(&:setup!)
+      end
+
+      private
+        def reading_key(key, failsafe:, failsafe_returning: nil)
+          failsafe(failsafe, returning: failsafe_returning) do
+            primary_cluster.with_connection_for(key) do
+              yield
+            end
+          end
+        end
+
+        def reading_keys(keys, failsafe:, failsafe_returning: nil)
+          connection_keys = primary_cluster.group_by_connection(keys)
+
+          connection_keys.map do |connection, keys|
+            failsafe(failsafe, returning: failsafe_returning) do
+              primary_cluster.with_connection(connection) do
+                yield keys
+              end
+            end
+          end
+        end
+
+
+        def writing_key(key, failsafe:, failsafe_returning: nil)
+          first_cluster_sync_rest_async do |cluster, async|
+            failsafe(failsafe, returning: failsafe_returning) do
+              cluster.with_connection_for(key, async: async) do
+                yield cluster
+              end
+            end
+          end
+        end
+
+        def writing_keys(entries, failsafe:, failsafe_returning: nil)
+          first_cluster_sync_rest_async do |cluster, async|
+            connection_entries = cluster.group_by_connection(entries)
+
+            connection_entries.map do |connection, entries|
+              failsafe(failsafe, returning: failsafe_returning) do
+                cluster.with_connection(connection, async: async) do
+                  yield cluster, entries
+                end
+              end
+            end
+          end
+        end
+
+        def writing_all(failsafe:, failsafe_returning: nil)
+          first_cluster_sync_rest_async do |cluster, async|
+            cluster.connection_names.each do |connection|
+              failsafe(failsafe, returning: failsafe_returning) do
+                cluster.with_connection(connection, async: async) do
+                  yield
+                end
+              end
+            end
+          end
+        end
+
+        def first_cluster_sync_rest_async
+          clusters.map.with_index { |cluster, index| yield cluster, index != 0 }.first
+        end
+    end
+  end
+end

data/lib/solid_cache/store/entries.rb

@@ -0,0 +1,81 @@
+module SolidCache
+  class Store
+    module Entries
+      attr_reader :clear_with
+
+      def initialize(options = {})
+        super(options)
+
+        # Truncating in test mode breaks transactional tests in MySQL (not in Postgres though)
+        @clear_with = options.fetch(:clear_with) { Rails.env.test? ? :delete : :truncate }&.to_sym
+
+        unless [ :truncate, :delete ].include?(clear_with)
+          raise ArgumentError, "`clear_with` must be either ``:truncate`` or ``:delete`"
+        end
+      end
+
+      private
+        def entry_delete_matched(matcher, batch_size)
+          writing_all(failsafe: :delete_matched) do
+            Entry.delete_matched(matcher, batch_size: batch_size)
+          end
+        end
+
+        def entry_clear
+          writing_all(failsafe: :clear) do
+            if clear_with == :truncate
+              Entry.clear_truncate
+            else
+              Entry.clear_delete
+            end
+          end
+        end
+
+        def entry_increment(key, amount)
+          writing_key(key, failsafe: :increment) do
+            Entry.increment(key, amount)
+          end
+        end
+
+        def entry_decrement(key, amount)
+          writing_key(key, failsafe: :decrement) do
+            Entry.decrement(key, amount)
+          end
+        end
+
+        def entry_read(key)
+          reading_key(key, failsafe: :read_entry) do
+            Entry.read(key)
+          end
+        end
+
+        def entry_read_multi(keys)
+          reading_keys(keys, failsafe: :read_multi_mget, failsafe_returning: {}) do |keys|
+            Entry.read_multi(keys)
+          end
+        end
+
+        def entry_write(key, payload)
+          writing_key(key, failsafe: :write_entry, failsafe_returning: false) do |cluster|
+            Entry.write(key, payload)
+            cluster.track_writes(1)
+            true
+          end
+        end
+
+        def entry_write_multi(entries)
+          writing_keys(entries, failsafe: :write_multi_entries, failsafe_returning: false) do |cluster, entries|
+            Entry.write_multi(entries)
+            cluster.track_writes(entries.count)
+            true
+          end
+        end
+
+        def entry_delete(key)
+          writing_key(key, failsafe: :delete_entry, failsafe_returning: false) do
+            Entry.delete_by_key(key)
+          end
+        end
+    end
+  end
+end

data/lib/solid_cache/store/failsafe.rb

@@ -0,0 +1,28 @@
+module SolidCache
+  class Store
+    module Failsafe
+      DEFAULT_ERROR_HANDLER = ->(method:, returning:, exception:) do
+        if Store.logger
+          Store.logger.error { "SolidCacheStore: #{method} failed, returned #{returning.inspect}: #{exception.class}: #{exception.message}" }
+        end
+      end
+
+      def initialize(options = {})
+        super(options)
+
+        @error_handler = options.fetch(:error_handler, DEFAULT_ERROR_HANDLER)
+      end
+
+      private
+        attr_reader :error_handler
+
+        def failsafe(method, returning: nil)
+          yield
+        rescue ActiveRecord::ActiveRecordError => error
+          ActiveSupport.error_reporter&.report(error, handled: true, severity: :warning)
+          error_handler&.call(method: method, exception: error, returning: returning)
+          returning
+        end
+    end
+  end
+end