shingara-blather 0.4.8

data/lib/blather/client/client.rb

@@ -0,0 +1,310 @@
+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
+
+    # 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)
+      self.new.setup(jid, password, host, port)
+    end
+
+    def initialize  # @private
+      @state = :initializing
+
+      @status = Stanza::Presence::Status.new
+      @handlers = {}
+      @tmp_handlers = {}
+      @filters = {:before => [], :after => []}
+      @roster = Roster.new self
+
+      setup_initial_handlers
+    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
+
+    # Register a handler
+    #
+    # @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_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
+
+    def post_init(stream, jid = nil)  # @private
+      @stream = stream
+      @jid = JID.new(jid) if jid
+      self.jid.node ? client_post_init : ready!
+    end
+
+    def unbind  # @private
+      call_handler_for(:disconnected, nil) || (EM.reactor_running? && EM.stop)
+    end
+
+    def receive_data(stanza)  # @private
+      catch(:halt) do
+        run_filters :before, stanza
+        handle_stanza stanza
+        run_filters :after, stanza
+      end
+    end
+
+    def setup?  # @private
+      @setup.is_a? Array
+    end
+
+    def setup(jid, password, host = nil, port = nil)  # @private
+      @jid = JID.new(jid)
+      @setup = [@jid, password]
+      @setup << host if host
+      @setup << port if port
+      self
+    end
+
+  protected
+    def stream  # @private
+      @stream || raise('Stream not ready!')
+    end
+
+    def check_handler(type, guards)  # @private
+      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  # @private
+      [:ready, :disconnected] + Stanza.handler_list + BlatherError.handler_list
+    end
+
+    def setup_initial_handlers  # @private
+      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 :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!  # @private
+      @state = :ready
+      call_handler_for :ready, nil
+    end
+
+    def client_post_init  # @private
+      write_with_handler Stanza::Iq::Roster.new do |node|
+        roster.process node
+        write @status
+        ready!
+      end
+    end
+
+    def run_filters(type, stanza)  # @private
+      @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)  # @private
+      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)  # @private
+      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)  # @private
+      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)  # @private
+      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/pubsub.rb

@@ -0,0 +1,170 @@
+module Blather
+module DSL
+
+  class PubSub
+    attr_accessor :host
+
+    # Create a new pubsub DSL
+    #
+    # @param [Blather::Client] client the client who's connection will be used
+    # @param [#to_s] host the PubSub host
+    def initialize(client, host)
+      @client = client
+      @host = host
+    end
+
+    # Retrieve Affiliations
+    #
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Hash] affiliations See {Blather::Stanza::PubSub::Affiliations#list}
+    def affiliations(host = nil, &callback)
+      request Stanza::PubSub::Affiliations.new(:get, send_to(host)), :list, callback
+    end
+
+    # Retrieve Subscriptions
+    #
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Hash] affiliations See {Blather::Stanza::PubSub::Subscriptions#list}
+    def subscriptions(host = nil, &callback)
+      request Stanza::PubSub::Subscriptions.new(:get, send_to(host)), :list, callback
+    end
+
+    # Discover Nodes
+    #
+    # @param [#to_s] path the node path
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Array<Blather::Stanza::DiscoItems::Item>] items
+    def nodes(path = nil, host = nil, &callback)
+      path ||= '/'
+      stanza = Stanza::DiscoItems.new(:get, path)
+      stanza.to = send_to(host)
+      request stanza, :items, callback
+    end
+
+    # Discover node information
+    #
+    # @param [#to_s] path the node path
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza::DiscoInfo>] info
+    def node(path, host = nil, &callback)
+      stanza = Stanza::DiscoInfo.new(:get, path)
+      stanza.to = send_to(host)
+      request stanza, nil, callback
+    end
+
+    # Retrieve items for a node
+    #
+    # @param [#to_s] path the node path
+    # @param [Array<#to_s>] list a list of IDs to retrieve
+    # @param [Fixnum, #to_s] max the maximum number of items to return
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Array<Blather::Stanza::PubSub::PubSubItem>] items see {Blather::Stanza::PubSub::Items#items}
+    def items(path, list = [], max = nil, host = nil, &callback)
+      request(
+        Stanza::PubSub::Items.request(send_to(host), path, list, max),
+        :items,
+        callback
+      )
+    end
+
+    # Subscribe to a node
+    #
+    # @param [#to_s] node the node to subscribe to
+    # @param [Blather::JID, #to_s] jid is the jid that should be used.
+    # Defaults to the stripped current JID
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
+    def subscribe(node, jid = nil, host = nil)
+      jid ||= client.jid.stripped
+      stanza = Stanza::PubSub::Subscribe.new(:set, send_to(host), node, jid)
+      request(stanza) { |n| yield n if block_given? }
+    end
+
+    # Unsubscribe from a node
+    #
+    # @param [#to_s] node the node to unsubscribe from
+    # @param [Blather::JID, #to_s] jid is the jid that should be used.
+    # Defaults to the stripped current JID
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
+    def unsubscribe(node, jid = nil, host = nil)
+      jid ||= client.jid.stripped
+      stanza = Stanza::PubSub::Unsubscribe.new(:set, send_to(host), node, jid)
+      request(stanza) { |n| yield n if block_given? }
+    end
+
+    # Publish an item to a node
+    #
+    # @param [#to_s] node the node to publish to
+    # @param [#to_s] payload the payload to send see {Blather::Stanza::PubSub::Publish}
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
+    def publish(node, payload, host = nil)
+      stanza = Stanza::PubSub::Publish.new(send_to(host), node, :set, payload)
+      request(stanza) { |n| yield n if block_given? }
+    end
+
+    # Delete items from a node
+    #
+    # @param [#to_s] node the node to delete from
+    # @param [Array<#to_s>] ids a list of ids to delete
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
+    def retract(node, ids = [], host = nil)
+      stanza = Stanza::PubSub::Retract.new(send_to(host), node, :set, ids)
+      request(stanza) { |n| yield n if block_given? }
+    end
+
+    # Create a node
+    #
+    # @param [#to_s] node the node to create
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
+    def create(node, host = nil)
+      stanza = Stanza::PubSub::Create.new(:set, send_to(host), node)
+      request(stanza) { |n| yield n if block_given? }
+    end
+
+    # Purge all node items
+    #
+    # @param [#to_s] node the node to purge
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
+    def purge(node, host = nil)
+      stanza = Stanza::PubSubOwner::Purge.new(:set, send_to(host), node)
+      request(stanza) { |n| yield n if block_given? }
+    end
+
+    # Delete a node
+    #
+    # @param [#to_s] node the node to delete
+    # @param [#to_s] host the PubSub host (defaults to the initialized host)
+    # @yield [Blather::Stanza] stanza the reply stanza
+    def delete(node, host = nil)
+      stanza = Stanza::PubSubOwner::Delete.new(:set, send_to(host), node)
+      request(stanza) { |n| yield n if block_given? }
+    end
+
+  private
+    def request(node, method = nil, callback = nil, &block)
+      unless block_given?
+        block = lambda do |node|
+          callback.call(method ? node.__send__(method) : node)
+        end
+      end
+
+      client.write_with_handler(node, &block)
+    end
+
+    def send_to(host = nil)
+      raise 'You must provide a host' unless (host ||= @host)
+      host
+    end
+
+    def client
+      @client
+    end
+  end  # PubSub
+
+end  # DSL
+end  # Blather