job-workflow 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 213a0654cb0482f1a2574f4e55d26c72f5274d24b61b933abd04e9e21f4c19d1
-  data.tar.gz: 0f19fce390ff18dcb13d80c8a4c6841dc2e096d4ea7586f0a2d6e2c6a467a45b
+  metadata.gz: 9474c65583cf21d485c3468675d4f23124e60e88f98c954bd38256b916d98ffe
+  data.tar.gz: 59d5e0b60a2b52e87ea4da4aab1834d02c63f88cba36f661acd8c74f89a4e6a9
 SHA512:
-  metadata.gz: 89e0d194c4f14817bd2866b4b07f2efe3eea0ffdbc74ff4b7c1f5474d59fb0a18749d68fc2c724ea690f370d1b335d1e69bf0f006ab9bb1964f74fcfd689232b
-  data.tar.gz: 49150a706fb10a4ba79a87397b4cbbfcb4554eba5e974d22d6176799d377f5d9814f20862be996bca253328fc1efa6a10429947cc308f4aa3dd884eaadd378d0
+  metadata.gz: 4ac034e1b373b28aa52dcffd059bc5b64e5c45fc04d9b07460c24491c2514eabddf839b2dcb2c4a2cfbf36b578e2836e153e9bd6f34cd24f8af543cf06242ce9
+  data.tar.gz: 455b6913137103b6a5871562a6adc0ffca11e9e99543b94ec7e0bda9f2b78c6c76c5cee73baec30ca5b5b5e2fd388d6a4b119c08d7cf1039c20e115e255f58d7

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-05-13
+
+### Added
+
+- Add task-scoped cursor helpers on `Context` so tasks can persist progress, restore task-local continuation state, and delegate explicit checkpoints without exposing ActiveJob continuation internals
+
+### Fixed
+
+- Initialize the SolidQueue adapter from a Railtie after Rails boot so the `ClaimedExecution` patch is applied reliably, rescheduled `dependency_wait` jobs are not marked finished early, and Rails apps no longer need a manual initializer
+
 ## [0.4.0] - 2026-05-12
 
 ### Fixed

data/README.md

@@ -1,6 +1,6 @@
 # JobWorkflow
 
-> ⚠️ **Early Stage (v0.4.0):** This library is in active development. APIs and features may change in breaking ways without notice. Use in production at your own risk and expect potential breaking changes in future releases.
+> ⚠️ **Early Stage (v0.5.0):** This library is in active development. APIs and features may change in breaking ways without notice. Use in production at your own risk and expect potential breaking changes in future releases.
 
 ## Overview
 

data/guides/API_REFERENCE.md

@@ -84,6 +84,76 @@ end
 
 **Map Task Output**: When `each:` is specified, outputs are automatically collected as an array.
 
