blather 0.2.1 → 0.2.2

data/lib/blather/client/dsl.rb

@@ -0,0 +1,99 @@
+require File.join(File.dirname(__FILE__), 'client')
+
+module Blather
+  module DSL
+    def client
+      @client ||= Client.new
+    end
+    module_function :client
+
+    ##
+    # Prepare server settings
+    #   setup [node@domain/resource], [password], [host], [port]
+    # host and port are optional defaulting to the domain in the JID and 5222 respectively
+    def setup(jid, password, host = nil, port = nil)
+      client.setup(jid, password, host, port)
+      at_exit { client.run }
+    end
+
+    ##
+    # Shutdown the connection.
+    # Flushes the write buffer then stops EventMachine
+    def shutdown
+      client.stop
+    end
+
+    ##
+    # Set handler for a stanza type
+    def handle(stanza_type, *guards, &block)
+      client.register_handler stanza_type, *guards, &block
+    end
+
+    ##
+    # Wrapper for "handle :ready" (just a bit of syntactic sugar)
+    def when_ready(&block)
+      handle :ready, &block
+    end
+
+    ##
+    # Set current status
+    def status(state = nil, msg = nil)
+      client.status = state, msg
+    end
+
+    ##
+    # Direct access to the roster
+    def roster
+      client.roster
+    end
+
+    ##
+    # Write data to the stream
+    # Anything that resonds to #to_s can be paseed to the stream
+    def write(stanza)
+      client.write(stanza)
+    end
+
+    ##
+    # Helper method to make sending basic messages easier
+    #   say [jid], [msg]
+    def say(to, msg)
+      client.write Blather::Stanza::Message.new(to, msg)
+    end
+
+    ##
+    # Wrapper to grab the current JID
+    def jid
+      client.jid
+    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.temporary_handler stanza.id, &callback
+      write stanza
+    end
+
+    ##
+    # PubSub proxy
+    def pubsub
+      client.pubsub
+    end
+
+    ##
+    # Checks to see if the method is part of the handlers list.
+    # If so it creates a handler, otherwise it'll pass it back
+    # to Ruby's method_missing handler
+    def method_missing(method, *args, &block)
+      if Blather::Stanza.handler_list.include?(method)
+        handle method, *args, &block
+      else
+        super
+      end
+    end
+  end #DSL
+end #Blather

data/lib/blather/client/pubsub.rb

@@ -0,0 +1,53 @@
+module Blather
+class Client
+
+  class PubSub
+    attr_accessor :host
+
+    def affiliations(&callback)
+      request Stanza::PubSub::Affiliations.new(:get, @host), :affiliates, callback
+    end
+
+    def subscriptions(&callback)
+      request Stanza::PubSub::Subscriptions.new(:get, @host), :subscriptions, callback
+    end
+
+    def nodes(path, &callback)
+      stanza = Stanza::DiscoItems.new(:get, path)
+      stanza.to = @host
+      request stanza, :items, callback
+    end
+
+    def node(path)
+      stanza = Stanza::DiscoInfo.new(:get, path)
+      stanza.to = @host
+      request(stanza) { |node| yield Stanza::PubSub::Node.import(node) }
+    end
+
+    def items(path, list = [], max = nil, &callback)
+      request Stanza::PubSub.items(@host, path, list, max), :items, callback
+    end
+=begin
+    def create(node)
+    end
+
+    def publish(node, payload)
+    end
+
+    def subscribe(node)
+      DSL.client.write Stanza::PubSub::Subscribe.new(:set, host, node, DSL.client.jid)
+    end
+
+    def unsubscribe(node)
+      DSL.client.write Stanza::PubSub::Unsubscribe.new(:set, host, node, DSL.client.jid)
+    end
+=end
+  private
+    def request(node, method = nil, callback, &block)
+      block = lambda { |node| callback.call node.__send__(method) } unless block_given?
+      DSL.client.write_with_handler(node, &block)
+    end
+  end
+
+end
+end

data/lib/blather/client/pubsub/node.rb

