blather 0.4.1 → 0.4.2

data/lib/blather/stanza/presence/status.rb

@@ -2,8 +2,68 @@ module Blather
 class Stanza
 class Presence
 
+  # = Status Stanza
+  #
+  # Presence stanzas are used to express an entity's current network availability (offline or online, along with
+  # various sub-states of the latter and optional user-defined descriptive text), and to notify other entities of
+  # that availability.
+  #
+  # == State Attribute
+  #
+  # The +state+ attribute determains the availability of the entity and can be one of the following:
+  #
+  # * +:available+ -- The entity or resource is available
+  # * +:away+ -- The entity or resource is temporarily away.
+  # * +:chat+ -- The entity or resource is actively interested in chatting.
+  # * +:dnd+ -- The entity or resource is busy (dnd = "Do Not Disturb").
+  # * +:xa+ -- The entity or resource is away for an extended period (xa = "eXtended Away").
+  #
+  # Blather provides a helper for each possible state:
+  #
+  #   Status#available?
+  #   Status#away?
+  #   Status#chat?
+  #   Status#dnd?
+  #   Status#xa?
+  #
+  # Blather treats the +type+ attribute like a normal ruby object attribute providing a getter and setter.
+  # The default +type+ is +available+.
+  #
+  #   status = Status.new
+  #   status.state              # => :available
+  #   status.available?         # => true
+  #   status.state = :away
+  #   status.away?              # => true
+  #   status.available?         # => false
+  #   status
+  #   status.state = :invalid   # => RuntimeError
+  #
+  # == Type Attribute
+  #
+  # The +type+ attribute is inherited from Presence, but limits the value to either +nil+ or +:unavailable+
+  # as these are the only types that relate to Status.
+  #
+  # == Priority Attribute
+  #
+  # The +priority+ attribute sets the priority of the status for the entity and must be an integer between
+  # -128 and 127. 
+  #
+  # == Message Attribute
+  #
+  # The optional +message+ element contains XML character data specifying a natural-language description of
+  # availability status. It is normally used in conjunction with the show element to provide a detailed
+  # description of an availability state (e.g., "In a meeting").
+  # 
+  # Blather treats the +message+ attribute like a normal ruby object attribute providing a getter and setter.
+  # The default +message+ is nil.
+  #
+  #   status = Status.new
+  #   status.message            # => nil
+  #   status.message = "gone!"
+  #   status.message            # => "gone!"
+  #
   class Status < Presence
-    VALID_STATES = [:away, :chat, :dnd, :xa]
+    VALID_STATES = [:away, :chat, :dnd, :xa] # :nodoc:
 
     include Comparable
 
@@ -16,18 +76,18 @@ class Presence
       node
     end
 
-    attribute_helpers_for(:state, VALID_STATES)
+    attribute_helpers_for(:state, [:available] + VALID_STATES)
 
     ##
     # Ensures type is nil or :unavailable
-    def type=(type)
+    def type=(type) # :nodoc:
       raise ArgumentError, "Invalid type (#{type}). Must be nil or unavailable" if type && type.to_sym != :unavailable
       super
     end
 
     ##
-    # Ensure state is one of :away, :chat, :dnd, :xa or nil
-    def state=(state)
+    # Ensure state is one of :available, :away, :chat, :dnd, :xa or nil
+    def state=(state) # :nodoc:
       state = state.to_sym if state
       state = nil if state == :available
       raise ArgumentError, "Invalid Status (#{state}), use: #{VALID_STATES*' '}" if state && !VALID_STATES.include?(state)
@@ -36,14 +96,14 @@ class Presence
     end
 
     ##
-    # return:: :available if state is nil
-    def state
+    # :available if state is nil
+    def state # :nodoc:
       (type || content_from(:show) || :available).to_sym
     end
 
     ##
     # Ensure priority is between -128 and 127
-    def priority=(new_priority)
+    def priority=(new_priority) # :nodoc:
       raise ArgumentError, 'Priority must be between -128 and +127' if new_priority && !(-128..127).include?(new_priority.to_i)
       set_content_for :priority, new_priority
       

data/lib/blather/stream/client.rb

@@ -19,6 +19,12 @@ class Stream
       STREAM
       send start_stream.gsub(/\s+/, ' ')
     end
+
+    def send(stanza)
+      stanza.from = self.jid if stanza.is_a?(Stanza) && !stanza.from.nil?
+      super stanza
+    end
+
   end #Client
 
 end #Stream

data/lib/blather/stream/features.rb

@@ -1,7 +1,7 @@
 module Blather # :nodoc:
 class Stream # :nodoc:
 
-  class Features
+  class Features # :nodoc:
     @@features = {}
     def self.register(ns)
       @@features[ns] = self

data/spec/blather/client/client_spec.rb

@@ -114,6 +114,43 @@ describe Blather::Client do
     @client.receive_data stanza
     @client.receive_data stanza
   end
