simple-rss 2.2.0 → 2.3.0

data/lib/simple-rss/json_entry_normalizer.rb

@@ -0,0 +1,147 @@
+# rbs_inline: enabled
+
+require "uri"
+require "date"
+
+class SimpleRSS::JsonEntryNormalizer
+  RFC3339_TIMESTAMP = /\A\d{4}-\d{2}-\d{2}[tT]
+                      (?:[01]\d|2[0-3]):[0-5]\d:(?:[0-5]\d|60)(?:\.\d+)?
+                      (?:[zZ]|[+-](?:[01]\d|2[0-3]):[0-5]\d)\z/x
+  FIELDS = {
+    title: "title", content_html: "content_html", content_text: "content_text", summary: "summary"
+  }.freeze
+  URL_FIELDS = %i[url external_url image banner_image].freeze
+
+  # @rbs @item: Hash[String, untyped]
+  # @rbs @feed: Hash[String, untyped]
+  # @rbs @source_url: String?
+  # @rbs @values: Hash[Symbol, untyped]
+  # @rbs @issues: Array[Hash[Symbol, untyped]]
+  # @rbs @sources: Hash[Symbol, untyped]
+
+  # @rbs (Hash[String, untyped], Hash[String, untyped], ?source_url: String?) -> void
+  def initialize(item, feed, source_url: nil)
+    @item = item
+    @feed = feed
+    @source_url = source_url || feed["feed_url"]
+    @issues = [] #: Array[Hash[Symbol, untyped]]
+    @sources = {} #: Hash[Symbol, untyped]
+    @values = { raw: item, issues: @issues, field_sources: @sources } #: Hash[Symbol, untyped]
+  end
+
+  # @rbs () -> SimpleRSS::NormalizedEntry
+  def entry
+    assign(:identifier, @item["id"].to_s, "id")
+    FIELDS.each { |field, source| assign(field, @item[source], source) }
+    URL_FIELDS.each { |field| assign(field, resolve_url(@item[field.to_s], field, field.to_s), field.to_s) }
+    assign(:published_at, read_date("date_published", :published_at), "date_published")
+    assign(:updated_at, read_date("date_modified", :updated_at), "date_modified")
+    @values[:summary_type] = :text if @item["summary"]
+    @values[:content_base_url] = @values[:url] || @source_url
+    read_language
+    read_categories
+    read_authors
+    @values[:attachments] = (@item["attachments"] || []).each_with_index.map { |attachment, index| read_attachment(attachment, index) }
+    @values[:links] = %i[url external_url].filter_map do |field|
+      next unless @values[field]
+
+      { url: @values[field], rel: field == :url ? "alternate" : "related", media_type: nil, source: field.to_s, raw: @item[field.to_s] }
+    end
+    SimpleRSS::NormalizedEntry.new(@values)
+  end
+
+  private
+
+  # @rbs (Symbol, untyped, String) -> void
+  def assign(field, value, source)
+    return if value.nil?
+
+    @values[field] = value
+    @sources[field] = source
+  end
+
+  # @rbs (Symbol, Symbol, untyped, String) -> void
+  def issue(field, code, value, source)
+    @issues << { field: field, code: code, value: value, source: source }
+  end
+
+  # @rbs (String, Symbol) -> Time?
+  def read_date(source, field)
+    value = @item[source]
+    return if value.nil?
+    return DateTime.rfc3339(value, Date::GREGORIAN).to_time if value.is_a?(String) && value.match?(RFC3339_TIMESTAMP)
+
+    issue(field, :invalid_date, value, source)
+    nil
+  rescue ArgumentError, RangeError
+    issue(field, :invalid_date, value, source)
+    nil
+  end
+
+  # @rbs (String?, Symbol, String) -> String?
+  def resolve_url(value, field, source)
+    return if value.nil? || value.strip.empty?
+
+    value = value.strip
+    return value if URI.parse(value).absolute?
+
+    source_url = @source_url
+    return URI.join(source_url, value).to_s if source_url && URI.parse(source_url).absolute?
+
+    issue(field, :relative_url_without_base, value, source)
+    value
+  rescue URI::Error
+    issue(field, :invalid_url, value, source)
+    value
+  end
+
+  # @rbs () -> void
+  def read_language
+    return unless @feed["version"] == SimpleRSS::JsonFeed::VERSIONS.last
+
+    object = @item.key?("language") ? @item : @feed
+    source = object.equal?(@item) ? "language" : "feed.language"
+    assign(:language, object["language"], source)
+  end
+
+  # @rbs () -> void
+  def read_categories
+    tags = @item["tags"] || []
+    categories = tags.map(&:strip).reject(&:empty?).uniq
+    assign(:categories, categories, "tags") if @item.key?("tags")
+    @values[:category_details] = tags.reject { |tag| tag.strip.empty? }.map { |tag| { term: tag.strip, label: nil, scheme: nil, source: "tags", raw: tag } }
+  end
+
+  # @rbs () -> void
+  def read_authors
+    object = @item
+    plural = @feed["version"] == SimpleRSS::JsonFeed::VERSIONS.last
+    object = @feed unless (plural && object.key?("authors")) || object.key?("author")
+    source = plural && object.key?("authors") ? "authors" : "author"
+    authors = source == "authors" ? object[source] : [object[source]].compact
+    source = "feed.#{source}" if object.equal?(@feed)
+    records = (authors || []).map do |author|
+      { name: author["name"], email: nil, url: resolve_url(author["url"], :authors, source),
+        avatar: resolve_url(author["avatar"], :authors, source), raw: author }
+    end
+    assign(:authors, records, source) unless records.empty?
+  end
+
+  # @rbs (Hash[String, untyped], Integer) -> Hash[Symbol, untyped]
+  def read_attachment(attachment, index)
+    source = "attachments[#{index}]"
+    { url: resolve_url(attachment["url"], :attachments, "#{source}.url"), media_type: attachment["mime_type"],
+      title: attachment["title"], size_in_bytes: read_number(attachment, "size_in_bytes", source),
+      duration_in_seconds: read_number(attachment, "duration_in_seconds", source), source: source, raw: attachment }
+  end
+
+  # @rbs (Hash[String, untyped], String, String) -> Numeric?
+  def read_number(attachment, field, source)
+    value = attachment[field]
+    return if value.nil?
+    return value if value.is_a?(Numeric) && value >= 0 && value.finite?
+
+    issue(:attachments, :invalid_number, value, "#{source}.#{field}")
+    nil
+  end
+end

