cloudtasker-tonix 0.1.0

data/lib/cloudtasker/testing.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require 'cloudtasker/backend/memory_task'
+
+module Cloudtasker
+  # Enable/Disable test mode for Cloudtasker
+  module Testing
+    module_function
+
+    #
+    # Set the test mode, either permanently or
+    # temporarily (via block).
+    #
+    # @param [Symbol] mode The test mode.
+    #
+    # @return [Symbol] The test mode.
+    #
+    def switch_test_mode(mode)
+      if block_given?
+        current_mode = @test_mode
+        begin
+          @test_mode = mode
+          yield
+        ensure
+          @test_mode = current_mode
+        end
+      else
+        @test_mode = mode
+      end
+    end
+
+    #
+    # Set the error mode, either permanently or
+    # temporarily (via block).
+    #
+    # @param [Symbol] mode The error mode.
+    #
+    # @return [Symbol] The error mode.
+    #
+    def switch_error_mode(mode)
+      if block_given?
+        current_mode = @error_mode
+        begin
+          @error_mode = mode
+          yield
+        ensure
+          @error_mode = current_mode
+        end
+      else
+        @error_mode = mode
+      end
+    end
+
+    #
+    # Set cloudtasker to real mode temporarily
+    #
+    # @param [Proc] &block The block to run in real mode
+    #
+    def enable!(&block)
+      switch_test_mode(:enabled, &block)
+    end
+
+    #
+    # Set cloudtasker to fake mode temporarily
+    #
+    # @param [Proc] &block The block to run in fake mode
+    #
+    def fake!(&block)
+      switch_test_mode(:fake, &block)
+    end
+
+    #
+    # Set cloudtasker to inline mode temporarily
+    #
+    # @param [Proc] &block The block to run in inline mode
+    #
+    def inline!(&block)
+      switch_test_mode(:inline, &block)
+    end
+
+    #
+    # Return true if Cloudtasker is enabled.
+    #
+    def enabled?
+      !@test_mode || @test_mode == :enabled
+    end
+
+    #
+    # Return true if Cloudtasker is in fake mode.
+    #
+    # @return [Boolean] True if jobs must be processed through drain calls.
+    #
+    def fake?
+      @test_mode == :fake
+    end
+
+    #
+    # Return true if Cloudtasker is in inline mode.
+    #
+    # @return [Boolean] True if jobs are run inline.
+    #
+    def inline?
+      @test_mode == :inline
+    end
+
+    #
+    # Temporarily raise errors in the same manner
+    # inline! does it.
+    #
+    # This is used when you want to manually drain the jobs
+    # but still want to surface errors at runtime, instead of
+    # using the retry mechanic.
+    #
+    def raise_errors!(&block)
+      switch_error_mode(:raise, &block)
+    end
+
+    #
+    # Temporarily silence errors. Job will follow the retry logic.
+    #
+    def silence_errors!(&block)
+      switch_error_mode(:silence, &block)
+    end
+
+    #
+    # Return true if jobs should raise errors immediately
+    # without relying on retries.
+    #
+    # @return [Boolean] True if jobs are run inline.
+    #
+    def raise_errors?
+      @test_mode == :inline || @error_mode == :raise
+    end
+
+    #
+    # Return true if tasks should be managed in memory.
+    #
+    # @return [Boolean] True if jobs are managed in memory.
+    #
+    def in_memory?
+      !enabled?
+    end
+  end
+
+  # Add extra methods for testing purpose
+  module Worker
+    #
+    # Clear all jobs.
+    #
+    def self.clear_all
+      Backend::MemoryTask.clear
+    end
+
+    #
+    # Run all the jobs.
+    #
+    # @return [Array<any>] The return values of the workers perform method.
+    #
+    def self.drain_all
+      Backend::MemoryTask.drain
+    end
+
+    # Module class methods
+    module ClassMethods
+      #
+      # Return all jobs related to this worker class.
+      #
+      # @return [Array<Cloudtasker::Backend::MemoryTask>] The list of tasks
+      #
+      def jobs
+        Backend::MemoryTask.all(to_s)
+      end
+
+      #
+      # Run all jobs related to this worker class.
+      #
+      # @return [Array<any>] The return values of the workers perform method.
+      #
+      def drain
+        Backend::MemoryTask.drain(to_s)
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/conflict_strategy/base_strategy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module ConflictStrategy
+      # Base behaviour for conflict strategies
+      class BaseStrategy
+        attr_reader :job
+
+        #
+        # Build a new instance of the class.
+        #
+        # @param [Cloudtasker::UniqueJob::Job] job The UniqueJob job
+        #
+        def initialize(job)
+          @job = job
+        end
+
+        #
+        # Handling logic to perform when a conflict occurs while
+        # scheduling a job.
+        #
+        # We return nil to flag the job as not scheduled
+        #
+        def on_schedule
+          nil
+        end
+
+        #
+        # Handling logic to perform when a conflict occurs while
+        # executing a job.
+        #
+        def on_execute
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/conflict_strategy/raise.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module ConflictStrategy
+      # This strategy raises an error on conflict, both on client and server side.
+      class Raise < BaseStrategy
+        RESCHEDULE_DELAY = 5 # seconds
+
+        # Raise a Cloudtasker::UniqueJob::LockError
+        def on_schedule
+          raise_lock_error
+        end
+
+        # Raise a Cloudtasker::UniqueJob::LockError
+        def on_execute
+          raise_lock_error
+        end
+
+        private
+
+        def raise_lock_error
+          raise(UniqueJob::LockError, id: job.id, unique_id: job.unique_id)
+        end
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/conflict_strategy/reject.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module ConflictStrategy
+      # This strategy rejects the job on conflict. This is equivalent to "do nothing".
+      class Reject < BaseStrategy
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/conflict_strategy/reschedule.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module ConflictStrategy
+      # This strategy reschedules the job on conflict. This strategy can only
+      # be used with processing locks (e.g. while_executing).
+      class Reschedule < BaseStrategy
+        RESCHEDULE_DELAY = 5 # seconds
+
+        #
+        # A conflict on schedule means that this strategy is being used
+        # with a lock scheduling strategy (e.g. until_executed) instead of a
+        # processing strategy (e.g. while_executing). In this case we let the
+        # scheduling happen as it does not make sense to reschedule in this context.
+        #
+        def on_schedule
+          yield
+        end
+
+        #
+        # Reschedule the job.
+        #
+        def on_execute
+          job.worker.reenqueue(RESCHEDULE_DELAY)
+        end
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/job.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    # Wrapper class for Cloudtasker::Worker delegating to lock
+    # and conflict strategies
+    class Job
+      attr_reader :worker, :call_opts
+
+      # The default lock strategy to use. Defaults to "no lock".
+      DEFAULT_LOCK = UniqueJob::Lock::NoOp
+
+      #
+      # Build a new instance of the class.
+      #
+      # @param [Cloudtasker::Worker] worker The worker at hand
+      # @param [Hash] worker The worker options
+      #
+      def initialize(worker, opts = {})
+        @worker = worker
+        @call_opts = opts
+      end
+
+      #
+      # Return the worker configuration options.
+      #
+      # @return [Hash] The worker configuration options.
+      #
+      def options
+        worker.class.cloudtasker_options_hash
+      end
+
+      #
+      # Return the Time To Live (TTL) that should be set in Redis for
+      # the lock key. Having a TTL on lock keys ensures that jobs
+      # do not end up stuck due to a dead lock situation.
+      #
+      # The TTL is calculated using schedule time + expected
+      # max job duration.
+      #
+      # The expected max job duration is set to 10 minutes by default.
+      # This value was chosen because it's twice the default request timeout
+      # value in Cloud Run. This leaves enough room for queue lag (5 minutes)
+      # + job processing (5 minutes).
+      #
+      # Queue lag is certainly the most unpredictable factor here.
+      # Job processing time is less of a factor. Jobs running for more than 5 minutes
+      # should be split into sub-jobs to limit invocation time over HTTP. Cloudtasker batch
+      # jobs can help achieve that if you need to make one big job split into sub-jobs "atomic".
+      #
+      # The default lock key expiration of "time_at + 10 minutes" may look aggressive but it
+      # is still a better choice than potentially having real-time jobs stuck for X hours.
+      #
+      # The expected max job duration can be configured via the `lock_ttl`
+      # option on the job itself.
+      #
+      # @return [Integer] The TTL in seconds
+      #
+      def lock_ttl
+        now = Time.now.to_i
+
+        # Get scheduled at and lock duration
+        scheduled_at = [call_opts[:time_at].to_i, now].compact.max
+        lock_duration = (options[:lock_ttl] || Cloudtasker::UniqueJob.lock_ttl).to_i
+
+        # Return TTL
+        scheduled_at + lock_duration - now
+      end
+
+      #
+      # Return the instantiated lock.
+      #
+      # @return [Any] The instantiated lock
+      #
+      def lock_instance
+        @lock_instance ||=
+          begin
+            # Infer lock class and get instance
+            lock_name = options[:lock]
+            lock_klass = Lock.const_get(lock_name.to_s.split('_').collect(&:capitalize).join)
+            lock_klass.new(self)
+          rescue NameError
+            DEFAULT_LOCK.new(self)
+          end
+      end
+
+      #
+      # Return the list of arguments used for job uniqueness.
+      #
+      # @return [Array<any>] The list of unique arguments
+      #
+      def unique_args
+        worker.try(:unique_args, worker.job_args) || worker.job_args
+      end
+
+      #
+      # Return a unique description of the job in hash format.
+      #
+      # @return [Hash] Representation of the unique job in hash format.
+      #
+      def digest_hash
+        @digest_hash ||= {
+          class: worker.class.to_s,
+          unique_args: unique_args
+        }
+      end
+
+      #
+      # Return the worker job ID.
+      #
+      # @return [String] The worker job ID.
+      #
+      def id
+        worker.job_id
+      end
+
+      #
+      # Return the ID of the unique job.
+      #
+      # @return [String] The ID of the job.
+      #
+      def unique_id
+        Digest::SHA256.hexdigest(digest_hash.to_json)
+      end
+
+      #
+      # Return the Global ID of the unique job. The gid
+      # includes the UniqueJob namespace.
+      #
+      # @return [String] The global ID of the job
+      #
+      def unique_gid
+        [self.class.to_s.underscore, unique_id].join('/')
+      end
+
+      #
+      # Return the Cloudtasker redis client.
+      #
+      # @return [Cloudtasker::RedisClient] The cloudtasker redis client.
+      #
+      def redis
+        @redis ||= Cloudtasker::RedisClient.new
+      end
+
+      #
+      # Acquire a new unique job lock or check that the lock is
+      # currently allocated to this job.
+      #
+      # Raise a `Cloudtasker::UniqueJob::LockError` if the lock
+      # if taken by another job.
+      #
+      def lock!
+        lock_acquired = redis.set(unique_gid, id, nx: true, ex: lock_ttl)
+        lock_already_acquired = !lock_acquired && redis.get(unique_gid) == id
+
+        raise(LockError) unless lock_acquired || lock_already_acquired
+      end
+
+      #
+      # Delete the job lock.
+      #
+      def unlock!
+        locked_id = redis.get(unique_gid)
+        redis.del(unique_gid) if locked_id == id
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/lock/base_lock.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module Lock
+      # Base behaviour for locks
+      class BaseLock
+        attr_reader :job
+
+        #
+        # Build a new instance of the class.
+        #
+        # @param [Cloudtasker::UniqueJob::Job] job The UniqueJob job
+        #
+        def initialize(job)
+          @job = job
+        end
+
+        #
+        # Return the worker configuration options.
+        #
+        # @return [Hash] The worker configuration options.
+        #
+        def options
+          job.options
+        end
+
+        #
+        # Return the strategy to use by default. Can be overriden in each lock.
+        #
+        # @return [Cloudtasker::UniqueJob::ConflictStrategy::BaseStrategy] The strategy to use by default.
+        #
+        def default_conflict_strategy
+          ConflictStrategy::Reject
+        end
+
+        #
+        # Return the conflict strategy to use on conflict
+        #
+        # @return [Cloudtasker::UniqueJob::ConflictStrategy::BaseStrategy] The instantiated strategy.
+        #
+        def conflict_instance
+          @conflict_instance ||=
+            begin
+              # Infer lock class and get instance
+              strategy_name = options[:on_conflict]
+              strategy_klass = ConflictStrategy.const_get(strategy_name.to_s.split('_').collect(&:capitalize).join)
+              strategy_klass.new(job)
+            rescue NameError
+              default_conflict_strategy.new(job)
+            end
+        end
+
+        #
+        # Lock logic invoked when a job is scheduled (client middleware).
+        #
+        def schedule
+          yield
+        end
+
+        #
+        # Lock logic invoked when a job is executed (server middleware).
+        #
+        def execute
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/lock/no_op.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module Lock
+      # Equivalent to no lock
+      class NoOp < BaseLock
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/lock/until_completed.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module Lock
+      # Conflict if any other job with the same args is scheduled or moved to execution
+      # while the first job is pending or executing. Unlocks only on successful completion
+      # or when a DeadWorkerError is raised.
+      class UntilCompleted < BaseLock
+        #
+        # Acquire a lock for the job and trigger a conflict
+        # if the lock could not be acquired.
+        #
+        def schedule(&block)
+          job.lock!
+          yield
+        rescue LockError
+          conflict_instance.on_schedule(&block)
+        end
+
+        #
+        # Acquire a lock for the job and trigger a conflict
+        # if the lock could not be acquired.
+        #
+        def execute(&block)
+          job.lock!
+          yield
+          # Unlock on successful completion
+          job.unlock!
+        rescue LockError
+          conflict_instance.on_execute(&block)
+        rescue Cloudtasker::DeadWorkerError
+          # Unlock when DeadWorkerError is raised
+          job.unlock!
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/lock/until_executed.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module Lock
+      # Conflict if any other job with the same args is scheduled or moved to execution
+      # while the first job is pending or executing.
+      class UntilExecuted < BaseLock
+        #
+        # Acquire a lock for the job and trigger a conflict
+        # if the lock could not be acquired.
+        #
+        def schedule(&block)
+          job.lock!
+          yield
+        rescue LockError
+          conflict_instance.on_schedule(&block)
+        end
+
+        #
+        # Acquire a lock for the job and trigger a conflict
+        # if the lock could not be acquired.
+        #
+        def execute(&block)
+          job.lock!
+          yield
+        rescue LockError
+          conflict_instance.on_execute(&block)
+        ensure
+          # Unlock the job on any error to avoid deadlocks.
+          job.unlock!
+        end
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/lock/until_executing.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module Lock
+      # Conflict if any other job with the same args is scheduled
+      # while the first job is pending.
+      class UntilExecuting < BaseLock
+        #
+        # Acquire a lock for the job and trigger a conflict
+        # if the lock could not be acquired.
+        #
+        def schedule(&block)
+          job.lock!
+          yield
+        rescue LockError
+          conflict_instance.on_schedule(&block)
+        end
+
+        #
+        # Release the lock and perform the job.
+        #
+        def execute
+          job.unlock!
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/lock/while_executing.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module Lock
+      # Conflict if any other job with the same args is moved to execution
+      # while the first job is executing.
+      class WhileExecuting < BaseLock
+        #
+        # Acquire a lock for the job and trigger a conflict
+        # if the lock could not be acquired.
+        #
+        def execute(&block)
+          job.lock!
+          yield
+        rescue LockError
+          conflict_instance.on_execute(&block)
+        ensure
+          # Unlock the job on any error to avoid deadlocks.
+          job.unlock!
+        end
+      end
+    end
+  end
+end

data/lib/cloudtasker/unique_job/lock_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    class LockError < StandardError
+    end
+  end
+end

data/lib/cloudtasker/unique_job/middleware/client.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Cloudtasker
+  module UniqueJob
+    module Middleware
+      # TODO: kwargs to job otherwise it won't get the time_at
+      # Client middleware, invoked when jobs are scheduled
+      class Client
+        def call(worker, _opts = {}, &block)
+          Job.new(worker).lock_instance.schedule(&block)
+        end
+      end
+    end
+  end
+end