active_remote-cached 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c89a29c20fea4fff1a59ab534285774e7758620a73fc4005866011326b67ddbe
-  data.tar.gz: 1fbb57ba895a2aedb8067e399ac747cd6428b2e11c18c043e0fc9fbd8e3a63a1
+  metadata.gz: db04ead0732ea2b7c372a7c7f674a8d3450c483a05688a56ee3684f2dc7c2688
+  data.tar.gz: 6d0823e6ff844c6effb2da7dddc15353da1240a694cc88324a1ed9c1d273189c
 SHA512:
-  metadata.gz: e07972d8b297ad00be81d09dc05330075db0f744d6d40f0323135f326368846325cc66975f8771260d14ba5cd96156c36e134e9bf500df4bff924d6bdcc9ef82
-  data.tar.gz: 5a1818958e13bac846e04616c1762f1fdbb3d7e5e664d8d7c56e86b36e1fa10d608bf242bd666e43ba1bea5eef6f3a17be01e2c1f715bab205413aabe3a764eb
+  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

@@ -0,0 +1,58 @@
+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/**/*'
+
+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:
+    - 'lib/active_remote-cached.rb'
+
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'lib/active_remote/cached.rb' # this module is big
+
+Style/Documentation:
+  Enabled: false
+
+# The generated finder methods in this file are long heredocs.
+Metrics/MethodLength:
+  Exclude:
+    - 'lib/active_remote/cached.rb'
+    - 'spec/**/*'
+
+Style/HashSyntax:
+  Description: >-
+                 Prefer Ruby 1.8 hash syntax { :a => 1, :b => 2 }
+                 over 1.9 syntax { a: 1, b: 2 }.
+  StyleGuide: 'https://git.moneydesktop.com/dev/ruby-style-guide#hash-literals'
+  EnforcedStyle: hash_rockets
+  Exclude:
+    - 'Gemfile'
+
+# Use lambdas instead of stabbys
+Style/Lambda:
+  EnforcedStyle: lambda

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/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in active_remote-cached.gemspec

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

data/active_remote-cached.gemspec

@@ -1,27 +1,58 @@
-# -*- encoding: utf-8 -*-
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+require 'English'
+
+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.name          = 'active_remote-cached'
   gem.version       = ActiveRemote::Cached::VERSION
-  gem.authors       = ["Brandon Dewitt", "MXDevExperience"]
-  gem.email         = ["brandonsdewitt@gmail.com", "devexperience@mx.com"]
-  gem.description   = %q{ Provides "cached" finders and a DSL to enumerate which finders should have cached versions }
-  gem.summary       = %q{ Provides a configuration for caching mechanisms and finders on ActiveRemote models that are cached/cacheable }
-  gem.homepage      = ""
-
-  gem.files         = `git ls-files`.split($/)
-  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"
-  gem.add_dependency "activesupport"
-
-  gem.add_development_dependency "bundler"
-  gem.add_development_dependency "mocha"
-  gem.add_development_dependency "pry"
-  gem.add_development_dependency "rake"
+  gem.authors       = ['Brandon Dewitt', 'MXDevExperience']
+  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      = HOMEPAGE
+  gem.license       = 'MIT'
+
+  gem.metadata = {
+    'homepage_uri' => HOMEPAGE,
+    'source_code_uri' => HOMEPAGE,
+    'rubygems_mfa_required' => 'true'
+  }
+
+  gem.required_ruby_version = '>= 3.1'
+  gem.files         = gem_files
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.require_paths = ['lib']
+
+  gem.add_dependency 'active_remote', '>= 6.1'
+  # 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', '~> 1.80'
 end

data/lib/active_remote/cached/argument_keys.rb

@@ -1,57 +1,94 @@
-module ActiveRemote::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
-
-    def initialize(*arguments, options)
-      @options = options
-      @arguments = arguments.flatten.compact
-      @argument_string = ""
-
-      @arguments.each do |argument|
-        @argument_string << "#{argument}"
-      end
-    end
+# frozen_string_literal: true
+
+module ActiveRemote
+  module Cached
+    class ArgumentKeys
+      attr_reader :arguments, :argument_string, :options
+
+      REMOVE_CHARACTERS = /[[:space:]+=><{}\[\];:\-,]/
+      # 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{[%./]}
 
-    def cache_key
-      return @argument_string.gsub(REMOVE_CHARACTERS, "") if remove_characters?
-      if replace_characters?
-        REPLACE_MAP.each do |character, replacement|
-          @argument_string.gsub!(character, replacement)
+      # 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
 
-      @argument_string
-    end
+      def self.normalize_value(value)
+        [value].flatten.compact.map { |element| escape_value(element) }.join(FIELD_SEPARATOR)
+      end
+      private_class_method :normalize_value
 
-    def to_s
-      cache_key
-    end
+      def self.escape_value(value)
+        value.to_s.gsub(ESCAPE_CHARACTERS, ESCAPE_MAP)
+      end
+      private_class_method :escape_value
 
-    private
+      def initialize(*arguments, options)
+        @options = options
+        @arguments = arguments.flatten.compact
+        @argument_string = @arguments.join
+      end
 
-    def remove_characters?
-      options.fetch(:active_remote_cached_remove_characters, false)
-    end
+      def cache_key
+        return @argument_string.gsub(REMOVE_CHARACTERS, '') if remove_characters?
+        return @argument_string unless replace_characters?
+
+        # One pass, rather than one gsub for each entry in the map.
+        @argument_string.gsub(REPLACE_CHARACTERS, REPLACE_MAP)
+      end
+
+      def to_s
+        cache_key
+      end
+
+      private
 
-    def replace_characters?
-      options.fetch(:active_remote_cached_replace_characters, false)
+      def remove_characters?
+        options.fetch(:active_remote_cached_remove_characters, false)
+      end
+
+      def replace_characters?
+        options.fetch(:active_remote_cached_replace_characters, false)
+      end
     end
   end
 end