redcrumbs 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+*.gem
+.DS_Store
+.bundle
+Gemfile.lock
+pkg/*

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in redcrumbs.gemspec
+gemspec

data/README.md

@@ -0,0 +1,159 @@
+# Redcrumbs
+
+Fast and unobtrusive activity tracking of ActiveRecord models using Redis and DataMapper.
+
+Redcrumbs is designed for high-traffic applications that need to track changes to their tables without making additional writes to the database. It is especially useful where the saved history needs to be expired over time and is not mission critical data. The emphasis is on reducing response times and easing the load on your main database.
+
+User context is built in and fully customisable and this makes Redcrumbs particularly useful for reporting relevant activity to users as it happens in your app.
+
+Redcrumbs is used for the 'News' feature in Project Zebra games but could also be used as the basis of a fast versioning or reporting system.
+
+For a more complete versioning system see the excellent [vestal_versions](https://github.com/laserlemon/vestal_versions) gem.
+
+Please note, this is early stage stuff. We're not using it in production just yet.
+
+## Installation
+
+Assuming you've got Redis installed and running on your system just add this to your Gemfile:
+
+```
+gem 'redcrumbs'
+```
+
+Then run the generator to create the initializer file. No migrations necessary!
+
+```
+$ rails g redcrumbs:install
+```
+
+Done! Look in `config/initializers/redcrumbs.rb` for customisation options.
+
+## Example
+
+Start tracking a model by adding `redcrumbed` to the class:
+
+```
+class Venue < ActiveRecord::Base
+  redcrumbed :only => [:name, :latlng]
+  
+  validates :name, :presence => true
+  validates :latlng, :uniqueness => true
+end
+```
+
+And that's pretty much it! Now you can do this:
+
+```
+> venue = Venue.last
+=> #<Venue id: 1, name: "Belfast City Hall" ... >
+
+> venue.update_attributes(:name => "City Hall, Belfast")
+=> #<Venue id: 1, name: "City Hall, Belfast" ... >
+
+> venue.crumbs
+=> [#<Crumb id: 34 ... >, #<Crumb id: 42 ... >, #<Crumb id: 53 ... >]
+
+> crumb = venue.crumbs.last
+=> #<Crumb id: 53 ... >
+
+> crumb.modifications
+=> {"name" => ["Belfast City Hall", "City Hall, Belfast"]}
+
+> crumb.subject
+=> #<Venue id: 1, name: "City Hall, Belfast" ... >
+
+```
+
+Not too shabby. But crumbs can also track the user that made the change (creator), and even a secondary user affected by the change (target). By default the creator is considered to be the user associated with the object:
+
+```
+> user = User.find(2)
+=> #<User id: 2, name: "Jon" ... >
+
+> venue = user.venues.last
+=> #<Venue id: 1, name: "City Hall, Belfast", user_id: 2 ... >
+
+> venue.update_attributes(:name => "Halla na Cathrach, Bhéal Feirste")
+=> #<Venue id: 1, name: "Halla na Cathrach, Bhéal Feirste", user_id: 2 ... >
+
+> crumb = venue.crumbs.last
+=> #<Crumb id: 54 ... >
+
+> crumb.modifications
+=> {"name" => ["City Hall, Belfast", "Halla na Cathrach, Bhéal Feirste"]}
+
+> crumb.creator
+=> #<User id: 2, name: "Jon" ... >
+
+# and really cool, returns a limited (default 100) array of crumbs affecting a user in reverse order:
+> user.crumbs(:limit => 20)
+=> [#<Crumb id: 64 ... >, #<Crumb id: 53 ... >, #<Crumb id: 42 ... > ... ]
+
+# or if you just want the crumbs created by the user
+> user.crumbs_by
+
+# or affecting the user
+> user.crumbs_for
+
+```
+
+You can customise just what should be considered a creator or target globally across your app by editing a few lines in the redcrumbs initializer. Or you can override the creator and target methods if you want class-specific control:
+
+```
+class User < ActiveRecord::Base
+  belongs_to :alliance
+  has_many :venues
+end
+
+class Venue < ActiveRecord::Base
+  redcrumbed :only => [:name, :latlng]
+  
+  belongs_to :user
+  
+  validates :name, :presence => true
+  validates :latlng, :uniqueness => true
+  
+  def creator
+    user.alliance
+  end
+end
+```
+
+## Conditional control
+
+You can pass `:if` and `:unless` options to the redcrumbed method to control when an action should be tracked in the same way you would for an ActiveRecord callback. For example:
+
+```
+class Venue < ActiveRecord::Base
+  redcrumbed :only => [:name, :latlng], :if => :has_user?
+  
+  def has_user?
+    !!user_id
+  end
+end
+```
+
+## Attribute storage
+
+It's not best practice but since the emphasis is on easing the load on our main database we have bent a few rules in order to reduce the calls on the database to, ideally, zero. In any given app you may be tracking several models and this results in a lot of SQL we could do without.
+
+`redcrumbed` accepts a `:store` option to which you can pass an array of attributes of the subject that you'd like to store on the crumb object itself. Use it sparingly if you know that, for example, you are only ever going to really use a couple of attributes of the subject and you want to avoid loading the whole thing from the database.
+
+```
+class Venue
+  redcrumbed :only => [:name, :latlng], :store => [:id, :name]
+end
+```
+
+So now if you call `crumb.subject` instead of loading the Venue from your database it will instantiate a new Venue with the same `id` and `name` attributes. You can always retrieve the original by calling `crumb.full_subject`.
+
+As you might expect, you can also do this for the creator and target of the crumb. See the redcrumbs.rb initializer for how to set this as a global configuration.
+
+
+## To-do
+
+Lots of refactoring, tests and new features.
+
+## License
+
+Created by John Hope (c) 2012 for Project Zebra. Released under MIT License (http://www.opensource.org/licenses/mit-license.php).

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/app/models/redcrumbs/crumb/expiry.rb

@@ -0,0 +1,23 @@
+module Redcrumbs
+  module Crumb::Expiry
+    extend ActiveSupport::Concern
+    
+    def mortal?
+      !!Redcrumbs.mortality
+    end
+
+    def expire_at
+      Time.now + Redcrumbs.mortality
+    end
+    
+    def time_to_live
+      REDIS.ttl(redis_key) if mortal?
+    end
+    
+    private
+    
+    def set_mortality
+      REDIS.expireat(redis_key, expire_at.to_i) if mortal?
+    end
+  end
+end

data/app/models/redcrumbs/crumb/getters.rb

@@ -0,0 +1,55 @@
+module Redcrumbs
+  module Crumb::Getters
+    extend ActiveSupport::Concern
+    
+    def subject
+      if !self.stored_subject.blank?
+        subject_from_storage
+      elsif subject_type && subject_id
+        self._subject ||= full_subject
+      end
+    end
+
+    def full_subject
+      subject_type.classify.constantize.find(subject_id)
+    end
+    
+    def subject_from_storage
+      new_subject = subject_type.constantize.new(self.stored_subject)
+      new_subject.id = self.stored_subject["id"] if self.stored_subject.has_key?("id")
+      new_subject
+    end
+    
+    def creator
+      if !self.stored_creator.blank?
+        creator_class.new(self.stored_creator)
+      elsif !self.creator_id.blank?
+        self._creator ||= full_creator
+      end
+    end
+    
+    def creator_class
+      Redcrumbs.creator_class_sym.to_s.classify.constantize
+    end
+    
+    def full_creator
+      creator_class.where(Redcrumbs.creator_primary_key => self.creator_id).first
+    end
+    
+    def target
+      if !self.stored_target.blank?
+        target_class.new(self.stored_target)
+      elsif !self.target_id.blank?
+        self._target ||= full_target
+      end
+    end
+    
+    def target_class
+      Redcrumbs.target_class_sym.to_s.classify.constantize
+    end
+
+    def full_target
+      target_class.where(Redcrumbs.target_primary_key => self.creator_id).first
+    end
+  end
+end

data/app/models/redcrumbs/crumb/setters.rb

@@ -0,0 +1,25 @@
+module Redcrumbs
+  module Crumb::Setters
+    extend ActiveSupport::Concern
+    
+    def subject=(subject)
+      self.stored_subject = subject.storeable_attributes
+      self.subject_type = subject.class.to_s
+      self.subject_id = subject.id
+    end
+
+    def creator=(creator)
+      unless !creator
+        self.stored_creator = creator.attributes.select {|attribute| Redcrumbs.store_creator_attributes.include?(attribute.to_sym)}
+        self.creator_id = creator[Redcrumbs.creator_primary_key]
+      end
+    end
+
+    def target=(target)
+      unless !target
+        self.stored_target = target.attributes.select {|attribute| Redcrumbs.store_target_attributes.include?(attribute.to_sym)}
+        self.target_id = target[Redcrumbs.target_primary_key]
+      end
+    end
+  end
+end

data/app/models/redcrumbs/crumb.rb

@@ -0,0 +1,64 @@
+require 'dm-core'
+require 'dm-types'
+require 'dm-timestamps'
+require 'dm-redis-adapter'
+
+## Note to self: Syntax to grab all by an attribute is - Notification.all(:subject_type => "User")
+## The attribute must be indexed as with subject_type below
+
+module Redcrumbs
+  class Crumb
+    REDIS = Redis.new
+    
+    include DataMapper::Resource
+    include Crumb::Getters
+    include Crumb::Setters
+    include Crumb::Expiry
+    
+    DataMapper.setup(:default, {:adapter  => "redis"})
+    
+    property :id, Serial
+    property :subject_id, Integer, :index => true
+    property :subject_type, String, :index => true
+    property :modifications, Json, :default => "{}"
+    property :created_at, DateTime
+    property :updated_at, DateTime
+    property :stored_creator, Json
+    property :stored_target, Json
+    property :stored_subject, Json
+    property :creator_id, Integer, :index => true
+    property :target_id, Integer, :index => true
+
+    DataMapper.finalize
+
+    after :save, :set_mortality
+
+    attr_accessor :_subject, :_creator, :_target
+
+    def initialize(params = {})
+      if self.subject = params[:subject]
+        self.target = self.subject.target if self.subject.respond_to?(:target)
+        self.creator = self.subject.creator if self.subject.respond_to?(:creator)
+      end
+      self.modifications = params[:modifications] unless !params[:modifications]
+    end
+
+    # Remember to change the respond_to? argument when moving from user/target class to dynamic with user as default
+    def self.build_from(subject)
+      unless subject.watched_changes.empty?
+        params = {:modifications => subject.watched_changes}
+        params.merge!({:subject => subject})
+        new(params)
+      end
+    end
+    
+    def redis_key
+      "redcrumbs_crumbs:#{id}"
+    end
+
+    # Designed to mimic ActiveRecord's count. Probably not performant and only should be used for tests really
+    def self.count
+      REDIS.keys("redcrumbs_crumbs:*").size - 8
+    end
+  end
+end

data/lib/generators/redcrumbs/install_generator.rb

@@ -0,0 +1,12 @@
+module Redcrumbs
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("../templates", __FILE__)
+
+      # all public methods in here will be run in order
+      def add_redcrumbs_initializer
+        template "initializer.rb", "config/initializers/redcrumbs.rb"
+      end
+    end
+  end
+end

data/lib/generators/redcrumbs/templates/initializer.rb

@@ -0,0 +1,21 @@
+Redcrumbs.setup do |config|
+  # When a change is made to a redcrumbed model the user associated with that model will
+  # automatically be stored on the Crumb object. By default Redcrumbs will look for a User
+  # object using 'id' as the primary key but you can override that here.
+  #
+  # config.creator_class_sym = :user
+  # config.creator_primary_key = 'id'
+  # config.target_class_sym = :user
+  # config.target_primary_key = 'id'
+  #
+  #
+  # If you're using the crumbs to report news back to a user you can store creator and target 
+  # attributes on the crumb object to avoid having to touch your main database at all. Keep it 
+  # sensible and evaluate whether the additional space used in Redis is really worth the time saving.
+  #
+  # config.store_creator_attributes = [:id, :name, :email]
+  #
+  #
+  # Set the mortality to make crumbs automatically expire in time. Default is infinity.
+  # config.mortality = 30.days
+end

data/lib/redcrumbs/config.rb

@@ -0,0 +1,19 @@
+module Redcrumbs
+  mattr_accessor :creator_class_sym
+  mattr_accessor :creator_primary_key
+  mattr_accessor :target_class_sym
+  mattr_accessor :target_primary_key
+
+  mattr_accessor :store_creator_attributes
+  mattr_accessor :store_target_attributes
+
+  mattr_accessor :mortality
+  
+  @@creator_class_sym ||= :user
+  @@creator_primary_key ||= 'id'
+  @@target_class_sym ||= :user
+  @@target_primary_key ||= 'id'
+  
+  @@store_creator_attributes ||= []
+  @@store_target_attributes ||= []
+end

data/lib/redcrumbs/creation.rb

@@ -0,0 +1,31 @@
+module Redcrumbs
+  module Creation
+    extend ActiveSupport::Concern
+    
+    module InstanceMethods
+      def crumbs
+        Crumb.all(:subject_type => self.class.to_s, :subject_id => self.id)
+      end
+
+      def watched_changes
+        changes.reject {|k,v| !self.class.redcrumbs_options[:only].include?(k.to_sym)}
+      end
+
+      def storeable_attributes
+        attributes.reject {|k,v| !self.class.redcrumbs_options[:store].include?(k.to_sym)}
+      end
+
+      def watched_changes_empty?
+        watched_changes.empty?
+      end
+
+      def notify_changes
+        unless watched_changes.empty?
+          n = Crumb.build_from(self)
+          n.save
+        end
+        yield
+      end
+    end
+  end
+end

data/lib/redcrumbs/engine.rb

@@ -0,0 +1,8 @@
+require "rails/engine"
+require "redcrumbs"
+
+module Redcrumbs
+  class Engine < Rails::Engine
+    # Nothing to see here. Consider moving the Crumb model from engine into lib in the future.
+  end
+end

data/lib/redcrumbs/options.rb

@@ -0,0 +1,27 @@
+module Redcrumbs
+ module Options
+    extend ActiveSupport::Concern
+    
+    module ClassMethods
+      # prepare_redcrumbed_options prepares class level options that customise the behaviour of
+      # redcrumbed. See documentation for a full explanation of redcrumbed options.
+      def prepare_redcrumbed_options(options)
+        defaults = {
+          :only => [],
+          :store => []
+        }
+        
+        options.reverse_merge!(defaults)
+        
+        options[:only] = Array(options[:only])
+        options[:store] = Array(options[:store])
+        
+        class_inheritable_accessor :redcrumbs_options
+        class_inheritable_accessor :redcrumbs_callback_options
+        
+        self.redcrumbs_options = options.dup
+        self.redcrumbs_callback_options = options.dup.select {|k,v| [:if, :unless].include?(k.to_sym)}
+      end
+    end
+  end
+end

data/lib/redcrumbs/users.rb

@@ -0,0 +1,35 @@
+module Redcrumbs
+# Provides methods for giving user context to crumbs. Retrieves crumbs created by a user (creator) or
+# affecting a user (target)
+ module Users
+    extend ActiveSupport::Concern
+    
+    module InstanceMethods
+      # Retrieves crumbs related to the user
+      def crumbs_for
+        Crumb.all(:target_id => self[Redcrumbs.target_primary_key], :order => [:created_at.desc])
+      end
+
+      # Retrieves crumbs created by the user
+      def crumbs_by
+        Crumb.all(:creator_id => self[Redcrumbs.creator_primary_key], :order => [:created_at.desc])
+      end
+      
+      # A limitable collection of both crumbs_for and crumbs_by
+      # This is an unforunate hack to get over the redis dm adapter's non-support of addition (OR) queries
+      def crumbs_as_user(opts = {})
+        opts[:limit] ||= 100
+        arr = crumbs_for 
+        arr += crumbs_by
+        arr.all(:limit => opts[:limit])
+      end
+      
+      # Creator method defines who should be considered the creator when a model is updated. This
+      # can be overridden in the redcrumbed model to define who the creator should be. Defaults
+      # to the current user (or creator class) associated with the model.
+      def creator
+        send(Redcrumbs.creator_class_sym) if respond_to?(Redcrumbs.creator_class_sym)
+      end
+    end
+  end
+end

data/lib/redcrumbs/version.rb

@@ -0,0 +1,3 @@
+module Redcrumbs
+  VERSION = "0.1.0"
+end

data/lib/redcrumbs.rb

@@ -0,0 +1,63 @@
+require 'active_support/concern'
+require 'active_support/dependencies/autoload'
+require "redcrumbs/version"
+require 'redcrumbs/engine'
+require 'dm-core'
+
+# Redcrumbs implements dirty models to track changes to ActiveRecord models in a way that is fast and
+# unobtrusive. By storing the data in Redis instead of a SQL database the footprint is greatly reduced, no
+# schema changes are necessary and we can harness all the advantages of a key value store; such as key expiry.
+#
+# Author:: John Hope
+# Copyright:: Copyright (c) 2012 John Hope for Project Zebra
+# License:: MIT License (http://www.opensource.org/licenses/mit-license.php)
+#
+# To start tracking a model use the 'redcrumbed' method:
+#
+#   class Venue
+#     redcrumbed, :only => [:name, :latlng]
+#   end
+#
+#   venue = Venue.last
+#   venue.crumbs(:limit => 20)
+#   crumb = venue.crumbs.last
+#   crumb.creator
+#      => #<User ... >
+#   crumb.modifications
+#      => {"name"=>["Belfast City Hall", "The City Hall, Belfast"]}
+#
+# See the documentation for more details on how to customise and use Redcrumbs.
+
+module Redcrumbs
+  extend ActiveSupport::Concern
+  extend ActiveSupport::Autoload
+  
+  autoload :Options
+  autoload :Config
+  autoload :Users
+  autoload :Creation
+  
+  include Config
+  
+  def self.setup
+    yield self
+  end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+  
+  module ClassMethods
+    def redcrumbed(options = {})
+      include Options
+      include Users
+      include Creation
+      
+      prepare_redcrumbed_options(options)
+      
+      around_save :notify_changes, self.redcrumbs_callback_options
+    end
+  end
+end
+
+ActiveRecord::Base.class_eval { include Redcrumbs }

data/redcrumbs.gemspec

@@ -0,0 +1,23 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "redcrumbs/version"
+
+Gem::Specification.new do |s|
+  s.name        = "redcrumbs"
+  s.version     = Redcrumbs::VERSION
+  s.authors     = ["John Hope"]
+  s.email       = ["info@midhirrecords.com"]
+  s.homepage    = "https://github.com/projectzebra/Redcrumbs"
+  s.summary     = %q{Fast and unobtrusive activity tracking of ActiveRecord models using DataMapper and Redis}
+  s.description = %q{Fast and unobtrusive activity tracking of ActiveRecord models using DataMapper and Redis}
+
+  s.rubyforge_project = "redcrumbs"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  
+  s.add_dependency 'data_mapper', '>= 1.2.0'
+  s.add_dependency 'dm-redis-adapter', '>= 0.6.2'
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: redcrumbs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- John Hope
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-05-21 00:00:00.000000000 +01:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: data_mapper
+  requirement: &2152286280 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *2152286280
+- !ruby/object:Gem::Dependency
+  name: dm-redis-adapter
+  requirement: &2152285780 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.6.2
+  type: :runtime
+  prerelease: false
+  version_requirements: *2152285780
+description: Fast and unobtrusive activity tracking of ActiveRecord models using DataMapper
+  and Redis
+email:
+- info@midhirrecords.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- app/models/redcrumbs/crumb.rb
+- app/models/redcrumbs/crumb/expiry.rb
+- app/models/redcrumbs/crumb/getters.rb
+- app/models/redcrumbs/crumb/setters.rb
+- lib/generators/redcrumbs/install_generator.rb
+- lib/generators/redcrumbs/templates/initializer.rb
+- lib/redcrumbs.rb
+- lib/redcrumbs/config.rb
+- lib/redcrumbs/creation.rb
+- lib/redcrumbs/engine.rb
+- lib/redcrumbs/options.rb
+- lib/redcrumbs/users.rb
+- lib/redcrumbs/version.rb
+- redcrumbs.gemspec
+has_rdoc: true
+homepage: https://github.com/projectzebra/Redcrumbs
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: redcrumbs
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Fast and unobtrusive activity tracking of ActiveRecord models using DataMapper
+  and Redis
+test_files: []