pigeons 0.0.1pre

data/lib/pigeons/scope.rb

@@ -0,0 +1,205 @@
+module Pigeons
+
+  module Scope
+
+    def self.get_scope(args)
+      elements = args[:elements]
+      previous_base_scope = args[:previous_base_scope]
+      previous_letters = args[:previous_letters]
+      flights = args[:flights]
+      flight = args[:flight]
+      letter_info = args[:letter_info]
+      flight_id = args[:flight_id]
+      opts = args[:opts]
+
+      Pigeons::Logger.debug [ 'Pigeons::', 'Scope::GetScope', 'Elements', elements ] if opts[:debug]
+
+      # We accept a running base_element
+      # -- gets
+      # then gets
+      # then gets
+
+      base_scope = previous_base_scope unless previous_base_scope.nil?
+
+      if elements[:base_element] # E.g. "users..."
+        base_scope = get_base_scope(elements[:base_element])
+        previous_letters = [] unless elements[:joiner] # Unless we have a joiner, we're ignoring previous letters
+      elsif elements[:joiner].nil? # "then..."
+        # must start with a base element or a joiner
+        raise PigeonError::PigeonFlightConfigError, "Missing a joiner in #{flight}, start a line with an elements (e.g. user) or and/then: #{letter_info}"
+      end
+
+      Pigeons::Logger.debug [ 'Pigeons::', 'Scope::GetScope', 'Base Element Count', "#{base_scope.name.number(base_scope.count)}" ] if opts[:debug]
+
+      raise PigeonError::PigeonFlightConfigError, "First flight element in #{flight} must specify base (e.g. user), but didn't: #{letter_info}" if base_scope.nil?
+
+      scope = base_scope.scoped # We'll start with a fresh
+      source_arel = scope.arel_table # This will be used for checking PigeonLetters.. or posts
+      pigeon_arel = PigeonLetter.arel_table # used in queries below
+
+      # First, we'll check by flight
+      # Flights are essentially cohorts
+      # All entites belong to one based on entity_id%x=y where x is the number of flights
+      # and y is the order of this flight in alphabetically order starting with 0
+      if flights.count > 0
+        scope = scope.where(["id%?=?",flights.count,flight_id])
+      end
+
+      raise PigeonError::PigeonFlightConfigError, "Flight #{flight} must specify letter: #{letter_info}" if elements[:letter].nil?
+
+      # Convert the letter to snakecase
+      letter = elements[:letter].downcase.gsub(' ', '_') # "a ... letter"
+
+      # Make sure this letter is valid
+      raise PigeonError::PigeonFlightConfigError, "Flight #{flight} referenced letter \"#{letter}\" that doesn't exist in PigeonMailer.  Try adding \"def #{letter}(#{source_arel.name.singularize})\"" unless PigeonMailer.action_methods.include?(letter.to_s) || PigeonMailer.respond_to?(letter.to_s) # We'll take action_methods or respond_to?
+
+      # Next, we need to do the "based on letters" queries
+
+      # Todo/Question: what happens when a user switches cohorts and now deserves two item types
+      # we need to be mighty cautious here to preclude that
+      # Also, may happen with milestones
+      # TODO: This above, last big thing besides getting these queries right
+      # and renaming maybe from letters to posts, or not
+      # also, what are we actually sending
+
+      # First, we'll base it on cooldown
+      # Since we don't ever want to send an entity two letters on the same day
+      scope = Checks.no_recent_letter_check(scope: scope, source: source_arel, pigeon: pigeon_arel)
+
+      # If we have a time_metric, we'll track a relative time
+      # This will be used for "every" and "after that"
+      # Note: we default coeffecient to 1 for the case "Every day"
+      relative_time = nil # base
+
+      if elements[:time_metric] # "24 hours..."
+        relative_time = case elements[:time_metric_unit]
+        when "second", "minute", "hour", "day", "week", "fortnight", "month", "year"
+          (elements[:time_metric_coefficient] || 1).to_i.send(elements[:time_metric_unit]).ago
+        when "time"
+          Time.now # "Every time" = since now
+        else
+          raise PigeonError::PigeonFlightConfigError, "Flight #{flight} referenced invalid time unit (e.g. days, hours, ..): #{elements[:time_metric_unit]}: #{letter_info}"
+        end
+      end
+
+      # Then, we'll base it on ourselves
+      # Select all items where not exists letter = self (unless recurring, then base on time)
+      if elements[:recurring].blank? # every
+        scope = Checks.non_recurring_check(scope: scope, source: source_arel, pigeon: pigeon_arel, letter: letter)
+      else # Recurring ("every")
+        scope = Checks.recurring_check(scope: scope, source: source_arel, pigeon: pigeon_arel, letter: letter, relative_time: relative_time)
+      end
+
+      # Next, we're going to check the previous req clause
+      if elements[:relative] || ( elements[:joiner] == "then" )# "after..." or begins with "then..."
+
+        # TODO: Type may also be a milestone or item metric
+        # Need to make this much more diverse
+        relative_action = nil
+        time_item = nil # TODO: Event
+
+        relative_time = Time.now if relative_time.nil? # If we don't have a relative time, we count it against now
+
+        # Then, we need to check our relative
+        if elements[:relative]
+          case elements[:relative]
+          when "after"
+            relative_action = :after
+            time_item = elements[:time_item]
+          else
+            raise PigeonError::PigeonFlightConfigError, "Flight #{flight} referenced invalid time relative (e.g. before/after): #{elements[:relative]}: #{letter_info}"
+          end
+        else # joiner - if we don't have a relative, we'll default to "after that"
+          case elements[:joiner]
+          when "then"
+            relative_action = :after
+            time_item = "that"
+          else
+            raise PigeonError::PigeonFlightConfigError, "Flight #{flight} got to illegal area of code: #{letter_info}"
+          end
+        end
+
+        # Then, we need to find the relative letter type
+        if time_item == "that" # Compare with last letter -- this is baked in
+          raise PigeonError::PigeonFlightConfigError, "Flight #{flight} referenced to previous letters (\"#{elements[:time_metric]} #{elements[:relative]}\"), but ambiguous previous lines: #{letter_info}" if previous_letters.empty?
+          scope = Checks.after_letter_check( scope: scope, source: source_arel, pigeon: pigeon_arel, letters: previous_letters.clone, relative_action: relative_action, relative_time: relative_time )
+        elsif time_item =~ /^(sign((ing )|[-]|[ ])?up)|(creat(e|ion))$/i # this is also baked in (matches: signup, signing up, sign up, sign-up, create, creation)
+          scope = scope.where("created_at < ?", relative_time)
+        else
+          # Let's try to match this against the events given to settings
+          matched_events = Settings.events.select do |event|
+            match = event[:matcher].match(time_item)
+            if match
+              # TODO # uhh
+              scope = event[:clause].call(scope, relative_time, match)
+              true
+            else
+              false
+            end
+          end
+
+          raise PigeonError::PigeonFlightConfigError, "Flight #{flight} has unmatched event: \"#{time_item}\".  You must set an extension to match all events: #{letter_info}" if matched_events.count == 0
+        end
+
+      end
+
+      # Last, we'll check conditionals brought on by us
+      if elements[:conditionals] # "who've..."
+        matched_conditionals = Settings.conditionals.select do |conditional|
+          match = conditional[:matcher].match(elements[:conditionals])
+          if match
+            scope = conditional[:clause].call(scope, match)
+            true
+          else
+            false
+          end
+        end
+        raise PigeonError::PigeonFlightConfigError, "Flight #{flight} has unmatched conditional: \"#{elements[:conditionals]}\".  You must set an extension to match all conditionals: #{letter_info}" if matched_conditionals.count == 0
+      end
+
+      # Set previous letters
+      if elements[:base_element].nil? && !elements[:joiner].nil? && !elements[:conditionals].nil?
+        # then who've ...    
+        previous_letters << letter # we're going to append ourselves to previous letters to allow us to skip since we've kept a running base element, but added conditions that make us skippable
+      else
+        # otherwise, to continue on, you must have received this specific letter
+        previous_letters = [ letter ] # just us
+      end
+
+      return {
+        scope: scope,
+        base_scope: base_scope,
+        letter: letter,
+        previous_letters: previous_letters,
+        entity: source_arel.name }
+    end
+
+    # This function takes a base element like "user" and returns a scope
+    def self.get_base_scope(base_element)
+      # First, we'll check the bases defined
+      Settings.bases.each do |base|
+        match = base[:matcher].match(base_element)
+        if match
+          res = base[:clause].call(match)
+
+          if !res.is_a?(ActiveRecord::Relation)
+            raise PigeonError::PigeonConfigError, "Base scope must return an ActiveRecord::Relation, but got #{res.class.name} for #{base_element}"
+          end
+
+          return res
+        end
+      end
+
+      # Then, we'll check for a model named likeso
+      # TODO/Note, we may want to depluralize
+      klass = Object.const_get(base_element.gsub(' ','_').classify) rescue nil
+
+      if klass && ( klass < ActiveRecord::Base )
+        return klass.scoped
+      end
+
+      raise PigeonError::PigeonConfigError, "Unable to find a scope for base element: #{base_element}"
+    end
+
+  end
+end

