pigeons 0.0.1pre

data/README.md

@@ -0,0 +1,29 @@
+# Pigeons
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pigeons'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pigeons
+
+## Usage
+
+TODO: Write usage instructions here
+
+## 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

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+ t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test

data/lib/generators/pigeons/install_generator.rb

@@ -0,0 +1,42 @@
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module Pigeons
+
+  class InstallGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    source_root File.expand_path('../templates', __FILE__)
+    
+    # desc "Some description of my generator here"
+
+    # Commandline options can be defined here using Thor-like options:
+    # class_option :my_opt, :type => :boolean, :default => false, :desc => "My Option"
+
+    # I can later access that option using:
+    # options[:my_opt]
+
+    # Generator Code. Remember this is just suped-up Thor so methods are executed in order
+    def generate_pigeons_json
+      copy_file "pigeons.json", "config/pigeons.json"
+    end
+
+    def generate_pigeon_letter
+      copy_file "pigeon_letter.rb", "app/models/pigeon_letter.rb"
+    end
+
+    def generate_pigeon_letter_migration
+      migration_template "pigeon_letter_migration.rb", "db/migrate/create_pigeon_letters"
+    end
+
+    def generate_pigeon_mailer
+      copy_file "pigeon_mailer.rb", "app/mailers/pigeon_mailer.rb"
+    end
+
+    def self.next_migration_number(dirname)
+      ActiveRecord::Generators::Base.next_migration_number(dirname)
+    end
+
+  end
+
+end

data/lib/generators/pigeons/templates/pigeon_letter.rb

@@ -0,0 +1,30 @@
+# Represents a letter sent by Pigeons
+# 
+# Attributes
+# letter_type:: Type of letter being sent
+# cargo_id:: Associated object id (e.g. a <user_id>) *polymorphic
+# cargo_type:: Assoication type (e.g. User) *polymorphic
+# sent_at:: Time letter was sent
+# flight:: What flight was this sent on?
+class PigeonLetter < ActiveRecord::Base
+
+  ### Associations
+  belongs_to :cargo, polymorphic: true
+
+  ### Attributes
+  attr_accessible :letter_type, :cargo, :cargo_id, :cargo_type, :flight
+
+  ### Validations
+  validates_presence_of :letter_type
+  validates_presence_of :cargo_id
+  validates_presence_of :cargo_type
+  validates_presence_of :flight
+
+  ### Member Functions
+
+  def send!
+    PigeonMailer.send(letter_type, cargo, flight).deliver
+    self.update_attribute(:sent_at, Time.now)
+  end
+
+end

data/lib/generators/pigeons/templates/pigeon_letter_migration.rb

@@ -0,0 +1,16 @@
+class CreatePigeonLetters < ActiveRecord::Migration
+  def change
+    create_table :pigeon_letters do |t|
+      t.string :letter_type
+      t.string :flight
+      t.string :cargo_type
+      t.integer :cargo_id
+      t.datetime :sent_at
+
+      t.timestamps
+    end
+
+    add_index :pigeon_letters, [ :cargo_id, :cargo_type ], :name => "index_pigeon_letters_cargo_id_cargo_type"
+    add_index :pigeon_letters, [ :letter_type ], :name => "index_pigeon_letters_letter_type"
+  end
+end

data/lib/generators/pigeons/templates/pigeon_mailer.rb

@@ -0,0 +1,8 @@
+class PigeonMailer < ActionMailer::Base
+  
+  # All mailers here should take a cargo (who you're sending to), and a flight (what flight this is in)
+  def welcome(cargo, flight)
+    
+  end
+
+end

data/lib/generators/pigeons/templates/pigeons.json

@@ -0,0 +1,5 @@
+{
+  "flights": {
+    "baseline": []
+  }
+}

data/lib/pigeons/checks.rb

