readthis 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a7b4dfe48dce8fa54170963b720ee202dedb19df
-  data.tar.gz: 0e611efe5dcd71df78491618472a0394ec408a69
+SHA256:
+  metadata.gz: 9ce73086f82fd00b89f037d6aba17fee9ba94b76766f020c65f1305c1faa122d
+  data.tar.gz: f63760bc92f7a0f4023b2e4817192282b5e77e34b61c73e6a5f7d4b60bc3ce02
 SHA512:
-  metadata.gz: 0f436a2f365f761d8be21ee93041f65b990b2f2ea92d8e95486bc127dbe8f4f3a27cad1250237a0cc1a8314e8b6992ab6698e6a8f9455e1d89ab4dab2b5b3148
-  data.tar.gz: 9e18f5b63c9bfc05b1e1e8f110a7957a7d9c6cedb70868e91c810509e42a93985b0fd6d84619c4880e58398d63d5a2e1ed0def088a760849d4dbd1275dd9c4f8
+  metadata.gz: bcd82892c461b1b34f9fa15873cb4948db25974e39acdb34615de49155346f6e858543c06f07207f0c00bfc3b8064d2856c4c05f49edab9c36b5884dc78b4c63
+  data.tar.gz: 51d85402830b660eba320626bd4a4db3928f33c3a3f77fbc2934fe553793b2809bd1074a8abaea9d63183001c75f1e5ee5f5b0d612991da2badc05e703c31be5

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Parker Selbert
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -8,7 +8,7 @@
 
 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,
+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

data/lib/active_support/cache/readthis_store.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'readthis'
 
 module ActiveSupport
@@ -5,6 +7,6 @@ module ActiveSupport
   # the ActiveSupport `cache_store` is set to `:readthis_store` it will resolve
   # to `Readthis::Cache`.
   module Cache
-    ReadthisStore ||= Readthis::Cache # rubocop:disable Style/ConstantName
+    ReadthisStore ||= Readthis::Cache # rubocop:disable Naming/ConstantName
   end
 end

data/lib/readthis.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'readthis/cache'
 require 'readthis/errors'
 require 'readthis/serializers'

data/lib/readthis/cache.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'readthis/entity'
 require 'readthis/expanders'
 require 'readthis/passthrough'
@@ -6,6 +8,9 @@ require 'redis'
 require 'connection_pool'
 
 module Readthis
+  # Readthis is a Redis backed cache client. It is a drop in replacement for
+  # any `ActiveSupport` compliant cache Above all Readthis emphasizes
+  # performance, simplicity, and explicitness.
   class Cache
     attr_reader :entity, :notifications, :options, :pool, :scripts
 
@@ -156,7 +161,7 @@ module Readthis
         count = options.fetch(:count, 1000)
         deleted = 0
 
-        until cursor == '0'.freeze
+        until cursor == '0'
           cursor, matched = store.scan(cursor || 0, match: namespaced, count: count)
 
           if matched.any?
@@ -218,7 +223,18 @@ module Readthis
     # Increment a key in the store.
     #
     # 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.
+    # but it isn't a Fixnum it will be coerced to 0.
+    #
+    # Note that this method does *not* use Redis' native `incr` or `incrby`
+    # commands. Those commands only work with number-like strings, and are
+    # incompatible with the encoded values Readthis writes to the store. The
+    # behavior of `incrby` is preserved as much as possible, but incrementing
+    # is not an atomic action. If multiple clients are incrementing the same
+    # key there will be a "last write wins" race condition, causing incorrect
+    # counts.
+    #
+    # If you absolutely require correct counts it is better to use the Redis
+    # client directly.
     #
     # @param [String] key Key for lookup
     # @param [Fixnum] amount Value to increment by
@@ -226,20 +242,20 @@ module Readthis
     #
     # @example
     #
-    #   cache.increment('counter') # => 0
     #   cache.increment('counter') # => 1
     #   cache.increment('counter', 2) # => 3
     #
     def increment(key, amount = 1, options = {})
-      invoke(:increment, key) do |_store|
-        alter(key, amount, options)
+      invoke(:increment, key) do |store|
+        alter(store, key, amount, options)
       end
     end
 
     # Decrement a key in the store.
     #
     # 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.
+    # but it isn't a Fixnum it will be coerced to 0. Like `increment`, this
+    # does not make use of the native `decr` or `decrby` commands.
     #
     # @param [String] key Key for lookup
     # @param [Fixnum] amount Value to decrement by
@@ -252,8 +268,8 @@ module Readthis
     #   cache.decrement('counter', 2) # => 17
     #
     def decrement(key, amount = 1, options = {})
-      invoke(:decrement, key) do |_store|
-        alter(key, amount * -1, options)
+      invoke(:decrement, key) do |store|
+        alter(store, key, -amount, options)
       end
     end
 
