cloudtasker 0.15.rc2 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42cff7c50d99de1f66e83e04a3946c7cf370ce03004ee47dc7ee3dcbb46564c8
-  data.tar.gz: 26997c5f357a41563a074e2d03ea2724c3824b46a4b034e45b9e5573d4024cbe
+  metadata.gz: 9ff26870d0e8805c1d799e77ca9e75904ed73f662fe19fa2296f79e276948b86
+  data.tar.gz: ab653c93ebda2b48aac08af8046324e7ee2ff14b368e9bbb656b1a7f79793749
 SHA512:
-  metadata.gz: 0aa102da9cbc6ba0d108eb5d3be521efd954544bc7f4a47c11830401c61d2e590cbad7d7d540448dd4c41df7d11774c663c519a1b044518dc1a7c9f46c2c5906
-  data.tar.gz: b415391333360f336f0553297206ce725df0d617a14f3dc0a8fe8c8fb81b7ead8b9fbe92f608ba75214af0469161b2abf1aab65c9b400900a7e5b047d6ed4a18
+  metadata.gz: 36ab5b779f9e7a56090983cfb82384c15a299bfd1300ce13fab1074bef6616c465269a766d1bc0b30a536336608d96359ee4cf26ff575590155afd3606ee4b3a
+  data.tar.gz: 98a7468f308d8ec6963b4909783a34e0257825c3a307610d05d7dbbd24e67030d880c3b5de273a589b327feee1def92396247c012c580db8eb532fb9628ee572

data/.github/workflows/test_ruby_3.x.yml

@@ -32,7 +32,7 @@ jobs:
       BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.appraisal }}.gemfile
     steps:
       - uses: actions/checkout@v2
-      - uses: zhulik/redis-action@1.1.0
+      - uses: shogo82148/actions-setup-redis@v1
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby }}

data/.rubocop.yml

@@ -12,7 +12,7 @@ Metrics/ClassLength:
   Max: 300
 
 Metrics/ModuleLength:
-  Max: 150
+  Max: 300
 
 Metrics/AbcSize:
   Max: 30
@@ -68,10 +68,14 @@ RSpec/MessageSpies:
   Enabled: false
 
 RSpec/MultipleExpectations:
+  Max: 5
   Exclude:
     - "examples/**/*"
     - "spec/integration/**/*"
 
+RSpec/ExampleLength:
+  Max: 10
+
 RSpec/AnyInstance:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,13 +1,26 @@
 # Changelog
 
-## [v0.15.rc2](https://github.com/keypup-io/cloudtasker/tree/v0.15.rc2) (2025-11-13)
+## [v0.15.0](https://github.com/keypup-io/cloudtasker/tree/v0.15.0) (2026-06-26)
 
