frivol 0.2.0 → 0.3.0

data/lib/frivol/class_methods.rb

@@ -0,0 +1,195 @@
+module Frivol
+  # == Frivol::ClassMethods
+  # These methods are available on the class level when Frivol is included in the class.
+  module ClassMethods
+    # Set the storage expiry time in seconds for the default bucket or the bucket passed.
+    def storage_expires_in(time, bucket = nil)
+      @frivol_storage_expiry ||= {}
+      @frivol_storage_expiry[bucket.to_s] = time
+    end
+
+    # Get the storage expiry time in seconds for the default bucket or the bucket passed.
+    def storage_expiry(bucket = nil)
+      @frivol_storage_expiry ||= {}
+      @frivol_storage_expiry.key?(bucket.to_s) ? @frivol_storage_expiry[bucket.to_s] : NEVER_EXPIRE
+    end
+
+    # Create a storage bucket.
+    # Frivol creates store_#{bucket} and retrieve_#{bucket} methods automatically.
+    # These methods work exactly like the default store and retrieve methods except that the bucket is
+    # stored in it's own key in Redis and can have it's own expiry time.
+    #
+    # Counters are special in that they do not store a hash but only a single integer value and also
+    # that the data in a counter is not cached for the lifespan of the object, but rather each call
+    # hits Redis. This is intended to make counters thread safe (for example you may have multiple
+    # workers working on a job and they can each increment a progress counter which would not work
+    # with the default retrieve/store method that normal buckets use). For this to actually be thread safe
+    # you need to pass the thread safe option to the config when you make the connection.
+    #
+    # In the case of a counter, the methods work slightly differently:
+    # - store_#{bucket} only takes an integer value to store (no key)
+    # - retrieve_#{bucket} only takes an integer default, and returns only the integer value
+    # - there is an added increment_#{bucket} method which increments the counter by 1
+    # - as well as increment_#{bucket}_by(value) method which increments the counter by the value
+    # - and similar decrement_#{bucket} and decrement_#{bucket}_by(value) methods
+    #
+    # Options are
+    # - <tt>:expires_in</tt> which sets the expiry time for a bucket;
+    # - <tt>:counter</tt> to create a special counter storage bucket;
+    # - <tt>:condition</tt> that must be satisfied before an action is taken on a bucket;
+    # - <tt>:else</tt>, which is an action that is performed if <tt>:condition</tt> is not satisfied
+    def storage_bucket(bucket, options = {})
+      time = options[:expires_in]
+      storage_expires_in(time, bucket) if !time.nil?
+
+      is_counter    = options[:counter]
+      seed_callback = options[:seed]
+
+
+      condition_block = Functor.new(options[:condition], true).compile
+      else_block      = Functor.new(options[:else]).compile
+
+      define_method :condition_evaluation do |*args, &block|
+        if instance_exec(*args, &condition_block)
+          block.call
+        else
+          instance_exec(*args, &else_block)
+        end
+      end
+
+      self.class_eval do
+        if is_counter
+          define_method "store_#{bucket}" do |value|
+            condition_evaluation("store_#{bucket}", value) do
+              Frivol::Helpers.store_counter(self, bucket, value)
+            end
+          end
+
+          define_method "retrieve_#{bucket}" do |default|
+            return_value = default
+            condition_evaluation("store_#{bucket}", default) do
+              return_value = Frivol::Helpers.retrieve_counter(self, bucket, default)
+            end
+            return_value
+          end
+
+          define_method "increment_#{bucket}" do
+            condition_evaluation("increment_#{bucket}") do
+              Frivol::Helpers.increment_counter(self, bucket, seed_callback)
+            end
+          end
+
+          define_method "increment_#{bucket}_by" do |amount|
+            condition_evaluation("increment_#{bucket}_by", amount) do
+              Frivol::Helpers.increment_counter_by(self, bucket, amount, seed_callback)
+            end
+          end
+
+          define_method "decrement_#{bucket}" do
+            Frivol::Helpers.decrement_counter(self, bucket, seed_callback)
+          end
+
+          define_method "decrement_#{bucket}_by" do |amount|
+            Frivol::Helpers.decrement_counter_by(self, bucket, amount, seed_callback)
+          end
+        else
+          define_method "store_#{bucket}" do |keys_and_values|
+            condition_evaluation("store_#{bucket}", keys_and_values) do
+              hash = Frivol::Helpers.retrieve_hash(self, bucket)
+              keys_and_values.each do |key, value|
+                hash[key.to_s] = value
+              end
+              Frivol::Helpers.store_hash(self, hash, bucket)
+            end
+          end
+
+          define_method "retrieve_#{bucket}" do |keys_and_defaults|
+            hash = {}
+            condition_evaluation("store_#{bucket}", keys_and_defaults) do
+              hash = Frivol::Helpers.retrieve_hash(self, bucket)
+            end
+
+            result = keys_and_defaults.map do |key, default|
+              hash[key.to_s] || (default.is_a?(Symbol) && respond_to?(default) && send(default)) || default
+            end
+            return result.first if result.size == 1
+            result
+          end
+        end
+
+        define_method "delete_#{bucket}" do
+          condition_evaluation("delete_#{bucket}") do
+            Frivol::Helpers.delete_hash(self, bucket)
+          end
+        end
+
+        define_method "clear_#{bucket}" do
+          condition_evaluation("clear_#{bucket}") do
+            Frivol::Helpers.clear_hash(self, bucket)
+          end
+        end
+      end
+
+      # Use Frivol to cache results for a method (similar to memoize).
+      # Options are :bucket which sets the bucket name for the storage,
+      # :expires_in which sets the expiry time for a bucket,
+      # and :counter to create a special counter storage bucket.
+      #
+      # If not :counter the key is the method_name.
+      #
+      # If you supply :expires_in you must also supply a :bucket otherwise
+      # it is ignored (and the default class expires_in is used if supplied).
+      #
+      # If :counter and no :bucket is provided the :bucket is set to the
+      # :bucket is set to the method_name (and so the :expires_in will be used).
+      def frivolize(method_name, options = {})
+        bucket        = options[:bucket]
+        time          = options[:expires_in]
+        is_counter    = options[:counter]
+        seed_callback = options[:seed]
+
+        bucket = method_name if bucket.nil? && is_counter
+        frivolized_method_name = "frivolized_#{method_name}"
+
+        self.class_eval do
+          alias_method frivolized_method_name, method_name
+          unless bucket.nil?
+            storage_bucket(bucket, {
+              :expires_in => time,
+              :counter    => is_counter,
+              :seed       => seed_callback })
+          end
+
+          if is_counter
+            define_method method_name do
+              value = send "retrieve_#{bucket}", -2147483647 # A rediculously small number that is unlikely to be used: -2**31 + 1
+              if value == -2147483647
+                value = send frivolized_method_name
+                send "store_#{bucket}", value
+              end
+              value
+            end
+          elsif !bucket.nil?
+            define_method method_name do
+              value = send "retrieve_#{bucket}", { method_name => false }
+              if !value
+                value = send frivolized_method_name
+                send "store_#{bucket}", { method_name => value }
+              end
+              value
+            end
+          else
+            define_method method_name do
+              value = retrieve method_name => false
+              if !value
+                value = send frivolized_method_name
+                store method_name.to_sym => value
+              end
+              value
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/frivol/config.rb

