rimcache 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8193c5feead4d6c058e64ba03b94fa863e32d5c9ab29819e3d44458401204914
+  data.tar.gz: 0bcf98dddfe53da75d045cfbd7870e4978b1b793c4f701556871ee04b5652b5c
+SHA512:
+  metadata.gz: 6226294aca56945946737f0feb4555b3e4d09ae46bba2faebdd9d71afd0afb5b2d4ffd37214fb24eb5d9b8d705f019cf44b7ffc35b2f0bb583607f4b4ace2f60
+  data.tar.gz: 7a1b36e38741f6716de88d51b8dc39f664bea0fac47c4dfa818559a18d9bdcb5e6a3ad65dbe8611d4b0ab4eba0065279977b74713a6655ea98fda70fb379459f

data/.rubocop.yml

@@ -0,0 +1,24 @@
+plugins:
+  - rubocop-minitest
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/AbcSize:
+  Exclude:
+    - 'test/**/*'
+
+Gemspec/RequireMFA:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-02-06
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Duncan McKee
+
+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,129 @@
+# Rimcache
+
+A right-in-memory "cache" for Ruby on Rails.
+
+Does your Rails app have individual records that most or all of your requests use?
+They rarely change but it's still handy to have them in the database?
+
+With Rimcache, you can keep a frozen ActiveRecord object or set of objects in
+memory and it will automatically refresh from the database when any server worker
+invalidates it. It avoids the serialization required for caching in Redis/Memcache,
+so it is usable for situations where Rails low-level caching is not.
+Associations on a record will stay loaded, so it can save more than one query per
+cached record.
+
+
+## Usage
+
+Say you have an app where every request is processed in the context one of just a few `Site` records.
+You could avoid loading it from the database every time like this:
+
+```ruby
+class Site < ActiveRecord::Base
+  has_many :features
+
+  after_update :expire_rimcache
+
+  def self.find_cached(slug)
+    Rimcache.fetch("site_#{slug}") do
+      # This will only be called if site is not already in cache or was expired
+      Site.eager_load(:features).find_by(slug:)
+    end
+  end
+
+  def expire_rimcache
+    Rimcache.expire("site_#{slug}")
+  end
+end
+```
+
+
+## Configuration
+
+If the record is rarely updated and you'd rather not bother with expiration,
+you can set a TTL with `Rimcache.config.refresh_interval`:
+
+```ruby
+Rimcache.config.refresh_interval = 15.minutes
+```
+
+This will cause the cache to be refreshed every 15 minutes, even if it has not been explicitly expired.
+That way, any changes to the record will be reflected by other processes in at most 15 minutes.
+Keep in mind, however, that using this strategy will lead to inconsistency between processes as they
+won't all reflect the changes at the same time.
+
+When you want to edit the record, you can call `Rimcache.fetch` with the `for_update` keyword argument:
+
+```ruby
+class Site < ActiveRecord::Base
+  has_many :features
+
+  after_update :expire_rimcache
+
+  def self.fetch_by_slug(slug, for_update: false)
+    Rimcache.fetch("site_#{slug}", for_update:) do
+      # This will only be called if site is not already in cache or was expired
+      Site.eager_load(:features).find_by(slug:)
+    end
+  end
+
+  def expire_rimcache
+    Rimcache.expire("site_#{slug}")
+  end
+end
+```
+
+Then a Site can be updated like this:
+
+```ruby
+site = Site.fetch_by_slug(:example, for_update: true)
+site.update!(name: "New Name") # after_update callback expires the rimcache
+```
+
+Note that `for_update` does not handle expiration, it just ensures the record is refreshed
+from the database and not frozen.
+
+
+### Expiry cache
+
+Rimcache by default uses Rails' low-level caching to coordinate expiration across processes.
+If you want to use a different cache store, you can set `Rimcache.config.expiry_cache` to an instance of
+`ActiveSupport::Cache::Store`.
+
+```ruby
+Rimcache.config.expiry_cache # defaults to Rails.cache
+Rimcache.config.expiry_cache = ActiveSupport::Cache::MemoryStore.new
+```
+
+If you want to use the same cache store as Rails but avoid conflicts, such as with
+another instance of `Rimcache::Store`, you can change `Rimcache.config.expiry_cache_key`:
+
+```ruby
+alt_rimcache = Rimcache::Store.new
+alt_rimcache.config.expiry_cache_key = "alt_rimcache"
+```
+
+In order to reduce the number of hits to the expiry cache, Rimcache only checks it
+every 4 seconds by default. This can be changed with `Rimcache.config.check_frequency`:
+
+```ruby
+Rimcache.config.check_frequency = 30.seconds
+Rimcache.config.check_frequency = nil # always check the expiry cache
+```
+
+
+<!--
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+-->
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mckeed/rimcache.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/README.rdoc