-[Full Changelog](https://github.com/keypup-io/cloudtasker/compare/v0.14.0...v0.15.rc2)
+[Full Changelog](https://github.com/keypup-io/cloudtasker/compare/v0.14.0...v0.15.0)
 
 **Improvements:**
+- Local Server: allow retry delay to be configured via the env var `LOCAL_SERVER_RETRY_DELAY`
+- Local Server: fix a syntax error on trap handling, which was re-raising an unnecessary exception.
+- Logging: add job `duration` on error logs
+- Logging: log error message as `reason` on `RetryWorkerError`
 - Queues: support `propagate_queue: true` option on `cloudtasker_options` to make workers enqueued inside a job use the runtime queue instead of the default (class-configured or `default`) queue.
+- Testing: add specific `raise_errors!` mode to raise job errors during testing, without having to specifically use `inline_mode`. Using `inline_mode` will still raise errors.
 - Unique Jobs: add `until_completed` strategy to lock jobs until they are completed or have exhausted all retries (thanks @jam-packed).
+- Workers: capture `job_attempts` on workers, which is captured from `X-CloudTasks-TaskRetryCount`
+- Workers: increase the allowed max task size to 1049KB since Google Tasks supports increased payloads
 - Workers: provide `perform_now` method to perform job inline and align with other job frameworks
+- Workers: support a global configuration option to control whether task payloads are base64-encoded. See `base64_encode_body`
+
+**Fixed bugs:**
+- Batch Jobs: prevent rollback of completion status if a completed job is replayed. This may happen if Cloud Tasks times out before the job completes.
+- Batch Jobs: prevent rollback of job statuses due to multiple children completing concurrently and updating the parent job status (race condition in batch completion callback). 
+- Unique Jobs: avoid long-lock on OOM/error while scheduling jobs. An initial short-lived lock is now acquired before scheduling the job, which is then turned into a long-lived lock after the job has been scheduled. This prevents jobs from being enqueued for a fair amount of time after a scheduling crash.
 
 **Maintenance:**
 - Supported rubies: drop support for ruby `2.7`. Cloudtasker now requires ruby `3.0` and above.

data/README.md

@@ -122,7 +122,7 @@ Open a Rails console and enqueue some jobs
   DummyWorker.perform_in(60, 'foo')
 
   # Process job immediately, inline
-  # Supported since: v0.15.rc2
+  # Supported since: v0.15.0
   DummyWorker.perform_now('foo')
 ```
 
@@ -446,6 +446,18 @@ Cloudtasker.configure do |config|
   # Default: true
   #
   # config.local_server_ssl_verify = true
+
+  #
+  # Enable/disable the base64 encoding of task payloads when sent to Google Cloud Tasks.
+  #
+  # Base64-encoding is required for job payloads containing special characters.
+  # The downside is that the Google Cloud Task UI will therefore obfuscate the payload and force users to manually decode the payload to see the actual content.
+  #
+  # Supported since: v0.15.0
+  #
+  # Default: true
+  #
+  # config.base64_encode_body = true
 end
 ```
 
@@ -481,7 +493,7 @@ MyWorker.schedule(args: [arg1, arg2], time_in: 5 * 60, queue: 'critical')
 
 # Perform worker immediately, inline. This will not send the job to
 # the processing queue. Middlewares such as Unique Job, Batch Jobs will still be invoked.
-# Supported since: v0.15.rc2
+# Supported since: v0.15.0
 MyWorker.perform_now(arg1, arg2)
 ```
 
@@ -555,7 +567,7 @@ CriticalWorker.schedule(args: [1], queue: :important)
 ```
 
 ### Propagating the queue in child workers
-**Supported since:** `v0.15.rc2`
+**Supported since:** `v0.15.0`
 
 You can specify `propagate_queue: true` via the `cloudtasker_options` to make workers enqueued inside a job use the runtime queue instead of the default (class-configured or `default`) queue:
 

data/app/controllers/cloudtasker/worker_controller.rb

@@ -63,7 +63,9 @@ module Cloudtasker
     #
     def payload
       # Return content parsed as JSON and add job retries count
-      @payload ||= JSON.parse(json_payload).merge(job_retries: job_retries, task_id: task_id)
+      @payload ||= JSON.parse(json_payload).merge(
+        job_retries: job_retries, job_attempts: job_attempts, task_id: task_id
+      )
     end
 
     #
@@ -75,6 +77,16 @@ module Cloudtasker
       request.headers[Cloudtasker::Config::RETRY_HEADER].to_i
     end
 
+    #
+    # Extract the number of times this task was attempted at runtime.
+    # This includes all attempts (including 50x errors).
+    #
+    # @return [Integer] The number of attempts.
+    #
+    def job_attempts
+      request.headers[Cloudtasker::Config::ATTEMPT_HEADER].to_i
+    end
+
     #
     # Return the Google Cloud Task ID from headers.
     #

data/docs/UNIQUE_JOBS.md

@@ -70,7 +70,7 @@ For each lock strategy the table specifies the lock period (start/end) and which
 | `until_executing` | The job is scheduled | The job starts processing | `reject` (default) or `raise` |
 | `while_executing` | The job starts processing | The job ends processing | `reject` (default), `reschedule` or `raise` |
 | `until_executed` | The job is scheduled | The job ends processing | `reject` (default) or `raise` |
-| `until_completed` | The job is scheduled | The job completes successfully or a `DeadWorkerError` is raised. Supported since `v0.15.rc1`. | `reject` (default) or `raise` |
+| `until_completed` | The job is scheduled | The job completes successfully or a `DeadWorkerError` is raised. Supported since `v0.15.0`. | `reject` (default) or `raise` |
 
 ## Available conflict strategies
 

data/lib/cloudtasker/backend/google_cloud_task_v1.rb

@@ -119,12 +119,16 @@ module Cloudtasker
         # Format dispatch_deadline to Google::Protobuf::Duration
         payload[:dispatch_deadline] = format_protobuf_duration(payload[:dispatch_deadline])
 
-        # Encode job content to support UTF-8. Google Cloud Task
-        # expect content to be ASCII-8BIT compatible (binary)
+        # Setup headers
         payload[:http_request][:headers] ||= {}
         payload[:http_request][:headers][Cloudtasker::Config::CONTENT_TYPE_HEADER] = 'text/json'
-        payload[:http_request][:headers][Cloudtasker::Config::ENCODING_HEADER] = 'Base64'
-        payload[:http_request][:body] = Base64.encode64(payload[:http_request][:body])
+
+        # Conditionally encode job content to support UTF-8.
+        # Google Cloud Task expect content to be ASCII-8BIT compatible (binary)
+        if config.base64_encode_body
+          payload[:http_request][:headers][Cloudtasker::Config::ENCODING_HEADER] = 'Base64'
+          payload[:http_request][:body] = Base64.encode64(payload[:http_request][:body])
+        end
 
         payload.compact
       end

data/lib/cloudtasker/backend/google_cloud_task_v2.rb

@@ -121,12 +121,16 @@ module Cloudtasker
         # Format dispatch_deadline to Google::Protobuf::Duration
         payload[:dispatch_deadline] = format_protobuf_duration(payload[:dispatch_deadline])
 
-        # Encode job content to support UTF-8.
-        # Google Cloud Task expect content to be ASCII-8BIT compatible (binary)
+        # Setup headers
         payload[:http_request][:headers] ||= {}
         payload[:http_request][:headers][Cloudtasker::Config::CONTENT_TYPE_HEADER] = 'text/json'
-        payload[:http_request][:headers][Cloudtasker::Config::ENCODING_HEADER] = 'Base64'
-        payload[:http_request][:body] = Base64.encode64(payload[:http_request][:body])
+
+        # Conditionally encode job content to support UTF-8.
+        # Google Cloud Task expect content to be ASCII-8BIT compatible (binary)
+        if config.base64_encode_body
+          payload[:http_request][:headers][Cloudtasker::Config::ENCODING_HEADER] = 'Base64'
+          payload[:http_request][:body] = Base64.encode64(payload[:http_request][:body])
+        end
 
         payload.compact
       end

data/lib/cloudtasker/backend/memory_task.rb

@@ -17,6 +17,15 @@ module Cloudtasker
         defined?(Cloudtasker::Testing) && Cloudtasker::Testing.inline?
       end
 
+      #
+      # Return true if errors must be raised immediately
+      #
+      # @return [Boolean] True if raise error mode is enabled.
+      #
+      def self.raise_errors?
+        defined?(Cloudtasker::Testing) && Cloudtasker::Testing.raise_errors?
+      end
+
       #
       # Return the task queue. A worker class name
       #
@@ -172,10 +181,10 @@ module Cloudtasker
         resp
       rescue DeadWorkerError => e
         self.class.delete(id)
-        raise(e) if self.class.inline_mode?
+        raise(e) if self.class.raise_errors?
       rescue StandardError => e
         self.job_retries += 1
-        raise(e) if self.class.inline_mode?
+        raise(e) if self.class.raise_errors?
       end
 
       #

data/lib/cloudtasker/batch/job.rb

@@ -35,6 +35,10 @@ module Cloudtasker
       # to be acquired.
       BATCH_MAX_LOCK_WAIT = 60
 
+      # TTL for the completion flag that prevents concurrent children from
+      # triggering multiple on_complete calls.
+      BATCH_COMPLETION_TTL = 100
+
       #
       # Return the cloudtasker redis client
       #
@@ -193,6 +197,15 @@ module Cloudtasker
         "#{batch_state_gid}/state_count/#{state}"
       end
 
+      #
+      # Return the key used to track batch completion.
+      #
+      # @return [String] The batch completion key.
+      #
+      def batch_completion_gid
+        "#{batch_state_gid}/completed"
+      end
+
       #
       # Return the number of jobs in a given state
       #
@@ -314,21 +327,34 @@ module Cloudtasker
       #
       # Update the batch state.
       #
-      # @param [String] job_id The batch id.
+      # @param [String] batch_id The batch id.
       # @param [String] status The status of the sub-batch.
+      # @param [Boolean] force Force update the status even if the registered status is a completion status.
       #
-      def update_state(batch_id, status)
+      def update_state(batch_id, status, force: false)
         migrate_batch_state_to_redis_hash
 
-        # Get current status
-        current_status = redis.hget(batch_state_gid, batch_id)
-        return if current_status == status.to_s
+        # Get stored status and abort if no changes
+        stored_status = redis.hget(batch_state_gid, batch_id)
+        return if stored_status == status.to_s
+
+        # Abort if the job has already been flagged as completed
+        #
+        # A job may be duplicated and run concurrently if Cloud Task times out
+        # before the job completes.
+        #
+        # In this case, the original job keeps running in the background while Cloud Task triggers a retry.
+        # This retry runs in parallel of the hung job. The retry may complete before the hung job.
+        # The hung job may eventually raise an error (e.g. timeout error) after the retried job has completed,
+        # which would leave the job status as "errored" instead of "completed in the batch state without
+        # the failsafe below.
+        return if COMPLETION_STATUSES.include?(stored_status) && !force
 
         # Update the batch state batch_id entry with the new status
         # and update counters
         redis.multi do |m|
           m.hset(batch_state_gid, batch_id, status)
-          m.decr(batch_state_count_gid(current_status))
+          m.decr(batch_state_count_gid(stored_status))
           m.incr(batch_state_count_gid(status))
         end
       end
@@ -407,8 +433,22 @@ module Cloudtasker
           run_worker_callback(:on_child_dead, child_batch.worker)
         end
 
-        # Notify the parent batch that we are done with this batch
-        on_complete if status != :errored && complete?
+        return if status == :errored
+        return unless complete?
+
+        # Notify the parent batch that we are done with this batch. Use SETNX to ensure
+        # only the first concurrent child to complete triggers on_complete.
+        return unless redis.set(batch_completion_gid, true, nx: true, ex: BATCH_COMPLETION_TTL)
+
+        begin
+          on_complete
+        rescue StandardError
+          # Clear key on error so completion can be reattempted
+          redis.del(batch_completion_gid)
+
+          # Re-raise
+          raise
+        end
       end
 
       #
@@ -439,6 +479,7 @@ module Cloudtasker
         redis.multi do |m|
           m.del(batch_gid)
           m.del(batch_state_gid)
+          m.del(batch_completion_gid)
           BATCH_STATUSES.each { |e| m.del(batch_state_count_gid(e)) }
         end
       end

data/lib/cloudtasker/cli.rb

@@ -82,7 +82,7 @@ module Cloudtasker
         logger.info "[Cloudtasker/Server] Booted Rails #{::Rails.version} application in #{environment} environment"
       end
 
-      # Get internal read/write pip
+      # Get internal read/write pipe
       self_read, self_write = IO.pipe
 
       # Setup signals to trap
@@ -104,7 +104,7 @@ module Cloudtasker
       local_server.start(opts)
 
       while (readable_io = read_pipe.wait_readable)
-        signal = readable_io.first[0].gets.strip
+        signal = readable_io.first.chomp
         handle_signal(signal)
       end
     rescue Interrupt

data/lib/cloudtasker/cloud_task.rb

@@ -82,12 +82,24 @@ module Cloudtasker
     # @return [Cloudtasker::CloudTask] The created task.
     #
     def self.create(payload)
-      raise MaxTaskSizeExceededError if payload.to_json.bytesize > Config::MAX_TASK_SIZE
+      raise MaxTaskSizeExceededError if payload_size(payload) > Config::MAX_TASK_SIZE
 
       resp = backend.create(payload)&.to_h
       resp ? new(**resp) : nil
     end
 
+    #
+    # Calculate the size of a task payload.
+    # The size of the task will be inflated if Base64 encoding is used.
+    #
+    # @param [Hash] payload The payload of the task
+    #
+    # @return [Integer] The size of of the payload, in bytes.
+    #
+    def self.payload_size(payload)
+      (Cloudtasker.config.base64_encode_body ? Base64.encode64(payload.to_json) : payload.to_json).bytesize
+    end
+
     #
     # Delete a cloud task by id.
     #

data/lib/cloudtasker/config.rb

@@ -8,18 +8,22 @@ module Cloudtasker
     attr_accessor :redis, :store_payloads_in_redis, :gcp_queue_prefix
     attr_writer :secret, :gcp_location_id, :gcp_project_id,
                 :processor_path, :logger, :mode, :max_retries,
-                :dispatch_deadline, :on_error, :on_dead, :oidc, :local_server_ssl_verify
+                :dispatch_deadline, :on_error, :on_dead, :oidc, :local_server_ssl_verify,
+                :base64_encode_body
 
     # Max Cloud Task size in bytes
-    MAX_TASK_SIZE = 100 * 1024 # 100 KB
+    # The GCP limit is 1MiB, which is 1049KB.
+    # The task formatting and headers add about 20KB.
+    MAX_TASK_SIZE = 1000 * 1000 # 1000 KB
 
     # Retry header in Cloud Task responses
     #
     # Definitions:
-    #   X-CloudTasks-TaskRetryCount: total number of retries (including 504 "instance unreachable")
-    #   X-CloudTasks-TaskExecutionCount: number of non-503 retries (= actual number of job failures)
+    #   X-CloudTasks-TaskRetryCount: total number of retries (including 50x errors)
+    #   X-CloudTasks-TaskExecutionCount: number of non-50x retries (= actual number of job failures)
     #
     RETRY_HEADER = 'X-Cloudtasks-Taskexecutioncount'
+    ATTEMPT_HEADER = 'X-CloudTasks-TaskRetryCount'
 
     # Cloud Task ID header
     TASK_ID_HEADER = 'X-CloudTasks-TaskName'
@@ -56,6 +60,9 @@ module Cloudtasker
     # Default on_error Proc
     DEFAULT_ON_ERROR = ->(error, worker) {}
 
+    # Default base64 encoding flag
+    DEFAULT_BASE64_ENCODE_BODY = true
+
     # Cache key prefix used to store workers in cache and retrieve
     # them later.
     WORKER_STORE_PREFIX = 'worker_store'
@@ -301,5 +308,15 @@ module Cloudtasker
     def local_server_ssl_verify
       @local_server_ssl_verify.nil? ? DEFAULT_LOCAL_SERVER_SSL_VERIFY_MODE : @local_server_ssl_verify
     end
+
+    #
+    # Return whether to base64 encode the task body when sending to Cloud Tasks.
+    # Encoding is enabled by default to support UTF-8 content.
+    #
+    # @return [Boolean] Whether to base64 encode the body.
+    #
+    def base64_encode_body
+      @base64_encode_body.nil? ? DEFAULT_BASE64_ENCODE_BODY : @base64_encode_body
+    end
   end
 end

data/lib/cloudtasker/invalid_worker_error.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module Cloudtasker
+  # Error raised when a worker class cannot be instantiated.
   class InvalidWorkerError < StandardError
+    def initialize(worker_name = nil)
+      super(worker_name ? "Invalid worker: #{worker_name}" : 'Invalid worker')
+    end
   end
 end

data/lib/cloudtasker/max_task_size_exceeded_error.rb

@@ -5,7 +5,7 @@ module Cloudtasker
   # See: https://cloud.google.com/appengine/quotas#Task_Queue
   #
   class MaxTaskSizeExceededError < StandardError
-    MSG = 'The size of Cloud Tasks must not exceed 100KB'
+    MSG = "The size of Cloud Tasks must not exceed #{Config::MAX_TASK_SIZE / 1000}KB".freeze
 
     def initialize(msg = MSG)
       super

data/lib/cloudtasker/testing.rb

@@ -29,6 +29,28 @@ module Cloudtasker
       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
     #
@@ -81,6 +103,35 @@ module Cloudtasker
       @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.
     #

data/lib/cloudtasker/unique_job/job.rb

@@ -10,6 +10,12 @@ module Cloudtasker
       # The default lock strategy to use. Defaults to "no lock".
       DEFAULT_LOCK = UniqueJob::Lock::NoOp
 
+      # Warning message when final lock cannot be acquired after scheduling
+      LOCK_FINALIZATION_WARNING = 'A provisional lock was acquired before enqueuing the job but the ' \
+                                  'lock could not be finalized after enqueuing the job. This means that ' \
+                                  'it took longer than lock_provisional_ttl to enqueue the job. See ' \
+                                  'Worker#lock_provisional_ttl option.'
+
       #
       # Build a new instance of the class.
       #
@@ -18,7 +24,7 @@ module Cloudtasker
       #
       def initialize(worker, opts = {})
         @worker = worker
-        @call_opts = opts
+        @call_opts = opts.to_h
       end
 
       #
@@ -63,8 +69,26 @@ module Cloudtasker
         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
+        # Return the TTL, which is the configured lock_duration at minima
+        [lock_duration, scheduled_at + lock_duration - now].max
+      end
+
+      #
+      # A provisional lock uses a very short duration and aims
+      # at covering the time it takes for the job to be enqueued through
+      # the client middleware chain.
+      #
+      # If the application crashes during this
+      # time (e.g. OOM), at least the job won't be locked for an extended period
+      # of time (which may span across a parent job retry, for instance)
+      #
+      # This TTL can be configured via the `lock_provisional_ttl` option on
+      # the job itself.
+      #
+      # @return [Integer] The TTL in seconds
+      #
+      def lock_provisional_ttl
+        (options[:lock_provisional_ttl] || Cloudtasker::UniqueJob.lock_provisional_ttl).to_i
       end
 
       #
@@ -93,6 +117,29 @@ module Cloudtasker
         worker.try(:unique_args, worker.job_args) || worker.job_args
       end
 
+      #
+      # The base unique scope generated from lock options
+      #
+      # @return [Hash] A scope hash
+      #
+      def base_unique_scope
+        if options[:lock_per_batch] && defined?(Cloudtasker::Batch::Job)
+          key = Cloudtasker::Batch::Job.key(:parent_id).to_sym
+          worker.job_meta.to_h.slice(key)
+        else
+          {}
+        end
+      end
+
+      #
+      # Return a scope to be included in the digest hash
+      #
+      # @return [Hash] A scope hash
+      #
+      def unique_scope
+        base_unique_scope.to_h.merge(worker.try(:unique_scope).to_h)
+      end
+
       #
       # Return a unique description of the job in hash format.
       #
@@ -101,8 +148,9 @@ module Cloudtasker
       def digest_hash
         @digest_hash ||= {
           class: worker.class.to_s,
-          unique_args: unique_args
-        }
+          unique_args: unique_args,
+          unique_scope: unique_scope.presence
+        }.compact
       end
 
       #
@@ -156,6 +204,49 @@ module Cloudtasker
         raise(LockError) unless lock_acquired || lock_already_acquired
       end
 
+      #
+      # Acquire a provisional lock, yield, then set a final lock.
+      #
+      # This method is designed for scheduling operations where you need to:
+      # 1. Acquire a provisional lock to prevent concurrent scheduling
+      # 2. Perform the scheduling operation (yield)
+      # 3. Set a final lock with proper TTL after scheduling succeeds
+      #
+      # Raises a `Cloudtasker::UniqueJob::LockError` if the provisional lock
+      # cannot be acquired.
+      #
+      # @return [Any] The return value of the block
+      #
+      def lock_for_scheduling!
+        # Step 1: Acquire provisional lock
+        # Check if the lock is already acquired from a previous run
+        acquired = redis.get(unique_gid) == id
+
+        # Set the lock exclusively, if not acquired already.
+        # Refresh the duration otherwise.
+        lock_acquired = redis.set(unique_gid, id, nx: !acquired, ex: lock_provisional_ttl)
+        raise(LockError) unless lock_acquired
+
+        # Step 2: Yield to perform scheduling operation
+        result = yield
+
+        # Step 3: Set final lock
+        # Check if the lock is still held by this job
+        acquired = redis.get(unique_gid) == id
+
+        # Set the lock with final duration
+        # If already acquired, refresh with final TTL
+        # If not acquired (expired or taken), try to acquire exclusively
+        final_lock_acquired = redis.set(unique_gid, id, nx: !acquired, ex: lock_ttl)
+
+        # Log a warning if final lock could not be acquired
+        # The job has already been enqueued at this point, so raising an error is useless
+        worker.logger.warn(LOCK_FINALIZATION_WARNING) unless final_lock_acquired
+
+        # Return the result of the block
+        result
+      end
+
       #
       # Delete the job lock.
       #

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

@@ -12,10 +12,13 @@ module Cloudtasker
         # if the lock could not be acquired.
         #
         def schedule(&block)
-          job.lock!
-          yield
+          job.lock_for_scheduling!(&block)
         rescue LockError
           conflict_instance.on_schedule(&block)
+        rescue StandardError
+          # Unlock the job if any error arises during scheduling
+          job.unlock!
+          raise
         end
 
         #

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

@@ -11,10 +11,13 @@ module Cloudtasker
         # if the lock could not be acquired.
         #
         def schedule(&block)
-          job.lock!
-          yield
+          job.lock_for_scheduling!(&block)
         rescue LockError
           conflict_instance.on_schedule(&block)
+        rescue StandardError
+          # Unlock the job if any error arises during scheduling
+          job.unlock!
+          raise
         end
 
         #

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

@@ -11,10 +11,13 @@ module Cloudtasker
         # if the lock could not be acquired.
         #
         def schedule(&block)
-          job.lock!
-          yield
+          job.lock_for_scheduling!(&block)
         rescue LockError
           conflict_instance.on_schedule(&block)
+        rescue StandardError
+          # Unlock the job if any error arises during scheduling
+          job.unlock!
+          raise
         end
 
         #

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

@@ -3,11 +3,10 @@
 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)
