stockboy 0.5.4 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4970df2dbcf052ef0b526d6eb4df39d0ed8027ff
-  data.tar.gz: 01c8f34e325e371d7575cf77a81968ac83f44841
+  metadata.gz: f79e82814670601621d41e2bd236f209c0623d26
+  data.tar.gz: eb46c2caf2ff5932afbc8eaf41a32064f52c6504
 SHA512:
-  metadata.gz: d6810492ff48e3e9774f318023de30e4ddec26dd8fe3b14a0674b9e7b4ae50bec5743538289f4b0fa1c84e115e786ead9eacf6d5da701d21e26667af92d4c523
-  data.tar.gz: f629334d14fca2a21bcf5c05841744976605084607b38e1aa1cb63e7bd136436bbc9c5330534be51bc9f07be5dd01a90a535267fe140106d404bfc0985ede4c2
+  metadata.gz: 041d9ca85788641bb8ee2e834c0488901f7d68207b1af5fb6e10e494d94b1e6d8b507cf06044403d6a2c06b81055dbf96853567ad9c4dcc057bfdcf8856f2aaf
+  data.tar.gz: 01ffad83c3db76ea4e97845c970dac4013a557b36044a118a83f577564ebaf13f52ae56dbdd220b1bbc21df82edf91adb7d620f9e011f95b7b6b724b63e72fb9

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.5.5 / 2013-12-12
+
+* [BUGFIX]      Ensure IMAP connections are reused and closed
+* [ENHANCEMENT] Expose IMAP search options for reuse
+
 ## 0.5.4 / 2013-12-04
 
 * [BUGFIX]      Fixed broken IMAP client

data/Gemfile

@@ -4,7 +4,8 @@ gemspec
 unless ENV["CI"]
   group :debug do
     gem "pry"
-    gem "pry-debugger"
+    gem "pry-debugger" if RUBY_VERSION.start_with? "1.9"
+    gem "pry-byebug" if RUBY_VERSION.start_with? "2."
   end
 end
 

data/lib/stockboy/configurator.rb

@@ -147,7 +147,8 @@ module Stockboy
     # defined within the context of each job template.
     #
     # @param [Symbol] key Name of the trigger
-    # @param [Trigger, Proc, #call] trigger_class
+    # @yieldparam [Stockboy::Job]
+    # @yieldparam [Array] Arguments passed to the action when called
     #
     # @example
     #   trigger :cleanup do |job, *args|

data/lib/stockboy/providers/imap.rb

@@ -1,4 +1,5 @@
 require 'stockboy/provider'
+require 'stockboy/providers/imap/search_options'
 require 'net/imap'
 require 'mail'
 
@@ -20,9 +21,6 @@ module Stockboy::Providers
   #
   class IMAP < Stockboy::Provider
 
-    # Corresponds to %v mode in +DateTime#strftime+
-    VMS_DATE = /\A\d{2}-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-\d{2}\z/i
-
     # @!group Options
 
     # Host name or IP address for IMAP server connection
@@ -128,17 +126,6 @@ module Stockboy::Providers
 
     # @!endgroup
 
-    # Library for connection, defaults to +Net::IMAP+
-    #
-    # @!attribute [rw] imap_client
-    #
-    def self.imap_client
-      @imap_client ||= Net::IMAP
-    end
-    class << self
-      attr_writer :imap_client
-    end
-
     # Initialize a new IMAP reader
     #
     def initialize(opts={}, &block)
@@ -158,23 +145,36 @@ module Stockboy::Providers
       DSL.new(self).instance_eval(&block) if block_given?
     end
 
+    # Direct access to the configured +Net::IMAP+ connection
+    #
+    # @example
+    #   provider.client do |imap|
+    #     imap.search("FLAGGED")
+    #   end
+    #
     def client
       raise(ArgumentError, "no block given") unless block_given?
-      return yield @open_client if @open_client
-
-      @open_client = ::Net::IMAP.new(host).tap do |i|
-        i.login(username, password)
-        i.examine(mailbox)
+      first_connection = @open_client.nil?
+      if first_connection
+        @open_client = ::Net::IMAP.new(host)
+        @open_client.login(username, password)
+        @open_client.examine(mailbox)
       end
       yield @open_client
-      @open_client.disconnect
-      @open_client = nil
     rescue ::Net::IMAP::Error => e
       errors.add :response, "IMAP connection error"
-      @open_client.disconnect
-      @open_client = nil
+    ensure
+      if first_connection
+        @open_client.disconnect
+        @open_client = nil
+      end
     end
 
+    # Purge the email from the mailbox corresponding to the [#matching_file]
+    #
+    # This can only be called after selecting the matching file to confirm the
+    # selected item, or after fetching the data
+    #
     def delete_data
       raise Stockboy::OutOfSequence, "must confirm #matching_message or calling #data" unless picked_matching_message?
 
@@ -185,12 +185,16 @@ module Stockboy::Providers
       end
     end
 
+    # IMAP message id for the email that contains the selected data to process
+    #
     def matching_message
       return @matching_message if @matching_message
-      keys = fetch_imap_message_keys
-      @matching_message = pick_from(keys) unless keys.empty?
+      message_ids = search(default_search_options)
+      @matching_message = pick_from(message_ids) unless message_ids.empty?
     end
 
+    # Clear received data and allow for selecting a new item from the server
+    #
     def clear
       super
       @matching_message = nil
@@ -198,8 +202,39 @@ module Stockboy::Providers
       @data_size = nil
     end
 
+    # Search the selected mailbox for matching messages
+    #
+    # By default, the configured options are used,
+    # @param [Hash, Array, String] options
+    #   Override default configured search options
+    #
+    # @example
+    #   provider.search(subject: "Daily Report", before: Date.today)
+    #   provider.search(["SUBJECT", "Daily Report", "BEFORE", "21-DEC-12"])
+    #   provider.search("FLAGGED BEFORE 21-DEC-12")
+    #
+    def search(options=nil)
+      client { |imap| imap.sort(['DATE'], search_keys(options), 'UTF-8') }
+    end
+
+    # Normalize a hash of search options into an array of IMAP search keys
+    #
+    # @param [Hash] options If none are given, the configured options are used
+    # @return [Array]
+    #
+    def search_keys(options=nil)
+      case options
+      when Array, String then options
+      else SearchOptions.new(options || default_search_options).to_imap
+      end
+    end
+
     private
 
+    def default_search_options
+      {subject: subject, from: from, since: since}
+    end
+
     def fetch_data
       client do |imap|
         return false unless matching_message
@@ -222,10 +257,6 @@ module Stockboy::Providers
       errors.empty?
     end
 
-    def fetch_imap_message_keys
-      client { |imap| imap.sort(['DATE'], search_keys, 'UTF-8') }
-    end
-
     def picked_matching_message?
       !!@matching_message
     end
@@ -241,27 +272,6 @@ module Stockboy::Providers
       end
     end
 
-    def search_keys
-      keys = []
-      keys.concat ['SUBJECT', subject]  if subject
-      keys.concat ['FROM', from]        if from
-      keys.concat ['SINCE', date_format(since)] if since
-      keys.concat search if search
-      keys
-    end
-
-    def date_format(value)
-      case value
-      when Date, Time, DateTime
-        value.strftime('%v')
-      when Numeric
-        Time.at(value).strftime('%v')
-      when String
-        return value if value =~ VMS_DATE
-        Date.parse(value).strftime('%v')
-      end
-    end
-
     # If activesupport is loaded, it mucks with DateTime#to_time to return
     # self when it has a utc_offset. Handle both to always return a Time.utc.
     #

data/lib/stockboy/providers/imap/search_options.rb

