xcapclient 1.0

data/lib/xcapclient/client.rb

@@ -0,0 +1,584 @@
+module XCAPClient
+	
+	
+	# The base class of the library. A program using this library must instantiate it.
+	#
+	# === Common notes for methods <tt>get*</tt>, <tt>put*</tt> and <tt>delete*</tt>
+	# 
+	# ==== Shared parameters
+	#
+	# *_auid_*: String, the auid of the application. Example:"pres-rules".
+	#
+	# *_document_*: nil by default. It can be:
+	#   * String, so the application must contain a document called as it.
+	#   * XCAPClient::Document object.
+	#   * nil, so the application default document is selected.
+	#
+	# *_check_etag_*: true by default. If true the client adds the header "If-None-Match" or "If-Match" to the HTTP request containing the last ETag received.
+	#
+	# *_selector_*: Document/node selector. The path that identifies the XML document or node within the XCAP root URL. It's automatically converted to ASCII and percent encoded if needed. Example:
+	#
+	#   '/cp:ruleset/cp:rule/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]'
+	#
+	# *_xml_namespaces_*: nil by default. It's a hash containing the prefixes and namespaces used in the query. Example:
+	#
+	#   {"pr"=>"urn:ietf:params:xml:ns:pres-rules", "cp"=>"urn:ietf:params:xml:ns:common-policy"}
+	#
+	# ==== Exceptions
+	#
+	# If these methods receive a non HTTP 2XX response they generate an exception. Check ERRORS.rdoc for detailed info.
+	#
+	# ==== Access to the full response
+	#
+	# In any case, the HTTP response is stored in the document _last_response_ attribute as an HTTP::Message[http://dev.ctor.org/doc/httpclient/] object. To get it:
+	#
+	#   @xcapclient.application("pres-rules").document.last_response
+	#
+	class Client
+		
+		
+		USER_AGENT = "Ruby-XCAPClient"
+		COMMON_HEADERS = {
+			"User-Agent" => "#{USER_AGENT}/#{VERSION}",
+			"Connection" => "close"
+		}
+		GLOBAL_XUI = "global"
+		XCAP_CAPS_XMLNS = "urn:ietf:params:xml:ns:xcap-caps"
+		HTTP_TIMEOUT = 6
+		CONF_PARAMETERS = [:xcap_root, :user, :auth_user, :password, :ssl_verify_cert]
+		
+		
+		attr_reader :xcap_root, :user, :auth_user, :password, :ssl_verify_cert
+		
+		
+		# Create a new XCAP client. It requires two parameters:
+		#
+		# * _conf_: A hash containing settings related to the server:
+		#   * _xcap_root_: The URL where the documents hold.
+		#   * _user_: The client username. Depending on the server it could look like "sip:alice@domain.org", "alice@domain.org" or "alice".
+		#   * _auth_user_: Username for authentication (if required).
+		#   * _ssl_verify_cert_: If true and the server uses SSL, the certificate is inspected (expiration time, signature...).
+		#
+		# * _applications_: A hash of hashes containing each XCAP application available for the client. Each application is an entry of the hash containing a key whose value is the "auid" of the application and whose value is a hast with the following fields:
+		#   * _xmlns_: The XML namespace uri of the application.
+		#   * _document_name_: The name of the default document for this application ("index" if not set).
+		#   * _scope_: Can be :user or :global (:user if not set).
+		#     * _:user_: Each user has his own document(s) for this application.
+		#     * _:global_: The document(s) is shared for all the users.
+		#
+		# Example:
+		#   xcap_conf = {
+		#     :xcap_root => "https://xcap.domain.org/xcap-root",
+		#     :user => "sip:alice@domain.org",
+		#     :auth_user => "alice",
+		#     :password => "1234",
+		#     :ssl_verify_cert => false
+		#   }
+		#   xcap_apps = {
+		#     "pres-rules" => {
+		#       :xmlns => "urn:ietf:params:xml:ns:pres-rules",
+		#       :mime_type => "application/auth-policy+xml",
+		#       :document_name => "index",
+		#       :scope => :user
+		#     },
+		#     "rls-services" => {
+		#       :xmlns => "urn:ietf:params:xml:ns:rls-services",
+		#       :mime_type => "application/rls-services+xml",
+		#       :document_name => "index",
+		#       :scope => :user
+		#     }
+		#   }
+		#
+		#   @client = Client.new(xcap_conf, xcap_apps)
+		#
+		# A XCAP application called "xcap-caps" is automatically added to the list of applications of the new client. This application is defined in the {RFC 4825}[http://tools.ietf.org/html/rfc4825].
+		#
+		def initialize(conf={}, applications={})
+			
+			# Check conf hash.
+			raise ConfigError, "`conf' must be a hash" unless (Hash === conf)
+			
+			# Check non existing parameter names.
+			conf.each_key do |key|
+				raise ConfigError, "Uknown parameter name '#{key}' in `conf' hash" unless CONF_PARAMETERS.include?(key)
+			end
+			
+			# Check xcap_root parameter.
+			@xcap_root = URI.parse(conf[:xcap_root].to_s)
+			raise ConfigError, "`xcap_root' must be http or https URI" unless [URI::HTTP, URI::HTTPS].include?(@xcap_root.class)
+			
+			# Check user.
+			@user = conf[:user].freeze
+			raise ConfigError, "`user' must be a non empty string" unless (String === @user && ! @user.empty?)
+			
+			@auth_user = conf[:auth_user].freeze || @user
+			@password = conf[:password].freeze
+			
+			# Initialize the HTTP client.
+			@http_client = HTTPClient.new
+			@http_client.set_auth(@xcap_root, @auth_user, @password)
+			@http_client.protocol_retry_count = 3  ### TODO: Set an appropiate value (min 2 for 401).
+			@http_client.connect_timeout = HTTP_TIMEOUT
+			@http_client.send_timeout = HTTP_TIMEOUT
+			@http_client.receive_timeout = HTTP_TIMEOUT
+			
+			@xcap_root.freeze  # Freeze now as it has been modified in @http_client.set_auth.
+			
+			# Check ssl_verify_cert parameter.
+			if URI::HTTPS === @xcap_root
+				@ssl_verify_cert = conf[:ssl_verify_cert] || false
+				raise ConfigError, "`ssl_verify_cert' must be true or false" unless [TrueClass, FalseClass].include?(@ssl_verify_cert.class)
+				@http_client.ssl_config.verify_mode = ( @ssl_verify_cert ? 3 : 0 )
+			end
+			
+			# Generate applications.
+			@applications = {}
+			
+			# Add the "xcap-caps" application.
+			@applications["xcap-caps"] = Application.new("xcap-caps", {
+				:xmlns => "urn:ietf:params:xml:ns:xcap-caps",
+				:mime_type => "application/xcap-caps+xml",
+				:scope => :global,
+				:document_name => "index"
+			})
+			
+			# Add custom applications.
+			applications.each do |auid, data|
+				@applications[auid] = Application.new(auid, data)
+			end
+			
+			@applications.freeze
+			
+		end  # def initialize
+		
+		
+		# Returns the XCAPClient::Application whose auid mathes the _auid_ parameter.
+		#
+		# Example:
+		#
+		#   @xcapclient.application("pres-rules")
+		#
+		def application(auid)
+			@applications[auid]
+		end
+		
+		
+		# Returns an Array with all the applications configured in the client.
+		def applications
+			@applications
+		end
+		
+		
+		# Fetch a document from the server.
+		#
+		# Example:
+		#
+		#   @xcapclient.get("pres-rules")
+		#
+		# If success:
+		# * The method returns true.
+		# * Received XML plain document is stored in <tt>@xcapclient.application("pres-rules").document.plain</tt> (the default document).
+		# * Received ETag is stored in <tt>@xcapclient.application("pres-rules").document.etag</tt>.
+		#
+		def get(auid, document=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:get, application, document, nil, nil, nil, nil, check_etag)
+			
+			# Check Content-Type.
+			check_content_type(response, application.mime_type)
+			
+			# Store the plain document.
+			document.plain = response.body.content
+			
+			# Update ETag.
+			document.etag = response.header["ETag"].first
+			
+			return true
+			
+		end
+		
+		
+		# Create/replace a document in the server.
+		#
+		# Example:
+		#
+		#   @xcapclient.put("pres-rules")
+		#
+		# If success:
+		# * The method returns true.
+		# * Local plain document in <tt>@xcapclient.application("pres-rules").document.plain</tt> is uploaded to the server.
+		# * Received ETag is stored in <tt>@xcapclient.application("pres-rules").document.etag</tt>.
+		#
+		def put(auid, document=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:put, application, document, nil, nil, nil, application.mime_type, check_etag)
+			
+			# Update ETag.
+			document.etag = response.header["ETag"].first
+			
+			return true
+			
+		end
+		
+		
+		# Delete a document in the server.
+		#
+		# Example:
+		#
+		#   @xcapclient.delete("pres-rules")
+		#
+		# If success:
+		# * The method returns true.
+		# * Local plain document and ETag are deleted.
+		#
+		def delete(auid, document=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:delete, application, document, nil, nil, nil, nil, check_etag)
+			
+			# Reset the local document.
+			document.plain = nil
+			document.etag = nil
+			
+			return true
+			
+		end
+		
+		
+		# Fetch an element from the document stored in the server.
+		#
+		# Example:
+		#
+		#   @xcapclient.get_element("pres-rules", nil,
+		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
+		#
+		# If success:
+		# * The method returns the response body as a String.
+		#
+		def get_element(auid, document, selector, xml_namespaces=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:get, application, document, selector, nil, xml_namespaces, nil, check_etag)
+			
+			# Check Content-Type.
+			check_content_type(response, "application/xcap-el+xml")
+			
+			return response.body.content
+			
+		end
+		
+		# Create/replace an element in the document stored in the server.
+		#
+		# Example:
+		#
+		#   @xcapclient.put_element("pres-rules", nil,
+		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:bob@example.org"]',
+		#     '<cp:one id="sip:bob@example.org"/>',
+		#     {"cp"=>"urn:ietf:params:xml:ns:common-policy"})
+		#
+		# If success:
+		# * The method returns true.
+		# * Local plain document and ETag are deleted (as the document has changed).
+		#
+		def put_element(auid, document, selector, selector_body, xml_namespaces=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:put, application, document, selector, selector_body, xml_namespaces, "application/xcap-el+xml", check_etag)
+			
+			# Reset local plain document and ETag as we have modified it.
+			document.plain = nil
+			document.etag = nil
+			
+			return true
+			
+		end
+		
+		
+		# Delete an element in the document stored in the server.
+		#
+		# Example:
+		#
+		#   @xcapclient.delete_element("pres-rules", nil,
+		#     '/cp:ruleset/cp:rule[@id="pres_whitelist"]/cp:conditions/cp:identity/cp:one[@id="sip:alice@example.org"]',
+		#     {"cp" => "urn:ietf:params:xml:ns:common-policy"})
+		#
+		# If success:
+		# * The method returns true.
+		# * Local plain document and ETag are deleted (as the document has changed).
+		#
+		def delete_element(auid, document, selector, xml_namespaces=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:delete, application, document, selector, nil, xml_namespaces, nil, check_etag)
+			
+			# Reset local plain document and ETag as we have modified it
+			document.plain = nil
+			document.etag = nil
+			
+			return true
+			
+		end
+		
+		
+		# Fetch the namespace prefixes of an element.
+		#
+		# If the client wants to create/replace an element, the body of the PUT request must use the same namespaces and prefixes as those used in the document stored in the server. This methods allows the client to fetch these namespaces and prefixes.
+		#
+		# Related documentation: {RFC 4825 section 7.10}[http://tools.ietf.org/html/rfc4825#section-7.10], {RFC 4825 section 10}[http://tools.ietf.org/html/rfc4825#section-10]
+		#
+		# Example:
+		#
+		#   @xcapclient.get_element_namespaces("pres-rules", nil,
+		#     '/ccpp:ruleset/ccpp:rule[@id="pres_whitelist"]',
+		#     { "ccpp" => "urn:ietf:params:xml:ns:common-policy" })
+		#
+		# Assuming the server uses "cp" for that namespace, it would reply:
+		#
+		#   HTTP/1.1 200 OK
+		#   Content-Type: application/xcap-ns+xml
+		#
+		#   <cp:identity xmlns:pr="urn:ietf:params:xml:ns:pres-rules"
+		#     xmlns:cp="urn:ietf:params:xml:ns:common-policy" />
+		#
+		# If Nokogiri[http://wiki.github.com/tenderlove/nokogiri] is available the method returns a hash:
+		#   {"pr"=>"urn:ietf:params:xml:ns:pres-rules", "cp"=>"urn:ietf:params:xml:ns:common-policy"}
+		# If not, the method returns the response body as a String and the application must parse it.
+		#
+		def get_element_namespaces(auid, document, selector, xml_namespaces=nil, check_etag=true)
+			
+			application, document = get_app_doc(auid, document)
+			response = send_request(:get, application, document, selector + "/namespace::*", nil, xml_namespaces, nil, check_etag)
+			
+			# Check Content-Type.
+			check_content_type(response, "application/xcap-ns+xml")
+			
+			return case NOKOGIRI_INSTALLED
+				when true
+					Nokogiri::XML.parse(response.body.content).namespaces
+				when false
+					response.body.content
+				end
+			
+		end
+		
+		
+		# Fetch the XCAP applications (auids) supported by the server.
+		#
+		# Related documentation: {RFC 4825 section 12}[http://tools.ietf.org/html/rfc4825#section-12]
+		#
+		# If Nokogiri[http://wiki.github.com/tenderlove/nokogiri] is available the method returns an Array containing the auids. If not, the response body is returned as a String.
+		#
+		def get_xcap_auids
+		
+			body = get_element("xcap-caps", nil, '/xcap-caps/auids')
+			
+			return case NOKOGIRI_INSTALLED
+				when true
+					parse(body).xpath("/auids/auid", {"xmlns" => XCAP_CAPS_XMLNS}).map {|auid| auid.content}
+				when false
+					body
+				end
+		
+		end
+		
+		
+		# Fetch the XCAP extensions supported by the server.
+		#
+		# Same as XCAPClient::Client::get_xcap_auids but fetching the supported extensions.
+		#
+		def get_xcap_extensions
+		
+			body = get_element("xcap-caps", nil, '/xcap-caps/extensions')
+			
+			return case NOKOGIRI_INSTALLED
+				when true
+					parse(body).xpath("/extensions/extension", {"xmlns" => XCAP_CAPS_XMLNS}).map {|extension| extension.content}
+				when false
+					body
+				end
+		
+		end
+		
+		
+		# Fetch the XCAP namespaces supported by the server.
+		#
+		# Same as XCAPClient::Client::get_xcap_auids but fetching the supported namespaces.
+		#
+		def get_xcap_namespaces
+		
+			body = get_element("xcap-caps", nil, '/xcap-caps/namespaces')
+			
+			return case NOKOGIRI_INSTALLED
+				when true
+					parse(body).xpath("/namespaces/namespace", {"xmlns" => XCAP_CAPS_XMLNS}).map {|namespace| namespace.content}
+				when false
+					body
+				end
+		
+		end
+		
+		
+		private
+		
+		
+		def get_app_doc(auid, document=nil)
+			
+			# Get the application.
+			application = @applications[auid]
+			raise WrongAUID, "There is no application with auid '#{auid}'" unless application
+			
+			# Get the document.
+			case document
+			when Document
+			when String
+				document_name = document
+				document = application.document(document_name)
+				raise DocumentError, "document '#{document_name}' doesn't exist in application '#{auid}'" unless document
+			when NilClass
+				document = application.document  # Default document.
+			else
+				raise ArgumentError, "`document' must be Document, String or nil"
+			end
+			
+			return [application, document]
+			
+		end
+		
+		
+		# Converts the hash namespaces hash into a HTTP query.
+		#
+		#   get_xmlns_query( { "a"=>"urn:test:default-namespace", "b"=>"urn:test:namespace1-uri" } )
+		#   => "?xmlns(a=urn:test:default-namespace)xmlns(b=urn:test:namespace1-uri)"
+		#
+		def get_xmlns_query(xml_namespaces)
+			
+			return "" unless xml_namespaces
+			
+			xmlns_query="?"
+			xml_namespaces.each do |prefix, uri|
+				xmlns_query += "xmlns(#{prefix}=#{uri})"
+			end
+			
+			return xmlns_query
+			
+		end
+		
+		
+		def send_request(method, application, document, selector, selector_body, xml_namespaces, content_type, check_etag)
+			
+			# Set extra headers.
+			extra_headers = {}.merge(COMMON_HEADERS)
+			if check_etag && document.etag
+				case method
+				when :get
+					extra_headers["If-None-Match"] = document.etag
+				when :put
+					extra_headers["If-Match"] = document.etag
+				when :delete
+					extra_headers["If-Match"] = document.etag
+				end
+			end
+			extra_headers["Content-Type"] = content_type if content_type
+			
+			# XUI.
+			xui = case application.scope
+			when :user
+				"users/#{user_encode(@user)}"
+			when :global
+				GLOBAL_XUI
+			end
+			
+			# URI.
+			uri = "#{@xcap_root}/#{application.auid}/#{xui}/#{document.name}"
+			uri += "/~~#{percent_encode(selector)}" if selector
+			uri +=  get_xmlns_query(xml_namespaces) if xml_namespaces
+			
+			# Body (just in case of PUT).
+			body = ( selector_body || document.plain || nil ) if method == :put
+			raise ArgumentError, "PUT body empty" unless String === body if method == :put
+			
+			begin
+				response = @http_client.request(method, uri, nil, body, extra_headers)
+			rescue => e
+				raise ConnectionError, "Error contacting the server <#{e.class}: #{e.message}>"
+			end
+			
+			document.last_response = response
+			
+			# Process the response.
+			case response.status.to_s
+			
+			when /^2[0-9]{2}$/
+				return response
+				
+			when "304"
+				raise HTTPDocumentNotModified
+				
+			when "400"
+				raise HTTPBadRequest
+				
+			when "404"
+				raise HTTPDocumentNotFound
+				
+			when /^(401|407)$/
+				raise HTTPAuthenticationError, "Couldn't authenticate for URI '#{uri}' [#{response.status} #{response.reason}]"
+			
+			when "409"
+				raise HTTPConflictError
+			
+			when "412"
+				raise HTTPNoMatchingETag
+			
+			when "500"
+				raise HTTPServerError
+				
+			else
+				raise HTTPUnknownError, "Unknown error for URI '#{uri}' [#{response.status} #{response.reason}]"
+				
+			end
+			
+		end  # def send_request
+		
+		
+		def percent_encode(str)
+			return case RUBY_VERSION_CORE
+			when :RUBY_1_9
+				str.dup.force_encoding('ASCII-8BIT').gsub(/[^a-zA-Z0-9\.,:;\-_?!@$&=+*\/~'()]/) { '%%%02x' % $&.ord }
+			when :RUBY_1_8
+				str.gsub(/[^a-zA-Z0-9\.,:;\-_?!@$&=+*\/~'()]/n) {|s| sprintf('%%%02x', s[0]) }
+			end
+		end
+		
+		
+		def user_encode(str)
+			return case RUBY_VERSION_CORE
+			when :RUBY_1_9
+				str.gsub(/[?\/]/) { '%%%02x' % $&.ord }
+			when :RUBY_1_8
+				str.gsub(/[?\/]/) {|s| sprintf('%%%02x', s[0]) }
+			end
+		end
+		
+		
+		def check_content_type(response, valid_content_type)
+			content_type = response.header["Content-Type"].first
+			raise HTTPWrongContentType, "Wrong Content-Type ('#{content_type})" unless content_type =~ /^#{Regexp.escape(valid_content_type)};?/i
+		end
+		
+		
+		def parse(str)
+			begin
+				Nokogiri::XML.parse(str, nil, nil, PARSE_OPTIONS)
+			rescue Nokogiri::SyntaxError => e
+				raise XMLParsingError, "Couldn't parse the XML file <#{e.class}: #{e.message}>"
+			end
+		end
+		
+		
+	end  # class Client
+	
+	
+end

data/lib/xcapclient/document.rb

@@ -0,0 +1,40 @@
+module XCAPClient
+	
+	class Document
+		
+		# The name of the document as it exists in the server.
+		attr_reader :name
+		
+		# Contains the plain document fetched from the server or manually set.
+		attr_accessor :plain
+		
+		# The last received ETag value in a response from the server. It can be set manually.
+		attr_accessor :etag
+		
+		# This attribute could contain the parsed instance of the XML document. It's not required by XCAPClient itself, but could be useful for the program in top of it.
+		attr_accessor :parsed
+		
+		# The last response received from the server. It's a HTTP::Message[http://dev.ctor.org/doc/httpclient/] object.
+		attr_accessor :last_response
+		
+		# Create a new instance. _name_, _plain_ and _etag_ are String.
+		def initialize(name, plain=nil, etag=nil, parsed=nil)
+			@name = name
+			@plain = plain
+			@parsed = parsed
+			@etag = etag
+			
+			# Check name.
+			raise ConfigError, "Document `name' must be a non empty string" unless String === @name && ! @name.empty?
+		end
+		
+		# Delete the local plain and parsed document and the ETag.
+		def reset
+			@plain = nil
+			@parsed = nil
+			@etag = nil
+		end
+		
+	end
+	
+end

data/lib/xcapclient/errors.rb

@@ -0,0 +1,21 @@
+module XCAPClient
+	
+	class XCAPClientError < StandardError ; end
+		class ConfigError < XCAPClientError ; end
+		class ArgumentError < XCAPClientError ; end
+		class ConnectionError < XCAPClientError ; end
+		class WrongAUID < XCAPClientError ; end
+		class DocumentError < XCAPClientError ; end
+		class HTTPError < XCAPClientError ; end
+			class HTTPAuthenticationError < HTTPError ; end
+			class HTTPNoMatchingETag < HTTPError ; end
+			class HTTPConflictError < HTTPError ; end
+			class HTTPDocumentNotModified < HTTPError ; end
+			class HTTPDocumentNotFound < HTTPError ; end
+			class HTTPWrongContentType < HTTPError ; end
+			class HTTPBadRequest < HTTPError ; end
+			class HTTPServerError < HTTPError ; end
+			class HTTPUnknownError < HTTPError ; end
+		class XMLParsingError < XCAPClientError ; end
+	
+end

data/lib/xcapclient.rb

@@ -0,0 +1,30 @@
+module XCAPClient
+	
+	VERSION = "1.0"
+	
+	RUBY_VERSION_CORE = case RUBY_VERSION
+		when /^1\.9\./
+			:RUBY_1_9
+		when /^1\.8\./
+			:RUBY_1_8
+		end
+	
+end
+
+
+require "httpclient"
+begin
+	require "nokogiri"
+	XCAPClient::NOKOGIRI_INSTALLED = true
+	XCAPClient::PARSE_OPTIONS = Nokogiri::XML::ParseOptions::NONET + Nokogiri::XML::ParseOptions::NOERROR
+rescue LoadError
+	STDERR.puts "WARNING: Nokogiri XML parser is not installed. Some non vital features are disabled."
+	XCAPClient::NOKOGIRI_INSTALLED = false
+end
+
+
+xcapclient_root = File.join(File.dirname(__FILE__), 'xcapclient')
+require File.join(xcapclient_root, "client")
+require File.join(xcapclient_root, "errors")
+require File.join(xcapclient_root, "application")
+require File.join(xcapclient_root, "document")