mrw-uppercut 0.0.1.pre1

data/README.textile

@@ -0,0 +1,151 @@
+h1. Uppercut
+
+
+h2. Overview
+
+Uppercut is a little DSL for writing agents and notifiers which you interact with via your Jabber client.
+
+
+h2. Making an Agent
+
+You could put together a very simple agent as follows:
+
+<pre>
+  <code>
+    class BasicAgent < Uppercut::Agent
+      command 'date' do |c|
+        m.send `date`
+      end
+  
+      command /^cat (.*)/ do |c, rest|
+        m.send File.read(rest)
+      end
+  
+      command 'report' do |c|
+        m.send 'Hostname: ' + `hostname`
+        m.send 'Running as: ' + ENV['USER']
+      end
+    end
+  </code>
+</pre>
+
+With the above code, we've created an Agent template of sorts.  It responds to three commands: {date cat report}.
+The block which is passed to "command" should always have at least one paramater.  The first parameter will 
+always be an Uppercut::Conversation object, which can be used to respond to the user who sent the input.  When passing
+a regular expression as the first parameter to "command", all of the _captures_ which the pattern match generates
+will also be passed to the block.  This can be seen in the "cat" example above.  There is one capture and it is
+passed in as _rest_.
+
+Then to actually put the Agent to work...
+
+<pre>
+  <code>
+    BasicAgent.new('user@server/resource', 'password').listen
+  </code>
+</pre>
+
+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
+
+<pre>
+  <code>
+    class BasicNotifier < Uppercut::Notifier
+      notifier :error do |m, data|
+        m.to 'tbmcmullen@gmail.com'
+        m.send "Something in your app blew up: #{data}"
+      end
+    end
+  </code>
+</pre>
+
+So, we make a new Notifier class and call a _notifier_ block within it.  This makes a notifier with the name :error, which sends a message to tbmcmullen@gmail.com when it fires.
+
+<pre>
+  <code>
+    notifier = BasicNotifier.new('user@server/resource', 'password').connect
+    
+    notifier.notify :error, 'Sprocket Error!'
+  </code>
+</pre>
+
+The purpose of a Notifier is just to make a multi-purpose event-driven notification system.  You could use it notify yourself of errors in your Rails app, or ping you when a new comment arrives on your blog, or ... I dunno, something else.
+
+The way I intend a Notifier to be used though is with Starling.  Take the following example...
+
+<pre>
+  <code>
+    notifier = BasicNotifier.new('user@server', 'password', :starling => 'localhost:22122', :queue => 'basic')
+    notifier.listen
+    sleep
+  </code>
+</pre>
+
+<pre>
+  <code>
+    require 'starling'
+    starling = Starling.new('localhost:22122')
+    starling.set 'basic', :error
+  </code>
+</pre>
+
+In that example, we have the same BasicNotifier.  Except this time, we provide it with information on which Starling queue on which Starling server to monitor.  Meanwhile, in the separate program, we attach to that same Starling server and push a symbol onto that same queue.
+
+In this case, what happens is BasicNotifier sees that symbol and begins processing it, just as if it had been passed in via the #notify method.
+
+
+
+h2. Todo
+
+
+h3. Security
+
+If you intend to use this on an open Jabber network (read: Google Talk) take some precautions.  Agent#new takes an optional list of JIDs that the agent will respond to.
+
+<pre>
+  <code>
+    BasicAgent.new('user@server/res', 'pw', :roster => ['you@server'])
+  </code>
+</pre>
+
+The agent created with the above statement will not respond to messages or subscription requests from anyone other than 'you@server'.
+
+h3. Features
+
+Uppercut is currently very thin on features, as it's in its infancy.  Here's a brief list of where I'm
+currently intending to take the project:
+
+* send files to and receive files from agents
+* improving the way one writes executables (using the Daemons library is best for the moment)
+* auto-updating of agents
+* I swear I'm going to find a use for MUC
+* allow agents to establish communications on their own, rather than being reactionary (think RSS updates)
+* ... other stuff that sounds fun to code up ...

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+patch: 1
+major: 0
+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/examples/personal.rb

@@ -0,0 +1,42 @@
+require 'rubygems'
+require 'uppercut'
+require 'yahoo-weather'
+require 'feed_tools'
+
+class PersonalAgent < Uppercut::Agent
+  def get_weather
+    @weather_client ||= YahooWeather::Client.new
+    @weather_client.lookup_location('94102') # lookup by zipcode
+  end
+
+  def get_news
+    FeedTools::Feed.open('feed://www.nytimes.com/services/xml/rss/nyt/HomePage.xml')
+  end
+
+  command 'weather' do |c, args|
+    weather = get_weather
+    c.send "#{weather.title}\n#{weather.condition.temp} degrees\n#{weather.condition.text}"
+  end
+
+  command 'forecast' do |c, args|
+    response = get_weather
+    msg = "#{response.forecasts[0].day} - #{response.forecasts[0].text}. "
+    msg << "High: #{response.forecasts[0].high} Low: #{response.forecasts[0].low}\n"
+    msg << "#{response.forecasts[1].day} - #{response.forecasts[1].text}. "
+    msg << "High: #{response.forecasts[1].high} Low: #{response.forecasts[1].low}\n"
+    c.send msg
+  end
+
+  command 'news' do |c, args|
+    msg = get_news.items[0, 5].map { |item|
+      "#{item.title}\n#{item.link}"
+    }.join("\n\n")
+    c.send msg
+  end
+end
+
+if $0 == __FILE__
+  agent = PersonalAgent.new('name@domain.com/PersonalAgent', 'password')
+  agent.listen
+  sleep
+end

