indieweb / Webmention Client Ruby
Programming Languages
Labels
Projects that are alternatives of or similar to Webmention Client Ruby
webmention-client-ruby
A Ruby gem for sending Webmention notifications.
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.5 (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.5.8 and is additionally tested against Ruby 2.6 and 2.7 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::ConnectionErrorWebmention::Client::TimeoutErrorWebmention::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.