+### Task continuation helpers
+
+Inside a task body, you can read the current task cursor, store a new cursor, and create interruption points through the task context.
+
+#### Regular task example
+
+```ruby
+task :sync_pages, output: { processed: "Integer" } do |ctx|
+  page = ctx.cursor || 1
+  result = ExternalAPI.fetch(page:)
+
+  ctx.set_cursor!(page + 1) if result.next_page?
+
+  { processed: result.items.size }
+end
+```
+
+- `ctx.cursor` returns the current task cursor, or `nil` when no cursor has been stored
+- `ctx.set_cursor!(value)` validates that `value` is ActiveJob-serializable, stores it in the current continuation step, and checkpoints the job through Active Job continuation
+- `ctx.checkpoint!` creates a checkpoint without changing the public cursor value
+- Call `ctx.set_cursor!` when you want to change the public cursor value and create a checkpoint at the same time
+- Call `ctx.checkpoint!` when you want the current task execution to become interruptible without changing the public cursor value
+- Outside task execution, `ctx.cursor` returns `nil`, and `ctx.set_cursor!` / `ctx.checkpoint!` raise an error
+
+For regular tasks, a cursor is only persisted when you call `ctx.set_cursor!(value)` explicitly.
+
+#### Checkpoint without changing the cursor
+
+```ruby
+task :publish_report do |ctx|
+  report = build_report
+  ctx.checkpoint!
+  deliver_report(report)
+end
+```
+
+#### Repeating work inside a task
+
+```ruby
+task :sync_users do |ctx|
+  start_index = ctx.cursor || 0
+
+  ctx.arguments.user_ids.drop(start_index).each_with_index do |user_id, offset|
+    sync_user(user_id)
+    ctx.set_cursor!(start_index + offset + 1)
+  end
+end
+```
+
+This pattern is useful when a single task iterates over an Enumerable internally and you want to resume from the last completed item after an interruption.
+
+#### `each:` task example
+
+```ruby
+task :sync_users, each: ->(ctx) { ctx.arguments.user_ids } do |ctx|
+  next_cursor = ExternalAPI.sync_user(
+    user_id: ctx.each_value,
+    cursor: ctx.cursor
+  )
+
+  ctx.set_cursor!(next_cursor) unless next_cursor.nil?
+end
+```
+
+For `each:` tasks, JobWorkflow keeps the existing integer resume behavior for completed iterations.
+
+- If an `each:` task is interrupted after calling `ctx.set_cursor!`, JobWorkflow resumes with both the current iteration index and the saved task cursor
+- If an iteration completes normally, the resume state advances to the next integer index
+- In other words, a custom cursor in an `each:` task is meant for resuming work inside the current iteration, not for replacing the completion index of finished iterations
+
 ### workflow_concurrency
 
 Configure job-level concurrency limits with workflow-aware context.

data/guides/PRODUCTION_DEPLOYMENT.md

@@ -1,6 +1,6 @@
 # Production Deployment
 
-> ⚠️ **Early Stage (v0.4.0):** JobWorkflow is still in early development. While this section outlines potential deployment patterns, please thoroughly test in your specific environment and monitor for any issues before relying on JobWorkflow in critical production systems.
+> ⚠️ **Early Stage (v0.5.0):** JobWorkflow is still in early development. While this section outlines potential deployment patterns, please thoroughly test in your specific environment and monitor for any issues before relying on JobWorkflow in critical production systems.
 
 This section covers suggested settings and patterns for running JobWorkflow in production-like environments.
 

data/guides/README.md

@@ -1,6 +1,6 @@
 # JobWorkflow Guides
 
-> ⚠️ **Early Stage (v0.4.0):** JobWorkflow is in active development. APIs and features may change. The following guides provide patterns and examples for building workflows, but be aware that implementations may need adjustment as the library evolves.
+> ⚠️ **Early Stage (v0.5.0):** JobWorkflow is in active development. APIs and features may change. The following guides provide patterns and examples for building workflows, but be aware that implementations may need adjustment as the library evolves.
 
 Welcome to the JobWorkflow documentation! This directory contains comprehensive guides to help you build robust workflows with JobWorkflow.
 

data/lib/job_workflow/context.rb

@@ -2,6 +2,8 @@
 
 module JobWorkflow
   class Context # rubocop:disable Metrics/ClassLength
+    EACH_TASK_CURSOR_MARKER = "__job_workflow_each_cursor__"
+
     attr_reader :workflow #: Workflow
     attr_reader :arguments #: Arguments
     attr_reader :output #: Output
@@ -52,7 +54,7 @@ module JobWorkflow
     #     job_status: JobStatus,
     #     ?job: DSL?
     #   ) -> void
-    def initialize(workflow:, arguments:, task_context:, output:, job_status:, job: nil) # rubocop:disable Metrics/ParameterLists
+    def initialize(workflow:, arguments:, task_context:, output:, job_status:, job: nil) # rubocop:disable Metrics/ParameterLists, Metrics/AbcSize, Metrics/MethodLength
       raise "job does not match the provided workflow" if job&.then { |j| j.class._workflow != workflow }
 
       self.job = job
@@ -64,6 +66,8 @@ module JobWorkflow
       self.enabled_with_each_value = false
       self.throttle_index = 0
       self.skip_in_dry_run_index = 0
