google-cloud-firestore 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96192127f7ee4dafde2959f7d1f463fb7fa24ab09055e7764e6f83fd0aeda8be
-  data.tar.gz: 4848935ba22ddc1b1cb9a24825a03802651d9dfc206b3d93a71af91b4e06eb8d
+  metadata.gz: 6c249cbd2bcfd378c5ab77ce2b5e717f629e741ca8c30b259897cfcd87ca732a
+  data.tar.gz: 90d335ef83762a548eefdc4ed2a35ea5c5c830a1069bd7b969e67a704496cf3b
 SHA512:
-  metadata.gz: 523e76c8d3829de28395b9fffd54dc2cd098e08cbc204836ae6836f85f29028b36721b2f66ebb455e5d1895b9d19c1cd1c23f5aee4fffae0842a9df897ce227b
-  data.tar.gz: 5ec65a1d3ecce996ab3a1d344495df11f84e5cce44d1932c1aea44aa877e5acf7a5e4fec9f7661ff6eb9c49a99db7c2d17109d825a0f5ee2959efe9e6bf73b34
+  metadata.gz: 4f8c8534c873bf3b86e8bccce74529c69ffebb5ba14e377ad60e0b32ae319ae22d8b96ff3eece237786952d169f49210168f3243a220e963b363d740c84aa54f
+  data.tar.gz: e0ae957a20ae64ae3c26cc6f379c12080fb8d71cf6b30bc0e4717787e7fadf785dcd5694a5d2422477639cb971da33715f21dae5f20613f490dd8a3ab5d9b1ba

data/.yardopts

@@ -2,6 +2,7 @@
 --title=Google Cloud Firestore API
 --exclude lib/google/firestore/v1beta1
 --markup markdown
+--markup-provider redcarpet
 
 ./lib/**/*.rb
 -

data/README.md

@@ -50,14 +50,14 @@ end
 
 ## Supported Ruby Versions
 
-This library is supported on Ruby 2.0+.
-
-However, Ruby 2.3 or later is strongly recommended, as earlier releases have
-reached or are nearing end-of-life. After June 1, 2018, Google will provide
-official support only for Ruby versions that are considered current and
-supported by Ruby Core (that is, Ruby versions that are either in normal
-maintenance or in security maintenance).
-See https://www.ruby-lang.org/en/downloads/branches/ for further details.
+This library is supported on Ruby 2.3+.
+
+Google provides official support for Ruby versions that are actively supported
+by Ruby Core—that is, Ruby versions that are either in normal maintenance or
+in security maintenance, and not end of life. Currently, this means Ruby 2.3
+and later. Older versions of Ruby _may_ still work, but are unsupported and not
+recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
+about the Ruby support schedule.
 
 [Client Library Documentation]: https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-firestore/latest/google/firestore/v1beta1
 [Product Documentation]: https://cloud.google.com/firestore

data/lib/google-cloud-firestore.rb

@@ -76,7 +76,7 @@ module Google
     #   present, the default project for the credentials is used.
     # @param [String, Hash, Google::Auth::Credentials] credentials The path to
     #   the keyfile as a String, the contents of the keyfile as a Hash, or a
-    #   Google::Auth::Credentials object. (See {Datastore::Credentials})
+    #   Google::Auth::Credentials object. (See {Firestore::Credentials})
     # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
     #   set of resources and operations that the connection can access. See
     #   [Using OAuth 2.0 to Access Google

data/lib/google/cloud/firestore.rb

@@ -390,6 +390,52 @@ module Google
     # user_ref.update({ nested_field_path => "Pasta" })
     # ```
     #