+        def call(worker, opts = {}, &block)
+          Job.new(worker, opts).lock_instance.schedule(&block)
         end
       end
     end

data/lib/cloudtasker/unique_job.rb

@@ -11,8 +11,12 @@ module Cloudtasker
     # after schedule time.
     DEFAULT_LOCK_TTL = 10 * 60 # 10 minutes
 
+    # The maximum duration of the provisional lock while
+    # enqueuing a job.
+    DEFAULT_LOCK_PROVISIONAL_TTL = 3
+
     class << self
-      attr_writer :lock_ttl
+      attr_writer :lock_ttl, :lock_provisional_ttl
 
       # Configure the middleware
       def configure
@@ -27,6 +31,15 @@ module Cloudtasker
       def lock_ttl
         @lock_ttl || DEFAULT_LOCK_TTL
       end
+
+      #
+      # Return the provisional TTL for locks
+      #
+      # @return [Integer] The lock TTL.
+      #
+      def lock_provisional_ttl
+        @lock_provisional_ttl || DEFAULT_LOCK_PROVISIONAL_TTL
+      end
     end
   end
 end

data/lib/cloudtasker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cloudtasker
-  VERSION = '0.15.rc2'
+  VERSION = '0.15.0'
 end

data/lib/cloudtasker/worker.rb

