bridgetown-webfinger 0.1.0

data/lib/bridgetown/webfinger/link.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # Wraps a [link][1] object within a {JRD}
+    #
+    # Links represent links to resources external to the entity. They are
+    # _optional_ within a JRD so may not appear in your Webfinger setup.
+    #
+    # [1]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4
+    class Link
+      extend Logging
+
+      # Parses and maybe-returns a {Link} when the value is one
+      #
+      # [Links][1] within the {JRD} are member objects representing a link to
+      # another resource.
+      #
+      # [1]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @param data [Hash] the data to parse as a link object
+      # @return [Link, nil] the link parsed from the data
+      def self.parse(data)
+        unless (rel = LinkRelationType.parse(data[:rel]))
+          return warn(
+            "Webfinger link rel is missing or malformed: #{data.inspect}, ignoring"
+          )
+        end
+
+        new(
+          rel: rel,
+          href: Href.parse(data[:href]),
+          properties: Properties.parse(data[:properties]),
+          titles: Titles.parse(data[:titles]),
+          type: data[:type]
+        )
+      end
+
+      # Creates a new {Link}
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @param rel [LinkRelationType] the type of relation the {Link} represents
+      # @param href [Href, nil] the optional {Href} URI of the link
+      # @param properties [Properties, nil] the optional list of {Properties}
+      #   describing the link
+      # @param titles [Titles, nil] the optional list of {Titles} naming the link
+      # @param type [String, nil] the optional media type of the target resource
+      def initialize(rel:, href: nil, properties: nil, titles: nil, type: nil)
+        @href = href
+        @properties = properties
+        @rel = rel
+        @titles = titles
+        @type = type
+      end
+
+      # The optional hypertext reference to a URI for the {Link}
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [Href, nil] the optional {Href} URI of the link
+      attr_reader :href
+
+      # The optional {Properties} characterizing the {Link}
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [Properties, nil] the optional list of {Properties} describing
+      #   the link
+      attr_reader :properties
+
+      # The {LinkRelationType} describing what the {Link} links to
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [LinkRelationType] the type of relation the {Link} represents
+      attr_reader :rel
+
+      # The optional {Titles} describing the {Link}
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [Titles, nil] the optional list of {Titles} naming the link
+      attr_reader :titles
+
+      # The optional media type of the {#href} for the {Link}
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [String, nil] the optional media type of the target resource
+      attr_reader :type
+
+      # Converts the {Link} into a JSON-serializable Hash
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [Hash] the Link as a JSON-compatible Hash
+      def to_h
+        result = {rel: rel}
+        result[:href] = href if href
+        result[:properties] = properties if properties
+        result[:titles] = titles if titles
+        result[:type] = type if type
+        result
+      end
+    end
+  end
+end

data/lib/bridgetown/webfinger/link_relation_type.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # Wraps the type of a {Link} relation
+    class LinkRelationType < Model
+      # The list of relation types, as [registered with IANA][1]
+      #
+      # This constant can be regenerated with the `data:link_relations` Rake
+      # task.
+      #
+      # [1]: https://www.iana.org/assignments/link-relations
+      #
+      # @since 0.1.0
+      # @api private
+      REGISTERED = Set.new(%w[
+        about
+        acl
+        alternate
+        amphtml
+        appendix
+        apple-touch-icon
+        apple-touch-startup-image
+        archives
+        author
+        blocked-by
+        bookmark
+        canonical
+        chapter
+        cite-as
+        collection
+        contents
+        convertedfrom
+        copyright
+        create-form
+        current
+        describedby
+        describes
+        disclosure
+        dns-prefetch
+        duplicate
+        edit
+        edit-form
+        edit-media
+        enclosure
+        external
+        first
+        glossary
+        help
+        hosts
+        hub
+        icon
+        index
+        intervalafter
+        intervalbefore
+        intervalcontains
+        intervaldisjoint
+        intervalduring
+        intervalequals
+        intervalfinishedby
+        intervalfinishes
+        intervalin
+        intervalmeets
+        intervalmetby
+        intervaloverlappedby
+        intervaloverlaps
+        intervalstartedby
+        intervalstarts
+        item
+        last
+        latest-version
+        license
+        linkset
+        lrdd
+        manifest
+        mask-icon
+        media-feed
+        memento
+        micropub
+        modulepreload
+        monitor
+        monitor-group
+        next
+        next-archive
+        nofollow
+        noopener
+        noreferrer
+        opener
+        openid2.local_id
+        openid2.provider
+        original
+        p3pv1
+        payment
+        pingback
+        preconnect
+        predecessor-version
+        prefetch
+        preload
+        prerender
+        prev
+        preview
+        previous
+        prev-archive
+        privacy-policy
+        profile
+        publication
+        related
+        restconf
+        replies
+        ruleinput
+        search
+        section
+        self
+        service
+        service-desc
+        service-doc
+        service-meta
+        sip-trunking-capability
+        sponsored
+        start
+        status
+        stylesheet
+        subsection
+        successor-version
+        sunset
+        tag
+        terms-of-service
+        timegate
+        timemap
+        type
+        ugc
+        up
+        version-history
+        via
+        webmention
+        working-copy
+        working-copy-of
+      ]).freeze
+
+      # Parses a maybe-returns a {LinkRelationType} when the value is one
+      #
+      # Link relation types may either be a URI to a relation type description
+      # or a value [registered with IANA][1].
+      #
+      # [1]: https://www.iana.org/assignments/link-relations
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @param rel [String] the rel to parse and validate
+      # @return [LinkRelationType, nil] the link relation type parsed from the rel
+      def self.parse(rel)
+        return unless Webfinger.uri?(rel) || REGISTERED.include?(rel)
+
+        new(rel)
+      end
+    end
+  end
+end

data/lib/bridgetown/webfinger/logging.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # Helper methods for logging purposes
+    module Logging
+      # When including the module, also extend it as well
+      #
+      # @since 0.1.0
+      # @api private
+      # @private
+      #
+      # @param base [Module] the base module or class including the module
+      # @return [void]
+      def self.included(base)
+        super
+        base.extend(self)
+      end
+
+      # Sends a warning message through the Bridgetown logger
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Print a warning in the logger
+      #
+      #    extend Bridgetown::Webfinger::Logging
+      #    warn "I like some of you less than you deserve"
+      #
+      # @param msg [String] the message to log
+      # @return [void]
+      def warn(msg)
+        Bridgetown.logger.warn(msg)
+        nil
+      end
+    end
+  end
+end

data/lib/bridgetown/webfinger/model.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # A wrapper for wrapping models within a {JRD}
+    #
+    # @since 0.1.0
+    # @api private
+    class Model < SimpleDelegator
+      include Logging
+    end
+  end
+end

data/lib/bridgetown/webfinger/parameters.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Bridgetown
+  module Webfinger
+    # Parses URI parameters in the Webfinger style
+    #
+    # This is necessary because Rack handles parameters differently than the
+    # Webfinger specification. In Rack, repeated parameters compete in a
+    # last-one-wins scheme. For example:
+    #
+    #     https://example.com?foo=1&foo=2&bar=3
+    #
+    # parses into:
+    #
+    #     {"foo" => 2, "bar" => 3}
+    #
+    # whereas Webfinger's processing [wants this][1]:
+    #
+    #     {"foo" => [1, 2], "bar" => 3}
+    #
+    # per the phrasing “the "rel" parameter MAY be included multiple times in
+    # order to request multiple link relation types.”
+    #
+    # [1]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.3
+    #
+    # @since 0.1.0
+    # @api private
+    class Parameters
+      # Splits query parameters at the ampersand and optional spaces
+      #
+      # This was borrowed from [Rack::QueryParser][2] and simplified.
+      #
+      # [2]: https://rubydoc.info/gems/rack/Rack/QueryParser
+      SPLITTER = %r{& *}n
+
+      # Parses a query string for a webfinger request into a hash
+      #
+      # This method cleans any unrelated parameters from the result and combines
+      # multiple requests for `rel`s into an array. It also handles unescaping
+      # terms.
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @param [String] query_string the query string for a webfinger request
+      # @return [Parameters] the cleaned param values
+      def self.from_query_string(query_string)
+        query_string
+          .split(SPLITTER)
+          .map { |pair| pair.split("=", 2).map! { |component| decode(component) } }
+          .each_with_object(Parameters.new) do |(param, value), result|
+            case param
+            when "resource" then result.resource = value
+            when "rel" then result.add_rel(value)
+            end
+          end
+      end
+
+      # Decodes a URI component; an alias to the URI method, for brevity
+      #
+      # @since 0.1.0
+      # @api private
+      # @private
+      #
+      # @param component [String] the component from the URI
+      # @return [String] the decoded component
+      private_class_method def self.decode(component)
+        URI.decode_uri_component(component)
+      end
+
+      # Creates a new {Parameters} from an optional resource and rel
+      #
+      #
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Create an empty
+      #
+      # @param resource [String, nil] the resource for the request
+      # @param rel [Array<String>, nil] the types of relation to scope the links to
+      # @return [void]
+      def initialize(resource: nil, rel: nil)
+        @resource = resource
+        @rel = rel
+      end
+
+      # The list of link relations requested within the {Parameters}
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Reading the link relations requested as a URL parameter
+      #
+      #   params = Bridgetown::Webfinger::Parameters.from_query_string(
+      #     "resource=acct%3Abilbo%40bagend.com&" \
+      #     "rel=http%3A%2F%2Fwebfinger.net%2Frel%2Favatar&" \
+      #     "rel=http%3A%2F%2Fwebfinger.net%2Frel%2Fprofile-page"
+      #   )
+      #   params.rel
+      #   #=> ["https://webfinger.net/rel/avatar", "https://webfinger.net/rel/profile-page"]
+      # @return [Array<String>, nil] the types of relation to scope the links to
+      attr_reader :rel
+
+      # The decoded resource requested within the {Parameters}
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Reading the resource requested as a URL parameter
+      #
+      #    params = Bridgetown::Webfinger::Parameters.from_query_string(
+      #      "resource=acct%3Abilbo%40bagend.com"
+      #    )
+      #    params.resource #=> "acct:bilbo@bagend.com"
+      #
+      # @return [String, nil] the resource for the request
+      attr_accessor :resource
+
+      # Checks for value object equality
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @param other [Parameters] the other parameter set to compare against
+      # @return [Boolean] true when they are equal, false otherwise
+      def ==(other)
+        other.instance_of?(Parameters) &&
+          resource == other.resource &&
+          rel == other.rel
+      end
+      alias_method :eql?, :==
+
+      # Adds a link relation, or "rel," to the {Parameters}
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Adding a link relation to a new {Parameters} instance
+      #
+      #   params = Bridgetown::Webfinger::Parameters.new
+      #   params.add_rel("http://webfinger.net/rel/avatar")
+      #   params.rel  #=> ["http://webfinger.net/rel/avatar"]
+      #
+      # @param rel [String] a type of relation to add to the scope request
+      # @return [void]
+      def add_rel(rel)
+        return unless rel
+
+        (@rel ||= []).push(rel)
+      end
+
+      # Allows the {Parameters} to be used in a Hash key; part of value object semantics
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [Integer]
+      def hash
+        [resource, *rel].hash
+      end
+    end
+  end
+end