data/lib/pigeons/version.rb

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

data/lib/pigeons.rb

@@ -0,0 +1,10 @@
+require "pigeons/version"
+
+require 'pigeons/pigeons'
+require 'pigeons/logger'
+require 'pigeons/elements'
+require 'pigeons/scope'
+require 'pigeons/checks'
+require 'pigeons/errors'
+require 'pigeons/extensions'
+require 'pigeons/pigeons_tasks'

data/pigeons.gemspec

@@ -0,0 +1,29 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pigeons/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "pigeons"
+  gem.version       = Pigeons::VERSION
+  gem.authors       = ["Geoff Hayes"]
+  gem.email         = ["geoff@safeshepherd.com"]
+  gem.description   = %q{Pigeons makes it a breeze to send your users lifecycle e-mails.}
+  gem.summary       = %q{Pigeons provides an extensible way to send our lifecycle e-mails through simple human-readable syntax}
+  gem.homepage      = "https://github.com/hayesgm/pigeons"
+
+  gem.add_dependency('activesupport')
+  gem.add_dependency('activerecord')
+  gem.add_dependency('actionmailer')
+
+  gem.add_development_dependency('mocha')
+  gem.add_development_dependency('shoulda')
+  gem.add_development_dependency('test-unit')
+  gem.add_development_dependency('rake')
+  gem.add_development_dependency('sqlite3')
+
+  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"]
+end

