blather 0.4.16 → 0.5.0

data/lib/blather/client/dsl.rb

@@ -217,8 +217,7 @@ module Blather
     #
     # Use this to stop the propogation of the stanza though the handler chain.
     #
-    # @example
-    # Ignore all IQ stanzas
+    # @example Ignore all IQ stanzas
     #
     #     before(:iq) { halt }
     def halt
@@ -230,7 +229,8 @@ module Blather
     # Use this to jump out of the current handler and let the next registered
     # handler take care of the stanza
     #
-    # @example
+    # @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
     #
@@ -252,12 +252,18 @@ module Blather
       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

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

@@ -1,6 +1,8 @@
 module Blather
 module DSL
 
+  # A helper class for providing a simplified PubSub interface to the
+  # DSL
   class PubSub
     attr_accessor :host
 

data/lib/blather/core_ext/eventmachine.rb

@@ -1,4 +1,6 @@
+# @private
 module EventMachine
+  # @private
   module Protocols
     # Basic SOCKS v5 client implementation
     #
@@ -16,6 +18,7 @@ module EventMachine
     #
     # EM.connect socks_host, socks_port, MyConn, host, port
     #
+    # @private
     class Socks5 < Connection
       def initialize(host, port)
         @host = host
@@ -119,4 +122,4 @@ module EventMachine
       end
     end
   end
-end
+end

data/lib/blather/core_ext/ipaddr.rb