@@ -0,0 +1,12 @@
+= Rimcache - the Right-in-Memory Cache
+
+"Caches" your commonly-used objects by just storing them frozen in a global hash.
+
+  Rimcache.cache(:default_settings) do
+    Settings.default
+  end
+
+It avoids a round-trip to Redis/memcache and serialization, so associations will stay loaded.
+
+Expiration is coordinated between processes via `Rails.cache` or a configurable ActiveSupport::Cache::Store.
+See +Rimcache::Config+ for configuration options.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/rimcache/config.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "logger"
+require "active_support/all"
+
+module Rimcache
+  # Configuration for Rimcache
+  class Config
+    # An instance of ActiveSupport::Cache::Store used to coordinate Rimcache expiry and invalidation
+    # across processes. If not set, defaults to Rails.cache.
+    # @return [ActiveSupport::Cache::Store]
+    attr_accessor :expiry_cache
+
+    # The cache key to use in expiry_cache.
+    # Defaults to "rimcache_expiry" but can be changed to avoid conflicts.
+    # @return [String | Symbol]
+    attr_accessor :expiry_cache_key
+
+    # The expiry cache will only be checked if it has not been in this much time.
+    # A stale cached value can keep being returned for up to this long after another
+    # process invalidates it.
+    # Defaults to 4 seconds
+    # @return [ActiveSupport::Duration] time in seconds
+    attr_accessor :check_frequency
+
+    # If this is set, rimcached values will be refreshed after this much
+    # time even if they have not been explicitly expired.
+    # Default value is +nil+.
+    # @return [ActiveSupport::Duration] time in seconds
+    attr_accessor :refresh_interval
+
+    def initialize
+      @check_frequency = 4.seconds
+      @expiry_cache_key = "rimcache_expiry"
+    end
+  end
+end

data/lib/rimcache/store.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require "active_support/all"
+
+module Rimcache
+  # The core of Rimcache. Stores frozen objects in a Hash while tracking when
+  # they were last stored and when they were last updated by any process connected
+  # to the same cross-process expiry cache.
+  #
+  # Access this via Rimcache.store for a singleton instance.
+  #
+  class Store
+    attr_accessor :config, :cached
+
+    def initialize
+      @config = Config.new
+      @cached = {}
+      @written_at = {}
+      @last_check = Time.current
+
+      # @expiry_cache is set on first demand to give the best chance
+      # that Rails.cache is loaded when we try to access it
+      @expiry_cache = nil
+      @expiry = nil
+    end
+
+    # Returns the value cached under +key+
+    def read(key)
+      cached[key]
+    end
+
+    # Returns true if no value has been cached for +key+ yet, if +expire+ has been
+    # called from any process with access to the same +expiry_cache+
+    # @return [Boolean] Whether the value under +key+ needs to be refreshed.
+    def expired?(key)
+      last_update = @written_at[key]
+      return true if !cached[key] || needs_refresh?(last_update)
+
+      # Check if another process has changed the value since we read it
+      expired_at = reload_expiry[key]
+      !!expired_at && expired_at > last_update
+    end
+
+    # Update the expiry_cache to notify other processes that the
+    # rimcached object at this key has changed and must be refreshed.
+    def expire(key)
+      cached[key] = nil
+      reload_expiry(force: true)
+      @expiry[key] = Time.current
+      expiry_cache.write(config.expiry_cache_key, @expiry, expires_in: nil)
+    end
+
+    # Fetches or updates data from the rimcache at the given key.
+    # If there's an unexpired stored value it is returned. Otherwise,
+    # the block is called and the result is frozen, stored in the rimcache
+    # under this key, and returned.
+    #
+    # The keyword argument +for_update+ can be set to +true+ to call the block
+    # and return the result unfrozen instead of caching it. You must still call
+    # +expire(key)+ or +update(key, value)+ after updating the record in the database.
+    #
+    def fetch(key, for_update: false)
+      raise(ArgumentError, "Rimcache: tried to store to cache with nil key") if key.nil?
+
+      if for_update
+        cached[key] = nil
+        yield
+      elsif expired?(key) || !cached[key]
+        write(key, yield.freeze) if block_given?
+      else
+        read(key)
+      end
+    end
+
+    # Expires the rimcache for this key and saves a frozen clone of +value+
+    # as the new value.
+    def update(key, value)
+      expire(key)
+      write(key, value.clone.freeze)
+    end
+
+    private
+
+    def needs_refresh?(last_update)
+      return true if last_update.nil?
+
+      !config.refresh_interval.nil? && Time.current - last_update > config.refresh_interval
+    end
+
+    def reload_expiry(force: false)
+      # Only check expiry_cache every few seconds for excessive efficiency
+      now = Time.current
+      return @expiry unless force || @expiry.nil? || now - @last_check > config.check_frequency
+
+      @last_check = now
+      @expiry = expiry_cache.read(config.expiry_cache_key) || {}
+    end
+
+    def write(key, value)
+      @written_at[key] = Time.current
+      cached[key] = value # must return value
+    end
+
+    # @return [ActiveSupport::Cache::Store]
+    def expiry_cache
+      @expiry_cache ||= config.expiry_cache || rails_cache || fallback_cache
+    end
+
+    def rails_cache
+      require "rails"
+      Rails.cache
+    rescue LoadError, NoMethodError
+      # return nil if there's no rails or no Rails.cache
+    end
+
+    def fallback_cache
+      puts "[Rimcache] Warning: no expiry cache found. Rimcache will not be invalidated across multiple processes."
+      ActiveSupport::Cache::MemoryStore.new
+    end
+  end
+end

data/lib/rimcache/version.rb

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

data/lib/rimcache.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "rimcache/store"
+require_relative "rimcache/version"
+
+# The main entry point to Rimcache.
+# "Caches" commonly-used objects by just storing them frozen in a global hash.
+# Expiration is handled via Rails low-level caching or a configurable ActiveSupport::Cache::Store.
+#
+module Rimcache
+  # A singleton instance of +Rimcache::Store+.
+  def self.store
+    @store ||= Store.include(Singleton).instance
+  end
+
+  # The +Rimcache::Config+ object associated with the singleton +store+
+  def self.config
+    store.config
+  end
+
+  # Fetches or updates data from the rimcache at the given key.
+  # If there's an unexpired stored value it is returned. Otherwise,
+  # the block is called and the result is frozen, stored in the rimcache
+  # under this key, and returned.
+  #
+  # The keyword argument +for_update+ can be set to +true+ to call the block
+  # and return the result unfrozen instead of caching it. You must still call
+  # +expire(key)+ or +update(key, value)+ after updating the record in the database.
+  #
+  def self.fetch(...)
+    store.fetch(...)
+  end
+
+  def self.expire(...)
+    store.expire(...)
+  end
+
+  module_function
+
+  # You can include +Rimcache+ in your model to use +rimcache+ instead of +Rimcache.fetch+
+  def rimcache(...)
+    Rimcache.fetch(...)
+  end
+
+  # You can include +Rimcache+ in your model to use +rimcache_expire+ instead of +Rimcache.expire+
+  def rimcache_expire(...)
+    Rimcache.expire(...)
+  end
+end

data/sig/rimcache.rbs

@@ -0,0 +1,27 @@
+# The main entry point to Rimcache.
+# "Caches" commonly-used objects by just storing them frozen in a global hash.
+# Expiration is handled via Rails low-level caching or a configurable ActiveSupport::Cache::Store.
+#
+module Rimcache
+  self.@store: untyped
+
+  # A singleton instance of +Rimcache::Store+.
+  def self.store: () -> Store
+
+  # The +Rimcache::Config+ object associated with the singleton +store+
+  def self.config: () -> Config
+
+  # Fetches or updates data from the rimcache at the given key.
+  # If there's an unexpired stored value it is returned. Otherwise,
+  # the block is called and the result is frozen, stored in the rimcache
+  # under this key, and returned.
+  #
+  # The keyword argument +for_update+ can be set to +true+ to call the block
+  # and return the result unfrozen instead of caching it. You must still call
+  # +expire(key)+ or +update(key, value)+ after updating the record in the database.
+  #
+  def self.fetch: ((String | Symbol | Object) key, ?for_update: bool) { (void) -> T } -> T
+
+  # You can include +Rimcache+ in your model to use +rimcache+ instead of +Rimcache.fetch+
+  def self?.rimcache: ((String | Symbol | Object) key, ?for_update: bool) { (void) -> T } -> T
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: rimcache
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Duncan McKee
+bindir: exe
+cert_chain: []
+date: 2025-05-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+description: |
+  "Caches" commonly-used objects by just storing them frozen in a global hash.
+  Expiration is handled via Rails low-level caching or an ActiveSupport::Cache
+email:
+- mckeed+rubygems@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- README.rdoc
+- Rakefile
+- lib/rimcache.rb
+- lib/rimcache/config.rb
+- lib/rimcache/store.rb
+- lib/rimcache/version.rb
+- sig/rimcache.rbs
+homepage: https://github.com/mckeed/rimcache
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/mckeed/rimcache
+  source_code_uri: https://github.com/mckeed/rimcache
+  changelog_uri: https://github.com/mckeed/rimcache/tree/CHANGELOG.md
+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.6.2
+specification_version: 4
+summary: Keep commonly-used records in memory with expiration coordinated via the
+  Rails cache.
+test_files: []