+      self.current_step = nil
+      self.current_cursor = nil
     end
 
     #:  () -> Hash[String, untyped]
@@ -77,6 +81,31 @@ module JobWorkflow
       self
     end
 
+    #:  () -> untyped
+    def cursor
+      return if current_step.nil?
+
+      current_cursor
+    end
+
+    #:  (untyped) -> void
+    def set_cursor!(value)
+      step = current_step || (raise "set_cursor! can be called only in task")
+
+      ActiveJob::Arguments.serialize([value])
+      self.current_cursor = value
+      step.set!(build_step_cursor(value))
+    end
+
+    #:  () -> void
+    def checkpoint!
+      step = current_step || (raise "checkpoint! can be called only in task")
+
+      return step.checkpoint! unless each_task?
+
+      step.set!(build_step_cursor(current_cursor))
+    end
+
     #:  (DSL) -> void
     def _job=(job)
       self.job = job
@@ -220,6 +249,18 @@ module JobWorkflow
       task_context
     end
 
+    #:  (ActiveJob::Continuation::Step, ?cursor: untyped) { () -> void } -> void
+    def _with_current_step(step, cursor: nil)
+      previous_step = current_step
+      previous_cursor = current_cursor
+      self.current_step = step
+      self.current_cursor = cursor
+      yield
+    ensure
+      self.current_step = previous_step
+      self.current_cursor = previous_cursor
+    end
+
     #:  (TaskOutput) -> void
     def _add_task_output(task_output)
       output.add_task_output(task_output)
@@ -245,12 +286,31 @@ module JobWorkflow
     attr_accessor :enabled_with_each_value #: bool
     attr_accessor :throttle_index #: Integer
     attr_accessor :skip_in_dry_run_index #: Integer
+    attr_accessor :current_step #: ActiveJob::Continuation::Step?
+    attr_accessor :current_cursor #: untyped
 
     #:  () -> String
     def parent_job_id
       _task_context.parent_job_id || job_id
     end
 
