google-cloud-firestore 1.4.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c6817bc0ec1113059a7a310bf96f92272d0947d2602c511796c2c921c325f41
-  data.tar.gz: 2b0835c6d9d67b03b1bfc00b7d03fde70f2696612194d51b7dec55f64066b246
+  metadata.gz: d1e7097a28daa16ef5b2de8684c5b052b6409b792a4e7f382f878c47745dbf1a
+  data.tar.gz: 35dae74e7a063ad5e456420633c50b60ea0731b2fcafdde0e6ceab25b10bea25
 SHA512:
-  metadata.gz: c40af10bf4ffd742dc9b889d4591d23197526ab4b5f0246bcd5b166ac0b913aaff2e78c41b3ccf1d1a8328c1e59075cb317616e2bb655e4ad105a20a8df9c9a2
-  data.tar.gz: b4f8e9c5d553951f49b42013247f665dd454be9b93c2edb329b9e7ac223275b1828d004a123faa98e65d357c4692cfd2f5dc3ecdfb0702fce044a67c2dcc82bf
+  metadata.gz: 23da24a3a861701b5156d1851be1eba45770565319e86d66e098f3a59156490ec16a7457d52fa55d0c216df653d2e1873a6212b5df3b23c67f576d40d706bd53
+  data.tar.gz: 9aef0214f2cf6a9db195be9b27dbb50f087b8d25be9041419a9d14d018f910aad449140848a0d49aa0223961672361b18e47a1f60b0e6eeeedd3752a88c2ac3a

data/AUTHENTICATION.md

@@ -76,7 +76,7 @@ The environment variables that google-cloud-firestore checks for project ID are:
 1. `FIRESTORE_PROJECT`
 2. `GOOGLE_CLOUD_PROJECT`
 
-The environment variables that google-cloud-firestore checks for credentials are configured on {Google::Cloud::Firestore::V1::Credentials}:
+The environment variables that google-cloud-firestore checks for credentials are configured on {Google::Cloud::Firestore::Credentials}:
 
 1. `FIRESTORE_CREDENTIALS` - Path to JSON file, or JSON contents
 2. `FIRESTORE_KEYFILE` - Path to JSON file, or JSON contents

data/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Release History
 
+### 2.1.0 / 2020-09-10
+
+#### Features
+
+* Add Query#limit_to_last
+
+### 2.0.0 / 2020-08-06
+
+This is a major update that removes the "low-level" client interface code, and
+instead adds the new `google-cloud-firestore-v1` gem as a dependency.
+The new dependency is a rewritten low-level client, produced by a next-
+generation client code generator, with improved performance and stability.
+
+This change should have no effect on the high-level interface that most users
+will use. The one exception is that the (mostly undocumented) `client_config`
+argument, for adjusting low-level parameters such as RPC retry settings on
+client objects, has been removed. If you need to adjust these parameters, use
+the configuration interface in `google-cloud-firestore-v1`.
+
+Substantial changes have been made in the low-level interfaces, however. If you
+are using the low-level classes under the `Google::Cloud::Firestore::V1` module,
+please review the docs for the new `google-cloud-firestore-v1` gem. In
+particular:
+
+* Some classes have been renamed, notably the client class itself.
+* The client constructor takes a configuration block instead of configuration
+  keyword arguments.
+* All RPC method arguments are now keyword arguments.
+
+### 1.4.4 / 2020-05-28
+
+#### Documentation
+
+* Fix a few broken links
+
+### 1.4.3 / 2020-05-21
+
+#### Bug Fixes
+
+* Adjusted some default timeout and retry settings
+
+### 1.4.2 / 2020-05-14
+
+#### Bug Fixes
+
+* Fix Ruby 2.7 keyword argument warning
+
 ### 1.4.1 / 2020-04-14
 
 #### Bug Fixes

data/TROUBLESHOOTING.md

@@ -24,14 +24,8 @@ improved, *please* create a new issue on GitHub so we can talk about it.
 
   - [New issue][gh-ruby]
 
-Or, you can ask questions on the [Google Cloud Platform Slack][slack-ruby]. You
-can use the "ruby" channel for general Ruby questions, or use the
-"google-cloud-ruby" channel if you have questions about this gem in particular.
-
 [so-ruby]: http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby+firestore
 
