Embiggen

A Ruby library to expand shortened URLs.

Current version: 1.5.0
Supported Ruby versions: >= 2.7

Installation

gem install embiggen -v '~> 1.5'

Or, in your Gemfile:

gem 'embiggen', '~> 1.5'

Usage

require 'embiggen'

# Basic usage
Embiggen::URI('https://youtu.be/dQw4w9WgXcQ').expand
#=> #<URI::HTTPS https://www.youtube.com/watch?v=dQw4w9WgXcQ&feature=youtu.be>

# Longer-form usage
uri = Embiggen::URI.new(URI('https://youtu.be/dQw4w9WgXcQ'))
uri.shortened?
#=> true
uri.expand
#=> #<URI::HTTPS https://www.youtube.com/watch?v=dQw4w9WgXcQ&feature=youtu.be>

# Gracefully deals with unshortened URIs
uri = Embiggen::URI('http://www.altmetric.com')
uri.shortened?
#=> false
uri.expand
#=> #<URI::HTTP http://www.altmetric.com>

# Raises errors with bad shortened URIs
Embiggen::URI('http://bit.ly/bad').expand
#=> TooManyRedirects: http://bit.ly/bad redirected too many times
# or...
#=> BadShortenedURI: following http://bit.ly/bad did not redirect

# Optionally specify a timeout in seconds for expansion (default is 1)
Embiggen::URI('https://youtu.be/dQw4w9WgXcQ').expand(:timeout => 5)

# Optionally specify a number of redirects to follow (default is 5)
Embiggen::URI('https://youtu.be/dQw4w9WgXcQ').expand(:redirects => 2)

# Override the default configuration for all expansions and add your own
# shorteners
Embiggen.configure do |config|
  config.timeout = 5
  config.redirects = 2
  config.shorteners += %w(myshorten.er anoth.er)
end

Shorteners

Embiggen ships with a default list of URL shortening service domains (c.f. Acknowledgements) in shorteners.txt but as it is likely to be outdated and incomplete, you are strongly encouraged to supply your own via Embiggen.configure.

The list of shorteners is an object that responds to include? and will be passed a URI. By default, Embiggen ships with a ShortenerList class which takes a list of string domains and will return true if given a URI with a matching host.

You can supply your own values and logic like so:

Embiggen.configure do |config|
  config.shorteners = Embiggen::ShortenerList.new(%w(myshorten.er anoth.er))
  # or load from a file...
  config.shorteners = Embiggen::ShortenerList.new(File.readlines('shorteners.txt').map(&:chomp))
end

# Use the Bitly API to only expand URIs on Bitly Pro domains
require 'bitly'
require 'forwardable'

class BitlyDomains
  extend Forwardable
  attr_reader :client
  def_delegator :client, :pro?, :include?

  def initialize(client)
    @client = client
  end
end

Bitly.use_api_version_3
Bitly.configure do |config|
  config.api_version = 3
  config.access_token = ENV.fetch('BITLY_ACCESS_TOKEN')
end

Embiggen.configure do |config|
  config.shorteners = BitlyDomains.new(Bitly.client)
end

API Documentation

`Embiggen::URI`

uri = Embiggen::URI('https://youtu.be/dQw4w9WgXcQ')
uri = Embiggen::URI(URI('https://youtu.be/dQw4w9WgXcQ'))

Return a new Embiggen::URI instance which can be expanded and asked whether it is shortened or not.

Takes instances of Ruby's URI or anything with a string representation (through to_s) that can be parsed as a valid URI.

`Embiggen::URI#expand`

Embiggen::URI('https://youtu.be/dQw4w9WgXcQ').expand
#=> #<URI::HTTPS https://www.youtube.com/watch?v=dQw4w9WgXcQ&feature=youtu.be>

Embiggen::URI('http://www.altmetric.com/').expand
#=> #<URI::HTTP http://www.altmetric.com/>

Embiggen::URI('https://youtu.be/dQw4w9WgXcQ').expand(:timeout => 5)
Embiggen::URI('https://youtu.be/dQw4w9WgXcQ').expand(:redirects => 2)

Expand the given URI, returning the full version as a URI if it is shortened or the original if it is not. Can raise the following exceptions during expansion:

Embiggen::TooManyRedirects: when a URI redirects more than the configured number of times;
Embiggen::BadShortenedURI: when a URI appears to be shortened but following it does not result in a redirect;
Embiggen::NetworkError: when an error occurs during expansion (e.g. a network timeout, connection reset, unreachable host, etc.).

All of the above inherit from Embiggen::Error and have a uri method for determining the problematic URI.

Takes an optional hash of options for expansion:

:timeout: overrides the default timeout for following redirects;
:redirects: overrides the default number of redirects to follow.

Uses a whitelist of shortening domains (as configured through Embiggen.configure) to determine whether a URI is shortened or not. Be sure to configure this to suit your needs.

`Embiggen::URI#shortened?`

Embiggen::URI('https://youtu.be/dQw4w9WgXcQ').shortened?
#=> true

Embiggen::URI('http://www.altmetric.com').shortened?
#=> false

Return true if the URI appears to be shortened. Uses the configured whitelist of shorteners, c.f. Shorteners.

`Embiggen.configure`

Embiggen.configure do |config|
  config.timeout = 5
  config.redirects = 2
  config.shorteners += %w(myshorten.er anoth.er)
end

Override the following settings:

timeout: the default timeout for following any redirects (can be overridden by passing options to Embiggen::URI#expand);
redirects: the default number of redirects to follow (can be overridden by passing options to Embiggen::URI#expand);
shorteners: the list of domains of shortening services, c.f. Shorteners.

Acknowledgements

The extraction of shorteners.txt and performance improvements to the shortener list were contributed by Avner Cohen;
The default list of shorteners includes:
- LongURL.org's curated list
- Bit.do's curated list
- Hongkiat's curated list
- A list of branded Bitly domains collected by Altmetric

License

Distributed under the MIT License.

altmetric / embiggen

readme