connfu-client 0.1

data/lib/connfu/dispatcher.rb

@@ -0,0 +1,164 @@
+require 'connfu/connfu_logger'
+
+module Connfu
+
+  ##
+  # Class that dispatches the external events.
+  # Currently there is no thread pool, so each event is executed sequentially
+  class Dispatcher
+    include Connfu::ConnfuLogger
+
+    attr_reader :continue
+    attr_reader :counter
+    attr_accessor :max_messages
+
+    ##
+    # Initializer
+    #
+    # ==== Parameters
+    # * +queue+ Connfu::Events instance to wait for incoming Message events
+    # * +listener_channels+ Hash of listener_channels.
+    #   * :key => channel name (valid ListenerChannel::CHANNEL_TYPES)
+    #   * :value => ListenerChannel instance
+    # * +app_channels+ information about application channels to set the channel_name associated to an inbound event
+    def initialize(queue, listener_channels, app_channels = [])
+      if listener_channels.nil? or !listener_channels.is_a?(Hash) or listener_channels.length == 0
+        raise Exception, "Unable to dispatch events if no channel is defined"
+      end
+
+      @continue = true
+      @counter = 0
+      @max_messages = 0
+      @listener_channels = listener_channels
+      @app_channels = app_channels
+      logger.debug("Dispatcher initializer")
+      @queue = queue
+    end
+
+    ##
+    # start waiting for incoming Message.
+    # Should create a new thread and wait to new events to come
+    # ==== Parameters
+    # * +queue+ optional Connfu::Events instance to wait for incoming Message events. If nil, the value got in the initializer is used
+    def start(queue = nil)
+      queue.nil? and queue = @queue
+      logger.debug("Dispatcher starts")
+      @thread = Thread.new {
+        while continue
+          logger.debug("Dispatcher waiting for a message from the Listener")
+          event = queue.get
+          @counter = @counter + 1
+          logger.debug "---------------------------------"
+          logger.debug "#{self.class} => #{event}"
+
+          if event.is_a?(Array)
+            event.each { |ev|
+              set_channels!(ev)
+              process_message(ev)
+            }
+          else
+            set_channels!(event)
+            process_message(event)
+          end
+
+        end
+      }
+    end
+
+    ##
+    # This method should be called for the thread that started the dispatcher
+    # in order to wait for dispatching incoming events from the listener
+    def join
+      @thread.join
+    end
+
+    ##
+    # Stop waiting for incoming events
+    def stop
+      @continue = false
+    end
+
+    private
+
+    ##
+    # Helper to validate if dispatcher should wait for new messages
+    def continue
+      if max_messages > 0
+        @continue and @counter < max_messages
+      else
+        @continue
+      end
+    end
+
+    ##
+    # Sets the message channel_name attribute. 
+    # The result is a list of application channels that should be advised about
+    # the inbound message
+    #
+    # * if message["type"].eql?("twitter"): message["channel_type"] is an 
+    # array of all the application twitter channels that has associated the message twitter account.
+    #   i.e.
+    #     Application channels: 
+    #       @app_channels = [
+    #                 {"uid"=>"twitter-channel-1", "type"=>"twitter", "accounts"=>[{"name"=>"juandebravo"}, {"name"=>"connfudev"}]},
+    #                 {"uid"=>"twitter-channel-2", "type"=>"twitter", "accounts"=>[{"name"=>"telefonicaid"}]}]
+    #     Incoming message:
+    #       message.channel_type = "twitter"
+    #       message.from = "juandebravo"
+    #
+    #      set_channels!(message) => message.channel_name = ["twitter-channel-1"]
+    #
+    # ==== Parameters
+    # * +message+ Connfu::Message with no channel_name info
+    # ==== Return
+    # * Connfu::Message with the channel_name filled with the relevant app channels
+    def set_channels!(message) # :doc:
+      channel_type = message.channel_type
+
+      # select channels with the same channel_type as the incoming message
+      channels = @app_channels.select { |channel| channel["type"].eql?(channel_type) }
+
+      # filter channels
+      case message.channel_type
+        when "twitter"  # filter by from or to account
+          channels = channels.select { |channel| 
+            channel["accounts"].select { |item| 
+              item["name"].eql?(message.from) or item["name"].eql?(message.to)
+            }.length > 0 
+          }
+        when "voice" # filter by did
+          channels = channels.select { |channel| 
+            channel["uid"].eql?(message.channel_name)
+            #channel["phones"].select{|item| 
+            #  item["phone_number"].eql?(message.to)
+            #}.length > 0 
+          }
+        when "sms"
+          channels = channels.select { |channel| 
+            channel["phones"].select{|item| 
+              item["phone_number"].eql?(message.to)
+            }.length > 0 
+          }
+        else
+          logger.warn("This code should not be executed because the first select should avoid this")
+          logger.info("Unexpected message: #{message.channel_type}")
+          channels = []
+      end
+
+      # get only the channel unique identifier
+      channels = channels.map { |channel| channel["uid"] }
+
+      logger.debug "Setting channels in the incoming message to #{channels}"
+      message.channel_name = channels
+    end
+
+    # Executes the blocks that are associated to that channel and event type
+    # @param *message* incoming message to be processed
+    def process_message(message)
+      logger.info("Calling event #{message.message_type} in the channel #{message.channel_type}")
+      @listener_channels[message.channel_type.to_sym].message(message.message_type.to_sym, message)
+    end
+
+  end
+
+end