data/lib/bridgetown/webfinger/properties.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # Wraps a `properties` member within a {Link} or {JRD}
+    class Properties < Model
+      # Parses and maybe-returns {Properties} when the value is one
+      #
+      # Properties within the {JRD} are name/value pairs [with URIs for names
+      # and strings or nulls for values][1].
+      #
+      # [1]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.5
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @param data [Hash] the data to parse as a properties object
+      # @return [Properties, nil] the properties parsed from the data
+      def self.parse(data)
+        return unless data
+
+        unless data.is_a?(Hash)
+          return warn("Webfinger link properties are malformed: #{data.inspect}, ignoring")
+        end
+
+        properties = data.select do |name, value|
+          if !Webfinger.uri?(name)
+            next warn("Webfinger property name is not a URI: #{name}, ignoring")
+          elsif !value.is_a?(String) || value.nil?
+            next warn("Webfinger property value is not a nullable string: #{value}, ignoring")
+          else
+            true
+          end
+        end
+
+        if !properties.empty?
+          new(properties)
+        else
+          warn("All Webfinger link properties pruned: #{data.inspect}, ignoring")
+        end
+      end
+    end
+  end
+end

data/lib/bridgetown/webfinger/titles.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # Wraps a `titles` member within a {Link}
+    class Titles < Model
+      # Parses and maybe-returns {Titles} when the value is one
+      #
+      # Titles within the {JRD} are name/value pairs [with language tag names
+      # and string values][2]. When the language is indeterminate, use `"und"`.
+      #
+      # [1]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.4
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @param data [Hash] the data to parse as a titles object
+      # @return [Titles, nil] the titles parsed from the data
+      def self.parse(data)
+        return unless data.is_a?(Hash)
+
+        data = data.select do |key, value|
+          if !key.is_a?(String)
+            next warn("Webfinger title key is not a string: #{key}, ignoring")
+          elsif !value.is_a?(String)
+            next warn("Webfinger title value for #{key} is not a string: #{value}, ignoring")
+          else
+            true
+          end
+        end
+
+        if !data.empty?
+          new(data)
+        else
+          warn("All Webfinger link titles pruned: #{data.inspect}, ignoring")
+        end
+      end
+    end
+  end
+end