active_remote-cached 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6ac1efd0991c3ee528e08b55099bf6f05a6c1eb243f290e4197be290b725dca
-  data.tar.gz: 34229f667ea990196cf2593fe31207532ddbc60fdd72904c8ff618a5e9b3c5c1
+  metadata.gz: db04ead0732ea2b7c372a7c7f674a8d3450c483a05688a56ee3684f2dc7c2688
+  data.tar.gz: 6d0823e6ff844c6effb2da7dddc15353da1240a694cc88324a1ed9c1d273189c
 SHA512:
-  metadata.gz: e38d49aedda27d13809af64e7f939bd2578dc8f45a3f0f657f0dabf4bae5e3f376078ae6b16bf8765a3e8e7d198f93fb7105e292e7555a1e86927d879c4992ad
-  data.tar.gz: 1c4f37e645e020daf1e4523e6788aa397a1d23a7bda1f59e4335bc17d1501eaaf5343ce7d94a72134d1f56a581099021456f391051dd3f841a432cb627c0d20b
+  metadata.gz: 760fe52b8cc4b6b1e3f5d7bb61af29567f0a8deb99ea0d4b29941bed11f293c1ef43667dcbefb9bf7a18423680871b7dbcd19ef314a9a7e58976385ae0305d59
+  data.tar.gz: 544d6d1e7d17afb3bb125af5d2e66efd41eae5676cd6984491fa9c611d0a0c258e8e8a69020adb13b9ad240dd4f4ab46e548defcd6b06194eee4789ee4402868

data/.github/workflows/ci.yml

@@ -0,0 +1,85 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: ${{ matrix.ruby }} / ${{ matrix.appraisal }}
+    runs-on: ubuntu-latest
+    env:
+      BUNDLE_GEMFILE: ${{ github.workspace }}/Gemfile
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby:
+          - '3.1'
+          - '3.4'
+          - jruby-9.4
+          - jruby-10.0
+        appraisal:
+          - active_remote-6.1
+          - active_remote-7.0
+          - active_remote-7.1
+          - active_remote-7.2
+          - active_remote-8.0
+        exclude:
+          # active_remote 8.0 requires ruby 3.2 or later.
+          # jruby-9.4 is ruby 3.1 compatible.
+          - ruby: '3.1'
+            appraisal: active_remote-8.0
+          - ruby: jruby-9.4
+            appraisal: active_remote-8.0
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Generate the appraisal gemfiles
+        run: bundle exec appraisal generate
+
+      # bundler-cache above only caches the root Gemfile. The appraisal
+      # gemfiles do not exist until the step above runs, so they need their own
+      # cache. Without this every job installs active_remote from cold.
+      - name: Cache the appraisal dependencies
+        uses: actions/cache@v4
+        with:
+          path: gemfiles/vendor/bundle
+          key: ${{ runner.os }}-${{ matrix.ruby }}-${{ matrix.appraisal }}-${{ hashFiles('Appraisals', '*.gemspec') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ matrix.ruby }}-${{ matrix.appraisal }}-
+
+      - name: Install the appraisal dependencies
+        run: |
+          bundle exec appraisal ${{ matrix.appraisal }} bundle config set --local path "$GITHUB_WORKSPACE/gemfiles/vendor/bundle"
+          bundle exec appraisal ${{ matrix.appraisal }} bundle install --jobs 4 --retry 3
+
+      - name: Run the specs
+        run: bundle exec appraisal ${{ matrix.appraisal }} rspec
+
+  rubocop:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Run RuboCop
+        run: bundle exec rubocop --parallel

data/.gitignore

@@ -17,3 +17,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+gemfiles/

data/.rubocop.yml

@@ -1,24 +1,30 @@
 AllCops:
   TargetRubyVersion: 3.1
+  # Do not adopt new cops automatically. Without this, every run prints the
+  # full pending cop list as a warning.
+  NewCops: disable
+  # Keep the default Exclude list. Without this, the Exclude below replaces the
+  # defaults, and RuboCop walks into vendor/bundle and reads the .rubocop.yml of
+  # every installed gem. Some of those name cops that no longer exist.
+  inherit_mode:
+    merge:
+      - Exclude
   Exclude:
     - 'gemfiles/**/*'
 
