fastaccess 0.0.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+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,137 @@
+# fastaccess - redisfast access on generated content
+
+Many web applications which provide textual content to the user
+have much more reads than writes. This can mean, that on
+every 10k reads there is one write (see some popular
+blogs or newspages). 
+
+Often this content is generated, because the input source
+is some markup format, like markdown. This means, that
+there is always the need to generate this content into
+html. 
+
+And this is why fastaccess exists. 
+It modifies any given method, which generates content,
+and stores it in a [redis][1] database.
+If this content solely depends on a model attribute,
+for example like the *body* in a blog post, it will
+be auto updated, if the underlying model attribute
+changes. Otherwise you can trigger the update manually.
+
+Now lets see how this works:
+
+## Using fastaccess
+
+First, of course, you'll need to include this gem in your
+projects *Gemfile*.
+
+Since this gem utilizes redis, make sure that this is installed
+and generate the default initializer with
+
+    rails generate fastaccess:initialize
+
+This will create a file in *config/initializers/fastaccess.rb* which
+will create an instance of a redis database-connection. If you already
+have one of those, feel free to replace the new instance with your version.
+
+Now, in your project you will have to use the gem-provided
+`acts_with_fastaccess_on` method to mark certain methods
+as registered with fastaccess for caching.
+
+```ruby
+class Post < ActiveRecord::Base
+  attr_accessible :title, :body
+  acts_with_fastaccess_on :markdown_body
+
+  def markdown_body
+    markdown(self.body)
+  end
+end
+```
+
+In this example a Model named *Post* is defined which has title and
+body attributes. The `markdown_body` method converts the markdown-body to
+html. Since this is needed often, it cached via redis.
+
+The previous example utilizes a method, which operates on one of the models
+attributes. So the redis-content will be updated if the pertaining Model
+instance is updated. But what if you have a method which uses more input
+than just specific attributes, which will update the models timestamp?
+
+For this case there is an explicit update method, which allows you
+to trigger an update.
+
+```ruby
+# app/models/post.rb
+class Post < ActiveRecord::Base
+  attr_accessible :title, :body, :tags
+  has_many :tags
+  acts_with_fastaccess_on :tag_list
+  include Fastaccess::Mixins
+  
+  def tag_list
+    self.tags.map(&name)
+  end
+end
+
+# app/controllers/posts_controller.rb
+class PostsController < ApplicationController
+  def update
+    @post = Post.find_by_id(params[:id])
+    @post.update_on :tag_list
+    respond_to do |format|
+      if @post.update_attributes(params[:post])
+        format.html { redirect_to @post, notice: 'Post was successfully updated.' }
+        format.json { head :no_content }
+      else
+        format.html { render action: "edit" }
+        format.json { render json: @post.errors, status: :unprocessable_entity }
+      end 
+  end
+end
+```
+
+If you don't want to *pollute* your model with these mixin-methods you
+can also call 
+
+```ruby
+Fastaccess::Fastaccess.update_content @post, :on => :tag_list, :arguments => []
+```
+
+## Features
+
+### planned features
+
+- ~~disable auto-update via option setting (planned for *0.0.2*)~~ *implemented*
+- more update flexibility
+  - e.g. custom update-constraints instead of calling `update_content` manually
+
+## License
+
+([The MIT License][mit])
+
+Copyright © 2013:
+
+- [Tim Reddehase][1]
+
+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.
+
+[mit]: http://opensource.org/licenses/MIT
+[1]: http://rightsrestricted.com

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Fastaccess'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/fastaccess.rb

@@ -0,0 +1,13 @@
+require 'redis'
+require 'fastaccess/fastaccess.rb'
+require 'fastaccess/mixins.rb'
+require 'fastaccess/acts_with_fastaccess_on'
+
+module Fastaccess
+
+  # convenience method to setup fastaccess
+  def self.setup(&block)
+    Fastaccess.setup &block
+  end
+
+end

data/lib/fastaccess/acts_with_fastaccess_on.rb

