builder-rails_cache 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c4aa749a4640d7ca3fe3729890999c3c51fe0bd1b273cde488367410c9496acf
+  data.tar.gz: a117fcaef9eaa8b354b3d047585d43af8e0261c4bddf66c903f735cfa2ec9f44
+SHA512:
+  metadata.gz: ba317a626c14dda2d79925cee3757ce47ead9ec88a5ecb1bfff034c65e72be0619f232d552d79f1d819cf0ce1900c716e957faaa0ef3141c78273e5b53b1fd8d
+  data.tar.gz: ec9cca1b5820d6e03ab90d8d0903f44494c50c193c79d95d6aebf66cf79d34e284d9ee56dd16452f8d57ff23cb1eb8950ef695ab577d1723d639391be1ba838e

data/.rspec

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

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-11-21
+
+- Initial release

data/README.md

@@ -0,0 +1,321 @@
+# Builder::RailsCache
+
+Provides a convenient `with_cache do ... end` wrapper around caching Rails responses, and shared_examples for use in your controller tests.
+
+```ruby
+  def index
+    # Cache the response across all users
+    json = with_cache do
+      # this code will only be called
+      # if the response is already cached,
+      # and the cache entry has not expired 
+      @records = MyModelClass.where(....)
+      # The return value of the block will be 
+      # what gets stored in the cache, so it's 
+      # simplest to just return the generated JSON
+      @records.to_json
+    end
+    # render whatever we got back from the cache if it was a hit,
+    # or whatever the block generated if it was a cache miss
+    render json: json, status: :ok
+  end
+```
+
+## Installation
+
+1. Add the gem to your Gemfile:
+
+```ruby
+  gem 'builder-rails_cache'
+```
+
+2. Install the gem
+
+```bash
+> bundle
+```
+
+_NOTE: future versions will automate as much of the following steps as possible - but for now, this must be a manual process_
+
+### Installing the gem into your application
+
+1. Include the module in your `ApplicationController` 
+
+(this can either be the global `BuilderBase::ApplicationController` or just for one specific module if you prefer):
+
+```
+  class ApplicationController < ActionController::Base
+    include Builder::RailsCache
+  end
+```
+
+2. Enable caching locally in development mode, if `RAILS_CACHE_STORE` is given
+
+In `config/environments/development.rb`, you should see a block something like this, usually around line 18 or so:
+
+```ruby
+  # Enable/disable caching. By default caching is disabled.
+  # Run rails dev:cache to toggle caching.
+  if Rails.root.join('tmp', 'caching-dev.txt').exist?
+    config.cache_store = :memory_store
+    config.public_file_server.headers = {
+      'Cache-Control' => "public, max-age=#{2.days.to_i}"
+    }
+  else
+    config.action_controller.perform_caching = false
+    config.cache_store = :null_store
+  end
+```
+
+Add another `elsif` clause to that block, so that it reads:
+
+```ruby
+  # Enable/disable caching. By default caching is disabled.
+  # Run rails dev:cache to toggle caching.
+  if Rails.root.join('tmp', 'caching-dev.txt').exist?
+    config.cache_store = :memory_store
+    config.public_file_server.headers = {
+      'Cache-Control' => "public, max-age=#{2.days.to_i}"
+    }
+  # NEW LINES START HERE ----------------
+  elsif ENV['RAILS_CACHE_STORE'].present?
+    config.cache_store = ENV['RAILS_CACHE_STORE'].to_sym
+  # /END OF NEW LINES -------------------
+  else
+    config.action_controller.perform_caching = false
+    config.cache_store = :null_store
+  end
+```
+
+3. Enable caching in production mode, if `RAILS_CACHE_STORE` is given
+   
+Note: this code will enable caching in all deployed environments (dev, stage, uat, prod etc),
+_but only if the RAILS_CACHE_STORE environment variable is present_ - so if you're cautious,
+you can push the code first, and then do a separate MR to provide the config which actually enables the cache
+in each environment, making it a simple job to revert it if anything goes wrong.
+
+Add these lines to `config/environment/production.rb`, anywhere _inside_ the `Rails.application.configure do ... end` block:
+
+```ruby
+  if ENV['RAILS_CACHE_STORE'].present?
+    config.cache_store = ENV['RAILS_CACHE_STORE'].to_sym
+  end
+```
+
+4. Include the `Builder::RailsCache` module in your ApplicationController:
+
+```ruby
+  module BuilderBase
+    class ApplicationController
+      include Builder::RailsCache
+    end
+ end
+```
+
+## Usage
+
+### Adding response-caching to a controller method
+ 
+For example, assume your controller method looks like this:
+
+```
+  def index
+    # Slow query:
+    @records = MyModelClass.where(....)
+    # maybe some other code is here too
+
+    # ultimately a response is rendered as JSON:
+    render json: @records.as_json, status: :ok
+  end
+```
+
+You can add a `with_cache` block around everything involved in generating the JSON - constructing 
+queries, retrieving the data, calling any serializers, etc.
+
+*NOTE* - The Rails cache ultimately stores _strings_ in Redis (or whatever other cache store you my have configured)
+So you'll need to split the _conversion of the result to_ JSON, from the _rendering_ of the result back to 
+the caller, like this:
+
+```ruby
+  def index
+    json = with_cache do
+      @records = MyModelClass.where(....)
+      @records.to_json
+    end
+    render json: json, status: :ok
+  end
+```
+
+#### Options / parameters
+
+`with_cache` accepts the following parameters, all are *optional*:
+
+##### `:user_id`
+
+This value will form the first part of the cache key
+
+*Caching a user-specific response for each user*
+Pass the current users' ID (e.g. `current_user.id`) to cache a different value for each user.
+It's important to do this if anything in the code _inside_ the block (including within any serializers called, etc) references the current user
+
+*Re-using the same cached value across all users*
+Pass nil (or just don't supply the parameter, as *nil is the default*) to cache the same value across all users
+
+
+##### `:cache_time`
+
+Determines expiry / TTL of the cache entry. If an entry is in the cache, but older than this value, it will be treated
+as if there is no cache entry there at all.
+
+*Default*
+If no value is given, it will use the value of `ENV['RAILS_CACHE_TIMEOUT_SECONDS']`. If that environment
+variable is not defined, or not parseable to an integer, it will default to zero - i.e. effectively disabling
+the caching
+
+*Specifying a number of seconds*
+If the value is an integer, it will use that as the number of seconds for which the cache entry will be considered valid.
+
+*Using a particular environment variable*
+If the value is a string or symbol, it will append that string (uppercased) to `RAILS_CACHE_TIMEOUT_SECONDS` and look 
+for an environment variable with that name to use. 
+For example, if you pass `:short` or `:long` this will use the value of the `ENV['RAILS_CACHE_TIMEOUT_SECONDS_SHORT']` or `ENV['RAILS_CACHE_TIMEOUT_SECONDS_LONG)']` env vars - letting you have different cache timeouts for different methods.
+
+
+
+##### `:headers_to_include`
+
+An array of header names, the values of which will be included in the key.
+This might be useful if your application uses, for instance, a `language` header to render different strings
+
+
+
+##### `:key`
+
+If a value is given, it will use that value as the cache key.
+If no value is given (*default*), it will construct a key using a combination of :
+* the given `user_id` (optional)
+* the full request URL including all query parameters
+* any headers specified in the given `headers_to_include` (optional). 
+
+If `user_id` is NOT given, then the same cache key will be used for all users (assuming they pass the same parameters and have the same values of the named headers), so make sure you consider this when introducing caching.
+
+#### Error handling / returning non-200 status
+
+The contents of the block are not called at all if there's a cache hit - so you may need to put a little thought into how to handle any non-OK status that you might want to return.
+
+For example, this code -
+
+```
+  def show
+    @record = MyClass.find(params[:id])
+    render json: @record.to_json, status: :ok
+  end
+```
+
+- has a potential edge case in the `.find` call. It will raise an `ActiveRecord::RecordNotFound` exception if the ID doesn't exist, which usually gets caught elsewhere and a 404 status returned. For this case, an exception will still bubble out of the block and be handled in the normal way, so this code should not need modifying.
+
+But if your controller method decides on response status without raising an exception, modification may be needed.
+For example:
+
+```ruby
+  def show
+    @record = MyClass.find(params[:id])
+    if @record.group_id != current_user.group_id
+      render json: { errors: ["You don't have permission to read that record"] }.to_json, status: :forbidden
+    else
+      render json: @record.to_json, status: :ok
+    end
+  end
+```
+
+This code may need a slight alteration to handle this case, something like this:
+
+```ruby
+  def show
+    result = with_cache do
+      @record = MyClass.find(params[:id])
+      if @record.group_id != current_user.group_id
+        'forbidden'
+      else
+        @record.to_json
+      end
+    end
+    
+    if result == 'forbidden'
+      render json: { errors: ["You don't have permission to read that record"] }.to_json, status: :forbidden
+    else
+      render json: result, status: :ok
+    end
+  end
+```
+
+
+### Testing caching behaviour
+
+#### Shared examples
+
+The gem provides three shared examples, which you can add to your controller tests as follows:
+
+Assuming your controller method looks like the example above,
+you can use these shared examples in your specs like this:
+
+```ruby
+  describe 'GET :index' do
+    # define the object & method which your caching block
+    # surrounds:
+    let(:object_with_cache_miss_method) { MyModelClass }
+    let(:method_called_on_cache_miss) { :where }
+
+    # two user accounts, so that it can test the caching behaviour
+    # across different users accessing the same methods
+    let(:account_1) { ...user account object 1... }
+    let(:account_2) { ...user account object 2... }
+    
+    # test the universal cache behaviour
+    it_behaves_like 'a cached method'
+
+    # ...and EITHER
+    it_behaves_like 'it has a different cache entry for each user'
+    # OR
+    it_behaves_like 'it has the same cache entry for all users'
+  end
+```
+
+That will test for standard caching behaviour, using an expectation like:
+
+`expect(object_with_cache_miss_method).to receive(:method_called_on_cache_miss)`
+
+to signal a cache miss, and:
+
+`expect(object_with_cache_miss_method).not_to receive(:method_called_on_cache_miss)`
+
+to signal a cache hit.
+
+You should ultimately get results that look something like this:
+
+```ruby
+      behaves like a cached method
+        caching
+          when the cache_timeout is more than zero
+            hitting the url twice for the same user with the same params
+              does not calls the code surrounded by with_cache the second time
+              returns the same response each time
+              after the cache expiry
+                calls the code surrounded by with_cache both times
+            hitting the url twice for the same user with different params
+              calls the code surrounded by with_cache both times
+      behaves like it has a different cache entry for each user
+        hitting the url twice for two different users with the same params
+          calls the code surrounded by with_cache both times
+
+```
+
+## Development
+
+After checking out the repo, run `rake spec` 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 Builder's GitLab at https://gitlab.builder.ai/cte/alistair-davidson/builder-rails_cache.

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/builder-rails_cache.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "lib/builder/rails_cache/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "builder-rails_cache"
+  spec.version = Builder::RailsCache::VERSION
+  spec.authors = ["Alistair Davidson"]
+  spec.email = ["alistair.davidson@builder.ai"]
+
+  spec.summary = "Provides convenience method `with_cache` for caching API response JSON"
+  spec.description = "Provides convenience method `with_cache` for caching API response JSON"
+  spec.homepage = "https://gitlab.builder.ai/cte/alistair-davidson/builder-rails_cache"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  # spec.metadata["allowed_push_host"] = "https://gem.fury.io/engineerai"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git appveyor Gemfile])
+    end
+
+  end
+  # make our shared examples available to projects which install the gem 
+  spec.files += `git ls-files -- spec/shared_examples/*.rb`.split("\n")
+
+  # spec.bindir = "exe"
+  # spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency 'rails', '>= 4.0'
+  spec.add_development_dependency "byebug"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/lib/builder/rails_cache/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Builder
+  module RailsCache
+    VERSION = "0.1.1"
+  end
+end

data/lib/builder/rails_cache.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "rails_cache/version"
+
+module Builder
+  module RailsCache
+    class Error < StandardError; end
+    
+    protected
+
+    # :cache_time determines expiry
+    # pass :short or :long to use the ENV['RAILS_CACHE_TIMEOUT_SECONDS_(SHORT|LONG)'] env vars
+    # or an integer to use a specific number of seconds
+    #
+    # :user_id will be the first part of the key
+    # Pass @token.id to cache a different value for each user
+    # or nil (default) to cache the same value across all users
+    #
+    # :key will default to nil, in which case a key will be constructed 
+    # from the user_id, the url, and the headers_to_include
+    def with_cache(cache_time: :short, user_id: nil, key: nil, headers_to_include: [])
+      timeout = cache_timeout(cache_time)
+      key ||= cache_key(user_id: user_id, headers_to_include: headers_to_include)
+      logger.debug "cache key: #{key}, timeout: #{timeout}"
+      cache_hit = true
+
+      data = cache_instance.fetch(key, expires_in: timeout) do
+        cache_hit = false
+        yield if block_given?
+      end
+      logger.debug( cache_hit ? 'CACHE HIT' : 'CACHE MISS')
+      data
+    end
+
+    def cache_instance
+      Rails.cache
+    end
+
+    def cache_key(user_id: nil, headers_to_include: [])
+      headers = request.headers.select{|k,v| headers_to_include.include?(k)}.map{|k,v| [k,v].join('=')}.flatten.join('&')
+      [user_id, request.url, headers]
+    end
+
+    # pass a symbol or string to use the value of the ENV['RAILS_CACHE_TIMEOUT_SECONDS_(...)'] env var
+    # (e.g. if you pass :short, it will use ENV['RAILS_CACHE_TIMEOUT_SECONDS_SHORT'])
+    # pass an integer to use a specific number of seconds - if this 0, it's essentially a force-refresh
+    # the default is 0
+    def cache_timeout(short_long_or_seconds = nil)
+      if short_long_or_seconds.is_a?(Integer)
+        short_long_or_seconds
+      elsif short_long_or_seconds.is_a?(Symbol) || short_long_or_seconds.is_a?(String)
+        ENV[ ["RAILS_CACHE_TIMEOUT_SECONDS", short_long_or_seconds.to_s.upcase].join('_') ].to_i
+      else
+        0
+      end
+    end
+  end
+end
+
+
+# Make the shared examples available to projects which install this gem
+# as per https://stackoverflow.com/a/50688950
+if ENV['RAILS_ENV'] == 'test'
+  require File.expand_path('../../spec/shared_examples/cached_method.rb', __dir__)
+end

data/sig/builder/rails_cache.rbs

@@ -0,0 +1,6 @@
+module Builder
+  module RailsCache
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

data/spec/shared_examples/cached_method.rb

@@ -0,0 +1,133 @@
+#
+# If your controller method looks like this:
+# ```
+#   def index
+#     json = with_cache do
+#       @records = MyModelClass.where(....)
+#       @records.to_json
+#     end
+#     render json: json, status: :ok
+# ```
+#
+# You can use this shared example in your specs like this:
+#
+# ```
+#   describe 'GET :index' do
+#     let(:object_with_cache_miss_method) { MyModelClass }
+#     let(:method_called_on_cache_miss) { :where }
+#
+#     it_behaves_like 'a cached method'
+#     # and EITHER
+#     it_behaves_like 'it has a different cache entry for each user' 
+#     # OR
+#     it_behaves_like 'it has the same cache entry for all users'
+#   end
+# ```
+#
+# That will test for standard caching behaviour, using the expectation:
+# `expect(object_with_cache_miss_method).to receive(:method_called_on_cache_miss)`
+# to signal a cache miss, and:
+# `expect(object_with_cache_miss_method).not_to receive(:method_called_on_cache_miss)`
+# to signal a cache hit
+#
+RSpec.shared_examples "a cached method" do
+  describe 'caching' do
+    let(:token_1) { BuilderJsonWebToken.encode(account_1.id, 1.day.from_now, token_type: 'login') }
+    let(:token_2) { BuilderJsonWebToken.encode(account_2.id, 1.day.from_now, token_type: 'login') }
+
+    # default cache for test environment is null_store, which does not actually write data
+    # so we need to force usage of memory_store in these tests
+    let(:memory_store) { ActiveSupport::Cache.lookup_store(:memory_store) }
+    let(:cache) { Rails.cache }
+
+    before do
+      allow(Rails).to receive(:cache).and_return(memory_store)
+      Rails.cache.clear
+    end
+
+    context 'when the cache_timeout is more than zero' do
+      before do
+        allow(controller).to receive(:cache_timeout).and_return(1)
+      end
+
+      context 'hitting the url twice for the same user with the same params' do
+        let(:params) { {some_param: 3, token: token_1} }
+        before do
+          request.headers['token'] = token_1
+        end
+
+        it 'does not calls the code surrounded by with_cache the second time' do
+          expect(object_with_cache_miss_method).to receive(method_called_on_cache_miss).exactly(:once).and_return([])
+          get :current_conditions, params: params
+          get :current_conditions, params: params
+        end
+
+        it 'returns the same response each time' do
+          get :current_conditions, params: params
+          response_1 = response.body.dup
+          get :current_conditions, params: params
+          response_2 = response.body.dup
+          expect(response_1).to eq(response_2)
+        end
+
+        context 'after the cache expiry' do
+          it 'calls the code surrounded by with_cache both times' do
+            expect(object_with_cache_miss_method).to receive(method_called_on_cache_miss).exactly(:twice).and_return([])
+            get :current_conditions, params: params
+            sleep(1.1)
+            get :current_conditions, params: params
+          end
+        end
+      end
+
+      context 'hitting the url twice for the same user with different params' do
+        let(:params_1) { {some_param: 3} }
+        let(:params_2) { {some_param: 3, foo: 'bar'} }
+
+        it 'calls the code surrounded by with_cache both times' do
+          expect(object_with_cache_miss_method).to receive(method_called_on_cache_miss).exactly(:twice).and_return([])
+          request.headers['token'] = token_1
+          get :current_conditions, params: params_1
+          request.headers['token'] = token_1
+          get :current_conditions, params: params_2
+        end
+      end
+    end
+  end
+end
+
+RSpec.shared_examples 'it has a different cache entry for each user' do
+  let(:token_1) { BuilderJsonWebToken.encode(account_1.id, 1.day.from_now, token_type: 'login') }
+  let(:token_2) { BuilderJsonWebToken.encode(account_2.id, 1.day.from_now, token_type: 'login') }
+
+  context 'hitting the url twice for two different users with the same params' do
+    let(:params_1) { {some_param: 3} }
+    let(:params_2) { {some_param: 3} }
+
+    it 'calls the code surrounded by with_cache both times' do
+      expect(object_with_cache_miss_method).to receive(method_called_on_cache_miss).exactly(:twice).and_return([])
+      request.headers['token'] = token_1
+      get :current_conditions, params: params_1
+      request.headers['token'] = token_2
+      get :current_conditions, params: params_2
+    end
+  end
+end
+
+RSpec.shared_examples 'it has the same cache entry for all users' do
+  let(:token_1) { BuilderJsonWebToken.encode(account_1.id, 1.day.from_now, token_type: 'login') }
+  let(:token_2) { BuilderJsonWebToken.encode(account_2.id, 1.day.from_now, token_type: 'login') }
+
+  context 'hitting the url twice for two different users with the same params' do
+    let(:params_1) { {some_param: 3} }
+    let(:params_2) { {some_param: 3} }
+
+    it 'does not calls the code surrounded by with_cache for the second user' do
+      expect(object_with_cache_miss_method).to receive(method_called_on_cache_miss).exactly(:once).and_return([])
+      request.headers['token'] = token_1
+      get :current_conditions, params: params_1
+      request.headers['token'] = token_2
+      get :current_conditions, params: params_2
+    end
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: builder-rails_cache
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Alistair Davidson
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-11-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Provides convenience method `with_cache` for caching API response JSON
+email:
+- alistair.davidson@builder.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- README.md
+- Rakefile
+- builder-rails_cache.gemspec
+- lib/builder/rails_cache.rb
+- lib/builder/rails_cache/version.rb
+- sig/builder/rails_cache.rbs
+- spec/shared_examples/cached_method.rb
+homepage: https://gitlab.builder.ai/cte/alistair-davidson/builder-rails_cache
+licenses: []
+metadata:
+  homepage_uri: https://gitlab.builder.ai/cte/alistair-davidson/builder-rails_cache
+  source_code_uri: https://gitlab.builder.ai/cte/alistair-davidson/builder-rails_cache
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key:
+specification_version: 4
+summary: Provides convenience method `with_cache` for caching API response JSON
+test_files: []