data/lib/uppercut.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'xmpp4r'
+require 'xmpp4r/roster'
+
+%w(base agent notifier message conversation).each do |mod|
+  require File.join(File.dirname(__FILE__), "uppercut/#{mod}")
+end
+

data/lib/uppercut/agent.rb

@@ -0,0 +1,229 @@
+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.
+      # 
+      # The pattern can be a String or a Regexp.  If a String is passed, it
+      # will dispatch this command only on an exact match.  A Regexp simply
+      # must match.
+      #
+      # There is always at least one argument sent to the block.  The first
+      # is a always an Uppercut::Message object, which can be used to reply
+      # to the sender. The rest of the arguments to the block correspond to
+      # any captures in the pattern Regexp. (Does not apply to String 
+      # patterns).
+      def command(pattern, &block)
+        commands.delete_if{|command| command[0] == pattern }
+        commands << [pattern, block]
+      end
+
+      # Define a callback for specific presence events.
+      #
+      # At the moment this is only confirmed to work with :subscribe and :unsubscribe, but it may work with other types as well.
+      # Example:
+      #
+      # on :subscribe do |conversation|
+      #   conversation.send "Welcome! Send 'help' for instructions."
+      # end
+      #
+      def on(type, &block)
+        raise 'Not a valid callback' unless VALID_CALLBACKS.include?(type)
+        callbacks[type] = block
+      end
+      
+      def commands #:nodoc:
+        @commands ||= []
+      end
+      
+      def callbacks #:nodoc:
+        @callbacks ||= {}
+      end
+    end
+
+    DEFAULT_OPTIONS = { :connect => true }
+    
+    # Create a new instance of an Agent, possibly connecting to the server.
+    #
+    # user should be a String in the form: "user@server/Resource".  pw is
+    # simply the password for this account.  The final, and optional, argument
+    # is a boolean which controls whether or not it will attempt to connect to
+    # the server immediately.  Defaults to true.
+    def initialize(user, pw, options={})
+      options = DEFAULT_OPTIONS.merge(options)
+      
+      @user = user
+      @pw = pw
+      connect if options[:connect]
+      listen if options[:listen]
+      
+      @allowed_roster = options[:roster]
+      @redirects = {}
+    end
+    
+
+    def inspect #:nodoc:
+      "<Uppercut::Agent #{@user} " +
+      "#{listening? ? 'Listening' : 'Not Listening'}:" +
+      "#{connected? ? 'Connected' : 'Disconnected'}>"
+    end
+
+    # Makes an Agent instance begin listening for incoming messages and
+    # subscription requests.
+    #
+    # Current listen simply eats any errors that occur, in the interest of
+    # keeping the remote agent alive.  These should be logged at some point
+    # in the future. Pass debug as true to prevent this behaviour.
+    #
+    # 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
+      connect unless connected?
+
+      @listen_thread = Thread.new {
+        @client.add_message_callback do |message|
+          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, 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|
+          # 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|
+          # 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
+      }
+    end
+
+    # Stops the Agent from listening to incoming messages.
+    #
+    # Simply kills the thread if it is running.
+    def stop
+      @listen_thread.kill if listening?
+    end
+
+    # True if the Agent is currently listening for incoming messages.
+    def listening?
+      @listen_thread && @listen_thread.alive?
+    end
+    
+    def redirect_from(contact, &block)
+      @redirects[contact] ||= []
+      @redirects[contact].push block
+    end
+    
+    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
+      return block[msg.body] if block
+
+      captures = nil
+      pair = self.class.commands.detect { |pattern, block| captures = matches?(pattern, msg.body) }
+      if pair
+        block = pair[1]
+        conversation = Conversation.new(msg.from, self)
+        arguments = [ conversation, *captures ][0..block.arity-1]
+        if block.arity < 1
+          conversation.instance_eval(&block)
+        else
+          block.call(*arguments)
+        end
+      end
+    end
+
+    def dispatch_presence(type, presence)
+      return unless self.class.callbacks[type]
+      self.class.callbacks[type].call(Conversation.new(presence.from, self), presence)
+    end
+
+    def __ucDefault(msg)
+      Message.new(msg.from, self).send("I don't know what \"#{msg.body}\" means.")
+    end
+
+    def matches?(pattern, msg)
+      captures = nil
+      case pattern
+      when String
+        captures = [] if pattern == msg
+      when Regexp
+        match_data = pattern.match(msg)
+        captures = match_data.captures if match_data
+      end
+      captures
+    end
+
+    def allowed_roster_includes?(jid)
+      return true unless @allowed_roster
+      
+      jid = jid.to_s
+      return true if @allowed_roster.include?(jid)
+      return true if @allowed_roster.include?(jid.sub(/\/[^\/]+$/, ''))
+    end
+
+  end
+end