activerecord_cached 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 051daa89ebda43ea098a7f152e567730f1a71f4794919ac4ac3ca8ec98936526
+  data.tar.gz: 829ea885b15719e2c77357f4caa1c6d39d4c221719fcca39a295eb41af1e0256
+SHA512:
+  metadata.gz: d98b20830828b808644df5b31a6a917a40af2aba50808e003c4b2b92d08f1b27297ba140ae61a4ea82c7c8c27ac0927545576734cf2b5f05074556d4daedcadf
+  data.tar.gz: ba34d2b20e9f07d13eb40b4bee773ed048eea9546d78e298b1ec0aa3c67c8012c170dad502b1d226d1ed3f50de54e12623f8abd6fa79d404d3e560fe2907990e

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [1.0.0] - 2024-01-23
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Janosch Müller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,64 @@
+# ActiveRecordCached
+
+This gem adds methods to cache small amounts of ActiveRecord data in RAM, Redis, or other stores.
+
+The cache for each model is busted both by individual CRUD operations on that model (e.g. `#update`), as well as by mass operations (e.g. `#update_all`).
+
+The cached methods work on whole models as well as on relations.
+
+There is an automatic warning if the data is getting too big to cache.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add activerecord_cached
+
+## Usage
+
+```ruby
+Pizza.cached_count # => 2374
+Pizza.limit(2).cached_pluck(:name) # => ["Funghi", "Spinaci"]
+Pizza.select(:id, :name).cached_records # => [#<Pizza id=1 name="Funghi">, ...]
+```
+
+Configuration:
+
+```ruby
+ActiveRecordCached.configure do |config|
+  # How to cache the data. Default: MemoryStore
+  config.cache_store = Rails.cache
+
+  # Maximum size of the standard memory store. Default: 32MB
+  config.max_total_bytes = 16.megabytes
+
+  # How much data to allow per cached relation. Default: 1MB
+  config.max_bytes = 2.megabytes
+
+  # How many records to allow per cached relation. Default: 10k
+  config.max_count = 1000
+
+  # What do to when any limit is exceeded. Default: warn
+  config.on_limit_reached = ->msg{ report(msg) }
+end
+```
+
+Specs:
+
+```ruby
+RSpec.configure do |config|
+  config.after(:each) { ActiveRecordCached.clear_all }
+end
+```
+
+## Tradeoffs
+
+The default MemoryStore is orders of magnitude faster than e.g. Redis, but it is wiped when the app is deployed or otherwise restarted, which may present a [cache stampede](https://en.wikipedia.org/wiki/Cache_stampede) risk under very high load.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jaynetics/activerecord_cached.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/activerecord_cached/activerecord_extensions.rb

@@ -0,0 +1,54 @@
+# define cached_* methods, e.g. cached_pluck
+module ActiveRecordCached
+  module BaseExtension
+    def clear_cached_values
+      ActiveRecordCached.clear_for_model(self)
+    end
+  end
+
+  module RelationExtension
+    def clear_cached_values
+      ActiveRecordCached.clear_for_model(klass)
+    end
+  end
+
+  %i[count maximum minimum pick pluck records sum].each do |method|
+    BaseExtension.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def cached_#{method}(*args)
+        all.cached_#{method}(*args)
+      end
+    RUBY
+
+    RelationExtension.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+      def cached_#{method}(*args)
+        ActiveRecordCached.fetch(self, :#{method}, args)
+      end
+    RUBY
+  end
+
+  ActiveRecord::Base.singleton_class.prepend BaseExtension
+  ActiveRecord::Relation.prepend RelationExtension
+
+  # bust cache on individual record changes - this module is included
+  # automatically into models that use cached methods.
+  module CRUDCallbacks
+    def self.included(base)
+      base.after_commit { self.class.clear_cached_values }
+    end
+  end
+
+  # bust cache on mass operations
+  module MassOperationWrapper
+    %i[delete_all insert_all touch_all update_all update_counters upsert_all].each do |mass_op|
+      class_eval <<~RUBY, __FILE__, __LINE__ + 1
+        def #{mass_op}(...)
+          result = super(...)
+          result && clear_cached_values
+          result
+        end
+      RUBY
+    end
+  end
+  ActiveRecord::Base.singleton_class.prepend MassOperationWrapper
+  ActiveRecord::Relation.prepend MassOperationWrapper
+end

data/lib/activerecord_cached/cache.rb

@@ -0,0 +1,57 @@
+module ActiveRecordCached
+  def fetch(relation, method, args)
+    key = ['ActiveRecordCached', relation.to_sql, method, args.sort].join(':')
+    model = relation.klass
+    prepare(model)
+    cache_store.fetch(key) do
+      log_model_cache_key(model, key)
+      query_db(relation, method, args)
+    end
+  end
+
+  def clear_for_model(model)
+    keys = cache_keys_per_model
+    return unless model_keys = keys.delete(model)&.keys
+
+    cache_store.delete_multi(model_keys)
+    cache_store.write(CACHE_KEYS_KEY, keys)
+  end
+
+  def clear_all
+    all_keys = cache_keys_per_model.values.flat_map(&:keys)
+    cache_store.delete_multi(all_keys)
+    cache_store.delete(CACHE_KEYS_KEY)
+  end
+
+  private
+
+  def prepare(model)
+    return if CRUDCallbacks.in?(model.included_modules)
+
+    PREPARE_MUTEX.synchronize do
+      CRUDCallbacks.in?(model.included_modules) || model.include(CRUDCallbacks)
+    end
+  end
+
+  PREPARE_MUTEX = Mutex.new
+
+  def log_model_cache_key(model, key)
+    keys = cache_keys_per_model
+    (keys[model] ||= {})[key] = true
+    cache_store.write(CACHE_KEYS_KEY, keys)
+  end
+
+  def cache_keys_per_model
+    cache_store.read(CACHE_KEYS_KEY) || {}
+  end
+
+  CACHE_KEYS_KEY = 'ActiveRecordCached:cache_keys_per_model'
+
+  def query_db(rel, method, args)
+    rel = rel.limit(max_count) if max_count && rel.limit_value.nil?
+    result = rel.send(method, *args)
+    result = result.to_a if method == :select
+    check_limit(rel, method, result)
+    result
+  end
+end

data/lib/activerecord_cached/configuration.rb

@@ -0,0 +1,54 @@
+module ActiveRecordCached
+  def configure(&block)
+    tap(&block)
+  end
+
+  def cache_store
+    @cache_store ||= store_with_limit_warning(
+      ActiveSupport::Cache::MemoryStore.new({ coder: nil, size: max_total_bytes })
+    )
+  end
+
+  def cache_store=(val)
+    val.is_a?(ActiveSupport::Cache::Store) || raise(ArgumentError, 'pass an ActiveSupport::Cache::Store')
+    @cache_store = store_with_limit_warning(val)
+  end
+
+  mattr_accessor(:max_total_bytes) { 32.megabytes }
+  def max_total_bytes=(val)
+    val.is_a?(Integer) && val > 0 || raise(ArgumentError, 'pass an int > 0')
+    super
+  end
+
+  mattr_accessor(:max_count) { 10_000 }
+  def max_count=(val)
+    val.is_a?(Integer) && val > 0 || val.nil? || raise(ArgumentError, 'pass an int > 0 or nil')
+    super
+  end
+
+  mattr_accessor(:max_bytes) { 1.megabyte }
+  def max_bytes=(val)
+    val.is_a?(Integer) && val > 0 || val.nil? || raise(ArgumentError, 'pass an int > 0 or nil')
+    super
+  end
+
+  mattr_accessor(:on_limit_reached) { ->(msg) { warn(msg) } }
+  def on_limit_reached=(val)
+    val.is_a?(Proc) && val.arity == 1 || raise(ArgumentError, 'pass a proc with arity 1')
+    super
+  end
+
+  private
+
+  def store_with_limit_warning(store)
+    return store unless store.is_a?(ActiveSupport::Cache::MemoryStore)
+
+    store.singleton_class.prepend(Module.new do
+      def prune(...)
+        ActiveRecordCached.send(:warn_max_total_bytes_exceeded)
+        super
+      end
+    end)
+    store
+  end
+end

data/lib/activerecord_cached/limit_checks.rb

@@ -0,0 +1,29 @@
+module ActiveRecordCached
+  private
+
+  def check_limit(relation, method, result)
+    values = Array(result)
+    if values.count == max_count
+      warn_limit_reached("#{relation.klass}.#{method} >= #{max_count} max_count")
+    elsif max_bytes_exceeded?(values)
+      warn_limit_reached("#{relation.klass}.#{method} >= #{max_bytes} max_bytes")
+    end
+  end
+
+  def warn_max_total_bytes_exceeded
+    warn_limit_reached("Store size >= #{max_total_bytes} max_total_bytes")
+  end
+
+  def warn_limit_reached(info)
+    on_limit_reached.call("ActiveRecordCached: data getting too big to cache. #{info}")
+  end
+
+  def max_bytes_exceeded?(values)
+    memsize = 0
+    max_bytes && values.inject(0) do |value|
+      memsize += Marshal.dump(value).bytesize
+      return true if memsize >= max_bytes
+    end
+    false
+  end
+end

data/lib/activerecord_cached/railtie.rb

@@ -0,0 +1,7 @@
+module ActiveRecordCached
+  class Railtie < ::Rails::Railtie
+    config.to_prepare do
+      ActiveRecordCached.clear_all
+    end
+  end
+end

data/lib/activerecord_cached/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActiveRecordCached
+  VERSION = "1.0.0"
+end

data/lib/activerecord_cached.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support"
+
+require_relative "activerecord_cached/activerecord_extensions"
+require_relative "activerecord_cached/cache"
+require_relative "activerecord_cached/configuration"
+require_relative "activerecord_cached/limit_checks"
+require_relative "activerecord_cached/railtie" if defined?(::Rails::Railtie)
+require_relative "activerecord_cached/version"
+
+module ActiveRecordCached
+  extend self
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: activerecord_cached
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Janosch Müller
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-01-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+description:
+email:
+- janosch84@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/activerecord_cached.rb
+- lib/activerecord_cached/activerecord_extensions.rb
+- lib/activerecord_cached/cache.rb
+- lib/activerecord_cached/configuration.rb
+- lib/activerecord_cached/limit_checks.rb
+- lib/activerecord_cached/railtie.rb
+- lib/activerecord_cached/version.rb
+homepage: https://github.com/jaynetics/activerecord_cached
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jaynetics/activerecord_cached
+  source_code_uri: https://github.com/jaynetics/activerecord_cached
+  changelog_uri: https://github.com/jaynetics/activerecord_cached/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.0.dev
+signing_key:
+specification_version: 4
+summary: Flexibly cache ActiveRecord queries across requests
+test_files: []