busybee 0.1.0 → 0.3.0

data/exe/busybee

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "busybee"
+
+Busybee::CLI.main(ARGV)

data/lib/busybee/cli.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Busybee
+  class CLI
+    attr_reader :runtime_config, :worker_class_names, :worker_classes
+
+    def self.main(args)
+      new(args).run
+    end
+
+    def initialize(args)
+      @worker_class_names = []
+      @parsed_options = {}
+      parse_options!(args.dup)
+      load_environment!
+      extract_workers_from_yaml! if @parsed_options[:config_file]
+      load_workers!
+      build_config!
+      apply_global_config!
+    end
+
+    def run
+      @runner = Runner.for(*@worker_classes, runtime_config: @runtime_config, client: client)
+      setup_signal_handlers!
+      @runner.run!
+    end
+
+    private
+
+    def client
+      @client ||= Busybee::Client.new
+    end
+
+    def handle_signal(_signal)
+      if @runner.stopping?
+        @runner.kill!
+        exit!(1)
+      else
+        @runner.stop!
+      end
+    end
+
+    def setup_signal_handlers!
+      %w[INT QUIT TERM].each do |signal|
+        trap(signal) do
+          Thread.new { handle_signal(signal) }.join
+        end
+      end
+    end
+
+    def load_environment!
+      return if ENV["BUSYBEE_SKIP_RAILS"]
+
+      begin
+        require "rails"
+      rescue LoadError
+        return
+      end
+
+      require "./config/environment"
+    rescue StandardError, LoadError => e
+      Busybee.logger&.error("Failed to load Rails environment: [#{e.class}] #{e.message}. " \
+                            "Set BUSYBEE_SKIP_RAILS=1 to skip Rails loading.")
+    end
+
+    def extract_workers_from_yaml!
+      @yaml_kwargs = RuntimeConfig.parse_yaml(@parsed_options[:config_file])
+      @worker_class_names = (@yaml_kwargs[:workers] || {}).keys
+    end
+
+    def build_config!
+      if @yaml_kwargs
+        kwargs = @yaml_kwargs.dup
+        # Merge CLI process-wide flags into YAML-sourced kwargs
+        %i[log_format worker_name cluster_address].each do |field|
+          kwargs[field] = @parsed_options[field] if @parsed_options[field]
+        end
+        @runtime_config = RuntimeConfig.new(**kwargs)
+      else
+        @runtime_config = RuntimeConfig.new(**@parsed_options)
+      end
+    end
+
+    def load_workers!
+      raise Busybee::NoWorkersSpecified, "No worker classes specified" if @worker_class_names.empty?
+
+      @worker_classes = @worker_class_names.map do |name|
+        Kernel.const_get(name)
+      rescue NameError => e
+        raise Busybee::WorkerNotFound, "Could not load worker class '#{name}': #{e.message}"
+      end
+    end
+
+    def parse_options!(args)
+      option_parser.parse!(args)
+      @worker_class_names = args
+      validate_config_exclusions!
+    end
+
+    def validate_config_exclusions!
+      return unless @parsed_options[:config_file]
+
+      if @parsed_options[:worker_mode]
+        raise ArgumentError, "--config and --worker-mode are mutually exclusive. " \
+                             "Set worker_mode in the YAML config file instead."
+      end
+
+      return if @worker_class_names.empty?
+
+      raise ArgumentError, "--config and positional worker args are mutually exclusive. " \
+                           "List workers in the YAML config file instead."
+    end
+
+    def option_parser # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+      OptionParser.new do |opts|
+        opts.banner = "Usage: busybee [options] WorkerClass [WorkerClass ...]"
+
+        opts.on("-v", "--version", "Print version and exit") do
+          puts Busybee::VERSION
+          exit
+        end
+
+        opts.on("-h", "--help", "Print this help message and exit") do
+          puts opts
+          exit
+        end
+
+        opts.on("-c", "--config FILE", "YAML configuration file") do |file|
+          @parsed_options[:config_file] = file
+        end
+
+        opts.on("-m", "--worker-mode MODE", "Worker mode (polling, streaming, hybrid)") do |mode|
+          @parsed_options[:worker_mode] = mode.to_sym
+        end
+
+        opts.on("-l", "--log-format FORMAT", "Log format (text, json)") do |format|
+          @parsed_options[:log_format] = format.to_sym
+        end
+
+        opts.on("-n", "--worker-name NAME", "Worker name for identification") do |name|
+          @parsed_options[:worker_name] = name
+        end
+
+        opts.on("-a", "--cluster-address ADDR", "Cluster address (host:port)") do |addr|
+          @parsed_options[:cluster_address] = addr
+        end
+      end
+    end
+
+    # Applies process-wide flags to gem-level config before runners start.
+    # Only sets values that were explicitly provided via CLI flags.
+    # Logs when overriding a value already set (e.g., by the Railtie).
+    def apply_global_config!
+      apply_global_setting!(:log_format)
+      apply_global_setting!(:worker_name)
+      apply_global_setting!(:cluster_address)
+    end
+
+    def apply_global_setting!(field)
+      cli_value = @runtime_config.public_send(field)
+      return unless cli_value
+
+      existing = Busybee.instance_variable_get(:"@#{field}")
+      if existing
+        flag = "--#{field.to_s.tr('_', '-')}"
+        Busybee.logger&.info("#{flag} overriding configured value: #{existing.inspect} → #{cli_value.inspect}")
+      end
+      Busybee.public_send(:"#{field}=", cli_value)
+    end
+  end
+end

