readthis 0.8.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ea629e7d22f58baa04359d6fabaee9116caf4e5d
-  data.tar.gz: ff5720742c337be8b178ca840064b3469766dcda
+  metadata.gz: 985ab4cb70b6ff45de0b279fe4d3ca90690cb206
+  data.tar.gz: d3c0519b74366c12278dc2a554d0a33c2914e7ac
 SHA512:
-  metadata.gz: b75d0eb316bb68975693ab64044cc3c30159b9511dde446b504e1075b5c6aa915bc3782290334001de3b921173714343c86110778bc41ec90f67dc84b9ef0704
-  data.tar.gz: 765fae41b2f8d511cd99269e17ed31eacbb968239e97be78422a4b20793ae3325feefc2f19d411b6d0a17722a7b06bbba78230fe49e12c76e01edabb9fc93b43
+  metadata.gz: e0cec4bef654487ed5f99c46f27d05572993a823239d1993b6e0b534f0b699f170c773ef191cddf468e1b05936c588d23ac6716ddf7659c89a86710306f13c5b
+  data.tar.gz: 5f8ac666204946a58135953c5e4b23d64a12f412019d578b28c8b8b1a7c351c1004775c0470a812038b12d2577b87eec5df8a4e09f628e5fbb1bed3fc008517a

data/README.md

@@ -52,7 +52,11 @@ cache = Readthis::Cache.new(
 )
 ```
 
+You can also specify `host`, `port`, `db` or any other valid Redis options. For
+more details about connection options see in [redis gem documentation][redisrb]
+
 [store]: http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html
+[redisrb]: https://github.com/redis/redis-rb#getting-started
 
 ### Instances & Databases
 
@@ -96,25 +100,43 @@ config.cache_store = :readthis_store, {
 }
 ```
 
-### Marshalling
+### Serializing
 
-Readthis uses Ruby's `Marshal` module for dumping and loading 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 marshaller.
+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.
 
-Use Oj for JSON marshalling, extremely fast, but supports limited types:
+By default Readthis knows about 3 different serializers:
 
-```ruby
-Readthis::Cache.new(marshal: Oj)
-```
+* Marshal
+* JSON
+* Passthrough
 
 If all cached data can safely be represented as a string then use the
-pass-through marshaller:
+pass-through serializer:
 
 ```ruby
 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:
+
+```ruby
+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.
+
 ## Differences From ActiveSupport::Cache
 
 Readthis supports all of standard cache methods except for the following:

data/lib/active_support/cache/readthis_store.rb

@@ -2,6 +2,6 @@ require 'readthis'
 
 module ActiveSupport
   module Cache
-    ReadthisStore ||= Readthis::Cache
+    ReadthisStore ||= Readthis::Cache # rubocop:disable Style/ConstantName
   end
 end

data/lib/readthis/cache.rb

@@ -1,24 +1,19 @@
 require 'readthis/entity'
 require 'readthis/expanders'
-require 'readthis/notifications'
 require 'readthis/passthrough'
 require 'redis'
 require 'connection_pool'
 
 module Readthis
   class Cache
-    attr_reader :entity, :expires_in, :namespace, :options, :pool
+    attr_reader :entity, :notifications, :options, :pool
 
     # Provide a class level lookup of the proper notifications module.
     # Instrumention is expected to occur within applications that have
     # ActiveSupport::Notifications available, but needs to work even when it
     # isn't.
     def self.notifications
-      if defined?(ActiveSupport::Notifications)
-        ActiveSupport::Notifications
-      else
-        Readthis::Notifications
-      end
+      ActiveSupport::Notifications if defined?(ActiveSupport::Notifications)
     end
 
     # Creates a new Readthis::Cache object with the given options.
@@ -39,9 +34,7 @@ module Readthis
     #   Readthis::Cache.new(compress: true, compression_threshold: 2048)
     #
     def initialize(options = {})
-      @options    = options
-      @expires_in = options.fetch(:expires_in, nil)
-      @namespace  = options.fetch(:namespace, nil)
+      @options = options
 
       @entity = Readthis::Entity.new(
         marshal:   options.fetch(:marshal, Marshal),
@@ -171,7 +164,7 @@ module Readthis
     #   cache.increment('counter', 2) # => 3
     #
     def increment(key, amount = 1, options = {})
-      invoke(:incremenet, key) do |store|
+      invoke(:increment, key) do |_store|
         alter(key, amount, options)
       end
     end
@@ -192,7 +185,7 @@ module Readthis
     #   cache.decrement('counter', 2) # => 17
     #
     def decrement(key, amount = 1, options = {})
-      invoke(:decrement, key) do |store|
+      invoke(:decrement, key) do |_store|
         alter(key, amount * -1, options)
       end
     end
@@ -271,13 +264,13 @@ module Readthis
       extracted = extract_options!(keys)
       missing   = {}
 
-      invoke(:fetch_multi, keys) do |store|
+      invoke(:fetch_multi, keys) do |_store|
         results.each do |key, value|
-          if value.nil?
-            value = yield(key)
-            missing[key] = value
-            results[key] = value
-          end
+          next unless value.nil?
+
+          value = yield(key)
+          missing[key] = value
+          results[key] = value
         end
       end
 
@@ -310,7 +303,7 @@ module Readthis
     # @example
     #
     #   cache.clear #=> 'OK'
-    def clear(options = {})
+    def clear(_options = nil)
       invoke(:clear, '*', &:flushdb)
     end
 
@@ -318,11 +311,12 @@ module Readthis
 
     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, entity.dump(value))
