shingara-blather 0.4.8

data/lib/blather/client/dsl.rb

@@ -0,0 +1,264 @@
+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
+  #       def self.run
+  #         client.run
+  #       end
+  #
+  #       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
+  #
+  #     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.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.client.run }
+  module DSL
+
+    autoload :PubSub, File.expand_path(File.join(File.dirname(__FILE__), *%w[dsl pubsub]))
+
+    # 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
+    def setup(jid, password, host = nil, port = nil)
+      client.setup(jid, password, host, port)
+    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 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
+    def say(to, msg)
+      client.write Blather::Stanza::Message.new(to, msg)
+    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
+    # 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
+
+    # 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

data/lib/blather/client.rb

@@ -0,0 +1,87 @@
+require 'optparse'
+require File.join(File.dirname(__FILE__), *%w[client dsl])
+
+include Blather::DSL
+
+options = {}
+optparse = OptionParser.new do |opts|
+  opts.banner = "Run with #{$0} [options] user@server/resource password [host] [port]"
+
+  opts.on('-D', '--debug', 'Run in debug mode (you will see all XMPP communication)') do
+    options[:debug] = true
+  end
+
+  opts.on('-d', '--daemonize', 'Daemonize the process') do |daemonize|
+    options[:daemonize] = daemonize
+  end
+
+  opts.on('--pid=[PID]', 'Write the PID to this file') do |pid|
+    if !File.writable?(File.dirname(pid))
+      $stderr.puts "Unable to write log file to #{pid}"
+      exit 1
+    end
+    options[:pid] = pid
+  end
+
+  opts.on('--log=[LOG]', 'Write to the [LOG] file instead of stdout/stderr') do |log|
+    if !File.writable?(File.dirname(log))
+      $stderr.puts "Unable to write log file to #{log}"
+      exit 1
+    end
+    options[:log] = log
+  end
+
+  opts.on_tail('-h', '--help', 'Show this message') do
+    puts opts
+    exit
+  end
+
+  opts.on_tail('-v', '--version', 'Show version') do
+    require 'yaml'
+    version = YAML.load_file File.join(File.dirname(__FILE__), %w[.. .. VERSION.yml])
+    puts "Blather v#{version[:major]}.#{version[:minor]}.#{version[:patch]}"
+    exit
+  end
+end
+optparse.parse!
+
+at_exit do
+  unless client.setup?
+    if ARGV.length < 2
+      puts optparse
+      exit 1
+    end
+    client.setup(*ARGV)
+  end
+
+  def run(options)
+    $stdin.reopen "/dev/null"
+
+    if options[:log]
+      log = File.new(options[:log], 'a')
+      log.sync = options[:debug]
+      $stdout.reopen log
+      $stderr.reopen $stdout
+    end
+
+    Blather.logger.level = Logger::DEBUG if options[:debug]
+
+    trap(:INT) { EM.stop }
+    trap(:TERM) { EM.stop }
+    EM.run { client.run }
+  end
+
+  if options[:daemonize]
+    pid = fork do
+      Process.setsid
+      exit if fork
+      File.open(options[:pid], 'w') { |f| f << Process.pid } if options[:pid]
+      run options
+      FileUtils.rm(options[:pid]) if options[:pid]
+    end
+    ::Process.detach pid
+    exit
+  else
+    run options
+  end
+end

data/lib/blather/core_ext/nokogiri.rb

@@ -0,0 +1,40 @@
+module Nokogiri
+module XML
+
+  class Node
+    # Alias #name to #element_name so we can use #name in an XMPP Stanza context
+    alias_method :element_name, :name
+    alias_method :element_name=, :name=
+
+    alias_method :attr_set, :[]= # :nodoc:
+    # Override Nokogiri's attribute setter to add the ability to kill an attribute
+    # by setting it to nil and to be able to lookup an attribute by symbol
+    #
+    # @param [#to_s] name the name of the attribute
+    # @param [#to_s, nil] value the new value or nil to remove it
+    def []=(name, value)
+      name = name.to_s
+      value.nil? ? remove_attribute(name) : attr_set(name, value.to_s)
+    end
+
+    alias_method :nokogiri_xpath, :xpath
+    # Override Nokogiri's #xpath method to add the ability to use symbols for lookup
+    # and namespace designation
+    def xpath(*paths)
+      paths[0] = paths[0].to_s
+      if paths.size > 1 && (namespaces = paths.pop).is_a?(Hash)
+        paths << namespaces.inject({}) { |h,v| h[v[0].to_s] = v[1]; h }
+      end
+      nokogiri_xpath *paths
+    end
+    alias_method :find, :xpath
+
+    # Return the first element at a specified xpath
+    # @see #xpath
+    def find_first(*paths)
+      xpath(*paths).first
+    end
+  end
+
+end #XML
+end #Blather