data/lib/busybee/client/error_handling.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "busybee"
+require "busybee/grpc/error"
+require "busybee/logging"
+
+module Busybee
+  class Client
+    # Provides GRPC error wrapping and optional retry logic.
+    module ErrorHandling
+      # Execute a block with optional GRPC retry and error wrapping.
+      # @yield Block that makes GRPC call
+      # @return Result of the block
+      # @raise [Busybee::GRPC::Error] Wrapped GRPC error
+      def with_retry
+        attempts = 0
+        max_attempts = Busybee.grpc_retry_enabled ? 2 : 1
+
+        begin
+          attempts += 1
+          yield
+        rescue *Busybee.grpc_retry_errors => e
+          if attempts < max_attempts
+            Busybee::Logging.warn("GRPC call failed, retrying in #{Busybee.grpc_retry_delay_ms}ms",
+                                  error_class: e.class.name)
+            sleep(Busybee.grpc_retry_delay_ms / 1000.0)
+            retry
+          end
+          message = attempts > 1 ? "GRPC call failed after retry" : "GRPC call failed"
+          raise Busybee::GRPC::Error, message
+        rescue ::GRPC::BadStatus => e
+          raise Busybee::GRPC::Error, "GRPC call failed"
+        end
+      end
+    end
+  end
+end

