distributed-lock-google-cloud-storage 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6262a932fc426a59ec6e6e4515fb925d282e04eb972fd78eb75daa0a81602a98
-  data.tar.gz: 408ae99f1f70e1e13a3f7bd9ee37384291e85dccc933b167259e3863a669043d
+  metadata.gz: 2ba7bdb482b1bf1a10c8c3933ff8680d980099de2c66fd8cf0f1aac0db7c258d
+  data.tar.gz: 4597cc7ffd7ae791808eb677c875b62f19d48bcd8ff83c63a38a2f4683ec2829
 SHA512:
-  metadata.gz: d6d47baecddc7660d441c1ef72b9a33337d5763b90e3f7b85a22499ecd3bd2ac2b82649175e36d0e15b38c89bc45722334716d512c8c34e1947cffc72fd7a7f2
-  data.tar.gz: 4abf33f73e4a443a6c93fdcecabe0f7efefccbcea7d56fd448a9448596d8834b93850963c5b39a1a97a9557fead5bb0c9fcd3e807d56a67a37d1d8f545fa5896
+  metadata.gz: 323019ce82a1dda8252a9332dca0e024f5801ec5367320ad7e2133712cc55e35060f9fc2fb1bed1545dbfe333477b1498a2e410f4a77551d993ae7838e6f67eb
+  data.tar.gz: 2b7d1b8ff59ddfdd14d100fdd67420e57b54c2c87688ccfbbceff53c6b22561630e1f7c2a5803bb9329650f818134b514d5238264251af944024950a6260047c

data/lib/distributed-lock-google-cloud-storage/lock.rb

@@ -11,6 +11,7 @@ require_relative 'utils'
 module DistributedLock
   module GoogleCloudStorage
     class Lock
+      # @!visibility private
       DEFAULT_INSTANCE_IDENTITY_PREFIX_WITHOUT_PID = SecureRandom.hex(12).freeze
 
       include Utils
@@ -65,13 +66,13 @@ module DistributedLock
       #   when acquiring the lock fails. Must be at least 0.
       # @param object_acl [String, nil] A predefined set of access control to apply to the Cloud Storage
       #   object. See the `acl` parameter in
-      #   [https://googleapis.dev/ruby/google-cloud-storage/latest/Google/Cloud/Storage/Bucket.html#create_file-instance_method](Google::Cloud::Storage::Bucket#create_file)
+      #   [Google::Cloud::Storage::Bucket#create_file](https://googleapis.dev/ruby/google-cloud-storage/latest/Google/Cloud/Storage/Bucket.html#create_file-instance_method)
       #   for acceptable values.
       # @param cloud_storage_options [Hash, nil] Additional options to pass to
-      #   {https://googleapis.dev/ruby/google-cloud-storage/latest/Google/Cloud/Storage.html#new-class_method Google::Cloud::Storage.new}.
+      #   [Google::Cloud::Storage.new](https://googleapis.dev/ruby/google-cloud-storage/latest/Google/Cloud/Storage.html#new-class_method).
       #   See its documentation to learn which options are available.
       # @param cloud_storage_bucket_options [Hash, nil] Additional options to pass to
-      #   {https://googleapis.dev/ruby/google-cloud-storage/latest/Google/Cloud/Storage/Project.html#bucket-instance_method Google::Cloud::Storage::Project#bucket}.
+      #   [Google::Cloud::Storage::Project#bucket](https://googleapis.dev/ruby/google-cloud-storage/latest/Google/Cloud/Storage/Project.html#bucket-instance_method).
       #   See its documentation to learn which options are available.
       #
       # @note The logger must either be thread-safe, or all writes to this logger by anything besides
@@ -119,6 +120,7 @@ module DistributedLock
         @owner = nil
         @metageneration = nil
         @refresher_thread = nil
+        @refresher_error = nil
 
         # The refresher generation is incremented every time we shutdown
         # the refresher thread. It allows the refresher thread to know
@@ -256,7 +258,7 @@ module DistributedLock
       # obtained by some other instance identity, waits until it becomes available,
       # or until timeout.
       #
-      # Accepts the same parameters as #lock.
+      # Accepts the same parameters as {#lock}.
       #
       # @return The block's return value.
       # @raise [AlreadyLockedError] This Lock instance — according to its internal state — believes