@@ -0,0 +1,98 @@
+module Pigeons
+
+  module Checks
+
+    # We're going to try to factor all major queries into individual functions
+    def self.no_recent_letter_check(args)
+      scope = args[:scope]
+      pigeon_arel = args[:pigeon]
+      source_arel = args[:source]
+
+      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].gt(Pigeons::Settings.cooldown.ago)
+          )
+        ).exists.not
+      )
+    end
+
+    def self.non_recurring_check(args)
+      scope = args[:scope]
+      pigeon_arel = args[:pigeon]
+      source_arel = args[:source]
+      letter = args[:letter]
+
+      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)
+          )
+        ).exists.not
+      )
+    end
+
+    def self.recurring_check(args)
+      scope = args[:scope]
+      pigeon_arel = args[:pigeon]
+      source_arel = args[:source]
+      letter = args[:letter]
+      relative_time = args[:relative_time]
+
+      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].gt(relative_time)
+          ).and(
+            pigeon_arel[:letter_type].eq(letter)
+          )
+        ).exists.not
+      )
+    end
+
+    def self.after_letter_check(args)
+      scope = args[:scope]
+      pigeon_arel = args[:pigeon]
+      source_arel = args[:source]
+      letters = args[:letters]
+      relative_action = args[:relative_action]
+      relative_time = args[:relative_time]
+
+      # TODO: We really need to sit down and think about what this check means
+      # Right now, it's going to mean
+      # All letters of letters type must have been made after relative_time ago
+      # And there must exist a letter of some such type
+      # As in, "we need the existence of a letter of type X or Y, and no letter of type X or Y may have been sent in the last .. days"
+
+      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[:letter_type].in(letters)
+          )
+        ).exists
+      ).where(
+        PigeonLetter.where(
+          pigeon_arel[:cargo_id].eq(source_arel[:id]).and(
+            pigeon_arel[:cargo_type].eq(source_arel.name.classify)
+          ).and(
+            pigeon_arel[:letter_type].in(letters)
+          ).and(
+            relative_action == :after ?
+              pigeon_arel[:created_at].gt(relative_time) : nil # TODO: nil?
+          )
+        ).exists.not
+      )
+    end
+
+  end
+end

data/lib/pigeons/elements.rb

