readthis 1.1.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c15a08e16c0c3499ba92207c32a0fb3cd07d6bea
-  data.tar.gz: 77b6b856ee036051b59a83c7a2013af49ef4c898
+  metadata.gz: d99b745b536b4761198212736eba995173cf7dd0
+  data.tar.gz: fb66dd2f67cc90114ad5037ea10b684722d6d468
 SHA512:
-  metadata.gz: e1c2bd1bcadb0b1d4636de110c1202adf9f4c197bc189ef5282d86f4765612d5383ec9792d435b0629012732151e5a7468a965cc7d99a8b14e9e95100d6312af
-  data.tar.gz: 8ab80c80422fa2ad11d70e03ad6697c6a5d5d78fc76460b27cf1a332b023b9b0419c40020d291cc8db01638844dfe33a693c12a59e1d28474b9f858dc06998cf
+  metadata.gz: 992a39d5b3c6fde1796dbd8ac8dc8c03aa44cd79152a15e6b1ca553327d4dec95f754ddb68a2275aa636d75d13658e43b712ebd95ae4b49ae21f6a164ad66b87
+  data.tar.gz: e5521f55739341901c7bbe6d9743127686643ca44cb82bf338f046a81fd16a522f364ee757e5f548f3ed9c647b495904c0faa1144470e47f4610f510cebc23e1

data/README.md