@@ -0,0 +1,27 @@
+module Blather
+class Client
+class PubSub
+
+  class Node
+    attr_accessor :path
+
+    def initialize(path)
+      @path = path
+    end
+
+    def info(&block)
+      DSL.client.write_with_handler Stanza::DiscoInfo.new(:get, path), &block
+    end
+
+    def items(&block)
+      DSL.client.write_with_handler Stanza::PubSub.items(path), &block
+    end
+
+    def nodes(&block)
+      DSL.client.write_with_handler Stanza::DiscoItems.new(:get, path), &block
+    end
+  end
+
+end #PubSub
+end #Client
+end #Blather

data/lib/blather/core_ext/active_support.rb

@@ -124,6 +124,7 @@ end
 
 class Array #:nodoc:
   alias_method :blank?, :empty?
+  def extract_options!; last.is_a?(::Hash) ? pop : {}; end
 end
 
 class Hash #:nodoc:

data/lib/blather/core_ext/libxml.rb

@@ -3,6 +3,7 @@ module LibXML # :nodoc:
 
     class Node
       alias_method :element_name, :name
+      alias_method :element_name=, :name=
     end
 
     class Attributes
@@ -12,10 +13,15 @@ module LibXML # :nodoc:
         attribute.remove! if attribute
       end
 
-      alias_method :old_hash_set, :[]=
+      alias_method :old_hash_set, :[]= # :nodoc:
       def []=(name, val)
         val.nil? ? remove(name.to_s) : old_hash_set(name.to_s, val.to_s)
       end
+
+      alias_method :old_hash_get, :[] # :nodoc:
+      def [](name)
+        old_hash_get name.to_s
+      end
     end #Attributes
 
   end #XML

data/lib/blather/errors.rb

@@ -1,27 +1,48 @@
 module Blather
   # Main error class
-  class BlatherError < StandardError; end
+  class BlatherError < StandardError
+    class_inheritable_array :handler_heirarchy
 
-    #Parse Errors
-    class ParseError < BlatherError; end
+    self.handler_heirarchy ||= []
+    self.handler_heirarchy << :error
 
-    # Stream errors
-    class StreamError < BlatherError
-      attr_accessor :type, :text
+    def self.register(handler)
+      self.handler_heirarchy.unshift handler
+    end
+  end
 
-      def initialize(node)
-        @type = node.detect { |n| n.name != 'text' && n['xmlns'] == 'urn:ietf:params:xml:ns:xmpp-streams' }
-        @text = node.detect { |n| n.name == 'text' }
+  ##
+  # Used in cases where a stanza only allows specific values for its attributes
+  # and an invalid value is attempted.
+  class ArgumentError < BlatherError
+    register :argument_error
+  end
 
-        @extra = node.detect { |n| n['xmlns'] != 'urn:ietf:params:xml:ns:xmpp-streams' }
-      end
+  ##
+  # The stream handler received a response it didn't know how to handle
+  class UnknownResponse < BlatherError
+    register :unknown_response_error
+    attr_reader :node
 