@@ -365,17 +381,27 @@ module Readthis
       end
     end
 
-    # Clear the entire cache. This flushes the current database, no
-    # globbing is applied.
+    # Clear the entire cache by flushing the current database.
     #
-    # @param [Hash] _options Options, only present for compatibility
+    # This flushes everything in the current database, with no globbing
+    # applied. Data in other numbered databases will be preserved.
+    #
+    # @option options [Hash] :async Flush the database asynchronously, only
+    #   supported in Redis 4.0+
     #
     # @example
     #
     #   cache.clear #=> 'OK'
-    #
-    def clear(_options = nil)
-      invoke(:clear, '*', &:flushdb)
+    #   cache.clear(async: true) #=> 'OK'
+    #
+    def clear(options = {})
+      invoke(:clear, '*') do |store|
+        if options[:async]
+          store.flushdb(async: true)
+        else
+          store.flushdb
+        end
+      end
     end
 
     protected
@@ -389,8 +415,8 @@ module Readthis
     end
 
     def write_entity(key, value, store, options)
-      namespaced = encode(namespaced_key(key, options))
-      dumped = encode(entity.dump(value, options))
+      namespaced = namespaced_key(key, options)
+      dumped = entity.dump(value, options)
 
       if (expiration = options[:expires_in])
         store.setex(namespaced, coerce_expiration(expiration), dumped)
@@ -401,20 +427,34 @@ module Readthis
 
     private
 
-    def alter(key, amount, options)
-      delta = read(key, options).to_i + amount
-      write(key, delta, options)
-      delta
-    end
+    def alter(store, key, amount, options)
+      options = merged_options(options)
+      namespaced = namespaced_key(key, options)
 
-    def coerce_expiration(expires_in)
-      Float(expires_in).ceil
+      loaded = entity.load(store.get(namespaced))
+      change = loaded.to_i + amount
+      dumped = entity.dump(change, options)
+      expiration = fallback_expiration(store, namespaced, options)
+
+      if expiration
+        store.setex(namespaced, coerce_expiration(expiration), dumped)
+      else
+        store.set(namespaced, dumped)
+      end
+
+      change
     end
 
-    def encode(string)
-      string = string.frozen? ? string.dup : string
+    def fallback_expiration(store, key, options)
+      options.fetch(:expires_in) do
+        ttl = store.ttl(key)
 
-      string.force_encoding(Encoding::BINARY)
+        ttl > 0 ? ttl : nil
+      end
+    end
+
+    def coerce_expiration(expires_in)
+      Float(expires_in).ceil
     end
 
     def instrument(name, key)

data/lib/readthis/entity.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'zlib'
 
 module Readthis

data/lib/readthis/errors.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Readthis
   # This is the base error that all other specific errors inherit from,
   # making it possible to rescue the `ReadthisError` superclass.

data/lib/readthis/expanders.rb

@@ -1,9 +1,38 @@
 module Readthis
+  # Expander methods are used to transform an object into a string suitable for
+  # use as a cache key.
   module Expanders
+    # Expand an object into a suitable cache key.
+    #
+    # The behavior of `expand_key` is largely modeled on the `expand_cache_key`
+    # method from `ActiveSupport::Cache`, with some subtle additions.
+    #
+    # @param [Object] key An object to stringify. Arrays, hashes, and objects
+    #   that respond to either `cache_key` or `to_param` have direct support.
+    #   All other objects will be coerced to a string, and frozen strings will
+    #   be duplicated.
+    #
+    # @return [String] A cache key string.
+    #
+    # @example String expansion
+    #
+    #   Readthis::Expanders.expand_key('typical-key')
+    #   'typical-key'
+    #
+    # @example Array string expansion
+    #
+    #   Readthis::Expanders.expand_key(['a', 'b', [:c, 'd'], 1])
+    #   'a/b/c/d/1'
+    #
+    # @example Hash expansion
+    #
+    #   Readthis::Expanders.expand_key(c: 1, 'a' => 3, b: 2)
+    #   'a=3/b=2/c=1'
+    #
     def self.expand_key(key)
       case
-      when key.respond_to?(:cache_key)
-        key.cache_key
+      when key.is_a?(String)
+        key.frozen? ? key.dup : key
       when key.is_a?(Array)
         key.flat_map { |elem| expand_key(elem) }.join('/')
       when key.is_a?(Hash)
@@ -11,6 +40,8 @@ module Readthis
           .sort_by { |hkey, _| hkey.to_s }
           .map { |hkey, val| "#{hkey}=#{val}" }
           .join('/')
+      when key.respond_to?(:cache_key)
+        key.cache_key
       when key.respond_to?(:to_param)
         key.to_param
       else
@@ -18,14 +49,32 @@ module Readthis
       end
     end
 
