webmention 10.0.0 → 10.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18cd676b542de4d7d4507fb30a6475cba645feca8dccebb4230d48904165d1dd
-  data.tar.gz: 309bb9ad852cc944a747a1b18a25e04009e9c0095f3249212654b4ee920e5132
+  metadata.gz: 0aef2414279b18a19630ebbff1fbd432bcdf6f99bebd04fbec000956d13de4d0
+  data.tar.gz: caaace5949544c00d5d020844d3ed4ce34208cbea81a67a8fd8acd8729bbe97a
 SHA512:
-  metadata.gz: f73890fc04da3b8ec912f3b469cdb7f29ef2761b56e0ca4854133981c3b18ecb09c7be7d1e24253935dafd0c858be13fd45c60c0365b2e005f7659ec74ee9467
-  data.tar.gz: d00e9b5a4b32fefcdc48e59e3a33d73662e79c563f69517be55984c57ba2fc790d544fac3f58c06b91bee6b92258fa2fe6b7f59aac73c92030d2ca14bbcd4d76
+  metadata.gz: 336f4b3d91f462223978f5fd52db6f1d3da4a4a4b27d56d70f48665e4585a0b0fef43703ebe10a9e9063a1599928166d895c94d74b3e91da5d5c0d50d581d3bc
+  data.tar.gz: 4ff3c624983522c24a777c3fd409605d6a4c4f4b33c8158f5558c3b2f9969d5942f4f3fd2b66689b029a3d9375e0d17522e7e4a040ba8d130adaed0417965dba

data/.yardopts

@@ -0,0 +1,6 @@
+-
+CHANGELOG.md
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+LICENSE
+USAGE.md

data/README.md

@@ -48,4 +48,4 @@ To learn more about Webmention, see [indieweb.org/Webmention](https://indieweb.o
 
 ## License
 
-This project is freely available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). See [LICENSE](https://github.com/indieweb/webmention-client-ruby/blob/main/LICENSE) for more details.
+This project is freely available under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.html). See [LICENSE](LICENSE) for more details.

data/lib/webmention/client.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Webmention
+  # A client interface to send and verify Webmention notifications.
   class Client
     # @return [Url]
     attr_reader :source_url
@@ -16,18 +17,18 @@ module Webmention
     # @example
     #   Webmention::Client.new("https://jgarber.example/posts/100", vouch: "https://tantek.example/notes/1")
     #
+    # @see https://indieweb.org/Vouch
+    #
     # @param source [String, HTTP::URI, #to_s]
     #   An absolute URL representing a source document.
     # @param vouch [String, HTTP::URI, #to_s]
     #   An absolute URL representing a document vouching for the source document.
-    #   See https://indieweb.org/Vouch for additional details.
     def initialize(source, vouch: nil)
       @source_url = Url.new(source)
       @vouch_url = Url.new(vouch)
     end
 
-    # @return [String]
-    #
+    # @!visibility private
     # simplecov:disable
     def inspect
       "#<#{self.class}:#{format("%#0x", object_id)} " \
@@ -36,7 +37,7 @@ module Webmention
     end
     # simplecov:enable
 
-    # Retrieve unique URLs mentioned by this client's source URL.
+    # Unique URLs mentioned by {source_url}.
     #
     # @example
     #   client = Webmention::Client.new("https://jgarber.example/posts/100")
@@ -56,7 +57,7 @@ module Webmention
         .sort
     end
 
-    # Send a webmention from this client's source URL to a target URL.
+    # Send a webmention from this client's {source_url} to a target URL.
     #
     # @example
     #   client = Webmention::Client.new("https://jgarber.example/posts/100")
@@ -81,7 +82,7 @@ module Webmention
       ErrorResponse.new("No Webmention endpoint found for target URL #{target}", response.request)
     end
 
-    # Send webmentions from this client's source URL to multiple target URLs.
+    # Send webmentions from {source_url} to multiple target URLs.
     #
     # @example
     #   client = Webmention::Client.new("https://jgarber.example/posts/100")
@@ -96,10 +97,9 @@ module Webmention
       targets.map { |target| send_webmention(target) }
     end
 
-    # Verify that this client's source URL links to a target URL.
+    # Verify that {source_url} links to a target URL.
     #
