busybee 0.1.0 → 0.3.0

data/lib/busybee/logging.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "busybee"
+require "json"
+
+module Busybee
+  # Centralized logging with prefixing and optional JSON formatting.
+  # Thread-safe: a mutex serializes format + write so concurrent threads
+  # cannot interleave within a single log line.
+  module Logging
+    PREFIX = "[busybee]"
+
+    class << self
+      def debug(message, **context)
+        log(:debug, message, **context)
+      end
+
+      def info(message, **context)
+        log(:info, message, **context)
+      end
+
+      def warn(message, **context)
+        log(:warn, message, **context)
+      end
+
+      def error(message, **context)
+        log(:error, message, **context)
+      end
+
+      private
+
+      def mutex = @mutex ||= Mutex.new
+
+      def log(level, message, **context)
+        return unless Busybee.logger
+
+        mutex.synchronize do
+          formatted = case Busybee.log_format
+                      when :text then format_text(message, **context)
+                      when :json then format_json(level, message, **context)
+                      end
+
+          Busybee.logger.public_send(level, formatted)
+        end
+      end
+
+      def format_text(message, **context)
+        formatted = "#{PREFIX} #{message}"
+        formatted += " (#{context.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')})" if context.any?
+        formatted
+      end
+
+      def format_json(level, message, **context)
+        context.merge(
+          message: "#{PREFIX} #{message}",
+          level: level.to_s
+        ).to_json
+      end
+    end
+  end
+end

data/lib/busybee/railtie.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "rails"
+require "active_support/core_ext/object/blank"
+require "busybee"
+
+module Busybee
+  # Rails integration for Busybee.
+  # Automatically configures Busybee from Rails configuration.
+  #
+  # @example Basic configuration
+  #   config.x.busybee.cluster_address = "localhost:26500"
+  #   config.x.busybee.credential_type = :insecure
+  #
+  # @example Camunda Cloud with Rails credentials
+  #   config.x.busybee.credential_type = :camunda_cloud
+  #   config.x.busybee.client_id = Rails.application.credentials.zeebe[:client_id]
+  #   config.x.busybee.client_secret = Rails.application.credentials.zeebe[:client_secret]
+  #   config.x.busybee.cluster_id = Rails.application.credentials.zeebe[:cluster_id]
+  #   config.x.busybee.region = "bru-2"
+  #
+  # @example Explicit credentials object
+  #   config.x.busybee.credentials = MyCustomCredentials.new(...)
+  #
+  class Railtie < Rails::Railtie
+    # Credential parameters that can be configured via config.x.busybee.*
+    CREDENTIAL_PARAMS = %i[
+      cluster_address client_id client_secret cluster_id region
+      token_url audience scope certificate_file
+    ].freeze
+
+    initializer "busybee.configure" do
+      Busybee.configure do |config|
+        busybee_conf = Rails.configuration.x.busybee
+
+        # Logger: Rails.logger by default, custom logger if set, nil if explicitly false
+        config.logger = case busybee_conf&.logger
+                        when false then nil
+                        when nil, true then Rails.logger
+                        else busybee_conf.logger
+                        end
+
+        next unless busybee_conf.presence
+
+        config.log_format = busybee_conf.log_format.presence if busybee_conf.log_format.presence
+        config.cluster_address = busybee_conf.cluster_address.presence
+        config.worker_name = busybee_conf.worker_name.presence
+
+        # Credentials: explicit object, or build from type + params
+        Busybee::Railtie.configure_credentials(config, busybee_conf)
+
+        # GRPC retry configuration
+        config.grpc_retry_enabled = !!busybee_conf.grpc_retry_enabled unless busybee_conf.grpc_retry_enabled.nil?
+        config.grpc_retry_delay_ms = busybee_conf.grpc_retry_delay_ms if busybee_conf.grpc_retry_delay_ms.presence
+        config.grpc_retry_errors = Array(busybee_conf.grpc_retry_errors) if busybee_conf.grpc_retry_errors.presence
+
+        # Client API method defaults
+        %i[default_message_ttl default_fail_job_backoff
+           default_job_request_timeout default_job_lock_timeout].each do |attr|
+          value = busybee_conf.public_send(attr)
+          config.public_send(:"#{attr}=", value) if value.presence
+        end
+
+        # Worker defaults
+        Busybee::Railtie.configure_worker_defaults(config, busybee_conf)
+      end
+    end
+
+    # @api private
+    def self.configure_worker_defaults(config, busybee_conf) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+      unless busybee_conf.default_input_required.nil?
+        config.default_input_required = !!busybee_conf.default_input_required
+      end
+      config.default_max_jobs = busybee_conf.default_max_jobs if busybee_conf.default_max_jobs.presence
+      unless busybee_conf.default_output_required.nil?
+        config.default_output_required = !!busybee_conf.default_output_required
+      end
+      config.default_buffer = !!busybee_conf.default_buffer unless busybee_conf.default_buffer.nil?
+      unless busybee_conf.default_buffer_throttle.nil?
+        config.default_buffer_throttle = busybee_conf.default_buffer_throttle
+      end
+      config.default_worker_mode = busybee_conf.default_worker_mode if busybee_conf.default_worker_mode.presence
+      if busybee_conf.default_backpressure_delay.presence
+        config.default_backpressure_delay = busybee_conf.default_backpressure_delay
+      end
+      config.shutdown_on_errors = busybee_conf.shutdown_on_errors if busybee_conf.shutdown_on_errors.presence
+    end
+
+    # @api private
+    def self.configure_credentials(config, busybee_conf)
+      # Option 1: Explicit credentials object
+      if busybee_conf.credentials.is_a?(Busybee::Credentials)
+        config.credentials = busybee_conf.credentials
+        return
+      end
+
+      # Option 2: Build credentials from type + params (or autodetect from params alone)
+      credential_type = busybee_conf.credential_type.presence
+      credential_params = extract_credential_params(busybee_conf)
+
+      config.credential_type = credential_type if credential_type
+      config.credentials = Busybee::Credentials.build(**credential_params) if credential_params.any?
+    end
+
+    # @api private
+    def self.extract_credential_params(busybee_conf)
+      CREDENTIAL_PARAMS.each_with_object({}) do |param, hash|
+        value = busybee_conf.public_send(param)
+        hash[param] = value unless value.nil?
+      end
+    end
+  end
+end

