siffer 0.0.4

data/lib/messages/error.rb

@@ -0,0 +1,174 @@
+module Siffer
+  module Messages
+    class Error
+      
+      attr_reader :category, :code, :description
+      
+      def initialize(category, code, desc = nil)
+        @category = CATEGORY[category]
+        @category_index = category
+        @code = CODE[@category][code]
+        @code_index = code
+        @description = desc
+      end
+      
+      def read
+        xml = Builder::XmlMarkup.new
+        xml.SIF_Error { |error|
+          error.SIF_Category(@category_index)
+          error.SIF_Code(@code_index)
+          error.SIF_Desc(@code)
+          error.SIF_ExtendedDesc(@description) unless @description.nil?
+        }
+      end
+      alias :to_str :read
+  
+      
+      # Categories of Errors specified by SIF
+      CATEGORY = [
+        "Unknown (This should NEVER be used if possible)",
+        "XML Validation",
+        "Encryption",
+        "Authentication",
+        "Access and Permissions",
+        "Registration",
+        "Provision",
+        "Subscription",
+        "Request and Response",
+        "Event Reporting and Processing",
+        "Transport",
+        "System (OS, Database, Vendor localized, etc.)",
+        "Generic Message Handling",
+        "SMB Handling"
+      ]
+      
+      # Codes related to CATEGORY
+      # Some codes are blank to match the SIF Spec
+      CODE = {
+        CATEGORY[1] => [ # Xml Validation
+          "",
+          "Generic error",
+          "Message is not well-formed",
+          "Generic validation error",
+          "Invalid value for element/attribute",
+          "",
+          "Missing mandatory element/attribute"
+          ],
+        CATEGORY[2] => [ # Encryption
+          "",
+          "Generic error"
+          ],
+        CATEGORY[3] => [ # Authentication
+          "",
+          "Generic error",
+          "Generic authentication error (with signature)",
+          "Missing sender's certificate",
+          "Invalid certificate",
+          "Sender's certificate is not trusted",
+          "Expired certificate",
+          "Invalid signature",
+          "Invalid encryption algorithm (only accepts MD4)",
+          "Missing public key of the receiver (when decrypting message)", 
+          "Missing receiver's private key (when decrypting message)"
+          ],
+        CATEGORY[4] => [ # Access and Permissions
+          "",
+          "Generic error",
+          "No permission to register",
+          "No permission to provide this object",
+          "No permission to subscribe to this SIF_Event",
+          "No permission to request this object",
+          "No permission to respond to this object request", 
+          "No permission to publish SIF_Event",
+          "No permission to administer policies",
+          "SIF_SourceId is not registered",
+          "No permission to publish SIF_Event Add",
+          "No permission to publish SIF_Event Change",
+          "No permission to publish SIF_Event Delete"
+          ],
+        CATEGORY[5] => [ # Registration
+          "",
+          "Generic error",
+          "The SIF_SourceId is invalid",
+          "Requested transport protocol is unsupported", 
+          "Requested SIF_Version(s) not supported",
+          "",
+          "Requested SIF_MaxBufferSize is too small", 
+          "ZIS requires a secure transport",
+          "",
+          "Agent is registered for push mode (returned when a push-mode agent sends a SIF_GetMessage)", 
+          "ZIS does not support the requested Accept-Encoding value"    
+          ],
+        CATEGORY[6] => [ # Provision
+          "",
+          "Generic error",
+          "",
+          "Invalid object", 
+          "Object already has a provider (SIF_Provide message)"
+          ],
+        CATEGORY[7] => [ # Subscription
+          "",
+          "Generic error",
+          "",
+          "Invalid object"
+          ],
+        CATEGORY[8] => [ # Request and Response
+          "",
+          "Generic error",
+          "",
+          "Invalid object",
+          "No provider",
+          "",
+          "",
+          "Responder does not support requested SIF_Version",
+          "Responder does not support requested SIF_MaxBufferSize",
+          "Unsupported query in request",
+          "Invalid SIF_RequestMsgId specified in SIF_Response",
+          "SIF_Response is larger than requested SIF_MaxBufferSize",
+          "SIF_PacketNumber is invalid in SIF_Response",
+          "SIF_Response does not match any SIF_Version from SIF_Request",
+          "SIF_DestinationId does not match SIF_SourceId from SIF_Request", 
+          "No support for SIF_ExtendedQuery",
+          "SIF_RequestMsgId deleted from cache due to timeout",
+          "SIF_RequestMsgId deleted from cache by administrator",
+          "SIF_Request cancelled by requesting agent"
+          ],
+        CATEGORY[9] => [ # Event Reporting and Processing
+          "",
+          "Generic error",
+          "", 
+          "Invalid event"
+          ],
+        CATEGORY[10] => [ # Transport
+          "",
+          "Generic error",
+          "Requested protocol is not supported",
+          "Secure channel requested and no secure path exists", 
+          "Unable to establish connection"
+          ],
+        CATEGORY[11] => [ # System
+          "",
+          "Generic Error"
+          ],
+        CATEGORY[12] => [ # Generic Message Handling
+          "",
+          "Generic error",
+          "Message not supported",
+          "Version not supported",
+          "Context not supported",
+          "Protocol error",
+          "No such message (as identified by SIF_OriginalMsgId)", 
+          "Multiple contexts not supported"
+          ],
+        CATEGORY[13] => [ # SMB Handling
+          "",
+          "Generic error",
+          "SMB can only be invoked during a SIF_Event acknowledgement", 
+          "Final SIF_Ack expected from Push-Mode Agent",
+          "Incorrect SIF_MsgId in final SIF_Ack"
+          ]
+      }
+      
+    end
+  end
+end