-    # @param target [String, HTTP::URI, #to_s]
-    #   An absolute URL representing a target document.
+    # @param target (see #send_webmention)
     #
     # @raise (see Client#mentioned_urls)
     #
@@ -110,7 +110,7 @@ module Webmention
 
     private
 
-    # @param target [String, HTTP::URI, #to_s]
+    # @param target (see #send_webmention)
     #
     # @return [Hash{Symbol => String}]
     def request_options_for(target)

data/lib/webmention/error_response.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Webmention
+  # An interface to instances of the {Request} class.
+  #
+  # An {ErrorResponse} represents {Request}s that generated errors (e.g.
+  # connection error, SSL error) or that could not locate a Webmention endpoint.
+  # The nature of the error is captured in the {#message} instance method.
   class ErrorResponse
     # @return [String]
     attr_reader :message
@@ -10,11 +15,6 @@ module Webmention
 
     # Create a new {ErrorResponse}.
     #
-    # Instances of this class represent HTTP requests that generated errors
-    # (e.g. connection error, SSL error) or that could not locate a Webmention
-    # endpoint. The nature of the error is captured in the {#message} instance
-    # method.
-    #
     # @api private
     #
     # @param message [String]
@@ -24,8 +24,7 @@ module Webmention
       @request = request
     end
 
-    # @return [String]
-    #
+    # @!visibility private
     # simplecov:disable
     def inspect
       "#<#{self.class}:#{format("%#0x", object_id)} " \
@@ -33,12 +32,16 @@ module Webmention
     end
     # simplecov:enable
 
+    # An {ErrorResponse} has no mentioned URLs.
+    #
     # @return [Set]
     def mentioned_urls
       Set.new
     end
 
-    # @return [Boolean]
+    # An {ErrorResponse} is never okay!
+    #
+    # @return [false]
     def ok?
       false
     end

data/lib/webmention/request.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Webmention
+  # An interface for executing HTTP requests and generating {Response}s and
+  # {ErrorResponse}s.
+  #
   # @api private
   class Request
     # Set defaults derived from Webmention specification examples.
@@ -13,7 +16,7 @@ module Webmention
       },
       headers: {
         accept: "*/*",
-        user_agent: "Webmention Client (https://rubygems.org/gems/webmention)",
+        user_agent: "Mozilla/5.0 (compatible; WebmentionClient/1.0; +https://rubygems.org/gems/webmention)",
       },
       timeout_options: {
         connect_timeout: 5,
@@ -48,24 +51,20 @@ module Webmention
     #     },
     #   )
     #
+    # @see https://indieweb.org/Vouch
+    #
     # @param method [Symbol]
     # @param url [String]
-    # @param options [Hash{Symbol => String}]
-    # @option options [String] :source
-    #   An absolute URL representing a source document.
-    # @option options [String] :target
-    #   An absolute URL representing a target document.
-    # @option options [String] :vouch
-    #   An absolute URL representing a document vouching for the source document.
-    #   See https://indieweb.org/Vouch for additional details.
+    # @param options [Hash{Symbol => Hash{Symbol => String}}]
+    # @option options [Hash{Symbol => String}] :form
+    #   A Hash of options to serialize as form-encoded.
     def initialize(method, url, **options)
       @method = method.to_sym
       @uri = HTTP::URI.parse(url.to_s)
       @options = options
     end
 
-    # @return [String]
-    #
+    # @!visibility private
     # simplecov:disable
     def inspect
       "#<#{self.class}:#{format("%#0x", object_id)} " \
@@ -74,7 +73,7 @@ module Webmention
     end
     # simplecov:enable
 
-    # Submit the {Request}.
+    # Execute the {Request}.
     #
     # @return [Response, ErrorResponse]
     def perform

data/lib/webmention/response.rb

@@ -1,39 +1,50 @@
 # frozen_string_literal: true
 
 module Webmention
+  # An interface to instances of the {Request} and `HTTP::Response` classes.
+  #
+  # A {Response} represents the results of a successful {Request}.
   class Response
     extend Forwardable
 
+    # Consider the first h-entry to be the authoritative content container when
+    # parsing a document for mentioned URLs. Fall back to the `<body>` element
+    # when no h-entry is found.
+    #
+    # @see http://microformats.org/wiki/h-entry
     PARSE_CONTEXT = [".h-entry .e-content", ".h-entry", "body"].freeze
+
     URI_REGEXP = URI::RFC2396_Parser.new.make_regexp(["http", "https"]).freeze
 
-    private_constant :PARSE_CONTEXT
+    public_constant :PARSE_CONTEXT
     private_constant :URI_REGEXP
 
+    # The {Request} associated with this {Response}.
+    #
     # @return [Request]
     attr_reader :request
 
-    # @!method
+    # @!method headers
     #   @return [HTTP::Headers]
     def_delegator :@response, :headers
 
-    # @!method
+    # @!method body
     #   @return [HTTP::Response::Body]
     def_delegator :@response, :body
 
-    # @!method
+    # @!method code
     #   @return [Integer]
     def_delegator :@response, :code
 
-    # @!method
+    # @!method reason
     #   @return [String]
     def_delegator :@response, :reason
 
-    # !@method
+    # @!method mime_type
     #   @return [String]
     def_delegator :@response, :mime_type
 
-    # !@method
+    # @!method uri
     #   @return [HTTP::URI]
     def_delegator :@response, :uri
 
@@ -52,8 +63,7 @@ module Webmention
       @request = request
     end
 
-    # @return [String]
-    #
+    # @!visibility private
     # simplecov:disable
     def inspect
       "#<#{self.class}:#{format("%#0x", object_id)} " \
@@ -63,14 +73,20 @@ module Webmention
     end
     # simplecov:enable
 
-    # Parse the response body for unique host names.
+    # Unique host names parsed from the response body.
+    #
+    # The returned `Set` contains the unique host names ("domain names") derived
+    # from the `Set` of {mentioned_urls}. Order is not guaranteed.
     #
     # @return [Set<String>]
     def mentioned_hosts
       @mentioned_hosts ||= Set.new(mentioned_urls.map { |url| HTTP::URI.parse(url).host })
     end
 
-    # Parse the response body for mentioned URLs.
+    # Unique mentioned URLs parsed from the response body.
+    #
+    # The returned `Set` contains the unique URLs parsed from the
+    # {PARSE_CONTEXT}. Order is not guaranteed.
     #
     # @return [Set<String>]
     def mentioned_urls
@@ -83,7 +99,9 @@ module Webmention
         )
     end
 