@@ -0,0 +1,121 @@
+require 'stockboy/providers/imap'
+
+module Stockboy::Providers
+
+  # Helper for building standard IMAP options passed to [::Net::IMAP#search]
+  #
+  class IMAP::SearchOptions
+
+    # Corresponds to %v mode in +DateTime#strftime+
+    VMS_DATE = /\A\d{2}-(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)-\d{2}\z/i
+
+    OPTION_FORMATS = {
+      'BEFORE'     => :date_format,
+      'ON'         => :date_format,
+      'SINCE'      => :date_format,
+      'SENTBEFORE' => :date_format,
+      'SENTON'     => :date_format,
+      'SENTSINCE'  => :date_format,
+      'FLAGGED'    => :boolean_format,
+      'UNFLAGGED'  => :boolean_format,
+      'SEEN'       => :boolean_format,
+      'UNSEEN'     => :boolean_format,
+      'ANSWERED'   => :boolean_format,
+      'UNANSWERED' => :boolean_format,
+      'DELETED'    => :boolean_format,
+      'UNDELETED'  => :boolean_format,
+      'DRAFT'      => :boolean_format,
+      'UNDRAFT'    => :boolean_format,
+      'NEW'        => :boolean_format,
+      'RECENT'     => :boolean_format,
+      'OLD'        => :boolean_format
+    }
+
+    # Read options from a hash
+    #
+    # @param [Hash] options
+    #
+    def initialize(options={})
+      @options = options.each_with_object(Hash.new) do |(k,v), h|
+        h[imap_key(k)] = v
+      end
+    end
+
+    # Return a hash with merged and normalized key strings
+    #
+    # @example
+    #   opt = Stockboy::Providers::IMAP::SearchOptions.new(since: Date.new(2012, 12, 21))
+    #   opt.to_hash #=> {"SINCE" => #<Date 2012, 12, 21>}
+    #
+    def to_hash
+      @options
+    end
+
+    # Return an array of IMAP search keys
+    #
+    # @example
+    #   opt = Stockboy::Providers::IMAP::SearchOptions.new(since: Date.new(2012, 12, 21))
+    #   opt.to_imap #=> ["SINCE", "21-DEC-12"]
+    #
+    def to_imap
+      @options.reduce([]) do |a, pair|
+        a.concat imap_pair(pair)
+      end
+    end
+
+    # Convert a rubyish key to IMAP string key format
+    #
+    # @param [String, Symbol] key
+    # @return [String]
+    #
+    def imap_key(key)
+      key.to_s.upcase.gsub(/[^A-Z]/,'').freeze
+    end
+
+    # Format a key-value pair for IMAP, according to the correct type
+    #
+    # @param [Array] pair
+    # @return [Array] pair
+    #
+    def imap_pair(pair)
+      if format = OPTION_FORMATS[pair[0]]
+        send(format, pair)
+      else
+        pair
+      end
+    end
+
+    # Format a key-value pair for IMAP date keys (e.g. SINCE, ON, BEFORE)
+    #
+    # @param [Array] pair
+    # @return [Array] pair
+    #
+    def date_format(pair)
+      pair[1] = case value = pair[1]
+      when Date, Time, DateTime
+        value.strftime('%v')
+      when Numeric
+        Time.at(value).strftime('%v')
+      when String
+        value =~ VMS_DATE ? value : Date.parse(value).strftime('%v')
+      end
+      pair
+    end
+
+    # Format a key-value pair for setting true/false on IMAP keys (e.g. DELETED)
+    #
+    # @param [Array] pair
+    # @return [Array] pair
+    #
+    def boolean_format(pair)
+      return [] unless pair[1] == true || pair[1] == false
+
+      if pair[1]
+        [pair[0]]
+      else
+        ['NOT', pair[0]]
+      end
+    end
+
+  end
+end

data/lib/stockboy/translations.rb

@@ -1,4 +1,5 @@
 require 'stockboy/exceptions'
+require 'stockboy/registry'
 require 'stockboy/translator'
 
 module Stockboy
@@ -7,8 +8,7 @@ module Stockboy
   # job template DSL.
   #
   module Translations
-
-    @registry ||= {}
+    extend Stockboy::Registry
 
     # Register a translator under a convenient symbolic name
     #
@@ -54,17 +54,5 @@ module Stockboy
       end
     end
 
-    # Look up a translation and return it by symbolic name
-    #
-    # @param [Symbol] func_name
-    # @return [Translator]
-    #
-    def self.find(func_name)
-      @registry[func_name]
-    end
-    class << self
-      alias_method :[], :find
-    end
-
   end
 end

data/lib/stockboy/version.rb

@@ -1,3 +1,3 @@
 module Stockboy
-  VERSION = "0.5.4"
+  VERSION = "0.5.5"
 end

data/spec/stockboy/providers/imap/search_options_spec.rb

@@ -0,0 +1,56 @@
+require 'spec_helper'
+require 'stockboy/providers/imap/search_options'
+
+module Stockboy::Providers
+  describe IMAP::SearchOptions do
+
+    describe "to_hash" do
+      it "converts keys to uppercase" do
+        options(subject: "Improbability")
+          .to_hash.should == {"SUBJECT" => "Improbability"}
+      end
+    end
+
+
+    describe "to_imap" do
+
+      it "converts to a flat array of options" do
+        options(subject: "Improbability", from: "me@example.com")
+          .to_imap.should == ["SUBJECT", "Improbability", "FROM", "me@example.com"]
+      end
+
+      DATE_OPTIONS = { before:      "BEFORE",
+                       on:          "ON",
+                       since:       "SINCE",
+                       sent_before: "SENTBEFORE",
+                       sent_on:     "SENTON",
+                       sent_since:  "SENTSINCE" }
+
+      DATE_OPTIONS.each do |date_option_symbol, date_option_imap|
+        it "converts #{date_option_imap.inspect} to IMAP date option" do
+          options(date_option_symbol => Time.new(2012, 12, 12))
+            .to_imap.should == [date_option_imap, "12-DEC-2012"]
+        end
+      end
+
+      BOOLEAN_OPTIONS = { seen:      "SEEN",
+                          unseen:    "UNSEEN",
+                          flagged:   "FLAGGED",
+                          unflagged: "UNFLAGGED" }
+
+      BOOLEAN_OPTIONS.each do |bool_option_symbol, bool_option_imap|
+        it "converts #{bool_option_imap.inspect} to IMAP single value option" do
+          options(bool_option_symbol => true).to_imap.should == [bool_option_imap]
+          options(bool_option_symbol => false).to_imap.should == ["NOT", bool_option_imap]
+          options(bool_option_symbol => nil).to_imap.should == []
+        end
+      end
+
+    end
+
+    def options(*args)
+      described_class.new(*args)
+    end
+
+  end
+end

