Hassle-free caching for HTTP download.
$ gem install webcache
Or with bundler:
gem 'webcache'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, and
the permissions of the cached files can be specified if needed.
You can change these settings on initialization:
cache = WebCache.new dir: 'tmp/my_cache', life: '3d', permissions: 0o640
response = cache.get 'http://example.com'Or later:
cache = WebCache.new
cache.dir = 'tmp/my_cache'
cache.life = '4h'
cache.permissions = 0o640
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 daysUse 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'
# => trueUse 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'
# => trueUse 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'
# => falseUse flush to delete the entire cache directory:
cache = WebCache.new
cache.flushUse force: true to force download even if the object is cached:
cache = WebCache.new
response = cache.get 'http://example.com', force: trueTo configure an authentication header, use the auth option. Similarly to
the other options, this can be set directly on the static class, on instance
initialization, or later on the instance:
cache = WebCache.new auth: '...'
cache.get 'http://example.com' # authenticated
cache = WebCache.new
cache.auth = '...'
cache.get 'http://example.com' # authenticated
WebCache.auth = '...'
WebCache.get 'http://example.com' # authenticatedFor basic authentication, provide a hash:
cache = WebCache.new auth: { user: 'user', pass: 's3cr3t' }For other authentication headers, simply provide the header string:
cache = WebCache.new auth: "Bearer t0k3n"The response object holds these properties:
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.
In case of an error, this contains the error message, nil otherwise.
Contains the HTTP code, or nil if there was a non-HTTP error.
A convenience method, returns true if error is empty.
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.
If you experience any issue, have a question or a suggestion, or if you wish to contribute, feel free to open an issue.