README.md

token-endpoint-ruby

⚠️ Deprecation Notice (2019-04-24) ⚠️ 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 token endpoint for use with Micropub and IndieAuth clients.

Key Features

• Uses the same discovery algorithm outlined in Section 5.3 of the W3C's Micropub Recommendation.
• Supports Ruby 2.4 and newer.

Getting Started

Before installing and using token-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.

token-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.

Installation

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

source 'https://rubygems.org'

gem 'token-endpoint'

…and hop over to your command prompt and run…

$ bundle install

Usage

Basic Usage

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

require 'token-endpoint'

endpoint = TokenEndpoint.discover('https://aaronparecki.com')

puts endpoint # returns String: 'https://aaronparecki.com/auth'

This example will search https://aaronparecki.com for a valid token endpoint using the same rules described in the W3C's Micropub Recommendation. In this case, the program returns a string: https://aaronparecki.com/auth/token.

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

require 'token-endpoint'

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

puts endpoint.nil? # returns Boolean: true

Advanced Usage

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

require 'token-endpoint'

client = TokenEndpoint::Client.new('https://aaronparecki.com')

puts client.response # returns HTTP::Response
puts client.endpoint # returns String: 'https://aaronparecki.com/auth/token'

Exception Handling

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

From jgarber623/absolutely and sporkmonger/addressable:

• TokenEndpoint::InvalidURIError

From httprb/http:

• TokenEndpoint::ConnectionError
• TokenEndpoint::TimeoutError
• TokenEndpoint::TooManyRedirectsError

Contributing

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

Acknowledgments

token-endpoint-ruby wouldn't exist without Micropub and the hard work put in by everyone involved in the IndieWeb movement.

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

License

token-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.