data/lib/connfu/dsl.rb

@@ -0,0 +1,84 @@
+require 'connfu/connfu_logger'
+
+module Connfu
+  ##
+  # This class parses a connFu application defined using the DSL
+  # i.e. 
+  #
+  #   Connfu.application(VALID_TOKEN, ENDPOINT) {
+  #      listen(:voice) do |conference| {
+  #         conference.on(:join) do |call|
+  #           puts "New inbound call from #{call[:from]} on number #{call[:to]}"
+  #         end
+  #     }
+  #      listen(:twitter) do |conference| {
+  #        twitter.on(:new) do |tweet|
+  #          puts "#{tweet[:channel_name]} just posted a new tweet: #{tweet.content}"
+  #        end
+  #     }
+  #   }
+  #
+  module DSL
+    include Connfu::ConnfuLogger
+    
+    class << self
+      
+      ##
+      # Parses the given block
+      # ==== Return
+      #
+      # Hash of values containing as key the listener channel type and as value the blocks to be executed
+      # when an event associated to that channel is received
+      def run
+        @listener_channels = {}
+        if block_given?
+          self.instance_exec(&Proc.new)
+          @listener_channels
+        else
+          nil
+        end
+      end
+      
+      ##
+      # This method is called while parsing the application logic and a new channel is defined.
+      # It inserts a new ListenerChannels in the listener_channels attribute with the Proc associated to
+      # each event type.
+      #
+      # i.e.
+      #      listen(:voice) do |conference| {
+      #         conference.on(:join) do |call|
+      #           puts "New inbound call from #{call[:from]} on number #{call[:to]}"
+      #         end
+      #     }
+      #
+      # While parsing this snippet of code, a new listener_channel will be stored, indicating that when
+      # a new +join+ event associated to a +voice+ channel is received, the line 
+      #
+      #      puts "New inbound call from #{call[:from]} on number #{call[:to]}"
+      #
+      # must be executed.
+      #
+      # ==== Parameters
+      #
+      # * +name+ channel name
+      # * +args+ actually not in used
+      def listen(name, args = {})
+
+        unless ListenerChannel.valid?(name)
+          logger.error "Invalid channel name #{name}"
+          return nil
+        end
+
+        # Create a new channel listener
+        listener_channel = Connfu::ListenerChannel.new(name)
+
+        # If defined, insert into the channel the desired logic
+        block_given? and listener_channel.add_block(&Proc.new)
+
+        # Add channel to channels array
+        @listener_channels.store(name, listener_channel)
+      end
+      
+    end
+  end  
+end

data/lib/connfu/events.rb

@@ -0,0 +1,32 @@
+module Connfu
+  
+  ##
+  # This class is used to send Message instances between transport (listener) and dispatcher layers
+  class Events
+
+    ##
+    # Initializer
+    def initialize
+      @queue = Queue.new
+    end
+
+    ##
+    # Returns a message from the queue. It waits until there's at least one message in the queue and acts
+    # as a FIFO queue.
+    #
+    # ==== Returns
+    # Connfu::Message instance
+    def get
+      @queue.pop
+    end
+
+    ##
+    # Inserts a message in the queue
+    #
+    # ==== Parameters
+    # * +event+ Connfu::Message instance
+    def put(event)
+      @queue << event
+    end
+  end
+end

data/lib/connfu/listener.rb

