Adding discovery document caching to Service interface

lib/google/api_client/service.rb

@@ -18,6 +18,7 @@ require 'google/api_client/service/resource'
 require 'google/api_client/service/request'
 require 'google/api_client/service/result'
 require 'google/api_client/service/batch'
+require 'google/api_client/service/simple_file_store'
 
 module Google
   class APIClient
@@ -33,6 +34,8 @@ module Google
       include Google::APIClient::Service::StubGenerator
       extend Forwardable
 
+      DEFAULT_CACHE_FILE = 'discovery.cache'
+
       # Cache for discovered APIs.
       @@discovered = {}
 
@@ -81,6 +84,10 @@ module Google
       #   `true` if gzip enabled, `false` otherwise.
       # @option options [Faraday::Connection] :connection
       #   A custom connection to be used for all requests.
+      # @option options [ActiveSupport::Cache::Store, :default] :discovery_cache
+      #   A cache store to place the discovery documents for loaded APIs.
+      #   Avoids unnecessary roundtrips to the discovery service.
+      #   :default loads the default local file cache store.
       def initialize(api_name, api_version, options = {})
         @api_name = api_name.to_s
         if api_version.nil?
@@ -109,11 +116,32 @@ module Google
 
         @options = options
 
-        # Cache discovered APIs in memory.
+        # Initialize cache store. Default to SimpleFileStore if :cache_store
+        # is not provided and we have write permissions.
+        if options.include? :cache_store
+          @cache_store = options[:cache_store]
+        else
+          cache_exists = File.exist?(DEFAULT_CACHE_FILE)
+          if (cache_exists && File.writable?(DEFAULT_CACHE_FILE)) ||
+             (!cache_exists && File.writable?(Dir.pwd))
+            @cache_store = Google::APIClient::Service::SimpleFileStore.new(
+              DEFAULT_CACHE_FILE)
+          end
+        end
+
+        # Attempt to read API definition from memory cache.
         # Not thread-safe, but the worst that can happen is a cache miss.
         unless @api = @@discovered[[api_name, api_version]]
-          @@discovered[[api_name, api_version]] = @api = @client.discovered_api(
+          # Attempt to read API definition from cache store, if there is one.
-            api_name, api_version)
+          # If there's a miss or no cache store, call discovery service.
+          if !@cache_store.nil?
+            @api = @cache_store.fetch("%s/%s" % [api_name, api_version]) do
+              @client.discovered_api(api_name, api_version)
+            end
+          else
+            @api = @client.discovered_api(api_name, api_version)
+          end
+          @@discovered[[api_name, api_version]] = @api
         end
 
         generate_call_stubs(self, @api)
@@ -151,6 +179,16 @@ module Google
       # @return [Faraday::Connection]
       attr_accessor :connection
 
+      ##
+      # The cache store used for storing discovery documents.
+      # If the user requested :default, use SimpleFileStore with default file
+      # name.
+      #
+      # @return [ActiveSupport::Cache::Store,
+      #          Google::APIClient::Service::SimpleFileStore,
+      #          nil]
+      attr_reader :cache_store
+
       ##
       # Prepares a Google::APIClient::BatchRequest object to make batched calls.
       # @param [Array] calls

lib/google/api_client/service/simple_file_store.rb

@@ -0,0 +1,151 @@
+# Copyright 2013 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Google
+  class APIClient
+    class Service
+
+      # Simple file store to be used in the event no ActiveSupport cache store
+      # is provided. This is not thread-safe, and does not support a number of
+      # features (such as expiration), but it's useful for the simple purpose of
+      # caching discovery documents to disk.
+      # Implements the basic cache methods of ActiveSupport::Cache::Store in a
+      # limited fashion.
+      class SimpleFileStore
+
+        # Creates a new SimpleFileStore.
+        #
+        # @param [String] file_path
+        #   The path to the cache file on disk.
+        # @param [Object] options
+        #   The options to be used with this SimpleFileStore. Not implemented.
+        def initialize(file_path, options = nil)
+          @file_path = file_path.to_s
+        end
+
+        # Returns true if a key exists in the cache.
+        #
+        # @param [String] name
+        #   The name of the key. Will always be converted to a string.
+        # @param [Object] options
+        #   The options to be used with this query. Not implemented.
+        def exist?(name, options = nil)
+          read_file
+          @cache.nil? ? nil : @cache.include?(name.to_s)
+        end
+
+        # Fetches data from the cache and returns it, using the given key.
+        # If the key is missing and no block is passed, returns nil.
+        # If the key is missing and a block is passed, executes the block, sets
+        # the key to its value, and returns it.
+        #
+        # @param [String] name
+        #   The name of the key. Will always be converted to a string.
+        # @param [Object] options
+        #   The options to be used with this query. Not implemented.
+        # @yield [String]
+        #   optional block with the default value if the key is missing
+        def fetch(name, options = nil)
+          read_file
+          if block_given?
+            entry = read(name.to_s, options)
+            if entry.nil?
+              value = yield name.to_s
+              write(name.to_s, value)
+              return value
+            else
+              return entry
+            end
+          else
+            return read(name.to_s, options)
+          end
+        end
+
+        # Fetches data from the cache, using the given key.
+        # Returns nil if the key is missing.
+        #
+        # @param [String] name
+        #   The name of the key. Will always be converted to a string.
+        # @param [Object] options
+        #   The options to be used with this query. Not implemented.
+        def read(name, options = nil)
+          read_file
+          @cache.nil? ? nil : @cache[name.to_s]
+        end
+
+        # Writes the value to the cache, with the key.
+        #
+        # @param [String] name
+        #   The name of the key. Will always be converted to a string.
+        # @param [Object] value
+        #   The value to be written.
+        # @param [Object] options
+        #   The options to be used with this query. Not implemented.
+        def write(name, value, options = nil)
+          read_file
+          @cache = {} if @cache.nil?
+          @cache[name.to_s] = value
+          write_file
+          return nil
+        end
+
+        # Deletes an entry in the cache.
+        # Returns true if an entry is deleted.
+        #
+        # @param [String] name
+        #   The name of the key. Will always be converted to a string.
+        # @param [Object] options
+        #   The options to be used with this query. Not implemented.
+        def delete(name, options = nil)
+          read_file
+          return nil if @cache.nil?
+          if @cache.include? name.to_s
+            @cache.delete name.to_s
+            write_file
+            return true
+          else
+            return nil
+          end
+        end
+
+        protected
+
+        # Read the entire cache file from disk.
+        # Will avoid reading if there have been no changes.
+        def read_file
+          if !File.exists? @file_path
+            @cache = nil
+          else
+            # Check for changes after our last read or write.
+            if @last_change.nil? || File.mtime(@file_path) > @last_change
+              File.open(@file_path) do |file|
+                @cache = Marshal.load(file)
+                @last_change = file.mtime
+              end
+            end
+          end
+          return @cache
+        end
+
+        # Write the entire cache contents to disk.
+        def write_file
+          File.open(@file_path, 'w') do |file|
+            Marshal.dump(@cache, file)
+          end
+          @last_change = File.mtime(@file_path)
+        end
+      end
+    end
+  end
+end

spec/google/api_client/service_spec.rb

@@ -57,7 +57,8 @@ describe Google::APIClient::Service do
         {
           :application_name => APPLICATION_NAME,
           :authenticated => false,
-          :connection => conn
+          :connection => conn,
+          :cache_store => nil
         }
       )
 
@@ -76,7 +77,8 @@ describe Google::APIClient::Service do
         {
           :application_name => APPLICATION_NAME,
           :authenticated => false,
-          :connection => conn
+          :connection => conn,
+          :cache_store => nil
         }
       )
       req = adsense.adunits.list(:adClientId => '1').execute()
@@ -93,7 +95,8 @@ describe Google::APIClient::Service do
         {
           :application_name => APPLICATION_NAME,
           :authenticated => false,
-          :connection => conn
+          :connection => conn,
+          :cache_store => nil
         }
       )
       req = adsense.accounts.adclients.list(:accountId => '1').execute()
@@ -102,7 +105,7 @@ describe Google::APIClient::Service do
     describe 'with no connection' do
       before do
         @adsense = Google::APIClient::Service.new('adsense', 'v1.3',
-          {:application_name => APPLICATION_NAME})
+          {:application_name => APPLICATION_NAME, :cache_store => nil})
       end
 
       it 'should return a resource when using a valid resource name' do
@@ -152,7 +155,8 @@ describe Google::APIClient::Service do
         {
           :application_name => APPLICATION_NAME,
           :authenticated => false,
-          :connection => conn
+          :connection => conn,
+          :cache_store => nil
         }
       )
       req = prediction.trainedmodels.insert(:project => '1').body({'id' => '1'}).execute()
@@ -171,7 +175,8 @@ describe Google::APIClient::Service do
         {
           :application_name => APPLICATION_NAME,
           :authenticated => false,
-          :connection => conn
+          :connection => conn,
+          :cache_store => nil
         }
       )
       req = prediction.trainedmodels.insert(:project => '1').body('{"id":"1"}').execute()
@@ -181,7 +186,7 @@ describe Google::APIClient::Service do
     describe 'with no connection' do
       before do
         @prediction = Google::APIClient::Service.new('prediction', 'v1.5',
-          {:application_name => APPLICATION_NAME})
+          {:application_name => APPLICATION_NAME, :cache_store => nil})
       end
 
       it 'should return a valid request with a body' do
@@ -227,7 +232,8 @@ describe Google::APIClient::Service do
         {
           :application_name => APPLICATION_NAME,
           :authenticated => false,
-          :connection => conn
+          :connection => conn,
+          :cache_store => nil
         }
       )
       req = drive.files.insert(:uploadType => 'multipart').body(@metadata).media(@media).execute()
@@ -237,7 +243,7 @@ describe Google::APIClient::Service do
     describe 'with no connection' do
       before do
         @drive = Google::APIClient::Service.new('drive', 'v1',
-          {:application_name => APPLICATION_NAME})
+          {:application_name => APPLICATION_NAME, :cache_store => nil})
       end
 
       it 'should return a valid request with a body and media upload' do
@@ -265,7 +271,8 @@ describe Google::APIClient::Service do
   describe 'with the Discovery API' do
     it 'should make a valid end-to-end request' do
       discovery = Google::APIClient::Service.new('discovery', 'v1',
-          {:application_name => APPLICATION_NAME, :authenticated => false})
+          {:application_name => APPLICATION_NAME, :authenticated => false,
+           :cache_store => nil})
       result = discovery.apis.get_rest(:api => 'discovery', :version => 'v1').execute
       result.should_not be_nil
       result.data.name.should == 'discovery'
@@ -280,7 +287,7 @@ describe Google::APIClient::Service::Result do
   describe 'with the plus API' do
     before do
       @plus = Google::APIClient::Service.new('plus', 'v1',
-          {:application_name => APPLICATION_NAME})
+          {:application_name => APPLICATION_NAME, :cache_store => nil})
       @reference = Google::APIClient::Reference.new({
         :api_method => @plus.activities.list.method,
         :parameters => {
@@ -478,7 +485,8 @@ describe Google::APIClient::Service::BatchRequest do
   describe 'with the discovery API' do
     before do
       @discovery = Google::APIClient::Service.new('discovery', 'v1',
-          {:application_name => APPLICATION_NAME, :authorization => nil})
+          {:application_name => APPLICATION_NAME, :authorization => nil,
+           :cache_store => nil})
     end
 
     describe 'with two valid requests' do

spec/google/api_client/simple_file_store_spec.rb

@@ -0,0 +1,137 @@
+# encoding:utf-8
+
+# Copyright 2013 Google Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'spec_helper'
+
+require 'google/api_client/service/simple_file_store'
+
+describe Google::APIClient::Service::SimpleFileStore do
+
+  FILE_NAME = 'test.cache'
+
+  before(:all) do
+    File.delete(FILE_NAME) if File.exists?(FILE_NAME)
+  end
+
+  describe 'with no cache file' do
+    before(:each) do
+      File.delete(FILE_NAME) if File.exists?(FILE_NAME)
+      @cache = Google::APIClient::Service::SimpleFileStore.new(FILE_NAME)
+    end
+
+    it 'should return nil when asked if a key exists' do
+      @cache.exist?('invalid').should be_nil
+      File.exists?(FILE_NAME).should be_false
+    end
+
+    it 'should return nil when asked to read a key' do
+      @cache.read('invalid').should be_nil
+      File.exists?(FILE_NAME).should be_false
+    end
+
+    it 'should return nil when asked to fetch a key' do
+      @cache.fetch('invalid').should be_nil
+      File.exists?(FILE_NAME).should be_false
+    end
+
+    it 'should create a cache file when asked to fetch a key with a default' do
+      @cache.fetch('new_key') do
+        'value'
+      end.should == 'value'
+      File.exists?(FILE_NAME).should be_true
+    end
+
+    it 'should create a cache file when asked to write a key' do
+      @cache.write('new_key', 'value')
+      File.exists?(FILE_NAME).should be_true
+    end
+
+    it 'should return nil when asked to delete a key' do
+      @cache.delete('invalid').should be_nil
+      File.exists?(FILE_NAME).should be_false
+    end
+  end
+
+  describe 'with an existing cache' do
+    before(:each) do
+      File.delete(FILE_NAME) if File.exists?(FILE_NAME)
+      @cache = Google::APIClient::Service::SimpleFileStore.new(FILE_NAME)
+      @cache.write('existing_key', 'existing_value')
+    end
+
+    it 'should return true when asked if an existing key exists' do
+      @cache.exist?('existing_key').should be_true
+    end
+
+    it 'should return false when asked if a nonexistent key exists' do
+      @cache.exist?('invalid').should be_false
+    end
+
+    it 'should return the value for an existing key when asked to read it' do
+      @cache.read('existing_key').should == 'existing_value'
+    end
+
+    it 'should return nil for a nonexistent key when asked to read it' do
+      @cache.read('invalid').should be_nil
+    end
+
+    it 'should return the value for an existing key when asked to read it' do
+      @cache.read('existing_key').should == 'existing_value'
+    end
+
+    it 'should return nil for a nonexistent key when asked to fetch it' do
+      @cache.fetch('invalid').should be_nil
+    end
+
+    it 'should return and save the default value for a nonexistent key when asked to fetch it with a default' do
+      @cache.fetch('new_key') do
+        'value'
+      end.should == 'value'
+      @cache.read('new_key').should == 'value'
+    end
+
+    it 'should remove an existing value and return true when asked to delete it' do
+      @cache.delete('existing_key').should be_true
+      @cache.read('existing_key').should be_nil
+    end
+
+    it 'should return false when asked to delete a nonexistent key' do
+      @cache.delete('invalid').should be_false
+    end
+
+    it 'should convert keys to strings when storing them' do
+      @cache.write(:symbol_key, 'value')
+      @cache.read('symbol_key').should == 'value'
+    end
+
+    it 'should convert keys to strings when reading them' do
+      @cache.read(:existing_key).should == 'existing_value'
+    end
+
+    it 'should convert keys to strings when fetching them' do
+      @cache.fetch(:existing_key).should == 'existing_value'
+    end
+
+    it 'should convert keys to strings when deleting them' do
+      @cache.delete(:existing_key).should be_true
+      @cache.read('existing_key').should be_nil
+    end
+  end
+
+  after(:all) do
+    File.delete(FILE_NAME) if File.exists?(FILE_NAME)
+  end
+end