openagent 0.7.1

data/README.md

@@ -0,0 +1,64 @@
+OpenAgent
+=========
+
+OpenAgent is a Ruby library for educational institutions that makes it easy to communicate with a ZIS (Zone Information Server). It implements most of the SIF 2.0r1 (School Interoperability Framework) specification.
+
+Getting Started
+--------------------
+
+```ruby
+client = OpenAgent::Client.connect(:name => "myagent", :url => "http://zis.institution.com/zis/myzone")
+
+# Send an initial request for all StudentPersonal objects
+client.request('StudentPersonal')
+
+# Set a callback so we can do something when we receive replies
+client.callback(:receive_message) do |message, http_response|
+  File.open("#{message.timestamp}.xml", "w") do |file|
+    file.write(http_response.body)
+  end
+end
+
+# Enter a polling loop
+client.run
+```
+
+Blog
+----
+http://blog.openzis.org/2010/08/23/creating-the-start-of-a-sif-agent-in-ruby/
+
+
+SIF 2.0 Spec
+------------
+http://specification.sifinfo.org/Implementation/2.0r1/
+
+History
+-------
+OpenAgent started as a Billboard.Net implementation of SIF in Ruby. Some features were later added by Instructure.
+
+TODO
+----
+
+- Convert old conditiongroup code to a DSL or something:
+```ruby
+  def create_conditiongroup(refobject, refid, operator="EQ")
+    cond1 = OpenAgent::Message::SIF_Request::SIF_Condition.new
+    cond1.element = "@SIF_RefObject"
+    cond1.operator = "EQ"
+    cond1.value = refobject
+
+    cond2 = OpenAgent::Message::SIF_Request::SIF_Condition.new
+    cond2.element = "@SIF_RefId"
+    cond2.operator = operator
+    cond2.value = refid
+
+    conditions = OpenAgent::Message::SIF_Request::SIF_Conditions.new
+    conditions.condition = [cond1, cond2]
+    conditions.type = 'And'
+
+    OpenAgent::Message::SIF_Request::SIF_ConditionGroup.new.tap do |cg|
+      cg.conditions = [conditions]
+      cg.type = 'None'
+    end
+  end
+```

data/lib/openagent.rb

@@ -0,0 +1,4 @@
+require 'openagent/message_builder'
+require 'openagent/zone'
+require 'openagent/agent'
+require 'openagent/client'

data/lib/openagent/agent.rb

@@ -0,0 +1,24 @@
+require 'virtus'
+
+module OpenAgent
+  class Agent
+    include Virtus.model
+
+    attribute :name,            String
+    attribute :source_id,       String,  :default => :name
+    attribute :version,         String,  :default => "2.0r1"
+    attribute :max_buffer_size, Integer, :default => 128_000
+    attribute :mode,            String,  :default => "Pull"
+    attribute :msg_version,     String,  :default => :version
+    attribute :msg_xmlns,       String,  :default => "http://www.sifinfo.org/infrastructure/2.x"
+
+    attribute :provide,         Array[String]
+    attribute :subscribe,       Array[String]
+    attribute :publish_add,     Array[String]
+    attribute :publish_change,  Array[String]
+    attribute :publish_delete,  Array[String]
+    attribute :request,         Array[String]
+    attribute :respond,         Array[String]
+
+  end
+end

data/lib/openagent/client.rb

