busybee 0.1.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/serialization.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/hash/indifferent_access"
+require "active_support/core_ext/string/inflections"
+require "active_support/json"
+require "busybee/error"
+require "json"
+
+module Busybee
+  # Centralized JSON serialization and deserialization for GRPC communication.
+  #
+  # Provides consistent handling of Ruby objects to/from JSON strings,
+  # with proper as_json support for serialization and indifferent access
+  # with method-style accessors for deserialization.
+  module Serialization
+    # Serialize a Ruby object to JSON string for GRPC.
+    #
+    # Calls as_json first so objects with custom serialization
+    # (like ActiveRecord models, Time, etc.) work correctly.
+    #
+    # @param obj [Object] The object to serialize (typically a Hash)
+    # @return [String] JSON string
+    def self.to_json(obj)
+      JSON.generate(obj.as_json)
+    end
+
+    # Deserialize a JSON string from GRPC to a frozen Ruby hash.
+    #
+    # Returns a frozen HashWithIndifferentAccess with method-style access
+    # (via HashAccess module). Nested hashes and arrays are also frozen
+    # and support method-style access.
+    #
+    # @param json_string [String, nil] The JSON string to parse
+    # @return [ActiveSupport::HashWithIndifferentAccess] frozen hash with method access
+    # @raise [Busybee::InvalidJobJson] if JSON is invalid
+    def self.from_json(json_string)
+      if json_string.nil? || json_string.empty?
+        return ActiveSupport::HashWithIndifferentAccess.new.extend(HashAccess).freeze
+      end
+
+      parsed = JSON.parse(json_string)
+      deep_freeze_and_extend(parsed.with_indifferent_access)
+    rescue JSON::ParserError => e
+      raise Busybee::InvalidJobJson, "Failed to parse JSON: #{e.message}", e.backtrace, cause: e
+    end
+
+    # Recursively freeze and extend hashes with HashAccess.
+    #
+    # @param obj [Object] The object to process
+    # @return [Object] The frozen, extended object
+    def self.deep_freeze_and_extend(obj)
+      case obj
+      when Hash
+        obj.extend(HashAccess)
+        obj.each_value { |value| deep_freeze_and_extend(value) }
+        obj.freeze
+      when Array
+        obj.each { |element| deep_freeze_and_extend(element) }
+        obj.freeze
+      else
+        obj.freeze if obj.respond_to?(:freeze)
+        obj
+      end
+    end
+
+    private_class_method :deep_freeze_and_extend
+
+    # Module that adds method-style access to hashes with camelCase to snake_case conversion.
+    #
+    # Allows accessing hash keys as methods:
+    #   hash.order_id       # looks for "order_id" or "orderId"
+    #   hash.customer_name  # looks for "customer_name" or "customerName"
+    #
+    # Recursively applied to nested hashes.
+    module HashAccess
+      def method_missing(method_name, *args, **kwargs, &block)
+        return super if args.any? || kwargs.any? || block
+
+        # Convert snake_case method name to potential camelCase keys
+        snake_key = method_name.to_s
+        camel_key = snake_key.camelize(:lower)
+
+        if key?(snake_key)
+          self[snake_key]
+        elsif key?(camel_key)
+          self[camel_key]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        snake_key = method_name.to_s
+        camel_key = snake_key.camelize(:lower)
+        key?(snake_key) || key?(camel_key) || super
+      end
+    end
+  end
+end

data/lib/busybee/testing/activated_job.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "json"
 require "rspec/matchers"
 require "busybee/grpc"
+require "busybee/serialization"
 
 module Busybee
   module Testing
@@ -32,22 +32,34 @@ module Busybee
         raw.key
       end
 
-      def process_instance_key
-        raw.processInstanceKey
+      def type
+        raw.type
       end
 
-      def variables
-        @variables ||= JSON.parse(raw.variables)
+      def process_instance_key
+        raw.processInstanceKey
       end
 
-      def headers
-        @headers ||= JSON.parse(raw.customHeaders)
+      def bpmn_process_id
+        raw.bpmnProcessId
       end
 
       def retries
         raw.retries
       end
 
+      def deadline
+        raw.deadline
+      end
+
+      def variables
+        @variables ||= Busybee::Serialization.from_json(raw.variables)
+      end
+
+      def headers
+        @headers ||= Busybee::Serialization.from_json(raw.customHeaders)
+      end
+
       # Assert that job variables include the expected values.
       # Raises RSpec expectation failure if not matched.
       #
@@ -75,7 +87,7 @@ module Busybee
       def mark_completed(variables = {})
         request = Busybee::GRPC::CompleteJobRequest.new(
           jobKey: key,
-          variables: JSON.generate(variables)
+          variables: Busybee::Serialization.to_json(variables)
         )
         client.complete_job(request)
         self
@@ -130,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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/duration"
+require "json"
+require "securerandom"
+require "busybee/grpc"
+
+module Busybee
+  module Testing
+    module Helpers
+      # These methods are available *on Helpers,* as module-level methods, which keeps them
+      # isolated from the test context of the public helper methods which consume them.
+      module Support
+        def unique_process_id
+          "test-process-#{SecureRandom.hex(6)}"
+        end
+
+        def extract_process_id(bpmn_content)
+          match = bpmn_content.match(/<bpmn:process id="([^"]+)"/)
+          match ? match[1] : nil
+        end
+
+        def bpmn_with_unique_id(bpmn_path, process_id)
+          bpmn_content = File.read(bpmn_path)
+          bpmn_content.
+            gsub(/(<bpmn:process id=")[^"]+/, "\\1#{process_id}").
+            # Possessive quantifiers (++, *+) prevent polynomial backtracking
+            gsub(/(<bpmndi:BPMNPlane\s++[^>]*+bpmnElement=")[^"]++/, "\\1#{process_id}")
+        end
+
+        def cancel_process_instance(key)
+          request = Busybee::GRPC::CancelProcessInstanceRequest.new(
+            processInstanceKey: key
+          )
+          grpc_client.cancel_process_instance(request)
+          true
+        rescue ::GRPC::NotFound
+          # Process already completed, ignore
+          false
+        end
+
+        def activate_jobs_raw(type, max_jobs:, timeout: nil)
+          worker = "#{type}-#{SecureRandom.hex(4)}"
+
+          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
+                                 request_timeout.to_i
+                               end
+
+          request = Busybee::GRPC::ActivateJobsRequest.new(
+            type: type,
+            worker: worker,
+            timeout: 30_000,
+            maxJobsToActivate: max_jobs,
+            requestTimeout: request_timeout_ms
+          )
+
+          jobs = []
+          grpc_client.activate_jobs(request).each do |response|
+            jobs.concat(response.jobs.to_a)
+          end
+          jobs
+        end
+
+        # This is the central grpc_client implementation (the one you should usually mock in a test).
+        # The actual public helper instance method delegates to this. It uses Busybee.credential_type
+        # if set, and attempts to autodetect from env vars otherwise.
+        def grpc_client
+          require "busybee/credentials"
+          Busybee::Credentials.build.grpc_stub
+        end
+      end
+    end
+  end
+end