WellKnown

A Ruby gem client for discovering and fetching well-known URLs (RFC 8615) from any domain. Includes the full IANA well-known URI registry.

Features

• Pure Ruby - Works with any Ruby framework or plain scripts
• Client - Fetch /.well-known/{suffix} from any domain
• Registry - Full IANA well-known URI registry (96 entries)
• Lookup - Check if a URI suffix is IANA-registered

Installation

Add this line to your application's Gemfile:

gem 'well_known'

And then execute:

bundle install

Or install it yourself as:

gem install well_known

Usage

Client

Fetch well-known URLs from any domain:

require 'well_known'

client = WellKnown::Client.new

# Fetch nodeinfo
response = client.fetch 'mastodon.social', 'nodeinfo'
puts response.status       # => 200
puts response.body         # => '{"links":[...]}'
puts response.content_type # => 'application/json'

# Fetch host-meta
response = client.fetch 'mastodon.social', 'host-meta'
puts response.content_type # => 'application/xrd+xml'

# Fetch security.txt
response = client.fetch 'example.com', 'security.txt'
puts response.body # => 'Contact: security@example.com'

Build URLs Without Fetching

client = WellKnown::Client.new

client.url_for 'mastodon.social', 'nodeinfo'
# => 'https://mastodon.social/.well-known/nodeinfo'

client.url_for 'example.com', 'webfinger'
# => 'https://example.com/.well-known/webfinger'

Client Options

# Custom timeout (default: 10 seconds)
client = WellKnown::Client.new timeout: 5

# Disable redirect following (default: true)
client = WellKnown::Client.new follow_redirects: false

Convenience Method

client   = WellKnown.client
response = client.fetch 'example.com', 'nodeinfo'

Registry

Check the IANA well-known URI registry:

require 'well_known'

# Check if a suffix is registered
WellKnown::Registry.registered? 'nodeinfo'  # => true
WellKnown::Registry.registered? 'webfinger' # => true
WellKnown::Registry.registered? 'made-up'   # => false

# Get details for a registered suffix
WellKnown::Registry.find 'nodeinfo'
# => { change_controller: 'NodeInfo Developer Community', reference: 'NodeInfo Diaspora' }

WellKnown::Registry.find 'webfinger'
# => { change_controller: 'IETF', reference: 'RFC 7033' }

# List all registered suffixes
WellKnown::Registry.suffixes
# => ['acme-challenge', 'agent-card.json', 'amphtml', ...]

# Get the full registry
WellKnown::Registry.entries
# => { 'acme-challenge' => { ... }, 'agent-card.json' => { ... }, ... }

Response Object

The WellKnown::Response object wraps the HTTP response:

response = client.fetch 'example.com', 'nodeinfo'

response.body         # => String - the response body
response.status       # => Integer - HTTP status code (e.g., 200)
response.content_type # => String - MIME type (e.g., 'application/json')
response.headers      # => Hash - all response headers
response.success?     # => Boolean - true if status is 2xx

Error Handling

begin
  response = client.fetch 'example.com', 'nodeinfo'
rescue WellKnown::FetchError => e
  puts "Could not fetch: #{e.message}"
rescue WellKnown::Error => e
  puts "WellKnown error: #{e.message}"
end

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

Running Tests

bundle exec rspec

Running RuboCop

bundle exec rubocop

Running All Checks

bundle exec rake

Contributing

Bug reports and pull requests are welcome on GitHub at the https://github.com/xoengineering/well_known repo.

License

The gem is available as open source under the terms of the MIT License.

References

• RFC 8615 - Well-Known URIs
• IANA Well-Known URI Registry