readthis 0.8.1 → 1.0.0.pre.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ea629e7d22f58baa04359d6fabaee9116caf4e5d
-  data.tar.gz: ff5720742c337be8b178ca840064b3469766dcda
+  metadata.gz: b0b93b4402db2eaaff687eb60a40296bb618dd4e
+  data.tar.gz: 81f108e00b2b7dfe0ce92d9209c1160e3cc59a6f
 SHA512:
-  metadata.gz: b75d0eb316bb68975693ab64044cc3c30159b9511dde446b504e1075b5c6aa915bc3782290334001de3b921173714343c86110778bc41ec90f67dc84b9ef0704
-  data.tar.gz: 765fae41b2f8d511cd99269e17ed31eacbb968239e97be78422a4b20793ae3325feefc2f19d411b6d0a17722a7b06bbba78230fe49e12c76e01edabb9fc93b43
+  metadata.gz: d8e81b60017904895db2c2d2666f9f9d2fdad7fa2178c6bbca617abc0d49e5d8934c3128e0f8dba1014c5b30f02d2101fcf3102d2ecee441d5f43f9be9a35282
+  data.tar.gz: 1b8c28d2a8fdcff75d38bc565dceaf14fb442a1d14ca2c547c53e315d5d6eae08f35f96dbf3f97e268f71774ab27eb9afa5faf4266a1f3becf8af7303c92eee9

data/CHANGELOG.md