data/lib/messages/message.rb

@@ -0,0 +1,71 @@
+module Siffer
+  module Messages
+    
+    # Base class for all Messages in the framework. Embeds the XMLNS as
+    # well as the version of SIF implemented.
+    class Message
+    
+      attr_reader :xmlns, :version, :header
+      
+      # source parameter is required (string describing the original sender)
+      def initialize(source, options = {})
+        raise ArgumentError, "Source not provided." if source.nil?
+        @xmlns = options[:xmlns] || Siffer.sif_xmlns
+        @version = options[:version] || Siffer.sif_version
+        @header = Header.new(source)
+        @body = Builder::XmlMarkup.new
+      end
+      
+      # Builds the xml for this message. Accepts a block if nested 
+      # elements are required.
+      def content
+        @xml ||= @body.SIF_Message(:version => @version, :xmlns => @xmlns) { |xml|
+          yield xml if block_given?
+        }
+      end
+      
+      # Alias method to the Header SourceId
+      def source_id() header.source_id; end
+      # Alias method to the Header MsgId
+      def msg_id() header.msg_id; end
+      
+      # used to remove the stack too deep issue when overridden
+      # there has to be a better way .... TODO: Fix the alias crap
+      alias :body :content 
+      
+      def put_header_into(xml)
+        xml.SIF_Header { |head|
+          head.SIF_MsgId(@header.msg_id)
+          head.SIF_Timestamp(@header.timestamp)
+          head.SIF_SourceId(@header.source_id)
+        }
+      end
+      
+      # Returns the content of the message
+      def read
+        # this construct prevents the xml from being built
+        # over and over again for every read made to this
+        # message.
+        @xml ||= content
+      end
+      alias :to_str :read
+      
+      # Each Message requires a Header to identify the source.
+      # You shouldn't need to initialize this by itself, it is
+      # used by Message.
+      class Header
+      
+        attr_reader :timestamp, :msg_id, :source_id
+      
+        def initialize(source)
+          raise ArgumentError, "Source not provided." if source.nil?
+          @timestamp = Time.now
+          @msg_id = UUID.generate(:compact).upcase
+          @source_id = source
+        end
+      
+      end
+  
+    end
+  end
+end

data/lib/messages/register.rb

