Skip to content

Latest commit

 

History

History
110 lines (67 loc) · 5.26 KB

README.md

File metadata and controls

110 lines (67 loc) · 5.26 KB

webmention-client-ruby

A Ruby gem for sending Webmention notifications.

Gem Downloads Build Maintainability Coverage

Key Features

  • Crawls a given URL for mentioned URLs.
  • Performs endpoint discovery on mentioned URLs.
  • Sends webmentions to mentioned URLs.

Getting Started

Before installing and using webmention-client-ruby, you'll want to have Ruby 2.4 (or newer) installed. It's recommended that you use a Ruby version managment tool like rbenv, chruby, or rvm.

webmention-client-ruby is developed using Ruby 2.4.7 and is additionally tested against Ruby 2.5 and 2.6 using Travis CI.

Installation

If you're using Bundler to manage gem dependencies, add webmention-client-ruby to your project's Gemfile:

source 'https://rubygems.org'

gem 'webmention'

…and then run:

bundle install

Usage

With webmention-client-ruby added to your project's Gemfile and installed, you may send a webmention from a source URL to a target URL:

require 'webmention'

source = 'https://source.example.com/post/100'  # A post on your website
target = 'https://target.example.com/post/100'  # A post on someone else's website

Webmention.send_mention(source, target) # => #<HTTP::Response/1.1 200 OK {…}>

If no Webmention endpoint is found for a given source URL, the send_mention method will return nil.

Note: HTTP::Response objects may return a variety of status codes that will vary depending on the endpoint's capabilities and the success or failure of the request. See the Webmention spec for more on status codes on their implications.

Sending multiple webmentions

To send webmentions to all URLs mentioned within a source URL's h-entry:

require 'webmention'

client = Webmention.client('https://source.example.com/post/100')

client.mentioned_urls    # => Array
client.send_all_mentions # => Hash

This example will crawl https://source.example.com/post/100, parse its markup for the first h-entry, perform endpoint discovery on mentioned URLs, and attempt to send webmentions to those URLs.

Note: If no h-entry is found at the provided source URL, the send_all_mentions method will search the source URL's <body> for mentioned URLs.

The send_all_mentions method returns a hash of mentioned URLs and the associated HTTP response (an HTTP::Response object):

{
  'https://target.example.com/post/100' => #<HTTP::Response/1.1 200 OK {…}>,
  'https://target.example.com/post/101' => #<HTTP::Response/1.1 200 OK {…}>
}

Exception Handling

There are several exceptions that may be raised by webmention-client-ruby's underlying dependencies. These errors are raised as subclasses of WebmentionClientError (which itself is a subclass of StandardError).

From sporkmonger/addressable:

  • Webmention::Client::InvalidURIError

From httprb/http:

  • Webmention::Client::ConnectionError
  • Webmention::Client::TimeoutError
  • Webmention::Client::TooManyRedirectsError

webmention-client-ruby will also raise a Webmention::Client::UnsupportedMimeTypeError when encountering an HTTP::Response instance with an unsupported MIME type.

Contributing

Interested in helping improve webmention-client-ruby? Awesome! Your help is greatly appreciated. See CONTRIBUTING.md for details.

Acknowledgments

webmention-client-ruby is written and maintained by Aaron Parecki (@aaronpk) and Nat Welch (@icco) with help from these additional contributors.

To learn more about Webmention, see indieweb.org/Webmention and webmention.net.

License

webmention-client-ruby is freely available under the Apache License 2.0. See LICENSE for more details.