diaspora_federation/lib/diaspora_federation/discovery/xrd_document.rb

# frozen_string_literal: true

module DiasporaFederation
  module Discovery
    # 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
    # {https://datatracker.ietf.org/doc/html/rfc6415#appendix-A RFC 6415, Appendix A}
    # for a description of the JSON format.
    #
    # @example 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
    #
    # @example Parsing a XrdDocument
    #   data = XrdDocument.xml_data(xml_string)
    #
    # @see http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html Extensible Resource Descriptor (XRD) Version 1.0
    class XrdDocument
      # xml namespace url
      XMLNS = "http://docs.oasis-open.org/ns/xri/xrd-1.0"

      # +Link+ element attributes
      LINK_ATTRS = %i[rel type href template].freeze

      # format string for datetime (+Expires+ element)
      DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%SZ"

      # The <Expires> element contains a time value which specifies the instant at
      # and after which the document has expired and SHOULD NOT be used.
      # @param [DateTime] value
      attr_writer :expires
      # The <Subject> element contains a URI value which identifies the resource
      # described by this XRD.
      # @param [String] value
      attr_writer :subject

      # @return [Array<String>] list of alias URIs
      attr_reader :aliases

      # @return [Hash<String => mixed>] list of properties. Hash key represents the
      #   +type+ attribute, and the value is the element content
      attr_reader :properties

      # @return [Array<Hash<attr => val>>] list of +Link+ element hashes. Each
      #   hash contains the attributesa and their associated values for the +Link+
      #   element.
      attr_reader :links

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

      # Generates an XML document from the current instance and returns it as string
      # @return [String] XML document
      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

      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

      # 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.
      #
      # @param [String] xrd_doc XML string
      # @return [Hash] extracted data
      # @raise [InvalidDocument] if the XRD is malformed
      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

      # Parse the JRD document from the given string and create a hash containing
      # the extracted data with symbolized keys.
      #
      # @param [String] jrd_doc JSON string
      # @return [Hash] extracted data
      # @raise [InvalidDocument] if the JRD is malformed
      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

      private

      attr_reader :expires, :subject

      NS = {xrd: XMLNS}.freeze

      def add_aliases_to(xml)
        aliases.each do |a|
          next if !a.instance_of?(String) || a.empty?

          xml.Alias(a.to_s)
        end
      end

      def add_properties_to(xml)
        properties.each do |type, val|
          xml.Property(val.to_s, type: type)
        end
      end

      def add_links_to(xml)
        links.each do |l|
          attrs = {}
          LINK_ATTRS.each do |attr|
            attrs[attr.to_s] = l[attr] if l.key?(attr)
          end
          xml.Link(attrs)
        end
      end

      private_class_method def self.parse_xrd_document(xrd_doc)
        raise ArgumentError unless xrd_doc.instance_of?(String)

        doc = Nokogiri::XML(xrd_doc)
        raise InvalidDocument, "Not an XRD document" if !doc.root || doc.root.name != "XRD"

        doc
      end

      private_class_method def self.parse_aliases_from_xml_doc(doc, data)
        aliases = []
        doc.xpath("xrd:XRD/xrd:Alias", NS).each do |node|
          aliases << node.content
        end
        data[:aliases] = aliases unless aliases.empty?
      end

      private_class_method def self.parse_properties_from_xml_doc(doc, data)
        properties = {}
        doc.xpath("xrd:XRD/xrd:Property", NS).each do |node|
          properties[node[:type]] = node.children.empty? ? nil : node.content
        end
        data[:properties] = properties unless properties.empty?
      end

      private_class_method def self.parse_links_from_xml_doc(doc, data)
        links = []
        doc.xpath("xrd:XRD/xrd:Link", NS).each do |node|
          link = {}
          LINK_ATTRS.each do |attr|
            link[attr] = node[attr.to_s] if node.key?(attr.to_s)
          end
          links << link
        end
        data[:links] = links unless links.empty?
      end

      # symbolize link keys from JSON hash, but only convert known keys
      private_class_method def self.symbolize_keys_for_links(links)
        links&.map do |link|
          {}.tap do |hash|
            LINK_ATTRS.each do |attr|
              hash[attr] = link[attr.to_s] if link.key?(attr.to_s)
            end
          end
        end
      end
    end
  end
end