mad-p-xmpp4r 0.6.0

data/lib/xmpp4r.rb

@@ -0,0 +1,116 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+#
+# ==Introduction
+#
+# XMPP4R is a XMPP/Jabber library for Ruby. It can be used to build scripts
+# using Jabber, full-featured Jabber clients, and components. It is written
+# with extensibility in mind.
+#
+# ==XML management
+#
+# All the XML parsing is REXML's, and XML stanzas like <message/> (class
+# <tt>Jabber::Message</tt>) or <iq/> (class <tt>Jabber::Iq</tt>) are indirect
+# derivatives from REXML's Element class. This provide a maximum flexibity:
+# the user can access attributes and childs using either the XMPP4R's helpers
+# or directly using REXML's methods.
+#
+# ===Automatic element casting
+#
+# Because there are special classes derived from REXML::Element to ease
+# development on the protocol level, Elements must be cast to them. This is
+# done via REXML::Element.import. This method is also used in import class
+# methods of some Element classes.
+#
+# The first occurance of this feature is in Jabber::Stream::receive:
+# * <tt><message/></tt> stanzas are cast to Jabber::Message class
+# * <tt><presence/></tt> stanzas are cast to Jabber::Presence class
+# * <tt><iq/></tt> stanzas are cast to Jabber::Iq class
+#
+# This is not only useful for stanzas but all other XML processing, too:
+# * <tt><x/></tt> children elements of <tt><message/></tt> and <tt><presence/></tt> are converted to Jabber::X
+# * <tt><error/></tt> children elements of all three stanzas are converted to Jabber::ErrorResponse
+# * <tt><query/></tt> children elements of <tt><iq/></tt> are converted to Jabber::IqQuery
+# * <tt><vCard/></tt> children elements of <tt><iq/></tt> are converted to Jabber::IqVcard
+#
+# The following conversion facilities are only executed if the respective
+# library parts are loaded. See below for more details on Non-basic features.
+# * Jabber::IqQuery elements are converted to Jabber::Roster::IqQueryRoster if their
+#   namespace is 'jabber:iq:roster'
+# * Jabber::IqQuery elements are converted to Jabber::Version::IqQueryVersion if their
+#   namespace is 'jabber:iq:version'
+# * Jabber::IqQuery elements are converted to Jabber::Discovery::IqQueryDiscoInfo if their
+#   namespace is 'http://jabber.org/protocol/disco#info'
+# * Jabber::IqQuery elements are converted to Jabber::Discovery::IqQueryDiscoItems if their
+#   namespace is 'http://jabber.org/protocol/disco#items'
+# * <tt><item/></tt> children elements of Jabber::Roster::IqQueryRoster are converted
+#   to Jabber::Roster::RosterItem
+# * <tt><identity/></tt> children elements of Jabber::IqQueryDiscoInfo are converted
+#   to Jabber::Discovery::DiscoIdentity
+# * <tt><feature/></tt> children elements of Jabber::IqQueryDiscoInfo are converted
+#   to Jabber::Discovery::DiscoFeature
+# * <tt><item/></tt> children elements of Jabber::IqQueryDiscoItems are converted
+#   to Jabber::Discovery::DiscoItem
+#
+# To use this, don't check for:
+# <tt>iq.queryns == 'http://jabber.org/protocol/disco#info'</tt>
+#
+# But instead check for the query's class:
+# <tt>iq.query.kind_of?(Jabber::IqQueryDiscoInfo)</tt>
+#
+# ==Where to begin?
+#
+# Because it is built in an extensible way, it might be hard for newcomers to
+# understand where to look at documentation for a specific method. For example,
+# Client inherits from Connection, which itself inherits from Stream.
+#
+# A newcomer should have a look at the <tt>Jabber::Client</tt> and
+# <tt>Jabber::Component</tt> classes, and their parent classes
+# <tt>Jabber::Connection</tt> and <tt>Jabber::Stream</tt>.  The best way to
+# understand how to use them is probably to look at the examples in the
+# <tt>examples/</tt> dir.
+#
+# ==Non-basic features
+#
+# <tt>require 'xmpp4r'</tt> only includes basic functionality for
+# Connections, Authentication, Stream processing, Callbacks, Stanza handling
+# and Debugging to keep the library's footprint small.
+#
+# There is code for features that aren't required by a *basic* client. These
+# must be additionally included to use them.
+#
+# ===Protocol-level features
+#
+# You're highly advised to read the according RFCs and JEPs if you intend to
+# use them. The benefit will be that you'll understand the protocols and be
+# going to be more efficient when programming with them.
+#
+# * Jabber::Bytestreams, Jabber::FileTransfer: <tt>require 'xmpp4r/bytestreams'</tt>
+# * Jabber::Dataforms: <tt>require 'xmpp4r/dataforms'</tt>
+# * Jabber::Delay: <tt>require 'xmpp4r/delay'</tt>
+# * Jabber::Discovery: <tt>require 'xmpp4r/discovery'</tt>
+# * Jabber::FeatureNegotiation: <tt>require 'xmpp4r/feature_negotiation'</tt>
+# * Jabber::MUC: <tt>require 'xmpp4r/muc'</tt>
+# * Jabber::Roster: <tt>require 'xmpp4r/roster'</tt>
+# * Jabber::Vcard: <tt>require 'xmpp4r/vcard'</tt>
+# * Jabber::Version: <tt>require 'xmpp4r/version'</tt>
+#
+# ===Helpers
+#
+# Helpers are intended to give more simplistic interfaces to various tasks
+# of Jabber clients at the cost of flexibility. But you won't need that
+# level of flexibility in most cases.
+#
+# * Jabber::Roster::Helper: <tt>require 'xmpp4r/roster'</tt>
+# * Jabber::MUC::MUCBrowser, Jabber::MUC::MUCClient, Jabber::MUC::SimpleMUCClient: <tt>require 'xmpp4r/muc'</tt>
+# * Jabber::Version::SimpleResponder, Jabber::Version::Responder: <tt>require 'xmpp4r/version'</tt>
+# * Jabber::Vcard::Helper: <tt>require 'xmpp4r/vcard'</tt>
+# * Jabber::FileTransfer::Helper, Jabber::Bytestreams::SOCKS5BytestreamsServer: <tt>require 'xmpp4r/bytestreams'</tt>
+#
+# ==Debugging
+#
+# Dumping your Jabber stream can be enabled this way:
+#   Jabber::debug = true
+
+require 'xmpp4r/xmpp4r'