@@ -0,0 +1,85 @@
+require 'connfu/connfu_stream'
+require 'connfu/connfu_logger'
+
+module Connfu
+
+  ##
+  # Class that listen to external events.
+  # Delegates the behavior in ConnfuStream so any new external resource
+  # can be added and no need to change the interface is required
+  #
+  class Listener
+    include Connfu::ConnfuLogger # application logger
+
+    attr_reader :continue
+    attr_reader :counter
+    attr_reader :app_stream
+    attr_accessor :max_messages # max amount of messages to receive
+
+    ##
+    # Listener initializer.
+    #
+    # ==== Parameters
+    # * +queue+ Connfu::Events instance to forward incoming events to be processed by the Dispatcher class
+    # * +app_stream+ valid HTTP stream url to connect and listen events
+    # * +token+ valid token to get access to a connFu Stream
+    # * +stream_endpoint+ endpoint to open a keepalive HTTP connection
+    def initialize(queue, app_stream, token, stream_endpoint)
+      @connfu_stream = Connfu::ConnfuStream.new(app_stream, token, stream_endpoint)
+      @continue = true
+      @counter = 0
+      @max_messages = 0
+      @queue = queue
+    end
+
+    ##
+    # start listening.
+    # Should create a new thread and wait to new events to come
+    # ==== Parameters
+    # * +queue+ to send incoming events to the Dispatcher class
+    def start(queue = nil)
+      queue.nil? and queue = @queue
+      logger.debug "Listener starts..."
+
+      @thread = Thread.new {
+        # listen to connFu
+        @connfu_stream.start_listening
+      }
+
+      while continue do
+        logger.debug "Waiting for a message from connFu stream"
+        message = @connfu_stream.get
+        @counter = @counter + 1
+
+        logger.debug "#{self.class} got message => #{message}"
+        # Write in internal Queue
+        queue.put(message)
+      end
+
+    end
+
+    ##
+    # Wait to get external events
+    def join
+      @thread.join
+    end
+
+    ##
+    # stop waiting for external events
+    def stop
+      @continue = false
+    end
+
+    ##
+    # checks if the thread should continue listening or return
+    def continue
+      if max_messages > 0
+        @continue and @counter < max_messages
+      else
+        @continue
+      end
+    end
+
+  end
+
+end

data/lib/connfu/listener_channel.rb

@@ -0,0 +1,100 @@
+require 'connfu/connfu_logger'
+
+module Connfu
+
+  ##
+  # This class models a specific connFu listener channel.
+  # A connFu listener channel is the path to fetch events from your resources.
+  # 
+  # ==== Current supported channel types:
+  # - +:voice+: inbound calls to a phone number mapped to the application
+  # - +:sms+: inbound sms to a phone number mapped to the application
+  # - +:twitter+: tweet messages that matches at least one of the rules defined by the application
+  # - +:rss+: atom or rss feed
+  class ListenerChannel
+    include Connfu::ConnfuLogger # application logger
+
+    # Constant that defines the supported channels
+    CHANNEL_TYPES = [:voice, :twitter, :sms, :rss]
+    CHANNEL_TYPES.freeze
+    CHANNEL_TYPES.each { |channel| channel.freeze }
+
+    # Constant that defines the supported channel events
+    EVENT_TYPES = [:new, :join, :leave, :new_topic]
+    EVENT_TYPES.freeze
+    EVENT_TYPES.each { |event| event.freeze }
+
+    # channel name (a CHANNELS item)
+    attr_reader :name
+
+    # blocks associated to the channel. Hash object (key = event_type, value = Proc)
+    attr_accessor :blocks
+
+    # how to filter inbound events from connFu
+    attr_reader :_filter
+
+    ##
+    # Channel initializer
+    #
+    # ==== Parameters
+    # * +name+ channel name (CHANNELS item)
+    def initialize(name)
+      @name = name
+      # initialize an Struct that shall keep the event blocks. There is a specific key per each event type
+      @blocks = Struct.new(*EVENT_TYPES).new(*Array.new(EVENT_TYPES.length){Array.new()})
+    end
+
+    ##
+    # Method that defines a new event in a channel
+    # ==== Parameters
+    # * +event+ event type. Must be included in EVENT_TYPES
+    #
+    def on(event)
+      EVENT_TYPES.include?(event) or (self.class.logger.error "Invalid event #{event}" and return)
+      block_given? and @blocks[event] << Proc.new
+    end
+
+    ##
+    # 
+    def message(event, arg = nil)
+      @blocks[event].each { |block|
+        block.call(arg)
+      }
+    end
+
+    def filter=(value)
+      @_filter = value
+      # TODO
+      # connFu provisioning request
+    end
+
+    def filter
+      @_filter
+    end
+
+    def add_block
+      block_given? and self.instance_exec self, &Proc.new
+
+      #
+      # Avoid using instance_exec: we can directly call the Proc received
+      # but we need to change the expectations regarding context "messages"
+      # @connfu.listener_channels[:foo].should... => @connfu.should
+      #
+      #block_given? and Proc.new.call(self)
+    end
+
+    class << self
+      ##
+      # Checks if a channel name is valid
+      # ==== Parameters
+      # * +name+ channel name
+      # ==== Return
+      # true if the channel name if valid, false if not
+      def valid?(name)
+        CHANNEL_TYPES.include?(name)
+      end
+    end
+
+  end
+
+end