+
+  it 'allows for breaking out of handlers' do
+    stanza = Blather::Stanza::Iq.new
+    response = mock(:iq => nil)
+    @client.register_handler(:iq) do |_|
+      response.iq
+      throw :halt
+      response.fail
+    end
+    @client.receive_data stanza
+  end
+
+  it 'allows for passing to the next handler of the same type' do
+    stanza = Blather::Stanza::Iq.new
+    response = mock(:iq1 => nil, :iq2 => nil)
+    @client.register_handler(:iq) do |_|
+      response.iq1
+      throw :pass
+      response.fail
+    end
+    @client.register_handler(:iq) do |_|
+      response.iq2
+    end
+    @client.receive_data stanza
+  end
+
+  it 'allows for passing to the next handler in the heirarchy' do
+    stanza = Blather::Stanza::Iq::Query.new
+    response = mock(:query => nil, :iq => nil)
+    @client.register_handler(:query) do |_|
+      response.query
+      throw :pass
+      response.fail
+    end
+    @client.register_handler(:iq) { |_| response.iq }
+    @client.receive_data stanza
+  end
 end
 
 describe 'Blather::Client#write' do
@@ -200,11 +237,37 @@ describe 'Blather::Client default handlers' do
     @client.receive_data status
   end
 
+  it 'lets status stanzas fall through to other handlers' do
+    jid = 'friend@jabber.local'
+    status = Blather::Stanza::Presence::Status.new :away
+    status.stubs(:from).returns jid
+    roster_item = mock()
+    roster_item.expects(:status=).with status
+    @client.stubs(:roster).returns({status.from => roster_item})
+
+    response = mock()
+    response.expects(:call).with jid
+    @client.register_handler(:status) { |s| response.call s.from.to_s }
+    @client.receive_data status
+  end
+
+  it 'handles an incoming roster node by processing it through the roster' do
+    roster = Blather::Stanza::Iq::Roster.new
+    client_roster = mock()
+    client_roster.expects(:process).with roster
+    @client.stubs(:roster).returns client_roster
+    @client.receive_data roster
+  end
+
   it 'handles an incoming roster node by processing it through the roster' do
     roster = Blather::Stanza::Iq::Roster.new
     client_roster = mock()
     client_roster.expects(:process).with roster
     @client.stubs(:roster).returns client_roster
+
+    response = mock()
+    response.expects(:call)
+    @client.register_handler(:roster) { |_| response.call }
     @client.receive_data roster
   end
 end
@@ -250,6 +313,74 @@ describe 'Blather::Client with a Client stream' do
   end
 end
 
+describe 'Blather::Client filters' do
+  before do
+    @client = Blather::Client.new
+  end
+
+  it 'raises an error when an invalid filter type is registered' do
+    lambda { @client.register_filter(:invalid) {} }.must_raise RuntimeError
+  end
+
+  it 'can be guarded' do
+    stanza = Blather::Stanza::Iq.new
+    ready = mock()
+    ready.expects(:call).once
+    @client.register_filter(:before, :iq, :id => stanza.id) { |_| ready.call }
+    @client.register_filter(:before, :iq, :id => 'not-id') { |_| ready.call }
+    @client.receive_data stanza
+  end
+
+  it 'can pass to the next handler' do
+    stanza = Blather::Stanza::Iq.new
+    ready = mock()
+    ready.expects(:call).once
+    @client.register_filter(:before) { |_| throw :pass; ready.call }
+    @client.register_filter(:before) { |_| ready.call }
+    @client.receive_data stanza
+  end
+
+  it 'runs them in order' do
+    stanza = Blather::Stanza::Iq.new
+    count = 0
+    @client.register_filter(:before) { |_| count.must_equal 0; count = 1 }
+    @client.register_filter(:before) { |_| count.must_equal 1; count = 2 }
+    @client.register_handler(:iq) { |_| count.must_equal 2; count = 3 }
+    @client.register_filter(:after) { |_| count.must_equal 3; count = 4 }
+    @client.register_filter(:after) { |_| count.must_equal 4 }
+    @client.receive_data stanza
+  end
+
+  it 'can modify the stanza' do
+    stanza = Blather::Stanza::Iq.new
+    stanza.from = 'from@test.local'
+    new_jid = 'before@filter.local'
+    ready = mock()
+    ready.expects(:call).with new_jid
+    @client.register_filter(:before) { |s| s.from = new_jid }
+    @client.register_handler(:iq) { |s| ready.call s.from.to_s }
+    @client.receive_data stanza
+  end
+
+  it 'can halt the handler chain' do
+    stanza = Blather::Stanza::Iq.new
+    ready = mock()
+    ready.expects(:call).never
+    @client.register_filter(:before) { |_| throw :halt }
+    @client.register_handler(:iq) { |_| ready.call }
+    @client.receive_data stanza
+  end
+
+  it 'can be specific to a handler' do
+    stanza = Blather::Stanza::Iq.new
+    ready = mock()
+    ready.expects(:call).once
+    @client.register_filter(:before, :iq) { |_| ready.call }
+    @client.register_filter(:before, :message) { |_| ready.call }
+    @client.receive_data stanza
+  end
+end
+
 describe 'Blather::Client guards' do
   before do
     @client = Blather::Client.new

