good_pipeline 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 350a7e051f704db8ee906a90bb8f641f1373be815aceb9adccc8cd17b2d38640
-  data.tar.gz: f0cebfb8f77d35e043df87e71e5698b4e6ec08a468d95702a5a3a489eb1debf9
+  metadata.gz: e9df8b5fbd57895f53adf1d3c5804ca9bd64ca792e880c2d4941957e4b8ca368
+  data.tar.gz: c4e2a7c4edbe27a0e40e7ff62a061f5ade53c44a74c0b824ce21bdf019cb8781
 SHA512:
-  metadata.gz: 682725126bc0643cd8ec88d249ef7e93b760d646a4aac30cbb693c1bde6d1c0b3d30494623eb5ffed8cc2845f62dc3642501648bf65cbf3adc43577f13734270
-  data.tar.gz: 5e2aae2df9e5b8997b85a4aff15d0989fa24f27b6e607332d82421c5e5b33d0a4171e455ddc04eab71f790657fe9f71d59b412b7ffa054b7f15c60148b1a1536
+  metadata.gz: e3c6e6940034efbc8679ede33b352022deb64a36b7a16a9dd3f02fd6dc32a837caf545407541bd0ca629f690d38cfa60342e6aa756e53ea321fb754eebbd772c
+  data.tar.gz: 878566f6d9ddc7b9ce6b4201f5bd241b21f2758f5475e3fa60e6c3fd629651bff06ff973af9f3f29ac4624bee58e78dc0f9628e8a1cdb503836e923a09e3944e

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.3.1] - 2026-03-26
+
+### Added
+
+- **`halt_pipeline!`** — call from any job to stop the pipeline early with a `succeeded` status. The halting step is marked `halted`, remaining pending steps are `skipped`, and the `on_success` callback fires. The GoodJob record completes as succeeded (no error, no discard). Available in all jobs via `GoodPipeline::Haltable`, included automatically by the Engine.
+- **`halted` coordination status** — new terminal step status for steps that called `halt_pipeline!`. Treated as satisfied for downstream dependency resolution.
+- **`halt_requested` column** — boolean column on steps table, set by `halt_pipeline!` and checked by the coordinator on step completion.
+- **`good_job_id` index** — partial unique index on `good_job_id` for fast step lookup from within jobs.
+
 ## [0.3.0] - 2026-03-25
 
 ### Performance

data/app/helpers/good_pipeline/mermaid_diagram_builder.rb

@@ -15,6 +15,7 @@ module GoodPipeline
       "  classDef failed fill:#f44336,color:#fff",
       "  classDef skipped fill:#bdbdbd,color:#333",
       "  classDef skipped_by_branch fill:#bdbdbd,color:#333",
+      "  classDef halted fill:#8bc34a,color:#fff",
       "  classDef branch fill:#ff9800,color:#fff,stroke:#f57c00",
       "  classDef terminal fill:#1a1a2e,color:#fff,stroke:#1a1a2e"
     ].freeze

data/app/models/good_pipeline/step_record.rb

@@ -7,11 +7,11 @@ module GoodPipeline
   class StepRecord < ActiveRecord::Base
     self.table_name = "good_pipeline_steps"
 
-    TERMINAL_COORDINATION_STATUSES = %w[succeeded failed skipped skipped_by_branch].freeze
+    TERMINAL_COORDINATION_STATUSES = %w[succeeded failed skipped skipped_by_branch halted].freeze
 
     VALID_COORDINATION_TRANSITIONS = {
-      "pending" => %w[enqueued skipped skipped_by_branch succeeded failed],
-      "enqueued" => %w[succeeded failed]
+      "pending" => %w[enqueued skipped skipped_by_branch succeeded failed halted],
+      "enqueued" => %w[succeeded failed halted]
     }.freeze
 
     enum :coordination_status, {
@@ -20,7 +20,8 @@ module GoodPipeline
       succeeded: "succeeded",
       failed: "failed",
       skipped: "skipped",
-      skipped_by_branch: "skipped_by_branch"
+      skipped_by_branch: "skipped_by_branch",
+      halted: "halted"
     }
 
     enum :on_failure_strategy, { halt: "halt", continue: "continue", ignore: "ignore" }

data/demo/app/jobs/halt_execution_job.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class HaltExecutionJob < ApplicationJob
+  def perform(**)
+    halt_pipeline!
+  end
+end

data/demo/db/migrate/20260319205326_create_good_pipeline_tables.rb

@@ -31,6 +31,7 @@ class CreateGoodPipelineTables < ActiveRecord::Migration[8.1]
       t.uuid :good_job_batch_id
       t.uuid :good_job_id
       t.integer :pending_upstream_count, null: false, default: 0
+      t.boolean :halt_requested, null: false, default: false
       t.integer :attempts
       t.string :error_class
       t.text :error_message
@@ -40,6 +41,7 @@ class CreateGoodPipelineTables < ActiveRecord::Migration[8.1]
 
     add_index :good_pipeline_steps, %i[pipeline_id key], unique: true
     add_index :good_pipeline_steps, :coordination_status
+    add_index :good_pipeline_steps, :good_job_id, unique: true, where: "good_job_id IS NOT NULL"
 
     create_table :good_pipeline_dependencies do |t|
       t.references :pipeline, null: false, foreign_key: { to_table: :good_pipeline_pipelines }, type: :uuid

data/demo/test/integration/test_halt_execution.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class TestHaltExecution < ActiveSupport::TestCase
+  def run_pipeline_to_completion(pipeline_record, timeout: 15)
+    deadline = Time.current + timeout
+    loop do
+      perform_enqueued_jobs_inline
+      pipeline_record.reload
+      return pipeline_record if pipeline_record.terminal?
+
+      raise "Pipeline did not reach terminal state within #{timeout}s (status: #{pipeline_record.status})" if Time.current > deadline
+
+      sleep 0.05
+    end
+  end
+
+  def test_halt_pipeline_marks_step_halted
+    pipeline_class = Class.new(GoodPipeline::Pipeline) do
+      failure_strategy :halt
+      define_method(:configure) do |**|
+        run :halt_step, HaltExecutionJob
+        run :after_step, DownloadJob, after: :halt_step
+      end
+    end
+    Object.const_set(:HaltSucceededPipeline, pipeline_class) unless defined?(::HaltSucceededPipeline)
+
+    chain = HaltSucceededPipeline.run
+    result = run_pipeline_to_completion(chain)
+
+    halt_step = result.steps.find_by(key: "halt_step")
+    assert_equal "halted", halt_step.coordination_status
+    assert halt_step.halt_requested?, "halt_requested should be true"
+  end
+
+  def test_halt_pipeline_skips_remaining_steps
+    pipeline_class = Class.new(GoodPipeline::Pipeline) do
+      failure_strategy :halt
+      define_method(:configure) do |**|
+        run :halt_step, HaltExecutionJob
+        run :after_step, DownloadJob, after: :halt_step
+      end
+    end
+    Object.const_set(:HaltSkipsPipeline, pipeline_class) unless defined?(::HaltSkipsPipeline)
+
+    chain = HaltSkipsPipeline.run
+    result = run_pipeline_to_completion(chain)
+
+    after_step = result.steps.find_by(key: "after_step")
+    assert_equal "skipped", after_step.coordination_status
+  end
+
+  def test_halt_pipeline_pipeline_succeeds
+    pipeline_class = Class.new(GoodPipeline::Pipeline) do
+      failure_strategy :halt
+      define_method(:configure) do |**|
+        run :halt_step, HaltExecutionJob
+        run :after_step, DownloadJob, after: :halt_step
+      end
+    end
+    Object.const_set(:HaltSucceedsPipeline, pipeline_class) unless defined?(::HaltSucceedsPipeline)
+
+    chain = HaltSucceedsPipeline.run
+    result = run_pipeline_to_completion(chain)
+
+    assert_equal "succeeded", result.status
+  end
+
+  def test_halt_pipeline_job_succeeds_in_good_job
+    pipeline_class = Class.new(GoodPipeline::Pipeline) do
+      failure_strategy :halt
+      define_method(:configure) do |**|
+        run :halt_step, HaltExecutionJob
+      end
+    end
+    Object.const_set(:HaltJobSucceedsPipeline, pipeline_class) unless defined?(::HaltJobSucceedsPipeline)
+
+    chain = HaltJobSucceedsPipeline.run
+    run_pipeline_to_completion(chain)
+
+    halt_step = chain.steps.find_by(key: "halt_step")
+    good_job = GoodJob::Job.find(halt_step.good_job_id)
+
+    assert_equal 1, good_job.executions_count
+    assert_nil good_job.error, "GoodJob record should have no error"
+    assert_not_nil good_job.finished_at
+  end
+
+  def test_halt_pipeline_with_parallel_steps
+    pipeline_class = Class.new(GoodPipeline::Pipeline) do
+      failure_strategy :continue
+      define_method(:configure) do |**|
+        run :halt_step, HaltExecutionJob
+        run :normal_step, DownloadJob
+        run :after_both, CleanupJob, after: %i[halt_step normal_step]
+      end
+    end
+    Object.const_set(:HaltParallelPipeline, pipeline_class) unless defined?(::HaltParallelPipeline)
+
+    chain = HaltParallelPipeline.run
+    result = run_pipeline_to_completion(chain)
+
+    halt_step = result.steps.find_by(key: "halt_step")
+    normal_step = result.steps.find_by(key: "normal_step")
+    after_both = result.steps.find_by(key: "after_both")
+
+    assert_equal "halted", halt_step.coordination_status
+    assert_equal "succeeded", normal_step.coordination_status
+    assert_equal "skipped", after_both.coordination_status
+    assert_equal "succeeded", result.status
+  end
+end

data/docs/failure-strategies.md

@@ -127,6 +127,41 @@ A downstream step is eligible for enqueue when **all** of its incoming edges are
 
 A downstream step is marked `skipped` when it's still `pending` and at least one incoming edge is **permanently unsatisfied** — the upstream is terminal, cannot satisfy the edge, and no future event can change that.
 
+## Early termination with success
+
+Sometimes a job determines there is nothing to do — the account is deactivated, the resource was already processed, etc. Call `halt_pipeline!` to stop the pipeline early and mark it as `succeeded`:
+
+```ruby
+class FetchDataJob < ApplicationJob
+  def perform(account_id:)
+    account = Account.find(account_id)
+    return halt_pipeline! if account.deactivated?
+
+    # ... normal work
+  end
+end
+```
+
+The behavior:
+
+| Aspect | Value |
+|---|---|
+| Halting step status | `halted` |
+| Remaining pending steps | `skipped` |
+| Pipeline status | `succeeded` |
+| Callback triggered | `on_success` |
+| GoodJob record | Succeeded (no error, no discard) |
+
+No configuration or module includes are required. The Engine includes `GoodPipeline::Haltable` into `ActiveJob::Base` at boot, so `halt_pipeline!` is available in any job. For non-pipeline jobs, it's a no-op.
+
+::: tip Return early
+Remember to use `return halt_pipeline!` — without `return`, the job continues executing after the call.
+:::
+
+::: warning Parallel steps
+If another step is already running when `halt_pipeline!` is called, that step continues to completion. Only `pending` steps are skipped. If the running step fails, the pipeline will derive to `failed`, not `succeeded`.
+:::
+
 ## Failure resolution table
 
 | Pipeline strategy | Step override | Effect when step fails |

data/lib/generators/good_pipeline/install/templates/create_good_pipeline_tables.rb.erb

@@ -29,6 +29,7 @@ class CreateGoodPipelineTables < ActiveRecord::Migration[<%= ActiveRecord::Migra
       t.uuid :good_job_batch_id
       t.uuid :good_job_id
       t.integer :pending_upstream_count, null: false, default: 0
+      t.boolean :halt_requested, null: false, default: false
       t.integer :attempts
       t.string :error_class
       t.text :error_message
@@ -38,6 +39,7 @@ class CreateGoodPipelineTables < ActiveRecord::Migration[<%= ActiveRecord::Migra
 
     add_index :good_pipeline_steps, %i[pipeline_id key], unique: true
     add_index :good_pipeline_steps, :coordination_status
+    add_index :good_pipeline_steps, :good_job_id, unique: true, where: "good_job_id IS NOT NULL"
 
     create_table :good_pipeline_dependencies do |t|
       t.references :pipeline, null: false, foreign_key: { to_table: :good_pipeline_pipelines }, type: :uuid

data/lib/good_pipeline/coordinator.rb

@@ -3,9 +3,14 @@
 module GoodPipeline
   class Coordinator # rubocop:disable Metrics/ClassLength
     class << self
-      def complete_step(step, succeeded:)
+      def complete_step(step, succeeded:) # rubocop:disable Metrics/MethodLength
         return if step.terminal_coordination_status?
 
+        if succeeded && step.halt_requested?
+          handle_halt_execution(step)
+          return
+        end
+
         record_step_outcome(step, succeeded)
         propagate_halt(step) if !succeeded && step.pipeline.halt?
         return if unblock_downstream_steps(step)
@@ -74,6 +79,19 @@ module GoodPipeline
 
       private
 
+      def handle_halt_execution(step)
+        step.transition_coordination_status_to!(:halted)
+        step.pipeline.steps.pending.update_all(coordination_status: "skipped")
+
+        pipeline = load_pipeline_with_active_check(step.pipeline_id)
+
+        recompute_pipeline_status(
+          pipeline,
+          has_active_steps: pipeline["has_active_steps"],
+          has_downstream_chains: pipeline["has_downstream_chains"]
+        )
+      end
+
       def record_step_outcome(step, succeeded)
         if succeeded
           step.transition_coordination_status_to!(:succeeded)
@@ -173,6 +191,7 @@ module GoodPipeline
       def permanently_unsatisfied?(upstream)
         upstream.terminal_coordination_status? &&
           !upstream.succeeded? &&
+          !upstream.halted? &&
           !upstream.skipped_by_branch? &&
           effective_failure_strategy(upstream) != :ignore
       end
@@ -186,6 +205,7 @@ module GoodPipeline
       def all_upstreams_satisfied?(step)
         step.upstream_steps.all? do |upstream|
           upstream.succeeded? ||
+            upstream.halted? ||
             upstream.skipped_by_branch? ||
             (upstream.failed? && effective_failure_strategy(upstream) == :ignore)
         end

data/lib/good_pipeline/engine.rb

@@ -13,6 +13,12 @@ module GoodPipeline
       end
     end
 
+    initializer "good_pipeline.haltable" do
+      ActiveSupport.on_load(:active_job) do
+        include GoodPipeline::Haltable
+      end
+    end
+
     initializer "good_pipeline.cleanup_hook" do
       ActiveSupport::Notifications.subscribe("cleanup_preserved_jobs.good_job") do |event|
         timestamp = event.payload[:timestamp]

data/lib/good_pipeline/haltable.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module GoodPipeline
+  module Haltable
+    def halt_pipeline!
+      step = GoodPipeline::StepRecord.find_by(good_job_id: provider_job_id)
+      step&.update_columns(halt_requested: true, updated_at: Time.current)
+    end
+  end
+end

data/lib/good_pipeline/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GoodPipeline
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/lib/good_pipeline.rb

@@ -13,6 +13,7 @@ require_relative "good_pipeline/branch_resolver"
 require_relative "good_pipeline/coordinator"
 require_relative "good_pipeline/chain_coordinator"
 require_relative "good_pipeline/runner"
+require_relative "good_pipeline/haltable"
 require_relative "good_pipeline/chain"
 require_relative "good_pipeline/engine" if defined?(Rails::Engine)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: good_pipeline
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Ali Hamdi Ali Fadel
@@ -93,6 +93,7 @@ files:
 - demo/app/jobs/cleanup_job.rb
 - demo/app/jobs/download_job.rb
 - demo/app/jobs/failing_job.rb
+- demo/app/jobs/halt_execution_job.rb
 - demo/app/jobs/publish_job.rb
 - demo/app/jobs/retryable_job.rb
 - demo/app/jobs/thumbnail_job.rb
@@ -135,6 +136,7 @@ files:
 - demo/test/integration/test_concurrent_fan_in.rb
 - demo/test/integration/test_end_to_end.rb
 - demo/test/integration/test_enqueue_atomicity.rb
+- demo/test/integration/test_halt_execution.rb
 - demo/test/integration/test_halt_ignore_chain.rb
 - demo/test/integration/test_ignore_transitive_exemption.rb
 - demo/test/integration/test_late_chain_registration.rb
@@ -184,6 +186,7 @@ files:
 - lib/good_pipeline/errors.rb
 - lib/good_pipeline/failure_metadata.rb
 - lib/good_pipeline/graph_validator.rb
+- lib/good_pipeline/haltable.rb
 - lib/good_pipeline/pipeline.rb
 - lib/good_pipeline/runner.rb
 - lib/good_pipeline/step_definition.rb