data/lib/busybee/client/job_operations.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/duration"
+require "busybee/grpc"
+require "busybee/serialization"
+
+module Busybee
+  class Client
+    # Job completion, failure, and error throwing operations.
+    module JobOperations
+      # Complete a job with optional output variables.
+      #
+      # @param job_key [Integer] The unique job identifier
+      # @param vars [Hash] Variables to return to the workflow engine
+      # @return [Object] Response from the gateway (truthy)
+      # @raise [Busybee::GRPC::Error] if completion fails
+      #
+      # @example Complete a job without variables
+      #   client.complete_job(123456)
+      #
+      # @example Complete a job with variables
+      #   client.complete_job(123456, vars: { result: "success", orderId: 999 })
+      #
+      def complete_job(job_key, vars: {})
+        request = Busybee::GRPC::CompleteJobRequest.new(
+          jobKey: job_key.to_i,
+          variables: Busybee::Serialization.to_json(vars)
+        )
+
+        with_retry do
+          stub.complete_job(request)
+        end
+      end
+
+      # Fail a job with an error message.
+      #
+      # @param job_key [Integer] The unique job identifier
+      # @param error_message [String] Error message describing the failure
+      # @param retries [Integer, nil] Override the number of remaining retries
+      # @param backoff [Integer, ActiveSupport::Duration, nil] Delay before retry in milliseconds
+      # @return [Object] Response from the gateway (truthy)
+      # @raise [Busybee::GRPC::Error] if failure operation fails
+      #
+      # @example Fail a job with default backoff
+      #   client.fail_job(123456, "Payment gateway timeout")
+      #
+      # @example Fail with custom retry count
+      #   client.fail_job(123456, "Transient error", retries: 3)
+      #
+      # @example Fail with custom backoff duration
+      #   client.fail_job(123456, "Rate limited", backoff: 30.seconds)
+      #
+      def fail_job(job_key, error_message, retries: nil, backoff: nil)
+        backoff_ms = backoff || Busybee.default_fail_job_backoff
+        backoff_ms = backoff_ms.is_a?(ActiveSupport::Duration) ? backoff_ms.in_milliseconds.to_i : backoff_ms.to_i
+
+        request = Busybee::GRPC::FailJobRequest.new(
+          jobKey: job_key.to_i,
+          errorMessage: error_message.to_s,
+          retryBackOff: backoff_ms
+        )
+
+        request.retries = retries.to_i if retries
+
+        with_retry do
+          stub.fail_job(request)
+        end
+      end
+
+      # Throw a BPMN error to be caught by an error boundary event.
+      #
+      # @param job_key [Integer] The unique job identifier
+      # @param error_code [String] BPMN error code (typically UPPERCASE_SNAKE_CASE)
+      # @param message [String] Optional error message for context
+      # @return [Object] Response from the gateway (truthy)
+      # @raise [Busybee::GRPC::Error] if throw operation fails
+      #
+      # @example Throw a BPMN error
+      #   client.throw_bpmn_error(123456, "ORDER_NOT_FOUND", message: "Order 550e8400 not found")
+      #
+      # @example Throw a BPMN error without message
+      #   client.throw_bpmn_error(123456, "PAYMENT_FAILED")
+      #
+      def throw_bpmn_error(job_key, error_code, message: "")
+        request = Busybee::GRPC::ThrowErrorRequest.new(
+          jobKey: job_key.to_i,
+          errorCode: error_code.to_s,
+          errorMessage: message.to_s
+        )
+
+        with_retry do
+          stub.throw_error(request)
+        end
+      end
+
+      # Update the retry count for a job.
+      #
+      # @param job_key [Integer] The unique job identifier
+      # @param retries [Integer] The new number of retries
+      # @return [Object] Response from the gateway (truthy)
+      # @raise [Busybee::GRPC::Error] if update operation fails
+      #
+      # @example Update job retries
+      #   client.update_job_retries(123456, 5)
+      #
+      def update_job_retries(job_key, retries)
+        request = Busybee::GRPC::UpdateJobRetriesRequest.new(
+          jobKey: job_key.to_i,
+          retries: retries.to_i
+        )
+
+        with_retry do
+          stub.update_job_retries(request)
+        end
+      end
+
+      # Update the timeout for a job.
+      #
+      # @param job_key [Integer] The unique job identifier
+      # @param timeout [Integer, ActiveSupport::Duration] New timeout in milliseconds
+      # @return [Object] Response from the gateway (truthy)
+      # @raise [Busybee::GRPC::Error] if update operation fails
+      #
+      # @example Update job timeout with milliseconds
+      #   client.update_job_timeout(123456, 30_000)
+      #
+      # @example Update job timeout with Duration
+      #   client.update_job_timeout(123456, 30.seconds)
+      #
+      def update_job_timeout(job_key, timeout)
+        timeout_ms = timeout.is_a?(ActiveSupport::Duration) ? timeout.in_milliseconds.to_i : timeout.to_i
+
+        request = Busybee::GRPC::UpdateJobTimeoutRequest.new(
+          jobKey: job_key.to_i,
+          timeout: timeout_ms
+        )
+
+        with_retry do
+          stub.update_job_timeout(request)
+        end
+      end
+
+      # Activate and process jobs with a block (bounded, non-streaming).
+      #
+      # @param job_type [String] The job type to activate
+      # @param max_jobs [Integer] Maximum number of jobs to activate
+      # @param job_timeout [Integer, ActiveSupport::Duration, nil] Job lock timeout in milliseconds
+      #   (defaults to Busybee.default_job_lock_timeout)
+      # @param request_timeout [Integer, ActiveSupport::Duration, nil] Request timeout in milliseconds
+      #   (defaults to Busybee.default_job_request_timeout)
+      # @yield [job] Yields each activated job to the block
+      # @yieldparam job [Busybee::Job] The activated job
+      # @return [Integer] Count of jobs processed
+      # @raise [ArgumentError] if no block given
+      # @raise [Busybee::GRPC::Error] if activation fails
+      #
+      # @example Process jobs
+      #   client.with_each_job("send-email") do |job|
+      #     send_email(job.variables.email, job.variables.subject)
+      #     job.complete!
+      #   end
+      #
+      def with_each_job(job_type, max_jobs: Busybee::Defaults::DEFAULT_MAX_JOBS, # rubocop:disable Metrics/AbcSize
+                        job_timeout: nil,
+                        request_timeout: nil)
+        raise ArgumentError, "block required" unless block_given?
+
+        job_timeout ||= Busybee.default_job_lock_timeout
+        request_timeout ||= Busybee.default_job_request_timeout
+
+        request = Busybee::GRPC::ActivateJobsRequest.new(
+          type: job_type.to_s,
+          worker: Busybee.worker_name,
+          maxJobsToActivate: max_jobs.to_i,
+          timeout: milliseconds_from(job_timeout),
+          requestTimeout: milliseconds_from(request_timeout)
+        )
+
+        count = 0
+        responses = with_retry { stub.activate_jobs(request) }
+
+        responses.each do |response|
+          response.jobs.each do |raw_job|
+            job = Busybee::Job.new(raw_job, client: self)
+            yield job
+            count += 1
+          end
+        end
+
+        count
+      end
+
+      # Open a long-lived stream for job activation.
+      #
+      # Unlike {#with_each_job}, this method returns a {Busybee::JobStream} that
+      # continuously receives jobs as they become available. The stream remains
+      # open until explicitly closed via {Busybee::JobStream#close}.
+      #
+      # @note The stream blocks while iterating. Call {Busybee::JobStream#close}
+      #   from another thread or use a signal handler to terminate the stream.
+      #
+      # @param job_type [String] The job type to activate
+      # @param job_timeout [Integer, ActiveSupport::Duration, nil] Job lock timeout in milliseconds
+      #   (defaults to Busybee.default_job_lock_timeout)
+      # @return [Busybee::JobStream] Stream of activated jobs
+      # @raise [Busybee::GRPC::Error] if stream creation fails
+      #
+      # @example Process jobs with graceful shutdown
+      #   stream = client.open_job_stream("send-email", job_timeout: 60.seconds)
+      #   trap("INT") { stream.close }
+      #
+      #   stream.each do |job|
+      #     send_email(job.variables)
+      #     job.complete!
+      #   end
+      #
+      def open_job_stream(job_type, job_timeout: nil)
+        job_timeout ||= Busybee.default_job_lock_timeout
+
+        request = Busybee::GRPC::StreamActivatedJobsRequest.new(
+          type: job_type.to_s,
+          worker: Busybee.worker_name,
+          timeout: milliseconds_from(job_timeout)
+        )
+
+        with_retry do
+          Busybee::JobStream.new(
+            stub.stream_activated_jobs(request, return_op: true),
+            client: self
+          )
+        end
+      end
+    end
+  end
+end

