gcslock 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1068b280fd4e77bb1270880eaa80aa0145d64f35d58121329e8500ecc2321948
+  data.tar.gz: 33b5f11756a7c89f55384730322fd43aebcc810dff452c4cbf13bb05f2920aea
+SHA512:
+  metadata.gz: de5e846755a1c556d263b6af0806b6e102bbd4c474aad7513aa3df8d84d6a8e1afb56b35cc3006e52f76508eac3bc691b5776175142f0e3d1cd9a0fb68ad40fa
+  data.tar.gz: fc5c9318fcdabb46acff6b89b54c9967ed13749c8cda75cc78699d063f233135a126013874667adc4e300c4975d82ad8da0971f1a972aed23ae01fdf236001b7

data/.gitignore

@@ -0,0 +1,5 @@
+._*
+tmp/
+Gemfile.lock
+.bundle/config
+.byebug_history

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/README.md

@@ -0,0 +1,21 @@
+# gcslock-ruby
+
+This is inspired by [the Golang version](https://github.com/marcacohen/gcslock).
+
+## Google Cloud Storage setup
+
+1. Setup a new project at the [Google APIs Console](https://console.developers.google.com) and enable the Cloud Storage API.
+1. Install the [Google Cloud SDK](https://cloud.google.com/sdk/downloads) tool and configure your project and your OAuth credentials.
+1. Create a bucket in which to store your lock file using the command `gsutil mb gs://your-bucket-name`.
+1. Enable object versioning in your bucket using the command `gsutil versioning set on gs://your-bucket-name`.
+1. In your Ruby code, require `gcslock/mutex` and use it as follows:
+
+```ruby
+require 'gcslock/mutex'
+
+m = GCSLock::Mutex.new('your-bucket-name', 'my-file.lock')
+m.synchronize do
+  // Protected and globally serialized computation happens here.
+end
+```
+

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load(Gem.bin_path('rspec-core', 'rspec'))

data/gcslock.gemspec

@@ -0,0 +1,29 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gcslock/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'gcslock'
+  spec.version = GCSLock::VERSION
+  spec.authors = ['Raphaël Beamonte']
+  spec.email = ['raphael.beamonte@gmail.com']
+
+  spec.summary = 'Google Cloud Storage distributed locking'
+  spec.description = "Allows to use a Google Cloud Storage bucket as a distributed locking system"
+  spec.homepage = 'https://github.com/XaF/gcslock-ruby'
+  spec.license = 'MIT'
+
+  raise "RubyGems 2.0 or newer is required to protect against public gem pushes." unless spec.respond_to?(:metadata)
+  spec.metadata['allowed_push_host'] = "https://rubygems.org"
+
+  spec.files = %x(git ls-files -z).split("\x0").reject { |f| f.match(/^(test|DESIGN)/) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version = '>= 2.0'
+
+  spec.add_runtime_dependency 'google-api-client'
+  spec.add_runtime_dependency 'google-cloud-storage', '~> 1.26.1'
+
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'codecov'
+end

data/lib/gcslock/errors.rb

@@ -0,0 +1,7 @@
+module GCSLock
+  class Error < StandardError; end
+  class LockAlreadyOwnedError < Error; end
+  class LockNotOwnedError < Error; end
+  class LockNotFoundError < Error; end
+  class LockTimeoutError < Error; end
+end

data/lib/gcslock/mutex.rb

@@ -0,0 +1,97 @@
+require 'google/cloud/storage'
+require 'securerandom'
+
+require_relative 'errors'
+
+module GCSLock
+  class Mutex
+    def initialize(bucket, object, client: nil, uuid: nil, min_backoff: nil, max_backoff: nil)
+      @client = client || Google::Cloud::Storage.new
+      @bucket = @client.bucket(bucket, skip_lookup: true)
+      @object = @bucket.file(object, skip_lookup: true)
+
+      @uuid = uuid || SecureRandom.uuid
+      @min_backoff = min_backoff || 0.01
+      @max_backoff = max_backoff || 5.0
+    end
+
+    # Attempts to grab the lock and waits if it isn't available.
+    # Raises `ThreadError` if `mutex` was locked by the current thread.
+    def lock(timeout: nil)
+      raise LockAlreadyOwnedError, "Mutex for #{@object.name} is already owned by this process" if owned?
+
+      backoff = @min_backoff
+      waited = 0.0 unless timeout.nil?
+
+      loop do
+        return true if try_lock
+        break if !timeout.nil? && waited + backoff > timeout
+        sleep(backoff)
+
+        backoff_opts = [@max_backoff, backoff * 2]
+
+        unless timeout.nil?
+          waited += backoff
+          backoff_opts.push(timeout - waited) if timeout > waited
+        end
+
+        backoff = backoff_opts.min
+      end
+
+      raise LockTimeoutError, "Unable to get mutex for #{@object.name} before timeout"
+    end
+
+    # Returns `true` if this lock is currently held by some thread.
+    def locked?
+      @object.reload!
+      @object.exists?
+    end
+
+    # Returns `true` if this lock is currently held by current thread.
+    def owned?
+      locked? && @object.size == @uuid.size && @object.download.read == @uuid
+    end
+
+    # Obtains a lock, runs the block, and releases the lock when the block completes.
+    # Raises `LockAlreadyOwnedError` if the lock is already owned by the current instance.
+    def synchronize(timeout: nil)
+      raise LockAlreadyOwnedError, "Mutex for #{@object.name} is already owned by this process" if owned?
+
+      lock(timeout: timeout)
+      begin
+        yield
+      ensure
+        unlock
+      end
+    end
+
+    # Attempts to obtain the lock and returns immediately. Returns `true` if the lock was granted.
+    def try_lock
+      @client.service.service.insert_object(
+        @bucket.name,
+        name: @object.name,
+        if_generation_match: 0,
+        upload_source: StringIO.new(@uuid),
+      )
+
+      true
+    rescue Google::Apis::ClientError => e
+      raise unless e.status_code == 412 && e.message.start_with?('conditionNotMet:')
+
+      false
+    end
+
+    # Releases the lock. Raises `LockNotOwnedError` if the lock is not owned by the current instance.
+    def unlock
+      raise LockNotOwnedError, "Mutex for #{@object.name} is not owned by this process" unless owned?
+      @object.delete
+    end
+
+    # Releases the lock even if not owned by this instance. Raises `LockNotFoundError` if the lock cannot be found.
+    def unlock!
+      @object.delete
+    rescue Google::Cloud::NotFoundError => e
+      raise LockNotFoundError, "Mutex for #{@object.name} not found"
+    end
+  end
+end

data/lib/gcslock/version.rb

@@ -0,0 +1,3 @@
+module GCSLock
+  VERSION = '1.0.0'.freeze
+end

data/spec/gcslock/mutex_spec.rb

@@ -0,0 +1,308 @@
+require 'spec_helper'
+require 'gcslock/mutex'
+
+describe GCSLock::Mutex do
+  before do
+    @bucket_name = 'bucket'
+    @object_name = 'object'
+
+    @gcs = instance_double(Google::Cloud::Storage::Project)
+    allow(Google::Cloud::Storage).to receive(:new).and_return(@gcs)
+
+    @bucket = instance_double(Google::Cloud::Storage::Bucket)
+    allow(@bucket).to receive(:name).and_return(@bucket_name)
+    allow(@gcs).to receive(:bucket).and_return(@bucket)
+
+    @object = instance_double(Google::Cloud::Storage::File)
+    allow(@object).to receive(:name).and_return(@object_name)
+    allow(@bucket).to receive(:file).and_return(@object)
+
+    @uuid = 'some_uuid'
+    allow(SecureRandom).to receive(:uuid).and_return(@uuid)
+  end
+
+  describe '.initialize' do
+    before do
+      @gcs = double(Google::Cloud::Storage)
+      allow(Google::Cloud::Storage).to receive(:new).and_return(@gcs)
+
+      @bucket = double(Google::Cloud::Storage::Bucket)
+      allow(@gcs).to receive(:bucket).and_return(@bucket)
+
+      @object = double(Google::Cloud::Storage::File)
+      allow(@bucket).to receive(:file).and_return(@object)
+    end
+
+    it 'initializes in GCS client when none provided' do
+      expect(Google::Cloud::Storage).to receive(:new).once
+
+      GCSLock::Mutex.new(@bucket_name, @object_name)
+    end
+
+    it 'initializes in GCS client when none provided' do
+      expect(Google::Cloud::Storage).not_to receive(:new)
+
+      GCSLock::Mutex.new(@bucket_name, @object_name, client: @gcs)
+    end
+
+    it 'initializes a bucket with lazy loading' do
+      expect(Google::Cloud::Storage).to receive(:new).once
+      expect(@gcs).to receive(:bucket).with(@bucket_name, skip_lookup: true).once
+
+      GCSLock::Mutex.new(@bucket_name, @object_name)
+    end
+
+    it 'initializes a file with lazy loading' do
+      expect(Google::Cloud::Storage).to receive(:new).once
+      expect(@bucket).to receive(:file).with(@object_name, skip_lookup: true).once
+
+      GCSLock::Mutex.new(@bucket_name, @object_name)
+    end
+
+    it 'initializes a randomly generated unique ID' do
+      expect(SecureRandom).to receive(:uuid).once
+
+      GCSLock::Mutex.new(@bucket_name, @object_name)
+    end
+  end
+
+  context 'initialized' do
+    before do
+      @mutex = GCSLock::Mutex.new(@bucket_name, @object_name)
+    end
+
+    describe '.lock' do
+      it 'sleeps and retry when failing on the first try_lock' do
+        expect(@mutex).to receive(:owned?).once.and_return(false)
+        expect(@mutex).to receive(:try_lock).once.and_return(false)
+        expect(@mutex).to receive(:sleep).once
+        expect(@mutex).to receive(:try_lock).once.and_return(true)
+
+        @mutex.lock(timeout: 2)
+      end
+
+      it 'sleeps just the time needed to retry once at the end' do
+        expect(@mutex).to receive(:owned?).once.and_return(false)
+        expect(@mutex).to receive(:sleep).exactly(2).times
+        expect(@mutex).to receive(:try_lock).exactly(3).times.and_return(false)
+
+        expect do
+          @mutex.lock(timeout: 0.03)
+        end.to raise_error(GCSLock::LockTimeoutError)
+      end
+
+      it 'raises an error if unable to get the lock when reaching the timeout' do
+        expect(@mutex).to receive(:owned?).once.and_return(false)
+        expect(@mutex).to receive(:try_lock).once.and_return(false)
+
+        expect do
+          @mutex.lock(timeout: 0)
+        end.to raise_error(GCSLock::LockTimeoutError)
+      end
+
+      it 'raises an error if the lock is already owned' do
+        expect(@mutex).to receive(:owned?).once.and_return(true)
+        expect(@mutex).not_to receive(:try_lock)
+
+        expect do
+          @mutex.lock
+        end.to raise_error(GCSLock::LockAlreadyOwnedError)
+      end
+    end
+
+    describe '.locked?' do
+      before do
+        allow(@object).to receive(:reload!)
+        allow(@object).to receive(:exists?)
+      end
+
+      it 'calls reload! on the lock file' do
+        expect(@object).to receive(:reload!).once
+
+        @mutex.locked?
+      end
+
+      it 'calls exists? on the lock file' do
+        expect(@object).to receive(:exists?).once
+
+        @mutex.locked?
+      end
+
+      it 'returns true if exists is true' do
+        expect(@object).to receive(:exists?).once.and_return(true)
+
+        expect(@mutex.locked?).to be(true)
+      end
+
+      it 'returns false if exists is false' do
+        expect(@object).to receive(:exists?).once.and_return(false)
+
+        expect(@mutex.locked?).to be(false)
+      end
+    end
+
+    describe '.owned?' do
+      it 'returns false if mutex is not locked' do
+        expect(@mutex).to receive(:locked?).once.and_return(false)
+
+        expect(@mutex.owned?).to be(false)
+      end
+
+      it 'returns false if mutex is locked but object size != uuid size' do
+        expect(@mutex).to receive(:locked?).once.and_return(true)
+        expect(@object).to receive(:size).once.and_return(@uuid.size + 10)
+
+        expect(@mutex.owned?).to be(false)
+      end
+
+      it 'returns false if mutex is locked and object size == uuid size but object content != uuid' do
+        expect(@mutex).to receive(:locked?).once.and_return(true)
+        expect(@object).to receive(:size).once.and_return(@uuid.size)
+
+        download = StringIO.new('blah')
+        expect(@object).to receive(:download).once.and_return(download)
+
+        expect(@mutex.owned?).to be(false)
+      end
+
+      it 'returns true if mutex is locked and object contains uuid' do
+        expect(@mutex).to receive(:locked?).once.and_return(true)
+        expect(@object).to receive(:size).once.and_return(@uuid.size)
+
+        download = StringIO.new(@uuid)
+        expect(@object).to receive(:download).once.and_return(download)
+
+        expect(@mutex.owned?).to be(true)
+      end
+    end
+
+    describe '.synchronize' do
+      it 'locks, yields and unlock the mutex' do
+        expect(@mutex).to receive(:owned?).once.and_return(false)
+        expect(@mutex).to receive(:lock).once.and_return(true)
+        expect(@mutex).to receive(:unlock).once
+
+        has_yielded = false
+        @mutex.synchronize do
+          has_yielded = true
+        end
+
+        expect(has_yielded).to be(true)
+      end
+
+      it 'raises an error if the lock is already owned' do
+        expect(@mutex).to receive(:owned?).once.and_return(true)
+        expect(@mutex).not_to receive(:lock)
+        expect(@mutex).not_to receive(:unlock)
+
+        has_yielded = false
+
+        expect do
+          @mutex.synchronize do
+            has_yielded = true
+          end
+        end.to raise_error(GCSLock::LockAlreadyOwnedError)
+
+        expect(has_yielded).to be(false)
+      end
+    end
+
+    describe '.try_lock' do
+      before do
+        @service = instance_double(Google::Cloud::Storage::Service)
+        allow(@gcs).to receive(:service).and_return(@service)
+
+        @servicev1 = instance_double(Google::Apis::StorageV1::StorageService)
+        allow(@service).to receive(:service).and_return(@servicev1)
+      end
+
+      it 'returns true if lock obtained' do
+        expect(@servicev1).to receive(:insert_object).with(
+          @bucket_name,
+          name: @object_name,
+          if_generation_match: 0,
+          upload_source: instance_of(StringIO),
+        ).once
+
+        expect(@mutex.try_lock).to be(true)
+      end
+
+      it 'returns false if lock already taken (precondition failed)' do
+        client_error = Google::Apis::ClientError.new('conditionNotMet: Precondition failed', status_code: 412)
+
+        expect(@servicev1).to receive(:insert_object).with(
+          @bucket_name,
+          name: @object_name,
+          if_generation_match: 0,
+          upload_source: instance_of(StringIO),
+        ).once.and_raise(client_error)
+
+        expect(@mutex.try_lock).to be(false)
+      end
+
+      it 'raises in case of precondition failed for other reason than conditionNotMet' do
+        client_error = Google::Apis::ClientError.new('blah: Precondition failed', status_code: 412)
+
+        expect(@servicev1).to receive(:insert_object).with(
+          @bucket_name,
+          name: @object_name,
+          if_generation_match: 0,
+          upload_source: instance_of(StringIO),
+        ).once.and_raise(client_error)
+
+        expect do
+          @mutex.try_lock
+        end.to raise_error(client_error)
+      end
+
+      it 'raises in case of other error than precondition failed' do
+        client_error = Google::Apis::ClientError.new('blah', status_code: 400)
+
+        expect(@servicev1).to receive(:insert_object).with(
+          @bucket_name,
+          name: @object_name,
+          if_generation_match: 0,
+          upload_source: instance_of(StringIO),
+        ).once.and_raise(client_error)
+
+        expect do
+          @mutex.try_lock
+        end.to raise_error(client_error)
+      end
+    end
+
+    describe '.unlock' do
+      it 'calls delete on the object if lock is owned' do
+        expect(@mutex).to receive(:owned?).once.and_return(true)
+        expect(@object).to receive(:delete).once
+
+        @mutex.unlock
+      end
+
+      it 'raises an error if the lock is not owned' do
+        expect(@mutex).to receive(:owned?).once.and_return(false)
+        expect(@object).not_to receive(:delete)
+
+        expect do
+          @mutex.unlock
+        end.to raise_error(GCSLock::LockNotOwnedError)
+      end
+    end
+
+    describe '.unlock!' do
+      it 'calls delete on the object' do
+        expect(@object).to receive(:delete).once
+
+        @mutex.unlock!
+      end
+
+      it 'raises an error if the object is not found' do
+        expect(@object).to receive(:delete).once.and_raise(Google::Cloud::NotFoundError.new('blah'))
+
+        expect do
+          @mutex.unlock!
+        end.to raise_error(GCSLock::LockNotFoundError)
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+if ENV['COVERAGE'] || ENV['CI'] == 'true'
+  require 'simplecov'
+
+  SimpleCov.start
+  if ENV['CI'] == 'true'
+    require 'codecov'
+    SimpleCov.formatter = SimpleCov::Formatter::Codecov
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: gcslock
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Raphaël Beamonte
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: google-api-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: google-cloud-storage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.26.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.26.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Allows to use a Google Cloud Storage bucket as a distributed locking
+  system
+email:
+- raphael.beamonte@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- bin/rspec
+- gcslock.gemspec
+- lib/gcslock/errors.rb
+- lib/gcslock/mutex.rb
+- lib/gcslock/version.rb
+- spec/gcslock/mutex_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/XaF/gcslock-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Google Cloud Storage distributed locking
+test_files: []