@@ -0,0 +1,35 @@
+
+module Pigeons
+
+  module Elements
+
+    # This is the beast of our regex base parsing library
+    # He is going to parse all discernable elements from the string
+    # And send it back as elements
+    def self.parse_elements(letter)
+      article = /a(?:[n]?|ll)/ix
+      base_element = /(#{article}\s+)? (?<base_element>[\w\s]+?)/ix
+      conditionals = /(who((\'ve)|(\s+ have))?\s+) (?<conditionals>[\w\s]+)/ix
+      letter_type = /(#{article}\s+)? (?<letter>[\w\s]+) \s+ letter/ix
+      time_metric = /( (?<time_metric_coefficient>\d+) \s+)? (?<time_metric_unit>time|second|minute|hour|day|week|fortnight|month|year)(s?)/ix
+      time_qualifier = /(?<relative>after) \s+ (?<time_item>[^.!$]+)/ix
+      time_clause = /((?<recurring>every)\s+)? (?<time_metric>#{time_metric})? (\s*#{time_qualifier})?/ix
+      
+      grammar = /^\s*                 # Allow whitespace
+        ((?<joiner>and|then)\s+)?     # Joiner is and or then
+        (#{base_element} \s+)?        # Base element as ActiveRecord type or base block
+        (#{conditionals} \s+)?        # Who ... condition block
+        get(s)? \s+                   # get
+        #{letter_type}                # a ... letter
+        (\s+ #{time_clause})?         # after letter or event block
+        \s*[.!]?                      # optional punctuation
+        \s*                           # allow whitespace
+      $/ix
+
+      # Pigeons::Logger.debug [ 'Grammar', grammar ]
+      grammar.match(letter)
+    end
+
+  end
+
+end

data/lib/pigeons/errors.rb

@@ -0,0 +1,8 @@
+module Pigeons
+  
+  module PigeonError
+    class PigeonConfigError < StandardError; end
+    class PigeonFlightConfigError < PigeonConfigError; end
+  end
+
+end

data/lib/pigeons/extensions.rb

@@ -0,0 +1,34 @@
+module Pigeons
+
+  # Extensions will tell Pigeon how to parse flights for app-specific context
+  class Extension
+    # base /regexp/ { return scope }
+
+    protected
+
+      def self.base(matcher, &clause)
+        matcher = Regexp.new(matcher, "i") if matcher.is_a?(String)
+        raise ArgumentError, "First argument must be a string or regular expression" unless matcher.is_a?(Regexp)
+        raise ArgumentError, "Must include block which returns scope" unless block_given?
+
+        Pigeons.add_base(matcher, clause)
+      end
+
+      def self.condition(matcher, &clause)
+        matcher = Regexp.new(matcher, "i") if matcher.is_a?(String)
+        raise ArgumentError, "First argument must be a string or regular expression" unless matcher.is_a?(Regexp)
+        raise ArgumentError, "Must include block which returns scope" unless block_given?
+
+        Pigeons.add_conditional(matcher, clause)
+      end
+
+      def self.event(matcher, &clause)
+        matcher = Regep.new(matcher, "i") if matcher.is_a?(String)
+        raise ArgumentError, "First argument must be a string or regular expression" unless matcher.is_a?(Regexp)
+        raise ArgumentError, "Must include block which returns scope" unless block_given?
+
+        Pigeons.add_event(matcher, clause)
+      end
+
+  end
+end

data/lib/pigeons/logger.rb

@@ -0,0 +1,15 @@
+module Pigeons
+  class Logger
+    
+    def self.log(*args)
+      Rails.logger.info(*args) if defined?(Rails)
+      p *args
+    end
+
+    def self.debug(*args)
+      Rails.logger.debug(*args) if defined?(Rails)
+      p *args
+    end
+
+  end
+end

data/lib/pigeons/pigeons.rb

@@ -0,0 +1,156 @@
+
+# Pigeon controls the Carrier Pigeon system
+# Note, we're going to try to make this not require Rails - but it may require some aspects of ActiveSupport, etc.
+
+module Pigeons
+
+  class Settings
+    # Initialize class attributes
+    class_attribute :pigeon_config_file
+    class_attribute :cooldown # Limit time between sending entity a second letter
+    class_attribute :bases, :conditionals, :events
+
+    # Set Defaults
+    self.pigeon_config_file = nil
+    self.cooldown = 2.days
+
+    # Initialize
+    self.bases = []
+    self.conditionals = []
+    self.events = []
+  end
+
+  # returns will be { flight_name: [ { letter: letter_a, query: sql query, count: result count, entity: type of entity }, { ... } ] } ...
+  def self.assemble(options={})
+    opts = {
+      debug: false,
+      deep_debug: false, # include flight results in debug output
+      send: true
+    }.with_indifferent_access.merge(options)
+
+    '''Assembles all base entities deserving a post in this flight'''
+
+    # First, we're going to check that PigeonMailer and PigeonLetter exist (and are as we'd expect)
+    require 'pigeon_letter' unless defined?(PigeonLetter)
+    require 'pigeon_mailer' unless defined?(PigeonMailer)
+
+    # We'll set a natural default location if Rails is defined
+    Settings.pigeon_config_file ||= "#{Rails.root}/config/pigeons.json" if defined?(Rails)
+
+    raise PigeonError::PigeonConfigError, "Must create PigeonMailer mailer (TODO: instructions)" unless defined?(PigeonMailer) && ( PigeonMailer < ActionMailer::Base )
+    raise PigeonError::PigeonConfigError, "Must create PigeonLetter model (TODO: instructions)" unless defined?(PigeonLetter) && ( PigeonLetter < ActiveRecord::Base )
+
+    # Next, we're going to pull the configuration JSON file
+    raise PigeonError::PigeonConfigError, "Must set pigeon_config_file" if Settings.pigeon_config_file.blank?
+    raise PigeonError::PigeonConfigError, "Missing pigeon configuration file: #{Settings.pigeon_config_file}" if !File.exists?(Settings.pigeon_config_file)
+    
+    pigeon_config = begin
+      JSON(File.read(Settings.pigeon_config_file)) # TODO: Caching?
+    rescue JSON::ParserError => e
+      raise PigeonError::PigeonConfigError, "Error parsing pigeon configuration file: #{e.inspect}"
+    end
+
+    # Flights are the "cohorts" defined what and how to send letters to our entities (e.g. users)
+    flights = Hash[pigeon_config['flights'].sort]
+    raise PigeonError::PigeonConfigError, "Configuration must include flights object" if flights.nil?
+
+    results = {}
+
+    # Note, order here is important (for mod i), and thus, we've sorted flights alphabeticaly to maintain consistency
+    flights.each_with_index do |(flight, flight_info), flight_id|
+      Pigeons::Logger.log [ 'Pigeons::', 'Flight::', flight ] if opts[:debug]
+
+      results[flight] = []
+
+      # We'll allow flight: [ ... ] instead of flight: { letters: [ ... ] } for shorthand if other options are not needed
+      flight_info = { 'letters' => flight_info } if flight_info.is_a?(Array)
+      
+      base_scope = default_base_scope = if flight_info['base'] # Note, this will usually be nil, but it can be set specifically
+        Scope.get_base_scope(flight_info['base'])
+      end
+      
+      raise PigeonError::PigeonFlightConfigError, "Letters must be present in flight" if flight_info['letters'].empty?
+
+      previous_letters = []
+
+      flight_info['letters'].each_with_index do |letter_info, i|
+
+        Pigeons::Logger.debug [ 'Pigeons::', "Flight #{flight}", "Letter Info", letter_info ] if opts[:debug]
+        # This is going to parse the letter info and make sure it makes sense
+        elements = Elements.parse_elements(letter_info)
+
+        # Let's see if we were able to parse letter info
+        raise PigeonError::PigeonFlightConfigError, "Failed to parse letter info for flight #{flight}: \"#{letter_info}\".  Should be like \"someone\" gets a \"type a\" letter \"sometime\" after \"some event\"" if elements.nil?
+
+        # Otherwise, convert capture groups to a nice hash
+        elements = Hash[elements.names.zip(elements.captures)].with_indifferent_access
+
+        # args such as default base scope? maybe we should change to an arguments hash
+        # note: for running conditionals, we could verify they skip the previous scopes, but this is going to
+        # end up a complicated query.  we're going to rely on letter-existence skipping instead
+        scope_res = Scope.get_scope(elements: elements, previous_base_scope: base_scope, previous_letters: previous_letters, flights: flights, flight: flight, flight_id: flight_id, letter_info: letter_info, opts: opts)
+        
+        scope = scope_res[:scope]
+        base_scope = scope_res[:base_scope]
+        previous_letters = scope_res[:previous_letters]
+        letter = scope_res[:letter]
+        entity = scope_res[:entity]
+
+        Pigeons::Logger.debug [ 'Pigeons::', "Flight #{flight} Letter", letter_info ] if opts[:debug]
+        Pigeons::Logger.debug [ 'Pigeons::', "Flight #{flight} Scope", scope.explain ] if opts[:debug]
+        Pigeons::Logger.debug [ 'Pigeons::', "Flight #{flight} Count", scope.count ] if opts[:debug]
+        Pigeons::Logger.debug [ 'Pigeons::', "Flight #{flight} Results", scope ] if opts[:deep_debug]
+
+        results[flight].push(letter: letter, query: scope.to_sql, count: scope.count, entity: entity, scope: scope)
+
+        # TODO: We could break this out?
+        self.send_letter(scope, letter, flight) if opts[:send]
+      end
+    end
+
+    results
+  end
+
+  # Add base will add a match clause to our checks in parsing
+  # scope_block is a proc that will return a scope used in further flight tests
+  def self.add_base(matcher, clause)
+    Settings.bases.push(matcher: matcher, clause: clause)
+  end
+
+  # Add a conditional block
+  # If a condition matches this conditional block, it will append its where clause
+  def self.add_conditional(matcher, clause)
+    Settings.conditionals.push(matcher: matcher, clause: clause)
+  end
+
+  def self.add_event(matcher, clause)
+    Settings.events.push(matcher: matcher, clause: clause)
+  end
+
+  public # TODO: should these change to private?
+
+    # This is responsible for the actual send letter aspect
+    # It will create PigeonLetters and call delivery
+    # to PigeonMailer
+    def self.send_letter(scope, letter_type, flight)
+      # The question we face here is, do we create letters one-by-one, or do we create the letters in bulk
+      # possibly updating sent_at after sending
+
+      # Also, how do we send letters?
+      # Is that asynchronous?
+
+      # Let's just do this quick and dirty and come back to this
+      scope.find_each do |cargo|
+        letter = PigeonLetter.create!(cargo: cargo, letter_type: letter_type, flight: flight)
+        
+        # Send the letter -- note, we may want to also send info about flights for tracking
+        begin
+          letter.send!
+        rescue => e # We're going to rescue here to save ourselves the humiliation of failing.
+          # It would be nice to log this at the PigeonLetter (database) or return level
+          p [ 'Pigeons::SendLetter', 'Failed to send letter', e ]
+        end
+      end
+    end
+    
+end

data/lib/pigeons/pigeons_tasks.rb

@@ -0,0 +1,8 @@
+
+if defined?(Rails)
+  class PigeonTask < Rails::Railtie
+    rake_tasks do
+      Dir[File.join(File.dirname(__FILE__),'../../tasks/*.rake')].each { |f| load f }
+    end
+  end
+end