@@ -0,0 +1,54 @@
+module Fastaccess
+  module ActsWithFastaccessOn
+    extend ActiveSupport::Concern
+ 
+    included do
+    end
+ 
+    module ClassMethods
+      # registers the pertaining method as one, which return value
+      # is provided through redis.
+      # This is for fast access of otherwise generated content
+      # with a high reading/writing ratio.
+      #
+      # @param [Symbol] method_name denoting the pertaining method
+      #                 this method shouldn't be defined beforehand.
+      # @param [Hash] options is basic options hash. 
+      #               currently has no effect on execution.
+      def acts_with_fastaccess_on(method_name, options = {})
+        Fastaccess.register_on self, method_name, options
+        # options = Fastaccess.merge_defaults(options)
+        define_singleton_method :method_added do |on_method|
+          if Fastaccess.registered? self, on_method
+            method = on_method
+            alias_name = Fastaccess.alias_for method
+            if !method_defined?(alias_name)
+              alias_method alias_name, method 
+              define_method method do |*args|
+                fastaccess_id = Fastaccess.id_for(self)
+                redis_id = "#{method}_#{fastaccess_id}"
+                opts = Fastaccess.options_for(self, method)
+                content_current = opts[:auto_update] ? Fastaccess.update_check(self) : true
+                if Fastaccess.redis.exists(redis_id) && content_current
+                  response = Fastaccess.redis.get(redis_id)
+                  begin
+                    return JSON.parse response
+                  rescue JSON::ParserError
+                    return response
+                  end
+                else
+                  response = method(alias_name).call(*args)
+                  Fastaccess.update_info self
+                  Fastaccess.redis.set(redis_id, (response.is_a? String) ? response : response.to_json)
+                  return response
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Fastaccess::ActsWithFastaccessOn

data/lib/fastaccess/fastaccess.rb