@@ -8,7 +8,7 @@ module Cloudtasker
       base.extend(ClassMethods)
       base.attr_writer :job_queue
       base.attr_accessor :job_args, :job_id, :job_meta, :job_reenqueued, :job_retries,
-                         :perform_started_at, :perform_ended_at, :task_id
+                         :job_attempts, :perform_started_at, :perform_ended_at, :task_id
     end
 
     #
@@ -47,7 +47,10 @@ module Cloudtasker
       return nil unless worker_klass.include?(self)
 
       # Return instantiated worker
-      worker_klass.new(**payload.slice(:job_queue, :job_args, :job_id, :job_meta, :job_retries, :task_id))
+      worker_klass.new(**payload.slice(
+        :job_queue, :job_args, :job_id, :job_meta,
+        :job_retries, :job_attempts, :task_id
+      ))
     rescue NameError
       nil
     end
@@ -141,7 +144,9 @@ module Cloudtasker
       # @return [Any] The result of the worker perform method.
       #
       def perform_now(*args)
-        new(job_args: args).execute
+        # Serialize/deserialize arguments to mimic job enqueueing and produce a similar context
+        job_args = JSON.parse(args.to_json)
+        new(job_args: job_args).execute
       end
 
       #
@@ -174,11 +179,13 @@ module Cloudtasker
     # @param [Array<any>] job_args The list of perform args.
     # @param [String] job_id A unique ID identifying this job.
     #
