webmention-endpoint-ruby

⚠️ Deprecation Notice (2019-04-25) ⚠️ This gem is deprecated in favor of indieweb/indieweb-endpoints-ruby and will no longer receive updates.

A Ruby gem for discovering a URL's Webmention endpoint.

• Compliant with Section 3.1.2 of the W3C's Webmention Recommendation.
• Passes all Endpoint Discovery tests on webmention.rocks.
• Supports Ruby 2.4 and newer.

Before installing and using webmention-endpoint-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-endpoint-ruby is developed using Ruby 2.4.6 and is additionally tested against Ruby 2.5.5 and 2.6.2 using Travis CI.

If you're using Bundler, add webmention-endpoint-ruby to your project's Gemfile:

source 'https://rubygems.org'

gem 'webmention-endpoint'

…and hop over to your command prompt and run…

$ bundle install

With webmention-endpoint-ruby added to your project's Gemfile and installed, you may discover a URL's Webmention endpoint by doing:

require 'webmention/endpoint'

endpoint = Webmention::Endpoint.discover('https://webmention.rocks/test/1')

puts endpoint # returns String: 'https://webmention.rocks/test/1/webmention'

This example will search https://webmention.rocks/test/1 for a valid Webmention endpoint in accordance with the rules described in the W3C's Webmention Recommendation. In this case, the program returns a string: https://webmention.rocks/test/1/webmention.

If no endpoint is discovered at the provided URL, the program will return nil:

require 'webmention/endpoint'

endpoint = Webmention::Endpoint.discover('https://example.com')

puts endpoint.nil? # returns Boolean: true

Should the need arise, you may work directly with the Webmention::Endpoint::Client class:

require 'webmention/endpoint'

client = Webmention::Endpoint::Client.new('https://webmention.rocks/test/1')

puts client.response # returns HTTP::Response
puts client.endpoint # returns String: 'https://webmention.rocks/test/1/webmention'

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

From jgarber623/absolutely and sporkmonger/addressable:

• Webmention::Endpoint::InvalidURIError

From httprb/http:

• Webmention::Endpoint::ConnectionError
• Webmention::Endpoint::TimeoutError
• Webmention::Endpoint::TooManyRedirectsError

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

webmention-endpoint-ruby wouldn't exist without Webmention and the hard work put in by everyone involved in the IndieWeb movement. Additionally, the comprehensive Endpoint Discovery test suite at webmention.rocks was invaluable in the development of this Ruby gem.

webmention-endpoint-ruby is written and maintained by Jason Garber.

webmention-endpoint-ruby is freely available under the MIT License. Use it, learn from it, fork it, improve it, change it, tailor it to your needs.