@@ -0,0 +1,39 @@
+module Frivol
+  # == Frivol::Config
+  # Sets the Frivol configuration (currently only the Redis config), allows access to the configured Redis instance,
+  # and has a helper method to include Frivol in a class with an optional storage expiry parameter
+  module Config
+    # Set the Redis configuration.
+    #
+    # Expects a hash such as
+    #   REDIS_CONFIG = {
+    #     :host => "localhost",
+    #     :port => 6379
+    #   }
+    #   Frivol::Config.redis_config = REDIS_CONFIG
+    def self.redis_config=(config)
+      @@redis_config = config
+      Thread.current[:frivol_redis] = nil
+    end
+
+    # Returns the configured Redis instance
+    def self.redis
+      Thread.current[:frivol_redis] ||= Redis.new(@@redis_config)
+    end
+
+    def self.allow_json_create
+      @@allow_json_create ||= []
+    end
+
+    # A convenience method to include Frivol in a class, with an optional storage expiry parameter.
+    #
+    # For example, you might have the following in environment.rb:
+    #   Frivol::Config.redis_config = REDIS_CONFIG
+    #   Frivol::Config.include_in ActiveRecord::Base, 600
+    # Which would include Frivol in ActiveRecord::Base and set the default storage expiry to 10 minutes
+    def self.include_in(host_class, storage_expires_in = nil)
+      host_class.send(:include, Frivol)
+      host_class.storage_expires_in storage_expires_in if storage_expires_in
+    end
+  end
+end