data/lib/blather/errors/sasl_error.rb

@@ -0,0 +1,43 @@
+module Blather
+
+# General SASL Errors
+# Check #name for the error name
+#
+# @handler :sasl_error
+class SASLError < BlatherError
+  SASL_ERR_NS = 'urn:ietf:params:xml:ns:xmpp-sasl'
+
+  class_inheritable_accessor :err_name
+  # @private
+  @@registrations = {}
+
+  register :sasl_error
+
+  # Import the stanza
+  #
+  # @param [Blather::XMPPNode] node the error node
+  # @return [Blather::SASLError]
+  def self.import(node)
+    self.new node
+  end
+
+  # Create a new SASLError
+  #
+  # @param [Blather::XMPPNode] node the error node
+  def initialize(node)
+    super()
+    @node = node
+  end
+
+  # The actual error name
+  #
+  # @return [Symbol] a symbol representing the error name
+  def name
+    if @node
+      name = @node.find_first('ns:*', :ns => SASL_ERR_NS).element_name
+      name.gsub('-', '_').to_sym
+    end
+  end
+end  # SASLError
+
+end  # Blather

data/lib/blather/errors/stanza_error.rb

@@ -0,0 +1,107 @@
+module Blather
+
+# Stanza errors
+# RFC3920 Section 9.3 (http://xmpp.org/rfcs/rfc3920.html#stanzas-error)
+#
+# @handler :stanza_error
+class StanzaError < BlatherError
+  STANZA_ERR_NS = 'urn:ietf:params:xml:ns:xmpp-stanzas'
+  VALID_TYPES = [:cancel, :continue, :modify, :auth, :wait].freeze
+
+  register :stanza_error
+
+  attr_reader :original, :name, :type, :text, :extras
+
+  # Factory method for instantiating the proper class for the error
+  #
+  # @param [Blather::XMPPNode] node the error node to import
+  # @return [Blather::StanzaError]
+  def self.import(node)
+    original = node.copy
+    original.remove_child 'error'
+
+    error_node = node.find_first '//*[local-name()="error"]'
+
+    name = error_node.find_first('child::*[name()!="text"]', STANZA_ERR_NS).element_name
+    type = error_node['type']
+    text = node.find_first 'descendant::*[name()="text"]', STANZA_ERR_NS
+    text = text.content if text
+
+    extras = error_node.find("descendant::*[name()!='text' and name()!='#{name}']").map { |n| n }
+
+    self.new original, name, type, text, extras
+  end
+
+  # Create a new StanzaError
+  #
+  # @param [Blather::XMPPNode] original the original stanza
+  # @param [String] name the error name
+  # @param [#to_s] type the error type as specified in
+  # [RFC3920](http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.3.2)
+  # @param [String, nil] text additional text for the error
+  # @param [Array<Blather::XMPPNode>] extras an array of extra nodes to add
+  def initialize(original, name, type, text = nil, extras = [])
+    @original = original
+    @name = name
+    self.type = type
+    @text = text
+    @extras = extras
+  end
+
+  # Set the error type
+  #
+  # @param [#to_sym] type the new error type. Must be on of
+  # Blather::StanzaError::VALID_TYPES
+  # @see [RFC3920 Section 9.3.2](http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.3.2)
+  def type=(type)
+    type = type.to_sym
+    if !VALID_TYPES.include?(type)
+      raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}"
+    end
+    @type = type
+  end
+
+  # The error name
+  #
+  # @return [Symbol]
+  def name
+    @name.gsub('-','_').to_sym
+  end
+
+  # Creates an XML node from the error
+  #
+  # @return [Blather::XMPPNode]
+  def to_node
+    node = self.original.reply
+    node.type = 'error'
+    node << (error_node = XMPPNode.new('error'))
+
+    error_node << (err = XMPPNode.new(@name, error_node.document))
+    err.namespace = 'urn:ietf:params:xml:ns:xmpp-stanzas'
+
+    if self.text
+      error_node << (text = XMPPNode.new('text', error_node.document))
+      text.namespace = 'urn:ietf:params:xml:ns:xmpp-stanzas'
+      text.content = self.text
+    end
+
+    self.extras.each { |extra| error_node << extra.dup }
+    node
+  end
+
+  # Convert the object to a proper node then convert it to a string
+  #
+  # @return [String]
+  def to_xml
+    to_node.to_s
+  end
+
+  # @private
+  def inspect
+    "Stanza Error (#{@name}): #{self.text} [#{self.extras}]"
+  end
+  # @private
+  alias_method :to_s, :inspect
+end  # StanzaError
+
+end  # Blather