-    def initialize(job_queue: nil, job_args: nil, job_id: nil, job_meta: {}, job_retries: 0, task_id: nil)
+    def initialize(job_queue: nil, job_args: nil, job_id: nil, job_meta: {}, job_retries: 0, job_attempts: 0,
+                   task_id: nil)
       @job_args = job_args || []
       @job_id = job_id || SecureRandom.uuid
       @job_meta = MetaStore.new(job_meta)
       @job_retries = job_retries || 0
+      @job_attempts = job_attempts || 0
       @job_queue = job_queue
       @task_id = task_id
     end
@@ -243,16 +250,18 @@ module Cloudtasker
       resp = execute_middleware_chain
 
       # Log job completion and return result
-      logger.info("Job done after #{job_duration}s") { { duration: job_duration * 1000 } }
+      logger.info("Job done after #{job_duration}s") { { duration: job_duration_ms } }
       resp
     rescue DeadWorkerError => e
-      logger.info("Job dead after #{job_duration}s and #{job_retries} retries") { { duration: job_duration * 1000 } }
+      logger.info("Job dead after #{job_duration}s and #{job_retries} retries") { { duration: job_duration_ms } }
       raise(e)
     rescue RetryWorkerError => e
-      logger.info("Job done after #{job_duration}s (retry requested)") { { duration: job_duration * 1000 } }
+      logger.info("Job done after #{job_duration}s (retry requested)") do
+        { duration: job_duration_ms, reason: e.message }
+      end
       raise(e)
     rescue StandardError => e