+    #:  () -> bool
+    def each_task?
+      task_context.task.each?
+    end
+
+    #:  (untyped) -> untyped
+    def build_step_cursor(value)
+      return value unless each_task?
+      return task_context.index if value.nil?
+
+      {
+        EACH_TASK_CURSOR_MARKER => true,
+        "index" => task_context.index,
+        "cursor" => value
+      }
+    end
+
     #:  () -> Hash[String, untyped]
     def serialize_for_job
       {

data/lib/job_workflow/dsl.rb

@@ -128,7 +128,7 @@ module JobWorkflow
       #   ) { (untyped) -> void } -> void
       def task(
         task_name,
-        each: ->(_ctx) { [TaskContext::NULL_VALUE] },
+        each: Task::DEFAULT_EACH,
         enqueue: nil,
         retry: 0,
         output: {},

data/lib/job_workflow/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  class Railtie < Rails::Railtie
+    config.after_initialize do
+      JobWorkflow::QueueAdapter.reset!
+      JobWorkflow::QueueAdapter.current.initialize_adapter!
+    end
+  end
+end

data/lib/job_workflow/runner.rb

@@ -14,7 +14,7 @@ module JobWorkflow
     def run
       task = context._task_context.task
       if !task.nil? && context.sub_job?
-        run_task(task)
+        job.step(task.task_name) { |step| run_task(task, step:) }
         persist_current_job_context
         return
       end
@@ -63,25 +63,46 @@ module JobWorkflow
       result
     end
 
-    #:  (Task, ?step: ActiveJob::Continuation::Step?) -> void
-    def run_task(task, step: nil)
+    #:  (Task, step: ActiveJob::Continuation::Step) -> void
+    def run_task(task, step:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       context._load_parent_task_output
-      context._with_each_value(task, start_index: step&.cursor).each do |ctx|
-        run_each_task(task, ctx)
-        step&.set!(ctx._task_context.index + 1)
+      start_index, task_cursor = decode_task_cursor(task, step.cursor)
+
+      context._with_each_value(task, start_index:).each do |ctx|
+        iteration_cursor = task_cursor
+        iteration_cursor = nil if task.each? && (task_cursor.nil? || start_index != ctx._task_context.index)
+
+        run_each_task(task, ctx, step:, cursor: iteration_cursor)
+        step.set!(ctx._task_context.index + 1) if task.each?
       rescue StandardError => e
         run_error_hooks(task, ctx, e)
         raise
       end
     end
 
-    #:  (Task, Context) -> void
-    def run_each_task(task, ctx)
+    #:  (Task, untyped) -> [Integer?, untyped]
+    def decode_task_cursor(task, task_cursor)
+      return [nil, task_cursor] unless task.each?
+      return [task_cursor, nil] if task_cursor.is_a?(Integer)
+
+      if task_cursor.is_a?(Hash) && task_cursor[Context::EACH_TASK_CURSOR_MARKER]
+        return [task_cursor.fetch("index"), task_cursor.fetch("cursor")]
+      end
+
+      raise "invalid each task cursor: #{task_cursor.inspect}" unless task_cursor.nil?
+
+      [nil, nil]
+    end
+
+    #:  (Task, Context, step: ActiveJob::Continuation::Step, ?cursor: untyped) -> void
+    def run_each_task(task, ctx, step:, cursor: nil)
       Instrumentation.instrument_task(job, task, ctx) do
-        ctx._with_task_throttle do
-          run_hooks(task, ctx) do
-            data = task.block.call(ctx)
-            add_task_output(ctx:, task:, each_index: ctx._task_context.index, data:)
+        ctx._with_current_step(step, cursor:) do
+          ctx._with_task_throttle do
+            run_hooks(task, ctx) do
+              data = task.block.call(ctx)
+              add_task_output(ctx:, task:, each_index: ctx._task_context.index, data:)
+            end
           end
         end
       end

data/lib/job_workflow/task.rb

@@ -2,6 +2,8 @@
 
 module JobWorkflow
   class Task
+    DEFAULT_EACH = ->(_ctx) { [nil] }
+
     attr_reader :job_name #: String
     attr_reader :block #: ^(untyped) -> void
     attr_reader :each #: ^(Context) -> untyped
@@ -72,6 +74,11 @@ module JobWorkflow
       "#{job_name}:#{task_name}"
     end
 
+    #:  () -> bool
+    def each?
+      !each.nil? && !each.equal?(DEFAULT_EACH)
+    end
+
     private
 
     attr_reader :name #: Symbol

data/lib/job_workflow/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JobWorkflow
-  VERSION = "0.4.0" # : String
+  VERSION = "0.5.0" # : String
 end

data/lib/job_workflow.rb

@@ -45,6 +45,9 @@ require_relative "job_workflow/task_output"
 require_relative "job_workflow/output"
 require_relative "job_workflow/queue"
 require_relative "job_workflow/auto_scaling"
+# :nocov:
+require_relative "job_workflow/railtie" if defined?(Rails::Railtie)
+# :nocov:
 
 module JobWorkflow
   class Error < StandardError; end
@@ -53,6 +56,5 @@ module JobWorkflow
 
   Instrumentation::LogSubscriber.attach!
 
-  ActiveSupport.on_load(:solid_queue) { QueueAdapter.current.initialize_adapter! }
   QueueAdapter.current.initialize_adapter!
 end

data/sig/generated/job_workflow/context.rbs

@@ -3,6 +3,8 @@
 module JobWorkflow
   class Context
     # rubocop:disable Metrics/ClassLength
+    EACH_TASK_CURSOR_MARKER: ::String
+
     attr_reader workflow: Workflow
 
     attr_reader arguments: Arguments
@@ -33,6 +35,15 @@ module JobWorkflow
     # :  (Hash[Symbol, untyped]) -> Context
     def _update_arguments: (Hash[Symbol, untyped]) -> Context
 
+    # :  () -> untyped
+    def cursor: () -> untyped
+
+    # :  (untyped) -> void
+    def set_cursor!: (untyped) -> void
+
+    # :  () -> void
+    def checkpoint!: () -> void
+
     # :  (DSL) -> void
     def _job=: (DSL) -> void
 
@@ -93,6 +104,9 @@ module JobWorkflow
     # :  () -> TaskContext
     def _task_context: () -> TaskContext
 
+    # :  (ActiveJob::Continuation::Step, ?cursor: untyped) { () -> void } -> void
+    def _with_current_step: (ActiveJob::Continuation::Step, ?cursor: untyped) { () -> void } -> void
+
     # :  (TaskOutput) -> void
     def _add_task_output: (TaskOutput) -> void
 
@@ -119,9 +133,19 @@ module JobWorkflow
 
     attr_accessor skip_in_dry_run_index: Integer
 
+    attr_accessor current_step: ActiveJob::Continuation::Step?
+
+    attr_accessor current_cursor: untyped
+
     # :  () -> String
     def parent_job_id: () -> String
 
+    # :  () -> bool
+    def each_task?: () -> bool
+
+    # :  (untyped) -> untyped
+    def build_step_cursor: (untyped) -> untyped
+
     # :  () -> Hash[String, untyped]
     def serialize_for_job: () -> Hash[String, untyped]
 

data/sig/generated/job_workflow/railtie.rbs

@@ -0,0 +1,6 @@
+# Generated from lib/job_workflow/railtie.rb with RBS::Inline
+
+module JobWorkflow
+  class Railtie < Rails::Railtie
+  end
+end

data/sig/generated/job_workflow/runner.rbs

@@ -30,11 +30,14 @@ module JobWorkflow
     # :  (Task) -> bool
     def skip_task?: (Task) -> bool
 
-    # :  (Task, ?step: ActiveJob::Continuation::Step?) -> void
-    def run_task: (Task, ?step: ActiveJob::Continuation::Step?) -> void
+    # :  (Task, step: ActiveJob::Continuation::Step) -> void
+    def run_task: (Task, step: ActiveJob::Continuation::Step) -> void
 
-    # :  (Task, Context) -> void
-    def run_each_task: (Task, Context) -> void
+    # :  (Task, untyped) -> [Integer?, untyped]
+    def decode_task_cursor: (Task, untyped) -> [ Integer?, untyped ]
+
+    # :  (Task, Context, step: ActiveJob::Continuation::Step, ?cursor: untyped) -> void
+    def run_each_task: (Task, Context, step: ActiveJob::Continuation::Step, ?cursor: untyped) -> void
 
     # :  (Task, Context) { () -> void } -> void
     def run_hooks: (Task, Context) { () -> void } -> void

data/sig/generated/job_workflow/task.rbs

@@ -2,6 +2,8 @@
 
 module JobWorkflow
   class Task
+    DEFAULT_EACH: untyped
+
     attr_reader job_name: String
 
     attr_reader block: ^(untyped) -> void
@@ -50,6 +52,9 @@ module JobWorkflow
     # :  () -> String
     def throttle_prefix_key: () -> String
 
+    # :  () -> bool
+    def each?: () -> bool
+
     private
 
     attr_reader name: Symbol

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: job-workflow
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - shoma07
@@ -90,6 +90,7 @@ files:
 - lib/job_workflow/queue_adapters/abstract.rb
 - lib/job_workflow/queue_adapters/null_adapter.rb
 - lib/job_workflow/queue_adapters/solid_queue_adapter.rb
+- lib/job_workflow/railtie.rb
 - lib/job_workflow/runner.rb
 - lib/job_workflow/schedule.rb
 - lib/job_workflow/semaphore.rb
@@ -141,6 +142,7 @@ files:
 - sig/generated/job_workflow/queue_adapters/abstract.rbs
 - sig/generated/job_workflow/queue_adapters/null_adapter.rbs
 - sig/generated/job_workflow/queue_adapters/solid_queue_adapter.rbs
+- sig/generated/job_workflow/railtie.rbs
 - sig/generated/job_workflow/runner.rbs
 - sig/generated/job_workflow/schedule.rbs
 - sig/generated/job_workflow/semaphore.rbs