solid_cache_mongoid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf9d5857f9532ff873ca0667c47e572d61ccaee958a9768d0bf372832ed45067
+  data.tar.gz: 2e6a812dd2b7930ddf81f7f1cddbf08cef0cf039365f974412b7460642964ee4
+SHA512:
+  metadata.gz: 1355e87bd9234e18d12a7a33fb70d9145be98088fa1117f983110a998fe5ec5f2857e8baf1d826a601112c224839e4e37ff0f0d738f04709ecdb550173032da2
+  data.tar.gz: 86dc49c94645cf8c6ecdc5c5d69ead576bf15ed66d3ecf0629952f7c49db7beafa3c181e993e3b4050a02ba0cdc50cb03931a79518315b71d03b3574c82e30a6

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 37signals, LLC
+
+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,189 @@
+# Solid Cache
+
+Solid Cache is a database-backed Active Support cache store that lets you keep a much larger cache than is typically possible with traditional memory-only Redis or Memcached stores. This is thanks to the speed of modern SSD drives, which make the access-time penalty of using disk vs RAM insignificant for most caching purposes. Simply put, you're now usually better off keeping a huge cache on disk rather than a small cache in memory.
+
+## Installation
+
+Solid Cache is configured by default in new Rails 8 applications. But if you're running an earlier version, you can add it manually following these steps:
+
+1. `bundle add solid_cache_mongoid`
+2. `bin/rails solid_cache_mongoid:install`
+
+This will configure Solid Cache as the production cache store and create `config/cache.yml`.
+
+## Configuration
+
+Configuration will be read from `config/cache.yml` or `config/solid_cache.yml`. You can change the location of the config file by setting the `SOLID_CACHE_CONFIG` env variable.
+
+The format of the file is:
+
+```yml
+default: &default
+  # database: <%= ENV.fetch("SOLID_CACHE_DATABASE", "solid_cache") %>
+  # collection: solid_cache_entries
+  # client: default
+  # encrypt: false
+  store_options:
+    # Cap age of oldest cache entry to fulfill retention policies
+    # max_age: <%%= 60.days.to_i %>
+    max_size: <%%= 256.megabytes %>
+    namespace: <%%= Rails.env %>
+
+development:
+  <<: *default
+
+test:
+  <<: *default
+
+production:
+  database: <%= ENV.fetch("SOLID_CACHE_DATABASE", "solid_cache") %>
+  <<: *default
+
+```
+
+For the full list of keys for `store_options` see [Cache configuration](#cache-configuration). Any options passed to the cache lookup will overwrite those specified here.
+
+After running `solid_cache:install`, `environments/production.rb` will replace your cache store with Solid Cache, but you can also do this manually:
+
+```ruby
+# config/environments/production.rb
+config.cache_store = :solid_cache_mongoid_store
+```
+### Engine configuration
+
+There are five options that can be set on the engine:
+
+- `executor` - the [Rails executor](https://guides.rubyonrails.org/threading_and_code_execution.html#executor) used to wrap asynchronous operations, defaults to the app executor
+- `size_estimate_samples` - if `max_size` is set on the cache, the number of the samples used to estimate the size.
+- `encrypted` - whether cache values should be encrypted (see [Enabling encryption](#enabling-encryption))
+- `encryption_context_properties` - custom encryption context properties
+
+These can be set in your Rails configuration:
+
+```ruby
+Rails.application.configure do
+  config.solid_cache.size_estimate_samples = 1000
+end
+```
+
+### Cache configuration
+
+Solid Cache supports these options in addition to the standard `ActiveSupport::Cache::Store` options:
+
+- `error_handler` - a Proc to call to handle any transient database errors that are raised (default: log errors as warnings)
+- `expiry_batch_size` - the batch size to use when deleting old records (default: `100`)
+- `expiry_method` - what expiry method to use `thread` or `job` (default: `thread`)
+- `expiry_queue` - which queue to add expiry jobs to (default: `default`)
+- `max_age` - the maximum age of entries in the cache (default: `2.weeks.to_i`). Can be set to `nil`, but this is not recommended unless using `max_entries` to limit the size of the cache.
+- `max_entries` - the maximum number of entries allowed in the cache (default: `nil`, meaning no limit)
+- `max_size` - the maximum size of the cache entries (default `nil`, meaning no limit)
+- `cluster` - (deprecated) a Hash of options for the cache database cluster, e.g `{ shards: [:database1, :database2, :database3] }`
+- `clusters` - (deprecated) an Array of Hashes for multiple cache clusters (ignored if `:cluster` is set)
+- `shards` - an Array of databases
+- `active_record_instrumentation` - whether to instrument the cache's queries (default: `true`)
+- `clear_with` - clear the cache with `:truncate` or `:delete` (default `truncate`, except for when `Rails.env.test?` then `delete`)
+- `max_key_bytesize` - the maximum size of a normalized key in bytes (default `1024`)
+
+## Cache expiry
+
+Solid Cache tracks writes to the cache. For every write it increments a counter by 1. Once the counter reaches 50% of the `expiry_batch_size` it adds a task to run on a background thread. That task will:
+
+1. Check if we have exceeded the `max_entries` or `max_size` values (if set).
+   The current entries are estimated by subtracting the max and min IDs from the `SolidCache::Entry` table.
+   The current size is estimated by sampling the entry `byte_size` columns.
+2. If we have, it will delete `expiry_batch_size` entries.
+3. If not, it will delete up to `expiry_batch_size` entries, provided they are all older than `max_age`.
+
+Expiring when we reach 50% of the batch size allows us to expire records from the cache faster than we write to it when we need to reduce the cache size.
+
+Only triggering expiry when we write means that if the cache is idle, the background thread is also idle.
+
+If you want the cache expiry to be run in a background job instead of a thread, you can set `expiry_method` to `:job`. This will enqueue a `SolidCache::ExpiryJob`.
+
+## Enabling encryption
+
+To encrypt the cache values, you can add the encrypt property.
+
+```yaml
+# config/cache.yml
+production:
+  encrypt: true
+```
+or
+```ruby
+# application.rb
+config.solid_cache.encrypt = true
+```
+
+You will need to set up your application to [use Active Record Encryption](https://www.mongodb.com/docs/mongoid/current/security/encryption).
+
+Solid Cache by default uses a custom encryptor and message serializer that are optimised for it.
+You can choose your own context properties instead if you prefer:
+
+```ruby
+# application.rb
+config.solid_cache.encryption_context_properties = {
+  deterministic: false
+}
+```
+
+## Index size limits
+The Solid Cache migrations try to create an index with 1024 byte entries. If that is too big for your database, you should:
+
+1. Edit the index size in the migration.
+2. Set `max_key_bytesize` on your cache to the new value.
+
+## Development
+
+Run the tests with `bin/rake test`. By default, these will run against SQLite.
+
+You can also run the tests against MySQL and PostgreSQL. First start up the databases:
+
+```shell
+$ docker compose up -d
+```
+
+Next, setup the database:
+
+```shell
+$ bin/rails db:setup
+```
+
+
+Then run the tests:
+
+```shell
+$ bin/rake test
+```
+
+### Testing with multiple Rails versions
+
+Solid Cache relies on [appraisal](https://github.com/thoughtbot/appraisal/tree/main) to test
+multiple Rails versions.
+
+To run a test for a specific version run:
+
+```shell
+bundle exec appraisal rails-7-1 bin/rake test
+```
+
+After updating the dependencies in the `Gemfile` please run:
+
+```shell
+$ bundle
+$ appraisal update
+```
+
+This ensures that all the Rails versions dependencies are updated.
+
+## Implementation
+
+Solid Cache is a FIFO (first in, first out) cache. While this is not as efficient as an LRU (least recently used) cache, it is mitigated by the longer cache lifespan.
+
+A FIFO cache is much easier to manage:
+1. We don't need to track when items are read.
+2. We can estimate and control the cache size by comparing the maximum and minimum IDs.
+3. By deleting from one end of the table and adding at the other end we can avoid fragmentation.
+
+## License
+Solid Cache is licensed under MIT.

data/Rakefile

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+def run_without_aborting(*tasks)
+  errors = []
+
+  tasks.each do |task|
+    Rake::Task[task].invoke
+  rescue Exception => e
+    puts e.message
+    puts e.backtrace
+    errors << task
+  end
+
+  abort "Errors running #{errors.join(', ')}" if errors.any?
+end
+
+def configs
+  [ :default, :database, :no_database, :client, :collection, :encrypted, :encrypted_custom ]
+end
+
+task :test do
+  tasks = configs.map { |config| "test:#{config}" }
+  run_without_aborting(*tasks)
+end
+
+configs.each do |config|
+  namespace :test do
+    task config do
+      if config == :default
+        sh("bin/rails test")
+      else
+        sh("SOLID_CACHE_CONFIG=config/cache_#{config}.yml bin/rails test")
+      end
+    end
+  end
+end
+
+task default: [:test]

data/app/jobs/solid_cache_mongoid/expiry_job.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module SolidCacheMongoid
+  class ExpiryJob < ActiveJob::Base
+    def perform(count, max_age: nil, max_entries: nil, max_size: nil)
+      Entry.expire(count, max_age: max_age, max_entries: max_entries, max_size: max_size)
+    end
+  end
+end

data/app/models/solid_cache_mongoid/entry/expiration.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SolidCacheMongoid
+  class Entry
+    module Expiration
+      extend ActiveSupport::Concern
+
+      class_methods do
+        def expire(count, max_age:, max_entries:, max_size:)
+          if (ids = expiry_candidate_ids(count, max_age: max_age, max_entries: max_entries, max_size: max_size)).any?
+            where(:id.in => ids).delete_all
+          end
+        end
+
+        private
+          def cache_full?(max_entries:, max_size:)
+            if max_entries && max_entries < id_range
+              true
+            elsif max_size && max_size < estimated_size
+              true
+            else
+              false
+            end
+          end
+
+          def expiry_candidate_ids(count, max_age:, max_entries:, max_size:)
+            cache_full = cache_full?(max_entries: max_entries, max_size: max_size)
+            return [] unless cache_full || max_age
+
+            # In the case of multiple concurrent expiry operations, it is desirable to
+            # reduce the overlap of entries being addressed by each. For that reason,
+            # retrieve more ids than are being expired, and use random
+            # sampling to reduce that number to the actual intended count.
+            retrieve_count = count * 3
+
+            uncached do
+              candidates = order_by([:id, :asc]).limit(retrieve_count)
+
+              candidate_ids = if cache_full
+                candidates.pluck(:id)
+              else
+                min_created_at = max_age.seconds.ago
+                # We don't have an index on created_at, but we can select
+                # the records by id and they'll be in created_at order.
+                candidates.pluck(:id, :created_at)
+                          .filter_map { |id, created_at| id if created_at < min_created_at }
+              end
+
+              candidate_ids.sample(count)
+            end
+          end
+      end
+    end
+  end
+end

data/app/models/solid_cache_mongoid/entry/size/estimate.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module SolidCacheMongoid
+  class Entry
+    # # Cache size estimation
+    #
+    # We store the size of each cache row in the byte_size field. This allows us to estimate the size of the cache
+    # by sampling those rows.
+    #
+    # To reduce the effect of outliers though we'll grab the N largest rows, and add their size to a sampled based
+    # estimate of the size of the remaining rows.
+    #
+    # ## Outliers
+    #
+    # There is an index on the byte_size column, so we can efficiently grab the N largest rows. We also grab the
+    # minimum byte_size of those rows, which we'll use as a cutoff for the non outlier sampling.
+    #
+    # ## Sampling
+    #
+    # To efficiently sample the data we use the key_hash column, which is a random 64 bit integer. There's an index
+    # on key_hash and byte_size so we can grab a sum of the byte_sizes in a range of key_hash directly from that
+    # index.
+    #
+    # To decide how big the range should be, we use the difference between the smallest and largest database IDs as
+    # an estimate of the number of rows in the table. This should be a good estimate, because we delete rows in ID order
+    #
+    # We then calculate the fraction of the rows we want to sample by dividing the sample size by the estimated number
+    # of rows.
+    #
+    # Then we grab the byte_size sum of the rows in the range of key_hash values excluding any rows that are larger than
+    # our minimum outlier cutoff. We then divide this by the sampling fraction to get an estimate of the size of the
+    # non outlier rows
+    #
+    # ## Equations
+    #
+    #  Given N samples and a key_hash range of Kmin..Kmax
+    #
+    #    outliers_cutoff              OC = min(byte_size of N largest rows)
+    #    outliers_size                OS = sum(byte_size of N largest rows)
+    #
+    #    estimated number of rows     R = max(ID) - min(ID) + 1
+    #    sample_fraction              F = N / R
+    #    sample_range_size            S = (Kmax - Kmin) * F
+    #    sample range is              K1..K2 where K1 = Kmin + rand(Kmax - S) and K2 = K1 + S
+    #
+    #    non_outlier_sample_size      NSS = sum(byte_size of rows in key_hash range K1..K2 where byte_size <= OC)
+    #    non_outlier_estimated_size   NES = NSS / F
+    #    estimated_size               ES = OS + NES
+    module Size
+      class Estimate
+        attr_reader :samples, :max_records
+
+        def initialize(samples:)
+          @samples = samples
+          @max_records ||= Entry.id_range
+        end
+
+        def size
+          outliers_size + non_outlier_estimated_size
+        end
+
+        def exact?
+          outliers_count < samples || sampled_fraction == 1
+        end
+
+        private
+          def outliers_size
+            outliers_size_count_and_cutoff[0]
+          end
+
+          def outliers_count
+            outliers_size_count_and_cutoff[1]
+          end
+
+          def outliers_cutoff
+            outliers_size_count_and_cutoff[2]
+          end
+
+          def outliers_size_count_and_cutoff
+            @outlier_size_and_cutoff ||= Entry.uncached do
+              largest = Entry.largest_byte_sizes(samples)
+
+              # Usar agregación de MongoDB para calcular sum, count y min
+              if largest.exists?
+                sum = largest.sum(:byte_size)
+                count = largest.count
+                min = largest.min(:byte_size)
+                [sum, count, min]
+              else
+                [0, 0, nil]
+              end
+            end
+          end
+
+          def non_outlier_estimated_size
+            @non_outlier_estimated_size ||= sampled_fraction.zero? ? 0 : (sampled_non_outlier_size / sampled_fraction).round
+          end
+
+          def sampled_fraction
+            @sampled_fraction ||=
+              if max_records <= samples
+                0
+              else
+                [samples.to_f / (max_records - samples), 1].min
+              end
+          end
+
+          def sampled_non_outlier_size
+            @sampled_non_outlier_size ||= Entry.uncached do
+              Entry.in_key_hash_range(sample_range).up_to_byte_size(outliers_cutoff).sum(:byte_size)
+            end
+          end
+
+          def sample_range
+            if sampled_fraction == 1
+              key_hash_range
+            else
+              start = rand(key_hash_range.begin..(key_hash_range.end - sample_range_size))
+              start..(start + sample_range_size)
+            end
+          end
+
+          def key_hash_range
+            Entry::KEY_HASH_ID_RANGE
+          end
+
+          def sample_range_size
+            @sample_range_size ||= (key_hash_range.size * sampled_fraction).to_i
+          end
+      end
+    end
+  end
+end

data/app/models/solid_cache_mongoid/entry/size/moving_average_estimate.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SolidCacheMongoid
+  class Entry
+    module Size
+      # Moving average cache size estimation
+      #
+      # To reduce variability in the cache size estimate, we'll use a moving average of the previous 20 estimates.
+      # The estimates are stored directly in the cache, under the "__solid_cache_entry_size_moving_average_estimates" key.
+      #
+      # We'll remove the largest and smallest estimates, and then average remaining ones.
+      class MovingAverageEstimate
+        ESTIMATES_KEY = "__solid_cache_entry_size_moving_average_estimates"
+        MAX_RETAINED_ESTIMATES = 50
+        TARGET_SAMPLED_FRACTION = 0.0005
+
+        attr_reader :samples, :size
+        delegate :exact?, to: :estimate
+
+        def initialize(samples:)
+          @samples = samples
+          @estimate = Estimate.new(samples: samples)
+          values = latest_values
+          @size = (values.sum / values.size.to_f).round
+          write_values(values)
+        end
+
+        private
+          attr_reader :estimate
+
+          def previous_values
+            value = Entry.read(ESTIMATES_KEY)
+            return [] unless value
+
+            # Convertir de BSON::Binary a string si es necesario
+            value_str = value.is_a?(BSON::Binary) ? value.data : value.to_s
+            value_str.presence&.split("|")&.map(&:to_i) || []
+          end
+
+          def latest_value
+            estimate.size
+          end
+
+          def latest_values
+            (previous_values + [latest_value]).last(retained_estimates)
+          end
+
+          def write_values(values)
+            Entry.write(ESTIMATES_KEY, values.join("|"))
+          end
+
+          def retained_estimates
+            [retained_estimates_for_target_fraction, MAX_RETAINED_ESTIMATES].min
+          end
+
+          def retained_estimates_for_target_fraction
+            (estimate.max_records / samples * TARGET_SAMPLED_FRACTION).floor + 1
+          end
+      end
+    end
+  end
+end

data/app/models/solid_cache_mongoid/entry/size.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidCacheMongoid
+  class Entry
+    module Size
+      extend ActiveSupport::Concern
+
+      included do
+        scope :largest_byte_sizes, -> (limit) { order(byte_size: :desc).limit(limit).only(:byte_size) }
+        scope :in_key_hash_range, -> (range) { where(:key_hash.gte => range.begin, :key_hash.lte => range.end) }
+        scope :up_to_byte_size, -> (cutoff) { where(:byte_size.lte => cutoff) }
+      end
+
+      class_methods do
+        def estimated_size(samples: SolidCacheMongoid.configuration.size_estimate_samples)
+          MovingAverageEstimate.new(samples: samples).size
+        end
+      end
+    end
+  end
+end

data/app/models/solid_cache_mongoid/entry.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module SolidCacheMongoid
+  class Entry
+    include Record
+    include Expiration
+    include Size
+    include Mongoid::Locker
+
+    # The estimated cost of an extra row in bytes, including fixed size columns, overhead, indexes and free space
+    # Based on experimentation on SQLite, MySQL and Postgresql.
+    # A bit high for SQLite (more like 90 bytes), but about right for MySQL/Postgresql.
+    ESTIMATED_ROW_OVERHEAD = 140
+
+    # Assuming MessagePack serialization
+    ESTIMATED_ENCRYPTION_OVERHEAD = 170
+
+    KEY_HASH_ID_RANGE = -(2**63)..(2**63 - 1)
+
+    MULTI_BATCH_SIZE = 1000
+
+    class << self
+      def write(key, value)
+        write_multi([ { key: key, value: value } ])
+      end
+
+      def write_multi(payloads)
+        without_query_cache do
+          payloads.each_slice(MULTI_BATCH_SIZE).each do |payload_batch|
+            add_key_hash_and_byte_size(payload_batch).each do |payload|
+              # Convertir key y value a BSON::Binary
+              key = payload.delete(:key)
+              value = payload.delete(:value)
+              obj = where(key_hash: payload[:key_hash]).first_or_initialize
+              obj.assign_attributes(payload)
+              obj.key = BSON::Binary.new(key)
+              obj.value = BSON::Binary.new(value)
+              obj.save!
+            end
+          end
+        end
+      end
+
+      def read(key)
+        read_multi([key])[key]
+      end
+
+      def read_multi(keys)
+        without_query_cache do
+          {}.tap do |results|
+            keys.each_slice(MULTI_BATCH_SIZE).each do |keys_batch|
+              key_hashes = key_hashes_for(keys_batch)
+
+              where(:key_hash.in => key_hashes)
+                .only(:key, :value)
+                .each do |entry|
+                  # Convertir BSON::Binary de vuelta a string
+                  key_str = entry.key.data
+                  value_str = entry.value.data
+                  results[key_str] = value_str
+                end
+            end
+          end
+        end
+      end
+
+      def delete_by_key(*keys)
+        without_query_cache do
+          where(:key_hash.in => key_hashes_for(keys)).delete_all
+        end
+      end
+
+      def clear_truncate
+        delete_all
+        nil
+      end
+
+      def clear_delete
+        without_query_cache do
+          delete_all
+        end
+        nil
+      end
+
+      def lock_and_write(key, &block)
+        without_query_cache do
+          entry = where(key_hash: key_hash_for(key)).first
+
+          if entry
+            entry.with_lock do
+              entry_key = entry.key.data
+              entry_value = entry.value.data
+
+              current_value = entry_key == key ? entry_value : nil
+              new_value = block.call(current_value)
+              write(key, new_value) if new_value
+              new_value
+            end
+          else
+            new_value = block.call(nil)
+            write(key, new_value) if new_value
+            new_value
+          end
+        end
+      end
+
+      def id_range
+        without_query_cache { count }
+      end
+
+      private
+        def add_key_hash_and_byte_size(payloads)
+          payloads.map do |payload|
+            payload.dup.tap do |payload|
+              payload[:key_hash] = key_hash_for(payload[:key])
+              payload[:byte_size] = byte_size_for(payload)
+            end
+          end
+        end
+
+        def key_hash_for(key)
+          # Need to unpack this as a signed integer - Postgresql and SQLite don't support unsigned integers
+          Digest::SHA256.digest(key.to_s).unpack("q>").first
+        end
+
+        def key_hashes_for(keys)
+          keys.map { |key| key_hash_for(key) }
+        end
+
+        def byte_size_for(payload)
+          payload[:key].to_s.bytesize + payload[:value].to_s.bytesize + estimated_row_overhead
+        end
+
+        def estimated_row_overhead
+          if SolidCacheMongoid.configuration.encrypt?
+            ESTIMATED_ROW_OVERHEAD + ESTIMATED_ENCRYPTION_OVERHEAD
+          else
+            ESTIMATED_ROW_OVERHEAD
+          end
+        end
+    end
+  end
+end
+
+ActiveSupport.run_load_hooks :solid_cache_entry, SolidCacheMongoid::Entry