-    # @return [Boolean]
+    # A {Response} is always okay!
+    #
+    # @return [true]
     def ok?
       true
     end

data/lib/webmention/url.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 module Webmention
+  # An interface representing a parsed URL and its {Response}.
+  #
   # @api private
   class Url
     extend Forwardable
@@ -19,8 +21,7 @@ module Webmention
       @uri = HTTP::URI.parse(url.to_s)
     end
 
-    # @return [String]
-    #
+    # @!visibility private
     # simplecov:disable
     def inspect
       "#<#{self.class}:#{format("%#0x", object_id)} " \

data/lib/webmention/verification.rb

@@ -1,26 +1,27 @@
 # frozen_string_literal: true
 
 module Webmention
+  # Verify that a source URL links to a target URL.
   class Verification
     # Create a new {Verification}.
     #
     # @api private
     #
+    # @see https://indieweb.org/Vouch
+    #
     # @param source_url [Url]
     #   An {URL} representing a source document.
     # @param target_url [Url]
     #   An {URL} representing a target document.
     # @param vouch_url [Url]
     #   An {URL} representing a document vouching for the source document.
-    #   See https://indieweb.org/Vouch for additional details.
     def initialize(source_url, target_url, vouch_url: nil)
       @source_url = source_url
       @target_url = target_url
       @vouch_url = vouch_url
     end
 
-    # @return [String]
-    #
+    # @!visibility private
     # simplecov:disable
     def inspect
       "#<#{self.class}:#{format("%#0x", object_id)} " \

data/lib/webmention.rb

@@ -14,6 +14,9 @@ require_relative "webmention/response"
 require_relative "webmention/error_response"
 require_relative "webmention/verification"
 
+# Send and verify Webmention notifications.
+#
+# @see https://indieweb.org/Webmention
 module Webmention
   # Retrieve unique URLs mentioned by the provided URL.
   #
@@ -22,10 +25,9 @@ module Webmention
   #
   # @param url [String, HTTP::URI, #to_s] An absolute URL.
   #
-  # @raise [Burly::UnsupportedMimeType]
-  #   Raised when response is of an unsupported MIME type.
+  # @raise (see Client#mentioned_urls)
   #
-  # @return [Array<String>]
+  # @return (see Client#mentioned_urls)
   def self.mentioned_urls(url)
     Client.new(url).mentioned_urls
   end
@@ -42,15 +44,13 @@ module Webmention
   #   target = "https://aaronpk.example/notes/1"
   #   Webmention.send_webmention(source, target, vouch: "https://tantek.example/notes/1")
   #
-  # @param source [String, HTTP::URI, #to_s]
-  #   An absolute URL representing a source document.
-  # @param target [String, HTTP::URI, #to_s]
-  #   An absolute URL representing a target document.
-  # @param vouch [String, HTTP::URI, #to_s]
-  #   An absolute URL representing a document vouching for the source document.
-  #   See https://indieweb.org/Vouch for additional details.
+  # @see https://indieweb.org/Vouch
+  #
+  # @param source (see Client#initialize)
+  # @param target (see Client#send_webmention)
+  # @param vouch (see Client#initialize)
   #
-  # @return [Response, ErrorResponse]
+  # @return (see Client#send_webmention)
   def self.send_webmention(source, target, vouch: nil)
     Client.new(source, vouch: vouch).send_webmention(target)
   end
@@ -67,13 +67,9 @@ module Webmention
   #   targets = ["https://aaronpk.example/notes/1", "https://adactio.example/notes/1"]
   #   Webmention.send_webmentions(source, targets, vouch: "https://tantek.example/notes/1")
   #
-  # @param source [String, HTTP::URI, #to_s]
-  #   An absolute URL representing a source document.
-  # @param targets [Array<String, HTTP::URI, #to_s>]
-  #   An array of absolute URLs representing multiple target documents.
-  # @param vouch [String, HTTP::URI, #to_s]
-  #   An absolute URL representing a document vouching for the source document.
-  #   See https://indieweb.org/Vouch for additional details.
+  # @see https://indieweb.org/Vouch
+  #
+  # @param (see .send_webmention)
   #
   # @return [Array<Response, ErrorResponse>]
   def self.send_webmentions(source, *targets, vouch: nil)
@@ -82,7 +78,7 @@ module Webmention
 
   # Verify that a source URL links to a target URL.
   #
-  # @param (see Webmention.send_webmention)
+  # @param (see .send_webmention)
   #
   # @raise (see Client#mentioned_urls)
   #

data/webmention.gemspec

@@ -4,7 +4,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 2.7"
 
   spec.name = "webmention"
-  spec.version = "10.0.0"
+  spec.version = "10.1.0"
   spec.authors = ["Jason Garber"]
   spec.email = ["jason@sixtwothree.org"]
 
@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
   spec.license = "Apache-2.0"
 
   spec.files = Dir["lib/**/*"].reject { |f| File.directory?(f) }
-  spec.files += ["LICENSE", "CHANGELOG.md", "CONTRIBUTING.md", "README.md", "USAGE.md"]
+  spec.files += [".yardopts", "LICENSE", "CHANGELOG.md", "CONTRIBUTING.md", "README.md", "USAGE.md"]
   spec.files += ["webmention.gemspec"]
 
   spec.require_paths = ["lib"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: webmention
 version: !ruby/object:Gem::Version
-  version: 10.0.0
+  version: 10.1.0
 platform: ruby
 authors:
 - Jason Garber
@@ -72,6 +72,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - CONTRIBUTING.md
 - LICENSE
@@ -90,11 +91,11 @@ licenses:
 - Apache-2.0
 metadata:
   bug_tracker_uri: https://github.com/indieweb/webmention-client-ruby/issues
-  changelog_uri: https://github.com/indieweb/webmention-client-ruby/releases/tag/v10.0.0
-  documentation_uri: https://rubydoc.info/gems/webmention/10.0.0
+  changelog_uri: https://github.com/indieweb/webmention-client-ruby/releases/tag/v10.1.0
+  documentation_uri: https://rubydoc.info/gems/webmention/10.1.0
   homepage_uri: https://github.com/indieweb/webmention-client-ruby
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/indieweb/webmention-client-ruby/tree/v10.0.0
+  source_code_uri: https://github.com/indieweb/webmention-client-ruby/tree/v10.1.0
 rdoc_options: []
 require_paths:
 - lib