data/lib/blather/errors/stream_error.rb

@@ -0,0 +1,82 @@
+module Blather
+
+# Stream Errors
+# [RFC3920 Section 9.3](http://xmpp.org/rfcs/rfc3920.html#streams-error-rules)
+#
+# @handler :stream_error
+class StreamError < BlatherError
+  STREAM_ERR_NS = 'urn:ietf:params:xml:ns:xmpp-streams'
+
+  register :stream_error
+
+  attr_reader :text, :extras
+
+  # Factory method for instantiating the proper class for the error
+  #
+  # @param [Blather::XMPPNode] node the importable node
+  def self.import(node)
+    name = node.find_first('descendant::*[name()!="text"]', STREAM_ERR_NS).element_name
+
+    text = node.find_first 'descendant::*[name()="text"]', STREAM_ERR_NS
+    text = text.content if text
+
+    extras = node.find("descendant::*[namespace-uri()!='#{STREAM_ERR_NS}']").map { |n| n }
+
+    self.new name, text, extras
+  end
+
+  # Create a new Stream Error
+  # [RFC3920 Section 4.7.2](http://xmpp.org/rfcs/rfc3920.html#rfc.section.4.7.2)
+  #
+  # @param [String] name the error name
+  # @param [String, nil] text optional error text
+  # @param [Array<Blather::XMPPNode>] extras an array of extras to attach to the
+  # error
+  def initialize(name, text = nil, extras = [])
+    @name = name
+    @text = text
+    @extras = extras
+  end
+
+  # The error name
+  #
+  # @return [Symbol]
+  def name
+    @name.gsub('-','_').to_sym
+  end
+
+  # Creates an XML node from the error
+  #
+  # @return [Blather::XMPPNode]
+  def to_node
+    node = XMPPNode.new('stream:error')
+
+    node << (err = XMPPNode.new(@name, node.document))
+    err.namespace = 'urn:ietf:params:xml:ns:xmpp-streams'
+
+    if self.text
+      node << (text = XMPPNode.new('text', node.document))
+      text.namespace = 'urn:ietf:params:xml:ns:xmpp-streams'
+      text.content = self.text
+    end
+
+    self.extras.each { |extra| node << extra.dup }
+    node
+  end
+
+  # Convert the object to a proper node then convert it to a string
+  #
+  # @return [String]
+  def to_xml
+    to_node.to_s
+  end
+
+  # @private
+  def inspect
+    "Stream Error (#{@name}): #{self.text}" + (self.extras.empty? ? '' : " [#{self.extras}]")
+  end
+  # @private
+  alias_method :to_s, :inspect
+end  # StreamError
+
+end  # Blather

data/lib/blather/errors.rb

@@ -0,0 +1,69 @@
+module Blather
+  # Main error class
+  # This starts the error hierarchy
+  #
+  # @handler :error
+  class BlatherError < StandardError
+    class_inheritable_array :handler_hierarchy
+    self.handler_hierarchy ||= []
+
+    # @private
+    @@handler_list = []
+
+    # Register the class's handler
+    #
+    # @param [Symbol] handler the handler name
+    def self.register(handler)
+      @@handler_list << handler
+      self.handler_hierarchy.unshift handler
+    end
+
+    # The list of registered handlers
+    #
+    # @return [Array<Symbol>] a list of currently registered handlers
+    def self.handler_list
+      @@handler_list
+    end
+
+    register :error
+
+    # @private
+    # HACK!! until I can refactor the entire Error object model
+    def id
+      nil
+    end
+  end  # BlatherError
+
+  # Used in cases where a stanza only allows specific values for its attributes
+  # and an invalid value is attempted.
+  #
+  # @handler :argument_error
+  class ArgumentError < BlatherError
+    register :argument_error
+  end  # ArgumentError
+
+  # The stream handler received a response it didn't know how to handle
+  #
+  # @handler :unknown_response_error
+  class UnknownResponse < BlatherError
+    register :unknown_response_error
+    attr_reader :node
+
+    def initialize(node)
+      @node = node
+    end
+  end  # UnknownResponse
+
+  # Something bad happened while parsing the incoming stream
+  #
+  # @handler :parse_error
+  class ParseError < BlatherError
+    register :parse_error
+    attr_reader :message
+
+    def initialize(msg)
+      @message = msg.to_s
+    end
+  end  # ParseError
+
+end  # Blather