data/lib/frivol/functor.rb

@@ -0,0 +1,37 @@
+module Frivol
+  # == Frivol::Functor
+  # Compiles proc, symbols, false, true into a proc that executes within a scope,
+  # or on an object.
+  class Functor
+    # Create a new functor which takes:
+    # method: can be a proc, symbol, false or true
+    # default: the value which is returned from the compiled proc if method is
+    #          not a proc, symbol, false or true. Defaults to nil
+    def initialize(method, default=nil)
+      @method  = method
+      @default = default
+    end
+
+    # returns a compiled proc based on the initialization arguments
+    def compile
+      case @method
+      when Proc
+        method = @method
+        proc do |*args|
+          args.unshift(self)
+          method.call(*args)
+        end
+      when Symbol
+        method = @method
+        proc do |*args|
+          self.send(method, *args)
+        end
+      when FalseClass, TrueClass
+        proc{ @method }
+      else
+        default_return = @default
+        proc{ default_return }
+      end
+    end
+  end
+end

data/lib/frivol/helpers.rb

@@ -0,0 +1,133 @@
+module Frivol
+  module Helpers #:nodoc:
+    require 'multi_json'
+
+    def self.dump_json(hash)
+      MultiJson.dump(hash)
+    end
+
+    def self.load_json(json)
+      hash = MultiJson.load(json)
+      return hash if Frivol::Config.allow_json_create.empty?
+      hash.each do |k,v|
+        if v.is_a?(Hash) && v['json_class']
+          klass = constantize(v['json_class'])
+          hash[k] = klass.send(:json_create, v) if Frivol::Config.allow_json_create.include?(klass)
+        end
+      end
+    end
+
+    def self.constantize(const)
+      unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ const
+        raise NameError, "#{const.inspect} is not a valid constant name!"
+      end
+      Object.module_eval("::#{$1}", __FILE__, __LINE__)
+    end
+
+
+    def self.store_hash(instance, hash, bucket = nil)
+      data, is_new = get_data_and_is_new instance
+      data[bucket.to_s] = hash
+
+      store_value instance, is_new[bucket.to_s], dump_json(hash), bucket
+
+      self.set_data_and_is_new instance, data, is_new
+    end
+
+    def self.store_value(instance, is_new, value, bucket = nil)
+      key = instance.send(:storage_key, bucket)
+      time = instance.class.storage_expiry(bucket)
+      if time == Frivol::NEVER_EXPIRE
+        Frivol::Config.redis[key] = value
+      else
+        Frivol::Config.redis.multi do |redis|
+          # TODO: write test for the to_i bug fix
+          time = redis.ttl(key).to_i unless is_new
+          redis[key] = value
+          redis.expire(key, time)
+        end
+      end
+    end
+
+    def self.retrieve_hash(instance, bucket = nil)
+      data, is_new = get_data_and_is_new instance
+      return data[bucket.to_s] if data.key?(bucket.to_s)
+      key = instance.send(:storage_key, bucket)
+      json = Frivol::Config.redis[key]
+
+      is_new[bucket.to_s] = json.nil?
+
+      hash = json.nil? ? {} : load_json(json)
+      data[bucket.to_s] = hash
+
+      self.set_data_and_is_new instance, data, is_new
+      hash
+    end
+
+    def self.delete_hash(instance, bucket = nil)
+      key = instance.send(:storage_key, bucket)
+      Frivol::Config.redis.del key
+      clear_hash(instance, bucket)
+    end
+
+    def self.clear_hash(instance, bucket = nil)
+      key = instance.send(:storage_key, bucket)
+      data = instance.instance_variable_defined?(:@frivol_data) ? instance.instance_variable_get(:@frivol_data) : {}
+      data.delete(bucket.to_s)
+      instance.instance_variable_set :@frivol_data, data
+    end
+
+    def self.get_data_and_is_new(instance)
+      data = instance.instance_variable_defined?(:@frivol_data) ? instance.instance_variable_get(:@frivol_data) : {}
+      is_new = instance.instance_variable_defined?(:@frivol_is_new) ? instance.instance_variable_get(:@frivol_is_new) : {}
+      [data, is_new]
+    end
+
+    def self.set_data_and_is_new(instance, data, is_new)
+      instance.instance_variable_set :@frivol_data, data
+      instance.instance_variable_set :@frivol_is_new, is_new
+    end
+
+    def self.store_counter(instance, counter, value)
+      key = instance.send(:storage_key, counter)
+      is_new = !Frivol::Config.redis.exists(key)
+      store_value instance, is_new, value, counter
+    end
+
+    def self.retrieve_counter(instance, counter, default)
+      key = instance.send(:storage_key, counter)
+      (Frivol::Config.redis[key] || default).to_i
+    end
+
+    def self.increment_counter(instance, counter, seed_callback=nil)
+      key = instance.send(:storage_key, counter)
+      store_counter_seed_value(key, instance, counter, seed_callback)
+      Frivol::Config.redis.incr(key)
+    end
+
+    def self.increment_counter_by(instance, counter, amount, seed_callback=nil)
+      key = instance.send(:storage_key, counter)
+      store_counter_seed_value(key, instance, counter, seed_callback)
+      Frivol::Config.redis.incrby(key, amount)
+    end
+
+    def self.decrement_counter(instance, counter, seed_callback=nil)
+      key = instance.send(:storage_key, counter)
+      store_counter_seed_value(key, instance, counter, seed_callback)
+      Frivol::Config.redis.decr(key)
+    end
+
+    def self.decrement_counter_by(instance, counter, amount, seed_callback=nil)
+      key = instance.send(:storage_key, counter)
+      store_counter_seed_value(key, instance, counter, seed_callback)
+      Frivol::Config.redis.decrby(key, amount)
+    end
+
+    def self.store_counter_seed_value(key, instance, counter, seed_callback)
+      unless Frivol::Config.redis.exists(key) || seed_callback.nil?
+        store_counter( instance, counter, seed_callback.call(instance))
+      end
+    end
+    private_class_method :store_counter_seed_value
+  end
+end

