tp-blather 0.8.2

data/lib/blather/client/client.rb

@@ -0,0 +1,345 @@
+require File.join(File.dirname(__FILE__), *%w[.. .. blather])
+
+module Blather
+  # # Blather Client
+  #
+  # Blather's Client class provides a set of helpers for working with common
+  # XMPP tasks such as setting up and starting the connection, settings
+  # status, registering and dispatching filters and handlers and roster
+  # management.
+  #
+  # Client can be used separately from the DSL if you'd like to implement your
+  # own DSL Here's the echo example using the client without the DSL:
+  #
+  #     require 'blather/client/client'
+  #     client = Client.setup 'echo@jabber.local', 'echo'
+  #
+  #     client.register_handler(:ready) do
+  #       puts "Connected ! send messages to #{client.jid.stripped}."
+  #     end
+  #
+  #     client.register_handler :subscription, :request? do |s|
+  #       client.write s.approve!
+  #     end
+  #
+  #     client.register_handler :message, :chat?, :body => 'exit' do |m|
+  #       client.write Blather::Stanza::Message.new(m.from, 'Exiting...')
+  #       client.close
+  #     end
+  #
+  #     client.register_handler :message, :chat?, :body do |m|
+  #       client.write Blather::Stanza::Message.new(m.from, "You sent: #{m.body}")
+  #     end
+  #
+  class Client
+    attr_reader :jid,
+                :roster,
+                :caps
+
+    # Create a new client and set it up
+    #
+    # @param [Blather::JID, #to_s] jid the JID to authorize with
+    # @param [String] password the password to authorize with
+    # @param [String] host if this isn't set it'll be resolved off the JID's
+    # domain
+    # @param [Fixnum, String] port the port to connect to.
+    #
+    # @return [Blather::Client]
+    def self.setup(jid, password, host = nil, port = nil, certs = nil, connect_timeout = nil)
+      self.new.setup(jid, password, host, port, certs, connect_timeout)
+    end
+
+    def initialize  # @private
+      @state = :initializing
+
+      @status = Stanza::Presence::Status.new
+      @handlers = {}
+      @tmp_handlers = {}
+      @filters = {:before => [], :after => []}
+      @roster = Roster.new self
+      @caps = Stanza::Capabilities.new
+
+      @handler_queue = GirlFriday::WorkQueue.new :handle_stanza, :size => 5 do |stanza|
+        handle_data stanza
+      end
+
+      setup_initial_handlers
+    end
+
+    # Check whether the client is currently connected.
+    def connected?
+      setup? && !@stream.nil? && !@stream.stopped?
+    end
+
+    # Get the current status. Taken from the `state` attribute of Status
+    def status
+      @status.state
+    end
+
+    # Set the status. Status can be set with either a single value or an array
+    # containing
+    #
+    # [state, message, to].
+    def status=(state)
+      state, msg, to = state
+
+      status = Stanza::Presence::Status.new state, msg
+      status.to = to
+      @status = status unless to
+
+      write status
+    end
+
+    # Start the connection.
+    #
+    # The stream type used is based on the JID. If a node exists it uses
+    # Blather::Stream::Client otherwise Blather::Stream::Component
+    def run
+      raise 'not setup!' unless setup?
+      klass = @setup[0].node ? Blather::Stream::Client : Blather::Stream::Component
+      klass.start self, *@setup
+    end
+    alias_method :connect, :run
+
+    # Register a filter to be run before or after the handler chain is run.
+    #
+    # @param [<:before, :after>] type the filter type
+    # @param [Symbol, nil] handler set the filter on a specific handler
+    # @param [guards] guards take a look at the guards documentation
+    # @yield [Blather::Stanza] stanza the incomming stanza
+    def register_filter(type, handler = nil, *guards, &filter)
+      unless [:before, :after].include?(type)
+        raise "Invalid filter: #{type}. Must be :before or :after"
+      end
+      @filters[type] << [guards, handler, filter]
+    end
+
+    # Register a temporary handler. Temporary handlers are based on the ID of
+    # the JID and live only until a stanza with said ID is received.
+    #
+    # @param [#to_s] id the ID of the stanza that should be handled
+    # @yield [Blather::Stanza] stanza the incomming stanza
+    def register_tmp_handler(id, &handler)
+      @tmp_handlers[id.to_s] = handler
+    end
+
+    # Clear handlers with given guards
+    #
+    # @param [Symbol, nil] type remove filters for a specific handler
+    # @param [guards] guards take a look at the guards documentation
+    def clear_handlers(type, *guards)
+      @handlers[type].delete_if { |g, _| g == guards }
+    end
+
+    # Register a handler
+    #
+    # @param [Symbol, nil] type set the filter on a specific handler
+    # @param [guards] guards take a look at the guards documentation
+    # @yield [Blather::Stanza] stanza the incomming stanza
+    def register_handler(type, *guards, &handler)
+      check_handler type, guards
+      @handlers[type] ||= []
+      @handlers[type] << [guards, handler]
+    end
+
+    # Write data to the stream
+    #
+    # @param [#to_xml, #to_s] stanza the content to send down the wire
+    def write(stanza)
+      self.stream.send(stanza)
+    end
+
+    # Helper that will create a temporary handler for the stanza being sent
+    # before writing it to the stream.
+    #
+    #     client.write_with_handler(stanza) { |s| "handle stanza here" }
+    #
+    # is equivalent to:
+    #
+    #     client.register_tmp_handler(stanza.id) { |s| "handle stanza here" }
+    #     client.write stanza
+    #
+    # @param [Blather::Stanza] stanza the stanza to send down the wire
+    # @yield [Blather::Stanza] stanza the reply stanza
+    def write_with_handler(stanza, &handler)
+      register_tmp_handler stanza.id, &handler
+      write stanza
+    end
+
+    # Close the connection
+    def close
+      self.stream.close_connection_after_writing
+    end
+
+    # @private
+    def post_init(stream, jid = nil)
+      @stream = stream
+      @jid = JID.new(jid) if jid
+      self.jid.node ? client_post_init : ready!
+    end
+
+    # @private
+    def unbind
+      call_handler_for(:disconnected, nil) || (EM.reactor_running? && EM.stop)
+    end
+
+    # @private
+    def receive_data(stanza)
+      @handler_queue << stanza
+    end
+
+    def handle_data(stanza)
+      catch(:halt) do
+        run_filters :before, stanza
+        handle_stanza stanza
+        run_filters :after, stanza
+      end
+    end
+
+    # @private
+    def setup?
+      @setup.is_a? Array
+    end
+
+    # @private
+    def setup(jid, password, host = nil, port = nil, certs = nil, connect_timeout = nil)
+      @jid = JID.new(jid)
+      @setup = [@jid, password]
+      @setup << host
+      @setup << port
+      @setup << certs
+      @setup << connect_timeout
+      self
+    end
+
+    protected
+
+    def stream
+      @stream || raise('Stream not ready!')
+    end
+
+    def check_handler(type, guards)
+      Blather.logger.warn "Handler for type \"#{type}\" will never be called as it's not a registered type" unless current_handlers.include?(type)
+      check_guards guards
+    end
+
+    def current_handlers
+      [:ready, :disconnected] + Stanza.handler_list + BlatherError.handler_list
+    end
+
+    def setup_initial_handlers
+      register_handler :error do |err|
+        raise err
+      end
+
+      # register_handler :iq, :type => [:get, :set] do |iq|
+      #   write StanzaError.new(iq, 'service-unavailable', :cancel).to_node
+      # end
+
+      register_handler :ping, :type => :get do |ping|
+        write ping.reply
+      end
+
+      register_handler :status do |status|
+        roster[status.from].status = status if roster[status.from]
+        nil
+      end
+
+      register_handler :roster do |node|
+        roster.process node
+      end
+    end
+
+    def ready!
+      @state = :ready
+      call_handler_for :ready, nil
+    end
+
+    def client_post_init
+      write_with_handler Stanza::Iq::Roster.new do |node|
+        roster.process node
+        write @status
+        ready!
+      end
+    end
+
+    def run_filters(type, stanza)
+      @filters[type].each do |guards, handler, filter|
+        next if handler && !stanza.handler_hierarchy.include?(handler)
+        catch(:pass) { call_handler filter, guards, stanza }
+      end
+    end
+
+    def handle_stanza(stanza)
+      if handler = @tmp_handlers.delete(stanza.id)
+        handler.call stanza
+      else
+        stanza.handler_hierarchy.each do |type|
+          break if call_handler_for(type, stanza)
+        end
+      end
+    end
+
+    def call_handler_for(type, stanza)
+      return unless handler = @handlers[type]
+      handler.find do |guards, handler|
+        catch(:pass) { call_handler handler, guards, stanza }
+      end
+    end
+
+    def call_handler(handler, guards, stanza)
+      if guards.first.respond_to?(:to_str)
+        result = stanza.find(*guards)
+        handler.call(stanza, result) unless result.empty?
+      else
+        handler.call(stanza) unless guarded?(guards, stanza)
+      end
+    end
+
+    # If any of the guards returns FALSE this returns true
+    # the logic is reversed to allow short circuiting
+    # (why would anyone want to loop over more values than necessary?)
+    #
+    # @private
+    def guarded?(guards, stanza)
+      guards.find do |guard|
+        case guard
+        when Symbol
+          !stanza.__send__(guard)
+        when Array
+          # return FALSE if any item is TRUE
+          !guard.detect { |condition| !guarded?([condition], stanza) }
+        when Hash
+          # return FALSE unless any inequality is found
+          guard.find do |method, test|
+            value = stanza.__send__(method)
+            # last_match is the only method found unique to Regexp classes
+            if test.class.respond_to?(:last_match)
+              !(test =~ value.to_s)
+            elsif test.is_a?(Array)
+              !test.include? value
+            else
+              test != value
+            end
+          end
+        when Proc
+          !guard.call(stanza)
+        end
+      end
+    end
+
+    def check_guards(guards)
+      guards.each do |guard|
+        case guard
+        when Array
+          guard.each { |g| check_guards([g]) }
+        when Symbol, Proc, Hash, String
+          nil
+        else
+          raise "Bad guard: #{guard.inspect}"
+        end
+      end
+    end
+  end  # Client
+
+end  # Blather

