google-cloud-firestore 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c1c6b4bcea222f6ed81150700b9d6c969fc70eeb8492db0ed69db1bb43f62cb
-  data.tar.gz: 50bbd220cf388af656606d99948477d47f9a1fa3d41ab479f6fcaa32f32e909d
+  metadata.gz: 12a9c7f721487eef84a1d703f77f0b2f56aea624fc9c6e1052be059c49437a6f
+  data.tar.gz: 76d354bb9933a7a83ef6163fef5bd37da82808786f05d06a83f54dc605ca1154
 SHA512:
-  metadata.gz: d1a810ae1cd779858ad8762dacd08765b2daf06b1de8ce13dc675b79ef7c6696c3bbda34d7593a6087e2189aebd2e23090bd89d11da8753f1751726270a61391
-  data.tar.gz: af77949c47636ca6e65ca14224fa5270a9f3daa4c00fd236e19780273e35593c0986ba5e5a0d601a6f107cbdc5482db51ca002841ee8cbf21acbd9ac752a93ee
+  metadata.gz: b8e403df8684221a0521432017c511f8b0c4d174c97c95129f7952e6751914093fe692585127d2f0a267f9776b9a464062bd10e3f3a7d9aa7c772edcddde8d2e
+  data.tar.gz: bd858f3f1c199b835ce22f567068af585f9ce41d2cd9da6811f5d06bbcc45ab1aadaa40575d1684bb2245d691c90589df420343a0233039f860030513037de75

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Release History
 
+### 2.3.0 / 2020-09-30
+
+#### Features
+
+* Add error callbacks for listener threads
+  * Add DocumentListener#last_error
+  * Add DocumentListener#on_error
+  * Add QueryListener#last_error
+  * Add QueryListener#on_error
+
 ### 2.2.0 / 2020-09-17
 
 #### Features

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

@@ -14,11 +14,14 @@
 
 
 require "google/cloud/firestore/watch/listener"
+require "monitor"
 
 module Google
   module Cloud
     module Firestore
       ##
+      # # DocumentListener
+      #
       # An ongoing listen operation on a document reference. This is returned by
       # calling {DocumentReference#listen}.
       #
@@ -31,25 +34,28 @@ module Google
       #   nyc_ref = firestore.doc "cities/NYC"
       #
       #   listener = nyc_ref.listen do |snapshot|
-      #     puts "The population of #{snapshot[:name]} "
-      #     puts "is #{snapshot[:population]}."
+      #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
       #   end
       #
       #   # When ready, stop the listen operation and close the stream.
       #   listener.stop
       #
       class DocumentListener
+        include MonitorMixin
         ##
         # @private
         # Creates the watch stream and listener object.
         def initialize doc_ref, &callback
+          super() # to init MonitorMixin
+
           @doc_ref = doc_ref
           raise ArgumentError if @doc_ref.nil?
 
           @callback = callback
           raise ArgumentError if @callback.nil?
+          @error_callbacks = []
 
-          @listener = Watch::Listener.for_doc_ref doc_ref do |query_snp|
+          @listener = Watch::Listener.for_doc_ref self, doc_ref do |query_snp|
             doc_snp = query_snp.docs.find { |doc| doc.path == @doc_ref.path }
 
             if doc_snp.nil?
@@ -80,8 +86,7 @@ module Google
         #   nyc_ref = firestore.doc "cities/NYC"
         #
         #   listener = nyc_ref.listen do |snapshot|
-        #     puts "The population of #{snapshot[:name]} "
-        #     puts "is #{snapshot[:population]}."
+        #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
         #   end
         #
         #   # When ready, stop the listen operation and close the stream.
@@ -103,8 +108,7 @@ module Google
         #   nyc_ref = firestore.doc "cities/NYC"
         #
         #   listener = nyc_ref.listen do |snapshot|
-        #     puts "The population of #{snapshot[:name]} "
-        #     puts "is #{snapshot[:population]}."
+        #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
         #   end
         #
         #   # Checks if the listener is stopped.
@@ -119,6 +123,81 @@ module Google
         def stopped?
           @listener.stopped?
         end
+
+        ##
+        # Register to be notified of errors when raised.
+        #
+        # If an unhandled error has occurred the listener will attempt to
+        # recover from the error and resume listening.
+        #
+        # Multiple error handlers can be added.
+        #
+        # @yield [callback] The block to be called when an error is raised.
+        # @yieldparam [Exception] error The error raised.
+        #
+        # @example
+        #   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]} is #{snapshot[:population]}."
+        #   end
+        #
+        #   # Register to be notified when unhandled errors occur.
+        #   listener.on_error do |error|
+        #     puts error
+        #   end
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def on_error &block
+          raise ArgumentError, "on_error must be called with a block" unless block_given?
+          synchronize { @error_callbacks << block }
+        end
+
+        ##
+        # The most recent unhandled error to occur while listening for changes.
+        #
+        # If an unhandled error has occurred the listener will attempt to
+        # recover from the error and resume listening.
+        #
+        # @return [Exception, nil] error The most recent error raised.
+        #
+        # @example
+        #   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]} is #{snapshot[:population]}."
+        #   end
+        #
+        #   # If an error was raised, it can be retrieved here:
+        #   listener.last_error #=> nil
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def last_error
+          synchronize { @last_error }
+        end
+
+        # @private Pass the error to user-provided error callbacks.
+        def error! error
+          error_callbacks = synchronize do
+            @last_error = error
+            @error_callbacks.dup
+          end
+          error_callbacks.each { |error_callback| error_callback.call error }
+        end
       end
     end
   end

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

@@ -168,8 +168,7 @@ module Google
         #   nyc_ref = firestore.doc "cities/NYC"
         #
         #   listener = nyc_ref.listen do |snapshot|
