cachext 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1141e77be7834868ab37636024f4eeea8c719581
-  data.tar.gz: aed591612989be4abf58211a409542c9f51c189e
+  metadata.gz: 99eccddb9064b17d7043869d9f62d2a39438cd12
+  data.tar.gz: 9cd79f5b34f472c9c855b981cab782e4af3f6086
 SHA512:
-  metadata.gz: 4f0bcdf511a0c61b65ee32a4b7a82c1f14864c08bd9a7c5c609970f6bc8f13cbe3c4c2e183966fb75d16cbeb2ce5a7f5f490c1ab9f02f268df8c1f324248370a
-  data.tar.gz: 7bffc2e75ce62b71a0a3db99c917653304291bb7ad854582a04caf7103bbfc18deb2a9c2e9026959ca51bccf143b9d4d532aa886d5afa312531cdd8ae65a771d
+  metadata.gz: db58512dcee683c1b3a3ea996eb0505f57020e1b81ae8c73e933f10fc9956670fae3cd7d09293063eeeca043305c6a31c800ab4861078265afcb8477866985b7
+  data.tar.gz: 31204397cfda1149f6d77e08a75392359c244a2399a1a7bb8ea0468998b27ebac4e6a13eae8a988621534d95a534596abf29c3a99d4af89377aa20b91b2f7408

data/README.md

@@ -2,24 +2,142 @@
 
 Extensions to normal Rails caching:
 