data/tasks/pigeons.rake

@@ -0,0 +1,142 @@
+
+namespace :pigeons do
+
+  desc "Show all posts that would be immediately sent"
+  task :check, [ :debug ] => :environment do |t, args|
+    p [ 'Pigeons::', 'Rake::Pigeons::Check', 'Initiating', args ]
+    
+    flights = Pigeons.assemble(send: false, debug: args[:debug] == "true")
+
+    flights.each do |flight, letters|
+      puts "\n#{flight.titleize} Flight"
+
+      letters.each do |letter_info|
+        puts "\t#{letter_info[:letter].titleize} -> #{letter_info[:count]} #{letter_info[:entity]}"
+      end
+    end
+    
+    p [ 'Pigeons::', 'Rake::Pigeons::Check', 'Completed' ]
+  end
+
+  desc "Run a simulation by day of Pigeon letters to be sent."
+  task :flight_test, [ :days, :debug, :force ] => :environment do |t, args|
+    unless Rails.env.staging? || Rails.env.development? || Rails.env.test? # Note, due to mocks, etc. this is not considered safe to run on any environment besides develpoment and staging
+      unless args[:force].blank?
+        puts "\n\e[0;31m   ######################################################################" 
+        puts "   #\n   #       Are you REALLY sure you want to run  Flight Test in #{Rails.env.capitalize}?"
+        puts "   #\n   #       Nothing should affect the database- but this is not considered safe for production databases."
+        puts "   #\n   #       Specifically, we are going to override Time.now, Time.current (with monkeypatches) and run a"
+        puts "   #\n   #       actual simulation day-by-day that we will rollback (and hope doesn't actually send letters)."
+        puts "   #\n   #       These assumptions are nice, but not good in a production environment."
+        puts "   #\n   #               Enter y/N + enter to continue\n   #"
+        puts "   ######################################################################\e[0m\n" 
+        proceed = STDIN.gets[0..0] rescue nil 
+        exit unless proceed == 'y' || proceed == 'Y'
+      else
+        raise "Refusing to run Flight Test on anything but Development and Staging (try rake pigeons:flight_test[days,debug,*force])"
+      end
+    end
+
+    p [ 'Pigeons::', 'Rake::Pigeons::FlightTest', 'Initiating', args ]
+    days = args[:days] ? args[:days].to_i : 15 # Default to 15 days?
+    debug = args[:debug] || false
+
+    # Stub both Time.now and Time.current
+    reality = Time.now
+    current_reality = Time.current
+
+    results = {} # E.g. { 'aflight': [ { letter_a: 5 } ]}
+    benchmarks = [] # day => run_time
+
+    # TODO: I'd like to be able to do this without degrading the environment with stubs, but that's probably not going to happen
+    time_class = class << ::Time; self; end
+    pigeon_class = class << ::PigeonMailer; self; end
+    PigeonMailer.action_methods.each { |mailer_action| pigeon_class.send(:define_method, mailer_action) { |*args| return true } }
+
+    PigeonLetter.transaction do
+      begin
+        days.times do |day|
+          puts ''
+          puts '-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-'
+          puts "Pigeons:: Simulating Day ##{day+1}"
+          puts ''
+          puts 'Letters by Type [Totals]'
+          PigeonLetter.where("sent_at IS NOT NULL").to_a.group_by { |pl| pl.letter_type }.each { |letter_type, letters| puts "\t#{letter_type}: #{letters.count}" }
+          puts ''
+          puts ''
+
+          # Time is a social construct
+          # We'll adjust it as need be
+          time_class.send(:define_method, :now) { reality + day.days }
+          time_class.send(:define_method, :current) { current_reality + day.days }
+          
+          start_time = Time.new.to_f
+          flights = Pigeons.assemble(send: true, debug: debug)
+          benchmarks[day] = Time.new.to_f - start_time
+
+          flights.each do |flight, letters|
+            results[flight] ||= {}
+            
+            puts "\n#{flight.titleize} Flight"
+
+            letters.each do |letter_info|
+              results[flight][letter_info[:letter]] ||= []
+              results[flight][letter_info[:letter]][day] = ( results[flight][letter_info[:letter]][day] || 0 ) + letter_info[:count]
+              puts "\t#{letter_info[:letter].titleize} -> #{letter_info[:count]} #{letter_info[:entity]}"
+            end
+          end
+        end
+      rescue => e
+        p [ 'Pigeons::', 'Encountered error in Rake::Pigeons::FlightTest', e.inspect ]
+        puts e.backtrace.join("\n\t")
+      ensure
+        p [ 'Pigeons::', 'Rolling back any changes made during test flight...' ]
+        raise ActiveRecord::Rollback # Force a rollback-- we don't want anything to be real here.  In the words of Biggie, "It was all a dream..."
+      end
+    end
+
+    p [ 'Pigeons::', 'Flight Test Results' ]
+    p [ 'Pigeons::' 'Raw Results', results ]
+    p [ 'Pigeons::' 'Runtimes', benchmarks ]
+
+    padding = proc { |num, i| " " + num.to_s + ( 1..(i.to_s.length - 1 + 2*3 - num.to_s.length) ).map { " " }.join }
+
+    results.each do |flight, day_by_day|
+      puts '##############################'
+      puts "#     #{flight.capitalize} Flight        #"
+      puts '##############################'
+      puts ""
+      puts ""
+
+      # "                    "
+      # Get the length just right
+      leading = ( 1..(day_by_day.map { |letter, count_by_day| letter }.sort { |a,b| a.length <=> b.length }.last.length + 2) ).map { " " }.join
+
+
+      puts "#{leading}| Day #{ (1..days).map { |i| "#{i}      " }.join }"
+      day_by_day.each do |letter, count_by_day|
+        puts ""
+        puts "#{letter}#{ ( leading.length - letter.length ).times.map { " " }.join }|     #{ count_by_day.each_with_index.map { |count, i| padding.call(count, i+1) }.join }"
+      end
+    end
+          
+    p [ 'Pigeons::', 'Rake::Pigeons::FlightTest', 'Completed' ]
+  end
+
+  task :send, [] => :environment do |t, args|
+    p [ 'Pigeons::', 'Rake::Pigeons::Send', 'Initiating', args ]
+    
+    flights = Pigeons.assemble(send: true)
+    
+    flights.each do |flight, letters|
+      puts "\n#{flight.titleize} Flight"
+
+      letters.each do |letter_info|
+        puts "\t#{letter_info[:letter].titleize} -> #{letter_info[:count]} #{letter_info[:entity]}"
+      end
+    end
+    
+    p [ 'Pigeons::', 'Rake::Pigeons::Send', 'Completed' ]
+  end
+
+end

data/test/test_helper.rb

@@ -0,0 +1,143 @@
+ENV["RAILS_ENV"] = "test"
+
+require File.expand_path('../test_helper', __FILE__)
+require 'active_support/all'
+require 'active_record'
+require 'action_mailer'
+require 'test/unit'
+
+# Some defines expected by pigeons
+class PigeonLetter < ActiveRecord::Base; end
+class PigeonMailer < ActionMailer::Base; end
+
+require 'pigeons'
+require 'mocha'
+include Mocha
+
+::NOW = ::Time.now
+::CURRENT = ::Time.current
+
+::Time.stubs(now: ::NOW) # Make this static for a test
+::Time.stubs(current: ::CURRENT)
+
+ActiveRecord::Base.establish_connection(
+  :adapter => 'sqlite3',
+  :database => ':memory:'
+)
+
+ActiveRecord::Schema.define do
+  self.verbose = false
+
+  create_table :dragons, :force => true do |t|
+    t.string :property
+    t.string :color
+    t.boolean :eaten
+    t.boolean :slept
+    t.datetime :hatched_at
+    t.datetime "created_at",  :null => false
+    t.datetime "updated_at",  :null => false
+  end
+
+  create_table :orcs, :force => true do |t|
+    t.string :name
+    t.datetime "created_at",  :null => false
+    t.datetime "updated_at",  :null => false
+  end
+
+  create_table :battles, :force => true do |t|
+    t.integer :dragon_id
+    t.integer :orc_id
+    t.boolean :is_dragon_victor
+    t.datetime "created_at",  :null => false
+    t.datetime "updated_at",  :null => false
+  end
+
+  create_table :pixies, :force => true do |t|
+    t.string :text
+    t.datetime "created_at",  :null => false
+    t.datetime "updated_at",  :null => false
+  end
+
+  create_table :levels, :force => true do |t|
+    t.integer :pixie_id
+    t.integer :level
+    t.datetime "created_at",  :null => false
+    t.datetime "updated_at",  :null => false
+  end
+  
+  create_table :pigeon_letters, :force => true do |t|
+    t.string   "letter_type"
+    t.string   "cargo_type"
+    t.integer  "cargo_id"
+    t.datetime "sent_at"
+    t.datetime "created_at",  :null => false
+    t.datetime "updated_at",  :null => false
+  end
+
+end
+
+# Clear these out in case they were used by any project settings
+Pigeons::Settings.bases = []
+Pigeons::Settings.conditionals = []
+Pigeons::Settings.events = []
+
+# Let's check classify works nicely
+ActiveSupport::Inflector.inflections do |inflect|
+  inflect.irregular 'pixie', 'pixies'
+end
+
+# This is the scope that's going to be on every object by the very nature of pigeons
+# Thus, we'll make helpers for them
+def letter_not_exists(scope, letter_type)
+  pigeon_arel = PigeonLetter.arel_table
+  source_arel = scope.arel_table
+
+  scope.where(
+    PigeonLetter.where(
+      pigeon_arel[:cargo_id].eq(source_arel[:id]).and(
+        pigeon_arel[:cargo_type].eq(source_arel.name.classify)
+      ).and(
+        pigeon_arel[:created_at].not_eq(nil)
+      ).and(
+        pigeon_arel[:letter_type].eq(letter_type.to_s)
+      )
+    ).exists.not
+  )
+end
+
+def simple_scope(scope, count=1, id=0)
+  pigeon_arel = PigeonLetter.arel_table
+  source_arel = scope.arel_table
+
+  scope.where("id%#{count}=#{id}").where(
+    PigeonLetter.where(
+      pigeon_arel[:cargo_id].eq(source_arel[:id]).and(
+        pigeon_arel[:cargo_type].eq(source_arel.name.classify)
+      ).and(
+        pigeon_arel[:created_at].gt(Pigeons::Settings.cooldown.ago)
+      )
+    ).exists.not
+  )
+end
+
+class Dragon < ActiveRecord::Base
+  has_many :battles
+end
+
+class Orc < ActiveRecord::Base
+  has_many :battles
+end
+
+class Battle < ActiveRecord::Base
+  belongs_to :dragon
+  belongs_to :orc
+end
+
+class Pixie < ActiveRecord::Base
+  has_many :levels
+end
+
+class Level < ActiveRecord::Base
+  belongs_to :pixie
+end
+