data/spec/stockboy/providers/imap_spec.rb

@@ -76,7 +76,7 @@ module Stockboy
 
       it "should call delete on the matching message" do
         allow(provider).to receive(:client).and_yield(imap)
-        allow(provider).to receive(:fetch_imap_message_keys) { [5] }
+        allow(provider).to receive(:search) { [5] }
 
         provider.matching_message
 
@@ -87,5 +87,64 @@ module Stockboy
       end
     end
 
+    describe "#client" do
+
+      before do
+        provider.host, provider.username, provider.password = "hhh", "uuu", "ppp"
+        provider.mailbox = "UNBOX"
+      end
+
+      it "reuses open connections in nested contexts" do
+        net_imap = expect_connection("hhh", "uuu", "ppp", "UNBOX")
+
+        provider.client do |connection|
+          expect(connection).to be net_imap
+          provider.client do |i|
+            expect(connection).to be net_imap
+          end
+        end
+      end
+
+      it "closes connections when catching exceptions" do
+        net_imap = expect_connection("hhh", "uuu", "ppp", "UNBOX")
+        provider.client { |i| raise Net::IMAP::Error }
+        provider.errors[:response].should include "IMAP connection error"
+      end
+
+    end
+
+    describe "#search_keys" do
+      it "uses configured options by default" do
+        provider.since = Date.new(2012, 12, 21)
+        provider.subject = "Earth"
+        provider.from = "me@example.com"
+
+        provider.search_keys.should == [
+          "SUBJECT", "Earth",
+          "FROM", "me@example.com",
+          "SINCE", "21-Dec-2012"
+        ]
+      end
+
+      it "replaces defaults with given options" do
+        provider.since = Date.new(2012, 12, 21)
+        provider.subject = "Earth"
+        provider.search_keys(subject: "Improbability").should == ["SUBJECT", "Improbability"]
+      end
+
+      it "returns the same array given" do
+        provider.search_keys(["SINCE", "21-DEC-12"]).should == ["SINCE", "21-DEC-12"]
+      end
+    end
+
+    def expect_connection(host, user, pass, mailbox)
+      net_imap = double("IMAP")
+      expect(Net::IMAP).to receive(:new).with(host) { net_imap }
+      expect(net_imap).to receive(:login).with(user, pass)
+      expect(net_imap).to receive(:examine).with(mailbox)
+      expect(net_imap).to receive(:disconnect)
+      net_imap
+    end
+
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stockboy
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.5.5
 platform: ruby
 authors:
 - Andrew Vit
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-05 00:00:00.000000000 Z
+date: 2013-12-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -146,6 +146,7 @@ files:
 - lib/stockboy/providers/ftp.rb
 - lib/stockboy/providers/http.rb
 - lib/stockboy/providers/imap.rb
+- lib/stockboy/providers/imap/search_options.rb
 - lib/stockboy/providers/soap.rb
 - lib/stockboy/railtie.rb
 - lib/stockboy/reader.rb
@@ -201,6 +202,7 @@ files:
 - spec/stockboy/providers/file_spec.rb
 - spec/stockboy/providers/ftp_spec.rb
 - spec/stockboy/providers/http_spec.rb
+- spec/stockboy/providers/imap/search_options_spec.rb
 - spec/stockboy/providers/imap_spec.rb
 - spec/stockboy/providers/soap_spec.rb
 - spec/stockboy/providers_spec.rb
@@ -247,7 +249,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: stockboy
-rubygems_version: 2.0.6
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: Multi-source data normalization library
@@ -279,6 +281,7 @@ test_files:
 - spec/stockboy/providers/file_spec.rb
 - spec/stockboy/providers/ftp_spec.rb
 - spec/stockboy/providers/http_spec.rb
+- spec/stockboy/providers/imap/search_options_spec.rb
 - spec/stockboy/providers/imap_spec.rb
 - spec/stockboy/providers/soap_spec.rb
 - spec/stockboy/providers_spec.rb