shingara-blather 0.4.8

data/lib/blather/jid.rb

@@ -0,0 +1,142 @@
+module Blather
+
+  # Jabber ID or JID
+  #
+  # See [RFC 3920 Section 3 - Addressing](http://xmpp.org/rfcs/rfc3920.html#addressing)
+  #
+  # An entity is anything that can be considered a network endpoint (i.e., an
+  # ID on the network) and that can communicate using XMPP. All such entities
+  # are uniquely addressable in a form that is consistent with RFC 2396 [URI].
+  # For historical reasons, the address of an XMPP entity is called a Jabber
+  # Identifier or JID. A valid JID contains a set of ordered elements formed
+  # of a domain identifier, node identifier, and resource identifier.
+  #
+  # The syntax for a JID is defined below using the Augmented Backus-Naur Form
+  # as defined in [ABNF]. (The IPv4address and IPv6address rules are defined
+  # in Appendix B of [IPv6]; the allowable character sequences that conform to
+  # the node rule are defined by the Nodeprep profile of [STRINGPREP] as
+  # documented in Appendix A of this memo; the allowable character sequences
+  # that conform to the resource rule are defined by the Resourceprep profile
+  # of [STRINGPREP] as documented in Appendix B of this memo; and the
+  # sub-domain rule makes reference to the concept of an internationalized
+  # domain label as described in [IDNA].)
+  #
+  #     jid             = [ node "@" ] domain [ "/" resource ]
+  #     domain          = fqdn / address-literal
+  #     fqdn            = (sub-domain 1*("." sub-domain))
+  #     sub-domain      = (internationalized domain label)
+  #     address-literal = IPv4address / IPv6address
+  #
+  # All JIDs are based on the foregoing structure. The most common use of this
+  # structure is to identify an instant messaging user, the server to which
+  # the user connects, and the user's connected resource (e.g., a specific
+  # client) in the form of <user@host/resource>. However, node types other
+  # than clients are possible; for example, a specific chat room offered by a
+  # multi-user chat service could be addressed as <room@service> (where "room"
+  # is the name of the chat room and "service" is the hostname of the
+  # multi-user chat service) and a specific occupant of such a room could be
+  # addressed as <room@service/nick> (where "nick" is the occupant's room
+  # nickname). Many other JID types are possible (e.g., <domain/resource>
+  # could be a server-side script or service).
+  #
+  # Each allowable portion of a JID (node identifier, domain identifier, and
+  # resource identifier) MUST NOT be more than 1023 bytes in length, resulting
+  # in a maximum total size (including the '@' and '/' separators) of 3071
+  # bytes.
+  class JID
+    include Comparable
+
+    PATTERN = /^(?:([^@]*)@)??([^@\/]*)(?:\/(.*?))?$/.freeze
+
+    attr_reader :node,
+                :domain,
+                :resource
+
+    def self.new(node, domain = nil, resource = nil)
+      node.is_a?(JID) ? node : super
+    end
+
+    # Create a new JID object
+    #
+    # @overload initialize(jid)
+    #   Passes the jid object right back out
+    #   @param [Blather::JID] jid a jid object
+    # @overload initialize(jid)
+    #   Creates a new JID parsed out of the provided jid
+    #   @param [String] jid a jid in the standard format
+    #   ("node@domain/resource")
+    # @overload initialize(node, domain = nil, resource = nil)
+    #   Creates a new JID
+    #   @param [String] node the node of the JID
+    #   @param [String, nil] domian the domain of the JID
+    #   @param [String, nil] resource the resource of the JID
+    # @raise [ArgumentError] if the parts of the JID are too large (1023 bytes)
+    # @return [Blather::JID] a new jid object
+    def initialize(node, domain = nil, resource = nil)
+      @resource = resource
+      @domain = domain
+      @node = node
+
+      if @domain.nil? && @resource.nil?
+        @node, @domain, @resource = @node.to_s.scan(PATTERN).first
+      end
+
+      @node.downcase!   if @node
+      @domain.downcase! if @domain
+
+      raise ArgumentError, 'Node too long' if (@node || '').length > 1023
+      raise ArgumentError, 'Domain too long' if (@domain || '').length > 1023
+      raise ArgumentError, 'Resource too long' if (@resource || '').length > 1023
+    end
+
+    # Turn the JID into a string
+    #
+    # * ""
+    # * "domain"
+    # * "node@domain"
+    # * "domain/resource"
+    # * "node@domain/resource"
+    #
+    # @return [String] the JID as a string
+    def to_s
+      s = @domain
+      s = "#{@node}@#{s}" if @node
+      s = "#{s}/#{@resource}" if @resource
+      s
+    end
+
+    # Returns a new JID with resource removed.
+    #
+    # @return [Blather::JID] a new JID without a resource
+    def stripped
+      dup.strip!
+    end
+
+    # Removes the resource (sets it to nil)
+    #
+    # @return [Blather::JID] the JID without a resource
+    def strip!
+      @resource = nil
+      self
+    end
+
+    # Compare two JIDs, helpful for sorting etc.
+    #
+    # String representations are compared, see JID#to_s
+    #
+    # @param [#to_s] other a JID to comare against
+    # @return [Fixnum<-1, 0, 1>]
+    def <=>(other)
+      to_s <=> other.to_s
+    end
+    alias_method :eql?, :==
+
+    # Test if JID is stripped
+    #
+    # @return [true, false]
+    def stripped?
+      @resource.nil?
+    end
+  end  # JID
+
+end  # Blather