data/lib/busybee/client/message_operations.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/duration"
+require "busybee/grpc"
+require "busybee/serialization"
+
+module Busybee
+  class Client
+    # Message and signal operations for process communication.
+    module MessageOperations
+      # Publish a message to trigger message catch events in process instances.
+      #
+      # @param name [String] The message name
+      # @param correlation_key [String] Correlation key to match against process instances
+      # @param ttl [Integer, ActiveSupport::Duration, nil] Time-to-live in milliseconds or Duration object
+      #   (defaults to Busybee.default_message_ttl)
+      # @param vars [Hash] Variables to pass with the message
+      # @param tenant_id [String, nil] Tenant ID for multi-tenancy
+      # @return [Integer] The message key
+      # @raise [ArgumentError] if vars is not a Hash
+      # @raise [Busybee::GRPC::Error] if publishing fails
+      #
+      # @example Publish a message with default TTL
+      #   key = client.publish_message("order-ready", correlation_key: "order-123")
+      #   # => 12345
+      #
+      # @example With explicit TTL and variables
+      #   client.publish_message("order-ready",
+      #     correlation_key: "order-123",
+      #     ttl: 30.seconds,
+      #     vars: { orderId: 123 })
+      #
+      def publish_message(name, correlation_key:, vars: {}, ttl: nil, tenant_id: nil)
+        raise ArgumentError, "vars must be a Hash" unless vars.is_a?(Hash)
+
+        ttl ||= Busybee.default_message_ttl
+        ttl_ms = ttl.is_a?(ActiveSupport::Duration) ? ttl.in_milliseconds.to_i : ttl.to_i
+
+        request = Busybee::GRPC::PublishMessageRequest.new(
+          name: name.to_s,
+          correlationKey: correlation_key.to_s,
+          variables: Busybee::Serialization.to_json(vars),
+          timeToLive: ttl_ms,
+          tenantId: tenant_id&.to_s
+        )
+
+        with_retry do
+          stub.publish_message(request).key
+        end
+      end
+
+      # Broadcast a signal to all process instances with matching signal catch events.
+      #
+      # @param signal_name [String] The signal name
+      # @param vars [Hash] Variables to pass with the signal
+      # @param tenant_id [String, nil] Tenant ID for multi-tenancy
+      # @return [Integer] The signal key
+      # @raise [ArgumentError] if vars is not a Hash
+      # @raise [Busybee::GRPC::Error] if broadcasting fails
+      #
+      # @example Broadcast a signal
+      #   key = client.broadcast_signal("cancel-all-orders")
+      #   # => 54321
+      #
+      # @example With variables
+      #   client.broadcast_signal("cancel-all-orders", vars: { reason: "system-maintenance" })
+      #
+      def broadcast_signal(signal_name, vars: {}, tenant_id: nil)
+        raise ArgumentError, "vars must be a Hash" unless vars.is_a?(Hash)
+
+        request = Busybee::GRPC::BroadcastSignalRequest.new(
+          signalName: signal_name.to_s,
+          variables: Busybee::Serialization.to_json(vars),
+          tenantId: tenant_id&.to_s
+        )
+
+        with_retry do
+          stub.broadcast_signal(request).key
+        end
+      end
+    end
+  end
+end