@@ -0,0 +1,170 @@
+require "sif/sif"
+require "openagent/agent"
+require "openagent/zone"
+require "openagent/xml_helpers"
+require "openagent/errors"
+require "openagent/message_builder"
+require "logger"
+
+module OpenAgent
+  class Client
+    include XMLHelpers
+
+    attr_reader :name, :url
+    attr_reader :agent, :zone, :builder
+
+    ZIS_SUCCESS = 0
+    ZIS_NO_MESSAGES = 9
+
+    Message = SIF::Infra::Common::Message
+    MessageRepresenter = ::SIF::Representation::Infra::Common::Message
+
+    def self.connect(opts={})
+      Client.new(opts).tap do |client|
+        client.register
+        client.provision
+      end
+    end
+
+    def initialize(opts={})
+      @callbacks    = {
+          :receive_message => [],
+          :each_loop => []
+      }
+
+      @name         = opts.delete(:name)
+      @url          = opts.delete(:url)
+      @pretty_print = opts.has_key?(:pretty_print) ? opts.delete(:pretty_print) : true
+
+      @agent_opts = opts['agent_opts'] || {}
+      @agent_opts[:name] = @name if @name
+
+      @zone_opts = opts['zone_opts'] || {}
+      @zone_opts[:uri] = @url if @url
+
+      @log          = Logger.new(opts["log"] || STDOUT, 'daily')
+      @agent        = opts['agent'] || OpenAgent::Agent.new(@agent_opts)
+      @zone         = opts['zone'] || OpenAgent::Zone.new(@zone_opts)
+
+      @builder      = OpenAgent::MessageBuilder.new(@agent, @zone)
+    end
+
+    def log(name, body)
+      @log.info "#{name}\n#{body}\n"
+    end
+
+    # Proxy to OpenAgent::Messaging
+    def method_missing(method, *args, &block)
+      if @builder.respond_to?(method)
+        message = @builder.send(method, *args)
+        send_message(message, &block)
+      else
+        super
+      end
+    end
+
+    def callback(name, &block)
+      if cbs = @callbacks[name.to_sym]
+        cbs << block
+      else
+        raise "Can't register callback #{name}. " +
+              "Available callbacks: #{@callbacks.keys.inspect}"
+      end
+    end
+
+    def trigger(name, *args)
+      if cbs = @callbacks[name.to_sym]
+        cbs.each { |cb| cb.call(*args) }
+      else
+        raise "Can't trigger callback #{name}. " +
+              "Available callbacks: #{@callbacks.keys.inspect}"
+      end
+    end
+
+    def run
+      wait_short = 10
+      wait_long = 30
+      loop do
+        begin
+          trigger(:each_loop)
+
+          wait_period = wait_long
+          messages_in_queue = true
+          while messages_in_queue
+            get_message do |http_response, doc, status_code|
+              wrap_msg = Message.new
+              MessageRepresenter.new(wrap_msg).from_xml(http_response.body)
+
+              if message = wrap_msg.inner_message
+
+                trigger(:receive_message, wrap_msg, http_response)
+
+                if message.response
+                  case status_code
+                  when ZIS_SUCCESS then
+                    if message.response.morepackets?
+                      wait_period = wait_short
+                    else
+                      wait_period = wait_long
+                    end
+                  when ZIS_NO_MESSAGES then
+                    if not message.morepackets?
+                      wait_period = wait_long
+                    end
+                  end
+                end
+
+                # We send an Ack for both an Event and a Response
+                if status_code == ZIS_SUCCESS
+                  ack(message.sourceid, message.msgid)
+                end
+              else
+                if status_code == ZIS_NO_MESSAGES
+                  messages_in_queue = false
+                end
+              end
+            end
+          end
+          sleep wait_period
+        rescue ResponseError => e
+          @log.error e
+        end
+      end
+    end
+
+  protected
+
+    def check_for_errors(msg)
+      # First check for a SIF_Error tag
+      raise SIFError, msg.ack.error if msg.ack.error
+
+      # Next check for a SIF_Code != 0
+      status_code = msg.ack.status.code
+      raise SIFCodeError, status_code unless [0, 9].include? status_code
+
+      status_code
+    end
+
+    def send_message(outgoing, &block)
+      representer = MessageRepresenter.new(outgoing)
+      req = @zone.create_request(representer.to_xml)
+
+      log "Request", req.body
+      @zone.send_request(req).tap do |response|
+        log "Response", formatted_xml(response.body, @pretty_print)
+
+        if response.body.empty?
+          raise ResponseError, "Response is empty"
+        else
+          incoming = Message.new
+          MessageRepresenter.new(incoming).from_xml(response.body)
+
+          check_for_errors(incoming)
+
+          yield incoming if block_given?
+        end
+      end
+    end
+
+  end
+end

data/lib/openagent/errors.rb

@@ -0,0 +1,30 @@
+module OpenAgent
+  class ResponseError < StandardError
+    attr_reader :error_object
+    def initialize(msg, error_object=nil)
+      @error_object = error_object
+      super(msg)
+    end
+  end
+
+  class SIFError < ResponseError
+    def initialize(error_object)
+      @error_object = error_object
+      super(@error_object.desc, @error_object)
+    end
+  end
+
+  class SIFCodeError < ResponseError
+    CODES = {
+      0 => "Success. SIF_Status/SIF_Data may contain additional data.",
+      7 => "Already have a message with this SIF_MsgId from you.",
+      8 => "Receiver is sleeping.",
+      9 => "No messages available. This is returned when an agent is trying to pull messages from a ZIS and there are no messages available."
+    }
+    def initialize(status_code)
+      code = CODES[status_code]
+      raise "Unknown SIF_Status Code: #{status_code.inspect} (Known Codes: #{CODES.keys.inspect})" if code.nil?
+      super("Code #{status_code}: " + code)
+    end
+  end
+end

data/lib/openagent/message_builder.rb

@@ -0,0 +1,171 @@
+require "uuid"
+require "sif/sif"
+
+module OpenAgent
+  class MessageBuilder
+    attr_writer :timestamp, :guuid
+
+    def initialize(agent, zone)
+      @agent = agent
+      @zone = zone
+    end
+
+    def ack(original_source_id, original_msg_id, code=1)
+      SIF::Infra::Common::Message.new(
+        :version => @agent.msg_version,
+        :xmlns => @agent.msg_xmlns,
+        :ack => SIF::Infra::Message::Ack.new(
+          :header => create_header,
+          :original_source_id => original_source_id,
+          :original_msg_id => original_msg_id,
+          :status => SIF::Infra::Common::Status.new(
+            :code => code
+          )
+        )
+      )
+    end
+
+    def request(object_name, condition_group=nil)
+      SIF::Infra::Common::Message.new(
+        :version => @agent.msg_version,
+        :xmlns => @agent.msg_xmlns,
+        :request => SIF::Infra::Message::Request.new(
+          :version => @agent.version,
+          :max_buffer_size => @agent.max_buffer_size,
+          :header => create_header,
+          :query => SIF::Infra::Common::Query.new(
+            :query_object => SIF::Infra::Common::QueryObject.new(
+              :object_name => object_name
+            ),
+            :condition_group => condition_group
+          )
+        )
+      )
+    end
+
+    def event(object_name, action='Change', object=nil)
+      SIF::Infra::Common::Message.new(
+        :version => @agent.msg_version,
+        :xmlns => @agent.msg_xmlns,
+        :event => SIF::Infra::Common::Event.new(
+          :header => create_header,
+          :object_data => SIF::Infra::Common::ObjectData.new(
+            :event_object => SIF::Infra::Common::EventObject.new(
+              :object_name => object_name,
+              :action => action,
+              :objects => [
+                SIF::Infra::Common::Object.new(
+                  :object_name => object_name
+                )
+              ]
+            )
+          )
+        )
+      )
+    end
+
+    def provision
+      object = SIF::Infra::Common::Object
+      SIF::Infra::Common::Message.new(
+        :version => @agent.msg_version,
+        :xmlns => @agent.msg_xmlns,
+        :provision => SIF::Infra::Common::Provision.new(
+          :header => create_header,
+          :subscribe_objects =>
+            (@agent.subscribe || []).map { |o| object.new(:object_name => o) },
+          :provide_objects =>
+            (@agent.provide || []).map { |o| object.new(:object_name => o) },
+          :request_objects =>
+            (@agent.request || []).map { |o| object.new(:object_name => o) },
+          :respond_objects => 
+            (@agent.respond || []).map { |o| object.new(:object_name => o) },
+          :publish_add_objects => 
+            (@agent.publish_add || []).map { |o| object.new(:object_name => o) },
+          :publish_change_objects => 
+            (@agent.publish_change || []).map { |o| object.new(:object_name => o) },
+          :publish_delete_objects => 
+            (@agent.publish_delete || []).map { |o| object.new(:object_name => o) },
+        )
+      )
+    end
+
+    def register
+      SIF::Infra::Common::Message.new(
+        :version => @agent.msg_version,
+        :xmlns => @agent.msg_xmlns,
+        :register => SIF::Infra::Message::Register.new(
+          :name => @agent.name,
+          :version => @agent.version,
+          :max_buffer_size => @agent.max_buffer_size,
+          :mode => @agent.mode,
+          :header => create_header
+        )
+      )
+    end
+
+    def unregister
+      SIF::Infra::Common::Message.new(
+        :version => @agent.msg_version,
+        :xmlns => @agent.msg_xmlns,
+        :unregister => SIF::Infra::Message::Unregister.new(
+          :header => create_header
+        )
+      )
+    end
+
+    def ping
+      system_control(SIF::Infra::Message::Ping.new)
+    end
+
+    def sleep
+      system_control(SIF::Infra::Message::Sleep.new)
+    end
+
+    def wakeup
+      system_control(SIF::Infra::Message::Wakeup.new)
+    end
+
+    def get_message
+      system_control(SIF::Infra::Message::GetMessage.new)
+    end
+
+    def get_zone_status
+      system_control(SIF::Infra::Message::GetZoneStatus.new)
+    end
+
+    def get_agent_acl
+      system_control(SIF::Infra::Message::GetAgentACL.new)
+    end
+
+  protected
+
+    def timestamp
+      @timestamp || Time.now.strftime('%Y-%m-%dT%H:%M:%S')
+    end
+
+    def guuid
+      @guuid || UUID.generate(:compact).upcase
+    end
+
+    def create_header
+      SIF::Infra::Common::Header.new(
+        :msg_id => guuid(),
+        :source_id => @agent.source_id,
+        :timestamp => timestamp()
+      )
+    end
+
+    def system_control(message_instance)
+      SIF::Infra::Common::Message.new(
+        :version => @agent.msg_version,
+        :xmlns => @agent.msg_xmlns,
+        :system_control => SIF::Infra::Message::SystemControl.new(
+          :header => create_header,
+          :system_control_data => SIF::Infra::Message::SystemControlData.new(
+            :data => message_instance
+          )
+        )
+      )
+    end
+  end
+end