@@ -0,0 +1,60 @@
+module Siffer
+  module Messages
+    
+    # Message used by Agents to register themselves with the ZIS.
+    class Register < Message
+      
+      attr_reader :name, :version, :vendor, :max_buffer, :mode
+      
+      def initialize(source, name, options = {})
+        super(source, options)
+        raise ArgumentError, "Agent name required" unless name
+        @name = name
+        @version = options[:version] || Siffer.sif_version
+        @max_buffer = options[:max_buffer] || 1024
+        @mode = options[:mode] || 'Pull'
+        @vendor = options[:vendor] || Siffer.vendor
+      end
+      
+      def content
+        body do |reg|
+          reg.SIF_Register() { |xml|
+            put_header_into xml
+            reg.SIF_Name(@name)
+            reg.SIF_Version(@version)
+            reg.SIF_MaxBufferSize(@max_buffer)
+            reg.SIF_Mode(@mode)
+          }
+        end
+      end
+      
+      # Parses the body passed as a Register message and returns a
+      # RequestBody that provides access to Register properties.
+      def self.parse(body)
+        RegisterBody.parse(body)
+      end
+      
+      class RegisterBody < RequestBody #:nodoc:
+        
+        def name
+          (@doc/:SIF_Name).text
+        end
+      
+        def version
+          (@doc/:SIF_Version).text
+        end
+      
+        def max_buffer
+          (@doc/:SIF_MaxBufferSize).text.to_i
+        end
+      
+        def mode
+          (@doc/:SIF_Mode).text
+        end
+        
+      end
+      
+    end
+    
+  end
+end

data/lib/messages/request_body.rb

@@ -0,0 +1,66 @@
+module Siffer
+  
+  module Messages
+    
+    # This class is used to parse the SIF Message information
+    # out of the Request Body. It parses enough information to redirect
+    # to other processes. It does not parse details of the Message such as
+    # Protocol if a Register message, or Error if an Ack message. Each 
+    # message type will inherit this class in order to provide a #parse
+    # method that will allow access to those specific attributes.
+    # It provides access to:
+    # * source_id
+    # * msg_id
+    # * type
+    class RequestBody
+      
+      def initialize(xml_string)
+        @xml = xml_string
+        @doc = Hpricot(@xml, :xml => true)
+      end
+      
+      # Will return the name of the element found just inside the root
+      # or just inside SIF_SystemControl if present. 
+      def type
+        begin
+          msg_type = (@doc/:SIF_Message).first.children[0].name
+          if msg_type == "SIF_SystemControl"
+            msg_type = (@doc/:SIF_Message/:SIF_SystemControl).first.children[0].name
+          end
+          drop_sif msg_type
+        rescue
+          raise "Failed to parse #{@xml} for SIF Type"
+        end
+      end
+      
+      # The SIF_SourceId from the SIF_Header
+      def source_id
+        (@doc/"//SIF_Header/SIF_SourceId/").text
+      end
+      
+      # The SIF_MsgId from the SIF_Header
+      def msg_id
+        (@doc/"//SIF_Header/SIF_MsgId/").text
+      end
+      
+      # Parses the xml provided and returns a RequestBody.
+      # Xml must respond to read or be a String.
+      def self.parse(xml)
+        unless xml.respond_to?("read") or xml.is_a?(String)
+          raise ArgumentError, "Unable to read Xml" 
+        end
+        xml = xml.read if xml.respond_to?("read")
+        self.new(xml) # use self because we are going to inherit this class
+      end
+      
+      private
+        # Drops the SIF_ from the front of the string provided
+        def drop_sif(string)
+          string.gsub!("SIF_","")
+        end
+      
+    end
+    
+  end
+  
+end

data/lib/messages/status.rb

