Class: DiasporaFederation::Discovery::XrdDocument

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

Overview

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

It also implements handling of the JRD format, see RFC 6415, Appendix A for a description of the JSON format.

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"
%i[rel type href template].freeze
DATETIME_FORMAT =

format string for datetime (Expires element)

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ XrdDocument

Returns a new instance of XrdDocument.



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

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



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

def aliases
  @aliases
end

#expires=(value) ⇒ Object

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) 


41
42
43
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 41

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.



57
58
59
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 57

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



52
53
54
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 52

def properties
  @properties
end

#subject=(value) ⇒ Object

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

Parameters:

  • value (String) 


45
46
47
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 45

def subject=(value)
  @subject = value
end

Class Method Details

.json_data(jrd_doc) ⇒ Hash

Parse the JRD document from the given string and create a hash containing the extracted data with symbolized keys.

Parameters:

  • jrd_doc (String) —

    JSON string

Returns:

  • (Hash) —

    extracted data

Raises:



122
123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 122

def self.json_data(jrd_doc)
  json_hash = JSON.parse(jrd_doc)

  {
    subject:    json_hash["subject"],
    expires:    (DateTime.strptime(json_hash["expires"], DATETIME_FORMAT) if json_hash.key?("expires")),
    aliases:    json_hash["aliases"],
    properties: json_hash["properties"],
    links:      symbolize_keys_for_links(json_hash["links"])
  }.compact
rescue JSON::JSONError => e
  raise InvalidDocument,
        "Not a JRD document: #{e.class}: #{e.message[0..255].encode(Encoding.default_external, undef: :replace)}"
end

.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:



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 100

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_json(*_args) ⇒ Object 



81
82
83
84
85
86
87
88
89
 
# File 'lib/diaspora_federation/discovery/xrd_document.rb', line 81

def to_json(*_args)
  {
    subject:    subject,
    expires:    (expires.strftime(DATETIME_FORMAT) if expires.instance_of?(DateTime)),
    aliases:    (aliases if aliases.any?),
    properties: (properties if properties.any?),
    links:      (links if links.any?)
  }.compact
end

#to_xml ⇒ String

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

Returns:

  • (String) —

    XML document



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

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