+    # ### Listening for changes
+    #
+    # You can listen to a document reference or a collection reference/query for
+    # changes. The current document snapshot or query results snapshot will be
+    # yielded first, and each time the contents change.
+    #
+    # You can use {Firestore::DocumentReference#listen} to be notified of
+    # changes to a single document:
+    #
+    # ```ruby
+    # require "google/cloud/firestore"
+    #
+    # firestore = Google::Cloud::Firestore.new
+    #
+    # # Get a document reference
+    # nyc_ref = firestore.doc "cities/NYC"
+    #
+    # listener = nyc_ref.listen do |snapshot|
+    #   puts "The population of #{snapshot[:name]} "
+    #   puts "is #{snapshot[:population]}."
+    # end
+    #
+    # # When ready, stop the listen operation and close the stream.
+    # listener.stop
+    # ```
+    #
+    # You can use {Firestore::Query#listen} to be notified of changes to any
+    # document contained in the query:
+    #
+    # ```ruby
+    # require "google/cloud/firestore"
+    #
+    # firestore = Google::Cloud::Firestore.new
+    #
+    # # Create a query
+    # query = firestore.col(:cities).order(:population, :desc)
+    #
+    # listener = query.listen do |snapshot|
+    #   puts "The query snapshot has #{snapshot.docs.count} documents "
+    #   puts "and has #{snapshot.changes.count} changes."
+    # end
+    #
+    # # When ready, stop the listen operation and close the stream.
+    # listener.stop
+    # ```
+    #
     # ## Using transactions and batched writes
     #
     # Cloud Firestore supports atomic operations for reading and writing data.

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

@@ -30,7 +30,7 @@ module Google
       # atomically at a single logical point in time in a database.
       #
       # All changes are accumulated in memory until the block passed to
-      # {Database#batch} completes. Unlike transactions, batches don't lock on
+      # {Client#batch} completes. Unlike transactions, batches don't lock on
       # document reads, should only fail if users provide preconditions, and are
       # not automatically retried.
       #

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

@@ -212,7 +212,7 @@ module Google
         ##
         # Creates a field path object representing the sentinel ID of a
         # document. It can be used in queries to sort or filter by the document
-        # ID. See {Client#document_id}.
+        # ID. See {FieldPath#document_id}.
         #
         # @return [FieldPath] The field path object.
         #
@@ -225,9 +225,8 @@ module Google
         #   cities_col = firestore.col "cities"
         #
         #   # Create a query
-        #   query = cities_col.start_at("NYC").order(
-        #     Google::Cloud::Firestore::FieldPath.document_id
-        #   )
+        #   query = cities_col.order(firestore.document_id)
+        #                     .start_at("NYC")
         #
         #   query.get do |city|
         #     puts "#{city.document_id} has #{city[:population]} residents."
@@ -383,31 +382,37 @@ module Google
         #
         def transaction max_retries: nil
           max_retries = 5 unless max_retries.is_a? Integer
-          retries = 0
-          backoff = 1.0
+          backoff = { current: 0, delay: 1.0, max: max_retries, mod: 1.3 }
 
           transaction = Transaction.from_client self
           begin
             yield transaction
             transaction.commit
           rescue Google::Cloud::UnavailableError => err
-            # Re-raise if deadline has passed
-            raise err if retries >= max_retries
-            # Sleep with incremental backoff
-            sleep(backoff *= 1.3)
+            # Re-raise if retried more than the max
+            raise err if backoff[:current] > backoff[:max]
+
+            # Sleep with incremental backoff before restarting
+            sleep backoff[:delay]
+
+            # Update increment backoff delay and retry counter
+            backoff[:delay] *= backoff[:mod]
+            backoff[:current] += 1
+
             # Create new transaction and retry
             transaction = Transaction.from_client \
               self, previous_transaction: transaction.transaction_id
-            retries += 1
             retry
           rescue Google::Cloud::InvalidArgumentError => err
-            # Return if a previous call has succeeded
-            return nil if retries > 0
+            # Return if a previous call was retried but ultimately succeeded
+            return nil if backoff[:current] > 0
+
             # Re-raise error.
             raise err
           rescue StandardError => err
             # Rollback transaction when handling unexpected error
             transaction.rollback rescue nil
+
             # Re-raise error.
             raise err
           end

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

@@ -43,9 +43,9 @@ module Google
             Time.at timestamp.seconds, Rational(timestamp.nanos, 1000)
           end
 