+        store.setex(namespaced, expiration.to_i, dumped)
       else
-        store.set(namespaced, entity.dump(value))
+        store.set(namespaced, dumped)
       end
     end
 
@@ -335,11 +329,15 @@ module Readthis
       delta
     end
 
-    def instrument(operation, key)
-      name    = "cache_#{operation}.active_support"
-      payload = { key: key }
+    def instrument(name, key)
+      if self.class.notifications
+        name    = "cache_#{name}.active_support"
+        payload = { key: key, name: name }
 
-      self.class.notifications.instrument(name, key) { yield(payload) }
+        self.class.notifications.instrument(name, payload) { yield(payload) }
+      else
+        yield
+      end
     end
 
     def invoke(operation, key, &block)
@@ -353,10 +351,7 @@ module Readthis
     end
 
     def merged_options(options)
-      options = options || {}
-      options[:namespace]  ||= namespace
-      options[:expires_in] ||= expires_in
-      options
+      (options || {}).merge!(@options)
     end
 
     def pool_options(options)

data/lib/readthis/entity.rb

@@ -2,51 +2,143 @@ require 'zlib'
 
 module Readthis
   class Entity
-    DEFAULT_THRESHOLD = 8 * 1024
-    MAGIC_BYTES = [120, 156].freeze
+    DEFAULT_OPTIONS = {
+      compress:  false,
+      marshal:   Marshal,
+      threshold: 8 * 1024
+    }.freeze
 
-    attr_reader :marshal, :compression, :threshold
+    COMPRESSED_FLAG = 0x8
 
+    # Creates a Readthis::Entity with default options. Each option can be
+    # overridden later when entities are being dumped.
+    #
+    # Options are sticky, meaning that whatever is used when dumping will
+    # 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
+    #
     def initialize(options = {})
-      @marshal     = options.fetch(:marshal, Marshal)
-      @compression = options.fetch(:compress, false)
-      @threshold   = options.fetch(:threshold, DEFAULT_THRESHOLD)
+      @options = DEFAULT_OPTIONS.merge(options)
     end
 
-    def dump(value)
-      if compress?(value)
-        compress(value)
-      else
-        marshal.dump(value)
-      end
+    # 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
+    # @return [String] The prepared, possibly compressed, string
+    #
+    # @example Dumping a value using defaults
+    #
+    #   entity.dump(string)
+    #
+    # @example Dumping a value with overrides
+    #
+    #   entity.dump(string, compress: false)
+    #
+    def dump(value, options = {})
+      compress  = with_fallback(options, :compress)
+      marshal   = with_fallback(options, :marshal)
+      threshold = with_fallback(options, :threshold)
+
+      dumped = deflate(marshal.dump(value), compress, threshold)
+
+      compose(dumped, marshal, compress)
     end
 
-    def load(value)
-      if compressed?(value)
-        decompress(value)
-      else
-        marshal.load(value)
-      end
-    rescue TypeError, Zlib::Error
-      value
+    # Parse a dumped value using the embedded options.
+    #
+    # @param  [String] Option embedded string to load
+    # @return [String] The original dumped string, restored
+    #
+    # @example
+    #
+    #   entity.load(dumped)
+    #
+    def load(string)
+      marshal, compress, value = decompose(string)
+
+      marshal.load(inflate(value, compress))
+    rescue TypeError, NoMethodError
+      string
     end
 
-    def compress(value)
-      Zlib::Deflate.deflate(marshal.dump(value))
+    # Composes a single byte comprised of the chosen serializer and compression
+    # options. The byte is formatted as:
+    #
+    # | 0000 | 0 | 000 |
+    #
+    # 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
+    # @return [String] The original string with a single byte prefixed
+    #
+    # @example Compose an option embedded string
+    #
+    #   entity.compose(string, Marshal, false) => 0x1  + string
+    #   entity.compose(string, JSON, true)     => 0x10 + string
+    #
+    def compose(value, marshal, compress)
+      flags  = serializers.assoc(marshal)
+      flags |= COMPRESSED_FLAG if compress
+
+      value.prepend([flags].pack('C'))
     end
 
-    def decompress(value)
-      marshal.load(Zlib::Inflate.inflate(value))
+    # Decompose an option embedded string into marshal, compression and value.
+    #
+    # @param  [String] Option embedded string to
+    # @return [Array<Module, Boolean, String>] An array comprised of the
+    #   marshal, compression flag, and the base string.
+    #
+    def decompose(string)
+      flags = string[0].unpack('C').first
+
+      if flags < 16
+        marshal  = serializers.rassoc(flags)
+        compress = (flags & COMPRESSED_FLAG) != 0
+
+        [marshal, compress, string[1..-1]]
+      else
+        [@options[:marshal], @options[:compress], string]
+      end
     end
 
     private
 
-    def compress?(value)
-      compression && value.bytesize >= threshold
+    def deflate(value, compress, threshold)
+      if compress && value.bytesize >= threshold
+        Zlib::Deflate.deflate(value)
+      else
+        value
+      end
+    end
+
+    def inflate(value, decompress)
+      if decompress
+        Zlib::Inflate.inflate(value)
+      else
+        value
+      end
+    rescue Zlib::Error
+      value
+    end
+
+    def serializers
+      Readthis.serializers
     end
 
-    def compressed?(value)
-      compression && value[0, 2].unpack('CC') == MAGIC_BYTES
+    def with_fallback(options, key)
+      options.key?(key) ? options[key] : @options[key]
     end
   end
 end

data/lib/readthis/expanders.rb

@@ -7,7 +7,7 @@ module Readthis
       when key.is_a?(Array)
         key.flat_map { |elem| expand_key(elem) }.join('/')
       when key.is_a?(Hash)
-        key.sort_by { |key, _| key.to_s }.map { |key, val| "#{key}=#{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/serializers.rb

@@ -0,0 +1,111 @@
+require 'json'
+require 'readthis/passthrough'
+
+module Readthis
+  SerializersFrozenError = Class.new(StandardError)
+  SerializersLimitError  = Class.new(StandardError)
+  UnknownSerializerError = Class.new(StandardError)
+
+  class Serializers
+    BASE_SERIALIZERS = {
+      Marshal     => 0x1,
+      Passthrough => 0x2,
+      JSON        => 0x3
+    }.freeze
+
+    SERIALIZER_LIMIT = 7
+
+    attr_reader :serializers, :inverted
+
+    # Creates a new Readthis::Serializers entity. No configuration is expected
+    # during initialization.
+    #
+    def initialize
+      reset!
+    end
+
+    # Append a new serializer. Up to 7 total serializers may be configured for
+    # 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`
+    # @return [self] Returns itself for possible chaining
+    #
+    # @example
+    #
+    #     serializers = Readthis::Serializers.new
+    #     serializers << Oj
+    #
+    def <<(serializer)
+      case
+      when serializers.frozen?
+        fail SerializersFrozenError
+      when serializers.length > SERIALIZER_LIMIT
+        fail SerializersLimitError
+      else
+        @serializers[serializer] = flags.max.succ
+        @inverted = @serializers.invert
+      end
+
+      self
+    end
+
+    # Freeze the serializers hash, preventing modification.
+    #
+    def freeze!
+      serializers.freeze
+    end
+
+    # Reset the instance back to the default state. Useful for cleanup during
+    # testing.
+    #
+    def reset!
+      @serializers = BASE_SERIALIZERS.dup
+      @inverted = @serializers.invert
+    end
+
+    # Find a flag for a serializer object.
+    #
+    # @param [Object] 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.
+    #
+    # @example
+    #
+    #   serializers.assoc(JSON) #=> 1
+    #
+    def assoc(serializer)
+      flag = serializers[serializer]
+
+      unless flag
+        fail UnknownSerializerError, "'#{serializer}' hasn't been configured"
+      end
+
+      flag
+    end
+
+    # Find a serializer object by flag value.
+    #
+    # @param [Number] Flag to look up the serializer object by
+    # @return [Module] The serializer object
+    #
+    # @example
+    #
+    #   serializers.rassoc(1) #=> Marshal
+    #
+    def rassoc(flag)
+      inverted[flag & inverted.length]
+    end
+
+    # @private
+    def marshals
+      serializers.keys
+    end
+
+    # @private
+    def flags
+      serializers.values
+    end
+  end
+end

data/lib/readthis/version.rb

@@ -1,3 +1,3 @@
 module Readthis
-  VERSION = '0.8.1'
+  VERSION = '1.0.0'
 end

data/lib/readthis.rb

@@ -1,5 +1,11 @@
 require 'readthis/cache'
+require 'readthis/serializers'
 require 'readthis/version'
 
 module Readthis
+  extend self
+
+  def serializers
+    @serializers ||= Readthis::Serializers.new
+  end
 end

data/spec/readthis/cache_spec.rb

@@ -1,4 +1,4 @@
-require 'readthis/cache'
+require 'readthis'
 
 RSpec.describe Readthis::Cache do
   let(:cache) { Readthis::Cache.new }
@@ -8,18 +8,6 @@ RSpec.describe Readthis::Cache do
   end
 
   describe '#initialize' do
-    it 'accepts and persists a namespace' do
-      cache = Readthis::Cache.new(namespace: 'kash')
-
-      expect(cache.namespace).to eq('kash')
-    end
-
-    it 'accepts and persists an expiration' do
-      cache = Readthis::Cache.new(expires_in: 10)
-
-      expect(cache.expires_in).to eq(10)
-    end
-
     it 'makes options available' do
       cache = Readthis::Cache.new(namespace: 'cache', expires_in: 1)
 
@@ -82,19 +70,52 @@ RSpec.describe Readthis::Cache do
     end
   end
 
+  describe 'serializers' do
+    after do
+      Readthis.serializers.reset!
+    end
+
+    it 'uses globally configured serializers' do
+      custom = Class.new do
+        def self.dump(value)
+          value
+        end
+
+        def self.load(value)
+          value
+        end
+      end
+
+      Readthis.serializers << custom
+
+      cache.write('customized', 'some value', marshal: custom)
+
+      expect(cache.read('customized')).to eq('some value')
+    end
+  end
+
   describe 'compression' do
-    it 'round trips entries when compression is enabled' do
+    it 'roundtrips entries when compression is enabled' do
       com_cache = Readthis::Cache.new(compress: true, compression_threshold: 8)
       raw_cache = Readthis::Cache.new
       value = 'enough text that it should be compressed'
 
       com_cache.write('compressed', value)
 
-      expect(raw_cache.read('compressed')).not_to eq(value)
       expect(com_cache.read('compressed')).to eq(value)
+      expect(raw_cache.read('compressed')).to eq(value)
+    end
+
+    it 'roundtrips entries with option overrides' do
+      cache = Readthis::Cache.new(compress: false)
+      value = 'enough text that it should be compressed'
+
+      cache.write('comp-round', value, marshal: JSON, compress: true, threshold: 8)
+
+      expect(cache.read('comp-round')).to eq(value)
     end
 
-    it 'round trips bulk entries when compression is enabled' do
+    it 'roundtrips bulk entries when compression is enabled' do
       cache = Readthis::Cache.new(compress: true, compression_threshold: 8)
       value = 'also enough text to compress'
 
@@ -146,7 +167,7 @@ RSpec.describe Readthis::Cache do
       expect(cache.read_multi('a', 'b', 'c')).to eq(
         'a' => 1,
         'b' => 2,
-        'c' => '3',
+        'c' => '3'
       )
     end
 
@@ -156,7 +177,7 @@ RSpec.describe Readthis::Cache do
 
       expect(cache.read_multi('d', 'e', namespace: 'cache')).to eq(
         'd' => 1,
-        'e' => 2,
+        'e' => 2
       )
     end
 
@@ -175,7 +196,11 @@ RSpec.describe Readthis::Cache do
     end
 
     it 'respects passed options' do
-      cache.write_multi({ 'a' => 1, 'b' => 2 }, namespace: 'multi', expires_in: 1)
+      cache.write_multi(
+        { 'a' => 1, 'b' => 2 },
+        namespace: 'multi',
+        expires_in: 1
+      )
 
       expect(cache.read('a')).to be_nil
       expect(cache.read('a', namespace: 'multi')).to eq(1)
@@ -194,7 +219,7 @@ RSpec.describe Readthis::Cache do
       expect(results).to eq(
         'a' => 1,
         'b' => 'bb',
-        'c' => 3,
+        'c' => 3
       )
 
       expect(cache.read('b')).to eq('bb')
@@ -266,4 +291,27 @@ RSpec.describe Readthis::Cache do
       expect(cache.decrement('unknown')).to eq(-1)
     end
   end
+
+  describe 'instrumentation' do
+    it 'instruments cache invokations' do
+      require 'active_support/notifications'
+
+      notes  = ActiveSupport::Notifications
+      cache  = Readthis::Cache.new
+      events = []
+
+      notes.subscribe(/cache_*/) do |*args|
+        events << ActiveSupport::Notifications::Event.new(*args)
+      end
+
+      cache.write('a', 'a')
+      cache.read('a')
+
+      expect(events.length).to eq(2)
+      expect(events.map(&:name)).to eq(%w[
+        cache_write.active_support
+        cache_read.active_support
+      ])
+    end
+  end
 end