data/lib/frivol/time_extensions.rb

@@ -0,0 +1,45 @@
+require 'time'
+
+# == Time
+# An extension to the <tt>Time</tt> class which allows instances to be
+# serialized by <tt>MultiJson#dump</tt> and deserialized by
+# <tt>MultiJson#load</tt>.
+class Time
+  # Serialize to JSON
+  def to_json(*a)
+    MultiJson.dump(
+      'json_class'   => self.class.name,
+      'data'         => self.to_s
+    )
+  end
+
+  # Deserialize from JSON
+  def self.json_create(o)
+    Time.parse(*o['data'])
+  end
+end
+
+Frivol::Config.allow_json_create << Time
+
+begin
+  # == ActiveSupport::TimeWithZone
+  # An extension to the <tt>ActiveSupport::TimeWithZone</tt> class which allows
+  # instances to be serialized by <tt>MultiJson#dump</tt> and deserialized by
+  # <tt>MultiJson#load</tt>.
+  class ActiveSupport::TimeWithZone
+    # Serialize to JSON
+    def to_json(*a)
+      MultiJson.dump(
+        'json_class'   => self.class.name,
+        'data'         => self.to_s
+      )
+    end
+
+    # Deserialize from JSON
+    def self.json_create(o)
+      Time.zone.parse(*o['data'])
+    end
+  end
+
+  Frivol::Config.allow_json_create << ActiveSupport::TimeWithZone
+rescue; end