-          def fields_to_hash fields, context
+          def fields_to_hash fields, client
             Hash[fields.map do |key, value|
-              [key.to_sym, value_to_raw(value, context)]
+              [key.to_sym, value_to_raw(value, client)]
             end]
           end
 
@@ -55,7 +55,7 @@ module Google
             end]
           end
 
-          def value_to_raw value, context
+          def value_to_raw value, client
             case value.value_type
             when :null_value
               nil
@@ -73,13 +73,13 @@ module Google
               StringIO.new value.bytes_value
             when :reference_value
               Google::Cloud::Firestore::DocumentReference.from_path \
-                value.reference_value, context
+                value.reference_value, client
             when :geo_point_value
               value.geo_point_value.to_hash
             when :array_value
-              value.array_value.values.map { |v| value_to_raw v, context }
+              value.array_value.values.map { |v| value_to_raw v, client }
             when :map_value
-              fields_to_hash value.map_value.fields, context
+              fields_to_hash value.map_value.fields, client
             end
           end
 
@@ -104,9 +104,12 @@ module Google
               Google::Firestore::V1beta1::Value.new(array_value:
                 Google::Firestore::V1beta1::ArrayValue.new(values: values))
             elsif Hash === obj
-              if obj.keys.sort == [:latitude, :longitude]
-                Google::Firestore::V1beta1::Value.new(geo_point_value:
-                  Google::Type::LatLng.new(obj))
+              # keys have been changed to strings before the hash gets here
+              geo_pairs = hash_is_geo_point? obj
+              if geo_pairs
+                Google::Firestore::V1beta1::Value.new(
+                  geo_point_value: hash_to_geo_point(obj, geo_pairs)
+                )
               else
                 fields = hash_to_fields obj
                 Google::Firestore::V1beta1::Value.new(map_value:
@@ -118,10 +121,30 @@ module Google
               Google::Firestore::V1beta1::Value.new bytes_value: content
             else
               raise ArgumentError,
-                   "A value of type #{obj.class} is not supported."
+                    "A value of type #{obj.class} is not supported."
             end
           end
 
+          def hash_is_geo_point? hash
+            return false unless hash.keys.count == 2
+
+            pairs = hash.map { |k, v| [String(k), v] }.sort
+            if pairs.map(&:first) == ["latitude".freeze, "longitude".freeze]
+              pairs
+            end
+          end
+
+          def hash_to_geo_point hash, pairs = nil
+            pairs ||= hash_is_geo_point? hash
+
+            raise ArgumentError, "value is not a geo point" unless pairs
+
+            Google::Type::LatLng.new(
+              latitude: pairs.first.last,
+              longitude: pairs.last.last,
+            )
+          end
+
           def writes_for_create doc_path, data
             writes = []
 
@@ -164,13 +187,15 @@ module Google
               if merge == true
                 # extract the leaf node field paths from data
                 field_paths = identify_leaf_nodes data
+                allow_empty = true
               else
                 field_paths = Array(merge).map do |field_path|
                   field_path = FieldPath.parse field_path unless field_path.is_a? FieldPath
                   field_path
                 end
+                allow_empty = false
               end
-              return writes_for_set_merge doc_path, data, field_paths
+              return writes_for_set_merge doc_path, data, field_paths, allow_empty
             end
 
             writes = []
@@ -195,9 +220,11 @@ module Google
             writes
           end
 
-          def writes_for_set_merge doc_path, data, field_paths
+          def writes_for_set_merge doc_path, data, field_paths, allow_empty
             raise ArgumentError, "data is required" unless data.is_a? Hash
 
+            validate_field_paths! field_paths
+
             writes = []
 
             # Ensure provided field paths are valid.
@@ -231,22 +258,32 @@ module Google
             delete_valid_check = delete_valid_check.include? false
             raise ArgumentError, "deleted field not included in merge" if delete_valid_check
 
+            server_time_paths.select! do |server_time_path|
+              field_paths.any? do |field_path|
+                server_time_path.formatted_string.start_with? field_path.formatted_string
+              end
+            end
+
             # Choose only the data there are field paths for
             field_paths -= delete_paths
             field_paths -= server_time_paths
             data = select_by_field_paths data, field_paths
+            # Restore delete paths
+            field_paths += delete_paths
 
-            if data.empty?
-              if server_time_paths.empty?
+            if data.empty? && !allow_empty
+              if server_time_paths.empty? && delete_paths.empty?
                 raise ArgumentError, "data required for set with merge"
               end
-            else
+            end
+
+            if data.any? || field_paths.any? || (allow_empty && server_time_paths.empty?)
               writes << Google::Firestore::V1beta1::Write.new(
                 update: Google::Firestore::V1beta1::Document.new(
                   name: doc_path,
                   fields: hash_to_fields(data)),
                 update_mask: Google::Firestore::V1beta1::DocumentMask.new(
-                  field_paths: field_paths.map(&:formatted_string))
+                  field_paths: field_paths.map(&:formatted_string).sort)
               )
             end
 