@@ -1,3 +1,4 @@
+# @private
 class IPAddr
   PrivateRanges = [
     IPAddr.new("10.0.0.0/8"),
@@ -16,4 +17,4 @@ class IPAddr
   def public?
     !private?
   end
-end
+end

data/lib/blather/core_ext/nokogiri.rb

@@ -1,12 +1,14 @@
+# @private
 module Nokogiri
 module XML
 
+  # Nokogiri::Node extensions
   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:
+    alias_method :attr_set, :[]=
     # 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
     #

data/lib/blather/errors/sasl_error.rb

@@ -5,6 +5,7 @@ module Blather
 #
 # @handler :sasl_error
 class SASLError < BlatherError
+  # @private
   SASL_ERR_NS = 'urn:ietf:params:xml:ns:xmpp-sasl'
 
   class_inheritable_accessor :err_name

data/lib/blather/errors/stanza_error.rb

@@ -5,7 +5,9 @@ module Blather
 #
 # @handler :stanza_error
 class StanzaError < BlatherError
+  # @private
   STANZA_ERR_NS = 'urn:ietf:params:xml:ns:xmpp-stanzas'
+  # @private
   VALID_TYPES = [:cancel, :continue, :modify, :auth, :wait].freeze
 
   register :stanza_error
@@ -105,4 +107,4 @@ class StanzaError < BlatherError
   alias_method :to_s, :inspect
 end  # StanzaError
 
-end  # Blather
+end  # Blather

data/lib/blather/errors/stream_error.rb

@@ -5,6 +5,7 @@ module Blather
 #
 # @handler :stream_error
 class StreamError < BlatherError
+  # @private
   STREAM_ERR_NS = 'urn:ietf:params:xml:ns:xmpp-streams'
 
   register :stream_error

data/lib/blather/file_transfer.rb

@@ -82,19 +82,22 @@ module Blather
         @transferred = 0
       end
 
+      # @private
       def post_init
         @file = File.open(@path, "w")
       end
 
+      # @private
       def receive_data(data)
         @transferred += data.size
         @file.write data
       end
 
+      # @private
       def unbind
         @file.close
         File.delete(@path) unless @transferred == @size
       end
     end
   end
-end
+end

data/lib/blather/file_transfer/s5b.rb

@@ -85,6 +85,7 @@ module Blather
         end
       end
 
+      # @private
       class SocketConnection < EM::P::Socks5
         include EM::Deferrable
 
@@ -96,9 +97,7 @@ module Blather
 
         def post_init
           self.succeed
-          class << self
-            include @@handler
-          end
+          (class << self; self; end).include(@@handler)
           send(:initialize, *@params)
           post_init
         end
@@ -109,4 +108,4 @@ module Blather
       end
     end
   end
-end
+end

data/lib/blather/jid.rb

@@ -46,12 +46,14 @@ module Blather
   class JID
     include Comparable
 
+    # Validating pattern for JID string
     PATTERN = /^(?:([^@]*)@)??([^@\/]*)(?:\/(.*?))?$/.freeze
 
     attr_reader :node,
                 :domain,
                 :resource
 
+    # @private
     def self.new(node, domain = nil, resource = nil)
       node.is_a?(JID) ? node : super
     end

data/lib/blather/roster_item.rb

@@ -3,6 +3,7 @@ module Blather
   # RosterItems hold internal representations of the user's roster
   # including each JID's status.
   class RosterItem
+    # @private
     VALID_SUBSCRIPTION_TYPES = [:both, :from, :none, :remove, :to].freeze
 
     attr_reader :jid,
@@ -12,6 +13,7 @@ module Blather
     attr_accessor :name,
                   :groups
 
+    # @private
     def self.new(item)
       return item if item.is_a?(self)
       super
@@ -118,8 +120,12 @@ module Blather
       r
     end
 
-    def <=>(o)
-      self.jid.to_s <=> o.jid.to_s
+    # Compare two RosterItems by their JID
+    #
+    # @param [Blather::JID] other the JID to compare against
+    # @return [Fixnum<-1, 0, 1>]
+    def <=>(other)
+      JID.new(self.jid) <=> JID.new(other.jid)
     end
 
     # Compare two RosterItem objects by name, type and category
@@ -130,7 +136,11 @@ module Blather
       o.jid == self.jid &&
       o.groups == self.groups
     end
-    alias_method :==, :eql?
+
+    # @private
+    def ==(o)
+      eql?(o)
+    end
   end #RosterItem
 
 end

data/lib/blather/stanza.rb

@@ -54,16 +54,24 @@ module Blather
 
     # Creates a copy with to and from swapped
     #
+    # @param [Hash] opts options to pass to reply!
+    # @option opts [Boolean] :remove_children Wether or not to remove child nodes when replying
+    #
     # @return [Blather::Stanza]
-    def reply
-      self.dup.reply!
+    def reply(opts = {})
+      self.dup.reply! opts
     end
 
     # Swaps from and to
     #
+    # @param [Hash] opts Misc options
+    # @option opts [Boolean] :remove_children Wether or not to remove child nodes when replying
+    #
     # @return [self]
-    def reply!
+    def reply!(opts = {})
+      opts = {:remove_children => false}.merge opts
       self.to, self.from = self.from, self.to
+      self.children.remove if opts[:remove_children]
       self
     end
 

data/lib/blather/stanza/disco/capabilities.rb

@@ -0,0 +1,161 @@
+module Blather
+class Stanza
+
+  # # Capabilities Stanza
+  #
+  # [XEP-0115 Entity Capabilities](http://xmpp.org/extensions/xep-0115.html)
+  #
+  # XMPP protocol extension for broadcasting and dynamically discovering client, device, or generic entity capabilities.
+  #
+  class Capabilities < Blather::Stanza::DiscoInfo
+    def self.new
+      super :result
+    end
+
+    # A string that is used to verify the identity and supported features of the entity.
+    #
+    # @return [String]
+    def ver
+      generate_ver identities, features
+    end
+
+    # A URI that uniquely identifies a software application, typically a URL at the
+    # website of the project or company that produces the software.
+    #
+    # @param [String] node the node URI
+    def node=(node)
+      @bare_node = node
+      super "#{node}##{ver}"
+    end
+
+    # Add an array of identities
+    # @param identities the array of identities, passed directly to Identity.new
+    def identities=(identities)
+      super identities
+      regenerate_full_node
+    end
+
+    # Add an array of features
+    # @param features the array of features, passed directly to Feature.new
+    def features=(features)
+      super features
+      regenerate_full_node
+    end
+
+    # The generated Presence::C node
+    #
+    # @return [Blather::Stanza::Presence::C]
+    def c
+      Blather::Stanza::Presence::C.new @bare_node, ver
+    end
+
+    private
+
+    def regenerate_full_node
+      self.node = @bare_node
+    end
+
+    def generate_ver_str(identities, features, forms = [])
+      # 1.  Initialize an empty string S.
+      s = ''
+
+      # 2. Sort the service discovery identities by category and
+      # then by type (if it exists) and then by xml:lang (if it
+      # exists), formatted as CATEGORY '/' [TYPE] '/' [LANG] '/'
+      # [NAME]. Note that each slash is included even if the TYPE,
+      # LANG, or NAME is not included.
+      identities.sort! do |identity1, identity2|
+        cmp_result = nil
+        [:category, :type, :xml_lang, :name].each do |field|
+          value1 = identity1.send(field)
+          value2 = identity2.send(field)
+
+          if value1 != value2
+            cmp_result = value1 <=> value2
+            break
+          end
+        end
+        cmp_result
+      end
+
+      # 3. For each identity, append the 'category/type/lang/name' to
+      # S, followed by the '<' character.
+      s += identities.collect do |identity|
+        [:category, :type, :xml_lang, :name].collect do |field|
+          identity.send(field).to_s
+        end.join('/') + '<'
+      end.join
+
+      # 4. Sort the supported service discovery features.
+      features.sort! { |feature1, feature2| feature1.var <=> feature2.var }
+
+      # 5. For each feature, append the feature to S, followed by the
+      # '<' character.
+      s += features.collect { |feature| feature.var.to_s + '<' }.join
+
+      # 6. If the service discovery information response includes
+      # XEP-0128 data forms, sort the forms by the FORM_TYPE (i.e., by
+      # the XML character data of the <value/> element).
+      forms.sort! do |form1, form2|
+        fform_type1 = form1.field 'FORM_TYPE'
+        fform_type2 = form2.field 'FORM_TYPE'
+        form_type1 = fform_type1 ? fform_type1.values.to_s : nil
+        form_type2 = fform_type2 ? fform_type2.values.to_s : nil
+        form_type1 <=> form_type2
+      end
+
+      # 7. For each extended service discovery information form:
+      forms.each do |form|
+        # 7.1. Append the XML character data of the FORM_TYPE field's
+        # <value/> element, followed by the '<' character.
+        fform_type = form.field 'FORM_TYPE'
+        form_type = fform_type ? fform_type.values.to_s : nil
+        s += "#{form_type}<"
+
+        # 7.2. Sort the fields by the value of the "var" attribute
+        fields = form.fields.sort { |field1, field2| field1.var <=> field2.var }
+
+        # 7.3. For each field:
+        fields.each do |field|
+          # 7.3.1. Append the value of the "var" attribute, followed by
+          # the '<' character.
+          s += "#{field.var}<"
+
+          # 7.3.2. Sort values by the XML character data of the <value/> element
+          # values = field.values.sort { |value1, value2| value1 <=> value2 }
+
+          # 7.3.3. For each <value/> element, append the XML character
+          # data, followed by the '<' character.
+          # s += values.collect { |value| "#{value}<" }.join
+          s += "#{field.value}<"
+        end
+      end
+      s
+    end
+
+    def generate_ver(identities, features, forms = [], hash = 'sha-1')
+      s = generate_ver_str identities, features, forms
+
+      # 9. Compute the verification string by hashing S using the
+      # algorithm specified in the 'hash' attribute (e.g., SHA-1 as
+      # defined in RFC 3174). The hashed data MUST be generated
+      # with binary output and encoded using Base64 as specified in
+      # Section 4 of RFC 4648 (note: the Base64 output MUST NOT
+      # include whitespace and MUST set padding bits to zero).
+
+      # See http://www.iana.org/assignments/hash-function-text-names
+      hash_klass = case hash
+                     when 'md2' then nil
+                     when 'md5' then Digest::MD5
+                     when 'sha-1' then Digest::SHA1
+                     when 'sha-224' then nil
+                     when 'sha-256' then Digest::SHA256
+                     when 'sha-384' then Digest::SHA384
+                     when 'sha-512' then Digest::SHA512
+                   end
+      hash_klass ? [hash_klass::digest(s)].pack('m').strip : nil
+    end
+  end # Caps
+
+end # Stanza
+end # Blather

data/lib/blather/stanza/disco/disco_info.rb

@@ -66,8 +66,9 @@ class Stanza
       super o, *(fields + [:identities, :features])
     end
 
+    # DiscoInfo::Identity
     class Identity < XMPPNode
-      # Create a new DiscoInfo Identity
+      # Create a new DiscoInfo::Identity
       # @overload new(node)
       #   Imports the XML::Node to create a Identity object
       #   @param [XML::Node] node the node object to import
@@ -158,6 +159,7 @@ class Stanza
       end
     end # Identity
 
+    # DiscoInfo::Feature
     class Feature < XMPPNode
       # Create a new DiscoInfo::Feature object
       # @overload new(node)