busybee 0.2.0 → 0.3.0

data/lib/busybee/runtime_config.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Busybee
+  # Operator-specified runtime configuration, typically from CLI flags or YAML.
+  #
+  # Two-phase lifecycle:
+  #   1. Constructed sparse (only fields the operator explicitly set)
+  #   2. After resolve_for(worker_class), fully resolved through the precedence chain:
+  #      per-worker RuntimeConfig → global RuntimeConfig → worker DSL → gem defaults
+  #
+  # Fields are divided into two groups:
+  #   - Worker-scoped: participate in the full 4-level precedence chain including
+  #     per-worker overrides. Passed to runner constructors.
+  #   - Process-wide: resolve at global RC → gem default only (no per-worker step).
+  #     Applied to gem-level config before runners start.
+  #
+  # Runners hold the resolved config at runtime.
+  class RuntimeConfig
+    VALID_WORKER_MODES = %i[polling streaming hybrid].freeze
+    VALID_LOG_FORMATS = %i[text json].freeze
+
+    # Top-level keys allowed in YAML config (worker-scoped fields + workers).
+    WORKER_SCOPED_KEYS = %i[worker_mode backpressure_delay max_jobs request_timeout
+                            buffer buffer_throttle job_timeout backoff].freeze
+    VALID_YAML_KEYS = (WORKER_SCOPED_KEYS + %i[workers]).freeze
+    PROCESS_WIDE_KEYS = %i[log_format worker_name cluster_address].freeze
+
+    # Parses a YAML config file and returns a kwargs hash suitable for
+    # RuntimeConfig.new(**result). Raw YAML types flow through — the
+    # constructor handles coercion (e.g., string → symbol for worker_mode).
+    def self.parse_yaml(path)
+      raw = YAML.safe_load_file(path) || {}
+      result = {}
+
+      raw.each do |key, value|
+        sym_key = key.to_sym
+        validate_yaml_key!(sym_key)
+        if sym_key == :workers
+          result[:workers] = parse_workers(value)
+        else
+          result[sym_key] = value
+        end
+      end
+
+      result
+    end
+
+    def self.validate_yaml_key!(key)
+      if PROCESS_WIDE_KEYS.include?(key)
+        raise ArgumentError, "#{key} is CLI-only and cannot be set in YAML. Use the corresponding CLI flag instead."
+      end
+      return if VALID_YAML_KEYS.include?(key)
+
+      raise ArgumentError,
+            "Unrecognized YAML key: #{key}. Valid keys: #{VALID_YAML_KEYS.join(', ')}"
+    end
+    private_class_method :validate_yaml_key!
+
+    def self.parse_workers(workers_list)
+      return {} unless workers_list
+
+      workers_list.each_with_object({}) do |entry, acc|
+        name, overrides = case entry
+                          when String then [entry, {}]
+                          when Hash   then extract_worker_entry(entry)
+                          end
+        validate_worker_override_keys!(name, overrides)
+        acc[name.to_s] = overrides
+      end
+    end
+    private_class_method :parse_workers
+
+    # A worker entry hash comes in two forms depending on YAML indentation:
+    #   Nested:  { "Worker" => { "max_jobs" => 32 } }
+    #   Flat:    { "Worker" => nil, "max_jobs" => 32 }
+    def self.extract_worker_entry(hash)
+      first_key, first_value = hash.first
+      if first_value.is_a?(Hash)
+        [first_key, first_value.transform_keys(&:to_sym)]
+      else
+        overrides = hash.compact.transform_keys(&:to_sym)
+        [first_key, overrides]
+      end
+    end
+    private_class_method :extract_worker_entry
+
+    def self.validate_worker_override_keys!(worker_name, overrides)
+      unknown = overrides.keys - WORKER_SCOPED_KEYS
+      return if unknown.empty?
+
+      raise ArgumentError,
+            "Unrecognized override keys for #{worker_name}: #{unknown.join(', ')}. " \
+            "Valid keys: #{WORKER_SCOPED_KEYS.join(', ')}"
+    end
+    private_class_method :validate_worker_override_keys!
+
+    # Worker-scoped fields (CLI: worker_mode only; all configurable via YAML)
+    attr_reader :worker_mode, :backpressure_delay, :max_jobs, :request_timeout,
+                :buffer, :buffer_throttle, :job_timeout, :backoff
+
+    # Process-wide fields
+    attr_reader :log_format, :worker_name, :cluster_address
+
+    def initialize(worker_mode: nil, backpressure_delay: nil, max_jobs: nil, # rubocop:disable Metrics/AbcSize,Metrics/ParameterLists
+                   request_timeout: nil, buffer: nil, buffer_throttle: nil,
+                   job_timeout: nil, backoff: nil,
+                   log_format: nil, worker_name: nil, cluster_address: nil,
+                   workers: {})
+      @worker_mode = coerce_symbol!(worker_mode, VALID_WORKER_MODES, "worker mode") if worker_mode
+      @backpressure_delay = backpressure_delay
+      @max_jobs = max_jobs
+      @request_timeout = request_timeout
+      @buffer = buffer
+      @buffer_throttle = buffer_throttle
+      @job_timeout = job_timeout
+      @backoff = backoff
+      @log_format = coerce_symbol!(log_format, VALID_LOG_FORMATS, "log format") if log_format
+      @worker_name = worker_name
+      @cluster_address = cluster_address
+      @workers = workers.each_with_object({}) do |(name, overrides), validated|
+        if overrides[:worker_mode]
+          mode = coerce_symbol!(overrides[:worker_mode], VALID_WORKER_MODES, "worker mode")
+          overrides = overrides.merge(worker_mode: mode)
+        end
+        validated[name.to_s] = overrides
+      end
+    end
+
+    # Resolves configuration for a specific worker class through the full
+    # precedence chain. Returns a new RuntimeConfig with all values populated.
+    #
+    # Worker-scoped fields resolve through 4 levels:
+    #   1. Per-worker RuntimeConfig override (highest priority)
+    #   2. Global RuntimeConfig value
+    #   3. Worker DSL (worker_class.configuration)
+    #   4. Gem default (lowest priority)
+    #
+    # Process-wide fields resolve through 2 levels:
+    #   1. Global RuntimeConfig value
+    #   2. Gem default
+    def resolve_for(worker_class) # rubocop:disable Metrics/AbcSize
+      wo = @workers[worker_class.name] || {}
+      dsl = worker_class.configuration
+
+      # rubocop:disable Layout/HashAlignment, Layout/LineLength
+      self.class.new(
+        worker_mode:        first_non_nil(wo[:worker_mode], @worker_mode, dsl.worker_mode, Busybee.default_worker_mode),
+        backpressure_delay: first_non_nil(wo[:backpressure_delay], @backpressure_delay, dsl.backpressure_delay, Busybee.default_backpressure_delay),
+        max_jobs:           first_non_nil(wo[:max_jobs], @max_jobs, dsl.polling_config[:max_jobs], Busybee.default_max_jobs),
+        request_timeout:    first_non_nil(wo[:request_timeout], @request_timeout, dsl.polling_config[:request_timeout], Busybee.default_job_request_timeout),
+        buffer:     first_non_nil(wo[:buffer], @buffer, dsl.streaming_config[:buffer], Busybee.default_buffer),
+        buffer_throttle:    first_non_nil(wo[:buffer_throttle], @buffer_throttle, dsl.streaming_config[:buffer_throttle], Busybee.default_buffer_throttle),
+        job_timeout:        first_non_nil(wo[:job_timeout], @job_timeout, dsl.job_timeout, Busybee.default_job_lock_timeout),
+        backoff:            first_non_nil(wo[:backoff], @backoff, dsl.backoff, Busybee.default_fail_job_backoff),
+        log_format:         first_non_nil(@log_format, Busybee.log_format),
+        worker_name:        first_non_nil(@worker_name, Busybee.worker_name),
+        cluster_address:    first_non_nil(@cluster_address, Busybee.cluster_address)
+      )
+      # rubocop:enable Layout/HashAlignment, Layout/LineLength
+    end
+
+    # Convenience method for runner consumption. Returns polling-relevant fields
+    # as a hash matching the shape expected by client.with_each_job.
+    def polling_options
+      { max_jobs: @max_jobs, request_timeout: @request_timeout, job_timeout: @job_timeout }
+    end
+
+    private
+
+    def first_non_nil(*values)
+      values.find { |v| !v.nil? }
+    end
+
+    def coerce_symbol!(value, valid_set, label)
+      sym = value.to_s.to_sym
+      return sym if valid_set.include?(sym)
+
+      raise ArgumentError,
+            "Invalid #{label}: #{value.inspect}. Valid: #{valid_set.map(&:inspect).join(', ')}"
+    end
+  end
+end

data/lib/busybee/testing/activated_job.rb

@@ -142,6 +142,19 @@ module Busybee
         self
       end
 
+      # Update the job's timeout.
+      #
+      # @param timeout [Integer] new timeout in milliseconds
+      # @return [self]
+      def update_timeout(timeout)
+        request = Busybee::GRPC::UpdateJobTimeoutRequest.new(
+          jobKey: key,
+          timeout: timeout.to_i
+        )
+        client.update_job_timeout(request)
+        self
+      end
+
       private
 
       def stringify_keys(hash)

data/lib/busybee/testing/helpers/execution.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "busybee/job"
+require "busybee/serialization"
+
+module Busybee
+  module Testing
+    module Helpers
+      # Builds test jobs and executes workers without a Zeebe connection.
+      #
+      # Included into Busybee::Testing::Helpers, which is auto-included in all
+      # RSpec examples when busybee/testing is required.
+      #
+      # @example Happy path
+      #   result = execute_worker(
+      #     ProcessOrderWorker,
+      #     variables: { order_id: order.id }
+      #   )
+      #   expect(result).to eq(status: "processed")
+      #
+      # @example Inspect job status after failure
+      #   job = build_test_job(variables: { order_id: 999 })
+      #   expect {
+      #     execute_worker(ProcessOrderWorker, job: job)
+      #   }.to raise_error(ActiveRecord::RecordNotFound)
+      #   expect(job).to be_failed
+      #
+      module Execution
+        # Build a test job backed by a stub client.
+        #
+        # The returned Job behaves like a real job — variables and headers are
+        # parsed, status tracking works, and all client operations (complete!,
+        # fail!, throw_bpmn_error!, update_retries, update_timeout) succeed
+        # silently through a stub client.
+        #
+        # @param type [String] job type (defaults to "test")
+        # @param variables [Hash] process variables
+        # @param headers [Hash] custom headers
+        # @param bpmn_process_id [String] BPMN process ID
+        # @param retries [Integer] retry count
+        # @return [Busybee::Job]
+        def build_test_job(type: "test", variables: {}, headers: {},
+                           bpmn_process_id: "test-process", retries: 3)
+          client = stub_client
+          raw_job = stub_raw_job(
+            type: type,
+            variables: variables,
+            headers: headers,
+            bpmn_process_id: bpmn_process_id,
+            retries: retries
+          )
+          Busybee::Job.new(raw_job, client: client)
+        end
+
+        # Execute a worker's full lifecycle against a test job.
+        #
+        # Runs the real Worker.perform_job — input validation, perform, output
+        # validation, auto-complete/auto-fail all execute as in production. The
+        # only difference: errors are re-raised after handle_failure completes,
+        # so you can use +expect { }.to raise_error+ alongside +expect(job).to be_failed+.
+        #
+        # @overload execute_worker(worker_class, variables: {}, headers: {},
+        #   bpmn_process_id: "test-process", retries: 3)
+        #   Build a test job from keyword arguments and execute.
+        #   @param worker_class [Class<Busybee::Worker>] the worker class to test
+        #   @param variables [Hash] process variables
+        #   @param headers [Hash] custom headers
+        #   @param bpmn_process_id [String] BPMN process ID
+        #   @param retries [Integer] retry count
+        #   @return [Object] the return value of the worker's +perform+ method
+        #
+        # @overload execute_worker(worker_class, job:)
+        #   Execute with a pre-built test job (from build_test_job).
+        #   @param worker_class [Class<Busybee::Worker>] the worker class to test
+        #   @param job [Busybee::Job] a pre-built test job
+        #   @return [Object] the return value of the worker's +perform+ method
+        #
+        def execute_worker(worker_class, job: nil, # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength
+                           variables: {}, headers: {},
+                           bpmn_process_id: "test-process", retries: 3)
+          if job
+            unless variables.empty? && headers.empty? &&
+                   bpmn_process_id == "test-process" && retries == 3
+              raise ArgumentError,
+                    "Cannot pass job: together with variables:, headers:, " \
+                    "bpmn_process_id:, or retries:. Use build_test_job to " \
+                    "pre-configure the job, or pass keyword arguments — not both."
+            end
+          else
+            job = build_test_job(
+              type: worker_class.job_type,
+              variables: variables, headers: headers,
+              bpmn_process_id: bpmn_process_id, retries: retries
+            )
+          end
+
+          # Wrap handle_failure to re-raise after production logic runs.
+          # This lets tests assert both error class AND job status.
+          allow(worker_class).to(
+            receive(:handle_failure).and_wrap_original do |m, *args|
+              m.call(*args).tap { raise args[1] }
+            end
+          )
+
+          worker_class.perform_job(job)
+        end
+
+        private
+
+        def stub_client
+          instance_double(
+            Busybee::Client,
+            complete_job: true,
+            fail_job: true,
+            throw_bpmn_error: true,
+            update_job_retries: true,
+            update_job_timeout: true
+          )
+        end
+
+        def stub_raw_job(type:, variables:, headers:, bpmn_process_id:, retries:)
+          # Plain double because protobuf generates field accessors dynamically
+          # via descriptors, which instance_double can't verify against.
+          double(
+            "Busybee::GRPC::ActivatedJob",
+            key: rand(100_000..999_999),
+            type: type,
+            processInstanceKey: rand(100_000..999_999),
+            bpmnProcessId: bpmn_process_id,
+            retries: retries,
+            deadline: (Time.now.to_i + 300) * 1000,
+            variables: Busybee::Serialization.to_json(variables),
+            customHeaders: Busybee::Serialization.to_json(headers)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/busybee/testing/helpers/support.rb

@@ -43,7 +43,7 @@ module Busybee
         def activate_jobs_raw(type, max_jobs:, timeout: nil)
           worker = "#{type}-#{SecureRandom.hex(4)}"
 
-          request_timeout = timeout || Busybee::Testing.activate_request_timeout
+          request_timeout = timeout || Busybee.default_job_request_timeout
           request_timeout_ms = if request_timeout.is_a?(ActiveSupport::Duration)
                                  request_timeout.in_milliseconds.to_i
                                else

data/lib/busybee/testing/helpers.rb

@@ -8,6 +8,7 @@ require "busybee/grpc"
 require "busybee/serialization"
 require "busybee/testing/activated_job"
 require "busybee/testing/helpers/support"
+require "busybee/testing/helpers/execution"
 
 module Busybee
   module Testing
@@ -17,6 +18,7 @@ module Busybee
     # RSpec helper methods for testing BPMN workflows against Zeebe.
     module Helpers
       extend Support
+      include Execution
 
       # Deploy a BPMN process file to Zeebe.
       #
@@ -151,7 +153,7 @@ module Busybee
       # Activate a single job of the given type.
       #
       # @param type [String] job type
-      # @param timeout [Integer, nil] request timeout in milliseconds (defaults to Busybee::Testing.activate_request_timeout)
+      # @param timeout [Integer, nil] request timeout in milliseconds (defaults to Busybee.default_job_request_timeout)
       # @return [ActivatedJob]
       # @raise [NoJobAvailable] if no job is available
       def activate_job(type, timeout: nil)
@@ -165,7 +167,7 @@ module Busybee
       #
       # @param type [String] job type
       # @param max_jobs [Integer] maximum number of jobs to activate
-      # @param timeout [Integer, nil] request timeout in milliseconds (defaults to Busybee::Testing.activate_request_timeout)
+      # @param timeout [Integer, nil] request timeout in milliseconds (defaults to Busybee.default_job_request_timeout)
       # @return [Enumerator<ActivatedJob>]
       def activate_jobs(type, max_jobs:, timeout: nil)
         Enumerator.new do |yielder|

data/lib/busybee/testing/matchers/complete_job.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+# Asserts that a worker completes the job successfully.
+#
+# Checks that the job ends in +:complete+ status. Optionally checks
+# the return value of +perform+ for expected variables via +with_vars+.
+#
+# @example Basic usage
+#   job = build_test_job(variables: { order_id: 1 })
+#   expect(MyWorker).to complete_job(job)
+#
+# @example With expected return variables
+#   expect(MyWorker).to complete_job(job).with_vars(status: "done")
+#
+RSpec::Matchers.define :complete_job do |job|
+  match do |worker_class|
+    @result = execute_worker(worker_class, job: job)
+    return false unless job.complete?
+
+    if @expected_vars
+      if @result.is_a?(Hash)
+        values_match?(@expected_vars, @result)
+      else
+        @expected_vars == {}
+      end
+    else
+      true
+    end
+  rescue StandardError => e
+    @raised_error = e
+    false
+  end
+
+  chain :with_vars do |expected|
+    @expected_vars = expected
+  end
+
+  chain :with_no_vars do
+    @expected_vars = {}
+  end
+
+  failure_message do
+    if @raised_error
+      "expected #{actual} to complete the job, but it raised " \
+        "#{@raised_error.class}: #{@raised_error.message}"
+    elsif !job.complete?
+      "expected job to be complete, but was #{job.status}"
+    else
+      "expected result to match #{@expected_vars.inspect}, " \
+        "got #{@result.inspect}"
+    end
+  end
+end

data/lib/busybee/testing/matchers/fail_job.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+# Asserts that a worker fails the job with an optional error match.
+#
+# Accepts the same argument forms as RSpec's +raise_error+:
+#   with_error(ErrorClass)
+#   with_error(ErrorClass, "exact message")
+#   with_error(ErrorClass, /message pattern/)
+#   with_error("exact message")
+#   with_error(/message pattern/)
+#
+# @example Basic usage
+#   job = build_test_job(variables: { order_id: 999 })
+#   expect(MyWorker).to fail_job(job)
+#
+# @example With error class
+#   expect(MyWorker).to fail_job(job).with_error(ActiveRecord::RecordNotFound)
+#
+# @example With error class and message
+#   expect(MyWorker).to fail_job(job).with_error(ArgumentError, /invalid/)
+#
+RSpec::Matchers.define :fail_job do |job|
+  match do |worker_class|
+    execute_worker(worker_class, job: job)
+    @no_error = true
+    false
+  rescue StandardError => e
+    @raised_error = e
+    job.failed? && error_matches?(e)
+  end
+
+  chain :with_error do |expected_error_or_message, expected_message = nil|
+    case expected_error_or_message
+    when String, Regexp
+      @expected_error = StandardError
+      @expected_message = expected_error_or_message
+    else
+      @expected_error = expected_error_or_message
+      @expected_message = expected_message
+    end
+  end
+
+  def error_matches?(error)
+    return true unless @expected_error
+
+    class_matches = @expected_error === error # rubocop:disable Style/CaseEquality
+    return false unless class_matches
+    return true unless @expected_message
+
+    case @expected_message
+    when Regexp then error.message.match?(@expected_message)
+    else error.message == @expected_message.to_s
+    end
+  end
+
+  failure_message do
+    if @no_error
+      "expected #{actual} to fail the job, but it completed successfully"
+    elsif !job.failed?
+      "expected job to be failed, but was #{job.status}"
+    else
+      "expected error matching #{expected_description}, " \
+        "got #{@raised_error.class}: #{@raised_error.message}"
+    end
+  end
+
+  def expected_description
+    parts = []
+    parts << @expected_error.inspect if @expected_error
+    parts << @expected_message.inspect if @expected_message
+    parts.join(" with message ")
+  end
+end

data/lib/busybee/testing/matchers/throw_bpmn_error_on.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+# Asserts that a worker throws a BPMN error on the job.
+#
+# Captures the error code and message passed to the stub client's
+# +throw_bpmn_error+ call for optional verification via +with_code+.
+#
+# @example Basic usage
+#   job = build_test_job(variables: { order_id: 999 })
+#   expect(MyWorker).to throw_bpmn_error_on(job)
+#
+# @example With error code
+#   expect(MyWorker).to throw_bpmn_error_on(job).with_code(:not_found)
+#
+# @example With error code and message
+#   expect(MyWorker).to throw_bpmn_error_on(job).with_code(:not_found, message: /missing/)
+#
+RSpec::Matchers.define :throw_bpmn_error_on do |job|
+  match do |worker_class|
+    client = job.instance_variable_get(:@client)
+    allow(client).to receive(:throw_bpmn_error) do |_key, code, message:|
+      @actual_code = code
+      @actual_message = message
+    end
+
+    execute_worker(worker_class, job: job)
+    return false unless job.error?
+
+    code_matches? && message_matches?
+  rescue StandardError => e
+    @raised_error = e
+    false
+  end
+
+  chain :with_code do |expected_code, opts = {}|
+    @expected_code = case expected_code
+                     when Symbol then expected_code.to_s.upcase
+                     when Class then expected_code.name.gsub("::", "_").underscore.upcase
+                     else expected_code
+                     end
+    @expected_message = opts[:message]
+  end
+
+  def code_matches?
+    return true unless @expected_code
+
+    values_match?(@expected_code, @actual_code)
+  end
+
+  def message_matches?
+    return true unless @expected_message
+
+    values_match?(@expected_message, @actual_message)
+  end
+
+  failure_message do
+    if @raised_error
+      "expected #{actual} to throw a BPMN error, but it raised " \
+        "#{@raised_error.class}: #{@raised_error.message}"
+    elsif !job.error?
+      "expected job to be error, but was #{job.status}"
+    elsif @expected_code && !code_matches?
+      "expected BPMN error code #{@expected_code.inspect}, " \
+        "got #{@actual_code.inspect}"
+    else
+      "expected BPMN error message #{@expected_message.inspect}, " \
+        "got #{@actual_message.inspect}"
+    end
+  end
+end

data/lib/busybee/testing.rb

@@ -3,25 +3,8 @@
 require "busybee/grpc"
 
 module Busybee
-  # Testing support for BPMN workflows with RSpec.
-  #
-  # @example Configuration
-  #   Busybee::Testing.configure do |config|
-  #     config.activate_request_timeout = 2000
-  #   end
-  #
+  # Testing support for BPMN workflows and workers with RSpec.
   module Testing
-    class << self
-      attr_writer :activate_request_timeout
-
-      def configure
-        yield self
-      end
-
-      def activate_request_timeout
-        @activate_request_timeout || 1000
-      end
-    end
   end
 end
 
@@ -33,6 +16,9 @@ if defined?(RSpec)
   require "busybee/testing/matchers/have_received_headers"
   require "busybee/testing/matchers/have_activated"
   require "busybee/testing/matchers/have_available_jobs"
+  require "busybee/testing/matchers/fail_job"
+  require "busybee/testing/matchers/complete_job"
+  require "busybee/testing/matchers/throw_bpmn_error_on"
 
   RSpec.configure do |config|
     config.include Busybee::Testing::Helpers

data/lib/busybee/version.rb

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