tyler-uppercut 0.6.2 → 0.7.0

data/README.textile

@@ -47,6 +47,32 @@ Then to actually put the Agent to work...
 This creates a new BasicAgent instance and sends it _listen_ to make it start accepting messages.
 Note that by default when an agent is listening, it ignores all errors.  (In the future, I'll have it log them.)
 
+There are also event callbacks for agents.  These events are based on XMPP presence messages.  So, as of this writing,
+the list of allowed callbacks is: signon, signoff, subscribe, unsubscribe, subscription_approval, subscription_denial,
+status_change, and status_message_change.
+
+You can use these callbacks as follows:
+
+<pre>
+  <code>
+    class CoolAgent < Uppercut::Agent
+      on :subscribe do |c|
+        c.send 'Hey dude, thanks for subscribing!'
+      end
+
+      on :signoff do |c|
+        puts "LOG: #{c.to} signed off."
+      end
+    end
+  </code>
+</pre>
+
+Some callbacks only work if the user allows the agent to subscribe to their presence notifications.  This happens
+automatically when a user subscribes to your agent.  (Depending on their client) they'll be presented with a choice
+to authorize or deny the subscription.  You can catch their answer with the 'subscription_approval' and 'subscription_denial'
+callbacks.  Without their approving the subscription, your 'signon', 'signoff', 'status_change', and 'status_message_change'
+callbacks will not be fired by them.  I suggest using the 'subscription_denial' callback to inform them of that.
+
 
 h2. Making a Notifier
 

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-patch: 2
+patch: 0
 major: 0
-minor: 6
+minor: 7

data/examples/basic_agent.rb

@@ -0,0 +1,28 @@
+class BasicNotifier < Uppercut::Notifier
+  notifier :basic do |n,data|
+    n.to 'tyler@codehallow.com'
+    n.send 'Hey kid.'
+  end
+end
+
+class BasicAgent < Uppercut::Agent
+  command 'date' do |m|
+    m.send `date`
+  end
+  
+  command /^cat (.*)/ do |m,rest|
+    m.send File.read(rest)
+  end
+  
+  command 'report' do |m|
+    m.send 'Hostname: ' + `hostname`
+    m.send 'Running as: ' + ENV['USER']
+  end
+  
+  command 'dangerous' do |c|
+    c.send "Are you sure?!"
+    c.wait_for do |reply|
+      c.send %w(yes y).include?(reply.downcase) ? "Okay!  Done boss!" : "Cancelled!"
+    end
+  end
+end

data/lib/uppercut/agent.rb

@@ -1,5 +1,8 @@
 class Uppercut
   class Agent < Base
+    VALID_CALLBACKS = [:signon, :signoff, :subscribe, :unsubscribe, :subscription_approval,
+                       :subscription_denial, :status_change, :status_message_change]
+
     class << self
       # Define a new command for the agent.
       # 
@@ -29,7 +32,8 @@ class Uppercut
       # end
       #
       def on(type, &block)
-        define_method("__on_#{type.to_s}__") { |conversation| block[conversation] }
+        raise 'Not a valid callback' unless VALID_CALLBACKS.include?(type)
+        define_method("__on_#{type.to_s}") { |conversation| block[conversation] }
       end
 
       private
@@ -76,34 +80,70 @@ class Uppercut
     # Calling listen fires off a new Thread whose sole purpose is to listen
     # for new incoming messages and then fire off a new Thread which dispatches
     # the message to the proper handler.
-    def listen(debug=false)
+    def listen
       connect unless connected?
 
       @listen_thread = Thread.new {
         @client.add_message_callback do |message|
-          next if message.body.nil?
-          next unless allowed_roster_includes?(message.from)
-
-          Thread.new do
-            begin
-              dispatch(message)
-            rescue => e
-              log e
-              raise if debug
-            end
+          log_and_continue do
+            next if message.body.nil?
+            next unless allowed_roster_includes?(message.from)
+            dispatch message
           end
         end
+
         @roster ||= Jabber::Roster::Helper.new(@client)
-        @roster.add_presence_callback do |item, oldp, newp|
-          dispatch_presence(item, newp)
+        @roster.add_presence_callback do |item, old_presence, new_presence|
+          # Callbacks:
+          # post-subscribe initial stuff (oldp == nil)
+          # status change: (oldp.show != newp.show)
+          # status message change: (oldp.status != newp.status)
+
+          log_and_continue do
+            if old_presence.nil? && new_presence.type == :unavailable
+              dispatch_presence :signoff, new_presence
+            elsif old_presence.nil?
+              # do nothing, we don't care
+            elsif old_presence.type == :unavailable && new_presence
+              dispatch_presence :signon, new_presence
+            elsif old_presence.show != new_presence.show
+              dispatch_presence :status_change, new_presence
+            elsif old_presence.status != new_presence.status
+              dispatch_presence :status_message_change, new_presence
+            end
+          end
         end
         @roster.add_subscription_request_callback do |item,presence|
-          next unless allowed_roster_includes?(presence.from)
-          @roster.accept_subscription(presence.from) 
-          dispatch_presence(item, presence)
+          # Callbacks:
+          # someone tries to subscribe (presence.type == 'subscribe')
+
+          log_and_continue do
+            case presence.type
+            when :subscribe
+              next unless allowed_roster_includes?(presence.from)
+              @roster.accept_subscription(presence.from)
+              @roster.add(presence.from, nil, true)
+              dispatch_presence :subscribe, presence
+            end
+          end
         end
         @roster.add_subscription_callback do |item, presence|
-          dispatch_presence(item, presence)
+          # Callbacks:
+          # user allows agent to subscribe to them (presence.type == 'subscribed')
+          # user denies agent subscribe request (presence.type == 'unsubscribed')
+          # user unsubscribes from agent (presence.type == 'unsubscribe')
+
+          log_and_continue do
+            case presence.type
+            when :subscribed
+              dispatch_presence :subscription_approval, presence
+            when :unsubscribed
+              # if item.subscription != :from, it's not a denial... it's just an unsub
+              dispatch_presence(:subscription_denial, presence) if item.subscription == :from
+            when :unsubscribe
+              dispatch_presence :unsubscribe, presence
+            end
+          end
         end
         sleep
       }
@@ -126,10 +166,17 @@ class Uppercut
       @redirects[contact].push block
     end
     
-    attr_accessor :allowed_roster
+    attr_accessor :allowed_roster, :roster
 
     private
 
+    def log_and_continue
+      yield
+    rescue => e
+      log e
+      raise if @debug
+    end
+
     def dispatch(msg)
       bare_from = msg.from.bare
       block = @redirects[bare_from].respond_to?(:shift) && @redirects[bare_from].shift
@@ -138,9 +185,9 @@ class Uppercut
       self.methods.grep(/^__uc/).sort.detect { |m| send(m,msg) != :no_match }
     end
 
-    def dispatch_presence(item, presence)
-      handler_method = "__on_#{presence.type.to_s}__"
-      self.send(handler_method, Conversation.new(presence.from, self)) if respond_to?(handler_method)
+    def dispatch_presence(type, presence)
+      handler = "__on_#{type}"
+      self.send(handler, Conversation.new(presence.from, self), presence) if respond_to?(handler)
     end
 
     def __ucDefault(msg)

data/spec/agent_spec.rb

@@ -124,6 +124,96 @@ describe Uppercut::Agent do
       @agent.should_receive(:dispatch)
       @agent.client.receive_message("foo@bar.com","test")
     end
+
+    describe 'presence callbacks' do
+      it 'processes :signon presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_signon
+        new_presence = Jabber::Presence.new(nil,nil)
+        old_presence = Jabber::Presence.new(nil,nil)
+        old_presence.type = :unavailable
+
+        @agent.roster.receive_presence(Jabber::Roster::Helper::RosterItem.new, old_presence, new_presence)
+      end
+
+      it 'processes :signoff presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_signoff
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :unavailable
+
+        @agent.roster.receive_presence(Jabber::Roster::Helper::RosterItem.new, nil, presence)
+      end
+
+      it 'processes :status_change presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_status_change
+
+        old_presence = Jabber::Presence.new(nil,nil)
+        new_presence = Jabber::Presence.new(nil,nil)
+        new_presence.show = :away
+
+        @agent.roster.receive_presence(Jabber::Roster::Helper::RosterItem.new, old_presence, new_presence)
+      end
+
+      it 'processes :status_message_change presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_status_message_change
+
+        old_presence = Jabber::Presence.new(nil,nil)
+        old_presence.status = 'chicka chicka yeaaaaah'
+
+        new_presence = Jabber::Presence.new(nil,nil)
+        new_presence.status = 'thom yorke is the man'
+
+        @agent.roster.receive_presence(Jabber::Roster::Helper::RosterItem.new, old_presence, new_presence)
+      end
+
+      it 'processes :subscribe presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_subscribe
+        @agent.roster.should_receive :add
+        @agent.roster.should_receive :accept_subscription
+
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :subscribe
+
+        @agent.roster.receive_subscription_request(Jabber::Roster::Helper::RosterItem.new, presence)
+      end
+
+      it 'processes :subscription_approval presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_subscription_approval
+
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :subscribed
+
+        @agent.roster.receive_subscription(Jabber::Roster::Helper::RosterItem.new, presence)
+      end
+
+      it 'processes :subscription_denial presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_subscription_denial
+
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :unsubscribed
+
+        item = Jabber::Roster::Helper::RosterItem.new
+        item.subscription = :from
+
+        @agent.roster.receive_subscription(item, presence)
+      end
+
+      it 'processes :unsubscribe presence callback' do
+        @agent.listen
+        @agent.should_receive :__on_unsubscribe
+
+        presence = Jabber::Presence.new(nil,nil)
+        presence.type = :unsubscribe
+
+        @agent.roster.receive_subscription(Jabber::Roster::Helper::RosterItem.new, presence)
+      end
+    end
   end
   
   describe :stop do
@@ -153,6 +243,16 @@ describe Uppercut::Agent do
       @agent.should_not be_listening
     end
   end
+
+  describe :dispatch_presence do
+    it 'calls the correct callback' do
+      @agent.listen
+      @agent.should_receive(:__on_subscribe)
+
+      presence = Jabber::Presence.new(nil,nil)
+      @agent.send(:dispatch_presence, :subscribe, presence)
+    end
+  end
   
   describe :dispatch do
     it "calls the first matching command" do

data/spec/jabber_stub.rb

@@ -46,13 +46,10 @@ class Jabber
   end
   
   class Presence
-    attr_accessor :from
+    attr_accessor :from, :type, :show, :status
 
     def initialize(a,b)
     end
-    
-    def from
-    end
   end
   
   class Message
@@ -64,12 +61,19 @@ class Jabber
   
   class Roster
     class Helper
+      class RosterItem
+        attr_accessor :subscription
+      end
+
       def initialize(client)
         @client = client
       end
       
       def accept_subscription(a)
       end
+
+      def add(a)
+      end
    
       attr_reader :on_subscription_request
       def add_subscription_request_callback(&block)
@@ -83,6 +87,20 @@ class Jabber
       def add_subscription_callback(&block)
         @on_subscription = block
       end
+
+      # TESTING HELPER METHODS
+
+      def receive_presence(item, old_presence, new_presence)
+        @on_presence[item, old_presence, new_presence]
+      end
+
+      def receive_subscription(item, presence)
+        @on_subscription[item, presence]
+      end
+
+      def receive_subscription_request(item, presence)
+        @on_subscription_request[item, presence]
+      end
     end
   end
 

data/spec/spec_helper.rb

@@ -35,6 +35,10 @@ class TestAgent < Uppercut::Agent
       c.send 'Hooray!'
     end
   end
+
+  Uppercut::Agent::VALID_CALLBACKS.each do |cb|
+    on(cb) { }
+  end
 end
 
 class TestNotifier < Uppercut::Notifier

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: tyler-uppercut
 version: !ruby/object:Gem::Version 
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors: 
 - Tyler McMullen
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-12-02 00:00:00 -08:00
+date: 2008-12-27 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -44,6 +44,7 @@ files:
 - spec/jabber_stub.rb
 - spec/notifier_spec.rb
 - spec/spec_helper.rb
+- examples/basic_agent.rb
 has_rdoc: false
 homepage: http://github.com/tyler/uppercut
 post_install_message: