indieweb-endpoints-ruby

A Ruby gem for discovering a URL's IndieAuth, Micropub, Microsub, and Webmention endpoints.

Key Features

• Compliant with Section 4.1 and Section 4.2.2 of the W3C's IndieAuth Working Group Note, Section 5.3 of the W3C's Micropub Recommendation, and Section 3.1.2 of the W3C's Webmention Recommendation.
• Passes all Endpoint Discovery tests on webmention.rocks.
• Supports Ruby 3.0 and newer.

Getting Started

Before installing and using indieweb-endpoints-ruby, you'll want to have Ruby 3.0 (or newer) installed. Using a Ruby version managment tool like rbenv, chruby, or rvm is recommended.

indieweb-endpoints-ruby is developed using Ruby 3.3.0 and is tested against additional Ruby versions using GitHub Actions.

Installation

Add indieweb-endpoints-ruby to your project's Gemfile and run bundle install:

source "https://rubygems.org"

gem "indieweb-endpoints"

Usage

Basic Usage

With indieweb-endpoints-ruby added to your project's Gemfile and installed, you may discover a URL's IndieWeb-relevant endpoints by doing:

require "indieweb/endpoints"

IndieWeb::Endpoints.get("https://aaronparecki.com")
#=> { authorization_endpoint: "https://aaronparecki.com/auth", "indieauth-metadata": "https://aaronparecki.com/.well-known/oauth-authorization-server", micropub: "https://aaronparecki.com/micropub", microsub: "https://aperture.p3k.io/microsub/1", redirect_uri: nil, token_endpoint: "https://aaronparecki.com/auth/token", webmention: "https://webmention.io/aaronpk/webmention" }

This example will search https://aaronparecki.com for valid IndieAuth, Micropub, and Webmention endpoints and return a Hash of results. Each key in the returned Hash will have a value of either a String representing a URL or nil. The redirect_uri key's value will be either an Array or nil since a given URL may register multiple callback URLs.

Advanced Usage

Should the need arise, you may work with the IndieWeb::Endpoints::Client class:

require "indieweb/endpoints"

client = IndieWeb::Endpoints::Client.new("https://aaronparecki.com")
#=> #<IndieWeb::Endpoints::Client uri: "https://aaronparecki.com">

client.response
#=> #<HTTP::Response/1.1 200 OK {…}>

client.endpoints
#=> { authorization_endpoint: "https://aaronparecki.com/auth", micropub: "https://aaronparecki.com/micropub", microsub: "https://aperture.p3k.io/microsub/1", redirect_uri: nil, token_endpoint: "https://aaronparecki.com/auth/token", webmention: "https://webmention.io/aaronpk/webmention" }

Exception Handling

There are several exceptions that may be raised by indieweb-endpoints-ruby's underlying dependencies. These errors are raised as subclasses of IndieWeb::Endpoints::Error (which itself is a subclass of StandardError).

From sporkmonger/addressable:

• IndieWeb::Endpoints::InvalidURIError

From httprb/http:

• IndieWeb::Endpoints::HttpError

From the Ruby Standard Library's OpenSSL::SSL::SSLError:

• IndieWeb::Endpoints::SSLError

Contributing

See CONTRIBUTING.md for more on how to contribute to indieweb-endpoints-ruby. Your help is greatly appreciated!

By contributing to and participating in the development of indieweb-endpoints-ruby, you acknowledge that you have read and agree to the IndieWeb Code of Conduct.

Acknowledgments

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

indieweb-endpoints-ruby is written and maintained by Jason Garber.

License

indieweb-endpoints-ruby is freely available under the MIT License.