resque-job-chain 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7dfd67579d991ba4ffe0e52761b622ff1870698aef56171db0897ca54cedfa7c
+  data.tar.gz: 134f3550a163edfcf4cf480e1c422898c06214bb727ab4443795c197576ca496
+SHA512:
+  metadata.gz: d95bf665b569b900720538bc0014c5fcd89939eae8bd9d8f93d500fc0c64808471e7ac567cc4b2347d58708c073f86883cd965159c652beb8b3984ba7d15dc50
+  data.tar.gz: d5a0e5ee4aacf8e31c25b528ee0ac8a9aed6baaf0aa7b95d315ab3a34fa8a81d689f75e59571bf9c9957a9d8adc9ae1c9db1b49212de5e0d203975793a8893ca

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.0] - Unreleased
+
+### Added
+- Chain declaration via Builder DSL
+- Step command pattern with serialization
+- Atomic Redis state management via Lua scripts (start, advance, fail)
+- Error strategies: abort, retry, skip
+- Shared context between steps
+- Observer callbacks for lifecycle events
+- Resque plugin hooks (after_perform, on_failure)
+- Idempotent chain start (duplicate prevention)
+- Configurable TTL for completed chain state
+- Optional StatsD and logger integration

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Duarte Reis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,116 @@
+# resque-job-chain
+
+A Resque plugin for declaring ordered chains of jobs with shared context, configurable error strategies, and atomic Redis state tracking.
+
+## Installation
+
+```ruby
+gem 'resque-job-chain'
+```
+
+## Usage
+
+### Declaring a chain
+
+```ruby
+chain = Resque::JobChain.build("order-processing-#{order_id}") do |c|
+  c.step FetchOrderJob, order_id: order_id
+  c.step ValidateInventoryJob, order_id: order_id, on_failure: :skip
+  c.step ChargePaymentJob, order_id: order_id, on_failure: :retry, max_attempts: 3
+  c.step ShipOrderJob, order_id: order_id
+  c.step SendConfirmationJob, order_id: order_id
+
+  c.on_failure :abort
+  c.context requested_at: Time.now.iso8601
+end
+
+chain.start!
+```
+
+### Job classes
+
+Extend `Resque::Plugins::JobChain` in your job classes to enable chain progression:
+
+```ruby
+class ChargePaymentJob
+  extend Resque::Plugins::JobChain
+  @queue = :payments
+
+  def self.perform(params)
+    result = PaymentGateway.charge(params['order_id'], params['amount'])
+
+    # Write to chain context for downstream steps
+    Resque::JobChain.update_context(params['_chain_id'], payment_ref: result.reference)
+  end
+end
+```
+
+Each step receives a hash with:
+- Its declared args
+- The current chain context (accumulated from prior steps)
+- `_chain_id` and `_step_index` metadata
+
+### Error strategies
+
+Per-step or chain-level:
+
+| Strategy | Behavior |
+|----------|----------|
+| `:abort` | Mark chain as failed, stop execution (default) |
+| `:retry` | Re-enqueue the step, up to `max_attempts` |
+| `:skip` | Mark step as skipped, advance to next |
+
+### Configuration
+
+```ruby
+Resque::JobChain.configure do |c|
+  c.default_strategy = :abort
+  c.default_max_attempts = 3
+  c.completed_chain_ttl = 86_400  # 24h
+  c.statsd_client = MyStatsD
+  c.logger = Rails.logger
+
+  c.on(:chain_started) { |id| log("Chain #{id} started") }
+  c.on(:step_completed) { |id, idx| log("Chain #{id} step #{idx} done") }
+  c.on(:chain_completed) { |id| log("Chain #{id} completed") }
+  c.on(:chain_failed) { |id, idx| alert("Chain #{id} failed at step #{idx}") }
+end
+```
+
+### Querying chain status
+
+```ruby
+Resque::JobChain.status('order-processing-42')
+# => {"status"=>"running", "current_step"=>"2", "total_steps"=>"5", ...}
+
+Resque::JobChain.context('order-processing-42')
+# => {"requested_at"=>"2024-01-01T00:00:00Z", "payment_ref"=>"pay_abc"}
+
+Resque::JobChain.active_chains
+# => ["order-processing-42", "order-processing-43"]
+```
+
+## Design
+
+Built using Gang of Four patterns:
+
+- **Builder** for chain declaration DSL
+- **Command** for step encapsulation
+- **Chain of Responsibility** for sequential execution
+- **Strategy** for pluggable error handling
+- **Template Method** for execution lifecycle
+- **Observer** for lifecycle callbacks
+
+All state transitions are atomic via Redis Lua scripts.
+
+## Development
+
+```bash
+docker-compose up -d
+REDIS_URL=redis://localhost:6380/15 bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/resque/job_chain/builder.rb

@@ -0,0 +1,40 @@
+module Resque
+  module JobChain
+    class Builder
+      def initialize(chain_id)
+        @chain_id = chain_id
+        @steps = []
+        @default_strategy = nil
+        @initial_context = {}
+      end
+
+      def step(job_class, **options)
+        step_args = options.except(:on_failure, :max_attempts, :queue)
+        @steps << Step.new(
+          job_class,
+          args: step_args,
+          on_failure: options[:on_failure],
+          max_attempts: options[:max_attempts],
+          queue: options[:queue]
+        )
+      end
+
+      def on_failure(strategy)
+        @default_strategy = strategy
+      end
+
+      def context(**initial_data)
+        @initial_context.merge!(initial_data)
+      end
+
+      def to_chain
+        Chain.new(
+          id: @chain_id,
+          steps: @steps,
+          default_strategy: @default_strategy,
+          initial_context: @initial_context
+        )
+      end
+    end
+  end
+end

data/lib/resque/job_chain/chain.rb

@@ -0,0 +1,33 @@
+module Resque
+  module JobChain
+    class Chain
+      attr_reader :id, :steps, :default_strategy, :initial_context
+
+      def initialize(id:, steps:, default_strategy: nil, initial_context: {})
+        @id = id
+        @steps = steps
+        @default_strategy = default_strategy || JobChain.configuration.default_strategy
+        @initial_context = initial_context
+      end
+
+      def start!
+        started = Persistence.start_chain(
+          chain_id: id,
+          steps: steps,
+          context: initial_context
+        )
+
+        if started
+          steps.first.enqueue(id, 0, initial_context)
+          Observable.notify(:chain_started, id)
+        end
+
+        started
+      end
+
+      def total_steps
+        steps.length
+      end
+    end
+  end
+end

data/lib/resque/job_chain/configuration.rb

@@ -0,0 +1,37 @@
+module Resque
+  module JobChain
+    class Configuration
+      # @return [Symbol] Default error strategy (:abort, :retry, :skip).
+      attr_accessor :default_strategy
+
+      # @return [Integer] Default max retry attempts for the :retry strategy.
+      attr_accessor :default_max_attempts
+
+      # @return [Integer] TTL in seconds for completed chain state in Redis.
+      attr_accessor :completed_chain_ttl
+
+      # @return [#increment, #gauge, nil] Optional StatsD-compatible client.
+      attr_accessor :statsd_client
+
+      # @return [#info, #error, nil] Optional logger for chain lifecycle events.
+      attr_accessor :logger
+
+      def initialize
+        @default_strategy = :abort
+        @default_max_attempts = 3
+        @completed_chain_ttl = 86_400
+        @statsd_client = nil
+        @logger = nil
+        @observers = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def on(event, &block)
+        @observers[event.to_sym] << block
+      end
+
+      def observers_for(event)
+        @observers[event.to_sym]
+      end
+    end
+  end
+end

data/lib/resque/job_chain/context.rb

@@ -0,0 +1,15 @@
+module Resque
+  module JobChain
+    module Context
+      module_function
+
+      def load(chain_id)
+        Persistence.load_context(chain_id)
+      end
+
+      def update(chain_id, **updates)
+        Persistence.merge_context(chain_id, updates)
+      end
+    end
+  end
+end

data/lib/resque/job_chain/executor.rb

@@ -0,0 +1,80 @@
+module Resque
+  module JobChain
+    class Executor
+      def initialize(chain_id, step_index)
+        @chain_id = chain_id
+        @step_index = step_index
+      end
+
+      def after_step
+        result = Persistence.advance(@chain_id, @step_index)
+
+        case result
+        when 'completed'
+          Observable.notify(:chain_completed, @chain_id)
+        when 'advanced'
+          enqueue_next_step
+          Observable.notify(:step_completed, @chain_id, @step_index)
+        when 'stale'
+          Observable.notify(:step_stale, @chain_id, @step_index)
+        end
+
+        result
+      end
+
+      def on_failure(error)
+        step = Persistence.load_step(@chain_id, @step_index)
+        strategy = resolve_strategy(step)
+        max_attempts = step.max_attempts || JobChain.configuration.default_max_attempts
+
+        result = Persistence.fail_step(
+          @chain_id, @step_index, error.message, strategy, max_attempts
+        )
+
+        handle_failure_result(result, step)
+      end
+
+      private
+
+      def resolve_strategy(step)
+        step.on_failure || JobChain.configuration.default_strategy
+      end
+
+      def handle_failure_result(result, step)
+        case result
+        when 'aborted', 'exhausted'
+          Observable.notify(:chain_failed, @chain_id, @step_index)
+        when /\Aretrying:(\d+)\z/
+          re_enqueue_current_step(step)
+          Observable.notify(:step_retrying, @chain_id, @step_index, ::Regexp.last_match(1).to_i)
+        when 'skipped'
+          handle_skipped_step
+        end
+
+        result
+      end
+
+      def handle_skipped_step
+        state = Persistence.load_state(@chain_id)
+        if state['status'] == 'completed'
+          Observable.notify(:chain_completed, @chain_id)
+        else
+          enqueue_next_step
+          Observable.notify(:step_skipped, @chain_id, @step_index)
+        end
+      end
+
+      def enqueue_next_step
+        next_index = @step_index + 1
+        step = Persistence.load_step(@chain_id, next_index)
+        context = Persistence.load_context(@chain_id)
+        step.enqueue(@chain_id, next_index, context)
+      end
+
+      def re_enqueue_current_step(step)
+        context = Persistence.load_context(@chain_id)
+        step.enqueue(@chain_id, @step_index, context)
+      end
+    end
+  end
+end

data/lib/resque/job_chain/observable.rb

@@ -0,0 +1,21 @@
+module Resque
+  module JobChain
+    module Observable
+      module_function
+
+      def notify(event, *args)
+        listeners = JobChain.configuration.observers_for(event)
+        listeners.each { |listener| listener.call(*args) }
+
+        log_event(event, args)
+      end
+
+      def log_event(event, args)
+        logger = JobChain.configuration.logger
+        return unless logger
+
+        logger.info("[resque-job-chain] #{event}: #{args.inspect}")
+      end
+    end
+  end
+end

data/lib/resque/job_chain/persistence.rb

@@ -0,0 +1,115 @@
+require 'json'
+
+module Resque
+  module JobChain
+    module Persistence
+      START_SCRIPT = File.read(File.expand_path('../../../lua/start_chain.lua', __dir__))
+      ADVANCE_SCRIPT = File.read(File.expand_path('../../../lua/advance_chain.lua', __dir__))
+      FAIL_SCRIPT = File.read(File.expand_path('../../../lua/fail_step.lua', __dir__))
+
+      module_function
+
+      def start_chain(chain_id:, steps:, context:)
+        steps_json = steps.map { |s| JSON.generate(s.to_h) }
+        result = raw_redis.eval(
+          START_SCRIPT,
+          keys: [state_key(chain_id), steps_key(chain_id), context_key(chain_id), active_key],
+          argv: [
+            steps.length.to_s,
+            JSON.generate(stringify_keys(context)),
+            chain_id,
+            JSON.generate(steps_json),
+            Time.now.utc.iso8601
+          ]
+        )
+        result == 1
+      end
+
+      def advance(chain_id, step_index)
+        raw_redis.eval(
+          ADVANCE_SCRIPT,
+          keys: [state_key(chain_id), active_key],
+          argv: [
+            step_index.to_s,
+            Time.now.utc.iso8601,
+            chain_id,
+            JobChain.configuration.completed_chain_ttl.to_s
+          ]
+        )
+      end
+
+      def fail_step(chain_id, step_index, error_message, strategy, max_attempts)
+        raw_redis.eval(
+          FAIL_SCRIPT,
+          keys: [state_key(chain_id), active_key],
+          argv: [
+            step_index.to_s,
+            error_message.to_s,
+            strategy.to_s,
+            max_attempts.to_s,
+            Time.now.utc.iso8601,
+            chain_id,
+            JobChain.configuration.completed_chain_ttl.to_s
+          ]
+        )
+      end
+
+      def load_state(chain_id)
+        raw_redis.hgetall(state_key(chain_id))
+      end
+
+      def load_step(chain_id, step_index)
+        json = raw_redis.lindex(steps_key(chain_id), step_index)
+        return nil unless json
+
+        Step.from_h(JSON.parse(json))
+      end
+
+      def load_context(chain_id)
+        json = raw_redis.get(context_key(chain_id))
+        return {} unless json
+
+        JSON.parse(json)
+      end
+
+      def merge_context(chain_id, updates)
+        current = load_context(chain_id)
+        merged = current.merge(stringify_keys(updates))
+        raw_redis.set(context_key(chain_id), JSON.generate(merged))
+        merged
+      end
+
+      def active_chains
+        raw_redis.smembers(active_key)
+      end
+
+      def state_key(chain_id)
+        "#{namespace}:job_chain:#{chain_id}:state"
+      end
+
+      def steps_key(chain_id)
+        "#{namespace}:job_chain:#{chain_id}:steps"
+      end
+
+      def context_key(chain_id)
+        "#{namespace}:job_chain:#{chain_id}:context"
+      end
+
+      def active_key
+        "#{namespace}:job_chain:active"
+      end
+
+      def namespace
+        Resque.redis.namespace
+      end
+
+      def raw_redis
+        Resque.redis.redis
+      end
+
+      def stringify_keys(hash)
+        hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/resque/job_chain/step.rb

@@ -0,0 +1,51 @@
+require 'json'
+
+module Resque
+  module JobChain
+    class Step
+      attr_reader :job_class, :args, :on_failure, :max_attempts, :queue
+
+      def initialize(job_class, args: {}, on_failure: nil, max_attempts: nil, queue: nil)
+        @job_class = job_class
+        @args = args
+        @on_failure = on_failure
+        @max_attempts = max_attempts
+        @queue = queue || job_class.instance_variable_get(:@queue)
+      end
+
+      def enqueue(chain_id, step_index, context)
+        merged = stringify_keys(args)
+                 .merge(stringify_keys(context))
+                 .merge('_chain_id' => chain_id, '_step_index' => step_index)
+
+        Resque.enqueue_to(queue, job_class, merged)
+      end
+
+      def to_h
+        {
+          'class' => job_class.to_s,
+          'args' => stringify_keys(args),
+          'on_failure' => on_failure&.to_s,
+          'max_attempts' => max_attempts,
+          'queue' => queue.to_s
+        }
+      end
+
+      def self.from_h(hash)
+        new(
+          Object.const_get(hash['class']),
+          args: hash['args'] || {},
+          on_failure: hash['on_failure']&.to_sym,
+          max_attempts: hash['max_attempts'],
+          queue: hash['queue']&.to_sym
+        )
+      end
+
+      private
+
+      def stringify_keys(hash)
+        hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/resque/job_chain/strategies/abort.rb

@@ -0,0 +1,9 @@
+module Resque
+  module JobChain
+    module Strategies
+      module Abort
+        STRATEGY = :abort
+      end
+    end
+  end
+end

data/lib/resque/job_chain/strategies/base.rb

@@ -0,0 +1,14 @@
+module Resque
+  module JobChain
+    module Strategies
+      def self.resolve(name)
+        case name.to_sym
+        when :abort then Abort
+        when :retry then Retry
+        when :skip  then Skip
+        else raise ArgumentError, "Unknown strategy: #{name}"
+        end
+      end
+    end
+  end
+end

data/lib/resque/job_chain/strategies/retry.rb

@@ -0,0 +1,9 @@
+module Resque
+  module JobChain
+    module Strategies
+      module Retry
+        STRATEGY = :retry
+      end
+    end
+  end
+end

data/lib/resque/job_chain/strategies/skip.rb

@@ -0,0 +1,9 @@
+module Resque
+  module JobChain
+    module Strategies
+      module Skip
+        STRATEGY = :skip
+      end
+    end
+  end
+end

data/lib/resque/job_chain/version.rb

@@ -0,0 +1,5 @@
+module Resque
+  module JobChain
+    VERSION = '0.1.0'.freeze
+  end
+end

data/lib/resque/job_chain.rb

@@ -0,0 +1,55 @@
+require 'resque'
+require_relative 'job_chain/version'
+require_relative 'job_chain/configuration'
+require_relative 'job_chain/step'
+require_relative 'job_chain/chain'
+require_relative 'job_chain/builder'
+require_relative 'job_chain/context'
+require_relative 'job_chain/persistence'
+require_relative 'job_chain/executor'
+require_relative 'job_chain/observable'
+require_relative 'job_chain/strategies/base'
+require_relative 'job_chain/strategies/abort'
+require_relative 'job_chain/strategies/retry'
+require_relative 'job_chain/strategies/skip'
+require_relative 'plugins/job_chain'
+
+module Resque
+  module JobChain
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      def build(chain_id, &block)
+        builder = Builder.new(chain_id)
+        block.call(builder)
+        builder.to_chain
+      end
+
+      def status(chain_id)
+        Persistence.load_state(chain_id)
+      end
+
+      def context(chain_id)
+        Persistence.load_context(chain_id)
+      end
+
+      def update_context(chain_id, **updates)
+        Persistence.merge_context(chain_id, updates)
+      end
+
+      def active_chains
+        Persistence.active_chains
+      end
+    end
+  end
+end

data/lib/resque/plugins/job_chain.rb

@@ -0,0 +1,32 @@
+module Resque
+  module Plugins
+    module JobChain
+      def after_perform_job_chain(*args)
+        chain_id, step_index = extract_chain_meta(args)
+        return unless chain_id
+
+        executor = Resque::JobChain::Executor.new(chain_id, step_index)
+        executor.after_step
+      end
+
+      def on_failure_job_chain(exception, *args)
+        chain_id, step_index = extract_chain_meta(args)
+        return unless chain_id
+
+        executor = Resque::JobChain::Executor.new(chain_id, step_index)
+        executor.on_failure(exception)
+      end
+
+      private
+
+      def extract_chain_meta(args)
+        hash = args.find { |a| a.is_a?(Hash) }
+        return [nil, nil] unless hash
+
+        chain_id = hash['_chain_id'] || hash[:_chain_id]
+        step_index = hash['_step_index'] || hash[:_step_index]
+        [chain_id, step_index&.to_i]
+      end
+    end
+  end
+end

data/lib/resque-job-chain.rb

@@ -0,0 +1 @@
+require 'resque/job_chain'

data/lua/advance_chain.lua

@@ -0,0 +1,40 @@
+-- Atomically marks current step complete and advances chain.
+--
+-- KEYS[1] = chain state HASH key
+-- KEYS[2] = active chains SET key
+--
+-- ARGV[1] = current step index (expected)
+-- ARGV[2] = current timestamp ISO8601
+-- ARGV[3] = chain_id
+-- ARGV[4] = ttl_seconds (for completed chains)
+--
+-- Returns: "advanced" | "completed" | "stale"
+
+local current = redis.call("HGET", KEYS[1], "current_step")
+if current ~= ARGV[1] then
+  return "stale"
+end
+
+local total = tonumber(redis.call("HGET", KEYS[1], "total_steps"))
+local next_step = tonumber(ARGV[1]) + 1
+
+redis.call("HSET", KEYS[1],
+  "step_status:" .. ARGV[1], "completed",
+  "step_completed_at:" .. ARGV[1], ARGV[2],
+  "updated_at", ARGV[2])
+
+if next_step >= total then
+  redis.call("HSET", KEYS[1],
+    "status", "completed",
+    "completed_at", ARGV[2])
+  redis.call("SREM", KEYS[2], ARGV[3])
+  redis.call("EXPIRE", KEYS[1], tonumber(ARGV[4]))
+  return "completed"
+end
+
+redis.call("HSET", KEYS[1],
+  "current_step", tostring(next_step),
+  "step_status:" .. tostring(next_step), "running",
+  "step_started_at:" .. tostring(next_step), ARGV[2])
+
+return "advanced"

data/lua/fail_step.lua

@@ -0,0 +1,84 @@
+-- Atomically handles step failure based on the configured strategy.
+--
+-- KEYS[1] = chain state HASH key
+-- KEYS[2] = active chains SET key
+--
+-- ARGV[1] = step index
+-- ARGV[2] = error message
+-- ARGV[3] = strategy ("abort" | "retry" | "skip")
+-- ARGV[4] = max_attempts (for retry)
+-- ARGV[5] = timestamp ISO8601
+-- ARGV[6] = chain_id
+-- ARGV[7] = ttl_seconds
+--
+-- Returns: "aborted" | "retrying:{N}" | "exhausted" | "skipped" | "stale"
+
+local current = redis.call("HGET", KEYS[1], "current_step")
+if current ~= ARGV[1] then
+  return "stale"
+end
+
+local total = tonumber(redis.call("HGET", KEYS[1], "total_steps"))
+
+if ARGV[3] == "abort" then
+  redis.call("HSET", KEYS[1],
+    "status", "failed",
+    "step_status:" .. ARGV[1], "failed",
+    "error_message", ARGV[2],
+    "error_step", ARGV[1],
+    "updated_at", ARGV[5])
+  redis.call("SREM", KEYS[2], ARGV[6])
+  redis.call("EXPIRE", KEYS[1], tonumber(ARGV[7]))
+  return "aborted"
+end
+
+if ARGV[3] == "retry" then
+  local attempts_key = "attempts:" .. ARGV[1]
+  local current_attempts = redis.call("HGET", KEYS[1], attempts_key)
+  local attempts = tonumber(current_attempts or "0") + 1
+  local max = tonumber(ARGV[4])
+
+  if attempts >= max then
+    redis.call("HSET", KEYS[1],
+      "status", "failed",
+      "step_status:" .. ARGV[1], "failed",
+      attempts_key, tostring(attempts),
+      "error_message", ARGV[2],
+      "error_step", ARGV[1],
+      "updated_at", ARGV[5])
+    redis.call("SREM", KEYS[2], ARGV[6])
+    redis.call("EXPIRE", KEYS[1], tonumber(ARGV[7]))
+    return "exhausted"
+  end
+
+  redis.call("HSET", KEYS[1],
+    attempts_key, tostring(attempts),
+    "step_status:" .. ARGV[1], "running",
+    "updated_at", ARGV[5])
+  return "retrying:" .. tostring(attempts)
+end
+
+if ARGV[3] == "skip" then
+  local next_step = tonumber(ARGV[1]) + 1
+
+  redis.call("HSET", KEYS[1],
+    "step_status:" .. ARGV[1], "skipped",
+    "updated_at", ARGV[5])
+
+  if next_step >= total then
+    redis.call("HSET", KEYS[1],
+      "status", "completed",
+      "completed_at", ARGV[5])
+    redis.call("SREM", KEYS[2], ARGV[6])
+    redis.call("EXPIRE", KEYS[1], tonumber(ARGV[7]))
+    return "skipped"
+  end
+
+  redis.call("HSET", KEYS[1],
+    "current_step", tostring(next_step),
+    "step_status:" .. tostring(next_step), "running",
+    "step_started_at:" .. tostring(next_step), ARGV[5])
+  return "skipped"
+end
+
+return "unknown_strategy"

data/lua/start_chain.lua

@@ -0,0 +1,38 @@
+-- Atomically initializes a chain. NX semantics prevent duplicate starts.
+--
+-- KEYS[1] = chain state HASH key
+-- KEYS[2] = chain steps LIST key
+-- KEYS[3] = chain context STRING key
+-- KEYS[4] = active chains SET key
+--
+-- ARGV[1] = total_steps (integer as string)
+-- ARGV[2] = initial context JSON
+-- ARGV[3] = chain_id
+-- ARGV[4] = steps JSON array (array of JSON strings)
+-- ARGV[5] = current timestamp ISO8601
+--
+-- Returns: 1 if started, 0 if already exists
+
+if redis.call("EXISTS", KEYS[1]) == 1 then
+  return 0
+end
+
+redis.call("HSET", KEYS[1],
+  "status", "running",
+  "current_step", "0",
+  "total_steps", ARGV[1],
+  "started_at", ARGV[5],
+  "updated_at", ARGV[5],
+  "step_status:0", "running",
+  "step_started_at:0", ARGV[5])
+
+redis.call("SET", KEYS[3], ARGV[2])
+
+local steps = cjson.decode(ARGV[4])
+for _, step_json in ipairs(steps) do
+  redis.call("RPUSH", KEYS[2], step_json)
+end
+
+redis.call("SADD", KEYS[4], ARGV[3])
+
+return 1

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: resque-job-chain
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Duarte Reis
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: resque
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Resque plugin that declares ordered chains of jobs with shared context,
+  configurable error strategies (abort, retry, skip), and atomic Redis state tracking.
+email:
+- duarte.reis@zendesk.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/resque-job-chain.rb
+- lib/resque/job_chain.rb
+- lib/resque/job_chain/builder.rb
+- lib/resque/job_chain/chain.rb
+- lib/resque/job_chain/configuration.rb
+- lib/resque/job_chain/context.rb
+- lib/resque/job_chain/executor.rb
+- lib/resque/job_chain/observable.rb
+- lib/resque/job_chain/persistence.rb
+- lib/resque/job_chain/step.rb
+- lib/resque/job_chain/strategies/abort.rb
+- lib/resque/job_chain/strategies/base.rb
+- lib/resque/job_chain/strategies/retry.rb
+- lib/resque/job_chain/strategies/skip.rb
+- lib/resque/job_chain/version.rb
+- lib/resque/plugins/job_chain.rb
+- lua/advance_chain.lua
+- lua/fail_step.lua
+- lua/start_chain.lua
+homepage: https://github.com/duarteareiasdosreis/resque-job-chain
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/duarteareiasdosreis/resque-job-chain
+  source_code_uri: https://github.com/duarteareiasdosreis/resque-job-chain
+  changelog_uri: https://github.com/duarteareiasdosreis/resque-job-chain/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ordered job chain execution for Resque
+test_files: []