README.rdoc @@ -1 +1,3 @@ -pkg \ No newline at end of file +pkg +.DS_Store +rdoc .gitignore @@ -1,3 +1,7 @@ +# Contains the complete public API for APICache. +# +# Uses Cache and API classes to determine the correct behaviour. +# class APICache class NotAvailableError < RuntimeError; end class Invalid < RuntimeError; end @@ -10,6 +14,7 @@ class APICache end # Initializes the cache + # def self.start(store = nil, logger = nil) APICache.logger = logger || APICache::Logger.new APICache::Cache.store = (store || APICache::MemcacheStore).new lib/api_cache.rb @@ -1,25 +1,27 @@ -class APICache::AbstractStore - def initialize - raise "Method not implemented. Called abstract class." - end - - # Set value. Returns true if success. - def set(key, value) - raise "Method not implemented. Called abstract class." - end - - # Get value. - def get(key) - raise "Method not implemented. Called abstract class." - end - - # Does a given key exist in the cache? - def exists?(key) - raise "Method not implemented. Called abstract class." - end - - # Has a given time passed since the key was set? - def expired?(key, timeout) - raise "Method not implemented. Called abstract class." +class APICache + class AbstractStore + def initialize + raise "Method not implemented. Called abstract class." + end + + # Set value. Returns true if success. + def set(key, value) + raise "Method not implemented. Called abstract class." + end + + # Get value. + def get(key) + raise "Method not implemented. Called abstract class." + end + + # Does a given key exist in the cache? + def exists?(key) + raise "Method not implemented. Called abstract class." + end + + # Has a given time passed since the key was set? + def expired?(key, timeout) + raise "Method not implemented. Called abstract class." + end end end lib/api_cache/abstract_store.rb @@ -1,92 +1,95 @@ require 'net/http' -# This class wraps up querying the API and remembers when each API was -# last queried in case there is a limit to the number that can be made. -# -class APICache::API - @query_times = {} - class << self - attr_reader :query_times - end - - # Takes the following options - # - # period:: Maximum frequency to call the API - # timeout:: Timeout when calling api (either to the proviced url or - # excecuting the passed block) - # block:: If passed then the block is excecuted instead of HTTP GET against - # the provided key +class APICache + # Wraps up querying the API. # - def initialize(key, options, &block) - @key, @block = key, block - @timeout = options[:timeout] - @period = options[:period] - end - - # Checks whether the API can be queried (i.e. whether :period has passed - # since the last query to the API). - # - # If :period is 0 then there is no limit on how frequently queries can - # be made to the API. + # Ensures that the API is not called more frequently than every +period+ seconds, and times out API requests after +timeout+ seconds. # - def queryable? - if query_times[@key] - if Time.now - query_times[@key] > @period - APICache.logger.log "Queryable: true - retry_time has passed" - true + class API + @query_times = {} + class << self + attr_reader :query_times + end + + # Takes the following options + # + # period:: Maximum frequency to call the API + # timeout:: Timeout when calling api (either to the proviced url or + # excecuting the passed block) + # block:: If passed then the block is excecuted instead of HTTP GET + # against the provided key + # + def initialize(key, options, &block) + @key, @block = key, block + @timeout = options[:timeout] + @period = options[:period] + end + + # Checks whether the API can be queried (i.e. whether :period has passed + # since the last query to the API). + # + # If :period is 0 then there is no limit on how frequently queries can + # be made to the API. + # + def queryable? + if query_times[@key] + if Time.now - query_times[@key] > @period + APICache.logger.log "Queryable: true - retry_time has passed" + true + else + APICache.logger.log "Queryable: false - queried too recently" + false + end else - APICache.logger.log "Queryable: false - queried too recently" - false + APICache.logger.log "Queryable: true - never used API before" + true end - else - APICache.logger.log "Queryable: true - never used API before" - true end - end - # Fetch data from the API. - # - # If no block is given then the key is assumed to be a URL and which will - # be queried expecting a 200 response. Otherwise the return value of the - # block will be used. - # - # If the block is unable to fetch the value from the API it should raise - # APICache::Invalid. - # - def get - APICache.logger.log "Fetching data from the API" - query_times[@key] = Time.now - Timeout::timeout(@timeout) do - if @block - # This should raise APICache::Invalid if it is not correct - @block.call - else - get_key_via_http + # Fetch data from the API. + # + # If no block is given then the key is assumed to be a URL and which will + # be queried expecting a 200 response. Otherwise the return value of the + # block will be used. + # + # If the block is unable to fetch the value from the API it should raise + # APICache::Invalid. + # + def get + APICache.logger.log "Fetching data from the API" + query_times[@key] = Time.now + Timeout::timeout(@timeout) do + if @block + # This should raise APICache::Invalid if it is not correct + @block.call + else + get_key_via_http + end end + rescue Timeout::Error, APICache::Invalid => e + raise APICache::CannotFetch, e.message end - rescue Timeout::Error, APICache::Invalid => e - raise APICache::CannotFetch, e.message - end - private + private + + def get_key_via_http + response = redirecting_get(@key) + case response + when Net::HTTPSuccess + # 2xx response code + response.body + else + raise APICache::Invalid, "Invalid http response: #{response.code}" + end + end - def get_key_via_http - response = redirecting_get(@key) - case response - when Net::HTTPSuccess - # 2xx response code - response.body - else - raise APICache::Invalid, "Invalid http response: #{response.code}" + def redirecting_get(url) + r = Net::HTTP.get_response(URI.parse(url)) + r.header['location'] ? redirecting_get(r.header['location']) : r end - end - def redirecting_get(url) - r = Net::HTTP.get_response(URI.parse(url)) - r.header['location'] ? redirecting_get(r.header['location']) : r - end - - def query_times - self.class.query_times + def query_times + self.class.query_times + end end end lib/api_cache/api.rb @@ -1,56 +1,58 @@ require 'digest/md5' -# Cache performs calculations relating to the status of items stored in the -# cache and delegates storage to the various cache stores. -# -class APICache::Cache - class << self - attr_accessor :store - end +class APICache + # Cache performs calculations relating to the status of items stored in the + # cache and delegates storage to the various cache stores. + # + class Cache + class << self + attr_accessor :store + end - def initialize(key, options) - @key = key - @cache = options[:cache] - @valid = options[:valid] - end + def initialize(key, options) + @key = key + @cache = options[:cache] + @valid = options[:valid] + end - # Returns one of the following options depending on the state of the key: - # - # * :current (key has been set recently) - # * :refetch (data should be refetched but is still available for use) - # * :invalid (data is too old to be useful) - # * :missing (do data for this key) - # - def state - if store.exists?(hash) - if !store.expired?(hash, @cache) - :current - elsif (@valid == :forever) || !store.expired?(hash, @valid) - :refetch + # Returns one of the following options depending on the state of the key: + # + # * :current (key has been set recently) + # * :refetch (data should be refetched but is still available for use) + # * :invalid (data is too old to be useful) + # * :missing (do data for this key) + # + def state + if store.exists?(hash) + if !store.expired?(hash, @cache) + :current + elsif (@valid == :forever) || !store.expired?(hash, @valid) + :refetch + else + :invalid + end else - :invalid + :missing end - else - :missing end - end - def get - store.get(hash) - end + def get + store.get(hash) + end - def set(value) - store.set(hash, value) - true - end - - private - - def hash - Digest::MD5.hexdigest @key - end - - def store - self.class.store + def set(value) + store.set(hash, value) + true + end + + private + + def hash + Digest::MD5.hexdigest @key + end + + def store + self.class.store + end end end lib/api_cache/cache.rb @@ -1,9 +1,11 @@ -class APICache::Logger - def initialize - - end - - def log(message) - # puts "APICache: #{message}" +class APICache + class Logger + def initialize + + end + + def log(message) + # puts "APICache: #{message}" + end end end lib/api_cache/logger.rb @@ -1,54 +1,56 @@ require 'memcache' -class APICache::MemcacheStore < APICache::AbstractStore - class NotReady < Exception #:nodoc: - def initialize - super("Memcache server is not ready") +class APICache + class MemcacheStore < APICache::AbstractStore + class NotReady < Exception #:nodoc: + def initialize + super("Memcache server is not ready") + end + end + + class NotDefined < Exception #:nodoc: + def initialize + super("Memcache is not defined") + end end - end - class NotDefined < Exception #:nodoc: def initialize - super("Memcache is not defined") + APICache.logger.log "Using memcached store" + namespace = 'api_cache' + host = '127.0.0.1:11211' + @memcache = MemCache.new(host, {:namespace => namespace}) + raise NotReady unless @memcache.active? + true + # rescue NameError + # raise NotDefined end - end - - def initialize - APICache.logger.log "Using memcached store" - namespace = 'api_cache' - host = '127.0.0.1:11211' - @memcache = MemCache.new(host, {:namespace => namespace}) - raise NotReady unless @memcache.active? - true - # rescue NameError - # raise NotDefined - end - - def set(key, data) - @memcache.set(key, data) - @memcache.set("#{key}_created_at", Time.now) - APICache.logger.log("cache: set (#{key})") - true - end - - def get(key) - data = @memcache.get(key) - APICache.logger.log("cache: #{data.nil? ? "miss" : "hit"} (#{key})") - data - end - - def exists?(key) - # TODO: inefficient - is there a better way? - !@memcache.get(key).nil? - end - - def expired?(key, timeout) - Time.now - created(key) > timeout - end - - private - def created(key) - @memcache.get("#{key}_created_at") + def set(key, data) + @memcache.set(key, data) + @memcache.set("#{key}_created_at", Time.now) + APICache.logger.log("cache: set (#{key})") + true + end + + def get(key) + data = @memcache.get(key) + APICache.logger.log("cache: #{data.nil? ? "miss" : "hit"} (#{key})") + data + end + + def exists?(key) + # TODO: inefficient - is there a better way? + !@memcache.get(key).nil? + end + + def expired?(key, timeout) + Time.now - created(key) > timeout + end + + private + + def created(key) + @memcache.get("#{key}_created_at") + end end end lib/api_cache/memcache_store.rb @@ -1,33 +1,35 @@ -class APICache::MemoryStore < APICache::AbstractStore - def initialize - APICache.logger.log "Using memory store" - @cache = {} - true - end +class APICache + class MemoryStore < APICache::AbstractStore + def initialize + APICache.logger.log "Using memory store" + @cache = {} + true + end - def set(key, value) - APICache.logger.log("cache: set (#{key})") - @cache[key] = [Time.now, value] - true - end + def set(key, value) + APICache.logger.log("cache: set (#{key})") + @cache[key] = [Time.now, value] + true + end - def get(key) - data = @cache[key][1] - APICache.logger.log("cache: #{data.nil? ? "miss" : "hit"} (#{key})") - data - end + def get(key) + data = @cache[key][1] + APICache.logger.log("cache: #{data.nil? ? "miss" : "hit"} (#{key})") + data + end - def exists?(key) - !@cache[key].nil? - end - - def expired?(key, timeout) - Time.now - created(key) > timeout - end + def exists?(key) + !@cache[key].nil? + end + + def expired?(key, timeout) + Time.now - created(key) > timeout + end - private + private - def created(key) - @cache[key][0] + def created(key) + @cache[key][0] + end end end lib/api_cache/memory_store.rb README.markdown d320719375002784e87713f8c819f0c792b5b9ea Martyn Loughran me@mloughran.com http://github.com/mloughran/api_cache/commit/bdb80b368f8b28381f4b829145692ded9bba5404 bdb80b368f8b28381f4b829145692ded9bba5404 2009-05-04T13:44:29-07:00 2009-05-04T13:38:03-07:00 Fixed and improved rdoc documentation * Changed the readme file to be rdoc formatted * For some reason APICache::Cache makes RDoc think APICache is a module... 62c279a618ba1157911b0d0b79baa4537e1fca14 Martyn Loughran me@mloughran.com