data/spec/blather/client/dsl_spec.rb

@@ -31,6 +31,26 @@ describe Blather::DSL do
     @dsl.shutdown
   end
 
+  it 'can throw a halt' do
+    catch(:halt) { @dsl.halt }
+  end
+
+  it 'can throw a pass' do
+    catch(:pass) { @dsl.pass }
+  end
+
+  it 'can setup before filters' do
+    guards = [:chat?, {:body => 'exit'}]
+    @client.expects(:register_filter).with :before, nil, *guards
+    @dsl.before nil, *guards
+  end
+
+  it 'can setup after filters' do
+    guards = [:chat?, {:body => 'exit'}]
+    @client.expects(:register_filter).with :after, nil, *guards
+    @dsl.after nil, *guards
+  end
+
   it 'sets up handlers' do
     type = :message
     guards = [:chat?, {:body => 'exit'}]

data/spec/blather/stanza/message_spec.rb

@@ -21,31 +21,42 @@ describe Blather::Stanza::Message do
   it 'provides "attr_accessor" for body' do
     s = Blather::Stanza::Message.new
     s.body.must_be_nil
-    s.xpath('body').must_be_empty
+    s.find('body').must_be_empty
 
     s.body = 'test message'
     s.body.wont_be_nil
-    s.xpath('body').wont_be_empty
+    s.find('body').wont_be_empty
   end
 
   it 'provides "attr_accessor" for subject' do
     s = Blather::Stanza::Message.new
     s.subject.must_be_nil
-    s.xpath('subject').must_be_empty
+    s.find('subject').must_be_empty
 
     s.subject = 'test subject'
     s.subject.wont_be_nil
-    s.xpath('subject').wont_be_empty
+    s.find('subject').wont_be_empty
   end
 
   it 'provides "attr_accessor" for thread' do
     s = Blather::Stanza::Message.new
     s.thread.must_be_nil
-    s.xpath('thread').must_be_empty
+    s.find('thread').must_be_empty
 
     s.thread = 1234
     s.thread.wont_be_nil
-    s.xpath('thread').wont_be_empty
+    s.find('thread').wont_be_empty
+  end
+
+  it 'can set a parent attribute for thread' do
+    s = Blather::Stanza::Message.new
+    s.thread.must_be_nil
+    s.find('thread').must_be_empty
+
+    s.thread = {4321 => 1234}
+    s.thread.must_equal '1234'
+    s.parent_thread.must_equal '4321'
+    s.find('thread[@parent="4321"]').wont_be_empty
   end
 
   it 'ensures type is one of Blather::Stanza::Message::VALID_TYPES' do

data/spec/blather/stream/client_spec.rb

@@ -988,4 +988,24 @@ describe Blather::Stream::Client do
     end
   end
 
+  it 'sends stanzas to the wire ensuring "from" is the full JID if set' do
+    client = mock()
+    client.stubs(:jid)
+    client.stubs(:jid=)
+    msg = Blather::Stanza::Message.new 'to@jid.com', 'body'
+    msg.from = 'node@jid.com'
+    comp = Blather::Stream::Client.new nil, client, 'node@jid.com/resource', 'pass'
+    comp.expects(:send_data).with { |s| s.must_match(/^<message[^>]*from="node@jid\.com\/resource"/) }
+    comp.send msg
+  end
+
+  it 'sends stanzas to the wire leaving "from" nil if not set' do
+    client = mock()
+    client.stubs(:jid)
+    client.stubs(:jid=)
+    msg = Blather::Stanza::Message.new 'to@jid.com', 'body'
+    comp = Blather::Stream::Client.new nil, client, 'node@jid.com/resource', 'pass'
+    comp.expects(:send_data).with { |s| s.wont_match(/^<message[^>]*from=/); true }
+    comp.send msg
+  end
 end

data/spec/blather/stream/component_spec.rb

@@ -83,7 +83,7 @@ describe Blather::Stream::Component do
     end
   end
 
-  it 'sends stanzas to the wire with ensuring from is set' do
+  it 'sends stanzas to the wire ensuring "from" is set' do
     client = mock()
     client.stubs(:jid)
     client.stubs(:jid=)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: blather
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors: 
 - Jeff Smick
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-06-07 00:00:00 -07:00
+date: 2009-06-13 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -45,7 +45,9 @@ files:
 - examples/drb_client.rb
 - examples/echo.rb
 - examples/execute.rb
+- examples/ping.rb
 - examples/ping_pong.rb
+- examples/pong.rb
 - examples/print_heirarchy.rb
 - examples/pubsub/cli.rb
 - examples/pubsub/ping_pong.rb