data/lib/blather/client/dsl.rb

@@ -0,0 +1,320 @@
+require File.join(File.dirname(__FILE__), 'client')
+
+module Blather
+
+  # # Blather DSL
+  #
+  # The DSL is a set of methods that enables you to write cleaner code. Being a
+  # module means it can be included in or extend any class you may want to
+  # create.
+  #
+  # Every stanza handler is registered as a method on the DSL.
+  #
+  # @example Include the DSL in the top level namespace.
+  #
+  #     require 'blather/client'
+  #     when_ready { puts "Connected ! send messages to #{jid.stripped}." }
+  #
+  #     subscription :request? do |s|
+  #       write_to_stream s.approve!
+  #     end
+  #
+  #     message :chat?, :body => 'exit' do |m|
+  #       say m.from, 'Exiting ...'
+  #       shutdown
+  #     end
+  #
+  #     message :chat?, :body do |m|
+  #       say m.from, "You sent: #{m.body}"
+  #     end
+  #
+  # @example Set the DSL to its own namespace.
+  #
+  #     require 'blather/client/dsl'
+  #     module Echo
+  #       extend Blather::DSL
+  #
+  #       when_ready { puts "Connected ! send messages to #{jid.stripped}." }
+  #
+  #       subscription :request? do |s|
+  #         write_to_stream s.approve!
+  #       end
+  #
+  #       message :chat?, :body => 'exit' do |m|
+  #         say m.from, 'Exiting ...'
+  #         shutdown
+  #       end
+  #
+  #       message :chat?, :body do |m|
+  #         say m.from, "You sent: #{m.body}"
+  #       end
+  #     end
+  #
+  #     Echo.setup 'foo@bar.com', 'foobar'
+  #
+  #     EM.run { Echo.run }
+  #
+  # @example Create a class out of it
+  #
+  #     require 'blather/client/dsl'
+  #     class Echo
+  #       include Blather::DSL
+  #     end
+  #
+  #     echo = Echo.new
+  #     echo.setup 'foo@bar.com', 'foobar'
+  #     echo.when_ready { puts "Connected ! send messages to #{jid.stripped}." }
+  #
+  #     echo.subscription :request? do |s|
+  #       write_to_stream s.approve!
+  #     end
+  #
+  #     echo.message :chat?, :body => 'exit' do |m|
+  #       say m.from, 'Exiting ...'
+  #       shutdown
+  #     end
+  #
+  #     echo.message :chat?, :body do |m|
+  #       say m.from, "You sent: #{m.body}"
+  #     end
+  #
+  #     EM.run { echo.run }
+  #
+  module DSL
+
+    autoload :PubSub, File.expand_path(File.join(File.dirname(__FILE__), *%w[dsl pubsub]))
+
+    def self.append_features(o)
+      Blather::Stanza.handler_list.each do |handler_name|
+        o.__send__ :remove_method, handler_name if !o.is_a?(Class) && o.method_defined?(handler_name)
+      end
+      super
+    end
+
+    # The actual client connection
+    #
+    # @return [Blather::Client]
+    def client
+      @client ||= Client.new
+    end
+    module_function :client
+
+    # A pubsub helper
+    #
+    # @return [Blather::PubSub]
+    def pubsub
+      @pubsub ||= PubSub.new client, jid.domain
+    end
+
+    # Push data to the stream
+    # This works such that it can be chained:
+    #     self << stanza1 << stanza2 << "raw data"
+    #
+    # @param [#to_xml, #to_s] stanza data to send down the wire
+    # @return [self]
+    def <<(stanza)
+      client.write stanza
+      self
+    end
+
+    # Prepare server settings
+    #
+    # @param [#to_s] jid the JID to authenticate with
+    # @param [#to_s] password the password to authenticate with
+    # @param [String] host (optional) the host to connect to (can be an IP). If
+    # this is `nil` the domain on the JID will be used
+    # @param [Fixnum, String] (optional) port the port to connect on
+    # @param [Fixnum] (optional) connection_timeout the time to wait for connection to succeed before timing out
+    def setup(jid, password, host = nil, port = nil, certs = nil, connection_timeout = nil)
+      client.setup(jid, password, host, port, certs, connection_timeout)
+    end
+
+    # Connect to the server. Must be run in the EventMachine reactor
+    def run
+      client.run
+    end
+
+    # Shutdown the connection.
+    # Flushes the write buffer then stops EventMachine
+    def shutdown
+      client.close
+    end
+
+    # Setup a before filter
+    #
+    # @param [Symbol] handler (optional) the stanza handler the filter should
+    # run before
+    # @param [guards] guards (optional) a set of guards to check the stanza
+    # against
+    # @yield [Blather::Stanza] stanza
+    def before(handler = nil, *guards, &block)
+      client.register_filter :before, handler, *guards, &block
+    end
+
+    # Setup an after filter
+    #
+    # @param [Symbol] handler (optional) the stanza handler the filter should
+    # run after
+    # @param [guards] guards (optional) a set of guards to check the stanza
+    # against
+    # @yield [Blather::Stanza] stanza
+    def after(handler = nil, *guards, &block)
+      client.register_filter :after, handler, *guards, &block
+    end
+
+    # Set handler for a stanza type
+    #
+    # @param [Symbol] handler the stanza type it should handle
+    # @param [guards] guards (optional) a set of guards to check the stanza
+    # against
+    # @yield [Blather::Stanza] stanza
+    def handle(handler, *guards, &block)
+      client.register_handler handler, *guards, &block
+    end
+
+    # Wrapper for "handle :ready" (just a bit of syntactic sugar)
+    #
+    # This is run after the connection has been completely setup
+    def when_ready(&block)
+      handle :ready, &block
+    end
+
+    # Wrapper for "handle :disconnected"
+    #
+    # This is run after the connection has been shut down.
+    #
+    # @example Reconnect after a disconnection
+    #     disconnected { client.run }
+    def disconnected(&block)
+      handle :disconnected, &block
+    end
+
+    # Set current status
+    #
+    # @param [Blather::Stanza::Presence::State::VALID_STATES] state the current
+    # state
+    # @param [#to_s] msg the status message to use
+    def set_status(state = nil, msg = nil)
+      client.status = state, msg
+    end
+
+    # Direct access to the roster
+    #
+    # @return [Blather::Roster]
+    def my_roster
+      client.roster
+    end
+
+    # Write data to the stream
+    #
+    # @param [#to_xml, #to_s] stanza the data to send down the wire.
+    def write_to_stream(stanza)
+      client.write stanza
+    end
+
+    # Helper method to join a MUC room
+    #
+    # @overload join(room_jid, nickname)
+    #   @param [Blather::JID, #to_s] room the JID of the room to join
+    #   @param [#to_s] nickname the nickname to join the room as
+    # @overload join(room_jid, nickname)
+    #   @param [#to_s] room the name of the room to join
+    #   @param [Blather::JID, #to_s] service the service domain the room is hosted at
+    #   @param [#to_s] nickname the nickname to join the room as
+    def join(room, service, nickname = nil)
+      join = Blather::Stanza::Presence::MUC.new
+      join.to = if nickname
+        "#{room}@#{service}/#{nickname}"
+      else
+        "#{room}/#{service}"
+      end
+      client.write join
+    end
+
+    # Helper method to make sending basic messages easier
+    #
+    # @param [Blather::JID, #to_s] to the JID of the message recipient
+    # @param [#to_s] msg the message to send
+    # @param [#to_sym] the stanza method to use
+    def say(to, msg, using = :chat)
+      client.write Blather::Stanza::Message.new(to, msg, using)
+    end
+
+    # The JID according to the server
+    #
+    # @return [Blather::JID]
+    def jid
+      client.jid
+    end
+
+    # Halt the handler chain
+    #
+    # Use this to stop the propogation of the stanza though the handler chain.
+    #
+    # @example Ignore all IQ stanzas
+    #
+    #     before(:iq) { halt }
+    def halt
+      throw :halt
+    end
+
+    # Pass responsibility to the next handler
+    #
+    # Use this to jump out of the current handler and let the next registered
+    # handler take care of the stanza
+    #
+    # @example Pass a message to the next handler
+    #
+    # This is contrive and should be handled with guards, but pass a message
+    # to the next handler based on the content
+    #
+    #     message { |s| puts "message caught" }
+    #     message { |s| pass if s.body =~ /pass along/ }
+    def pass
+      throw :pass
+    end
+
+    # Request items or info from an entity
+    #     discover (items|info), [jid], [node] do |response|
+    #     end
+    def discover(what, who, where, &callback)
+      stanza = Blather::Stanza.class_from_registration(:query, "http://jabber.org/protocol/disco##{what}").new
+      stanza.to = who
+      stanza.node = where
+
+      client.register_tmp_handler stanza.id, &callback
+      client.write stanza
+    end
+
+    # Set the capabilities of the client
+    #
+    # @param [String] node the URI
+    # @param [Array<Hash>] identities an array of identities
+    # @param [Array<Hash>] features an array of features
+    def set_caps(node, identities, features)
+      client.caps.node = node
+      client.caps.identities = identities
+      client.caps.features = features
+    end
+
+    # Send capabilities to the server
+    def send_caps
+      client.register_handler :disco_info, :type => :get, :node => client.caps.node do |s|
+        r = client.caps.dup
+        r.to = s.from
+        r.id = s.id
+        client.write r
+      end
+      client.write client.caps.c
+    end
+
+    # Generate a method for every stanza handler that exists.
+    Blather::Stanza.handler_list.each do |handler_name|
+      module_eval <<-METHOD, __FILE__, __LINE__
+        def #{handler_name}(*args, &callback)
+          handle :#{handler_name}, *args, &callback
+        end
+      METHOD
+    end
+  end  # DSL
+end  # Blather