@@ -2,12 +2,14 @@
 [![Build Status](https://travis-ci.org/sorentwo/readthis.svg?branch=master)](https://travis-ci.org/sorentwo/readthis)
 [![Code Climate](https://codeclimate.com/github/sorentwo/readthis/badges/gpa.svg)](https://codeclimate.com/github/sorentwo/readthis)
 [![Coverage Status](https://coveralls.io/repos/sorentwo/readthis/badge.svg?branch=master&service=github)](https://coveralls.io/github/sorentwo/readthis?branch=master)
+[![Inline Docs](http://inch-ci.org/github/sorentwo/readthis.svg?branch=master)](http://inch-ci.org/github/sorentwo/readthis)
 
 # Readthis
 
-Readthis is a drop in replacement for any ActiveSupport compliant cache. It
-emphasizes performance and simplicity and takes some cues from Dalli the popular
-Memcache client.
+Readthis is a Redis backed cache client for Ruby. It is a drop in replacement
+for any `ActiveSupport` compliant cache and can also be used for [session
+storage](#session-storage).  Above all Readthis emphasizes performance,
+simplicity, and explicitness.
 
 For new projects there isn't any reason to stick with Memcached. Redis is as
 fast, if not faster in many scenarios, and is far more likely to be used
@@ -65,24 +67,40 @@ instances have numerous benefits like: more predictable performance, avoiding
 expires in favor of LRU, and tuning the persistence mechanism. See [Optimizing
 Redis Usage for Caching][optimizing-usage] for more details.
 
-[optimizing-usage]: http://sorentwo.com/2015/07/27/optimizing-redis-usage-for-caching.html
-
-At the very least you'll want to use a specific database for caching. In the
+At the very least, you'll want to use a specific database for caching. In the
 event the database needs to be purged you can do so with a single `clear`
 command, rather than finding all keys in a namespace and deleting them.
 Appending a number between 0 and 15 will specify the redis database, which
-defaults to 0. For example, using database 2:
+defaults to `0`. For example, using database `2`:
 
 ```bash
 REDIS_URL=redis://localhost:6379/2
 ```
 
+[optimizing-usage]: http://sorentwo.com/2015/07/27/optimizing-redis-usage-for-caching.html
+
 ### Expiration
 
 Be sure to use an integer value when setting expiration time. The default
 representation of `ActiveSupport::Duration` values won't work when setting
 expiration time, which will cause all keys to have `-1` as the TTL. Expiration
-values are always cast as an integer on write.
+values are always cast as an integer on write. For example:
+
+```ruby
+Readthis::Cache.new(expires_in: 1.week) # don't do this
+Readthis::Cache.new(expires_in: 1.week.to_i) # do this
+```
+
+By using the `refresh` option the TTL for keys can be refreshed automatically
+every time the key is read. This is helpful for ensuring commonly hit keys are
+kept cached, effectively making the cache a hybrid LRU.
+
+```ruby
+Readthis::Cache.new(refresh: true)
+```
+
+Be aware that `refresh` adds a slight overhead to all read operations, as they
+are now all write operations as well.
 
 ### Compression
 
@@ -132,23 +150,68 @@ Readthis.serializers.freeze!
 Readthis::Cache.new(marshal: Oj)
 ```
 
-Be aware that the order in which you add serializers matters. Serializers are
+Be aware that the *order in which you add serializers matters*. Serializers are
 sticky and a flag is stored with each cached value. If you subsequently go to
 deserialize values and haven't configured the same serializers in the same order
 your application will raise errors.
 
+## Fault Tolerance
+
+In some situations it is desirable to keep serving requests from disk or the
+database if Redis crashes. This can be achieved with connection fault tolerance
+by enabling it at the top level:
+
+```ruby
+Readthis.fault_tolerant = true
+```
+
+The default value is `false`, because while it may work for `fetch` operations,
+it isn't compatible with other state-based commands like `increment`.
+
+## Running Arbitrary Redis Commands
+
+Readthis provides access to the underlying Redis connection pool, allowing you
+to run arbitrary commands directly through the cache instance. For example, if
+you wanted to expire a key manually using an instance of `Rails.cache`:
+
+```ruby
+Rails.cache.pool.with { |client| client.expire('foo-key', 60) }
+```
+
 ## Differences From ActiveSupport::Cache
 
 Readthis supports all of standard cache methods except for the following:
 
 * `cleanup` - Redis does this with TTL or LRU already.
-* `delete_matched` - You really don't want to perform key matching operations in
-  Redis. They are linear time and only support basic globbing.
+* `mute` and `silence!` - You must subscribe to the events `/cache*.active_support/`
+  with `ActiveSupport::Notifications` to [log cache calls manually][notifications].
+
+[notifications]: https://github.com/sorentwo/readthis/issues/22#issuecomment-142595938
 
 Like other `ActiveSupport::Cache` implementations it is possible to cache `nil`
 as a value. However, the fetch methods treat `nil` values as a cache miss and
 re-generate/re-cache the value. Caching `nil` isn't recommended.
 
+## Session Storage
+
+By using [ActionDispatch::Session::CacheStore][cache-store] it's possible to
+reuse `:readthis_store` or specify a new Readthis cache store for storing
+sessions.
+
+```ruby
+Rails.application.config.session_store :cache_store
+```
+
+To specify a separate Readthis instance you can use the `:cache` option:
+
+```ruby
+Rails.application.config.session_store :cache_store,
+  cache: Readthis::Cache.new,
+  expire_after: 2.weeks.to_i
+```
+
+[cache-store]: http://api.rubyonrails.org/classes/ActionDispatch/Session/CacheStore.html
+
 ## Contributing
 
 1. Fork it

data/lib/active_support/cache/readthis_store.rb

@@ -1,6 +1,9 @@
 require 'readthis'
 
 module ActiveSupport
+  # Provided for compatibility with ActiveSupport's cache lookup behavior. When
+  # the ActiveSupport `cache_store` is set to `:readthis_store` it will resolve
+  # to `Readthis::Cache`.
   module Cache
     ReadthisStore ||= Readthis::Cache # rubocop:disable Style/ConstantName
   end

data/lib/readthis.rb

@@ -4,16 +4,39 @@ require 'readthis/serializers'
 require 'readthis/version'
 
 module Readthis
-  extend self
-
   # The current, global, instance of serializers that is used by all cache
   # instances.
   #
-  # @returns [Readthis::Serializers] An cached Serializers instance
+  # @return [Readthis::Serializers] An cached Serializers instance
   #
   # @see readthis/serializers
   #
   def serializers
     @serializers ||= Readthis::Serializers.new
   end
+
+  # Indicates whether connection error tolerance is enabled. With tolerance
+  # enabled every operation will return a `nil` value.
+  #
+  # @return [Boolean] True for enabled, false for disabled
+  #
+  def fault_tolerant?
+    @fault_tolerant
+  end
+
+  # Toggle fault tolerance for connection errors.
+  #
+  # @param [Boolean] value The new value for fault tolerance
+  #
+  def fault_tolerant=(value)
+    @fault_tolerant = value
+  end
+
+  # @private
+  def reset!
+    @fault_tolerant = nil
+    @serializers = nil
+  end
+
+  module_function :serializers, :fault_tolerant?, :fault_tolerant=, :reset!
 end

data/lib/readthis/cache.rb

@@ -1,12 +1,13 @@
 require 'readthis/entity'
 require 'readthis/expanders'
 require 'readthis/passthrough'
+require 'readthis/scripts'
 require 'redis'
 require 'connection_pool'
 
 module Readthis
   class Cache
-    attr_reader :entity, :notifications, :options, :pool
+    attr_reader :entity, :notifications, :options, :pool, :scripts
 
     # Provide a class level lookup of the proper notifications module.
     # Instrumention is expected to occur within applications that have
@@ -18,17 +19,19 @@ module Readthis
 
     # Creates a new Readthis::Cache object with the given options.
     #
-    # @option [Hash]    :redis Options that will be passed to the underlying redis connection
-    # @option [Boolean] :compress (false) Enable or disable automatic compression
-    # @option [Number]  :compression_threshold (8k) The size a string must be for compression
-    # @option [Number]  :expires_in The number of seconds until an entry expires
-    # @option [Module]  :marshal (Marshal) Any module that responds to `dump` and `load`
-    # @option [String]  :namespace Prefix used to namespace entries
-    # @option [Number]  :pool_size (5) The number of threads in the pool
-    # @option [Number]  :pool_timeout (5) How long before a thread times out
+    # @option options [Hash]    :redis Options that will be passed to the redis connection
+    # @option options [Boolean] :compress (false) Enable or disable automatic compression
+    # @option options [Number]  :compression_threshold (8k) Minimum string size for compression
+    # @option options [Number]  :expires_in The number of seconds until an entry expires
+    # @option options [Boolean] :refresh (false) Automatically refresh key expiration
+    # @option options [Module]  :marshal (Marshal) Module that responds to `dump` and `load`
+    # @option options [String]  :namespace Prefix used to namespace entries
+    # @option options [Number]  :pool_size (5) The number of threads in the pool
+    # @option options [Number]  :pool_timeout (5) How long before a thread times out
     #
     # @example Create a new cache instance
-    #   Readthis::Cache.new(namespace: 'cache', redis: { url: 'redis://localhost:6379/0' })
+    #   Readthis::Cache.new(namespace: 'cache',
+    #                       redis: { url: 'redis://localhost:6379/0' })
     #
     # @example Create a compressed cache instance
     #   Readthis::Cache.new(compress: true, compression_threshold: 2048)
@@ -45,14 +48,16 @@ module Readthis
       @pool = ConnectionPool.new(pool_options(options)) do
         Redis.new(options.fetch(:redis, {}))
       end
+
+      @scripts = Readthis::Scripts.new
     end
 
     # Fetches data from the cache, using the given key. If there is data in
     # the cache with the given key, then that data is returned. Otherwise, nil
     # is returned.
     #
-    # @param [String] Key for lookup
-    # @param [Hash] Optional overrides
+    # @param [String] key Key for lookup
+    # @param [Hash] options Optional overrides
     #
     # @example
     #
@@ -60,18 +65,22 @@ module Readthis
     #   cache.read('matched') # => 'some value'
     #
     def read(key, options = {})
+      options = merged_options(options)
+
       invoke(:read, key) do |store|
-        value = store.get(namespaced_key(key, merged_options(options)))
+        key = namespaced_key(key, options)
+
+        refresh_entity(key, store, options)
 
-        entity.load(value)
+        entity.load(store.get(key))
       end
     end
 
     # Writes data to the cache using the given key. Will overwrite whatever
     # value is already stored at that key.
     #
-    # @param [String] Key for lookup
-    # @param [Hash] Optional overrides
+    # @param [String] key Key for lookup
+    # @param [Hash] options Optional overrides
     #
     # @example
     #
@@ -90,13 +99,14 @@ module Readthis
     # Delete the value stored at the specified key. Returns `true` if
     # anything was deleted, `false` otherwise.
     #
-    # @params [String] The key for lookup
-    # @params [Hash] Optional overrides
+    # @param [String] key The key for lookup
+    # @param [Hash] options Optional overrides
     #
     # @example
     #
     #   cache.delete('existing-key') # => true
     #   cache.delete('random-key')   # => false
+    #
     def delete(key, options = {})
       namespaced = namespaced_key(key, merged_options(options))
 
@@ -105,6 +115,49 @@ module Readthis
       end
     end
 
+    # Delete all values that match a given pattern. The pattern must be defined
+    # using Redis compliant globs. The following examples are borrowed from the
+    # `KEYS` documentation:
+    #
+    # * `h?llo` matches hello, hallo and hxllo
+    # * `h*llo` matches hllo and heeeello
+    # * `h[ae]llo` matches hello and hallo, but not hillo
+    # * `h[^e]llo` matches hallo, hbllo, ... but not hello
+    # * `h[a-b]llo` matches hallo and hbllo
+    #
+    # Note that `delete_matched` does *not* use the `KEYS` command, making it
+    # safe for use in production.
+    #
+    # @param [String] pattern The glob pattern for matching keys
+    # @option [String] :namespace Prepend a namespace to the pattern
+    # @option [Number] :count Configure the number of keys deleted at once
+    #
+    # @example Delete all 'cat' keys
+    #
+    #   cache.delete_matched('*cats') #=> 47
+    #   cache.delete_matched('*dogs') #=> 0
+    #
+    def delete_matched(pattern, options = {})
+      namespaced = namespaced_key(pattern, merged_options(options))
+
+      invoke(:delete, pattern) do |store|
+        cursor  = nil
+        count   = options.fetch(:count, 1000)
+        deleted = 0
+
+        until cursor == '0'.freeze
+          cursor, matched = store.scan(cursor || 0, match: namespaced, count: count)
+
+          if matched.any?
+            store.del(*matched)
+            deleted += matched.length
+          end
+        end
+
+        deleted
+      end
+    end
+
     # Fetches data from the cache, using the given key. If there is data in the
     # cache with the given key, then that data is returned.
     #
@@ -114,10 +167,11 @@ module Readthis
     # the block will be written to the cache under the given cache key, and
     # that return value will be returned.
     #
-    # @param [String] Key for lookup
-    # @param [Block] Optional block for generating the value when missing
+    # @param [String] key Key for lookup
     # @param options [Hash] Optional overrides
     # @option options [Boolean] :force Force a cache miss
+    # @yield [String] Gives a missing key to the block, which is used to
+    #   generate the missing value
     #
     # @example Typical
     #
@@ -130,7 +184,8 @@ module Readthis
     #   cache.fetch('city') do
     #     'Duckburgh'
     #   end
-    #   cache.fetch('city')   # => "Duckburgh"
+    #
+    #   cache.fetch('city') # => "Duckburgh"
     #
     # @example Cache Miss
     #
@@ -154,9 +209,9 @@ module Readthis
     # If the key doesn't exist it will be initialized at 0. If the key exists
     # but it isn't a Fixnum it will be initialized at 0.
     #
-    # @param [String] Key for lookup
-    # @param [Fixnum] Value to increment by
-    # @param [Hash] Optional overrides
+    # @param [String] key Key for lookup
+    # @param [Fixnum] amount Value to increment by
+    # @param [Hash] options Optional overrides
     #
     # @example
     #
@@ -175,9 +230,9 @@ module Readthis
     # If the key doesn't exist it will be initialized at 0. If the key exists
     # but it isn't a Fixnum it will be initialized at 0.
     #
-    # @param [String] Key for lookup
-    # @param [Fixnum] Value to decrement by
-    # @param [Hash] Optional overrides
+    # @param [String] key Key for lookup
+    # @param [Fixnum] amount Value to decrement by
+    # @param [Hash] options Optional overrides
     #
     # @example
     #
@@ -212,7 +267,9 @@ module Readthis
       return {} if keys.empty?
 
       invoke(:read_multi, keys) do |store|
-        values = store.mget(mapping).map { |value| entity.load(value) }
+        values = store.mget(*mapping).map { |value| entity.load(value) }
+
+        refresh_entity(mapping, store, options)
 
         keys.zip(values).to_h
       end
@@ -224,8 +281,8 @@ module Readthis
     #
     # This is a non-standard, but useful, cache method.
     #
-    # @param [Hash] Key value hash to write
-    # @param [Hash] Optional overrides
+    # @param [Hash] hash Key value hash to write
+    # @param [Hash] options Optional overrides
     #
     # @example
     #
@@ -282,8 +339,8 @@ module Readthis
 
     # Returns `true` if the cache contains an entry for the given key.
     #
-    # @param [String] Key for lookup
-    # @param [Hash] Optional overrides
+    # @param [String] key Key for lookup
+    # @param [Hash] options Optional overrides
     #
     # @example
     #
@@ -299,23 +356,32 @@ module Readthis
     # Clear the entire cache. This flushes the current database, no
     # globbing is applied.
     #
-    # @param [Hash] Options, only present for compatibility.
+    # @param [Hash] _options Options, only present for compatibility
     #
     # @example
     #
     #   cache.clear #=> 'OK'
+    #
     def clear(_options = nil)
       invoke(:clear, '*', &:flushdb)
     end
 
     protected
 
+    def refresh_entity(keys, store, options)
+      return unless options[:refresh] && options[:expires_in]
+
+      expiration = coerce_expiration(options[:expires_in])
+
+      scripts.run('mexpire', store, keys, expiration)
+    end
+
     def write_entity(key, value, store, options)
       namespaced = namespaced_key(key, options)
       dumped = entity.dump(value, options)
 
-      if expiration = options[:expires_in]
-        store.setex(namespaced, expiration.to_i, dumped)
+      if (expiration = options[:expires_in])
+        store.setex(namespaced, coerce_expiration(expiration), dumped)
       else
         store.set(namespaced, dumped)
       end
@@ -324,12 +390,15 @@ module Readthis
     private
 
     def alter(key, amount, options)
-      number = read(key, options)
-      delta  = number.to_i + amount
+      delta = read(key, options).to_i + amount
       write(key, delta, options)
       delta
     end
 
+    def coerce_expiration(expires_in)
+      Float(expires_in).ceil
+    end
+
     def instrument(name, key)
       if self.class.notifications
         name    = "cache_#{name}.active_support"
@@ -345,6 +414,8 @@ module Readthis
       instrument(operation, key) do
         pool.with(&block)
       end
+    rescue Redis::BaseError => error
+      raise error unless Readthis.fault_tolerant?
     end
 
     def extract_options!(array)

data/lib/readthis/entity.rb

@@ -1,13 +1,19 @@
 require 'zlib'
 
 module Readthis
+  # An instance of the Entity class is used to handle `load` and `dump`
+  # operations on cached values.
   class Entity
+    # Unless they are overridden, these are the options used to load and unload
+    # every value.
     DEFAULT_OPTIONS = {
       compress:  false,
       marshal:   Marshal,
       threshold: 8 * 1024
     }.freeze
 
+    # A hexidecimal compression flag. When it is present within the magic bit
+    # of an entity that entity is considered compressed.
     COMPRESSED_FLAG = 0x8
 
     # Creates a Readthis::Entity with default options. Each option can be
@@ -17,9 +23,12 @@ module Readthis
     # automatically be used again when loading, regardless of how current
     # options are set.
     #
-    # @option [Boolean] :compress (false) Enable or disable automatic compression
-    # @option [Module]  :marshal (Marshal) Any module that responds to `dump` and `load`
-    # @option [Number]  :threshold (8k) The size a string must be for compression
+    # @option [Boolean] :compress (false) Enable or disable automatic
+    #   compression
+    # @option [Module]  :marshal (Marshal) Any module that responds to `dump`
+    #   and `load`
+    # @option [Number]  :threshold (8k) The size a string must be for
+    #   compression
     #
     def initialize(options = {})
       @options = DEFAULT_OPTIONS.merge(options)
@@ -28,10 +37,13 @@ module Readthis
     # Output a value prepared for cache storage. Passed options will override
     # whatever has been specified for the instance.
     #
-    # @param  [String] String to dump
-    # @option [Boolean] :compress Enable or disable automatic compression
-    # @option [Module]  :marshal Any module that responds to `dump` and `load`
-    # @option [Number]  :threshold The size a string must be for compression
+    # @param [String] value String to dump
+    # @option options [Boolean] :compress Enable or disable automatic
+    #   compression
+    # @option options [Module] :marshal Any module that responds to `dump` and
+    #   `load`
+    # @option options [Number] :threshold The size a string must be for
+    #   compression
     # @return [String] The prepared, possibly compressed, string
     #
     # @example Dumping a value using defaults
@@ -40,7 +52,7 @@ module Readthis
     #
     # @example Dumping a value with overrides
     #
-    #   entity.dump(string, compress: false)
+    #   entity.dump(string, compress: false, marshal: JSON)
     #
     def dump(value, options = {})
       compress  = with_fallback(options, :compress)
@@ -54,7 +66,7 @@ module Readthis
 
     # Parse a dumped value using the embedded options.
     #
-    # @param  [String] Option embedded string to load
+    # @param [String] string Option embedded string to load
     # @return [String] The original dumped string, restored
     #
     # @example
@@ -77,9 +89,9 @@ module Readthis
     # Where there are four unused bits, 1 compression bit, and 3 bits for the
     # serializer. This allows up to 8 different serializers for marshaling.
     #
-    # @param  [String] String to prefix with flags
-    # @param  [Module] The marshal module to be used
-    # @param  [Boolean] Flag determining whether the value is compressed
+    # @param  [String] value String to prefix with flags
+    # @param  [Module] marshal The marshal module to be used
+    # @param  [Boolean] compress Flag determining whether the value is compressed
     # @return [String] The original string with a single byte prefixed
     #
     # @example Compose an option embedded string
@@ -96,7 +108,7 @@ module Readthis
 
     # Decompose an option embedded string into marshal, compression and value.
     #
-    # @param  [String] Option embedded string to
+    # @param  [String] string Option embedded string to
     # @return [Array<Module, Boolean, String>] An array comprised of the
     #   marshal, compression flag, and the base string.
     #

data/lib/readthis/errors.rb

@@ -1,7 +1,22 @@
 module Readthis
+  # This is the base error that all other specific errors inherit from,
+  # making it possible to rescue the `ReadthisError` superclass.
+  #
+  # This isn't raised by itself.
   ReadthisError = Class.new(StandardError)
 
+  # Raised when attempting to modify the serializers after they have been
+  # frozen.
   SerializersFrozenError = Class.new(ReadthisError)
+
+  # Raised when attempting to add a new serializer after the limit of 7 is
+  # reached.
   SerializersLimitError  = Class.new(ReadthisError)
+
+  # Raised when an unknown script is called.
+  UnknownCommandError = Class.new(ReadthisError)
+
+  # Raised when a serializer was specified, but hasn't been configured for
+  # usage.
   UnknownSerializerError = Class.new(ReadthisError)
 end

data/lib/readthis/expanders.rb

@@ -7,7 +7,10 @@ module Readthis
       when key.is_a?(Array)
         key.flat_map { |elem| expand_key(elem) }.join('/')
       when key.is_a?(Hash)
-        key.sort_by { |hkey, _| hkey.to_s }.map { |hkey, val| "#{hkey}=#{val}" }.join('/')
+        key
+          .sort_by { |hkey, _| hkey.to_s }
+          .map { |hkey, val| "#{hkey}=#{val}" }
+          .join('/')
       when key.respond_to?(:to_param)
         key.to_param
       else

data/lib/readthis/passthrough.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Readthis
   module Passthrough
     def self.dump(value)
-      value
+      value.dup
     end
 
     def self.load(value)

data/lib/readthis/scripts.rb

@@ -0,0 +1,56 @@
+module Readthis
+  # The `Scripts` class is used to conveniently execute lua scripts. The first
+  # time a command is run it is stored on the server and subsequently referred
+  # to by its SHA. Each instance tracks SHAs separately, they are not global.
+  class Scripts
+    attr_reader :loaded
+
+    # Creates a new Readthis::Scripts instance.
+    def initialize
+      @loaded = {}
+    end
+
+    # Run a named lua script with the provided keys and arguments.
+    #
+    # @param [String] command The script to run, without a `.lua` extension
+    # @param [#Store] store A Redis client for storing and evaluating the script
+    # @param [Array] keys One or more keys to pass to the command
+    # @param [Array] args One or more args to pass to the command
+    #
+    # @return [Any] The Redis converted value returned on the script
+    #
+    # @example
+    #
+    #   scripts.run('mexpire', store, %w[a b c], 1) # => 'OK'
+    #
+    def run(command, store, keys, args = [])
+      store.evalsha(
+        sha(command, store),
+        Array(keys),
+        Array(args)
+      )
+    end
+
+    private
+
+    def sha(command, store)
+      loaded[command] ||= load_script!(command, store)
+    end
+
+    def load_script!(command, store)
+      path = abs_path("#{command}.lua")
+
+      File.open(path) do |file|
+        loaded[command] = store.script(:load, file.read)
+      end
+    rescue Errno::ENOENT
+      raise Readthis::UnknownCommandError, "unknown command '#{command}'"
+    end
+
+    def abs_path(filename)
+      dir = File.expand_path(File.dirname(__FILE__))
+
+      File.join(dir, '../../script', filename)
+    end
+  end
+end

data/lib/readthis/serializers.rb

@@ -4,12 +4,16 @@ require 'readthis/passthrough'
 
 module Readthis
   class Serializers
+    # Defines the default set of three serializers: Marshal, Passthrough, and
+    # JSON. With a hard limit of 7 that leaves 4 additional slots.
     BASE_SERIALIZERS = {
       Marshal     => 0x1,
       Passthrough => 0x2,
       JSON        => 0x3
     }.freeze
 
+    # The hard serializer limit, based on the number of possible values within
+    # a single 3bit integer.
     SERIALIZER_LIMIT = 7
 
     attr_reader :serializers, :inverted
@@ -25,7 +29,7 @@ module Readthis
     # any single application be configured for any single application. This
     # limit is based on the number of bytes available in the option flag.
     #
-    # @param [Module] Any object that responds to `dump` and `load`
+    # @param [Module] serializer Any object that responds to `dump` and `load`
     # @return [self] Returns itself for possible chaining
     #
     # @example
@@ -36,9 +40,9 @@ module Readthis
     def <<(serializer)
       case
       when serializers.frozen?
-        fail SerializersFrozenError
-      when serializers.length > SERIALIZER_LIMIT
-        fail SerializersLimitError
+        raise SerializersFrozenError
+      when serializers.length >= SERIALIZER_LIMIT
+        raise SerializersLimitError
       else
         @serializers[serializer] = flags.max.succ
         @inverted = @serializers.invert
@@ -63,7 +67,7 @@ module Readthis
 
     # Find a flag for a serializer object.
     #
-    # @param [Object] Look up a flag by object
+    # @param [Object] serializer Look up a flag by object
     # @return [Number] Corresponding flag for the serializer object
     # @raise [UnknownSerializerError] Indicates that a serializer was
     #   specified, but hasn't been configured for usage.
@@ -76,7 +80,7 @@ module Readthis
       flag = serializers[serializer]
 
       unless flag
-        fail UnknownSerializerError, "'#{serializer}' hasn't been configured"
+        raise UnknownSerializerError, "'#{serializer}' hasn't been configured"
       end
 
       flag
@@ -84,7 +88,7 @@ module Readthis
 
     # Find a serializer object by flag value.
     #
-    # @param [Number] Flag to look up the serializer object by
+    # @param [Number] flag Integer to look up the serializer object by
     # @return [Module] The serializer object
     #
     # @example
@@ -92,7 +96,7 @@ module Readthis
     #   serializers.rassoc(1) #=> Marshal
     #
     def rassoc(flag)
-      inverted[flag & inverted.length]
+      inverted[flag & SERIALIZER_LIMIT]
     end
 
     # @private

data/lib/readthis/version.rb

@@ -1,3 +1,3 @@
 module Readthis
-  VERSION = '1.1.0'
+  VERSION = '1.5.0'.freeze
 end

data/script/mexpire.lua

@@ -0,0 +1,7 @@
+local expire = ARGV[1]
+
+for index = 1, #KEYS do
+  redis.call('EXPIRE', KEYS[index], expire)
+end
+
+return true

data/spec/matchers/redis_matchers.rb

@@ -0,0 +1,13 @@
+module RedisMatchers
+  extend RSpec::Matchers::DSL
+
+  matcher :have_ttl do |expected|
+    match do |cache|
+      cache.pool.with do |client|
+        expected.all? do |(key, value)|
+          client.ttl(key) == value
+        end
+      end
+    end
+  end
+end

data/spec/readthis/cache_spec.rb

@@ -1,6 +1,8 @@
-require 'readthis'
+require 'matchers/redis_matchers'
 
 RSpec.describe Readthis::Cache do
+  include RedisMatchers
+
   let(:cache) { Readthis::Cache.new }
 
   after do
@@ -48,16 +50,23 @@ RSpec.describe Readthis::Cache do
     end
 
     it 'uses a custom expiration' do
-      cache = Readthis::Cache.new(namespace: 'cache', expires_in: 86400)
+      cache = Readthis::Cache.new(expires_in: 10)
 
       cache.write('some-key', 'some-value')
       cache.write('other-key', 'other-value', expires_in: 1)
 
       expect(cache.read('some-key')).not_to be_nil
       expect(cache.read('other-key')).not_to be_nil
-      sleep 1.01
-      expect(cache.read('some-key')).not_to be_nil
-      expect(cache.read('other-key')).to be_nil
+
+      expect(cache).to have_ttl('some-key' => 10, 'other-key' => 1)
+    end
+
+    it 'rounds floats to a valid expiration value' do
+      cache = Readthis::Cache.new
+
+      cache.write('some-key', 'some-value', expires_in: 0.1)
+
+      expect(cache).to have_ttl('some-key' => 1)
     end
 
     it 'expands non-string keys' do
@@ -73,6 +82,18 @@ RSpec.describe Readthis::Cache do
     it 'gracefully handles nil options' do
       expect { cache.read('whatever', nil) }.not_to raise_error
     end
+
+    it 'can refresh the expiration of an entity' do
+      cache = Readthis::Cache.new(refresh: true)
+
+      cache.write('some-key', 'some-value', expires_in: 1)
+
+      cache.read('some-key', expires_in: 2)
+      expect(cache).to have_ttl('some-key' => 2)
+
+      cache.read('some-key', expires_in: 0.1)
+      expect(cache).to have_ttl('some-key' => 1)
+    end
   end
 
   describe 'serializers' do
@@ -151,6 +172,12 @@ RSpec.describe Readthis::Cache do
       expect(cache.read('missing-key')).to eq(value)
     end
 
+    it 'returns computed value when using passthrough marshalling' do
+      cache = Readthis::Cache.new(marshal: Readthis::Passthrough)
+      result = cache.fetch('missing-key') { 'value for you' }
+      expect(result).to eq('value for you')
+    end
+
     it 'does not set for a missing key without a block' do
       expect(cache.fetch('missing-key')).to be_nil
     end
@@ -166,6 +193,16 @@ RSpec.describe Readthis::Cache do
       cache.write('great-key', 'great')
       expect(cache.fetch('great-key', nil)).to eq('great')
     end
+
+    it 'serves computed content when the cache is down and tolerance is enabled' do
+      Readthis.fault_tolerant = true
+
+      allow(cache.pool).to receive(:with).and_raise(Redis::CannotConnectError)
+
+      computed = cache.fetch('error-key') { 'computed' }
+
+      expect(computed).to eq('computed')
+    end
   end
 
   describe '#read_multi' do
@@ -194,6 +231,17 @@ RSpec.describe Readthis::Cache do
     it 'returns {} with no keys' do
       expect(cache.read_multi(namespace: 'cache')).to eq({})
     end
+
+    it 'refreshes each key that is read' do
+      cache = Readthis::Cache.new(refresh: true)
+
+      cache.write('a', 1, expires_in: 1)
+      cache.write('b', 2, expires_in: 1)
+
+      cache.read_multi('a', 'b', expires_in: 2)
+
+      expect(cache).to have_ttl('a' => 2, 'b' => 2)
+    end
   end
 
   describe '#write_multi' do
@@ -214,8 +262,8 @@ RSpec.describe Readthis::Cache do
 
       expect(cache.read('a')).to be_nil
       expect(cache.read('a', namespace: 'multi')).to eq(1)
-      sleep 1.01
-      expect(cache.read('a', namespace: 'multi')).to be_nil
+
+      expect(cache).to have_ttl('multi:a' => 1)
     end
   end
 
@@ -279,6 +327,32 @@ RSpec.describe Readthis::Cache do
     end
   end
 
+  describe '#delete_matched' do
+    it 'deletes all matching keys' do
+      cache.write('tomcat', 'cat')
+      cache.write('wildcat', 'cat')
+      cache.write('bobcat', 'cat')
+      cache.write('cougar', 'cat')
+
+      expect(cache.delete_matched('tomcat')).to eq(1)
+      expect(cache.read('tomcat')).to be_nil
+      expect(cache.read('bobcat')).not_to be_nil
+      expect(cache.read('wildcat')).not_to be_nil
+
+      expect(cache.delete_matched('*cat', count: 1)).to eq(2)
+      expect(cache.read('wildcat')).to be_nil
+      expect(cache.read('bobcat')).to be_nil
+
+      expect(cache.delete_matched('*cat')).to eq(0)
+    end
+
+    it 'respects namespacing when matching keys' do
+      cache.write('tomcat', 'cat', namespace: 'feral')
+
+      expect(cache.delete_matched('tom*', namespace: 'feral')).to eq(1)
+    end
+  end
+
   describe '#increment' do
     it 'atomically increases the stored integer' do
       cache.write('counter', 10)
@@ -318,10 +392,10 @@ RSpec.describe Readthis::Cache do
       cache.read('a')
 
       expect(events.length).to eq(2)
-      expect(events.map(&:name)).to eq(%w[
+      expect(events.map(&:name)).to eq %w[
         cache_write.active_support
         cache_read.active_support
-      ])
+      ]
     end
   end
 end

data/spec/readthis/entity_spec.rb

@@ -1,4 +1,3 @@
-require 'readthis'
 require 'json'
 
 RSpec.describe Readthis::Entity do

data/spec/readthis/expanders_spec.rb

@@ -1,5 +1,3 @@
-require 'readthis/expanders'
-
 RSpec.describe Readthis::Expanders do
   def expand(key, namespace = nil)
     Readthis::Expanders.namespace_key(key, namespace)

data/spec/readthis/passthrough_spec.rb

@@ -1,17 +1,16 @@
-require 'readthis/passthrough'
-
 RSpec.describe Readthis::Passthrough do
+  let(:value) { 'skywalker' }
+
   describe '.load' do
     it 'passes through the provided value' do
-      value = Object.new
       expect(Readthis::Passthrough.load(value)).to eq(value)
     end
   end
 
   describe '.dump' do
     it 'passes through the provided value' do
-      value = Object.new
       expect(Readthis::Passthrough.dump(value)).to eq(value)
+      expect(Readthis::Passthrough.dump(value)).not_to be(value)
     end
   end
 end

data/spec/readthis/scripts_spec.rb

@@ -0,0 +1,31 @@
+RSpec.describe Readthis::Scripts do
+  let(:scripts) { Readthis::Scripts.new }
+
+  describe '#run' do
+    it 'raises an error with an unknown command' do
+      expect do
+        scripts.run('unknown', nil, [])
+      end.to raise_error(Readthis::UnknownCommandError)
+    end
+
+    it 'runs the script command with a single key' do
+      store = Redis.new
+
+      store.set('alpha', 'content')
+      scripts.run('mexpire', store, 'alpha', 1)
+
+      expect(store.ttl('alpha')).to eq(1)
+    end
+
+    it 'runs the script command with multiple keys' do
+      store = Redis.new
+
+      store.set('beta', 'content')
+      store.set('gamma', 'content')
+      scripts.run('mexpire', store, %w[beta gamma], 1)
+
+      expect(store.ttl('beta')).to eq(1)
+      expect(store.ttl('gamma')).to eq(1)
+    end
+  end
+end

data/spec/readthis/serializers_spec.rb

@@ -1,5 +1,3 @@
-require 'readthis/serializers'
-
 RSpec.describe Readthis::Serializers do
   CustomSerializer  = Class.new
   AnotherSerializer = Class.new
@@ -24,9 +22,9 @@ RSpec.describe Readthis::Serializers do
 
     it 'prevents more than seven serializers' do
       serializers = Readthis::Serializers.new
-
+      serializers << Class.new until serializers.flags.length >= 7
       expect do
-        10.times { serializers << Class.new }
+        serializers << Class.new
       end.to raise_error(Readthis::SerializersLimitError)
     end
   end
@@ -48,18 +46,29 @@ RSpec.describe Readthis::Serializers do
   end
 
   describe '#rassoc' do
-    it 'inverts the current set of serializers' do
-      serializers = Readthis::Serializers.new
+    let(:serializers) { Readthis::Serializers.new }
 
+    it 'inverts the current set of serializers' do
       expect(serializers.rassoc(1)).to eq(Marshal)
     end
 
     it 'returns custom serializers' do
-      serializers = Readthis::Serializers.new
       serializers << CustomSerializer
-
       expect(serializers.rassoc(4)).to eq(CustomSerializer)
     end
+
+    it 'inverts default serializers after adding custom one' do
+      serializers << CustomSerializer
+      expect(serializers.rassoc(1)).to eq(Marshal)
+      expect(serializers.rassoc(3)).to eq(JSON)
+    end
+
+    it 'takes into account only first 3 bytes of passed integer' do
+      expect(serializers.rassoc(1)).to eq(Marshal)
+      expect(serializers.rassoc(11)).to eq(JSON)
+      serializers << CustomSerializer
+      expect(serializers.rassoc(12)).to eq(CustomSerializer)
+    end
   end
 
   describe '#freeze!' do

data/spec/readthis_spec.rb

@@ -1,9 +1,19 @@
-require 'readthis'
-
 RSpec.describe Readthis do
   describe '#serializers' do
     it 'lists currently configured serializers' do
       expect(Readthis.serializers.marshals).to include(Marshal, JSON)
     end
   end
+
+  describe '#fault_tolerant?' do
+    it 'defaults to being false' do
+      expect(Readthis).not_to be_fault_tolerant
+    end
+
+    it 'can be enabled' do
+      Readthis.fault_tolerant = true
+
+      expect(Readthis).to be_fault_tolerant
+    end
+  end
 end

data/spec/spec_helper.rb

@@ -1,4 +1,5 @@
 require 'coveralls'
+require 'readthis'
 
 Coveralls.wear!
 
@@ -20,4 +21,8 @@ RSpec.configure do |config|
 
   config.order = :random
   Kernel.srand config.seed
+
+  config.before do
+    Readthis.reset!
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: readthis
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Parker Selbert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-08 00:00:00.000000000 Z
+date: 2016-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -123,12 +123,16 @@ files:
 - lib/readthis/errors.rb
 - lib/readthis/expanders.rb
 - lib/readthis/passthrough.rb
+- lib/readthis/scripts.rb
 - lib/readthis/serializers.rb
 - lib/readthis/version.rb
+- script/mexpire.lua
+- spec/matchers/redis_matchers.rb
 - spec/readthis/cache_spec.rb
 - spec/readthis/entity_spec.rb
 - spec/readthis/expanders_spec.rb
 - spec/readthis/passthrough_spec.rb
+- spec/readthis/scripts_spec.rb
 - spec/readthis/serializers_spec.rb
 - spec/readthis_spec.rb
 - spec/spec_helper.rb
@@ -152,15 +156,18 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Pooled active support compliant caching with redis
 test_files:
+- spec/matchers/redis_matchers.rb
 - spec/readthis/cache_spec.rb
 - spec/readthis/entity_spec.rb
 - spec/readthis/expanders_spec.rb
 - spec/readthis/passthrough_spec.rb
+- spec/readthis/scripts_spec.rb
 - spec/readthis/serializers_spec.rb
 - spec/readthis_spec.rb
 - spec/spec_helper.rb
+has_rdoc: