userq 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MWVhMzUwNTA1MzU1NjIwOGE0NzA2MDFjYzY3ZGU0ZWU3YWVkODE0MA==
+  data.tar.gz: !binary |-
+    ZDkxNWIzZTdlOTVmNzlkZWYzYmY3OTYwZjNjNTFhYWEzZGUwMWNmMg==
+SHA512:
+  metadata.gz: !binary |-
+    ZTBkZjBmODIwMDBkNDQ0NmIwODNhNmI5YTI3NzNmZmQ4Zjc4MTUyYTAwMjAy
+    MWUwNDU3OTY4NTE3YjcyM2ExODIwNjdjNDU4YTEzNjhkYjk4YzBiMjlkMjgy
+    NTgxN2EyM2YyN2Q2MGU5NmMyMDI5OWY4YmJjMjIyZGRhMjIwMjI=
+  data.tar.gz: !binary |-
+    ZWIzZWNkNTA1MTY4OGM3ZWFhMzRlMTBkYTNjYzE1Y2NjMjdmZDQ3NDQ2ZTRh
+    YzQ1ZmM3NjdkMzFlYzBiMzAyZDExZTEwNzZhYzBjMmI3MzQ1NmNiMTU1Yzgw
+    YzIxN2YxOGMxNmY2YTFkNjdmMTNiY2MwZmUyZTU4ZDFjYzUxNjE=

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 StudentHack
+
+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,102 @@
+# UserQ: Simple User Queues for Rails
+
+UserQ allows you to **very quickly** integrate awesome user-based queues into your Rails application. Many large ticketing websites such as [Ticketmaster](http://www.ticketmaster.com) use queues as a means of user experience.
+
+[![Build Status](https://travis-ci.org/studenthack/userq.png?branch=master)](https://travis-ci.org/studenthack/userq)
+[![Dependency Status](https://gemnasium.com/studenthack/userq.png)](https://gemnasium.com/studenthack/userq)
+![Gen Version](https://d25lcipzij17d.cloudfront.net/badge.png?title=gem&type=3c&v=0.0.1)
+
+![Screenshot](http://i.imgur.com/uqYjMyF.gif)
+
+### Example code
+```ruby
+queue = UserQ::Queue.new(capacity: 50)
+
+## Can we enter the queue?
+if queue.enter_into_queue?
+	entry = queue.enter
+	# They have a place in the queue. Sell them a ticket!
+else
+	# No place in queue. Run this block again after n seconds.
+end
+
+# Default expiry: 180 seconds
+puts entry.expires # => 180
+sleep(5)
+puts entry.expires # => 175
+```
+
+### How does it work?
+Tell it how much you capacity you have (i.e. how many available tickets are left) and then UserQ does its beautiful magic. Some of the questions you can ask UserQ:
+
+* How many "people" are in the queue?
+* When does the current users spot in the queue expire?
+* When do you think another spot in the queue will open? (i.e. average wait time)
+* Can I extend/shorten the current users spot in the queue?
+
+### Install
+```
+Install the gem:
+$ gem install userq
+
+Install the database model (automatically migrates):
+$ rails generate userq:install
+
+You're all setup!
+```
+
+
+### UserQ Documentation
+See the [full documentation on the Wiki](/studenthack/userq/wiki/Documentation) to see what you can do with UserQ.
+
+
+### Uninstall UserQ
+```
+Revoke the UserQ migration:
+$ rake db:rollback
+
+Remove everything UserQ:
+$ rails destroy userq:install
+```
+
+
+### Development
+Directly clone the repository (or fork it and clone your fork):
+```
+$ git clone https://github.com/studenthack/userq.git
+```
+
+Do some awesome stuff. To test simply run
+```
+$ rake test
+```
+
+We love pull requests! Make sure you write a test for your contribution.
+
+### Roadmap
+- Lots of more awesome looking tests
+- Develop the UserQ Wiki
+- Assign queue places in a chronological order (first into queue = first entry) instead of randomly
+
+### Release History
+- 23/12/13: The initial version
+
+### LICENCE
+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/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'UserQ'
+  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/generators/userq/install_generator.rb

@@ -0,0 +1,44 @@
+module Userq
+  class InstallGenerator < ::Rails::Generators::Base
+    source_root File.expand_path("../templates", __FILE__)
+
+    # Setup and create the migration
+    def do_migration
+      migration_exists = Dir["db/migrate/*_create_user_queues.rb"].count > 0
+
+      if migration_exists and installing?
+        puts "UserQ is already installed. Maybe a 'rake db:migrate' command might help?"
+        return
+      end
+
+      create_migration
+
+      puts "Success! UserQ is installed. You can now use it in your application." if installing?
+      puts "UserQ has already been uninstalled. Remember the 'user_queue' table needs to be manually destroyed." if destroying? and migration_exists == false
+      puts "Success! UserQ is uninstalled. The table 'userq_queue' needs to be destroyed manually to complete removal." if destroying? and migration_exists
+  end
+
+    private
+
+      def create_migration
+        migration_id = Time.now.to_i
+        migration_exists = Dir["db/migrate/*_create_user_queues.rb"].count > 0
+
+        copy_file "migration.rb", "db/migrate/#{migration_id}_create_user_queues.rb" if installing?
+        copy_file "migration.rb", Dir["db/migrate/*_create_user_queues.rb"][0].to_s if destroying? and migration_exists
+
+        run "rake db:migrate VERSION=#{migration_id}"
+      end
+
+    # Thanks to ynkr: http://stackoverflow.com/a/8829177/408177
+    protected
+
+      def installing?
+        :invoke == behavior
+      end
+
+      def destroying?
+        :revoke == behavior
+      end
+  end
+end

data/lib/generators/userq/templates/migration.rb

@@ -0,0 +1,12 @@
+class CreateUserQueues < ActiveRecord::Migration
+  def change
+    create_table :user_queues do |t|
+      t.string   :code
+      t.datetime :expires_at
+      t.text     :data
+      t.string   :context
+
+      t.timestamps
+    end
+  end
+end

data/lib/userq.rb

@@ -0,0 +1,201 @@
+module UserQ
+
+  class Queue
+    attr_accessor :queue_constraints
+
+    # pre: constraints is a hash - capacity (int), taken (int), entry_time (int of seconds)
+    # post: instance of UserQ::Queue
+    def initialize constraints = {}
+      self.queue_constraints = { context: 'all', capacity: 2, taken: 0, entry_time: 180, auto_clean: true }.merge(constraints)
+    end
+
+    def constraints input # Update the constraints
+      queue_constraints.merge!(input)
+    end
+
+    def constraint input # Alias of self.constraints
+      constraints(input)
+    end
+
+
+    # Beautiful syntax.
+
+    def enter_into_queue? # Check if enough space in queue
+      current_limit = queue_constraints[:capacity].to_i
+      current_usage = queue_constraints[:taken].to_i + UserQ::UserQueue.count_unexpired(queue_constraints[:context])
+
+      # Assess whether enough space left into queue
+      current_usage < current_limit
+    end
+
+    def nearest_entry # In seconds how long the next entry in the queue will expire.
+      UserQ::UserQueue.next_in_seconds(queue_constraints[:context])
+    end
+
+    def avg_wait_time # nearest_time but more human-readable
+      case nearest_entry.floor
+      when 0..30
+        return "Less than 30 seconds"
+      when 31..60
+        return "Less than a minute"
+      else
+        return "approximately #{(nearest_entry.floor / 60).floor} minutes"
+      end
+    end
+
+    def empty?
+      UserQ::UserQueue.count_in_context(queue_constraints[:context]) == 0
+    end
+
+    def empty_queue # Clean entries that aren't ever going to be re-used.
+      UserQ::UserQueue.empty(queue_constraints[:context])
+      true
+    end
+
+    def reset
+      UserQ::UserQueue.reset(queue_constraints[:context])
+      true
+    end
+
+    def enter data = {}
+      return false unless enter_into_queue?
+
+      entry = UserQ::UserQueue.new
+      entry.code = UserQ::Internal.generate_code
+      entry.expires_at = UserQ::Internal.current_time + queue_constraints[:entry_time]
+      entry.data = data.to_json
+      entry.context = queue_constraints[:context]
+      entry.save
+
+      # Automatically clean expired tokens. Woohoo!
+      empty_queue if queue_constraints[:auto_clean]
+
+      Entry.new(entry.code)
+    end
+
+  end
+
+  class Entry
+    attr_accessor :code, :entry
+
+    def initialize code
+      self.entry = UserQ::UserQueue.find_by_code(self.code = code)
+      raise "Entry code #{code} not valid" if self.entry.count == 0
+
+      # Woohoo!
+      self.entry = self.entry.first
+    end
+
+    def valid_context? context
+      entry.context == context
+    end
+
+    def expired?
+      entry.expires_at < UserQ::Internal.current_time
+    end
+
+    def alive? # Opposite of expired?
+      entry.expires_at >= UserQ::Internal.current_time
+    end
+
+    def expires
+      expires = (entry.expires_at - UserQ::Internal.current_time).floor
+      expires > -1 ? expires : -1
+    end
+
+    def expire
+      entry.expires_at = UserQ::Internal.current_time - 1
+      entry.save
+      true
+    end
+
+    def remove
+      entry.destroy
+      entry = nil
+      code = nil
+      true
+    end
+
+    def removed?
+      true if entry.nil? or code.nil?
+      false
+    end
+
+    def shorten seconds
+
+      entry.expires_at -= seconds if entry.expires_at >= UserQ::Internal.current_time
+      entry.save
+
+      expires
+    end
+
+    def extend seconds
+
+      if entry.expires_at < UserQ::Internal.current_time
+        entry.expires_at = UserQ::Internal.current_time + seconds
+      else
+        entry.expires_at += seconds
+      end
+
+      entry.save
+      expires
+    end
+
+    def alive
+      entry.created_at - UserQ::Internal.current_time
+    end
+
+    def data
+      entry.data || Hash.new
+    end
+  end
+
+  # UserQ::Queue.constraint(capacity: 100)
+
+
+  class UserQueue < ActiveRecord::Base
+    def self.find_by_code code
+      where(code: code)
+    end
+
+    def self.count_unexpired context
+      where(context: context).where("expires_at > ?", UserQ::Internal.current_time).count
+    end
+
+    def self.count_in_context context
+      where(context: context).count
+    end
+
+    def self.reset context
+      where(context: context).destroy_all
+    end
+
+    def self.next_in_seconds context
+      seconds = (where(context: context).order(expires_at: :asc).first.expires_at - UserQ::Internal.current_time).to_i
+      seconds > 0 ? seconds : 0
+    end
+
+    def self.empty context
+      where(context: context).where("expires_at <= ?", UserQ::Internal.current_time).destroy_all
+    end
+  end
+
+
+  # Useful internal tools we use to make it beautiful.
+  class Internal
+    def self.symbolize array
+      result = {}
+      array.each { |key, value| result[key.to_sym] = value }
+      result
+    end
+
+    def self.current_time # Time all comes from here. Beautiful to update.
+      Time.now
+    end
+
+    def self.generate_code
+      rand(36**24).to_s(36)
+    end
+  end
+
+end

data/lib/userq/version.rb

@@ -0,0 +1,3 @@
+module UserQ
+  VERSION = "0.0.1"
+end

data/test/Gemfile.test

@@ -0,0 +1,5 @@
+source 'http://rubygems.org'
+
+gem "rails"
+gem "sqlite3"
+gem "json"

data/test/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Dummy::Application.load_tasks