@@ -269,18 +306,7 @@ module Google
             end
 
             # Duplicate field paths check
-            dup_keys = new_data_pairs.map(&:first).map(&:formatted_string)
-            if dup_keys.size != dup_keys.uniq.size
-              raise ArgumentError, "duplicate field paths"
-            end
-            dup_keys.each do |field_path|
-              prefix_check = dup_keys.select do |this_path|
-                this_path.start_with? "#{field_path}."
-              end
-              if prefix_check.any?
-                raise ArgumentError, "one field cannot be a prefix of another"
-              end
-            end
+            validate_field_paths! new_data_pairs.map(&:first)
 
             delete_paths, new_data_pairs = new_data_pairs.partition do |field_path, value|
               value.is_a?(FieldValue) && value.type == :delete
@@ -301,10 +327,9 @@ module Google
 
             data, nested_server_time_paths = remove_field_value_from data, :server_time
 
-            server_time_paths = root_server_time_paths + nested_server_time_paths
             server_time_paths = root_server_time_paths + nested_server_time_paths
 
-            field_paths = (field_paths - (field_paths - identify_all_file_paths(data)) + delete_paths).uniq
+            field_paths = (field_paths + delete_paths).uniq
             field_paths.each do |field_path|
               raise ArgumentError, "empty paths not allowed" if field_path.fields.empty?
             end
@@ -319,7 +344,7 @@ module Google
                   name: doc_path,
                   fields: hash_to_fields(data)),
                 update_mask: Google::Firestore::V1beta1::DocumentMask.new(
-                  field_paths: field_paths.map(&:formatted_string)),
+                  field_paths: (field_paths).map(&:formatted_string).sort),
                 current_document: Google::Firestore::V1beta1::Precondition.new(
                   exists: true)
               )
@@ -464,13 +489,15 @@ module Google
             tmp_hash = ret_hash
             prev_hash = ret_hash
             dup_hash = hash.dup
-            fields = field_path.fields
+            fields = field_path.fields.dup
             last_field = nil
 
             # squash fields until the key exists?
-            until dup_hash.key? fields.first
-              fields.unshift "#{fields.shift}.#{fields.shift}"
-              break if fields.count <= 1
+            if fields.count > 1
+              until dup_hash.key? fields.first
+                fields.unshift "#{fields.shift}.#{fields.shift}"
+                break if fields.count <= 1
+              end
             end
 
             fields.each do |field|
@@ -482,9 +509,25 @@ module Google
               dup_hash = dup_hash[field]
             end
             prev_hash[last_field] = dup_hash
+            prev_hash.delete_if { |_k, v| v.nil? }
             ret_hash
           end
 
+          def validate_field_paths! field_paths
+            field_paths_strings = field_paths.map(&:formatted_string)
+            if field_paths_strings.size != field_paths_strings.uniq.size
+              raise ArgumentError, "duplicate field paths"
+            end
+            field_paths_strings.each do |field_path|
+              prefix_check = field_paths_strings.select do |this_path|
+                this_path.start_with? "#{field_path}."
+              end
+              if prefix_check.any?
+                raise ArgumentError, "one field cannot be a prefix of another"
+              end
+            end
+          end
+
           def deep_merge_hashes left_hash, right_hash
             right_hash.each_pair do |key, right_value|
               left_value = left_hash[key]

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