-      logger.info("Job failed after #{job_duration}s") { { duration: job_duration * 1000 } }
+      logger.info("Job failed after #{job_duration}s") { { duration: job_duration_ms } }
       raise(e)
     end
 
@@ -327,6 +336,7 @@ module Cloudtasker
         job_args: job_args,
         job_meta: job_meta.to_h,
         job_retries: job_retries,
+        job_attempts: job_attempts,
         job_queue: job_queue,
         task_id: task_id
       }
@@ -418,6 +428,15 @@ module Cloudtasker
       @job_duration ||= (perform_ended_at - perform_started_at).ceil(3)
     end
 
+    #
+    # Return the job_duration in milliseconds
+    #
+    # @return [Float] The time taken in milliseconds as a floating point number.
+    #
+    def job_duration_ms
+      job_duration * 1000
+    end
+
     #
     # Run worker callback.
     #

data/lib/cloudtasker/worker_handler.rb

@@ -60,8 +60,8 @@ module Cloudtasker
       # Worker will be nil on InvalidWorkerError - in that case we use generic logging
       logger = worker&.logger || Cloudtasker.logger
 
-      # Log error
-      logger.error(error)
+      # Log error with duration
+      logger.error(error) { { duration: worker&.job_duration_ms }.compact }
     end
 
     #
@@ -92,7 +92,7 @@ module Cloudtasker
       args_payload_key = extracted_payload[:args_payload_key]
 
       # Build worker
-      worker = Cloudtasker::Worker.from_hash(payload) || raise(InvalidWorkerError)
+      worker = Cloudtasker::Worker.from_hash(payload) || raise(InvalidWorkerError, payload[:worker])
 
       # Yied worker
       resp = yield(worker)
@@ -178,7 +178,7 @@ module Cloudtasker
     #
     def store_payload_in_redis?
       Cloudtasker.config.redis_payload_storage_threshold &&
-        worker.job_args.to_json.bytesize > (Cloudtasker.config.redis_payload_storage_threshold * 1024)
+        worker.job_args.to_json.bytesize > (Cloudtasker.config.redis_payload_storage_threshold * 1000)
     end
 
     #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cloudtasker
 version: !ruby/object:Gem::Version
-  version: 0.15.rc2
+  version: 0.15.0
 platform: ruby
 authors:
 - Arnaud Lachaume
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-11-13 00:00:00.000000000 Z
+date: 2026-06-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -237,7 +237,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.4
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Background jobs for Ruby using Google Cloud Tasks (beta)