sequel-unicache 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7312873a5f6af6b72a09b5a4711198ecd8dc437a
+  data.tar.gz: 16fa4a4d621007f6e721161f7083a4ef0aaed761
+SHA512:
+  metadata.gz: 87c3e2659afbacf1efe0378f7521c991e5595330e74adcfee6798aec6d54962ab741b8b7e7e2d3d7b77aa4e8550287870d0df166222c2307c991613965232eed
+  data.tar.gz: c4f9ce36433aa0f91dcc7822d5a04e6413ef524565aae5e442c81d0d83ea2eb10d342f4a590ece8e4fbb908de78eeccc1679a6c3abca0c9197a9b4c87a67d327

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.yml

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in sequel-unicache.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Bachue Zhou
+
+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

@@ -0,0 +1,144 @@
+[![Build Status](https://travis-ci.org/bachue/sequel-unicache.svg)](https://travis-ci.org/bachue/sequel-unicache)
+
+# Sequel Unicache
+
+Read through caching library inspired by Cache Money, support Sequel 4
+
+Read-Through: Queries by ID or any specified unique key, like `User[params[:id]]` or `User[username: 'bachue@gmail.com']`, will first look in Memcache/Redis store and then look in the database for the results of that query. If there is a cache miss, it will populate the cache. As objects are updated and deleted, all of the caches are automatically expired.
+
+## Dependency
+
+Ruby >= 2.1.0
+Sequel >= 4.0
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sequel-unicache'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install sequel-unicache
+
+## Configuration
+
+You must configure Unicache during initialization, for Rails, create a file in config/initializers and copy the code into it will be acceptable.
+
+```ruby
+Sequel::Unicache.configure cache: Dalli::Client.new('localhost:11211'),       # Required, object to manipulate memcache or redis
+                   ttl: 60,                                                   # Expiration time, by default it's 0, means won't expire
+                   serialize: {|values, opts| Marshal.dump(values) },         # Serialization method,
+                                                                              # by default it's Marshal (fast, Ruby native-supported, non-portable)
+                   deserialize: {|cache, opts| Marshal.load(cache) },         # Deserialization method
+                   key: {|hash, opts| "#{opts.model_class.name}/{hash[:id]}" },    # Cache key generation method
+                   enabled: true,                                             # Enabled on all Sequel::Model subclasses by default
+                   logger: Logger.new(STDOUT)                                 # Logger, needed when debug
+
+# Read & write global configuration by key:
+Sequel::Unicache.config.ttl # 60
+Sequel::Unicache.config.ttl = 20
+```
+
+Unicache configuration has 3 levels, global-level, configuration-level and key-level, which is the most flexible.
+
+## Usage
+
+For example, cache User object:
+
+```ruby
+class User < Sequel::Model
+  # class level configuration, for all unicache keys of the model
+  unicache if: {|user, opts| !user.deleted? },                      # don't cache it if model is deleted
+           ttl: 30,                                                 # Specify the cache expiration time (unit: second), will overwrite the default configuration
+           cache: Dalli::Client.new('localhost:11211'),             # Memcache/Redis store, will overwrite the default configuration
+           serialize: {|values, opts| values.to_msgpack },          # Serialization method, will overwrite the global configuration
+           deserialize: {|cache, opts| MessagePack.unpack(cache) }, # Deserialization method, will overwrite the global configuration
+           key: {|hash, opts| "users/#{hash[:id]}" },               # Cache key generation method, will overwrite the global configuration
+           logger: Logger.new(STDERR),                              # Object for log, will overwrite the global configuration
+
+  # by default primary key is always unique cache key, all settings will just follow global configuration and class configuration
+  # key level configuration for username
+  unicache :username,                                               # username will also be an unique key (username should has unique index in database, and never be null)
+           ttl: 60                                                  # will override the global and class configuration
+
+  unicache :company_name, :department, :employee_id                 # company_name, department, employee_id have complexed unique index
+end
+```
+
+Then it will fetch cached object in this situations:
+
+```ruby
+User[1]
+User[username: 'bachue@gmail.com']
+User.find 1
+User.find username: 'bachue@gmail.com'
+
+User[company_name: 'EMC', employee_id: '12345']
+User.find company_name: 'EMC', employee_id: '12345'
+article.user
+```
+
+Cache expiration methods:
+
+```ruby
+user.expire_unicache
+```
+
+You can temporarily suspend / unsuspend read-through on runtime:
+
+```ruby
+# These three APIs are thread-safe
+Sequel::Unicache.suspend_unicache
+Sequel::Unicache.unsuspend_unicache
+Sequel::Unicache.suspend_unicache do
+  User[1] # query database directly, and won't write model into cache
+end
+```
+
+Even if read-through is suspended, model modification or deletion will still expire the cache, don't worry about it.
+
+Within a transaction, read-through will also be suspended, then you can query data from transaction rather than cache.
+
+You're not supposed to enable Unicache during the testing or development. These methods can help to enable or disable all Unicache features.
+
+```ruby
+# Notice: These three APIs are not thread-safe, do not call then on runtime!
+Sequel::Unicache.enable
+Sequel::Unicache.disable
+Sequel::Unicache.enabled?
+```
+
+But if Unicache is disabled, no expiration any more, cache could be dirty because of that.
+
+Unicache won't expire cache until you create, update or delete a model and commit the transaction successfully.
+
+If you reload a model, cache will also be updated.
+
+## Notice
+
+* Database must support transaction.
+
+* You must call Sequel APIs as the document mentioned then cache can work.
+
+* You must set primary key before you call any Unicache DSL if you need.
+
+* If you want to configure both class-level and key-level for a model, configure class-level first.
+
+* Unicache use hook to expire cache.
+  If someone update database by SQL directly (even Sequel APIs like `User.insert`, `user.delete` or `User.db.[]` won't be supported) or by another project without unicache, then cache in Memcache/Redis won't be expired automatically.
+  You must expire cache manually or by another mechanism.
+
+## Contributing
+
+1. Fork it ( https://github.com/bachue/sequel-unicache/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+
+desc 'Run all test cases'
+task :test do
+  root = File.expand_path __dir__
+  specs = "#{root}/spec"
+  spec_helper = root + '/spec/spec_helper'
+  exec 'bundle', 'exec', 'rspec', '-f', 'd',
+       '-I', root, '-r', spec_helper, '-b', '-c', specs
+end
+

data/lib/sequel/unicache.rb

@@ -0,0 +1,18 @@
+require 'sequel'
+require 'sequel/unicache/version'
+require 'sequel/unicache/global_configuration'
+require 'sequel/unicache/configuration'
+require 'sequel/unicache/finder'
+require 'sequel/unicache/expire'
+
+module Sequel
+  module Unicache
+    extend GlobalConfiguration::ClassMethods
+  end
+
+  class Model
+    extend Unicache::Configuration::ClassMethods
+    extend Unicache::Finder::ClassMethods
+    include Unicache::Expire::InstanceMethods
+  end
+end

data/lib/sequel/unicache/configuration.rb

@@ -0,0 +1,111 @@
+require 'sequel/unicache/global_configuration'
+require 'sequel/unicache/hook'
+require 'sequel/unicache/transaction'
+
+module Sequel
+  module Unicache
+    class Configuration < GlobalConfiguration
+      %i(if model_class unicache_keys).each do |attr|
+        define_method(attr) { @opts[attr] }
+        define_method("#{attr}=") { |val| @opts[attr] = val }
+      end
+
+      module ClassMethods
+      private
+        # Configure for specfied model
+        def unicache *args
+          opts = args.last.is_a?(Hash) ? args.pop : {}
+          Utils.initialize_unicache_for_class self unless @unicache_class_configuration # Initialize class first
+          if args.empty? # class-level configuration
+            config = Unicache.config.to_h.merge opts
+            @unicache_class_configuration = Configuration.new config.merge model_class: self
+          else           # key-level configuration
+            Utils.initialize_unicache_for_key self unless @unicache_key_configurations # Initialize key
+            key = Utils.normalize_key_for_unicache args
+            config = Unicache.config.to_h.merge @unicache_class_configuration.to_h.merge(opts)
+            config.merge! unicache_keys: key
+            @unicache_key_configurations[key] = Configuration.new config
+          end
+        end
+
+        def initialize_unicache
+          Utils.initialize_unicache_for_class self unless @unicache_class_configuration # Initialize class first
+          Utils.initialize_unicache_for_key self unless @unicache_key_configurations # Initialize key
+        end
+
+      public
+        # Read configuration for specified model
+        def unicache_for *key, fuzzy: false
+          initialize_unicache
+          if fuzzy
+            config = Utils.fuzzy_search_for key, @unicache_key_configurations
+          else
+            key = Utils.normalize_key_for_unicache key
+            config = @unicache_key_configurations[key]
+          end
+          config
+        end
+
+        def unicache_enabled_for? *key # config.enabled must be true, config.cache must be existed
+          if key.first.is_a?(Configuration)
+            config = key.first
+          else
+            config = unicache_for(*key)
+          end
+          config.cache && config.enabled if config
+        end
+
+        def unicache_class_configuration
+          initialize_unicache
+          @unicache_class_configuration
+        end
+
+        def unicache_configurations
+          initialize_unicache
+          @unicache_key_configurations
+        end
+
+        class Utils
+          class << self
+            def initialize_unicache_for_class model_class
+              model_class.instance_exec do
+                plugin :dirty
+                class_config = Unicache.config.to_h.merge model_class: model_class
+                @unicache_class_configuration = Configuration.new class_config
+              end
+              Hook.install_hooks_for_unicache
+              Transaction.install_hooks_for_unicache
+            end
+
+            def initialize_unicache_for_key model_class
+              model_class.instance_exec do
+                @unicache_key_configurations = {}
+                if primary_key
+                  pk_config = @unicache_class_configuration.to_h.merge unicache_keys: model_class.primary_key
+                  @unicache_key_configurations[primary_key] = Configuration.new pk_config
+                end
+              end
+            end
+
+            def normalize_key_for_unicache keys
+              keys.size == 1 ? keys.first.to_sym : keys.sort.map(&:to_sym)
+            end
+
+            # fuzzy search will always search for enabled config
+            def fuzzy_search_for keys, configs
+              _, result = configs.detect do |cache_key, config|
+                            match = if cache_key.is_a? Array
+                                      cache_key & keys == cache_key
+                                    else
+                                      keys.include? cache_key
+                                    end
+                            match & config.cache && config.enabled
+                          end
+              result
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/unicache/expire.rb

@@ -0,0 +1,19 @@
+require 'sequel/unicache/write'
+
+module Sequel
+  module Unicache
+    class Expire
+      module InstanceMethods # Provide instance methods for Sequel::Model, to expire cache
+        def refresh
+          model = super
+          Write.expire model if Unicache.enabled?
+          model
+        end
+
+        def expire_unicache
+          Write.expire self, force: true
+        end
+      end
+    end
+  end
+end

data/lib/sequel/unicache/finder.rb

@@ -0,0 +1,52 @@
+module Sequel
+  module Unicache
+    module Finder # Provide class methods for Sequel::Model, to find cache by unicache keys
+      module ClassMethods
+        def primary_key_lookup pk
+          if !Unicache.enabled? || Unicache.unicache_suspended? ||
+             dataset.joined_dataset? || !@fast_pk_lookup_sql
+            # If it's not a simple table, simple pk,
+            # assign this job to parent class, which will call first_where to do that
+            super
+          else
+            config = unicache_for primary_key # primary key is always unicache keys, no needs to fuzzy search
+            if unicache_enabled_for? config
+              find_with_cache({primary_key => pk}, config) { super }
+            else
+              super
+            end
+          end
+        end
+
+        def first_where hash
+          return primary_key_lookup hash unless hash.is_a? Hash
+          if Unicache.enabled? && !Unicache.unicache_suspended? && simple_table
+            config = unicache_for(*hash.keys, fuzzy: true) # need fuzzy search, this function always returns enabled config
+            if config
+              find_with_cache(hash, config) { super }
+            else
+              super
+            end
+          else
+            super
+          end
+        end
+
+      private
+
+        # Find from cache first, if failed, get fallback result from block
+        def find_with_cache hash, config
+          cache = config.cache.get config.key.(hash, config)
+          if cache
+            values = config.deserialize.(cache, config)
+            dataset.row_proc.call values
+          else
+            model = yield
+            Write.write model if model
+            model
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sequel/unicache/global_configuration.rb

@@ -0,0 +1,79 @@
+module Sequel
+  module Unicache
+    class GlobalConfiguration
+      def initialize opts = {}
+        @opts = default_config.merge opts
+      end
+
+      def set opts
+        @opts.merge! opts
+      end
+
+      def to_h
+        @opts
+      end
+
+      %i(cache ttl serialize deserialize key enabled logger).each do |attr|
+        define_method(attr) { @opts[attr] }
+        define_method("#{attr}=") { |val| @opts[attr] = val }
+      end
+
+    private
+
+      def default_config
+        { serialize: ->(values, _) { Marshal.dump values },
+          deserialize: ->(cache, _) { Marshal.load cache },
+          key: ->(hash, opts) {
+            cls  = opts.model_class.name
+            keys = hash.keys.sort.map {|key| [key, hash[key]] }.flatten.
+                                  map {|str| str.to_s.gsub(':', '\:') }.join(':')
+            "#{cls}:#{keys}"
+          },
+          enabled: true }
+      end
+
+      module ClassMethods
+        attr_reader :config
+
+        def self.extended base
+          base.instance_exec { @config = GlobalConfiguration.new }
+        end
+
+        def configure opts
+          @config.set opts
+        end
+
+        def enable
+          @disabled = false
+        end
+
+        def disable
+          @disabled = true
+        end
+
+        def enabled?
+          !@disabled
+        end
+
+        def unicache_suspended?
+          Thread.current[:unicache_suspended]
+        end
+
+        def suspend_unicache
+          if block_given?
+            origin, Thread.current[:unicache_suspended] = Thread.current[:unicache_suspended], true
+            yield
+          else
+            origin = true
+          end
+        ensure
+          Thread.current[:unicache_suspended] = origin
+        end
+
+        def unsuspend_unicache
+          Thread.current[:unicache_suspended] = false
+        end
+      end
+    end
+  end
+end