data/lib/simple-rss/json_feed.rb

@@ -0,0 +1,176 @@
+# rbs_inline: enabled
+
+require "json"
+
+class SimpleRSS::JsonFeed
+  VERSIONS = %w[https://jsonfeed.org/version/1 https://jsonfeed.org/version/1.1].freeze
+  FEED_FIELDS = %w[title description home_page_url feed_url icon favicon language author authors expired next_url hubs user_comment].freeze
+  FEED_STRINGS = %w[description home_page_url feed_url icon favicon next_url user_comment].freeze
+  ITEM_STRINGS = %w[url external_url title summary content_html content_text image banner_image].freeze
+
+  attr_reader :document #: Hash[String, untyped]
+  attr_reader :items #: Array[Hash[Symbol, untyped]]
+
+  # @rbs @originals: Hash[Hash[Symbol, untyped], Hash[String, untyped]]
+
+  # @rbs (String) -> void
+  def initialize(source)
+    source = source.b.sub(/\A\xEF\xBB\xBF/n, "").force_encoding(Encoding::UTF_8)
+    raise SimpleRSSError, "Malformed JSON Feed: invalid UTF-8" unless source.valid_encoding?
+
+    @document = JSON.parse(source)
+    validate
+    freeze_data(@document)
+    @originals = {} #: Hash[Hash[Symbol, untyped], Hash[String, untyped]]
+    @originals.compare_by_identity
+    @items = @document.fetch("items").map do |original|
+      item = legacy_item(original)
+      @originals[item] = original
+      item
+    end
+  rescue JSON::ParserError, EncodingError => e
+    raise SimpleRSSError, "Malformed JSON Feed: #{e.message}"
+  end
+
+  # @rbs (Hash[Symbol, untyped], ?source_url: String?) -> SimpleRSS::NormalizedEntry
+  def normalized_entry(item, source_url: nil)
+    original = @originals[item] || raise(SimpleRSSError, "Cannot normalize an item without its original JSON source")
+    SimpleRSS::JsonEntryNormalizer.new(original, document, source_url: source_url).entry
+  end
+
+  private
+
+  # @rbs () -> void
+  def validate
+    check_type(document, Hash, "feed")
+    validate_numbers(document)
+    required_string(document, "version", "feed")
+    raise SimpleRSSError, "Unsupported JSON Feed version: #{document["version"].inspect}" unless VERSIONS.include?(document["version"])
+
+    required_string(document, "title", "feed")
+    check_type(document["items"], Array, "items")
+    optional_strings(document, FEED_STRINGS, "feed")
+    optional_strings(document, ["language"], "feed") if version_1_1?
+    validate_expiration
+    validate_authors(document, "feed")
+    optional_array(document, "hubs", "feed").each_with_index do |hub, index|
+      check_type(hub, Hash, "hubs[#{index}]")
+      %w[type url].each { |field| required_string(hub, field, "hubs[#{index}]") }
+    end
+    document["items"].each_with_index { |item, index| validate_item(item, "items[#{index}]") }
+  end
+
+  # @rbs (untyped) -> void
+  def validate_numbers(value)
+    case value
+    when Hash then value.each_value { |child| validate_numbers(child) }
+    when Array then value.each { |child| validate_numbers(child) }
+    when Float
+      raise SimpleRSSError, "JSON Feed number exceeds the supported range" unless value.finite?
+    end
+  end
+
+  # @rbs () -> void
+  def validate_expiration
+    return unless document.key?("expired")
+    return if [true, false].include?(document["expired"])
+
+    raise SimpleRSSError, "JSON Feed feed.expired must be a boolean"
+  end
+
+  # @rbs (untyped, String) -> void
+  def validate_item(item, path)
+    check_type(item, Hash, path)
+    identifier = item["id"]
+    unless (identifier.is_a?(String) || identifier.is_a?(Numeric)) && !identifier.to_s.strip.empty?
+      raise SimpleRSSError, "JSON Feed #{path}.id must be a nonblank string or number"
+    end
+    unless %w[content_html content_text].any? { |field| item[field].is_a?(String) }
+      raise SimpleRSSError, "JSON Feed #{path} requires content_html or content_text"
+    end
+
+    optional_strings(item, ITEM_STRINGS, path)
+    optional_strings(item, ["language"], path) if version_1_1?
+    validate_authors(item, path)
+    optional_array(item, "tags", path).each { |tag| check_type(tag, String, "#{path}.tags[]") }
+    optional_array(item, "attachments", path).each_with_index do |attachment, index|
+      attachment_path = "#{path}.attachments[#{index}]"
+      check_type(attachment, Hash, attachment_path)
+      %w[url mime_type].each { |field| required_string(attachment, field, attachment_path) }
+      optional_strings(attachment, ["title"], attachment_path)
+    end
+  end
+
+  # @rbs (Hash[String, untyped], String) -> void
+  def validate_authors(object, path)
+    if version_1_1? && object.key?("authors")
+      optional_array(object, "authors", path).each_with_index { |author, index| validate_author(author, "#{path}.authors[#{index}]") }
+      return
+    end
+
+    validate_author(object["author"], "#{path}.author") if object.key?("author")
+  end
+
+  # @rbs (untyped, String) -> void
+  def validate_author(author, path)
+    check_type(author, Hash, path)
+    fields = %w[name url avatar]
+    optional_strings(author, fields, path)
+    return if fields.any? { |field| author[field].is_a?(String) }
+
+    raise SimpleRSSError, "JSON Feed #{path} requires name, url, or avatar"
+  end
+
+  # @rbs (Hash[String, untyped], Array[String], String) -> void
+  def optional_strings(object, fields, path)
+    fields.each { |field| check_type(object[field], String, "#{path}.#{field}") if object.key?(field) }
+  end
+
+  # @rbs (Hash[String, untyped], String, String) -> Array[untyped]
+  def optional_array(object, field, path)
+    return [] unless object.key?(field)
+
+    check_type(object[field], Array, "#{path}.#{field}")
+    object[field]
+  end
+
+  # @rbs (Hash[String, untyped], String, String) -> void
+  def required_string(object, field, path)
+    check_type(object[field], String, "#{path}.#{field}")
+  end
+
+  # @rbs (untyped, untyped, String) -> void
+  def check_type(value, type, path)
+    return if value.is_a?(type)
+
+    raise SimpleRSSError, "JSON Feed #{path} must be a #{type}"
+  end
+
+  # @rbs () -> bool
+  def version_1_1?
+    document["version"] == VERSIONS.last
+  end
+
+  # @rbs (Hash[String, untyped]) -> Hash[Symbol, untyped]
+  def legacy_item(original)
+    entry = SimpleRSS::JsonEntryNormalizer.new(original, document).entry
+    attachment = entry.attachments.first || {}
+    original.transform_keys(&:to_sym).merge(
+      id: entry.identifier, guid: entry.identifier, link: entry.url,
+      description: entry.summary || entry.content_text || entry.content_html,
+      content: entry.content_html || entry.content_text, category: entry.categories.dup,
+      pubDate: entry.published_at || original["date_published"], updated: entry.updated_at || original["date_modified"],
+      enclosure_url: attachment[:url], enclosure_type: attachment[:media_type], enclosure_length: attachment[:size_in_bytes],
+      media_thumbnail_url: entry.image, media_content_url: entry.banner_image
+    )
+  end
+
+  # @rbs (untyped) -> void
+  def freeze_data(value)
+    case value
+    when Hash then value.each_value { |child| freeze_data(child) }
+    when Array then value.each { |child| freeze_data(child) }
+    end
+    value.freeze
+  end
+end

data/lib/simple-rss/normalized_entry.rb

@@ -0,0 +1,79 @@
+# rbs_inline: enabled
+
+class SimpleRSS::NormalizedEntry
+  attr_reader :external_url, :image, :banner_image, :language #: String?
+  attr_reader :identifier, :url, :title #: String?
+  attr_reader :published_at, :updated_at #: Time?
+  attr_reader :content_html, :content_text, :content_url, :content_base_url, :summary #: String?
+  attr_reader :summary_type #: Symbol?
+  attr_reader :categories #: Array[String]
+  attr_reader :category_details, :attachments, :links, :authors, :issues #: Array[Hash[Symbol, untyped]]
+  attr_reader :raw #: Hash[Symbol | String, untyped]
+  attr_reader :field_sources #: Hash[Symbol, untyped]
+  attr_reader :raw_xml #: String?
+
+  # @rbs (Hash[Symbol, untyped]) -> void
+  def initialize(attributes)
+    values = immutable_copy(attributes)
+    empty_categories = [] #: Array[String]
+    empty_records = [] #: Array[Hash[Symbol, untyped]]
+    empty_data = {} #: Hash[Symbol, untyped]
+    empty_categories.freeze
+    empty_records.freeze
+    empty_data.freeze
+    @external_url = values[:external_url]
+    @image = values[:image]
+    @banner_image = values[:banner_image]
+    @language = values[:language]
+    @identifier = values[:identifier]
+    @url = values[:url]
+    @title = values[:title]
+    @published_at = values[:published_at]
+    @updated_at = values[:updated_at]
+    @content_html = values[:content_html]
+    @content_text = values[:content_text]
+    @content_url = values[:content_url]
+    @content_base_url = values[:content_base_url]
+    @summary = values[:summary]
+    @summary_type = values[:summary_type]
+    @categories = values.fetch(:categories, empty_categories)
+    @category_details = values.fetch(:category_details, empty_records)
+    @attachments = values.fetch(:attachments, empty_records)
+    @links = values.fetch(:links, empty_records)
+    @authors = values.fetch(:authors, empty_records)
+    @issues = values.fetch(:issues, empty_records)
+    @raw = values.fetch(:raw, empty_data)
+    @raw_xml = values[:raw_xml]
+    @field_sources = values.fetch(:field_sources, empty_data)
+    freeze
+  end
+
+  # @rbs () -> Time?
+  def effective_at
+    published_at || updated_at
+  end
+
+  # @rbs () -> Hash[Symbol, untyped]
+  def to_h
+    {
+      external_url: external_url, image: image, banner_image: banner_image, language: language,
+      identifier: identifier, url: url, title: title, published_at: published_at, updated_at: updated_at,
+      content_html: content_html, content_text: content_text, content_url: content_url, content_base_url: content_base_url,
+      summary: summary, summary_type: summary_type, categories: categories, category_details: category_details,
+      attachments: attachments, links: links, authors: authors, issues: issues, field_sources: field_sources,
+      raw: raw, raw_xml: raw_xml
+    }
+  end
+
+  private
+
+  # @rbs (untyped) -> untyped
+  def immutable_copy(value)
+    case value
+    when Hash then value.to_h { |key, child| [immutable_copy(key), immutable_copy(child)] }.freeze
+    when Array then value.map { |child| immutable_copy(child) }.freeze
+    when String, Time then value.dup.freeze
+    else value
+    end
+  end
+end

data/lib/simple-rss/request_errors.rb

@@ -0,0 +1,21 @@
+# rbs_inline: enabled
+
+class SimpleRSS
+  class RequestError < SimpleRSSError; end
+  class PolicyError < RequestError; end
+  class RequestTimeout < RequestError; end
+  class ResponseTooLarge < RequestError; end
+  class RedirectError < RequestError; end
+  class DiscoveryError < SimpleRSSError; end
+  class DiscoveryDependencyError < DiscoveryError; end
+
+  class HTTPError < RequestError
+    attr_reader :status_code #: Integer
+
+    # @rbs (Integer) -> void
+    def initialize(status_code)
+      @status_code = status_code
+      super("HTTP #{status_code} during feed discovery")
+    end
+  end
+end

data/lib/simple-rss/request_policy.rb

@@ -0,0 +1,72 @@
+# rbs_inline: enabled
+
+require "ipaddr"
+require "resolv"
+require "uri"
+
+class SimpleRSS::RequestPolicy
+  BLOCKED_IPV4 = %w[
+    0.0.0.0/8 10.0.0.0/8 100.64.0.0/10 127.0.0.0/8 169.254.0.0/16 172.16.0.0/12
+    192.0.0.0/24 192.0.2.0/24 192.88.99.0/24 192.168.0.0/16 198.18.0.0/15
+    198.51.100.0/24 203.0.113.0/24 224.0.0.0/4 240.0.0.0/4
+  ].map { |range| IPAddr.new(range).freeze }.freeze
+  GLOBAL_IPV6 = IPAddr.new("2000::/3").freeze
+  BLOCKED_IPV6 = %w[2001::/23 2001:db8::/32 2002::/16 3fff::/20].map { |range| IPAddr.new(range).freeze }.freeze
+
+  # @rbs @policy: untyped
+
+  # @rbs (untyped) -> void
+  def initialize(policy)
+    unless %i[public unrestricted].include?(policy) || policy.respond_to?(:call)
+      raise ArgumentError, "network_policy must be :public, :unrestricted, or a callable"
+    end
+
+    @policy = policy
+  end
+
+  # @rbs (String) -> untyped
+  def self.parse_url(value)
+    uri = URI.parse(value)
+    raise SimpleRSS::PolicyError, "Expected an absolute HTTP or HTTPS URL" unless uri.is_a?(URI::HTTP)
+
+    unless uri.hostname && !uri.hostname.to_s.empty? && uri.port&.between?(1, 65_535)
+      raise SimpleRSS::PolicyError, "Expected a valid host and port"
+    end
+    raise SimpleRSS::PolicyError, "Credentials in URLs are not supported" if uri.userinfo
+
+    uri.fragment = nil
+    uri.path = "/" if uri.path.to_s.empty?
+    uri.normalize
+  rescue URI::Error, TypeError
+    raise SimpleRSS::PolicyError, "Malformed HTTP or HTTPS URL"
+  end
+
+  # @rbs (untyped) -> String
+  def address(uri)
+    addresses = resolve(uri.hostname.to_s)
+    raise SimpleRSS::RequestError, "No destination addresses were resolved" if addresses.empty?
+    unless addresses.all? { |address| allowed?(uri, address) }
+      raise SimpleRSS::PolicyError, "Destination address is prohibited by network_policy"
+    end
+
+    (addresses.find(&:ipv4?) || addresses.fetch(0)).to_s
+  end
+
+  private
+
+  # @rbs (String) -> Array[untyped]
+  def resolve(hostname)
+    [IPAddr.new(hostname)]
+  rescue IPAddr::InvalidAddressError
+    Resolv.getaddresses(hostname).uniq.map { |address| IPAddr.new(address) }
+  end
+
+  # @rbs (untyped, untyped) -> bool
+  def allowed?(uri, address)
+    return true if @policy == :unrestricted
+    return @policy.call(uri.dup.freeze, address.dup.freeze) == true if @policy.respond_to?(:call)
+    return BLOCKED_IPV4.none? { |range| range.include?(address) } if address.ipv4?
+
+    GLOBAL_IPV6.include?(address) && BLOCKED_IPV6.none? { |range| range.include?(address) }
+  end
+end

data/lib/simple-rss/xml_element.rb

@@ -0,0 +1,136 @@
+# rbs_inline: enabled
+
+class SimpleRSS::XmlElement
+  attr_reader :name #: String
+  attr_reader :attributes #: Hash[String, String]
+  attr_reader :content #: String
+  attr_reader :namespaces #: Hash[String, String]
+  attr_reader :base_urls #: Array[String]
+
+  # @rbs (String, String, String?, Hash[Symbol, untyped]) -> void
+  def initialize(name, attributes, content, parent)
+    @name = name
+    @attributes = self.class.attributes(attributes).transform_values { |value| CGI.unescapeHTML(value) }
+    @content = content.to_s
+    @namespaces = parent.fetch(:namespaces).merge(@attributes.select { |key, _value| key == "xmlns" || key.start_with?("xmlns:") })
+    base_url = @attributes["xml:base"]
+    @base_urls = parent.fetch(:base_urls).dup
+    @base_urls << base_url if base_url
+  end
+
+  # @rbs () -> Array[SimpleRSS::XmlElement]
+  def children
+    self.class.child_elements(content).map do |name, attributes, body|
+      self.class.new(name, attributes, body, { namespaces: namespaces, base_urls: base_urls })
+    end
+  end
+
+  # @rbs () -> String?
+  def namespace
+    namespaces[name.include?(":") ? "xmlns:#{name.split(":").first}" : "xmlns"]
+  end
+
+  # @rbs (String, String?) -> bool
+  def matches?(local_name, namespace)
+    name.split(":").last == local_name && self.namespace == namespace
+  end
+
+  # @rbs (String) -> bool
+  def rss?(local_name)
+    return false if name.include?(":") && namespace.nil?
+
+    name.split(":").last == local_name && SimpleRSS::RSS_NAMESPACES.include?(namespace)
+  end
+
+  # @rbs (String) -> bool
+  def selected?(selector)
+    if selector.start_with?("{")
+      namespace, local_name = selector.delete_prefix("{").split("}", 2)
+      return local_name ? matches?(local_name, namespace) : false
+    end
+
+    name == selector
+  end
+
+  # @rbs () -> String
+  def text
+    content.split(/(<!\[CDATA\[.*?\]\]>)/m).map do |part|
+      part.start_with?("<![CDATA[") ? part[9...-3].to_s : CGI.unescapeHTML(part.gsub(/<!--.*?-->|<\?.*?\?>/m, ""))
+    end.join.strip
+  end
+
+  # @rbs () -> Hash[Symbol, untyped]
+  def raw
+    { name: name, namespace: namespace, attributes: attributes, content: content }
+  end
+
+  # @rbs () -> String
+  def xhtml_content
+    scopes = [namespaces]
+    content.gsub(SimpleRSS::XML_TAG_PATTERN) do |token|
+      name = Regexp.last_match(2).to_s
+      attributes = Regexp.last_match(3)
+      closing = Regexp.last_match(1) == "/"
+      next token unless attributes
+
+      if closing
+        context = scopes.last || namespaces
+        scopes.pop if scopes.size > 1
+      else
+        declarations = self.class.attributes(attributes).select { |key, _value| key == "xmlns" || key.start_with?("xmlns:") }
+        context = (scopes.last || namespaces).merge(declarations.transform_values { |value| CGI.unescapeHTML(value) })
+        scopes << context unless attributes.rstrip.end_with?("/")
+      end
+      namespace = context[name.include?(":") ? "xmlns:#{name.split(":").first}" : "xmlns"]
+      next token unless namespace == "http://www.w3.org/1999/xhtml"
+
+      token.sub(name, name.split(":").last.to_s)
+    end.strip
+  end
+
+  # @rbs (String) -> Hash[String, String]
+  def self.attributes(attributes)
+    values = {} #: Hash[String, String]
+    attributes.scan(/([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/m) do
+      name = Regexp.last_match(1)
+      value = Regexp.last_match(2) || Regexp.last_match(3)
+      values[name] = value if name && value
+    end
+    values
+  end
+
+  # @rbs (String) -> Array[[String, String, String?]]
+  def self.child_elements(content)
+    elements = [] #: Array[[String, String, String?]]
+    current_element = nil #: [String, String, String?]?
+    depth = 0
+    body_start = 0
+    position = 0
+
+    while (token = SimpleRSS::XML_TAG_PATTERN.match(content, position))
+      position = token.end(0)
+      attributes = token[3]
+      next unless attributes
+
+      if token[1] == "/"
+        depth = [depth - 1, 0].max
+        if depth.zero? && current_element
+          current_element[2] = content[body_start...token.begin(0)]
+          current_element = nil
+        end
+        next
+      end
+
+      self_closing = attributes.rstrip.end_with?("/")
+      if depth.zero?
+        element = [token[2].to_s, attributes, nil] #: [String, String, String?]
+        elements << element
+        current_element = element unless self_closing
+        body_start = token.end(0)
+      end
+      depth += 1 unless self_closing
+    end
+
+    elements
+  end
+end