data/lib/busybee/client/process_operations.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "busybee/grpc"
+require "busybee/serialization"
+
+module Busybee
+  class Client
+    # Process deployment, instance creation, and cancellation operations.
+    module ProcessOperations
+      # Deploy one or more BPMN files.
+      #
+      # @param paths [Array<String>] Paths to BPMN files
+      # @param tenant_id [String, nil] Tenant ID for multi-tenancy
+      # @return [Hash{String => Integer}] Map of bpmn_process_id => process_definition_key
+      # @raise [Busybee::GRPC::Error] if deployment fails
+      #
+      # @example Deploy a single file
+      #   client.deploy_process("workflows/order.bpmn")
+      #   # => { "order-fulfillment" => 2251799813685249 }
+      #
+      # @example Deploy multiple files
+      #   client.deploy_process("order.bpmn", "payment.bpmn")
+      #   # => { "order-fulfillment" => 123, "payment-process" => 456 }
+      #
+      def deploy_process(*paths, tenant_id: nil) # rubocop:disable Metrics/AbcSize
+        resources = paths.map do |path|
+          Busybee::GRPC::Resource.new(
+            name: File.basename(path),
+            content: File.read(path)
+          )
+        end
+
+        request = Busybee::GRPC::DeployResourceRequest.new(
+          resources: resources,
+          tenantId: tenant_id&.to_s
+        )
+
+        with_retry do
+          response = stub.deploy_resource(request)
+          response.deployments.each_with_object({}) do |deployment, result|
+            result[deployment.process.bpmnProcessId] = deployment.process.processDefinitionKey
+          end
+        end
+      end
+
+      # Start a process instance.
+      #
+      # @param bpmn_process_id [String] The BPMN process ID to start
+      # @param vars [Hash] Variables to pass to the process instance
+      # @param version [Integer, Symbol, nil] Process version (:latest, nil, or specific version number)
+      # @param tenant_id [String, nil] Tenant ID for multi-tenancy
+      # @return [Integer] The process_instance_key
+      # @raise [ArgumentError] if vars is not a Hash
+      # @raise [Busybee::GRPC::Error] if starting the process fails
+      #
+      # @example Start a process instance with variables
+      #   key = client.start_instance("order-fulfillment", vars: { orderId: 123 })
+      #   # => 67890
+      #
+      def start_instance(bpmn_process_id, vars: {}, version: :latest, tenant_id: nil)
+        raise ArgumentError, "vars must be a Hash" unless vars.is_a?(Hash)
+
+        request = Busybee::GRPC::CreateProcessInstanceRequest.new(
+          bpmnProcessId: bpmn_process_id.to_s,
+          variables: Busybee::Serialization.to_json(vars),
+          version: version == :latest || version.nil? ? -1 : version.to_i,
+          tenantId: tenant_id&.to_s
+        )
+
+        with_retry do
+          stub.create_process_instance(request).processInstanceKey
+        end
+      end
+      alias start_process_instance start_instance
+
+      # Cancel a running process instance.
+      #
+      # @param process_instance_key [Integer, String] The process instance key to cancel
+      # @param ignore_missing [Boolean] If true, return false instead of raising when instance not found
+      # @return [Boolean] true if cancelled, false if not found and ignore_missing is true
+      # @raise [Busybee::GRPC::Error] if cancellation fails (unless ignore_missing for NotFound)
+      #
+      # @example Cancel an instance
+      #   client.cancel_instance(67890)
+      #   # => true
+      #
+      # @example Safely cancel without error if missing
+      #   client.cancel_instance(99999, ignore_missing: true)
+      #   # => false
+      #
+      def cancel_instance(process_instance_key, ignore_missing: false)
+        request = Busybee::GRPC::CancelProcessInstanceRequest.new(
+          processInstanceKey: process_instance_key.to_i
+        )
+
+        with_retry do
+          stub.cancel_process_instance(request)
+          true
+        end
+      rescue Busybee::GRPC::Error => e
+        raise unless ignore_missing && e.grpc_status == :not_found
+
+        false
+      end
+      alias cancel_process_instance cancel_instance
+    end
+  end
+end