embiggen 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6af561209a387ec502e579b6917f6bf3984fd7c3
-  data.tar.gz: 8a53fba0f9b2879df685ddfc8e82647b6c51411b
+  metadata.gz: 47bfb5ace689946c57eb0595e0aa5c9992a6fe70
+  data.tar.gz: 7a1d1441cf49e8b785c9c63ed9f07899d08d0283
 SHA512:
-  metadata.gz: ae5a3f54a1c89cf969d8a0d292c23163becc1a31ab8c45bb218b7b93f998a9b838d0e457dd37bd03d05cd4954becbd7580d37ea95894e157d472c117e1ca9462
-  data.tar.gz: c858db7c641918040855a9ede16b3c3ccee88840f860667860172d50629e81324d0c2356be4f787ace159e129987cf6d8b7c12ccfd5c6c382b6794924ecc3d86
+  metadata.gz: ac5abe95ea7a88f6e93d8815b91c963362fe671fbb1334d4b8e104d06bac61cf846ce2fb7ee9bdf6a73a8d9b33e1c26a417b63ef4d6d228097aa9ee8136aeb64
+  data.tar.gz: 40a02c961adffd16f0f06b4d0851817ba8fc9f21ed08f3383831118e2ee1a101a91fd574e9b60751e99452b9000be6fd2ac81b3eeacb2d4d34108f97c2f444a7

data/README.md

@@ -2,7 +2,23 @@
 
 A Ruby library to expand shortened URLs.
 
+**Current version:** 0.1.1  
+**Supported Ruby versions:** 1.8.7, 1.9.2, 1.9.3, 2.0, 2.1, 2.2
+
+## Installation
+
+```
+gem install embiggen -v '~> 0.1'
+```
+
+Or, in your `Gemfile`:
+
+```ruby
+gem 'embiggen', '~> 0.1'
+```
+
 ## Usage
+
 ```ruby
 require 'embiggen'
 
@@ -45,9 +61,125 @@ Embiggen.configure do |config|
 end
 ```
 
+## Shorteners
+
+Embiggen ships with a default list of URL shortening service domains (c.f.
+[Acknowledgements](#acknowledgements)) but as it is likely to be outdated and
+incomplete, you are strongly encouraged to supply your own via
+`Embiggen.configure`:
+
+```ruby
+Embiggen.configure do |config|
+  config.shorteners = %w(myshorten.er anoth.er)
+  # or load from a file...
+  config.shorteners = File.readlines('shorteners.txt').map(&:chomp)
+end
+```
+
+## API Documentation
+
+### `Embiggen::URI`
+
+```ruby
+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`][URI] or
+anything with a string representation (through `to_s`) that can be parsed as a
+valid URI.
+
+### `Embiggen::URI#expand`
+
+```ruby
+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`][URI] if it is
+shortened or the original if it cannot be expanded. Will not raise any
+exceptions thrown during expansion (e.g. timeouts, network errors, invalid
+return URIs); see `expand!` for an alternative.
+
+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](#shorteners).
+
+### `Embiggen::URI#expand!`
+
+```ruby
+Embiggen::URI('https://youtu.be/dQw4w9WgXcQ').expand!
+#=> #<URI:HTTPS https://www.youtube.com/watch?v=dQw4w9WgXcQ&feature=youtu.be>
+
+Embiggen::URI('http://bit.ly/some-bad-link').expand!
+# TooManyRedirects: http://bit.ly/some-bad-link redirected too many times
+```
+
+Expand the given URI as with `Embiggen::URI#expand` but don't suppress any
+exceptions raised during expansion (including timeouts, network errors,
+invalid return URIs, too many redirects or no redirects whatsoever).
+
+Takes the same options as `Embiggen::URI#expand`.
+
+Two Embiggen-specific errors (both inheriting from `Embiggen::Error`) can be
+raised:
+
+* `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::URI#shortened?`
+
+```ruby
+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](#shorteners).
+
+### `Embiggen.configure`
+
+```ruby
+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` or
+  `Embiggen::URI#expand!`);
+* `redirects`: the default number of redirects to follow (can be overridden by
+  passing options to `Embiggen::URI#expand` or `Embiggen::URI#expand!`);
+* `shorteners`: the list of domains of shortening services, c.f.
+  [Shorteners](#shorteners).
+
 ## Acknowledgements
 
-* The list of shorteners comes from [LongURL.org's curated
+* The default list of shorteners comes from [LongURL.org's curated
   list](http://longurl.org/services).
 
 ## License
@@ -55,3 +187,5 @@ end
 Copyright © 2015 Altmetric LLP
 
 Distributed under the MIT License.
+
+[URI]: http://ruby-doc.org/stdlib/libdoc/uri/rdoc/URI.html

data/lib/embiggen/uri.rb

@@ -13,7 +13,7 @@ module Embiggen
       expand!(request_options)
     rescue TooManyRedirects => error
       error.uri
-    rescue Error, ::Timeout::Error, ::Errno::ECONNRESET
+    rescue StandardError, ::Timeout::Error
       uri
     end
 

data/spec/embiggen/uri_spec.rb

@@ -63,6 +63,20 @@ module Embiggen
         expect(uri.expand).to eq(URI('http://bit.ly/bad'))
       end
 
+      it 'does not expand URIs whose host is unreachable' do
+        stub_request(:head, 'http://bit.ly/bad').to_raise(Errno::EHOSTUNREACH)
+        uri = described_class.new(URI('http://bit.ly/bad'))
+
+        expect(uri.expand).to eq(URI('http://bit.ly/bad'))
+      end
+
+      it 'does not expand URIs whose name or service is not known' do
+        stub_request(:head, 'http://bit.ly/bad').to_raise(SocketError)
+        uri = described_class.new(URI('http://bit.ly/bad'))
+
+        expect(uri.expand).to eq(URI('http://bit.ly/bad'))
+      end
+
       it 'takes an optional timeout' do
         stub_request(:head, 'http://bit.ly/bad').to_timeout
         uri = described_class.new(URI('http://bit.ly/bad'))

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: embiggen
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Paul Mucur
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-14 00:00:00.000000000 Z
+date: 2015-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec