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.