data/lib/xmpp4r/base64.rb

@@ -0,0 +1,32 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+begin
+  require 'base64'
+rescue LoadError
+  ##
+  # Ruby 1.9 has dropped the Base64 module,
+  # this is a replacement
+  #
+  # We could replace all call by Array#pack('m')
+  # and String#unpack('m'), but this module
+  # improves readability.
+  module Base64
+    ##
+    # Encode a String
+    # data:: [String] Binary
+    # result:: [String] Binary in Base64
+    def self.encode64(data)
+      [data].pack('m')
+    end
+
+    ##
+    # Decode a Base64-encoded String
+    # data64:: [String] Binary in Base64
+    # result:: [String] Binary
+    def self.decode64(data64)
+      data64.unpack('m').first
+    end
+  end
+end

data/lib/xmpp4r/bytestreams.rb

@@ -0,0 +1,15 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+require 'xmpp4r/bytestreams/iq/si.rb'
+require 'xmpp4r/bytestreams/iq/bytestreams.rb'
+require 'xmpp4r/bytestreams/helper/ibb/base.rb'
+require 'xmpp4r/bytestreams/helper/ibb/initiator.rb'
+require 'xmpp4r/bytestreams/helper/ibb/target.rb'
+require 'xmpp4r/bytestreams/helper/filetransfer.rb'
+require 'xmpp4r/bytestreams/helper/socks5bytestreams/base.rb'
+require 'xmpp4r/bytestreams/helper/socks5bytestreams/initiator.rb'
+require 'xmpp4r/bytestreams/helper/socks5bytestreams/server.rb'
+require 'xmpp4r/bytestreams/helper/socks5bytestreams/target.rb'
+require 'xmpp4r/bytestreams/helper/socks5bytestreams/socks5.rb'

data/lib/xmpp4r/bytestreams/helper/filetransfer.rb