-    def self.namespace_key(key, namespace)
+    # Prepend a namespace to a key after expanding it.
+    #
+    # @param [Object] key An object to stringify.
+    # @param [String] namespace An optional namespace to prepend, if `nil` it
+    #   is ignored.
+    #
+    # @return [String] A binary encoded string combining the namespace and key.
+    #
+    # @example Applying a namespace
+    #
+    #   Knuckles::Expanders.namespace_key('alpha', 'greek')
+    #   'greek:alpha'
+    #
+    # @example Omitting a namespace
+    #
+    #   Knuckles::Expanders.namespace_key('alpha', nil)
+    #   'alpha'
+    #
+    def self.namespace_key(key, namespace = nil)
       expanded = expand_key(key)
 
       if namespace
         "#{namespace}:#{expanded}"
       else
         expanded
-      end
+      end.force_encoding(Encoding::BINARY)
     end
   end
 end

data/lib/readthis/passthrough.rb

@@ -1,11 +1,29 @@
 # frozen_string_literal: true
 
 module Readthis
+  # The `Passthrough` serializer performs no encoding on objects. It should be
+  # used when caching simple string objects when the overhead of marshalling or
+  # other serialization isn't desired.
   module Passthrough
+    # Dump an object to string, without performing any encoding on it.
+    #
+    # @param [Object] value Any object to be dumped as a string. Frozen strings
+    #   will be duplicated.
+    #
+    # @return [String] The converted object.
+    #
     def self.dump(value)
-      value.dup
+      case value
+      when String then value.dup
+      else value.to_s
+      end
     end
 
+    # Load an object without modifying it at all.
+    #
+    # @param [String] value The object to return, expected to be a string.
+    #
+    # @return [String] The original value.
     def self.load(value)
       value
     end

data/lib/readthis/scripts.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 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
@@ -48,7 +50,7 @@ module Readthis
     end
 
     def abs_path(filename)
-      dir = File.expand_path(File.dirname(__FILE__))
+      dir = File.expand_path(__dir__)
 
       File.join(dir, '../../script', filename)
     end

data/lib/readthis/serializers.rb

@@ -1,8 +1,41 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'readthis/errors'
 require 'readthis/passthrough'
 
 module Readthis
+  # Instances of the `Serializers` class are used to configure the use of
+  # multiple "serializers" for a single cache.
+  #
+  # Readthis uses Ruby's `Marshal` module for serializing all values by
+  # default. This isn't always the fastest option, and depending on your use
+  # case it may be desirable to use a faster but less flexible serializer.
+  #
+  # By default Readthis knows about 3 different serializers:
+  #
+  # * Marshal
+  # * JSON
+  # * Passthrough
+  #
+  # If all cached data can safely be represented as a string then use the
+  # pass-through serializer:
+  #
+  #   Readthis::Cache.new(marshal: Readthis::Passthrough)
+  #
+  # You can introduce up to four additional serializers by configuring
+  # `serializers` on the Readthis module. For example, if you wanted to use the
+  # extremely fast Oj library for JSON serialization:
+  #
+  #   Readthis.serializers << Oj
+  #   # Freeze the serializers to ensure they aren't changed at runtime.
+  #   Readthis.serializers.freeze!
+  #   Readthis::Cache.new(marshal: Oj)
+  #
+  # 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.
   class Serializers
     # Defines the default set of three serializers: Marshal, Passthrough, and
     # JSON. With a hard limit of 7 that leaves 4 additional slots.
@@ -32,7 +65,7 @@ module Readthis
     # @param [Module] serializer Any object that responds to `dump` and `load`
     # @return [self] Returns itself for possible chaining
     #
-    # @example
+    # @example Adding Oj as an accepted serializer
     #
     #     serializers = Readthis::Serializers.new
     #     serializers << Oj
@@ -53,16 +86,24 @@ module Readthis
 
     # Freeze the serializers hash, preventing modification.
     #
+    # @return [self] The serializer instance.
+    #
     def freeze!
       serializers.freeze
+
+      self
     end
 
     # Reset the instance back to the default state. Useful for cleanup during
     # testing.
     #
+    # @return [self] The serializer instance.
+    #
     def reset!
       @serializers = BASE_SERIALIZERS.dup
       @inverted = @serializers.invert
+
+      self
     end
 
     # Find a flag for a serializer object.
@@ -72,7 +113,7 @@ module Readthis
     # @raise [UnknownSerializerError] Indicates that a serializer was
     #   specified, but hasn't been configured for usage.
     #
-    # @example
+    # @example Find the JSON serializer's flag
     #
     #   serializers.assoc(JSON) #=> 1
     #
@@ -91,7 +132,7 @@ module Readthis
     # @param [Number] flag Integer to look up the serializer object by
     # @return [Module] The serializer object
     #
-    # @example
+    # @example Find the serializer associated with flag 1
     #
     #   serializers.rassoc(1) #=> Marshal
     #