@@ -1,3 +1,24 @@
+## v1.0.0-beta
+
+- Breaking: This change is necessary for the consistency and portability of
+  values going forward. All entities are now written with a set of option flags
+  as the initial byte. This flag is later used to determine whether the entity
+  was compressed and what was used to marshal it. There are a number of
+  advantages to this approach, consistency and reliability being the most
+  important. See [readthis#17][pull-17] for additional background.
+- Added: Per-entity options can be passed through to any cache method that
+  writes a value (`write`, `fetch`, etc). For example, this allows certain
+  entities to be cached as JSON while all other entities are cached using
+  Marshal. Thanks to @fabn.
+- Fixed: A hash containing the cache key is passed as the payload for
+  `ActiveSupport::Notifications` instrumentation, rather than the key directly.
+  This moves the implementation in-line with the tests for the code, and
+  prevents errors from being masked when an error occurs inside an instrumented
+  block. [readthis#20][pull-20]. Discovered by @banister and fixed by @workmad3.
+
+[pull-17]: https://github.com/sorentwo/readthis/pull/17
+[pull-20]: https://github.com/sorentwo/readthis/pull/20
+
 ## v0.8.1 2015-09-04
 
 - Changed: `Readthis::Cache` now has an accessor for the options that were
@@ -13,9 +34,9 @@
   when it can the value looks to be compressed, falling back to the initial
   value when decompression fails. See [readthis#13][issue-13] for details.
 
-[issue-13]: https://github.com/sorentwo/readthis/pull/13
-[issue-15]: https://github.com/sorentwo/readthis/pull/15
-[issue-16]: https://github.com/sorentwo/readthis/pull/16
+[issue-13]: https://github.com/sorentwo/readthis/issues/13
+[issue-15]: https://github.com/sorentwo/readthis/issues/15
+[issue-16]: https://github.com/sorentwo/readthis/issues/16
 
 ## v0.8.0 2015-08-26
 

data/README.md

@@ -102,11 +102,11 @@ 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.
 
-Use Oj for JSON marshalling, extremely fast, but supports limited types:
+By default Readthis knows about 3 different serializers for marshalling:
 
-```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:
@@ -115,6 +115,24 @@ pass-through marshaller:
 Readthis::Cache.new(marshal: Readthis::Passthrough)
 ```
 
+You can introduce up to four additional marshals by configuring `serializers` on
+the Readthis module. For example, if you wanted to use Oj for JSON marshalling,
+it is extremely fast, but supports limited types:
+
+```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/benchmarks/composing.rb

@@ -0,0 +1,43 @@
+require 'benchmark/ips'
+
+def compose_a(marshal, compress)
+  prefix = ''
+  prefix << 'R|'.freeze
+  prefix << marshal.name.ljust(24)
+  prefix << (compress ? '1'.freeze : '0'.freeze)
+  prefix << 1
+  prefix << '|R'.freeze
+end
+
+def compose_b(marshal, compress)
+  "R|#{marshal.name.ljust(24)}#{compress ? '1'.freeze : '0'.freeze}1|R"
+end
+
+def compose_c(marshal, compress)
+  name = marshal.name.ljust(24)
+  comp = compress ? '1'.freeze : '0'.freeze
+
+  "R|#{name}#{comp}1|R"
+end
+
+SERIALIZER_FLAG = { Marshal => 0x1 }.freeze
+COMPRESSED_FLAG = 0x8
+
+# | 0000 | 0 | 000 |
+# four unused bits, # 1 compression bit, 3 bits for serializer, allow up to 8
+# different marshalers
+def compose_d(marshal, compress)
+  flags  = SERIALIZER_FLAG[marshal]
+  flags |= COMPRESSED_FLAG if compress
+
+  [flags].pack('C')
+end
+
+Benchmark.ips do |x|
+  x.report('a') { compose_a(Marshal, true) }
+  x.report('b') { compose_b(Marshal, true) }
+  x.report('c') { compose_c(Marshal, true) }
+  x.report('d') { compose_d(Marshal, true) }
+
+  x.compare!
+end

data/benchmarks/generic.rb

@@ -0,0 +1,30 @@
+require 'benchmark/ips'
+require 'json'
+require 'readthis'
+
+READTHIS = Readthis::Cache.new(
+  expires_in: 120,
+  marshal: JSON,
+  compress: true
+)
+
+def write_key(key)
+  READTHIS.write(key, key.to_s * 2048)
+end
+
+KEYS = (1..1_000).to_a
+KEYS.each { |key| write_key(key) }
+
+Benchmark.ips do |x|
+  x.report 'readthis:write' do
+    write_key(KEYS.sample)
+  end
+
+  x.report 'readthis:read' do
+    READTHIS.read(KEYS.sample)
+  end
+
+  x.report 'readthis:read_multi' do
+    READTHIS.read(KEYS.sample(30))
+  end
+end

data/benchmarks/marshalling.rb

@@ -9,18 +9,17 @@ require 'msgpack'
 require 'readthis'
 require 'readthis/passthrough'
 
-OPTIONS = { compressed: false }
+Readthis.serializers << Oj
+Readthis.serializers << MessagePack
 
-readthis_pass    = Readthis::Cache.new(OPTIONS.merge(marshal: Readthis::Passthrough))
-readthis_oj      = Readthis::Cache.new(OPTIONS.merge(marshal: Oj))
-readthis_msgpack = Readthis::Cache.new(OPTIONS.merge(marshal: MessagePack))
-readthis_json    = Readthis::Cache.new(OPTIONS.merge(marshal: JSON))
-readthis_ruby    = Readthis::Cache.new(OPTIONS.merge(marshal: Marshal))
+readthis_oj      = Readthis::Cache.new(marshal: Oj)
+readthis_msgpack = Readthis::Cache.new(marshal: MessagePack)
+readthis_json    = Readthis::Cache.new(marshal: JSON)
+readthis_ruby    = Readthis::Cache.new(marshal: Marshal)
 
 HASH = ('a'..'z').each_with_object({}) { |key, memo| memo[key] = key }
 
 Benchmark.ips do |x|
-  x.report('pass:hash:dump')    { readthis_pass.write('pass',       HASH) }
   x.report('oj:hash:dump')      { readthis_oj.write('oj',           HASH) }
   x.report('json:hash:dump')    { readthis_json.write('json',       HASH) }
   x.report('msgpack:hash:dump') { readthis_msgpack.write('msgpack', HASH) }
@@ -30,7 +29,6 @@ Benchmark.ips do |x|
 end
 
 Benchmark.ips do |x|
-  x.report('pass:hash:load')    { readthis_pass.read('pass') }
   x.report('oj:hash:load')      { readthis_oj.read('oj') }
   x.report('json:hash:load')    { readthis_json.read('json') }
   x.report('msgpack:hash:load') { readthis_msgpack.read('msgpack') }

data/benchmarks/multi.rb

@@ -1,7 +1,3 @@
-require 'bundler'
-
-Bundler.setup
-
 require 'benchmark/ips'
 require 'dalli'
 require 'redis-activesupport'

data/benchmarks/parsing.rb

@@ -0,0 +1,42 @@
+require 'benchmark/ips'
+
+def parse_a(string)
+  marshal  = string[2, 12].strip
+  compress = string[15] == '1'.freeze
+
+  [Kernel.const_get(marshal), compress, string[18..-1]]
+end
+
+def parse_b(marked)
+  prefix = marked[0, 32].scrub('*'.freeze)[/R\|(.*)\|R/, 1]
+  offset = prefix.size + 4
+
+  marshal, c_name, _ = prefix.split(' '.freeze)
+
+  compress = c_name == 'true'.freeze
+
+  [Kernel.const_get(marshal), compress, marked[offset..-1]]
+end
+
+SERIALIZERS     = { Marshal => 0x1 }.freeze
+DESERIALIZERS   = SERIALIZERS.invert.freeze
+COMPRESSED_FLAG = 0x8
+MARSHAL_FLAG    = 0x3
+BINARY_FLAG     = [SERIALIZERS[Marshal] | COMPRESSED_FLAG].pack('C')
+
+def parse_c(binary_string)
+  flags = binary_string[0].unpack('C').first
+
+  [DESERIALIZERS[flags & MARSHAL_FLAG], flags & COMPRESSED_FLAG, binary_string[1..-1]]
+end
+
+STR = 'R|Marshal      0|Rafdlkadfjadfj asdlkfjasdlfkj asdlfkjdasflkjadsflkjadslkjfadslkjfasdlkjfadlskjf laksdjflkajsdflkjadsflkadjsfladskjf laksjflakdjfalsdkjfadlskjf laksdjflkajdsflk j'
+STR2 = BINARY_FLAG << 'Rafdlkadfjadfj asdlkfjasdlfkj asdlfkjdasflkjadsflkjadslkjfadslkjfasdlkjfadlskjf laksdjflkajsdflkjadsflkadjsfladskjf laksjflakdjfalsdkjfadlskjf laksdjflkajdsflk j'
+
+Benchmark.ips do |x|
+  x.report('a') { parse_a(STR) }
+  x.report('b') { parse_b(STR) }
+  x.report('c') { parse_c(STR2) }
+
+  x.compare!
+end

data/benchmarks/profile.rb

@@ -6,7 +6,7 @@ require 'fileutils'
 require 'stackprof'
 require 'readthis'
 
-readthis = Readthis::Cache.new('redis://localhost:6379/11')
+readthis = Readthis::Cache.new
 
 FileUtils.mkdir_p('tmp')
 readthis.clear

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/lib/readthis/cache.rb

@@ -171,7 +171,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
@@ -310,7 +310,7 @@ module Readthis
     # @example
     #
     #   cache.clear #=> 'OK'
-    def clear(options = {})
+    def clear(_options = nil)
       invoke(:clear, '*', &:flushdb)
     end
 
@@ -318,11 +318,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
 
@@ -339,7 +340,7 @@ module Readthis
       name    = "cache_#{operation}.active_support"
       payload = { key: key }
 
-      self.class.notifications.instrument(name, key) { yield(payload) }
+      self.class.notifications.instrument(name, payload) { yield(payload) }
     end
 
     def invoke(operation, key, &block)

data/lib/readthis/entity.rb

@@ -2,51 +2,144 @@ 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
+    MARSHAL_FLAG    = 0x3
 
+    # 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 & MARSHAL_FLAG)
+        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/serializers.rb

@@ -0,0 +1,100 @@
+require 'json'
+require 'readthis/passthrough'
+
+module Readthis
+  SerializersFrozenError = Class.new(Exception)
+  SerializersLimitError  = Class.new(Exception)
+
+  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?
+        raise SerializersFrozenError
+      when serializers.length > SERIALIZER_LIMIT
+        raise 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 by the marshal object.
+    #
+    # @param [Object] Look up a flag by object
+    # @return [Number] Corresponding flag for the marshal object
+    #
+    # @example
+    #
+    #   serializers.assoc(Marshal) #=> 1
+    #
+    def assoc(marshal)
+      serializers[marshal]
+    end
+
+    # Find a marshal object by flag value.
+    #
+    # @param [Number] Flag to look up the marshal object by
+    # @return [Module] The marshal object
+    #
+    def rassoc(flag)
+      inverted[flag]
+    end
+
+    # The current list of marshal objects.
+    #
+    def marshals
+      serializers.keys
+    end
+
+    # The current list of flags.
+    #
+    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-beta'
 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 }
@@ -82,19 +82,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(_)
+          'dumped'
+        end
+
+        def self.load(_)
+          'dumped'
+        end
+      end
+
+      Readthis.serializers << custom
+
+      cache.write('customized', 'overwrite me', marshal: custom)
+
+      expect(cache.read('customized')).to include('dumped')
+    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'
 

data/spec/readthis/entity_spec.rb

@@ -1,4 +1,4 @@
-require 'readthis/entity'
+require 'readthis'
 require 'json'
 
 RSpec.describe Readthis::Entity do
@@ -7,14 +7,21 @@ RSpec.describe Readthis::Entity do
       string = 'some string'
       entity = Readthis::Entity.new
 
-      expect(entity.dump(string)).to eq(Marshal.dump(string))
+      expect(entity.dump(string)).to include(Marshal.dump(string))
     end
 
     it 'marshals using a custom marshaller' do
       string = 'some string'
       entity = Readthis::Entity.new(marshal: JSON)
 
-      expect(entity.dump(string)).to eq(JSON.dump(string))
+      expect(entity.dump(string)).to include(JSON.dump(string))
+    end
+
+    it 'overrides the marshaller' do
+      string = 'still some string'
+      entity = Readthis::Entity.new
+
+      expect(entity.dump(string, marshal: JSON)).to include(JSON.dump(string))
     end
 
     it 'applies compression when enabled' do
@@ -39,6 +46,22 @@ RSpec.describe Readthis::Entity do
       expect(entity.load(string)).to eq(string)
     end
 
+    it 'overrides the compression threshold' do
+      string = 'a' * 8
+      entity = Readthis::Entity.new(compress: true, threshold: 2)
+      dumped = entity.dump(string)
+
+      expect(entity.dump(string, threshold: 100)).not_to eq(dumped)
+    end
+
+    it 'overrides the compression option' do
+      string = 'a' * 8
+      entity = Readthis::Entity.new(compress: true, threshold: 2)
+      dumped = entity.dump(string)
+
+      expect(entity.dump(string, compress: false)).not_to eq(dumped)
+    end
+
     it 'safely roundtrips nil values' do
       entity = Readthis::Entity.new
 
@@ -49,26 +72,27 @@ RSpec.describe Readthis::Entity do
   describe '#load' do
     it 'unmarshals a value' do
       object = { a: 1, b: '2' }
-      dumped = Marshal.dump(object)
       entity = Readthis::Entity.new
+      dumped = entity.dump(object)
 
       expect(entity.load(dumped)).to eq(object)
     end
 
     it 'uncompresses when compression is enabled' do
       string = 'another one of those huge strings'
-      entity = Readthis::Entity.new(compress: true, threshold: 0)
-      dumped = Marshal.dump(string)
-
-      compressed = entity.compress(dumped)
+      entity = Readthis::Entity.new(compress: true, threshold: 4)
+      dumped = entity.dump(dumped)
 
-      expect(entity.load(compressed)).not_to eq(string)
+      expect(entity.load(dumped)).not_to eq(string)
     end
 
-    it 'does not try to load a nil value' do
-      entity = Readthis::Entity.new
+    it 'uses the dumped value to define load options' do
+      value   = [1, 2, 3]
+      custom  = Readthis::Entity.new(marshal: JSON, compress: true)
+      general = Readthis::Entity.new(marshal: Marshal, compress: false)
+      dumped  = custom.dump(value)
 
-      expect(entity.load(nil)).to be_nil
+      expect(general.load(dumped)).to eq(value)
     end
 
     it 'passes through the value when it fails to marshal' do
@@ -84,4 +108,47 @@ RSpec.describe Readthis::Entity do
       expect { entity.load(dumped) }.not_to raise_error
     end
   end
+
+  describe '#compose' do
+    it 'prepends the string with a formatted marker' do
+      string = 'the quick brown fox'
+      marked = Readthis::Entity.new.compose(string, Marshal, true)
+
+      expect(marked[0]).not_to eq('t')
+    end
+  end
+
+  describe '#decompose' do
+    it 'returns extracted options and values' do
+      string = 'the quick brown fox'
+      entity = Readthis::Entity.new
+      marked = entity.compose(string.dup, JSON, true)
+
+      marshal, compress, value = entity.decompose(marked)
+
+      expect(marshal).to eq(JSON)
+      expect(compress).to eq(true)
+      expect(value).to eq(string)
+    end
+
+    it 'can reconstruct longer qualified module names' do
+      string = 'a' * 30
+      entity = Readthis::Entity.new
+      marked = entity.compose(string, Readthis::Passthrough, false)
+
+      marshal, _, _ = entity.decompose(marked)
+
+      expect(marshal).to eq(Readthis::Passthrough)
+    end
+
+    it 'returns the original string without a marker' do
+      string = 'the quick brown fox'
+      entity = Readthis::Entity.new
+      marshal, compress, value = entity.decompose(string)
+
+      expect(marshal).to eq(Marshal)
+      expect(compress).to eq(false)
+      expect(value).to eq(string)
+    end
+  end
 end

data/spec/readthis/serializers_spec.rb

@@ -0,0 +1,72 @@
+require 'readthis/serializers'
+
+RSpec.describe Readthis::Serializers do
+  CustomSerializer  = Class.new
+  AnotherSerializer = Class.new
+
+  describe '#<<' do
+    it 'appends new serializers' do
+      serializers = Readthis::Serializers.new
+
+      serializers << CustomSerializer
+
+      expect(serializers.marshals).to include(CustomSerializer)
+      expect(serializers.flags).to eq((1..4).to_a)
+    end
+
+    it 'increments flags' do
+      serializers = Readthis::Serializers.new
+      serializers << CustomSerializer
+      serializers << AnotherSerializer
+
+      expect(serializers.flags).to eq((1..5).to_a)
+    end
+
+    it 'prevents more than seven serializers' do
+      serializers = Readthis::Serializers.new
+
+      expect {
+        10.times { serializers << Class.new }
+      }.to raise_error(Readthis::SerializersLimitError)
+    end
+  end
+
+  describe '#assoc' do
+    it 'looks up serializers by module' do
+      serializers = Readthis::Serializers.new
+
+      expect(serializers.assoc(Marshal)).to eq(0x1)
+    end
+  end
+
+  describe '#rassoc' do
+    it 'inverts the current set of serializers' do
+      serializers = Readthis::Serializers.new
+
+      expect(serializers.rassoc(1)).to eq(Marshal)
+    end
+  end
+
+  describe '#freeze!' do
+    it 'does now allow appending after freeze' do
+      serializers = Readthis::Serializers.new
+
+      serializers.freeze!
+
+      expect {
+        serializers << CustomSerializer
+      }.to raise_error(Readthis::SerializersFrozenError)
+    end
+  end
+
+  describe '#reset!' do
+    it 'reverts back to the original set of serializers' do
+      serializers = Readthis::Serializers.new
+
+      serializers << Class.new
+      serializers.reset!
+
+      expect(serializers.marshals.length).to eq(3)
+    end
+  end
+end

data/spec/readthis_spec.rb

@@ -0,0 +1,9 @@
+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
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: readthis
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 1.0.0.pre.beta
 platform: ruby
 authors:
 - Parker Selbert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-04 00:00:00.000000000 Z
+date: 2015-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -111,11 +111,14 @@ files:
 - PERFORMANCE.md
 - README.md
 - Rakefile
+- benchmarks/composing.rb
 - benchmarks/compressed.rb
 - benchmarks/driver.rb
+- benchmarks/generic.rb
 - benchmarks/marshalling.rb
 - benchmarks/memory.rb
 - benchmarks/multi.rb
+- benchmarks/parsing.rb
 - benchmarks/profile.rb
 - bin/rspec
 - lib/active_support/cache/readthis_store.rb
@@ -125,6 +128,7 @@ files:
 - lib/readthis/expanders.rb
 - lib/readthis/notifications.rb
 - lib/readthis/passthrough.rb
+- lib/readthis/serializers.rb
 - lib/readthis/version.rb
 - readthis.gemspec
 - spec/readthis/cache_spec.rb
@@ -132,6 +136,8 @@ files:
 - spec/readthis/expanders_spec.rb
 - spec/readthis/notifications_spec.rb
 - spec/readthis/passthrough_spec.rb
+- spec/readthis/serializers_spec.rb
+- spec/readthis_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/sorentwo/readthis
 licenses:
@@ -148,12 +154,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.4.5.1
 signing_key: 
 specification_version: 4
 summary: Pooled active support compliant caching with redis
@@ -163,4 +169,6 @@ test_files:
 - spec/readthis/expanders_spec.rb
 - spec/readthis/notifications_spec.rb
 - spec/readthis/passthrough_spec.rb
+- spec/readthis/serializers_spec.rb
+- spec/readthis_spec.rb
 - spec/spec_helper.rb