@@ -0,0 +1,321 @@
+# =XMPP4R - XMPP Library for Ruby
+# License:: Ruby's license (see the LICENSE file) or GNU GPL, at your option.
+# Website::http://home.gna.org/xmpp4r/
+
+require 'xmpp4r/callbacks'
+require 'xmpp4r/bytestreams/iq/si'
+require 'xmpp4r/bytestreams/iq/bytestreams'
+require 'xmpp4r/dataforms/x/data'
+require 'xmpp4r/bytestreams/helper/ibb/base'
+require 'xmpp4r/bytestreams/helper/socks5bytestreams/base'
+require 'xmpp4r/bytestreams/helper/socks5bytestreams/target'
+
+module Jabber
+  module FileTransfer
+    ##
+    # The TransferSource is an interface (Mix-in)
+    # which sources for FileTransfer#offer should include
+    module TransferSource
+      ##
+      # Filename of the offered file
+      def filename
+      end
+      ##
+      # Mime-type of the offered file, can be nil
+      def mime
+      end
+      ##
+      # Size of the offered file
+      def size
+      end
+      ##
+      # MD5-Sum of the offered file, can be nil
+      def md5
+      end
+      ##
+      # Date of the offered file, can be nil
+      def date
+      end
+      ##
+      # Read a chunk from the source
+      #
+      # If this is a ranged transfer, it should
+      # implement length checking
+      # length:: [Fixnum]
+      def read(length=nil)
+      end
+      ##
+      # Seek in the source for ranged transfers
+      def seek(position)
+      end
+      ##
+      # Set the amount of data to send for ranged transfers
+      def length=(l)
+      end
+      ##
+      # Does implement the methods seek and length= ?
+      #
+      # FileTransfer will only then offer a ranged transfer.
+      # result:: [false] or [true]
+      def can_range?
+        false
+      end
+    end
+
+    ##
+    # Simple implementation of TransferSource
+    # for sending simple files
+    # (supports ranged transfers)
+    class FileSource
+      include TransferSource
+
+      def initialize(filename)
+        @file = File.new(filename)
+        @filename = filename
+        @bytes_read = 0
+        @length = nil
+      end
+
+      def filename
+        File::basename @filename
+      end
+
+      ##
+      # Everything is 'application/octet-stream'
+      def mime
+        'application/octet-stream'
+      end
+
+      def size
+        File.size @filename
+      end
+
+      def date
+        @file.mtime
+      end
+
+      ##
+      # Because it can_range?, this method implements length checking
+      def read(length=512)
+        if @length
+          return nil if @bytes_read >= @length  # Already read everything requested
+          if @bytes_read + length > @length # Will we read more than requested?
+            length = @length - @bytes_read  # Truncate it!
+          end
+        end
+
+        buf = @file.read(length)
+        @bytes_read += buf.size if buf
+        buf
+      end
+
+      def seek(position)
+        @file.seek(position)
+      end
+
+      def length=(l)
+        @length = l
+      end
+
+      def can_range?
+        true
+      end
+    end
+
+    ##
+    # The FileTransfer helper provides the ability to respond
+    # to incoming and to offer outgoing file-transfers.
+    class Helper
+      ##
+      # Set this if you want to use this helper in a Component
+      attr_accessor :my_jid
+      ##
+      # Set this to false if you don't want to use SOCKS5Bytestreams
+      attr_accessor :allow_bytestreams
+      ##
+      # Set this to false if you don't want to use IBB
+      attr_accessor :allow_ibb
+
+      ##
+      # Create a new FileTransfer instance
+      def initialize(stream)
+        @stream = stream
+        @my_jid = nil
+        @allow_bytestreams = true
+        @allow_ibb = true
+
+        @incoming_cbs = CallbackList.new
+
+        @stream.add_iq_callback(150, self) { |iq|
+          if iq.type == :set
+            file = iq.first_element('si/file')
+            field = nil
+            iq.each_element('si/feature/x') { |e| field = e.field('stream-method') }
+
+            if file and field
+              @incoming_cbs.process(iq, file)
+              true
+            else
+              false
+            end
+          else
+            false
+          end
+        }
+      end
+
+      ##
+      # Add a callback which will be invoked upon an incoming file-transfer
+      #
+      # block takes two arguments:
+      # * Iq
+      # * Bytestreams::IqSiFile in the Iq
+      # You may then invoke accept or decline
+      def add_incoming_callback(priority = 0, ref = nil, &block)
+        @incoming_cbs.add(priority, ref, block)
+      end
+
+      ##
+      # Accept an incoming file-transfer,
+      # to be used in a block given to add_incoming_callback
+      #
+      # offset and length will be ignored if there is no
+      # 'si/file/range' in iq.
+      # iq:: [Iq] of file-transfer we want to accept
+      # offset:: [Fixnum] or [nil]
+      # length:: [Fixnum] or [nil]
+      # result:: [Bytestreams::SOCKS5BytestreamsTarget] or [Bytestreams::IBBTarget] or [nil] if no valid stream-method
+      def accept(iq, offset=nil, length=nil)
+        oldsi = iq.first_element('si')
+
+        answer = iq.answer(false)
+        answer.type = :result
+
+        si = answer.add(Bytestreams::IqSi.new)
+        if (offset or length) and oldsi.file.range
+          si.add(Bytestreams::IqSiFile.new)
+          si.file.add(Bytestreams::IqSiFileRange.new(offset, length))
+        end
+        si.add(FeatureNegotiation::IqFeature.new.import(oldsi.feature))
+        si.feature.x.type = :submit
+        stream_method = si.feature.x.field('stream-method')
+
+        if stream_method.options.keys.include?(Bytestreams::NS_BYTESTREAMS) and @allow_bytestreams
+          stream_method.values = [Bytestreams::NS_BYTESTREAMS]
+          stream_method.options = []
+          @stream.send(answer)
+
+          Bytestreams::SOCKS5BytestreamsTarget.new(@stream, oldsi.id, iq.from, iq.to)
+        elsif stream_method.options.keys.include?(Bytestreams::IBB::NS_IBB) and @allow_ibb
+          stream_method.values = [Bytestreams::IBB::NS_IBB]
+          stream_method.options = []
+          @stream.send(answer)
+
+          Bytestreams::IBBTarget.new(@stream, oldsi.id, iq.from, iq.to)
+        else
+          eanswer = iq.answer(false)
+          eanswer.type = :error
+          eanswer.add(ErrorResponse.new('bad-request')).type = :cancel
+          eanswer.error.add(REXML::Element.new('no-valid-streams')).add_namespace('http://jabber.org/protocol/si')
+          @stream.send(eanswer)
+
+          nil
+        end
+      end
+
+      ##
+      # Decline an incoming file-transfer,
+      # to be used in a block given to add_incoming_callback
+      # iq:: [Iq] of file-transfer we want to decline
+      def decline(iq)
+        answer = iq.answer(false)
+        answer.type = :error
+        error = answer.add(ErrorResponse.new('forbidden', 'Offer declined'))
+        error.type = :cancel
+        @stream.send(answer)
+      end
+
+      ##
+      # Offer a file to somebody
+      #
+      # Will wait for a response from the peer
+      #
+      # The result is a stream which you can configure, or nil
+      # if the peer responded with an invalid stream-method.
+      #
+      # May raise an ServerError
+      # jid:: [JID] to send the file to
+      # source:: File-transfer source, implementing the FileSource interface
+      # desc:: [String] or [nil] Optional file description
+      # from:: [String] or [nil] Optional jid for components
+      # result:: [Bytestreams::SOCKS5BytestreamsInitiator] or [Bytestreams::IBBInitiator] or [nil]
+      def offer(jid, source, desc=nil, from=nil)
+        from = from || @my_jid || @stream.jid
+        session_id = Jabber::IdGenerator.instance.generate_id
+
+        offered_methods = {}
+        if @allow_bytestreams
+          offered_methods[Bytestreams::NS_BYTESTREAMS] = nil
+        end
+        if @allow_ibb
+          offered_methods[Bytestreams::IBB::NS_IBB] = nil
+        end
+
+        iq = Iq.new(:set, jid)
+        iq.from = from
+        si = iq.add(Bytestreams::IqSi.new(session_id, Bytestreams::PROFILE_FILETRANSFER, source.mime))
+
+        file = si.add(Bytestreams::IqSiFile.new(source.filename, source.size))
+        file.hash = source.md5
+        file.date = source.date
+        file.description = desc if desc
+        file.add(Bytestreams::IqSiFileRange.new) if source.can_range?
+
+        feature = si.add(REXML::Element.new('feature'))
+        feature.add_namespace 'http://jabber.org/protocol/feature-neg'
+        x = feature.add(Dataforms::XData.new(:form))
+        stream_method_field = x.add(Dataforms::XDataField.new('stream-method', :list_single))
+        stream_method_field.options = offered_methods
+
+        begin
+          stream_method = nil
+          response = nil
+          @stream.send_with_id(iq) do |r|
+            response = r
+            si = response.first_element('si')
+            if si and si.feature and si.feature.x
+              stream_method = si.feature.x.field('stream-method').values.first
+
+              if si.file and si.file.range
+                if source.can_range?
+                  source.seek(si.file.range.offset) if si.file.range.offset
+                  source.length = si.file.range.length if si.file.range.length
+                else
+                  source.read(si.file.range.offset)
+                end
+              end
+            end
+          end
+        rescue ServerError => e
+          if e.error.code == 403  # Declined
+            return false
+          else
+            raise e
+          end
+        end
+
+        if stream_method == Bytestreams::NS_BYTESTREAMS and @allow_bytestreams
+          Bytestreams::SOCKS5BytestreamsInitiator.new(@stream, session_id, from, jid)
+        elsif stream_method == Bytestreams::IBB::NS_IBB and @allow_ibb
+          Bytestreams::IBBInitiator.new(@stream, session_id, from, jid)
+        else  # Target responded with a stream_method we didn't offer
+          eanswer = response.answer
+          eanswer.type = :error
+          eanswer.add ErrorResponse.new('bad-request')
+          @stream.send(eanswer)
+          nil
+        end
+      end
+    end
+  end
+end