-        #     puts "The population of #{snapshot[:name]} "
-        #     puts "is #{snapshot[:population]}."
+        #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
         #   end
         #
         #   # When ready, stop the listen operation and close the stream.

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

@@ -53,8 +53,7 @@ module Google
       #   nyc_ref = firestore.doc "cities/NYC"
       #
       #   listener = nyc_ref.listen do |snapshot|
-      #     puts "The population of #{snapshot[:name]} "
-      #     puts "is #{snapshot[:population]}."
+      #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
       #   end
       #
       #   # When ready, stop the listen operation and close the stream.

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

@@ -41,17 +41,21 @@ module Google
       #   listener.stop
       #
       class QueryListener
+        include MonitorMixin
         ##
         # @private
         # Creates the watch stream and listener object.
         def initialize query, &callback
+          super() # to init MonitorMixin
+
           @query = query
           raise ArgumentError if @query.nil?
 
           @callback = callback
           raise ArgumentError if @callback.nil?
+          @error_callbacks = []
 
-          @listener = Watch::Listener.for_query query, &callback
+          @listener = Watch::Listener.for_query self, query, &callback
         end
 
         ##
@@ -112,6 +116,83 @@ module Google
         def stopped?
           @listener.stopped?
         end
+
+        ##
+        # Register to be notified of errors when raised.
+        #
+        # If an unhandled error has occurred the listener will attempt to
+        # recover from the error and resume listening.
+        #
+        # Multiple error handlers can be added.
+        #
+        # @yield [callback] The block to be called when an error is raised.
+        # @yieldparam [Exception] error The error raised.
+        #
+        # @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
+        #
+        #   # Register to be notified when unhandled errors occur.
+        #   listener.on_error do |error|
+        #     puts error
+        #   end
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def on_error &block
+          raise ArgumentError, "on_error must be called with a block" unless block_given?
+          synchronize { @error_callbacks << block }
+        end
+
+        ##
+        # The most recent unhandled error to occur while listening for changes.
+        #
+        # If an unhandled error has occurred the listener will attempt to
+        # recover from the error and resume listening.
+        #
+        # @return [Exception, nil] error The most recent error raised.
+        #
+        # @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
+        #
+        #   # If an error was raised, it can be retrieved here:
+        #   listener.last_error #=> nil
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def last_error
+          synchronize { @last_error }
+        end
+
+        # @private Pass the error to user-provided error callbacks.
+        def error! error
+          error_callbacks = synchronize do
+            @last_error = error
+            @error_callbacks.dup
+          end
+          error_callbacks.each { |error_callback| error_callback.call error }
+        end
       end
     end
   end

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

@@ -16,7 +16,7 @@
 module Google
   module Cloud
     module Firestore
-      VERSION = "2.2.0".freeze
+      VERSION = "2.3.0".freeze
     end
   end
 end

data/lib/google/cloud/firestore/watch/listener.rb

@@ -30,7 +30,7 @@ module Google
         class Listener
           include MonitorMixin
 
-          def self.for_doc_ref doc_ref, &callback
+          def self.for_doc_ref parent, doc_ref, &callback
             raise ArgumentError if doc_ref.nil?
             raise ArgumentError if callback.nil?
 
@@ -44,10 +44,10 @@ module Google
               )
             )
 
-            new nil, doc_ref, doc_ref.client, init_listen_req, &callback
+            new parent, nil, doc_ref, doc_ref.client, init_listen_req, &callback
           end
 
-          def self.for_query query, &callback
+          def self.for_query parent, query, &callback
             raise ArgumentError if query.nil?
             raise ArgumentError if callback.nil?
 
@@ -61,12 +61,13 @@ module Google
               )
             )
 
-            new query, nil, query.client, init_listen_req, &callback
+            new parent, query, nil, query.client, init_listen_req, &callback
           end
 
-          def initialize query, doc_ref, client, init_listen_req, &callback
+          def initialize parent, query, doc_ref, client, init_listen_req, &callback
             super() # to init MonitorMixin
 
+            @parent = parent
             @query = query
             @doc_ref = doc_ref
             @client = client
@@ -119,6 +120,8 @@ module Google
 
           def send_callback query_snp
             @callback.call query_snp
+          rescue StandardError => e
+            @parent.error! e
           end
 
           def start_listening!
@@ -270,25 +273,29 @@ module Google
             @request_queue.push self
           rescue GRPC::Cancelled, GRPC::DeadlineExceeded, GRPC::Internal,
                  GRPC::ResourceExhausted, GRPC::Unauthenticated,
-                 GRPC::Unavailable, GRPC::Core::CallError
+                 GRPC::Unavailable, GRPC::Core::CallError => e
             # Restart the stream with an incremental back for a retriable error.
             # Also when GRPC raises the internal CallError.
 
-            # Re-raise if retried more than the max
-            raise err if @backoff[:current] > @backoff[:max]
-
-            # Sleep with incremental backoff before restarting
-            sleep @backoff[:delay]
+            # Raise if retried more than the max
+            if @backoff[:current] > @backoff[:max]
+              @parent.error! e
+              raise e
+            else
+              # Sleep with incremental backoff before restarting
+              sleep @backoff[:delay]
 
-            # Update increment backoff delay and retry counter
-            @backoff[:delay] *= @backoff[:mod]
-            @backoff[:current] += 1
+              # Update increment backoff delay and retry counter
+              @backoff[:delay] *= @backoff[:mod]
+              @backoff[:current] += 1
 
-            retry
+              retry
+            end
           rescue RestartStream
             retry
           rescue StandardError => e
-            raise Google::Cloud::Error.from_error(e)
+            @parent.error! e
+            raise e
           end
         end
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-firestore
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Google Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-17 00:00:00.000000000 Z
+date: 2020-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-core