@@ -0,0 +1,204 @@
+require 'set'
+
+module Fastaccess
+  # This class contains the most
+  # relevant helpers methods, which
+  # doesn't need to be located elsewhere.
+  # (e.g. like mixins)
+  class Fastaccess
+
+    # the default options for the
+    # acts_with_fastaccess_on method.
+    ACTS_OPTIONS_DEFAULTS = {
+      :auto_update => true
+    }
+
+    @@fastaccess_on = Hash.new Set.new
+    @@last_updated  = Hash.new
+    @@registered_options = Hash.new ACTS_OPTIONS_DEFAULTS
+
+    # accessor for the actual registration hash.
+    cattr_accessor :fastaccess_on
+
+    # hash for monitoring updates on registered objects.
+    cattr_accessor :last_updated
+
+    # hash for options of registered methods
+    cattr_accessor :registered_options
+
+    # registers a method, defined on a certain class,
+    # as being handled by fastaccess.
+    # @param [Class] class_name is the actual Class.
+    # @param [Symbol] method_name is the symbol
+    #                 denoting the actual method
+    def self.register_on(class_name, method_name, options={})
+      self.fastaccess_on[class_name] << method_name
+      id = options_id_for(class_name, method_name)
+      self.registered_options[id] = self.registered_options[id].merge(options)
+    end
+
+    # inquires if a certain method, which is
+    # defined on a given class, is registered
+    # with fastaccess.
+    # @param [Class] class_name is the actual Class.
+    # @param [Symbol] method_name is the symbol
+    #                 denoting the actual method
+    def self.registered?(class_name, method_name)
+      self.fastaccess_on[class_name].include? method_name
+    end
+
+    # gets the options for a class_name, method_name
+    # pair
+    # @param [Class] class_name is the actual Class.
+    # @param [Symbol] method_name is the symbol
+    #                 denoting the actual method
+    # @return [Hash] the options for the pair
+    def self.options_for(class_name, method_name)
+      id = options_id_for(class_name, method_name)
+      self.registered_options[id]
+    end
+
+    # checks if a class_instance seems to be
+    # up to date according to updated_at timestamp.
+    # This only works if the registered method 
+    # is actually dependent (and only dependent)
+    # on model attributes.
+    # @param [Object] class_instance any Object,
+    #                 preferably a decendent of
+    #                 an actual Rails Model.
+    # @return [Boolean] is true if everything is up to date.
+    def self.update_check(class_instance)
+      id = self.id_for(class_instance)
+      return true if self.last_updated[id] == false
+      class_instance.updated_at == self.last_updated[id]
+    end
+    
+    # updates the timestamp in the redis
+    # database with the one from class_instance.
+    # usually called after there was new content
+    # pushed into redis (or content was updated)
+    # @param [Object] class_instance any Object,
+    #                 preferably a decendent of
+    #                 an actual Rails Model.
+    def self.update_info(class_instance)
+      id = self.id_for(class_instance)
+      unless self.last_updated[id] == false
+        self.last_updated[id] = class_instance.updated_at
+      end
+    end
+
+    # creates a fastaccess id for a class_instance
+    # @param [Object] class_instance any Object,
+    #                 preferably a decendent of
+    #                 an actual Rails Model.
+    # @return [String] the identifier
+    def self.id_for(class_instance)
+      "#{class_instance.class}-#{class_instance.id}"
+    end
+
+    # creates the id for the registered_options hash
+    # @param [Class] class_name a class singleton object
+    # @param [Symbol] method_name is the identifying symbol of a method
+    # @return [String] the identifier
+    def self.options_id_for(class_name, method_name)
+      "#{class_name}-#{method_name}"
+    end
+
+    # returns the aliased name for
+    # any given method. 
+    # @param [Symbol] method a symbol denoting the method.
+    # @return [Symbol] aliased method symbol.
+    def self.alias_for(method)
+      :"aliased_#{method}"
+    end
+
+    # setting content in redis
+    # @param [String] redis_id the id
+    # @param [Object] content should be basic content
+    #                 e.g. String, Hash, Array or Numbers.
+    def self.set(redis_id, content)
+      redis.set(redis_id, (content.is_a? String) ? content : content.to_json)
+    end
+
+    # getting redis content
+    # @param [String] redis_id the id
+    # @return [Object] stored content
+    def self.get(redis_id)
+      response = redis.get(redis_id)
+      begin
+        return JSON.parse response
+      rescue JSON::ParserError
+        return response
+      end
+    end
+
+    # manually update content in redis
+    # for a given object.
+    # @param [Object] obj any Object,
+    #                 preferably a decendent of
+    #                 an actual Rails Model.
+    # @param [Hash] options a simple hash
+    # @option options [Symbol] :on a certain registered
+    #                          method.
+    # @option options [Array] :arguments an array of
+    #                         arguments passed to
+    #                         the :on method or, if
+    #                         :on is not present, every
+    #                         method registered with fastaccess
+    #                         on the pertaining class.
+    def self.update_content(obj, options={})
+      class_name = obj.is_a?(Class) ? obj : obj.class
+      methods = if method = options[:on]
+        if registered? class_name, method
+          [method]
+        else
+          []
+        end
+      else
+        fastaccess_on[class_name]
+      end
+      methods.each do |method|
+        callable = obj.method( alias_for(method) )
+        content = if options[:arguments]
+                    callable.call(*options[:arguments])
+                  else
+                    callable.call
+                  end
+        self.set("#{method}_#{id_for(obj)}", content)
+      end
+    end
+
+    # setting up the environment for fastaccess 
+    def self.setup(&block)
+      instance_eval &block if block_given?
+    end
+
+    # setting the global redis instance for fastaccess.
+    # @param [Redis] redis_instance The Connection to a redis server
+    def self.set_redis(redis_instance)
+      if redis_instance
+        @@redis = redis_instance 
+      else
+        @@redis = $redis if $redis
+      end
+    end
+
+    # getting the redis instance 
+    # @return [Redis] the instance
+    def self.redis
+      @@redis
+    end
+
+    # merges the, hopefully, reasonable
+    # defaults with the supplied options
+    # hash
+    # @param [Hash] options the pertaining options
+    #               supplied by the user
+    # @return [Hash] the merged options hash
+    def self.merge_defaults(options)
+      ACTS_OPTIONS_DEFAULTS.merge(options)
+    end
+
+  end
+
+end