Class: DiasporaFederation::Discovery::XrdDocument

Inherits:
Object
  • Object
show all
Defined in:
lib/diaspora_federation/discovery/xrd_document.rb

Overview

Note:

RFC 6415 recommends that servers should also offer the JRD format in addition to the XRD representation. Implementing XrdDocument#to_json and XrdDocument.json_data should be almost trivial due to the simplicity of the format and the way the data is stored internally already. See RFC 6415, Appendix A for a description of the JSON format.

This class implements basic handling of XRD documents as far as it is necessary in the context of the protocols used with diaspora* federation.

Examples:

Creating a XrdDocument

doc = XrdDocument.new
doc.expires = DateTime.new(2020, 1, 15, 0, 0, 1)
doc.subject = "http://example.tld/articles/11"
doc.aliases << "http://example.tld/cool_article"
doc.aliases << "http://example.tld/authors/2/articles/3"
doc.properties["http://x.example.tld/ns/version"] = "1.3"
doc.links << { rel: "author", type: "text/html", href: "http://example.tld/authors/2" }
doc.links << { rel: "copyright", template: "http://example.tld/copyright?id={uri}" }

doc.to_xml

Parsing a XrdDocument

data = XrdDocument.xml_data(xml_string)

See Also:

Constant Summary collapse

XMLNS =

xml namespace url

"http://docs.oasis-open.org/ns/xri/xrd-1.0".freeze
%i(rel type href template).freeze
DATETIME_FORMAT =

format string for datetime (Expires element)

"%Y-%m-%dT%H:%M:%SZ".freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ XrdDocument

Returns a new instance of XrdDocument.



61
62
63
64
65
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 61

def initialize
  @aliases = []
  @links = []
  @properties = {}
end

Instance Attribute Details

#aliases ⇒ Array<String> (readonly)

Returns list of alias URIs.

Returns:

  • (Array<String>) —

    list of alias URIs



50
51
52
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 50

def aliases
  @aliases
end

#expires=(value) ⇒ Object (writeonly)

The <Expires> element contains a time value which specifies the instant at and after which the document has expired and SHOULD NOT be used.

Parameters:

  • value (DateTime) 


43
44
45
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 43

def expires=(value)
  @expires = value
end

#links ⇒ Array<Hash<attr => val>> (readonly)

Returns list of Link element hashes. Each hash contains the attributesa and their associated values for the Link element.

Returns:

  • (Array<Hash<attr => val>>) —

    list of Link element hashes. Each hash contains the attributesa and their associated values for the Link element.



59
60
61
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 59

def links
  @links
end

#properties ⇒ Hash<String => mixed> (readonly)

Returns list of properties. Hash key represents the type attribute, and the value is the element content.

Returns:

  • (Hash<String => mixed>) —

    list of properties. Hash key represents the type attribute, and the value is the element content



54
55
56
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 54

def properties
  @properties
end

#subject=(value) ⇒ Object (writeonly)

The <Subject> element contains a URI value which identifies the resource described by this XRD.

Parameters:

  • value (String) 


47
48
49
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 47

def subject=(value)
  @subject = value
end

Class Method Details

.xml_data(xrd_doc) ⇒ Hash

Parse the XRD document from the given string and create a hash containing the extracted data.

Small bonus: the hash structure that comes out of this method is the same as the one used to produce a JRD (JSON Resource Descriptor) or parsing it.

Parameters:

  • xrd_doc (String) —

    XML string

Returns:

  • (Hash) —

    extracted data

Raises:



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 92

def self.xml_data(xrd_doc)
  doc = parse_xrd_document(xrd_doc)

  {}.tap do |data|
    exp_elem = doc.at_xpath("xrd:XRD/xrd:Expires", NS)
    data[:expires] = DateTime.strptime(exp_elem.content, DATETIME_FORMAT) unless exp_elem.nil?

    subj_elem = doc.at_xpath("xrd:XRD/xrd:Subject", NS)
    data[:subject] = subj_elem.content unless subj_elem.nil?

    parse_aliases_from_xml_doc(doc, data)
    parse_properties_from_xml_doc(doc, data)
    parse_links_from_xml_doc(doc, data)
  end
end

Instance Method Details

#to_xml ⇒ String

Generates an XML document from the current instance and returns it as string

Returns:

  • (String) —

    XML document



69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 69

def to_xml
  Nokogiri::XML::Builder.new(encoding: "UTF-8") {|xml|
    xml.XRD("xmlns" => XMLNS) {
      xml.Expires(@expires.strftime(DATETIME_FORMAT)) if @expires.instance_of?(DateTime)

      xml.Subject(@subject) if !@subject.nil? && !@subject.empty?

      add_aliases_to(xml)
      add_properties_to(xml)
      add_links_to(xml)
    }
  }.to_xml
end