data/lib/blather/roster.rb

@@ -0,0 +1,111 @@
+module Blather
+
+  # Local Roster
+  # Takes care of adding/removing JIDs through the stream
+  class Roster
+    include Enumerable
+
+    # Create a new roster
+    #
+    # @param [Blather::Stream] stream the stream the roster should use to
+    # update roster entries
+    # @param [Blather::Stanza::Roster] stanza a roster stanza used to preload
+    # the roster
+    # @return [Blather::Roster]
+    def initialize(stream, stanza = nil)
+      @stream = stream
+      @items = {}
+      stanza.items.each { |i| push i, false } if stanza
+    end
+
+    # Process any incoming stanzas and either adds or removes the
+    # corresponding RosterItem
+    #
+    # @param [Blather::Stanza::Roster] stanza a roster stanza
+    def process(stanza)
+      stanza.items.each do |i|
+        case i.subscription
+        when :remove then @items.delete(key(i.jid))
+        else @items[key(i.jid)] = RosterItem.new(i)
+        end
+      end
+    end
+
+    # Pushes a JID into the roster
+    #
+    # @param [String, Blather::JID, #jid] elem a JID to add to the roster
+    # @return [self]
+    # @see #push
+    def <<(elem)
+      push elem
+      self
+    end
+
+    # Push a JID into the roster and update the server
+    #
+    # @param [String, Blather::JID, #jid] elem a jid to add to the roster
+    # @param [true, false] send send the update over the wire
+    # @see Blather::JID
+    def push(elem, send = true)
+      jid = elem.respond_to?(:jid) ? elem.jid : JID.new(elem)
+      @items[key(jid)] = node = RosterItem.new(elem)
+
+      @stream.write(node.to_stanza(:set)) if send
+    end
+    alias_method :add, :push
+
+    # Remove a JID from the roster and update the server
+    #
+    # @param [String, Blather::JID] jid the JID to remove from the roster
+    def delete(jid)
+      @items.delete key(jid)
+      item = Stanza::Iq::Roster::RosterItem.new(jid, nil, :remove)
+      @stream.write Stanza::Iq::Roster.new(:set, item)
+    end
+    alias_method :remove, :delete
+
+    # Get a RosterItem by JID
+    #
+    # @param [String, Blather::JID] jid the jid of the item to return
+    # @return [Blather::RosterItem, nil] the associated RosterItem
+    def [](jid)
+      items[key(jid)]
+    end
+
+    # Iterate over all RosterItems
+    #
+    # @yield [Blather::RosterItem] yields each RosterItem
+    def each(&block)
+      items.each &block
+    end
+
+    # Get a duplicate of all RosterItems
+    #
+    # @return [Array<Blather::RosterItem>] a duplicate of all RosterItems
+    def items
+      @items.dup
+    end
+
+    # A hash of items keyed by group
+    #
+    # @return [Hash<group => Array<RosterItem>>]
+    def grouped
+      self.inject(Hash.new{|h,k|h[k]=[]}) do |hash, item|
+        item[1].groups.each { |group| hash[group] << item[1] }
+        hash
+      end
+    end
+
+  private
+    # Creates a stripped jid
+    def self.key(jid)
+      JID.new(jid).stripped.to_s
+    end
+
+    # Instance method to wrap around the class method
+    def key(jid)
+      self.class.key(jid)
+    end
+  end  # Roster
+
+end  # Blather