-Layout/AccessModifierIndentation:
-  Enabled: false
-Layout/CommentIndentation:
-  Enabled: false
-Layout/IndentationConsistency:
-  Enabled: false
-
-Style/AccessModifierDeclarations:
-  Enabled: false
-
 Naming/MethodParameterName:
   Enabled: false
 
 Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
+    - '*.gemspec'
+
+# ActiveSupport cache #fetch only calls the block on a miss, so the block form
+# is not the same as the Hash#fetch default value form.
+Style/RedundantFetchBlock:
+  Exclude:
+    - 'spec/active_remote/cached/cache_spec.rb'
 
 Naming/FileName:
   Exclude:
@@ -32,11 +38,11 @@ Metrics/ModuleLength:
 Style/Documentation:
   Enabled: false
 
+# The generated finder methods in this file are long heredocs.
 Metrics/MethodLength:
-  Enabled: false
-
-Naming/VariableNumber:
-  Enabled: false
+  Exclude:
+    - 'lib/active_remote/cached.rb'
+    - 'spec/**/*'
 
 Style/HashSyntax:
   Description: >-
@@ -50,6 +56,3 @@ Style/HashSyntax:
 # Use lambdas instead of stabbys
 Style/Lambda:
   EnforcedStyle: lambda
-
-Style/MissingRespondToMissing:
-  Enabled: false

data/Appraisals

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+appraise 'active_remote-6.1' do
+  gem 'active_remote', '~> 6.1.0'
+  # activesupport 6.1 is not compatible with concurrent-ruby 1.3.5 and later
+  gem 'concurrent-ruby', '< 1.3.5'
+  # ruby 3.4 removed these from the default gems, activesupport 6.1 still needs them
+  gem 'base64'
+  gem 'bigdecimal'
+  gem 'mutex_m'
+end
+
+appraise 'active_remote-7.0' do
+  gem 'active_remote', '~> 7.0.0'
+end
+
+appraise 'active_remote-7.1' do
+  gem 'active_remote', '~> 7.1.0'
+end
+
+appraise 'active_remote-7.2' do
+  gem 'active_remote', '~> 7.2.0'
+end
+
+appraise 'active_remote-8.0' do
+  gem 'active_remote', '~> 8.0.0'
+end

data/README.md

@@ -1,5 +1,7 @@
 # ActiveRemote::Cached
 