@@ -273,10 +275,10 @@ module DistributedLock
 
       # Pretends like we've never obtained this lock, abandoning our internal state about the lock.
       #
-      # Shuts down background lock refreshing, and ensures that
-      # #locked_according_to_internal_state? returns false.
+      # Shuts down background lock refreshing, and ensures that {#locked_according_to_internal_state?}
+      # returns false.
       #
-      # Does not modify any server data, so #locked_according_to_server? may still return true.
+      # Does not modify any server data, so {#locked_according_to_server?} may still return true.
       #
       # @return [void]
       def abandon
@@ -302,15 +304,19 @@ module DistributedLock
       # Returns whether the lock is healthy. A lock is considered healthy until
       # we fail to refresh the lock too many times consecutively.
       #
-      # Failure to refresh could happen for many reasons, including but not limited
-      # to: network problems, the lock object being forcefully deleted by someone else.
+      # Failure to refresh could happen for many reasons. Some failures are temporary, such
+      # as network problems. Others are permanent, such as the lock object being forcefully
+      # deleted by someone else.
       #
-      # "Too many" is defined by the `max_refresh_fails` argument passed to the constructor.
+      # Upon encountering a permanent failure, the lock is immediately declared unhealthy.
+      # Upon encountering a temporary failure, the lock is declared unhealthy after encountering
+      # a temporary error `max_refresh_fails` times consecutively.
       #
       # It only makes sense to call this method after having obtained this lock.
       #
       # @return [Boolean]
       # @raise [NotLockedError] This lock was not obtained.
+      # @see #last_refresh_error
       def healthy?
         @state_mutex.synchronize do
           raise NotLockedError, 'Not locked' if !unsynced_locked_according_to_internal_state?
@@ -318,7 +324,9 @@ module DistributedLock
         end
       end
 
-      # Checks whether the lock is healthy. See #healthy? for the definition of "healthy".
+      # Checks whether the lock is healthy. See {#healthy?} for the definition of "healthy".
+      # Use {#last_refresh_error} to query the last error that caused the lock to be declared
+      # unhealthy.
       #
       # It only makes sense to call this method after having obtained this lock.
       #
@@ -329,6 +337,19 @@ module DistributedLock
         raise LockUnhealthyError, 'Lock is not healthy' if !healthy?
       end
 
+      # Returns the last error that caused the lock to be declared unhealthy.
+      #
+      # Don't use this method to check whether the lock is _currently_ healthy.
+      # If this lock has ever been unhealthy, then this method returns a non-nil value
+      # even if the lock is currently healthy.
+      #
+      # @return [StandardError, nil]
+      def last_refresh_error
+        @state_mutex.synchronize do
+          @refresher_error
+        end
+      end
+
 
       private
 
@@ -429,9 +450,7 @@ module DistributedLock
       def delete_lock_object(expected_metageneration)
         file = @bucket.file(@path, skip_lookup: true)
         file.delete(if_metageneration_match: expected_metageneration)
-      rescue Google::Cloud::NotFoundError
-        false
-      rescue Google::Cloud::FailedPreconditionError
+      rescue Google::Cloud::NotFoundError, Google::Cloud::FailedPreconditionError
         false
       end
 
@@ -563,7 +582,17 @@ module DistributedLock
           end
           log_debug { "Done refreshing lock. metageneration=#{file.metageneration}" }
           true
+
         rescue => e
+          @state_mutex.synchronize do
+            if @refresher_generation != refresher_generation
+              log_debug { 'Abort refreshing lock' }
+              return true
+            end
+
+            @refresher_error = e
+          end
+
           log_error { "Error refreshing lock: #{e}" }
           [false, permanent_failure]
         end

data/lib/distributed-lock-google-cloud-storage/utils.rb

@@ -2,6 +2,7 @@
 
 module DistributedLock
   module GoogleCloudStorage
+    # @!visibility private
     module Utils
       private
 

data/lib/distributed-lock-google-cloud-storage/version.rb

@@ -3,7 +3,7 @@
 module DistributedLock
   module GoogleCloudStorage
     module Version
-      VERSION_STRING = '1.0.0'
+      VERSION_STRING = '1.1.0'
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: distributed-lock-google-cloud-storage
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Hongli Lai
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-09-09 00:00:00.000000000 Z
+date: 2021-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-cloud-storage