moderation 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Lee Jones
+
+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,214 @@
+# Moderation
+
+Certain types of data are good to keep around, but only in moderation.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'moderation'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install moderation
+
+## Usage
+
+Moderation stores the most recent data based on a limit you set (25 objects by default). Moderation can store the data in Redis or in-memory.
+
+### Possible use cases
+
+* admin dashboards and event streams
+* user activity (signups, purchases, favorites)
+* user search history
+* processing failures
+* visitor ip addresses
+* sent emails
+* incoming emails
+* referring pages/domains
+
+### Initialization Options
+
+Moderation initializes with a Hash of options:
+
+    Moderation.new(options = {})
+
+**options**
+
+* `:limit` - integer that determines how many objects Moderation will keep before deleting old objects (default: 25)
+* `:storage` - an instance of a storage object (default: in-memory)
+* `:constructor` - optional, class used to initialize new objects when fetching data from storage
+* `:construct_with` - optional, symbol for the method to call on the `:constructor`
+
+Example:
+
+    website_visitors = Moderation.new(
+      :limit => 50,
+      :storage => redis,
+      :constructor => Visitor,
+      :construct_with => :new_from_json
+    )
+
+### Interface
+
+**insert(item)**
+
+* `item` - object, stored as JSON
+  * Hash
+  * Array
+  * Other objects
+* returns `nil`
+
+Example:
+
+    new_visitor = Visitor.new('223.123.243.11', 'http://example.com/')
+    website_visitors.insert(new_visitor)
+
+**all(options = {})**
+
+* `options` - optional, a Hash of parameters
+  * `:limit` - specifies the max number of objects that are fetched from storage (default: 25)
+* returns an Array of objects
+
+Examples (after a couple more people visited the website):
+
+    website_visitors.all
+    => [#<Visitor ip_address="223.123.243.11", visited_url="http://example.com">, #<Visitor ip_address="123.443.243.11", visited_url="http://example.com/about">, #<Visitor ip_address="292.122.155.11", visited_url="http://example.com/contact">]
+
+    website_visitors.all(:limit => 1)
+    => [#<Visitor ip_address="223.123.243.11", visited_url="http://example.com">]
+
+#### Storing Hash or Array objects
+
+Example:
+
+    temperatures = Moderation.new
+
+    # add some data
+    (1..28).to_a.each do |n|
+      high = rand(100)
+      temperature = {
+        :date => "2013-02-#{n}",
+        :high => "#{high}F",
+        :low => "#{high - rand(20)}F"
+      }
+      temperatures.insert(temperature)
+    end
+
+    # keeps only the 25 most recent temperatures:
+    temperatures.all.count
+    => 25
+
+    # the most recently added temperature is first:
+    temperatures.all.first
+    => {:date=>"2013-02-28", :high=>"89F", :low=>"72F"}
+
+#### Storing other types of objects
+
+Other types of objects need to meet 2 requirements:
+
+  * respond to `to_json(*a)` with a string that can be later used to reconstruct the object
+  * initialize with a hash of attributes (see “Custom constructors” if you need a different way to initialize your objects)
+
+For this example we’ll create a simple object to represent a user's recent search history:
+
+    require 'ostruct'
+    require 'json'
+
+    class UserSearch < OpenStruct
+      def to_json(*a)
+        {:term => term, :user => user, :result_count => result_count}.to_json(*a)
+      end
+    end
+
+Now we can setup moderation and store new searches using the `:constructor` option:
+
+    user_search_history = Moderation.new(
+      :limit => 50,
+      :constructor => UserSearch
+    )
+
+Our search controller might look something like:
+
+    search = UserSearch.new(
+      :user => current_user.id,
+      :term => params[:q],
+      :result_count => results.count
+    )
+    user_search_history.insert(search)
+
+We configured `user_search_history` with `:limit => 50` so only the 50 most recent searches are kept in storage.
+
+#### Custom constructors
+
+If your object does not initialize from a hash of attributes you can pass in the `:contruct_with` option and parse the JSON yourself. For example, if we had a Note class:
+
+    require 'json'
+
+    class Note
+      attr_reader :title, :content
+
+      def initialize(title, content)
+        @title = title
+        @content = content
+      end
+
+      def to_json(*a)
+        {:title => title, :content => content}.to_json(*a)
+      end
+
+      def self.new_from_json(json)
+        data = JSON.parse(json)
+        new(data['title'], data['content'])
+      end
+    end
+
+Then we could configure moderation to use the `new_from_json` constructor method:
+
+    notes = Moderation.new(
+      :limit => 3,
+      :constructor => Note,
+      :construct_with => :new_from_json
+    )
+
+### Storage
+
+#### Redis storage
+
+Moderation can use a Redis storage backend. You'll want to pass in a `:collection` which is a string that gets used as the storage key in Redis. We're using a Redis list to store the data.
+
+    require 'redis'
+    redis = Redis.new
+    redis_storage = Moderation::Storage::Redis.new(
+      :collection => 'recent_visitors',
+      :server => redis
+    )
+
+Then setup moderation with the `:storage` option:
+
+    recent_visitors = Moderation.new(
+      :limit => 50,
+      :constructor => Visitor,
+      :construct_with => :new_from_json,
+      :storage => redis_storage
+    )
+
+#### In-memory storage
+
+Moderation stores data in-memory by default.
+
+## Contributing
+
+1. Fork it
+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 new Pull Request
+
+## TODO
+
+- [] document creating new storage backends

data/Rakefile

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

data/lib/moderation.rb

@@ -0,0 +1,45 @@
+require 'moderation/version'
+require 'multi_json'
+
+class Moderation
+  attr_reader :constructor, :construct_with, :limit, :storage
+  autoload 'Storage', 'moderation/storage.rb'
+  DEFAULT_LIMIT = 25
+
+  def initialize(options = {})
+    @constructor = options[:constructor]
+    @construct_with = options[:construct_with]
+    @limit = options.fetch(:limit, DEFAULT_LIMIT)
+    @storage = options.fetch(:storage, Storage::InMemory.new)
+    @storage.limit = @limit
+  end
+
+  def insert(item)
+    storage.insert(MultiJson.dump(item))
+  end
+
+  def all(options = {})
+    fetch_limit = options.fetch(:limit, limit)
+    storage.all(limit: fetch_limit).map do |stored_item|
+      if using_custom_constructor?
+        constructor.send(construct_with, stored_item)
+      elsif using_constructor?
+        data = MultiJson.load(stored_item, :symbolize_keys => true)
+        constructor.new(data)
+      else
+        MultiJson.load(stored_item, :symbolize_keys => true)
+      end
+    end
+  end
+
+  private
+
+  def using_constructor?
+    ! constructor.nil?
+  end
+
+  def using_custom_constructor?
+    using_constructor? && ! construct_with.nil? 
+  end
+end
+

data/lib/moderation/storage.rb

@@ -0,0 +1,6 @@
+class Moderation
+  class Storage
+    autoload 'InMemory', 'moderation/storage/in_memory.rb'
+    autoload 'Redis', 'moderation/storage/redis.rb'
+  end
+end

data/lib/moderation/storage/in_memory.rb

@@ -0,0 +1,31 @@
+class Moderation
+  class Storage
+    class InMemory 
+      attr_accessor :limit
+
+      def initialize(limit = Moderation::DEFAULT_LIMIT)
+        @limit = limit
+      end
+
+      def insert(item)
+        data.unshift(item)
+        if data.count > @limit
+          data.pop(data.count - @limit)
+        end
+        data
+      end
+
+      def all(options = {})
+        fetch_limit = options.fetch(:limit, limit)
+        data.first(fetch_limit)
+      end
+
+      private
+
+      def data
+        @data ||= []
+      end
+    end
+  end
+end
+

data/lib/moderation/storage/redis.rb

@@ -0,0 +1,61 @@
+require 'redis/namespace'
+
+class Moderation
+  class Storage
+    class Redis
+      attr_reader :collection, :server
+      attr_accessor :limit
+
+      def initialize(options = {}) 
+        @limit = options.fetch(:limit, Moderation::DEFAULT_LIMIT)
+        @collection = options.fetch(:collection)
+        @server = options.fetch(:server, nil)
+      end
+
+      def insert(item)
+        if redis.respond_to?(:multi)
+          redis.multi { insert_item_and_trim_collection(item) }
+        else
+          insert_item_and_trim_collection(item)
+        end
+      end
+
+      def all(options = {})
+        fetch_limit = options.fetch(:limit, limit).to_i - 1
+        redis.lrange(collection, 0, fetch_limit)
+      end
+
+      private
+
+      def redis
+        @redis ||= begin
+          # graciously borrowed from https://github.com/defunkt/resque
+          case server
+          when String
+            if server['redis://']
+              redis_connection = ::Redis.connect(:url => server, :thread_safe => true)
+            else
+              url, namespace = server.split('/', 2)
+              host, port, db = server.split(':')
+              redis_connection = ::Redis.new(:host => host, :port => port,
+                :thread_safe => true, :db => db)
+            end
+            namespace ||= :moderation
+
+            ::Redis::Namespace.new(namespace, :redis => redis_connection)
+          when ::Redis::Namespace
+            server
+          else
+            ::Redis::Namespace.new(:moderation, :redis => server)
+          end
+        end
+      end
+
+      def insert_item_and_trim_collection(item)
+        redis.lpush(collection, item)
+        redis.ltrim(collection, 0, (limit - 1))
+      end
+    end
+  end
+end
+

data/lib/moderation/version.rb

@@ -0,0 +1,3 @@
+class Moderation
+  VERSION = "0.0.1"
+end

data/moderation.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'moderation/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "moderation"
+  gem.version       = Moderation::VERSION
+  gem.authors       = ["Lee Jones"]
+  gem.email         = ["scribblethink@gmail.com"]
+  gem.description   = %q{Moderation stores only the most recent data based on a limit you set.}
+  gem.summary       = %q{Certain types of data are good to keep around, but only in moderation. Moderation makes it easy to keep only the most recent amount of data you care about. Persistent storage is backed by Redis.}
+  gem.homepage      = "http://github.com/leejones/moderation"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+
+  gem.add_dependency('multi_json', '~> 1.0')
+  gem.add_dependency('redis-namespace', '~> 1.0')
+
+  gem.add_development_dependency('rspec', '~> 2.0')
+  gem.add_development_dependency('pry')
+end
+

data/spec/moderation_spec.rb

@@ -0,0 +1,94 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'moderation'
+require 'ostruct'
+require 'json'
+
+describe Moderation do
+  it 'keeps a limited amount of data' do
+    recent_visitors = Moderation.new(:limit => 3, :constructor => Visitor)
+    5.times do |n|
+      visitor = Visitor.new(:ip_address => "222.333.44#{n}")
+      recent_visitors.insert(visitor)
+    end
+    recent_visitors.all.count.should eql(3)
+  end
+
+  it 'keeps the most recently stored objects' do
+    recent_visitors = Moderation.new(:limit => 3, :constructor => Visitor)
+    5.times do |n|
+      visitor = Visitor.new(:ip_address => "222.333.44#{n}")
+      recent_visitors.insert(visitor)
+    end
+    recent_visitors.all.map(&:ip_address).should eql(["222.333.444", "222.333.443", "222.333.442"])
+  end
+
+  it 'retrieves objects you stored' do
+    notes = Moderation.new(:limit => 3, :constructor => Note)
+    stored_note = Note.new(:title => 'A Title', :content => 'Some content')
+    notes.insert(stored_note)
+    retrieved_note = notes.all.first
+    retrieved_note.title.should eql('A Title')
+    retrieved_note.content.should eql('Some content')
+  end
+
+  it 'limits the number of results returned' do
+    notes = Moderation.new(:limit => 3, :constructor => Note)
+    (0..5).to_a.each do |n|
+      note = Note.new(:title => "Title #{n}", :content => "Content #{n}")
+      notes.insert(note)
+    end
+    notes.all(limit: 2).count.should eql(2)
+  end
+
+  it 'uses a custom contructor' do
+    books = Moderation.new(:constructor => Book, :construct_with => :new_from_json) 
+    new_book = Book.new('Title Goes Here', 'Author Name')
+    books.insert(new_book)
+    retrieved_book = books.all.first
+    [retrieved_book.title, retrieved_book.author].should eql(['Title Goes Here', 'Author Name'])
+  end
+
+  it 'stores a limited amount of data in redis' do
+    redis_storage = Moderation::Storage::Redis.new(:collection => 'rows')
+    rows = Moderation.new(:limit => 33, :storage => redis_storage)
+    50.times { |n| rows.insert [n] }
+    rows.all.count.should eql(33)
+  end
+
+  private
+
+  class Visitor < OpenStruct
+    def to_json(*a)
+      { :ip_address => ip_address }.to_json
+    end
+  end
+
+  class Note < OpenStruct
+    def to_json(*a)
+      {
+        :title => title,
+        :content => content 
+      }.to_json
+    end
+  end
+
+  class Book
+    attr_reader :title, :author
+
+    def initialize(title, author)
+      @title = title
+      @author = author
+    end
+
+    def to_json(*a)
+      { :title => title, :author => author }.to_json(a)
+    end
+
+    def self.new_from_json(json)
+      data = JSON.parse(json, :symbolize_names => true)
+      new(data[:title], data[:author])
+    end
+  end
+end
+

data/spec/storage/in_memory_spec.rb

@@ -0,0 +1,43 @@
+require File.expand_path('../../../lib/moderation/storage/in_memory.rb', __FILE__)
+
+describe Moderation::Storage::InMemory do
+  it 'initializes with a default limit of 25' do
+    storage = Moderation::Storage::InMemory.new
+    storage.limit.should eql(25)
+  end
+
+  it 'accepts a custom limit of 200' do
+    storage = Moderation::Storage::InMemory.new(200)
+    storage.limit.should eql(200)
+  end
+
+  it 'accepts a new limit' do
+    storage = Moderation::Storage::InMemory.new(200)
+    storage.limit = 100
+    storage.limit.should eql(100)
+  end
+
+  it 'inserts data' do
+    storage = Moderation::Storage::InMemory.new
+    storage.insert('treadstone')
+    storage.all.should eql(['treadstone'])
+  end
+
+  it 'returns all data' do
+    numbers = Moderation::Storage::InMemory.new
+    Array(0..10).each { |n|  numbers.insert(n) }
+    numbers.all.should eql([10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0])
+  end
+
+  it 'returns a subset of data' do
+    numbers = Moderation::Storage::InMemory.new
+    Array(0..10).each { |n|  numbers.insert(n) }
+    numbers.all(:limit => 5).should eql([10, 9, 8, 7, 6])
+  end
+
+  it 'returns an empty Array' do
+    numbers = Moderation::Storage::InMemory.new
+    numbers.all.should eql([])
+  end
+end
+

data/spec/storage/redis_spec.rb

@@ -0,0 +1,55 @@
+require File.expand_path('../../../lib/moderation/storage/redis.rb', __FILE__)
+
+describe Moderation::Storage::Redis do
+  before(:each) do
+    redis = Redis.new
+    @redis = Redis::Namespace.new('moderation_test', redis)
+    @redis.del 'test_data'
+  end
+
+  it 'initializes with a default limit of 25' do
+    storage = Moderation::Storage::Redis.new(:collection => 'test_data', :server => @redis)
+    storage.limit.should eql(25)
+  end
+
+  it 'accepts a custom limit' do
+    storage = Moderation::Storage::Redis.new(:limit => 200, :collection => 'test_data', :server => @redis)
+    storage.limit.should eql(200)
+  end
+
+  it 'accespts a new limit after initialization' do
+    storage = Moderation::Storage::Redis.new(:limit => 200, :collection => 'test_data', :server => @redis)
+    storage.limit = 135
+    storage.limit.should eql(135)
+  end
+
+  it 'inserts data' do
+    storage = Moderation::Storage::Redis.new(:collection => 'test_data', :server => @redis)
+    storage.insert('a little bit of data')
+    storage.all.should eql(['a little bit of data'])
+  end
+
+  it 'returns all data' do
+    numbers = Moderation::Storage::Redis.new(:collection => 'test_data', :server => @redis)
+    Array(0..10).each { |n|  numbers.insert(n) }
+    numbers.all.should eql(["10", "9", "8", "7", "6", "5", "4", "3", "2", "1", "0"])
+  end
+
+  it 'returns a subset of data' do
+    numbers = Moderation::Storage::Redis.new(:collection => 'test_data', :server => @redis)
+    Array(0..10).each { |n|  numbers.insert(n) }
+    numbers.all(:limit => 5).should eql(["10", "9", "8", "7", "6"])
+  end
+
+  it 'returns an empty Array' do
+    numbers = Moderation::Storage::Redis.new(:collection => 'test_data', :server => @redis)
+    numbers.all.should eql([])
+  end
+
+  it 'removes data outside of limit' do
+    numbers = Moderation::Storage::Redis.new(:collection => 'test_data', :server => @redis, :limit => 5)
+    Array(0..10).each { |n|  numbers.insert(n) }
+    @redis.lrange('test_data', 0, -1).count.should eql(5)
+  end
+end
+

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification 
+name: moderation
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Lee Jones
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-02-11 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: multi_json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: redis-namespace
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "1.0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "2.0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: pry
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+description: Moderation stores only the most recent data based on a limit you set.
+email: 
+- scribblethink@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/moderation.rb
+- lib/moderation/storage.rb
+- lib/moderation/storage/in_memory.rb
+- lib/moderation/storage/redis.rb
+- lib/moderation/version.rb
+- moderation.gemspec
+- spec/moderation_spec.rb
+- spec/storage/in_memory_spec.rb
+- spec/storage/redis_spec.rb
+homepage: http://github.com/leejones/moderation
+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: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Certain types of data are good to keep around, but only in moderation. Moderation makes it easy to keep only the most recent amount of data you care about. Persistent storage is backed by Redis.
+test_files: 
+- spec/moderation_spec.rb
+- spec/storage/in_memory_spec.rb
+- spec/storage/redis_spec.rb