-      def to_s
-        "Stream Error (#{type.name}) #{"[#{@extra.name}]" if @extra}: #{text.content if text}"
-      end
+    def initialize(node)
+      @node = node
     end
+  end
+
+  ##
+  # TLS negotiations broke down
+  class TLSFailure < BlatherError
+    register :tls_failure
+  end
 
-    # Stanza errors
-    class StanzaError < BlatherError; end
-      class ArgumentError < StanzaError; end
-end
+  ##
+  # Something bad happened while parsing the incoming stream
+  class ParseError < BlatherError
+    register :parse_error
+    attr_reader :message
+
+    def initialize(message)
+      @message = message
+    end
+  end
+end

data/lib/blather/errors/sasl_error.rb

@@ -0,0 +1,87 @@
+module Blather
+
+class SASLError < BlatherError
+  class_inheritable_accessor :err_name
+  @@registrations = {}
+
+  register :sasl_error
+
+  ##
+  # Register the handler and type to simplify importing
+  def self.register(handler, err_name)
+    super handler
+    self.err_name = err_name
+    @@registrations[err_name] = self
+  end
+
+  ##
+  # Retreive an error class from a given name
+  def self.class_from_registration(err_name)
+    @@registrations[err_name.to_s] || self
+  end
+
+  ##
+  # Factory to create the proper error object from an error node
+  def self.import(node)
+    err_name = node.children.first.element_name
+    class_from_registration(err_name).new
+  end
+
+  ##
+  # XMPP defined error name
+  def err_name
+    self.class.err_name
+  end
+
+  ##
+  # The receiving entity acknowledges an <abort/> element sent by the initiating entity; sent in reply to the <abort/> element.
+  class Aborted < SASLError
+    register :sasl_aborted_error, 'aborted'
+  end
+
+  ##
+  # The data provided by the initiating entity could not be processed because the [BASE64] encoding is incorrect
+  # (e.g., because the encoding does not adhere to the definition in Section 3 of [BASE64]); sent in reply to a <response/>
+  # element or an <auth/> element with initial response data.
+  class IncorrectEncoding < SASLError
+    register :sasl_incorrect_encoding_error, 'incorrect-encoding'
+  end
+  
+  ##
+  # The authzid provided by the initiating entity is invalid, either because it is incorrectly formatted or because the
+  # initiating entity does not have permissions to authorize that ID; sent in reply to a <response/> element or an <auth/>
+  # element with initial response data.
+  class InvalidAuthzid < SASLError
+    register :sasl_invalid_authzid_error, 'invalid-authzid'
+  end
+  
+  ##
+  # The initiating entity did not provide a mechanism or requested a mechanism that is not supported by the receiving entity;
+  # sent in reply to an <auth/> element.
+  class InvalidMechanism < SASLError
+    register :sasl_invalid_mechanism_error, 'invalid-mechanism'
+  end
+  
+  ##
+  # The mechanism requested by the initiating entity is weaker than server policy permits for that initiating entity; sent in
+  # reply to a <response/> element or an <auth/> element with initial response data.
+  class MechanismTooWeak < SASLError
+    register :sasl_mechanism_too_weak_error, 'mechanism-too-weak'
+  end
+  
+  ##
+  # The authentication failed because the initiating entity did not provide valid credentials (this includes but is not limited
+  # to the case of an unknown username); sent in reply to a <response/> element or an <auth/> element with initial response data.
+  class NotAuthorized < SASLError
+    register :sasl_not_authorized_error, 'not-authorized'
+  end
+  
+  ##
+  # The authentication failed because of a temporary error condition within the receiving entity; sent in reply to an <auth/>
+  # element or <response/> element.
+  class TemporaryAuthFailure < SASLError
+    register :sasl_temporary_auth_failure_error, 'temporary-auth-failure'
+  end
+end #SASLError
+
+end #Blather

data/lib/blather/errors/stanza_error.rb

@@ -0,0 +1,262 @@
+module Blather
+
+##
+# Stanza errors
+# RFC3920 Section 9.3 (http://xmpp.org/rfcs/rfc3920.html#stanzas-error)
+class StanzaError < BlatherError
+  VALID_TYPES = [:cancel, :continue, :modify, :auth, :wait]
+
+  class_inheritable_accessor :err_name
+  @@registrations = {}
+  
+  register :stanza_error
+
+  attr_reader :original, :type, :text, :extras
+
+  ##
+  # Register the handler and type to simplify importing
+  def self.register(handler, err_name)
+    super handler
+    self.err_name = err_name
+    @@registrations[err_name] = self
+  end
+
+  ##
+  # Retreive an error class from a given name
+  def self.class_from_registration(err_name)
+    @@registrations[err_name.to_s] || self
+  end
+
+  ##
+  # Factory method for instantiating the proper class
+  # for the error
+  def self.import(node)
+    original = node.copy
+    original.remove_child 'error'
+
+    error_node = node.find_first 'child::error'
+
+    name = error_node.find_first('child::*[name()!="text"]', 'urn:ietf:params:xml:ns:xmpp-stanzas').element_name
+    type = error_node['type']
+    text = node.find_first 'descendant::text', 'urn:ietf:params:xml:ns:xmpp-stanzas'
+    text = text.content if text
+
+    extras = error_node.find("descendant::*[name()!='text' and name()!='#{name}']").map { |n| n }
+
+    class_from_registration(name).new original, type, text, extras
+  end
+
+  ##
+  # <tt>original</tt> An original node must be provided for stanza errors. You can't declare
+  # a stanza error on without a stanza.
+  # <tt>type</tt> is the error type specified in RFC3920 (http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.3.2)
+  # <tt>text</tt> is an option error description
+  # <tt>extras</tt> an array of application specific nodes to add to the error. These should be properly namespaced.
+  def initialize(original, type, text = nil, extras = [])
+    @original = original
+    self.type = type
+    @text = text
+    @extras = extras
+  end
+
+  ##
+  # XMPP defined error name
+  def err_name
+    self.class.err_name
+  end
+
+  ##
+  # Set the error type (see RFC3920 Section 9.3.2 (http://xmpp.org/rfcs/rfc3920.html#rfc.section.9.3.2))
+  def type=(type)
+    type = type.to_sym
+    raise ArgumentError, "Invalid Type (#{type}), use: #{VALID_TYPES*' '}" if !VALID_TYPES.include?(type)
+    @type = type
+  end
+
+  ##
+  # Creates an XML node from the error
+  def to_node
+    node = self.original.reply
+
+    error_node = XMPPNode.new 'error'
+    err = XMPPNode.new(self.err_name)
+    err.namespace = 'urn:ietf:params:xml:ns:xmpp-stanzas'
+    error_node << err
+
+    if self.text
+      text = XMPPNode.new('text')
+      text.namespace = 'urn:ietf:params:xml:ns:xmpp-stanzas'
+      text << self.text
+      error_node << text
+    end
+
+    self.extras.each do |extra|
+      extra_copy = extra.copy
+      extra_copy.namespace = extra.namespace
+      error_node << extra_copy
+    end
+
+    node << error_node
+    node.type = 'error'
+    node
+  end
+
+  ##
+  # Turns the object into XML fit to be sent over the stream
+  def to_xml
+    to_node.to_s
+  end
+
+  def inspect # :nodoc:
+    "Stanza Error (#{self.err_name}): #{self.text}"
+  end
+  alias_method :to_s, :inspect # :nodoc:
+
+  ##
+  # The sender has sent XML that is malformed or that cannot be processed (e.g., an IQ stanza that includes
+  # an unrecognized value of the 'type' attribute); the associated error type SHOULD be "modify"
+  class BadRequest < StanzaError
+    register :stanza_bad_request_error, 'bad-request'
+  end
+
+  ##
+  # Access cannot be granted because an existing resource or session exists with the same name or address;
+  # the associated error type SHOULD be "cancel"
+  class Conflict < StanzaError
+    register :stanza_conflict_error, 'conflict'
+  end
+
+  ##
+  # the feature requested is not implemented by the recipient or server and therefore cannot be processed;
+  # the associated error type SHOULD be "cancel".
+  class FeatureNotImplemented < StanzaError
+    register :stanza_feature_not_implemented_error, 'feature-not-implemented'
+  end
+
+  ##
+  # the requesting entity does not possess the required permissions to perform the action;
+  # the associated error type SHOULD be "auth".
+  class Forbidden < StanzaError
+    register :stanza_forbidden_error, 'forbidden'
+  end
+
+  ##
+  # the recipient or server can no longer be contacted at this address (the error stanza MAY contain a new address
+  # in the XML character data of the <gone/> element); the associated error type SHOULD be "modify".
+  class Gone < StanzaError
+    register :stanza_gone_error, 'gone'
+  end
+
+  ##
+  # the server could not process the stanza because of a misconfiguration or an otherwise-undefined internal server error;
+  # the associated error type SHOULD be "wait".
+  class InternalServerError < StanzaError
+    register :stanza_internal_server_error, 'internal-server-error'
+  end
+
+  ##
+  # the addressed JID or item requested cannot be found; the associated error type SHOULD be "cancel".
+  class ItemNotFound < StanzaError
+    register :stanza_item_not_found_error, 'item-not-found'
+  end
+
+  ##
+  # the addressed JID or item requested cannot be found; the associated error type SHOULD be "cancel".
+  class JidMalformed < StanzaError
+    register :stanza_jid_malformed_error, 'jid-malformed'
+  end
+
+  ##
+  # the recipient or server understands the request but is refusing to process it because it does not meet criteria defined
+  # by the recipient or server (e.g., a local policy regarding acceptable words in messages); the associated error type SHOULD be "modify".
+  class NotAcceptable < StanzaError
+    register :stanza_not_acceptable_error, 'not-acceptable'
+  end
+
+  ##
+  # The recipient or server does not allow any entity to perform the action; the associated error type SHOULD be "cancel".
+  class NotAllowed < StanzaError
+    register :stanza_not_allowed_error, 'not-allowed'
+  end
+
+  ##
+  # the sender must provide proper credentials before being allowed to perform the action, or has provided improper credentials;
+  # the associated error type SHOULD be "auth".
+  class NotAuthorized < StanzaError
+    register :stanza_not_authorized_error, 'not-authorized'
+  end
+
+  ##
+  # the requesting entity is not authorized to access the requested service because payment is required; the associated error type SHOULD be "auth".
+  class PaymentRequired < StanzaError
+    register :stanza_payment_required_error, 'payment-required'
+  end
+
+  ##
+  # the intended recipient is temporarily unavailable; the associated error type SHOULD be "wait" (note: an application MUST NOT
+  # return this error if doing so would provide information about the intended recipient's network availability to an entity that
+  # is not authorized to know such information).
+  class RecipientUnavailable < StanzaError
+    register :stanza_recipient_unavailable_error, 'recipient-unavailable'
+  end
+
+  ##
+  # the recipient or server is redirecting requests for this information to another entity, usually temporarily (the error stanza SHOULD contain
+  # the alternate address, which MUST be a valid JID, in the XML character data of the <redirect/> element); the associated error type SHOULD be "modify".
+  class Redirect < StanzaError
+    register :stanza_redirect_error, 'redirect'
+  end
+
+  ##
+  # the requesting entity is not authorized to access the requested service because registration is required; the associated error type SHOULD be "auth".
+  class RegistrationRequired < StanzaError
+    register :stanza_registration_required_error, 'registration-required'
+  end
+
+  ##
+  # a remote server or service specified as part or all of the JID of the intended recipient does not exist; the associated error type SHOULD be "cancel".
+  class RemoteServerNotFound < StanzaError
+    register :stanza_remote_server_not_found_error, 'remote-server-not-found'
+  end
+
+  ##
+  # a remote server or service specified as part or all of the JID of the intended recipient (or required to fulfill a request) could not be
+  # contacted within a reasonable amount of time; the associated error type SHOULD be "wait".
+  class RemoteServerTimeout < StanzaError
+    register :stanza_remote_server_timeout_error, 'remote-server-timeout'
+  end
+
+  ##
+  # the server or recipient lacks the system resources necessary to service the request; the associated error type SHOULD be "wait".
+  class ResourceConstraint < StanzaError
+    register :stanza_resource_constraint_error, 'resource-constraint'
+  end
+
+  ##
+  # the server or recipient does not currently provide the requested service; the associated error type SHOULD be "cancel".
+  class ServiceUnavailable < StanzaError
+    register :stanza_service_unavailable_error, 'service-unavailable'
+  end
+
+  ##
+  # the requesting entity is not authorized to access the requested service because a subscription is required; the associated error type SHOULD be "auth".
+  class SubscriptionRequired < StanzaError
+    register :stanza_subscription_required_error, 'subscription-required'
+  end
+
+  ##
+  # the error condition is not one of those defined by the other conditions in this list; any error type may be associated with this condition,
+  # and it SHOULD be used only in conjunction with an application-specific condition.
+  class UndefinedCondition < StanzaError
+    register :stanza_undefined_condition_error, 'undefined-condition'
+  end
+
+  ##
+  # the recipient or server understood the request but was not expecting it at this time (e.g., the request was out of order);
+  # the associated error type SHOULD be "wait".
+  class UnexpectedRequest < StanzaError
+    register :stanza_unexpected_request_error, 'unexpected-request'
+  end
+end #StanzaError
+
+end #Blather