data/lib/busybee/runner/hybrid.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Busybee
+  class Runner
+    # Hybrid runner — combines polling and streaming for best-of-both-worlds job processing.
+    # Subclasses Streaming, adding a drain phase: opens a stream first (captures all new jobs),
+    # drains the backlog via polling, then transitions to buffer-only processing.
+    # The pump thread reads from the stream into a thread-safe buffer; the main thread does
+    # all perform_job calls (sequential guarantee).
+    class Hybrid < Streaming
+      BACKPRESSURE_ERRORS = [::GRPC::ResourceExhausted].freeze
+
+      private
+
+      # Always uses pump thread + buffer — the drain phase requires it.
+      def buffer?
+        true
+      end
+
+      # Override to insert drain phase between pump start and buffer processing.
+      def run_with_buffer
+        @pump_thread = Thread.new { pump_stream_into_buffer }
+
+        # Phase 2: Drain backlog via polling (main thread, sequential, returns when backlog is empty)
+        drain_backlog_while_also_processing_buffer
+
+        # Phase 3: Process from buffer only (main thread, sequential, returns when stream is cancelled)
+        process_buffered_jobs(blocking: true)
+
+        err = @shutdown_error.get
+        raise err if err
+      end
+
+      def drain_options
+        @drain_options ||= @runtime_config.polling_options.merge(request_timeout: -1)
+      end
+
+      def drain_backlog_while_also_processing_buffer # rubocop:disable Metrics/AbcSize
+        loop do
+          break if stopping?
+
+          polled_count = @client.with_each_job(job_type, **drain_options) do |job|
+            if stopping?
+              handle_shutdown_job(job)
+            else
+              @worker_class.perform_job(job)
+              # After each polled job, drain any stream jobs that arrived —
+              # always prioritize keeping up with the stream over working through backlog.
+              process_buffered_jobs(blocking: false)
+            end
+          rescue Busybee::Worker::Shutdown => e
+            @shutdown_error.update { |prev| prev || e }
+            stop!
+          end
+
+          break if polled_count < drain_options[:max_jobs] # Caught up: fewer than requested
+        rescue *BACKPRESSURE_ERRORS
+          # [hook: runner.backpressure]
+          sleep @runtime_config.backpressure_delay
+        end
+      end
+    end
+  end
+end

data/lib/busybee/runner/multi.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Busybee
+  class Runner
+    # Multi runner — manages multiple worker types in a single process.
+    # Each worker gets its own child runner (Polling/Streaming/Hybrid) running
+    # in a dedicated thread via Concurrent::FixedThreadPool.
+    #
+    # Provides the same interface as single-worker runners (run!, stop!, kill!)
+    # so the CLI can treat all runner types uniformly.
+    class Multi < Runner
+      attr_reader :runners
+
+      def initialize(worker_classes, runtime_config: nil, client: nil)
+        super(client: client)
+        runtime_config ||= RuntimeConfig.new
+        @runners = worker_classes.map do |worker_class|
+          resolved = runtime_config.resolve_for(worker_class)
+          Runner.for(worker_class, runtime_config: resolved, client: @client)
+        end
+        @thread_pool = Concurrent::FixedThreadPool.new(worker_classes.length)
+        @thread_error = Concurrent::AtomicReference.new(nil)
+
+        check_connection_pool_size(worker_classes)
+      end
+
+      def run!
+        return if stopping?
+
+        @running.make_true
+        post_runners_to_pool
+        @thread_pool.wait_for_termination
+
+        err = @thread_error.get
+        raise err if err
+      ensure
+        @running.make_false
+      end
+
+      def stop!
+        super
+        @runners.each(&:stop!)
+        @thread_pool.shutdown
+      end
+
+      def stopping?
+        @runners.all?(&:stopping?)
+      end
+
+      def kill!
+        super
+        @runners.each(&:kill!)
+        @thread_pool.kill
+      end
+
+      private
+
+      def post_runners_to_pool
+        @runners.each do |runner|
+          @thread_pool.post do
+            runner.run!
+          rescue StandardError => e
+            @thread_error.update { |prev| prev || e }
+            Busybee.logger&.error(
+              "Error in runner for #{runner_worker_name(runner)}: " \
+              "[#{e.class}] #{e.message}"
+            )
+            stop!
+          end
+        end
+      end
+
+      def runner_worker_name(runner)
+        runner.instance_variable_get(:@worker_class)&.name || "(anonymous worker)"
+      end
+
+      def check_connection_pool_size(worker_classes)
+        return unless defined?(ActiveRecord::Base)
+
+        pool_size = ActiveRecord::Base.connection_pool.size
+        worker_count = worker_classes.length
+
+        if pool_size < worker_count
+          Busybee.logger&.error(
+            "Process #{Process.pid} is running #{worker_count} workers but the database " \
+            "connection pool size is only #{pool_size}. This may cause connection timeout " \
+            "errors. Adjust the pool size (usually via RAILS_MAX_THREADS) or reduce the " \
+            "number of workers in this process."
+          )
+        else
+          Busybee.logger&.info(
+            "Process #{Process.pid} will run #{worker_count} workers with a database " \
+            "connection pool size of #{pool_size}."
+          )
+        end
+      end
+    end
+  end
+end

data/lib/busybee/runner/polling.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Busybee
+  class Runner
+    # Polling runner — fetches jobs via client.with_each_job in a loop.
+    # Each iteration long-polls the gateway for available jobs, yields them
+    # sequentially to the worker's perform_job, and handles shutdown/errors.
+    class Polling < Runner
+      BACKPRESSURE_ERRORS = [::GRPC::ResourceExhausted].freeze
+
+      def run!
+        return if stopping?
+
+        @running.make_true
+        # [hook: runner.started]
+        shutdown_error = nil
+
+        loop do
+          break if stopping?
+
+          process_all_available_jobs { |e| shutdown_error = e }
+        rescue *BACKPRESSURE_ERRORS
+          # [hook: runner.backpressure]
+          sleep @runtime_config.backpressure_delay
+        end
+
+        raise shutdown_error if shutdown_error
+      ensure
+        # [hook: runner.stopping]
+        @running.make_false
+      end
+
+      private
+
+      def process_all_available_jobs
+        @client.with_each_job(job_type, **@runtime_config.polling_options) do |job|
+          if stopping?
+            handle_shutdown_job(job)
+          else
+            @worker_class.perform_job(job)
+          end
+        rescue Busybee::Worker::Shutdown => e
+          # [hook: runner.shutdown]
+          yield e
+          stop!
+        end
+      end
+
+      def job_type
+        @worker_class.configuration.job_type
+      end
+    end
+  end
+end

data/lib/busybee/runner/streaming.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Busybee
+  class Runner
+    # Streaming runner — receives jobs via client.open_job_stream.
+    # The stream continuously pushes newly-activated jobs from the gateway.
+    # Note: streams only receive jobs created after the stream opens;
+    # pre-existing jobs require polling to retrieve.
+    #
+    # Two modes:
+    # - buffer: true (default) — A pump thread reads from the stream into a Queue;
+    #   the main thread pops and processes sequentially. Better shutdown responsiveness
+    #   and enables pump delay configuration.
+    # - buffer: false — stream.each calls perform_job inline on the main thread.
+    #   Simpler model for workers that don't need buffer features.
+    class Streaming < Runner
+      def initialize(worker_class, runtime_config: nil, client: nil)
+        super
+        return unless buffer?
+
+        @job_buffer = Queue.new
+        @shutdown_error = Concurrent::AtomicReference.new(nil)
+      end
+
+      def run!
+        return if stopping?
+
+        @running.make_true
+        # [hook: runner.started]
+
+        @stream = @client.open_job_stream(job_type, job_timeout: @runtime_config.job_timeout)
+
+        if buffer?
+          run_with_buffer
+        else
+          run_inline
+        end
+      ensure
+        # [hook: runner.stopping]
+        @stream&.close
+        if buffer?
+          @pump_thread&.join(5)
+          handle_remaining_jobs_in_buffer
+        end
+        @running.make_false
+      end
+
+      def stop!
+        super
+        @stream&.close # unblocks stream.each via GRPC::Cancelled
+        @job_buffer&.push(:stop) if buffer?
+      end
+
+      def kill!
+        super
+        @pump_thread&.kill
+        return unless buffer?
+
+        @job_buffer.clear
+        @job_buffer.push(:stop)
+      end
+
+      private
+
+      def run_with_buffer
+        @pump_thread = Thread.new { pump_stream_into_buffer }
+        process_buffered_jobs(blocking: true)
+
+        err = @shutdown_error.get
+        raise err if err
+      end
+
+      def run_inline
+        shutdown_error = nil
+
+        @stream.each do |job|
+          if stopping?
+            handle_shutdown_job(job)
+            break
+          end
+
+          @worker_class.perform_job(job)
+        rescue Busybee::Worker::Shutdown => e
+          # [hook: runner.shutdown]
+          shutdown_error = e
+          stop!
+          break
+        end
+
+        raise shutdown_error if shutdown_error
+      end
+
+      def pump_stream_into_buffer
+        delay = @runtime_config.buffer_throttle
+
+        @stream.each do |job|
+          break if stopping?
+
+          @job_buffer.push(job)
+          sleep(delay.to_f / 1000) if delay
+        end
+      rescue StandardError => e
+        # Stream error (e.g., GRPC::Error). Store and stop so main thread can re-raise.
+        # Normal close via stop! produces GRPC::Cancelled, which JobStream#each absorbs —
+        # so this only fires on genuine failures.
+        @shutdown_error.update { |prev| prev || e }
+      ensure
+        # Stream ended — either naturally (external close, server-side close),
+        # via error (handled above), or because stop! was already called.
+        # In all cases, stop! to unblock the main thread's buffer pop.
+        # Idempotent when stop! was already called.
+        stop!
+      end
+
+      # Process jobs from the buffer.
+      # blocking: false — drains all currently-buffered jobs, returns if/when empty.
+      # blocking: true  — blocks on pop until :stop sentinel or stopping?.
+      def process_buffered_jobs(blocking:)
+        loop do
+          break if stopping?
+
+          job = @job_buffer.pop(!blocking)
+          break if job == :stop
+
+          if stopping?
+            handle_shutdown_job(job)
+          else
+            @worker_class.perform_job(job)
+          end
+        rescue ThreadError
+          break # buffer empty (non-blocking only)
+        rescue Busybee::Worker::Shutdown => e
+          @shutdown_error.update { |prev| prev || e }
+          stop!
+        end
+      end
+
+      # Drain remaining buffer during shutdown, failing all jobs.
+      def handle_remaining_jobs_in_buffer
+        loop do
+          job = @job_buffer.pop(true) # non-blocking
+          next if job == :stop
+
+          handle_shutdown_job(job)
+        rescue ThreadError
+          break # buffer empty
+        end
+      end
+
+      def buffer?
+        @runtime_config.buffer
+      end
+
+      def job_type
+        @worker_class.configuration.job_type
+      end
+    end
+  end
+end

data/lib/busybee/runner.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Busybee
+  # Base class for all runner types. Provides shared interface (run!, stop!, stopping?,
+  # running?, kill!) and the Runner.for factory method for mode resolution.
+  #
+  # Subclasses must implement #run! to define their job-fetching loop.
+  class Runner
+    def initialize(worker_class = nil, runtime_config: nil, client: nil)
+      @worker_class = worker_class
+      @runtime_config = runtime_config
+      @client = client || Busybee::Client.new
+      @stop_requested = Concurrent::AtomicBoolean.new(false)
+      @running = Concurrent::AtomicBoolean.new(false)
+    end
+
+    # Blocks until stopped or error. Subclasses must implement.
+    def run!
+      raise NotImplementedError
+    end
+
+    # Signals graceful shutdown. Thread-safe (called from signal handler).
+    def stop!
+      @stop_requested.make_true
+    end
+
+    # True if stop! has been called.
+    def stopping?
+      @stop_requested.true?
+    end
+
+    # True if run! is actively executing.
+    def running?
+      @running.true?
+    end
+
+    # Force shutdown. Base: calls stop!. Multi overrides to also kill thread pool.
+    def kill!
+      stop!
+    end
+
+    class << self
+      # Factory method. Resolves worker mode via RuntimeConfig and returns
+      # the appropriate runner instance.
+      #
+      # Mode resolution (lowest to highest priority):
+      #   1. Gem default: Busybee.default_worker_mode
+      #   2. Worker DSL: worker_class.configuration.worker_mode
+      #   3. RuntimeConfig override (global or per-worker)
+      def for(*worker_classes, runtime_config: nil, client: nil)
+        runtime_config ||= RuntimeConfig.new
+        client ||= Busybee::Client.new
+
+        if worker_classes.length > 1
+          Multi.new(worker_classes, runtime_config: runtime_config, client: client)
+        else
+          resolved = runtime_config.resolve_for(worker_classes.first)
+          runner_class_for(resolved).new(worker_classes.first, runtime_config: resolved, client: client)
+        end
+      end
+
+      private
+
+      def runner_class_for(resolved_config)
+        case resolved_config.worker_mode
+        when :polling then Polling
+        when :streaming then Streaming
+        when :hybrid then Hybrid
+        else
+          raise ArgumentError,
+                "Invalid worker mode: #{resolved_config.worker_mode.inspect}. Valid: :polling, :streaming, :hybrid"
+        end
+      end
+    end
+
+    private
+
+    # Fails a job during graceful shutdown, preserving its retry count.
+    # Uses the worker's configured backoff (or gem default).
+    def handle_shutdown_job(job)
+      job.fail!(
+        "Worker shutting down",
+        retries: job.retries,
+        backoff: @runtime_config.backoff
+      )
+    rescue StandardError => e
+      Busybee.logger&.warn("Failed to fail job #{job.key} during shutdown: #{e.message}")
+    end
+  end
+end
+
+require "busybee/runner/polling"
+require "busybee/runner/streaming"
+require "busybee/runner/hybrid"
+require "busybee/runner/multi"