punchline 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7cf29f420c42097206b7df8314facad3f2f777c6
+  data.tar.gz: 73c9c8d9036f745b3055551ab0de2e40204ae954
+SHA512:
+  metadata.gz: aea0964fe5cf076e7c7cc645997877f1cb056437c18f2f3a332c5932f80c8106ce628197e8fe6bef2f70d417e7a21e162adeee2e1eccfd2149185d0ad077e4fa
+  data.tar.gz: 504d8ffd5b9c953d50e3e60629e5a0edab8da91a56629dd583c61965b67ffd8c4240122a0053ff81b029ec66ebd1b923abc470707bcdd5353d835b5535d24240

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

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/.rspec

@@ -0,0 +1 @@
+--color --format doc

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+cache: bundler
+services:
+  - redis-server
+rvm:
+  - jruby
+  - 2.0.0
+  - 2.1.0
+
+script: 'bundle exec rake'

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Chris Atkins
+
+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,71 @@
+[![Build Status](https://travis-ci.org/catkins/punchline.svg)](https://travis-ci.org/catkins/punchline) [![Dependency Status](https://gemnasium.com/catkins/punchline.svg)](https://gemnasium.com/catkins/punchline) [![Coverage Status](https://img.shields.io/coveralls/catkins/punchline.svg)](https://coveralls.io/r/catkins/punchline) [![Code Climate](https://codeclimate.com/github/catkins/punchline/badges/gpa.svg)](https://codeclimate.com/github/catkins/punchline)
+
+# Punchline
+
+Punchline is a Redis backed Minimum Priority Queue with enforced uniqueness and atomicity fuelled by lua scripts.
+
+## Motivation
+
+At Doceo, we needed a way to atomically keep track of dirty records that needed reprocessing, whilst also avoiding doing extra work if records are marked as dirty and haven't been processed yet.
+
+## Prerequisites
+
+- Redis 2.6+
+
+Currently tested against Ruby 2.0.0, 2.1.0 and JRuby
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'punchline', github: 'catkins/punchline'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+## Usage
+
+```ruby
+require 'punchline'
+
+# optionally override Punchline with your own Redis client, otherwise defaults to Redis.new
+Punchline.config.redis = Redis.new host: "10.0.1.1", port: 6830
+
+# create a queue
+queue = Punchline::MinQueue.new
+queue.length # => 0
+
+# add a key
+queue.enqueue priority: Time.now.to_i, value: 'hello!' # => true
+queue.length # => 1
+
+# shortly after... higher priority score is rejected
+queue.enqueue priority: Time.now.to_i, value: 'hello!' # => false
+queue.length # => 1
+
+# original key is retrieved
+queue.dequeue # => { :priority => 1411405014, :value => "hello!" }
+
+# queue is now empty
+queue.length # => 0
+
+```
+
+## TODO
+
+- Add support for Redis::Namespace
+- Come up with a gem name that isn't taken...
+- Push to rubygems
+
+## Contributing
+
+1. Fork it ( http://github.com/catkins/punchline/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 new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rspec/core/rake_task'
+require 'bundler/gem_tasks'
+
+# Default directory to look in is `/specs`
+# Run with `rake spec`
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = ['--color', '--format', 'doc']
+end
+
+task :default => :spec

data/lib/punchline/configuration.rb

@@ -0,0 +1,13 @@
+# Encoding: utf-8
+
+require 'redis'
+
+module Punchline
+  class Configuration
+    attr_accessor :redis
+
+    def initialize(redis = nil)
+      @redis = redis || Redis.new
+    end
+  end
+end

data/lib/punchline/lua/dequeue.lua

@@ -0,0 +1,9 @@
+local key = KEYS[1]
+
+-- fetch the lowest priority value
+local score = redis.call("ZRANGE", key, 0, 0, "WITHSCORES")
+
+-- delete the smallest value
+redis.call("ZREMRANGEBYRANK", key, 0, 0)
+
+return score

data/lib/punchline/lua/enqueue.lua

@@ -0,0 +1,19 @@
+local key = KEYS[1]
+local priority = tonumber(ARGV[1])
+local value = ARGV[2]
+
+local current_score = tonumber(redis.call("ZSCORE", key, value))
+
+-- first time key has been added
+if current_score == nil then
+  redis.call("ZADD", key, priority, value)
+  return true
+end
+
+-- only add if it's a lower priority
+if priority < current_score then
+  redis.call("ZADD", key, priority, value)
+  return true
+end
+
+return false

data/lib/punchline/min_queue.rb

@@ -0,0 +1,81 @@
+# Encoding: utf-8
+
+module Punchline
+  class MinQueue
+
+    attr_accessor :key
+
+    def initialize(key)
+      @key = key
+      load_scripts!
+    end
+
+    def config
+      @config ||= Punchline.config.dup
+    end
+
+    def length
+      redis.zcard key
+    end
+
+    def all
+      redis.zrange(key, 0, -1, with_scores: true).map do |pair|
+        { value: pair.first, priority: pair.last.to_i }
+      end
+    end
+
+    def enqueue(options = {})
+      priority = options.fetch :priority
+      value    = options.fetch :value
+      @enqueue.call([key], [priority, value]) == 1
+    end
+
+    def dequeue
+      value, priority = @dequeue.call [key]
+
+      { value: value, priority: priority.to_i } unless value.nil?
+    end
+
+    def redis
+      config.redis
+    end
+
+    def load_scripts!
+      @enqueue = Script.new redis, 'enqueue.lua'
+      @dequeue = Script.new redis, 'dequeue.lua'
+    end
+
+    def clear!
+      redis.del key
+    end
+
+    def reset_scripts!
+      redis.script :flush
+    end
+
+
+    class Script
+      SCRIPT_BASE_PATH = File.expand_path('../lua', __FILE__)
+
+      attr_accessor :redis, :body, :sha, :script_name
+
+      def initialize(redis, script_name)
+        @redis = redis
+        @script_name = script_name
+      end
+
+      def call(keys = [], argv = [])
+        load! unless @body
+        @redis.evalsha sha, keys, argv
+      end
+
+      private
+
+      def load!
+        path = File.join SCRIPT_BASE_PATH, script_name
+        @body = File.read path
+        @sha  = redis.script :load, body
+      end
+    end
+  end
+end

data/lib/punchline/version.rb

@@ -0,0 +1,5 @@
+# Encoding: utf-8
+
+module Punchline
+  VERSION = "0.0.1"
+end

data/lib/punchline.rb

@@ -0,0 +1,11 @@
+require 'punchline/version'
+require 'punchline/configuration'
+require 'punchline/min_queue'
+
+module Punchline
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+  end
+end

data/punchline.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'punchline/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'punchline'
+  spec.version       = Punchline::VERSION
+  spec.authors       = ['Chris Atkins']
+  spec.email         = ['christopherlionelatkins@gmail.com']
+  spec.summary       = %q{Persistent redis based min-priority queue}
+  spec.description   = %q{Persistent redis based min-priority queue.}
+  spec.homepage      = 'http://github.com/catkins/punchline'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'redis', '>= 3.0.0'
+
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rspec', '~> 3.1.0'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'coveralls'
+end

data/spec/mindy/configuration_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+module Punchline
+  describe Configuration do
+    subject(:config) { Configuration.new }
+
+    it { should respond_to :redis }
+
+    describe '#redis' do
+      subject(:redis) { config.redis }
+      it { should_not be_nil }
+    end
+  end
+end

data/spec/mindy/min_queue_spec.rb

@@ -0,0 +1,169 @@
+require 'spec_helper'
+
+module Punchline
+  describe MinQueue do
+    TEST_KEY = 'punchline:test:queue'
+
+    def clear_queue!
+      Redis.new.del TEST_KEY
+    end
+
+    before(:all) { clear_queue! }
+    after(:each) { clear_queue! }
+
+    let(:some_key) { TEST_KEY }
+    subject(:min_queue) { MinQueue.new some_key }
+
+
+    it { should_not be_nil }
+    it { should respond_to :config }
+
+    describe '#redis' do
+      it { should respond_to :redis }
+
+      it 'should not be nil' do
+        expect(subject.redis).not_to be_nil
+      end
+
+      it 'should be equal to config#redis' do
+        config = min_queue.config
+        expect(min_queue.redis).to eq config.redis
+      end
+    end
+
+    describe '#key' do
+      it { should respond_to :key }
+
+      it 'matches the constructor params' do
+        expect(min_queue.key).to eq some_key
+      end
+    end
+
+    describe '#length' do
+      it { should respond_to :length }
+
+      let(:mock_redis) { double 'redis', zcard: 5, del: true }
+
+      it 'is initially zero' do
+        expect(subject.length).to eq 0
+      end
+
+      it 'checks the cardinality of sorted set in redis' do
+        subject.config.redis = mock_redis
+        expect(mock_redis).to receive(:zcard).with(some_key)
+        subject.length
+      end
+
+      it 'returns the length of the sorted set' do
+        subject.config.redis = mock_redis
+        expect(subject.length).to eq 5
+      end
+    end
+
+    describe '#all' do
+      it { should respond_to :all }
+
+      it 'delegates to reading redis range' do
+        expect(subject.redis).to receive(:zrange).with(some_key, 0, -1, with_scores: true)
+                                                 .and_return([])
+        subject.all
+      end
+
+      it 'returns an array' do
+        expect(subject.all).to be_kind_of Array
+      end
+
+      it 'returns elements as hashes' do
+        subject.enqueue priority: 123, value: 'hello'
+
+        hash = subject.all.first
+        expect(hash).not_to be_nil
+        expect(hash[:priority]).to eq 123
+        expect(hash[:value]).to eq 'hello'
+      end
+    end
+
+    describe '#enqueue' do
+      after(:each) do
+        subject.reset_scripts!
+      end
+
+      it { should respond_to :enqueue }
+
+      it 'increases the length by 1' do
+        expect {
+          subject.enqueue priority: 123, value: 'hello'
+        }.to change {
+          subject.length
+        }.by 1
+      end
+
+      it 'returns true when key is written' do
+        result = subject.enqueue priority: 123, value: 'hello'
+        expect(result).to eq true
+      end
+
+      it 'returns false when key is not written' do
+        result = subject.enqueue priority: 123, value: 'hello'
+        result = subject.enqueue priority: 456, value: 'hello'
+        expect(result).to eq false
+      end
+
+      describe 'duplicates' do
+        it 'ignores duplicate values' do
+          subject.enqueue priority: 123, value: 'hello'
+
+          expect {
+            subject.enqueue priority: 567, value: 'hello'
+          }.to change {
+            subject.length
+          }.by(0)
+        end
+
+        it 'retains only the lowest priority score' do
+          subject.enqueue priority: 123, value: 'hello'
+          subject.enqueue priority: 567, value: 'hello'
+          subject.enqueue priority: 789, value: 'hello'
+
+          pair = subject.dequeue
+          expect(pair[:priority]).to eq 123
+        end
+      end
+    end
+
+    describe '#dequeue' do
+      after(:each) do
+        subject.reset_scripts!
+        subject.clear!
+      end
+
+      it { should respond_to :dequeue }
+
+      it 'decreases the length by 1' do
+        subject.enqueue priority: 123, value: 'hello'
+
+        expect{ subject.dequeue }.to change { subject.length }.by -1
+      end
+
+      it 'returns the pair with the lowest score' do
+        subject.enqueue priority: 123, value: 'hello'
+        subject.enqueue priority: 567, value: 'world'
+        expect(subject.dequeue).to eq({ value: 'hello', priority: 123 })
+      end
+    end
+
+    describe '#clear!' do
+      it { should respond_to :clear! }
+
+      it 'deletes the key on redis' do
+        expect(subject.redis).to receive(:del).with(some_key)
+        subject.clear!
+      end
+
+      it 'resets the length' do
+        subject.enqueue priority: 123, value: 'hello'
+        expect { subject.clear! }.to change { subject.length }.by -1
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'coveralls'
+Coveralls.wear!
+
+require 'pry'
+require 'punchline'

metadata

@@ -0,0 +1,149 @@
+--- !ruby/object:Gem::Specification
+name: punchline
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Chris Atkins
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Persistent redis based min-priority queue.
+email:
+- christopherlionelatkins@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .coveralls.yml
+- .gitignore
+- .rspec
+- .travis.yml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/punchline.rb
+- lib/punchline/configuration.rb
+- lib/punchline/lua/dequeue.lua
+- lib/punchline/lua/enqueue.lua
+- lib/punchline/min_queue.rb
+- lib/punchline/version.rb
+- punchline.gemspec
+- spec/mindy/configuration_spec.rb
+- spec/mindy/min_queue_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/catkins/punchline
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.3.0
+signing_key: 
+specification_version: 4
+summary: Persistent redis based min-priority queue
+test_files:
+- spec/mindy/configuration_spec.rb
+- spec/mindy/min_queue_spec.rb
+- spec/spec_helper.rb