+[![CI](https://github.com/skunkworker/active_remote-cached/actions/workflows/ci.yml/badge.svg)](https://github.com/skunkworker/active_remote-cached/actions/workflows/ci.yml)
+
 Provides cached finders for ActiveRemote models that allow a caching provider to cache the result of a query.
 
 ## Installation
@@ -88,6 +90,125 @@ Each finder as takes an optional options hash that will override the options pas
 customer = ::Customer.cached_find_by_id(1, :expires_in => 15.minutes)
 ```
 
+## Development
+
+Install the dependencies:
+
+```shell
+bundle install
+```
+
+Run the specs against the default gemfile:
+
+```shell
+bundle exec rspec
+```
+
+Run RuboCop:
+
+```shell
+bundle exec rubocop
+```
+
+### Test matrix
+
+This gem uses [appraisal](https://github.com/thoughtbot/appraisal) to test against
+several `active_remote` versions. The `Appraisals` file defines each version.
+
+Generate the gemfiles. They are not committed:
+
+```shell
+bundle exec appraisal generate
+```
+
+Install every appraisal:
+
+```shell
+bundle exec appraisal install
+```
+
+Run the specs against every appraisal:
+
+```shell
+bundle exec appraisal rspec
+```
+
+Run the specs against one appraisal:
+
+```shell
+bundle exec appraisal active_remote-8.0 rspec
+```
+
+Remove the generated gemfiles:
+
+```shell
+bundle exec appraisal clean
+```
+
+CI runs this matrix on Ruby 3.1, Ruby 3.4, JRuby 9.4, and JRuby 10.0.
+`active_remote` 8.0 requires Ruby 3.2 or later. CI does not run that
+version on Ruby 3.1 or JRuby 9.4.
+
+## Upgrading to 1.2.0
+
+### Every cache key changes
+
+Before 1.2.0 the cache key held only the argument values, joined with no
+separator. Three different finders shared one cache entry:
+
+```ruby
+Customer.cached_find_by_name_and_email("x", "y")  # key: "xy"
+Customer.cached_find_by_city_and_state("x", "y")  # key: "xy"  same entry
+Customer.cached_find_by_id("xy")                  # key: "xy"  same entry
+```
+
+The key now names each field, so each finder gets its own entry:
+
+```ruby
+Customer.cached_find_by_name_and_email("x", "y")  # key: "email.y/name.x"
+```
+
+Every existing cache entry becomes a miss after the upgrade. Expect one cold
+period. The gem already causes this on an ActiveSupport upgrade, through
+`RUBY_AND_ACTIVE_SUPPORT_VERSION`.
+
+### A bad call now raises
+
+A dynamic finder called with too few arguments used to pass `nil` for the
+missing field and cache the result. It now raises `ArgumentError`:
+
+```ruby
+Customer.cached_find_by_email_and_name("only_one")  # => ArgumentError
+```
+
+### The cache provider validator raises a new class
+
+`ActiveRemote::Cached::Cache::InvalidCacheProvider` replaces the bare
+`RuntimeError` that `ActiveRemote::Cached.cache` raised for a provider that is
+missing a method.
+
+## Known behavior
+
+Two behaviors are recorded in the specs. Neither is fixed. Read
+`spec/active_remote/cached_spec.rb` for the specs that describe them.
+
+### Finder name matching is not anchored
+
+`_method_missing_name` matches a finder name inside a longer method name. A
+method named `not_cached_find_by_guid` resolves to `cached_find_by_guid`.
+
+### A subclass has its own empty cached_methods list
+
+A subclass inherits the finder methods its parent defined, and the options
+those finders were declared with. It does not inherit the `cached_methods`
+list. The parent accepts the finder arguments in any order. The subclass
+accepts them only in the order the method was defined.
+
+```ruby
+Parent.cached_find_by_beta_and_alpha('B', 'A')  # works
+Child.cached_find_by_beta_and_alpha('B', 'A')   # raises NoMethodError
+```
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1,14 +1,9 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
-require 'rake/testtask'
+require 'rspec/core/rake_task'
+require 'appraisal'
 
-Rake::TestTask.new do |t|
-  t.libs.push 'lib'
-  t.libs.push 'spec'
-  t.pattern = 'spec/**/*_spec.rb'
-  t.verbose = true
-end
+::RSpec::Core::RakeTask.new(:spec)
 
-task :spec => :test
 task :default => :spec

data/active_remote-cached.gemspec

@@ -6,6 +6,21 @@ lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'active_remote/cached/version'
 
+HOMEPAGE = 'https://github.com/mxenabled/active_remote-cached'
+
+# git ls-files returns nothing outside a checkout, so a build from a released
+# tarball needs the glob.
+def gem_files
+  files = if File.directory?(File.join(__dir__, '.git'))
+            `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+          else
+            Dir.glob('{lib,spec}/**/*', File::FNM_DOTMATCH) +
+              %w[LICENSE.txt README.md Rakefile Appraisals active_remote-cached.gemspec]
+          end
+
+  files.reject { |file| File.directory?(file) }
+end
+
 Gem::Specification.new do |gem|
   gem.name          = 'active_remote-cached'
   gem.version       = ActiveRemote::Cached::VERSION
@@ -13,21 +28,31 @@ Gem::Specification.new do |gem|
   gem.email         = ['brandonsdewitt@gmail.com', 'devexperience@mx.com']
   gem.description   = ' Provides "cached" finders and a DSL to enumerate which finders should have cached versions '
   gem.summary       = ' Provides a configuration for caching mechanisms and finders on ActiveRemote models'
-  gem.homepage      = ''
+  gem.homepage      = HOMEPAGE
+  gem.license       = 'MIT'
+
+  gem.metadata = {
+    'homepage_uri' => HOMEPAGE,
+    'source_code_uri' => HOMEPAGE,
+    'rubygems_mfa_required' => 'true'
+  }
 
-  gem.required_ruby_version = '>= 2.6'
-  gem.files         = `git ls-files`.split($INPUT_RECORD_SEPARATOR)
+  gem.required_ruby_version = '>= 3.1'
+  gem.files         = gem_files
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ['lib']
 
   gem.add_dependency 'active_remote', '>= 6.1'
-  gem.add_dependency 'activesupport'
+  # NullStore and ActiveSupport::VERSION::STRING. Matches the active_remote floor.
+  gem.add_dependency 'activesupport', '>= 6.1'
 
+  gem.add_development_dependency 'appraisal'
   gem.add_development_dependency 'bundler'
   gem.add_development_dependency 'mocha'
+  # ostruct leaves the default gems in ruby 4.0
+  gem.add_development_dependency 'ostruct'
   gem.add_development_dependency 'pry'
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'rspec', '>= 3.0'
-  gem.add_development_dependency 'rubocop'
+  gem.add_development_dependency 'rubocop', '~> 1.80'
 end

data/lib/active_remote/cached/argument_keys.rb

@@ -1,45 +1,79 @@
+# frozen_string_literal: true
+
 module ActiveRemote
   module Cached
     class ArgumentKeys
       attr_reader :arguments, :argument_string, :options
 
       REMOVE_CHARACTERS = /[[:space:]+=><{}\[\];:\-,]/
-      REPLACE_MAP = [
-        [' ', 'SP'],
-        ['+', 'PL'],
-        ['=', 'EQ'],
-        ['>', 'GT'],
-        ['<', 'LT'],
-        ['{', 'LB'],
-        ['}', 'RB'],
-        ['[', 'LB2'],
-        [']', 'RB2'],
-        [';', 'SC'],
-        [':', 'CO'],
-        ['-', 'DA'],
-        [',', 'COM']
-      ].freeze
+      # Covers the same characters as REMOVE_CHARACTERS. A tab or a newline
+      # left in a key breaks the Memcached protocol.
+      REPLACE_MAP = {
+        ' ' => 'SP',
+        "\t" => 'TB',
+        "\n" => 'NL',
+        "\r" => 'CR',
+        "\f" => 'FF',
+        "\v" => 'VT',
+        '+' => 'PL',
+        '=' => 'EQ',
+        '>' => 'GT',
+        '<' => 'LT',
+        '{' => 'LB',
+        '}' => 'RB',
+        '[' => 'LB2',
+        ']' => 'RB2',
+        ';' => 'SC',
+        ':' => 'CO',
+        '-' => 'DA',
+        ',' => 'COM'
+      }.freeze
+      REPLACE_CHARACTERS = ::Regexp.union(REPLACE_MAP.keys)
+
+      # The separators below are absent from both REMOVE_CHARACTERS and
+      # REPLACE_MAP, so they survive either option. escape_value/1 escapes them
+      # inside a value, which makes the key one-to-one with the arguments.
+      FIELD_SEPARATOR = '.'
+      PAIR_SEPARATOR = '/'
+      ESCAPE_MAP = { '%' => '%25', FIELD_SEPARATOR => '%2E', PAIR_SEPARATOR => '%2F' }.freeze
+      ESCAPE_CHARACTERS = %r{[%./]}
+
+      # Build a key that names each field, so that two finders with the same
+      # values do not share one cache entry.
+      #
+      #   for_fields([:alpha, :beta], ['x', 'y'], {}).cache_key
+      #   # => "alpha.x/beta.y"
+      #
+      def self.for_fields(field_names, values, options)
+        pairs = field_names.each_with_index.map do |field_name, index|
+          "#{field_name}#{FIELD_SEPARATOR}#{normalize_value(values[index])}"
+        end
+
+        new(pairs.join(PAIR_SEPARATOR), options)
+      end
+
+      def self.normalize_value(value)
+        [value].flatten.compact.map { |element| escape_value(element) }.join(FIELD_SEPARATOR)
+      end
+      private_class_method :normalize_value
+
+      def self.escape_value(value)
+        value.to_s.gsub(ESCAPE_CHARACTERS, ESCAPE_MAP)
+      end
+      private_class_method :escape_value
 
       def initialize(*arguments, options)
         @options = options
         @arguments = arguments.flatten.compact
-        @argument_string = ''
-
-        @arguments.each do |argument|
-          @argument_string << argument.to_s
-        end
+        @argument_string = @arguments.join
       end
 
       def cache_key
         return @argument_string.gsub(REMOVE_CHARACTERS, '') if remove_characters?
+        return @argument_string unless replace_characters?
 
-        if replace_characters?
-          REPLACE_MAP.each do |character, replacement|
-            @argument_string.gsub!(character, replacement)
-          end
-        end
-
-        @argument_string
+        # One pass, rather than one gsub for each entry in the map.
+        @argument_string.gsub(REPLACE_CHARACTERS, REPLACE_MAP)
       end
 
       def to_s

data/lib/active_remote/cached/cache.rb

@@ -5,6 +5,10 @@ require 'delegate'
 module ActiveRemote
   module Cached
     class Cache < ::SimpleDelegator
+      # Raised when the given cache provider is missing a method the library
+      # calls on it.
+      class InvalidCacheProvider < ::StandardError; end
+
       attr_reader :cache_provider
 
       def initialize(new_cache_provider)
@@ -29,14 +33,19 @@ module ActiveRemote
         @nested_cache_provider = ::ActiveSupport::Cache::MemoryStore.new
       end
 
+      def nested_caching?
+        !nested_cache_provider.is_a?(::ActiveSupport::Cache::NullStore)
+      end
+
       def exist?(*args)
         nested_cache_provider.exist?(*args) || super
       end
 
       def fetch(name, options = {})
-        fetch_value = nested_cache_provider.fetch(name, options) { super }
+        provider_options = provider_fetch_options(options)
+        fetch_value = nested_cache_provider.fetch(name, provider_options) { super(name, provider_options) }
 
-        delete(name) unless valid_fetched_value?(fetch_value, options)
+        delete(name) if delete_after_fetch?(fetch_value, options, provider_options)
 
         fetch_value
       end
@@ -54,6 +63,24 @@ module ActiveRemote
 
       attr_reader :nested_cache_provider
 
+      # :skip_nil tells the provider not to write a nil at all, which saves a
+      # write and the delete that follows it. Only an ActiveSupport store is
+      # known to honor the option.
+      def provider_fetch_options(options)
+        return options if options.fetch(:allow_nil, false)
+        return options unless cache_provider.is_a?(::ActiveSupport::Cache::Store)
+
+        options.merge(:skip_nil => true)
+      end
+
+      def delete_after_fetch?(value, options, provider_options)
+        return false if valid_fetched_value?(value, options)
+        # The provider already skipped the write.
+        return false if value.nil? && provider_options[:skip_nil]
+
+        true
+      end
+
       def valid_fetched_value?(value, options = {})
         return false if value.nil? && !options.fetch(:allow_nil, false)
         return false if !options.fetch(:allow_empty, false) && value.respond_to?(:empty?) && value.empty?
@@ -64,10 +91,9 @@ module ActiveRemote
       def validate_provider_method_present(method_name)
         return if cache_provider.respond_to?(method_name)
 
-          raise <<-CACHE_METHOD
-          ActiveRemote::Cached::Cache must respond_to? #{method_name}
-          in order to be used as a caching interface for ActiveRemote
-          CACHE_METHOD
+        raise InvalidCacheProvider,
+              "ActiveRemote::Cached::Cache must respond_to? #{method_name} " \
+              'in order to be used as a caching interface for ActiveRemote'
       end
     end
   end

data/lib/active_remote/cached/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveRemote
   module Cached
-    VERSION = '1.1.1'
+    VERSION = '1.2.0'
   end
 end