@@ -0,0 +1,55 @@
+module Siffer
+  module Messages
+    
+    class Status
+      
+      attr_reader :code, :description, :data
+      
+      def initialize(code,data)
+        @code = code
+        @description = CODES[code]
+        @data = data
+      end
+      
+      def read
+        xml = Builder::XmlMarkup.new
+        xml.SIF_Status { |status|
+          status.SIF_Code(code)
+          status.SIF_Description(description)
+          if data.nil?
+            status.SIF_Data
+          else
+            status.SIF_Data{ |data_node| data_node << data.read }
+          end
+        }
+      end
+      alias :to_str :read
+      
+      def self.method_missing(sym,*args)
+        data = args.first
+        status = nil
+        CODES.each do |key, val|
+          if val.downcase.to_sym == sym
+            status =  Status.new(key,data)
+          end
+        end
+        if status
+          return status
+        else
+          super(sym,*args)
+        end
+      end
+      
+      CODES = {
+        0 => "Success",
+        1 => "Immediate",
+        2 => "Intermediate", 
+        3 => "Final",
+        7 => "Duplicate",
+        8 => "Sleeping", 
+        9 => "No Messages"
+      }
+    end
+    
+  end
+end

data/lib/messaging.rb

@@ -0,0 +1,96 @@
+module Siffer
+  # The Messaging module takes care of all of the Message handling for
+  # Siffer. It will check messages against content-type constraints as 
+  # well as validate the message XML against constraints outlined in the
+  # SIF Implementation Specification.
+  module Messaging
+
+    include Siffer::Messages
+
+    class BadContentType < Exception #:nodoc:
+    end
+    class MalformedXml < Exception #:nodoc:
+    end
+    class MalformedSIFMessage < Exception #:nodoc:
+    end
+    class XmlNsMismatch < Exception #:nodoc:
+    end
+    class VersionMismatch < Exception #:nodoc:
+    end
+    
+    # Checks the request against the messaging constraints:
+    # * check_content_type
+    # * validate_message
+    # Raises exceptions accordingly.
+    def request_failed_messaging?
+      begin
+        check_content_type
+        validate_message
+      rescue BadContentType
+        # Make a better Not Acceptable response
+         @response = Response.new(Siffer::Protocol::HTTP_STATUS_CODES[406],
+                      406,
+                      {"Content-Type" => MIME_TYPES["htm"]})
+      rescue MalformedXml; error_response(1,2);
+      rescue MalformedSIFMessage; error_response(12,2);
+      rescue VersionMismatch; error_response(12,3);
+      rescue XmlNsMismatch; error_response(1,4,"XMLNS not compatible with SIF")
+      end
+    end
+    
+    # Provides a context for the original message.
+    def using_message_from(request, &block)
+      yield if block_given?
+    end
+    
+    # Reads request content type and validates it's either text/xml
+    # or application/xml;charset=utf-8. If it isn't it will raise a
+    # BadContentType exception.
+    def check_content_type
+      content_type = @request.content_type
+      unless [MIME_TYPES["xml"], MIME_TYPES["appxml"]].include? content_type
+        raise BadContentType
+      end
+    end
+    
+    # Validates the Request Body against the constraints of SIF Messaging.
+    # The word "validate" is used loosely as there is no XML validation
+    # currently. 
+    #
+    # Currently validates:
+    # * <tt>well-formed XML</tt> - XML must be well formed.
+    # * <tt>message root</tt> - XML must be a SIF message.
+    # * <tt>version</tt> - Must match SIF version implemented. 
+    # * <tt>xmlns</tt> - Must match xmlns implemented.
+    #
+    # Does not validate:
+    # * valid XML
+    # * different versions of SIF
+    def validate_message
+      begin
+        body = (@request.body.respond_to? :read) ? @request.body.read : @request.body
+        xml = REXML::Document.new(body)
+        # validate Message Root
+        raise MalformedXml if xml.root.nil?
+        # validate Message Root is a SIF_Message
+        raise MalformedSIFMessage if xml.root.name != "SIF_Message"
+        # validate SIF version
+        raise VersionMismatch if xml.root.attributes["version"] != Siffer.sif_version
+        # validate SIF xmlns
+        raise XmlNsMismatch if xml.root.attributes["xmlns"] != Siffer.sif_xmlns
+         # any others?
+      rescue REXML::ParseException
+        raise MalformedXml
+      end
+    end
+  
+    # MIME Types used in Siffer
+    MIME_TYPES = {
+      "appxml" => "application/xml;charset=utf-8", 
+      "htm"   => "text/html",
+      "html"  => "text/html",
+      "xml"   => "text/xml"
+    }
+    
+  end
+end