agent_xmpp 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,11 @@
+*.sw?
+.DS_Store
+coverage/*
+rdoc/*
+*.gem
+*.tmproj
+*.yml
+*.db
+log/*
+*.log
+test/xml_messages.txt

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Troy Stribling
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,417 @@
+= Agent XMPP
+
+Agent XMPP is a simple DSL for writing automated XMPP clients that support Messaging, Ad-Hoc Commands and Publish Subscribe 
+Events. An application that responds to an Ad-Hoc command can be written with few lines of code.
+
+    # myapp.rb
+    require 'rubygems'
+    require 'agent_xmpp'
+
+    command 'hello' do
+      'Hello World' 
+    end
+
+Specify the application Jabber ID (JID), password and roster in <tt>agent_xmpp.yml</tt>.
+
+    jid: myapp@nowhere.com
+    password: none
+    roster:
+        - 
+            jid:you@home.com
+            groups: [admin]
+
+Be sure libxml2 headers are available and that libsqlite3-ruby1.9.1 is installed,
+
+    sudo apt-get install libxml2-dev
+    sudo apt-get install libsqlite3-ruby1.9.1
+
+Install the gem,
+
+    sudo gem install troystribling-agent_xmpp --source=http://gems.github.com
+
+Install the Gajim XMPP Client version 0.12.3 or higher, http://www.gajim.org, and connect to <i>you@home.com</i>. 
+
+Run the application,
+
+    ruby myapp.rb
+
+When started for the first time <tt>myapp.rb</tt> will automatically send buddy requests to all contacts specified
+in <tt>agent_xmpp.yml</tt>. Accept the buddy request and _myapp_ will appear as a contact in the Gajim roster. Right click on _myapp_
+and select _execute_ _commands_ from the drop down menu. A list of Ad-Hoc Commands will be displayed containing _hello_. 
+Select it and click the _forward_ _button_ to execute.
+
+== Supported Environment
+
+The following versions of ruby are supported
+
+    ruby 1.9.1
+    
+The following Operating Systems are supported
+    
+    Ubuntu 10.4
+    
+== Ad-Hoc Command Response Payload
+
+Agent XMPP will map native ruby scalars, arrays and hashes returned by <tt>execute</tt> blocks to jabber:x:data command 
+response payloads (see XEP-0004 http://xmpp.org/extensions/xep-0004.html for a description of jabber:x:data).
+
+    command 'scalar' do
+      'scalar' 
+    end
+
+    command 'hash' do
+      {:a1 => 'v1', :a2 => 'v2'}
+    end
+
+    command 'scalar_array' do
+      ['v1', 'v2','v3', 'v4'] 
+    end
+
+    command 'hash_array' do
+      {:a1 => ['v11', 'v11'], :a2 => 'v12'}
+    end
+
+    command 'array_hash' do
+      [{:a1 => 'v11', :a2 => 'v12'}, 
+       {:a1 => 'v21', :a2 => 'v22'}, 
+       {:a1 => 'v31', :a2 => 'v32'}]
+    end
+
+    command 'array_hash_array' do
+      [{:a1 => ['v11', 'v11'], :a2 => 'v12'}, 
+       {:a1 => ['v21', 'v21'], :a2 => 'v22'}, 
+       {:a1 => ['v31', 'v31'], :a2 => 'v32'}]
+    end
+
+a <tt>params</tt> structure is available within the <tt>execute</tt> block containing routing information.
+
+== Ad-Hoc Command Forms
+
+Agent XMPP supports 
+== Send Commands
+
+Commands may be sent with or without a response callback,
+
+    send_command(:to=>'thatapp@a-place.com/ahost', :node=> 'hello') do |status, data|
+      puts "COMMAND RESPONSE: #{status}, #{data.inspect}"
+    end
+
+    send_command(:to=>'thatapp@a-place.com/ahost', :node=> 'bye')
+
+and within <tt>command</tt> blocks.
+
+    command 'hash_hello' do
+      send_command(:to=>params[:from], :node=> 'hello') do |status, data|
+        puts "COMMAND RESPONSE: #{status}, #{data.inspect}"
+      end
+      {:a1 => 'v1', :a2 => 'v2'}
+    end
+
+== Publish
+
+Publish nodes are configured in <tt>agent_xmpp.yml</tt>.
+
+    jid: myapp@nowhere.com
+    password: none
+    roster:
+        - 
+            jid:you@home.com
+    publish:
+        - 
+            node: time
+            title: "Curent Time"   
+        - 
+            node: alarm
+            title: "Alarms"   
+
+The nodes are created if they do not exist and publish methods are generated for each node.
+
+    publish_time('The time is:' + Time.now.to_s)
+    
+    publish_alarm({:severity => :major, :description => "A really bad failure"})
+
+Publish nodes discovered that are not in <tt>agent_xmpp.yml</tt> will be deleted.
+
+== Publish Options
+
+The following publish options are available with the indicated default values. The options may be changed in
+<tt>agent_xmpp.yml</tt>.
+
+    :title                    => 'event',
+    :access_model             => 'presence',
+    :max_items                => 20,
+    :deliver_notifications    => 1,
+    :deliver_payloads         => 1,
+    :persist_items            => 1,
+    :subscribe                => 1,
+    :notify_config            => 0,
+    :notify_delete            => 0,
+    :notify_retract           => 0,
+
+See http://xmpp.org/extensions/xep-0060.html#registrar-formtypes-config for a detailed description.
+
+== Subscribe
+
+Declare <tt>event</tt> blocks in <tt>myapp.rb</tt> to subscribe to published events.
+
+    # myapp.rb
+    require 'rubygems'
+    require 'agent_xmpp'
+
+    event 'someone@somewhere.com', 'time' do
+      message(:to=>'someone@somewhere.com', :body=>"Got the event at: " + Time.now.to_s)
+    end
+
+Agent XMPP will verify subscription to the event and subscribe if required. Subscriptions
+discovered that are not declared by an event block will be deleted.
+
+== Receive Chat Messages
+
+Declare <tt>chat</tt> blocks in <tt>myapp.rb</tt> to receive and respond to chat messages.
+  
+    # myapp.rb
+    require 'rubygems'
+    require 'agent_xmpp'
+
+    chat do
+      params[:body].reverse
+    end
+
+If the <tt>chat</tt> block returns a <tt>String</tt> a response will be sent to the message sender.
+
+== Send Chat Messages
+
+    send_chat(:to=>'thatapp@a-place.com/onahost', :body=>"Hello from #{AgentXmpp.jid.to_s} at " + Time.now.to_s)
+    
+== Roster
+
+Roster groups may be specified in <tt>agent_xmpp.yml</tt>.
+
+    jid: myapp@nowhere.com
+    password: none
+    roster:
+        - 
+            jid:you@home.com
+            groups: [good group, owners]
+        
+        - 
+            jid: someone@somewhere.com
+            groups: [bad group]
+     
+Agent XMPP will update the roster maintained on the XMPP server to be consistent with to the roster specified in <tt>agent_xmpp.yml</tt>. 
+
+== Routing Priority
+
+The routing priority may be configured in <tt>agent_xmpp.yml</tt>. The default value is 1. Valid values are between -127 and 128. 
+See http://xmpp.org/rfcs/rfc3921.html for a details.
+
+    jid: myapp@nowhere.com
+    password: none
+    priority: 128
+    roster:
+        - 
+            jid:you@home.com
+            groups: [good group, owners]
+        
+== Major Event Callbacks
+
+Agent XMPP provides callbacks for applications to respond to major events that occur during execution.
+ 
+    # application starting
+    before_start{}
+
+    # connected to server
+    after_connected{|connection|}
+
+    # client restarts when disconnected form server
+    restarting_client{|connection|}
+    
+    # a pubsub node was discovered at service
+    discovered_pubsub_node{|service, node|}
+    
+    # command nodes were discovered at jid
+    discovered_command_nodes{|jid, nodes|}
+
+    # a presence message of status :available or :unavailable was received from jid
+    received_presence{|from, status|}
+    
+== Authentication
+    
+* Basic SASL
+
+== Development with XMPP Clients
+
+Ad-Hoc Commands, jabber:x:data Forms nor Service Discovery are widely supported by XMPP clients and I have not found
+a client that supports Publish-Subscribe. Gajim http://www.gajim.org provides support for Ad-Hoc Commands and jabber:x:data Forms. Service Discovery,
+which is useful for Publish-Subscibe development, is supported by Gajim, but Psi http://psi-im.org provides a much better
+implementation. Both Gajim and Psi provide an interface for manual entry of XML messages. Since Publish-Subscribe is not supported on
+the user interface manual entry of messages is required for development. Example messages can be found at http://gist.github.com/160344
+
+== Logging
+
+By default log messages are written to STDOUT. A log file can be specified with the -l option.
+
+        ruby mybot.rb -l file.log
+
+The logger can be accessed and configured.
+        
+        before_start do
+          AgentXmpp.logger.level = Logger::WARN 
+        end
+
+== More Examples
+
+More examples can be found at http://gist.github.com/160338
+
+== Supported XEPs
+
+    XEP-0004 jabber:x:data Forms    http://xmpp.org/extensions/xep-0004.html
+    XEP-0030 Service Discovery      http://xmpp.org/extensions/xep-0030.html
+    XEP-0050 Ad-Hoc Commands        http://xmpp.org/extensions/xep-0050.html
+    XEP-0060 Publish Subscribe      http://xmpp.org/extensions/xep-0060.html
+    XEP-0092 Software Version       http://xmpp.org/extensions/xep-0092.html
+
+== Message Processing Callbacks
+
+Message processing callbacks are available to applications to extend the message processing work flow. To receive
+callbacks a delegate object must be provided that implements the callbacks of interest.   
+
+    after_connected do |connection|
+      connection.add_delegate(YourDelegate)
+    end
+
+=== Connection
+
+    on_connect(connection)
+
+    on_disconnect(connection)
+
+    on_did_not_connect(connection)
+
+=== Authentication
+
+    on_bind(connection)
+
+    on_preauthenticate_features(connection)
+
+    on_authenticate(connection)
+
+    on_did_not_authenticate(connection)
+
+    on_postauthenticate_features(connection)
+
+    on_start_session(connection)
+
+=== Presence
+
+    on_presence(connection, presence)
+
+    on_presence_subscribe(connection, presence)
+
+    on_presence_subscribed(connection, presence)
+
+    on_presence_unavailable(connection, presence)
+
+    on_presence_unsubscribed(connection, presence)
+    
+    on_presence_error(pipe, presence)
+
+=== Roster
+
+    on_roster_result(connection, stanza)
+
+    on_roster_set(connection, stanza)
+
+    on_roster_item(connection, roster_item)
+
+    on_remove_roster_item(connection, roster_item)
+
+    on_all_roster_items(connection)
+
+    on_update_roster_item_result(connection, item_jid)
+
+    on_update_roster_item_error(connection, item_jid)
+
+    on_remove_roster_item(connection, item_jid)
+
+    on_remove_roster_item_error(connection, item_jid)
+
+=== Service Discovery
+
+    on_version_result(connection, version)
+
+    on_version_get(connection, request)
+
+    on_version_error(connection, error)
+    
+    on_discoinfo_get(connection, request) 
+
+    on_discoinfo_result(connection, discoinfo)
+    
+    on_discoinfo_error(connection, error)
+    
+    on_discoitems_result(connection, discoitems)
+    
+    on_discoitems_get(connection, request)
+
+    on_discoitems_error(connection, result)
+            
+=== Applications
+
+    on_command_set(connection, stanza)
+
+    on_message_chat(connection, stanza)
+
+    on_message_normal(connection, stanza)
+
+    on_pubsub_event(connection, event, to, from)
+
+=== PubSub
+
+    on_publish_result(connection, result, node)
+
+    on_publish_error(connection, result, node)
+
+    on_discovery_of_pubsub_service(connection, jid, ident)
+    
+    on_discovery_of_pubsub_collection(connection, jid, node)
+      
+    on_discovery_of_pubsub_leaf(connection, jid, node)
+
+    on_discovery_of_user_pubsub_root(pipe, pubsub, node)
+
+    on_pubsub_subscriptions_result(connection, result)
+    
+    on_pubsub_subscriptions_error(connection, result)
+
+    on_pubsub_affiliations_result(connection, result)
+    
+    on_pubsub_affiliations_error(connection, result)
+
+    on_discovery_of_user_pubsub_root(connection, result)
+    
+    on_create_node_result(connection, node, result)    
+
+    on_create_node_error(connection, node, result)    
+
+    on_delete_node_result(connection, node, result)    
+
+    on_delete_node_error(connection, node, result)    
+
+    on_pubsub_subscribe_result(connection, result, node) 
+
+    on_pubsub_subscribe_error(connection, result, node) 
+
+    on_pubsub_subscribe_error_item_not_found(connection, result, node) 
+
+    on_pubsub_unsubscribe_result(connection, result, node) 
+
+    on_pubsub_unsubscribe_error(connection, result, node) 
+    
+=== ERRORS
+
+    on_unsupported_message(connection, stanza)
+
+== Copyright
+
+Copyright (c) 2009 Troy Stribling. See LICENSE for details.