Skip to content
Hassle-free caching for HTTP download with ruby
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
lib
spec
.gitignore
.rspec
.travis.yml
Gemfile
LICENSE
README.md
Runfile
webcache.gemspec

README.md

WebCache

Gem Version Build Status Maintainability


Hassle-free caching for HTTP download.


Install

$ gem install webcache

Or with bundler:

gem 'webcache'

Usage

WebCache can be used both as an instance, and as a static class.

require 'webcache'

# Instance
cache = WebCache.new life: '3h'
response = cache.get 'http://example.com'

# Static
WebCache.life = '3h'
WebCache.get 'http://example.com'

The design intention is to provide both a globally available singleton WebCache object, as well as multiple caching instances, with different settings - depending on the use case.

Note that the examples in this README are all using the instance syntax, but all methods are also available statically.

This is the basic usage pattern:

require 'webcache'
cache = WebCache.new
response = cache.get 'http://example.com'
puts response             # => "<html>...</html>"
puts response.content     # => same as above
puts response.to_s        # => same as above
puts response.error       # => nil
puts response.base_uri    # => "http://example.com/"

By default, the cached objects are stored in the ./cache directory, and expire after 60 minutes. The cache directory will be created as needed.

You can change these settings on initialization:

cache = WebCache.new dir: 'tmp/my_cache', life: '3d'
response = cache.get 'http://example.com'

Or later:

cache = WebCache.new
cache.dir = 'tmp/my_cache'
cache.life = '4h'
response = cache.get 'http://example.com'

The life property accepts any of these formats:

cache.life = 10     # 10 seconds
cache.life = '20s'  # 20 seconds
cache.life = '10m'  # 10 minutes
cache.life = '10h'  # 10 hours
cache.life = '10d'  # 10 days

Use the cached? method to check if a URL is cached:

cache = WebCache.new
cache.cached? 'http://example.com'
# => false

response = cache.get 'http://example.com'
cache.cached? 'http://example.com'
# => true

Use enable and disable to toggle caching on and off:

cache = WebCache.new
cache.disable
cache.enabled? 
# => false

response = cache.get 'http://example.com'
cache.cached? 'http://example.com'
# => false

cache.enable
response = cache.get 'http://example.com'
cache.cached? 'http://example.com'
# => true

Use clear url to remove a cached object if it exists:

cache = WebCache.new
response = cache.get 'http://example.com'
cache.cached? 'http://example.com'
# => true

cache.clear 'http://example.com'
cache.cached? 'http://example.com'
# => false

Use flush to delete the entire cache directory:

cache = WebCache.new
cache.flush

Use force: true to force download even if the object is cached:

cache = WebCache.new
response = cache.get 'http://example.com', force: true

Basic Authentication and Additional Options

WebCache uses Ruby's Open URI to download. If you wish to modify the options it uses, simply update the options hash.

For example, to use HTTP basic authentication, use something like this:

cache = WebCache.new
cache.options[:http_basic_authentication] = ["user", "pass123!"]
response = cache.get 'http://example.com'

Response Object

The response object holds these properties:

response.content

Contains the HTML content. In case of an error, this will include the error message. The #to_s method of the response object also returns the same content.

response.error

In case of an error, this contains the error message, nil otherwise.

response.base_uri

Contains the actual address of the page. This is useful when the request is redirected. For example, http://example.com will set the base_uri to http://example.com/ (note the trailing slash).


For a similar gem that provides general purpose caching, see the Lightly gem

You can’t perform that action at this time.