data/lib/blather/roster_item.rb

@@ -0,0 +1,122 @@
+module Blather
+
+  # RosterItems hold internal representations of the user's roster
+  # including each JID's status.
+  class RosterItem
+    VALID_SUBSCRIPTION_TYPES = [:both, :from, :none, :remove, :to].freeze
+
+    attr_reader :jid,
+                :ask,
+                :statuses
+
+    attr_accessor :name,
+                  :groups
+
+    def self.new(item)
+      return item if item.is_a?(self)
+      super
+    end
+
+    # Create a new RosterItem
+    #
+    # @overload initialize(jid)
+    #   Create a new RosterItem based on a JID
+    #   @param [Blather::JID] jid the JID object
+    # @overload initialize(jid)
+    #   Create a new RosterItem based on a JID string
+    #   @param [String] jid a JID string
+    # @overload initialize(node)
+    #   Create a new RosterItem based on a stanza
+    #   @param [Blather::Stanza::Iq::Roster::RosterItem] node a RosterItem
+    #   stanza
+    # @return [Blather::RosterItem] the new RosterItem
+    def initialize(item)
+      @statuses = []
+      @groups = []
+
+      case item
+      when JID
+        self.jid = item.stripped
+      when String
+        self.jid = JID.new(item).stripped
+      when XMPPNode
+        self.jid          = JID.new(item[:jid]).stripped
+        self.name         = item[:name]
+        self.subscription = item[:subscription]
+        self.ask          = item[:ask]
+        item.groups.each { |g| @groups << g }
+      end
+
+      @groups = [nil] if @groups.empty?
+    end
+
+    # Set the jid
+    #
+    # @param [String, Blather::JID] jid the new jid
+    # @see Blather::JID
+    def jid=(jid)
+      @jid = JID.new(jid).stripped
+    end
+
+    # Set the subscription
+    # Ensures it is one of VALID_SUBSCRIPTION_TYPES
+    #
+    # @param [#to_sym] sub the new subscription
+    def subscription=(sub)
+      if sub && !VALID_SUBSCRIPTION_TYPES.include?(sub = sub.to_sym)
+        raise ArgumentError, "Invalid Type (#{sub}), use: #{VALID_SUBSCRIPTION_TYPES*' '}"
+      end
+      @subscription = sub ? sub : :none
+    end
+
+    # Get the current subscription
+    #
+    # @return [:both, :from, :none, :remove, :to]
+    def subscription
+      @subscription || :none
+    end
+
+    # Set the ask value
+    #
+    # @param [nil, :subscribe] ask the new ask
+    def ask=(ask)
+      if ask && (ask = ask.to_sym) != :subscribe
+        raise ArgumentError, "Invalid Type (#{ask}), can only be :subscribe"
+      end
+      @ask = ask ? ask : nil
+    end
+
+    # Set the status then sorts them according to priority
+    #
+    # @param [Blather::Stanza::Status] the new status
+    def status=(presence)
+      @statuses.delete_if { |s| s.from == presence.from }
+      @statuses << presence
+      @statuses.sort!
+    end
+
+    # The status with the highest priority
+    #
+    # @param [String, nil] resource the resource to get the status of
+    def status(resource = nil)
+      top = if resource
+        @statuses.detect { |s| s.from.resource == resource }
+      else
+        @statuses.first
+      end
+    end
+
+    # Translate the RosterItem into a proper stanza that can be sent over the
+    # stream
+    #
+    # @return [Blather::Stanza::Iq::Roster]
+    def to_stanza(type = nil)
+      r = Stanza::Iq::Roster.new type
+      n = Stanza::Iq::Roster::RosterItem.new jid, name, subscription, ask
+      r.query << n
+      n.groups = groups
+      r
+    end
+  end #RosterItem
+
+end

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

@@ -0,0 +1,176 @@
+module Blather
+class Stanza
+
+  # # DiscoInfo Stanza
+  #
+  # [XEP-0030 Disco Info](http://xmpp.org/extensions/xep-0030.html#info)
+  #
+  # Disco Info node that provides or retreives information about a jabber entity
+  #
+  # @handler :disco_info
+  class DiscoInfo < Disco
+    register :disco_info, nil, 'http://jabber.org/protocol/disco#info'
+
+    # Create a new DiscoInfo stanza
+    # @param [:get, :set, :result, :error, nil] type the Iq stanza type
+    # @param [String, nil] node the name of the node the info belongs to
+    # @param [Array<Array, DiscoInfo::Identity>, nil] identities a list of
+    # identities. these are passed directly to DiscoInfo::Identity.new
+    # @param [Array<Array, DiscoInfo::Identity>, nil] features a list of
+    # features. these are passed directly to DiscoInfo::Feature.new
+    # @return [DiscoInfo] a new DiscoInfo stanza
+    def self.new(type = nil, node = nil, identities = [], features = [])
+      new_node = super type
+      new_node.node = node
+      [identities].flatten.each { |i| new_node.query << Identity.new(i) }
+      [features].flatten.each   { |f| new_node.query << Feature.new(f) }
+      new_node
+    end
+
+    # List of identity objects
+    def identities
+      query.find('//ns:identity', :ns => self.class.registered_ns).map do |i|
+        Identity.new i
+      end
+    end
+
+    # List of feature objects
+    def features
+      query.find('//ns:feature', :ns => self.class.registered_ns).map do |f|
+        Feature.new f
+      end
+    end
+
+    class Identity < XMPPNode
+      # 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
+      # @overload new(opts = {})
+      #   Creates a new Identity using a hash of options
+      #   @param [Hash] opts a hash of options
+      #   @option opts [String] :name the name of the identity
+      #   @option opts [String] :type the type of the identity
+      #   @option opts [String] :category the category of the identity
+      # @overload new(name, type = nil, category = nil)
+      #   Create a new Identity by name
+      #   @param [String] name the name of the Identity
+      #   @param [String, nil] type the type of the Identity
+      #   @param [String, nil] category the category of the Identity
+      def self.new(name, type = nil, category = nil)
+        new_node = super :identity
+
+        case name
+        when Nokogiri::XML::Node
+          new_node.inherit name
+        when Hash
+          new_node.name = name[:name]
+          new_node.type = name[:type]
+          new_node.category = name[:category]
+        else
+          new_node.name = name
+          new_node.type = type
+          new_node.category = category
+        end
+        new_node
+      end
+
+      # The Identity's category
+      # @return [Symbol, nil]
+      def category
+        read_attr :category, :to_sym
+      end
+
+      # Set the Identity's category
+      # @param [String, Symbol] category the new category
+      def category=(category)
+        write_attr :category, category
+      end
+
+      # The Identity's type
+      # @return [Symbol, nil]
+      def type
+        read_attr :type, :to_sym
+      end
+
+      # Set the Identity's type
+      # @param [String, Symbol] type the new category
+      def type=(type)
+        write_attr :type, type
+      end
+
+      # The Identity's name
+      # @return [String]
+      def name
+        read_attr :name
+      end
+
+      # Set the Identity's name
+      # @param [String] name the new name for the identity
+      def name=(name)
+        write_attr :name, name
+      end
+
+      # Compare two Identity objects by name, type and category
+      # @param [DiscoInfo::Identity] o the Identity object to compare against
+      # @return [true, false]
+      def eql?(o)
+        unless o.is_a?(self.class)
+          raise "Cannot compare #{self.class} with #{o.class}"
+        end
+
+        o.name == self.name &&
+        o.type == self.type &&
+        o.category == self.category
+      end
+      alias_method :==, :eql?
+    end # Identity
+
+    class Feature < XMPPNode
+      # Create a new DiscoInfo::Feature object
+      # @overload new(node)
+      #   Create a new Feature by importing an XML::Node
+      #   @param [XML::Node] node an XML::Node to import
+      # @overload new(var)
+      #   Create a new feature by var
+      #   @param [String] var a the Feautre's var
+      # @return [DiscoInfo::Feature]
+      def self.new(var)
+        new_node = super :feature
+        case var
+        when Nokogiri::XML::Node
+          new_node.inherit var
+        else
+          new_node.var = var
+        end
+        new_node
+      end
+
+      # The Feature's var
+      # @return [String]
+      def var
+        read_attr :var
+      end
+
+      # Set the Feature's var
+      # @param [String] var the new var
+      def var=(var)
+        write_attr :var, var
+      end
+
+      # Compare two Feature objects by var
+      # @param [DiscoInfo::Feature] o the Feature object to compare against
+      # @return [true, false]
+      def eql?(o)
+        unless o.is_a?(self.class)
+          raise "Cannot compare #{self.class} with #{o.class}"
+        end
+
+        o.var == self.var
+      end
+      alias_method :==, :eql?
+    end
+  end # Feature
+
+end # Stanza
+end # Blather

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

@@ -0,0 +1,132 @@
+module Blather
+class Stanza
+
+  # # DiscoItems Stanza
+  #
+  # [XEP-0030 Disco Info](http://xmpp.org/extensions/xep-0030.html#items)
+  #
+  # Disco Items node that provides or retreives items associated with a
+  # jabbery entity
+  #
+  # @handler :disco_items
+  class DiscoItems < Disco
+    register :disco_items, nil, 'http://jabber.org/protocol/disco#items'
+
+    # Create a new DiscoItems node
+    #
+    # @param [#to_s] type the IQ type
+    # @param [#to_s] node the node the items are associated with
+    # @param [Array<Blather::XMPPNode>] items an array of Disco::Items
+    # @return [Blather::Stanza::DiscoItems]
+    def self.new(type = nil, node = nil, items = [])
+      new_node = super type
+      new_node.node = node
+      [items].flatten.each { |item| new_node.query << Item.new(item) }
+      new_node
+    end
+
+    # Set of items associated with the node
+    #
+    # @return [Array<Blather::Stanza::DiscoItems::Item>]
+    def items
+      query.find('//ns:item', :ns => self.class.registered_ns).map do |i|
+        Item.new i
+      end
+    end
+
+    # An individual Disco Item
+    class Item < XMPPNode
+      # Create a new Blather::Stanza::DiscoItems::Item
+      #
+      # @overload new(node)
+      #   Create a new Item by inheriting an existing node
+      #   @param [XML::Node] node an XML::Node to inherit from
+      # @overload new(opts)
+      #   Create a new Item through a hash of options
+      #   @param [Hash] opts a hash options
+      #   @option opts [Blather::JID, String] :jid the JID to attach to the item
+      #   @option opts [#to_s] :node the node the item is attached to
+      #   @option opts [#to_S] :name the name of the Item
+      # @overload new(jid, node = nil, name  = nil)
+      #   Create a new Item
+      #   @param [Blather::JID, String] jid the JID to attach to the item
+      #   @param [#to_s] node the node the item is attached to
+      #   @param [#to_s] name the name of the Item
+      def self.new(jid, node = nil, name = nil)
+        new_node = super :item
+
+        case jid
+        when Nokogiri::XML::Node
+          new_node.inherit jid
+        when Hash
+          new_node.jid = jid[:jid]
+          new_node.node = jid[:node]
+          new_node.name = jid[:name]
+        else
+          new_node.jid = jid
+          new_node.node = node
+          new_node.name = name
+        end
+        new_node
+      end
+
+      # Get the JID attached to the node
+      #
+      # @return [Blather::JID, nil]
+      def jid
+        (j = self[:jid]) ? JID.new(j) : nil
+      end
+
+      # Set the JID of the node
+      #
+      # @param [Blather::JID, String, nil] jid the new JID
+      def jid=(jid)
+        write_attr :jid, jid
+      end
+
+      # Get the name of the node
+      #
+      # @return [String, nil]
+      def node
+        read_attr :node
+      end
+
+      # Set the name of the node
+      #
+      # @param [String, nil] node the new node name
+      def node=(node)
+        write_attr :node, node
+      end
+
+      # Get the Item name
+      #
+      # @return [String, nil]
+      def name
+        read_attr :name
+      end
+
+      # Set the Item name
+      #
+      # @param [#to_s] name the Item name
+      def name=(name)
+        write_attr :name, name
+      end
+
+      # Check for equality based on jid, node, and name
+      #
+      # @param [Blather::Stanza::DiscoItems::Item] o the other Item
+      def eql?(o)
+        unless o.is_a?(self.class)
+          raise "Cannot compare #{self.class} with #{o.class}"
+        end
+
+        o.jid == self.jid &&
+        o.node == self.node &&
+        o.name == self.name
+      end
+      alias_method :==, :eql?
+    end
+  end
+
+end #Stanza
+end #Blather

data/lib/blather/stanza/disco.rb

@@ -0,0 +1,25 @@
+module Blather
+class Stanza
+
+  # # Disco Base class
+  #
+  # Use Blather::Stanza::DiscoInfo or Blather::Stanza::DiscoItems
+  class Disco < Iq::Query
+
+    # Get the name of the node
+    #
+    # @return [String] the node name
+    def node
+      query[:node]
+    end
+
+    # Set the name of the node
+    #
+    # @param [#to_s] node the new node name
+    def node=(node)
+      query[:node] = node
+    end
+  end
+
+end # Stanza
+end # Blather