-* Lock
+* Lock (inspired by https://github.com/seamusabshere/lock_and_cache)
 * Backup
 
-## Installation
+## Quickstart
 
-Add this line to your application's Gemfile:
+```ruby
+Cachext.config.cache = Rails.cache
+Cachext.config.redis = Redis.current
+
+key = [:foo, :bar, 1]
+Cachext.fetch key, expires_in: 2.hours, default: "cow" do
+  Faraday.get "http://example.com/foo/bar/1"
+end
+```
+
+* Other services making the same call at the same time will wait for the
+  first to complete, so only 1 call is made in a 2 hour window
+* A backup of the value is stored too, so if the service raises a
+  Faraday::Error::ConnectionFailed we'll return the backup
+* If no backup exists but we got a ConnectionFailed, we'll return the default
+  of "cow"
 
 ```ruby
-gem 'cachext'
+Record = Struct.new :id
+Cachext.multi [:foo, :bar], [1,2,3], expires_in: 5.minutes do |ids|
+  data = JSON.parse Faraday.get("http://example.com/foo/bar?ids=#{ids.join(',')}")
+  data.each_with_object({}) do |record, acc|
+    acc[record["id"]] = Record.new record["id"]
+  end
+end
+# => { 1 => Record.new(1), 2 => Record.new(2), 3 => Record.new(3) }
 ```
 
-And then execute:
+* The passed block will be called with the ids that were not available in the
+  cache. The return value of the block should either be a hash with keys of
+  ids, or an array of objects that have `id` methods.
+* In the event of a server error (ie `ConnectionFailed`), backup values are
+  used.
 
-    $ bundle
+## Configuration options
+
+```ruby
+Cachext.config.cache = Rails.cache
+```
+
+`Cachext` expects a cache store that has the `ActiveSupport::Cache` interface,
+so that can be Memcache, Redis, FileStore, etc.
+
+```ruby
+Cachext.config.redis = Redis.current
+```
+
+`Cachext` uses redis for locking (the
+[Redlock](https://github.com/leandromoreira/redlock-rb) gem under the hood), so
+we need at least Redis 2.8.
+
+```ruby
+Cachext.config.raise_errors = false
+Cachext.config.default_errors = [
+  Faraday::Error::ConnectionFailed,
+  Faraday::Error::TimeoutError,
+]
+```
+
+By default `Cachext` will not re-raise the standard default errors. Setting
+this to `true` is helpful in a test environment. The `default_errors` are those
+caught as transient issues that a backup will be used for.
+
+```ruby
+Cachext.config.not_found_errors = [Faraday::Error::ResourceNotFound]
+```
+
+If a NotFound exception is raised, the backup is *not* used, and any backup
+that exists will be deleted. Then the exception will be re-raised.
+
+```ruby
+Cachext.config.default_expires_in = 60 # in seconds
+```
+
+The default TTL for values fetched. Only used for the "fresh" cache, not the
+backup (which has no TTL).
+
+```ruby
+Cachext.config.max_lock_wait = 5 # in seconds
+```
+
+The most we'll wait for a lock to unlock. If it takes more than this value to
+get a lock (due to another service holding the lock while making the call),
+we'll fallback to the backup value.
+
+```ruby
+Cachext.config.debug = ENV['CACHEXT_DEBUG'] == "true"
+```
+
+If `debug` is set to `true` (or you run your program/test with
+`CACHEXT_DEBUG=true`), you'll get lots of debug messages around the locking and
+whats going on. Very helpful for debugging :)
+
+```ruby
+Cachext.config.heartbeat_expires = 2 # in seconds
+```
+
+If a process that holds a lock crashes, other processes will have to wait this
+many seconds for the lock to expire.
+
+```ruby
+Cachext.config.error_logger = nil
+```
+
+If set to an object that responds to call, will `call` with any errors caught.
 
 ## Usage
 
-Replace `Rails.cache.fetch` with `Cachext.fetch`.
+```ruby
+Cachext.fetch key, options, &block
+```
+
+Available options:
+
+* `expires_in`: override for the `default_expires_in`, in seconds
+* `default`: object or proc that will be used as the default if no backup is found
+* `errors`: override for the `default_errors` to be caught
+* `reraise_errors`: default `true`, if set to `false` NotFound errors will not
+  be raised
+* `not_found_error`: override for `not_found_errors`
+* `heartbeat_expires`: override for `heartbeat_expires`
+
+```ruby
+Cachext.multi key_base, ids, options, &block
+```
+
+Available options:
+
+* `expires_in`: override for `default_expires_in`, in seconds
+* `return_array`: return an array instead of a hash. Will include missing
+  records as `Cachext::MissingRecord` objects so you can deal with them.
 
 ## Development
 

data/lib/cachext/client.rb

@@ -40,7 +40,7 @@ module Cachext
     end
 
     def handle_error key, options, error
-      @config.error_logger.error error
+      @config.error_logger.call error if @config.log_errors?
       raise if @config.raise_errors && reraise_errors
     end
 

data/lib/cachext/configuration.rb

@@ -36,5 +36,9 @@ module Cachext
     def lock_redis
       @lock_redis ||= Redis::Namespace.new :cachext, redis: redis
     end
+
+    def log_errors?
+      error_logger.present?
+    end
   end
 end

data/lib/cachext/multi.rb

@@ -4,7 +4,7 @@ require "active_support/core_ext/hash/reverse_merge"
 
 module Cachext
   class Multi
-    delegate :cache, :default_errors, :error_logger, to: :@config
+    attr_reader :config, :key_base
 
     def initialize config, key_base, options = {}
       @config = config
@@ -30,6 +30,10 @@ module Cachext
       @options.fetch :expires_in, @config.default_expires_in
     end
 
+    def heartbeat_expires
+      @options.fetch :heartbeat_expires, config.heartbeat_expires
+    end
+
     private
 
     def missing_records ids
@@ -39,9 +43,10 @@ module Cachext
     class FindByIds
       attr_reader :multi, :ids
 
-      delegate :cache, to: :multi
+      delegate :config, :heartbeat_expires, to: :multi
+      delegate :cache, :lock_manager, :max_lock_wait, to: :config
 
-      def initialize(multi, ids, lookup)
+      def initialize multi, ids, lookup
         @multi = multi
         @ids = ids
         @lookup = lookup
@@ -64,12 +69,44 @@ module Cachext
 
       def direct
         @direct ||= if uncached_or_stale_ids.length > 0
-          records = uncached_where uncached_or_stale_ids
-          write_cache records
-          records
+          with_lock uncached_or_stale_ids do
+            records = uncached_where uncached_or_stale_ids
+            write_cache records
+            records
+          end
         else
           {}
         end
+      rescue Features::Lock::TimeoutWaitingForLock => e
+        config.error_logger.call e if config.log_errors?
+        {}
+      end
+
+      def with_lock ids, &block
+        @lock_info = obtain_lock ids
+        block.call
+      ensure
+        lock_manager.unlock @lock_info if @lock_info
+      end
+
+      def obtain_lock ids
+        lock_key = lock_key_from_ids ids
+
+        start_time = Time.now
+
+        until lock_info = lock_manager.lock(lock_key, (heartbeat_expires * 1000).ceil)
+          sleep rand
+          if Time.now - start_time > max_lock_wait
+            raise Features::Lock::TimeoutWaitingForLock
+          end
+        end
+
+        lock_info
+      end
+
+      def lock_key_from_ids(ids)
+        key = Key.new multi.key_base + ids
+        key.digest
       end
 
       def write_cache records
@@ -95,20 +132,41 @@ module Cachext
       end
 
       def uncached_where ids
-        records = @lookup.call ids
+        with_heartbeat_extender lock_key_from_ids(ids) do
+          records = @lookup.call ids
 
-        if records.is_a?(Array)
-          records = records.each_with_object({}) do |record, acc|
-            acc[record.id] = record
+          if records.is_a?(Array)
+            records = records.each_with_object({}) do |record, acc|
+              acc[record.id] = record
+            end
           end
-        end
 
-        delete_backups ids - records.keys
-        records
-      rescue *multi.default_errors => e
-        multi.error_logger.error e
+          delete_backups ids - records.keys
+          records
+        end
+      rescue *config.default_errors => e
+        config.error_logger.call e if config.log_errors?
         {}
       end
+
+      def with_heartbeat_extender lock_key, &block
+        done = false
+        heartbeat_frequency = heartbeat_expires / 2
+
+        Thread.new do
+          loop do
+            break if done
+            sleep heartbeat_frequency
+            break if done
+            lock_manager.lock lock_key, (heartbeat_expires * 1000).ceil, extend: @lock_info
+          end
+        end
+
+        block.call
+      ensure
+        lock_manager.unlock @lock_info
+        done = true
+      end
     end
   end
 end

data/lib/cachext/options.rb

@@ -8,12 +8,14 @@ module Cachext
                 :not_found_error,
                 :heartbeat_expires
 
-    def initialize config, expires_in: config.default_expires_in,
+    def initialize config,
+                   expires_in: config.default_expires_in,
                    default: nil,
                    errors: config.default_errors,
                    reraise_errors: true,
                    not_found_error: config.not_found_errors,
                    heartbeat_expires: config.heartbeat_expires
+
       @expires_in = expires_in
       @default = default
       @errors = errors

data/lib/cachext/version.rb

@@ -1,3 +1,3 @@
 module Cachext
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cachext
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Donald Plummer