@@ -13,7 +13,7 @@
 # limitations under the License.
 
 
-require "googleauth"
+require "google/cloud/firestore/v1beta1/credentials"
 
 module Google
   module Cloud
@@ -37,17 +37,7 @@ module Google
       #
       #   firestore.project_id #=> "my-project"
       #
-      class Credentials < Google::Auth::Credentials
-        SCOPE = ["https://www.googleapis.com/auth/datastore"].freeze
-        PATH_ENV_VARS = %w[FIRESTORE_CREDENTIALS FIRESTORE_KEYFILE
-                           GOOGLE_CLOUD_CREDENTIALS GOOGLE_CLOUD_KEYFILE
-                           GCLOUD_KEYFILE].freeze
-        JSON_ENV_VARS = %w[FIRESTORE_CREDENTIALS_JSON FIRESTORE_KEYFILE_JSON
-                           GOOGLE_CLOUD_CREDENTIALS_JSON
-                           GOOGLE_CLOUD_KEYFILE_JSON
-                           GCLOUD_KEYFILE_JSON].freeze
-        DEFAULT_PATHS = \
-          ["~/.config/gcloud/application_default_credentials.json"].freeze
+      class Credentials < Google::Cloud::Firestore::V1beta1::Credentials
       end
     end
   end

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

@@ -0,0 +1,124 @@
+# Copyright 2018 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.
+
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # # DocumentChange
+      #
+      # A DocumentChange object represents a change to the document matching a
+      # query. It contains the document affected and the type of change that
+      # occurred (added, modifed, or removed).
+      #
+      # See {Query#listen} and {QuerySnapshot#changes}.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   # Create a query
+      #   query = firestore.col(:cities).order(:population, :desc)
+      #
+      #   listener = query.listen do |snapshot|
+      #     puts "The query snapshot has #{snapshot.docs.count} documents "
+      #     puts "and has #{snapshot.changes.count} changes."
+      #   end
+      #
+      #   # When ready, stop the listen operation and close the stream.
+      #   listener.stop
+      #
+      class DocumentChange
+        ##
+        # The document snapshot object for the data.
+        #
+        # @return [DocumentSnapshot] document snapshot.
+        #
+        def doc
+          @doc
+        end
+        alias document doc
+
+        ##
+        # The type of change (':added', ':modified', or ':removed').
+        #
+        # @return [Symbol] The type of change.
+        #
+        def type
+          return :removed if @new_index.nil?
+          return :added if @old_index.nil?
+          :modified
+        end
+
+        ##
+        # Determines whether the document was added.
+        #
+        # @return [Boolean] Whether the document was added.
+        #
+        def added?
+          type == :added
+        end
+
+        ##
+        # Determines whether the document was modified.
+        #
+        # @return [Boolean] Whether the document was modified.
+        #
+        def modified?
+          type == :modified
+        end
+
+        ##
+        # Determines whether the document was removed.
+        #
+        # @return [Boolean] Whether the document was removed.
+        #
+        def removed?
+          type == :removed
+        end
+
+        ##
+        # The index in the documents array prior to the change.
+        #
+        # @return [Integer, nil] The old index
+        #
+        def old_index
+          @old_index
+        end
+
+        ##
+        # The index in the documents array after the change.
+        #
+        # @return [Integer, nil] The new index
+        #
+        def new_index
+          @new_index
+        end
+
+        ##
+        # @private New DocumentChange from a
+        # Google::Cloud::Firestore::DocumentSnapshot object.
+        def self.from_doc doc, old_index, new_index
+          new.tap do |s|
+            s.instance_variable_set :@doc, doc
+            s.instance_variable_set :@old_index, old_index
+            s.instance_variable_set :@new_index, new_index
+          end
+        end
+      end
+    end
+  end
+end