-[gh-search-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues?q=label%3A%22api%3A+firestore%22
-
-[gh-ruby]: https://github.com/googlecloudplatform/google-cloud-ruby/issues/new
+[gh-search-ruby]: https://github.com/googleapis/google-cloud-ruby/issues?q=label%3A%22api%3A+firestore%22
 
-[slack-ruby]: https://gcp-slack.appspot.com/
+[gh-ruby]: https://github.com/googleapis/google-cloud-ruby/issues/new

data/lib/google-cloud-firestore.rb

@@ -42,8 +42,6 @@ module Google
     #
     #   * `https://www.googleapis.com/auth/datastore`
     # @param [Integer] timeout Default timeout to use in requests. Optional.
-    # @param [Hash] client_config A hash of values to override the default
-    #   behavior of the API client. Optional.
     #
     # @return [Google::Cloud::Firestore::Client]
     #
@@ -60,10 +58,8 @@ module Google
     #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
     #   firestore = gcloud.firestore scope: platform_scope
     #
-    def firestore scope: nil, timeout: nil, client_config: nil
-      Google::Cloud.firestore @project, @keyfile,
-                              scope: scope, timeout: (timeout || @timeout),
-                              client_config: client_config
+    def firestore scope: nil, timeout: nil
+      Google::Cloud.firestore @project, @keyfile, scope: scope, timeout: (timeout || @timeout)
     end
 
     ##
@@ -87,8 +83,6 @@ module Google
     #
     #   * `https://www.googleapis.com/auth/datastore`
     # @param [Integer] timeout Default timeout to use in requests. Optional.
-    # @param [Hash] client_config A hash of values to override the default
-    #   behavior of the API client. Optional.
     #
     # @return [Google::Cloud::Firestore::Client]
     #
@@ -97,13 +91,12 @@ module Google
     #
     #   firestore = Google::Cloud.firestore
     #
-    def self.firestore project_id = nil, credentials = nil, scope: nil,
-                       timeout: nil, client_config: nil
+    def self.firestore project_id = nil, credentials = nil, scope: nil, timeout: nil
       require "google/cloud/firestore"
-      Google::Cloud::Firestore.new project_id: project_id,
+      Google::Cloud::Firestore.new project_id:  project_id,
                                    credentials: credentials,
-                                   scope: scope, timeout: timeout,
-                                   client_config: client_config
+                                   scope:       scope,
+                                   timeout:     timeout
     end
   end
 end
@@ -122,17 +115,17 @@ Google::Cloud.configure.add_config! :firestore do |config|
   default_emulator = Google::Cloud::Config.deferred do
     ENV["FIRESTORE_EMULATOR_HOST"]
   end
+  default_scopes = [
+    "https://www.googleapis.com/auth/cloud-platform",
+    "https://www.googleapis.com/auth/datastore"
+  ]
 
   config.add_field! :project_id, default_project, match: String, allow_nil: true
   config.add_alias! :project, :project_id
-  config.add_field! :credentials, default_creds,
-                    match:     [String, Hash, Google::Auth::Credentials],
-                    allow_nil: true
+  config.add_field! :credentials, default_creds, match: [String, Hash, Google::Auth::Credentials], allow_nil: true
   config.add_alias! :keyfile, :credentials
-  config.add_field! :scope, nil, match: [String, Array]
+  config.add_field! :scope, default_scopes, match: [String, Array]
   config.add_field! :timeout, nil, match: Integer
-  config.add_field! :client_config, nil, match: Hash
-  config.add_field! :emulator_host, default_emulator,
-                    match: String, allow_nil: true
-  config.add_field! :endpoint, nil, match: String
+  config.add_field! :emulator_host, default_emulator, match: String, allow_nil: true
+  config.add_field! :endpoint, "firestore.googleapis.com", match: String
 end

data/lib/google/cloud/firestore.rb

@@ -33,7 +33,6 @@ module Google
     #
     module Firestore
       # rubocop:disable Metrics/AbcSize
-      # rubocop:disable Metrics/MethodLength
 
       ##
       # Creates a new object for connecting to the Firestore service.
@@ -56,8 +55,6 @@ module Google
       #
       #   * `https://www.googleapis.com/auth/datastore`
       # @param [Integer] timeout Default timeout to use in requests. Optional.
-      # @param [Hash] client_config A hash of values to override the default
-      #   behavior of the API client. Optional.
       # @param [String] endpoint Override of the endpoint host name. Optional.
       #   If the param is nil, uses the default endpoint.
       # @param [String] emulator_host Firestore emulator host. Optional.
@@ -73,13 +70,17 @@ module Google
       #
       #   firestore = Google::Cloud::Firestore.new
       #
-      def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
-                   client_config: nil, endpoint: nil, emulator_host: nil,
-                   project: nil, keyfile: nil
+      def self.new project_id: nil,
+                   credentials: nil,
+                   scope: nil,
+                   timeout: nil,
+                   endpoint: nil,
+                   emulator_host: nil,
+                   project: nil,
+                   keyfile: nil
         project_id    ||= (project || default_project_id)
         scope         ||= configure.scope
         timeout       ||= configure.timeout
-        client_config ||= configure.client_config
         endpoint      ||= configure.endpoint
         emulator_host ||= configure.emulator_host
 
@@ -87,13 +88,8 @@ module Google
           project_id = project_id.to_s
           raise ArgumentError, "project_id is missing" if project_id.empty?
 
-          return Firestore::Client.new(
-            Firestore::Service.new(
-              project_id, :this_channel_is_insecure,
-              host: emulator_host, timeout: timeout,
-              client_config: client_config
-            )
-          )
+          service = Firestore::Service.new project_id, :this_channel_is_insecure, host: emulator_host, timeout: timeout
+          return Firestore::Client.new service
         end
 
         credentials ||= (keyfile || default_credentials(scope: scope))
@@ -107,16 +103,11 @@ module Google
         project_id = project_id.to_s
         raise ArgumentError, "project_id is missing" if project_id.empty?
 
-        Firestore::Client.new(
-          Firestore::Service.new(
-            project_id, credentials,
-            host: endpoint, timeout: timeout, client_config: client_config
-          )
-        )
+        service = Firestore::Service.new project_id, credentials, host: endpoint, timeout: timeout
+        Firestore::Client.new service
       end
 
       # rubocop:enable Metrics/AbcSize
-      # rubocop:enable Metrics/MethodLength
 
       ##
       # Configure the Google Cloud Firestore library.
@@ -132,8 +123,6 @@ module Google
       # * `scope` - (String, Array<String>) The OAuth 2.0 scopes controlling
       #   the set of resources and operations that the connection can access.
       # * `timeout` - (Integer) Default timeout to use in requests.
-      # * `client_config` - (Hash) A hash of values to override the default
-      #   behavior of the API client.
       # * `endpoint` - (String) Override of the endpoint host name, or `nil`
       #   to use the default endpoint.
       # * `emulator_host` - (String) Host name of the emulator. Defaults to

data/lib/google/cloud/firestore/client.rb

@@ -82,12 +82,13 @@ module Google
         # @!group Access
 
         ##
-        # Retrieves a list of collections.
+        # Retrieves an enumerator for the root collections.
         #
         # @yield [collections] The block for accessing the collections.
-        # @yieldparam [CollectionReference] collection A collection.
+        # @yieldparam [CollectionReference] collection A collection reference object.
         #
-        # @return [Enumerator<CollectionReference>] collection list.
+        # @return [Enumerator<CollectionReference>] An enumerator of collection references. If a block is provided,
+        #  this is the same enumerator that is accessed through the block.
         #
         # @example
         #   require "google/cloud/firestore"
@@ -101,11 +102,10 @@ module Google
         #
         def cols
           ensure_service!
-
-          return enum_for :cols unless block_given?
-
-          collection_ids = service.list_collections "#{path}/documents"
-          collection_ids.each { |collection_id| yield col collection_id }
+          grpc = service.list_collections "#{path}/documents"
+          cols_enum = CollectionReferenceList.from_grpc(grpc, self, "#{path}/documents").all
+          cols_enum.each { |c| yield c } if block_given?
+          cols_enum
         end
         alias collections cols
         alias list_collections cols
@@ -134,8 +134,7 @@ module Google
             raise ArgumentError, "collection_path must refer to a collection."
           end
 
-          CollectionReference.from_path \
-            "#{path}/documents/#{collection_path}", self
+          CollectionReference.from_path "#{path}/documents/#{collection_path}", self
         end
         alias collection col
 
@@ -167,9 +166,9 @@ module Google
             raise ArgumentError, "Invalid collection_id: '#{collection_id}', " \
               "must not contain '/'."
           end
-          query = Google::Firestore::V1::StructuredQuery.new(
+          query = Google::Cloud::Firestore::V1::StructuredQuery.new(
             from: [
-              Google::Firestore::V1::StructuredQuery::CollectionSelector.new(
+              Google::Cloud::Firestore::V1::StructuredQuery::CollectionSelector.new(
                 collection_id: collection_id, all_descendants: true
               )
             ]
@@ -670,8 +669,7 @@ module Google
         # @private
         def list_documents parent, collection_id, token: nil, max: nil
           ensure_service!
-          grpc = service.list_documents \
-            parent, collection_id, token: token, max: max
+          grpc = service.list_documents parent, collection_id, token: token, max: max
           DocumentReference::List.from_grpc grpc, self, parent, collection_id
         end
 

data/lib/google/cloud/firestore/collection_reference.rb

@@ -18,6 +18,7 @@ require "google/cloud/firestore/document_reference"
 require "google/cloud/firestore/document_snapshot"
 require "google/cloud/firestore/query"
 require "google/cloud/firestore/generate"
+require "google/cloud/firestore/collection_reference_list"
 
 module Google
   module Cloud

data/lib/google/cloud/firestore/collection_reference_list.rb

@@ -0,0 +1,137 @@
+# Copyright 2020 Google LLC
+#
+# 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
+#
+#     https://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 "delegate"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # @private
+      #
+      # An Array delegate for pagination. Private class exposing only an Enumerator to clients.
+      #
+      class CollectionReferenceList < DelegateClass(::Array)
+        ##
+        # If not empty, indicates that there are more records that match the request and this value should be passed
+        # to continue.
+        attr_accessor :token
+
+        ##
+        # @private Create a new CollectionReference::List with an array of CollectionReference instances.
+        def initialize arr = []
+          super arr
+        end
+
+        ##
+        # Whether there is a next page of collection references.
+        #
+        # @return [Boolean]
+        #
+        def next?
+          !token.nil?
+        end
+
+        ##
+        # Retrieve the next page of collection references.
+        #
+        # @return [CollectionReference::List] The list of collection references.
+        #
+        def next
+          return nil unless next?
+          ensure_service!
+          grpc = @client.service.list_collections @parent, token: token, max: @max
+          self.class.from_grpc grpc, @client, @parent, max: @max
+        end
+
+        ##
+        # Retrieves remaining results by repeatedly invoking {#next} until {#next?} returns `false`. Calls the given
+        # block once for each result, which is passed as the argument to the block.
+        #
+        # An Enumerator is returned if no block is given.
+        #
+        # This method will make repeated API calls until all remaining results are retrieved. (Unlike `#each`, for
+        # example, which merely iterates over the results returned by a single API call.) Use with caution.
+        #
+        # @param [Integer] request_limit The upper limit of API requests to make to load all collection references.
+        #   Default is no limit.
+        # @yield [collection_reference] The block for accessing each collection_reference.
+        # @yieldparam [CollectionReference] collection_reference The collection reference object.
+        #
+        # @return [Enumerator]
+        #
+        # @example Iterating each collection reference by passing a block:
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   firestore.cols do |collection_reference|
+        #     puts collection_reference.collection_id
+        #   end
+        #
+        # @example Using the enumerator by not passing a block:
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   all_collection_ids = firestore.cols.map do |collection_reference|
+        #     collection_reference.collection_id
+        #   end
+        #
+        def all request_limit: nil
+          request_limit = request_limit.to_i if request_limit
+          unless block_given?
+            return enum_for :all, request_limit: request_limit
+          end
+          results = self
+          loop do
+            results.each { |r| yield r }
+            if request_limit
+              request_limit -= 1
+              break if request_limit < 0
+            end
+            break unless results.next?
+            results = results.next
+          end
+        end
+
+        ##
+        # @private New CollectionReference::List from a `Google::Cloud::Firestore::V1::ListCollectionIdsResponse`
+        # object.
+        def self.from_grpc grpc, client, parent, max: nil
+          raise ArgumentError, "parent is required" unless parent
+          cols = CollectionReferenceList.new(Array(grpc.collection_ids).map do |collection_id|
+            CollectionReference.from_path "#{parent}/#{collection_id}", client
+          end)
+          token = grpc.next_page_token
+          token = nil if token == ""
+          cols.instance_variable_set :@token, token
+          cols.instance_variable_set :@client, client
+          cols.instance_variable_set :@parent, parent
+          cols.instance_variable_set :@max, max
+          cols
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active service is available.
+        def ensure_service!
+          raise "Must have active connection" unless @client.service
+        end
+      end
+    end
+  end
+end