busybee 0.1.0 → 0.3.0

data/lib/busybee/credentials/tls.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "grpc"
+
+require "busybee/credentials"
+
+module Busybee
+  class Credentials
+    # TLS credentials with server certificate verification.
+    # No client authentication (mTLS not supported in v0.2).
+    #
+    # @example With system default certificates
+    #   credentials = Busybee::Credentials::TLS.new(cluster_address: "zeebe.example.com:443")
+    #   stub = credentials.grpc_stub
+    #
+    # @example With custom CA certificate
+    #   credentials = Busybee::Credentials::TLS.new(
+    #     cluster_address: "zeebe.example.com:443",
+    #     certificate_file: "/path/to/ca-cert.pem"
+    #   )
+    #   stub = credentials.grpc_stub
+    #
+    class TLS < Credentials
+      attr_reader :certificate_file
+
+      # @param cluster_address [String, nil] Zeebe cluster address (host:port)
+      # @param certificate_file [String, nil] Path to CA certificate file.
+      #   If nil, uses system default certificates.
+      def initialize(cluster_address: nil, certificate_file: nil)
+        super(cluster_address: cluster_address)
+        @certificate_file = certificate_file
+      end
+
+      def grpc_channel_credentials
+        if certificate_file
+          ::GRPC::Core::ChannelCredentials.new(File.read(certificate_file))
+        else
+          ::GRPC::Core::ChannelCredentials.new
+        end
+      end
+    end
+  end
+end

data/lib/busybee/credentials.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "busybee"
+
+module Busybee
+  # Base class for credentials. Defines interface for all credential types.
+  #
+  # Credentials objects are responsible for:
+  # - Knowing which cluster address to connect to
+  # - Providing gRPC channel credentials for authentication
+  # - Creating and memoizing gRPC stub instances
+  #
+  # Subclasses must implement #grpc_channel_credentials.
+  #
+  # @example Direct stub access
+  #   credentials = Busybee::Credentials::Insecure.new
+  #   stub = credentials.grpc_stub
+  #   response = stub.topology(Busybee::GRPC::TopologyRequest.new)
+  #
+  class Credentials
+    attr_reader :cluster_address
+
+    class << self
+      # Factory method to build appropriate credentials based on configuration.
+      #
+      # First checks Busybee.credential_type for explicit type selection.
+      # If not set, autodetects credential type based on which keys are present in params.
+      # If no keys are given in params, attempts to load them from environment vars.
+      #
+      # @param cluster_address [String, nil] Override cluster address
+      # @param params [Hash] Configuration parameters (keys inform credential type selection)
+      # @option params [Boolean] :insecure Use insecure connection (no TLS, no auth)
+      # @return [Credentials] Appropriate credentials instance
+      #
+      # @example Insecure for local development
+      #   Credentials.build(insecure: true)
+      #
+      # @example With explicit type configuration
+      #   Busybee.credential_type = :insecure
+      #   Credentials.build  # Uses configured type
+      #
+      def build(cluster_address: nil, **params)
+        if params.empty?
+          params = extract_possible_credential_params_from_env
+          extracted_address = params.delete(:cluster_address) # always delete to avoid duplicate keyword arg
+          cluster_address ||= extracted_address # allow explicit kwarg to override env
+        end
+
+        case Busybee.credential_type
+        when :insecure
+          build_insecure(cluster_address: cluster_address, **params)
+        when :tls
+          build_tls(cluster_address: cluster_address, **params)
+        when :oauth
+          build_oauth(cluster_address: cluster_address, **params)
+        when :camunda_cloud
+          build_camunda_cloud(cluster_address: cluster_address, **params)
+        else
+          autodetect_credentials(cluster_address: cluster_address, **params)
+        end
+      end
+
+      private
+
+      # Autodetects credential type based on provided parameters.
+      # As new credential types are added, extend this method with detection logic.
+      #
+      # @raise [Busybee::CannotDetectCredentials] if params are present but don't match
+      #   any known credential type pattern
+      def autodetect_credentials(cluster_address: nil, **params)
+        if tls_keys?(params)
+          build_tls(cluster_address: cluster_address, **params)
+        elsif oauth_keys?(params)
+          build_oauth(cluster_address: cluster_address, **params)
+        elsif camunda_cloud_keys?(params)
+          build_camunda_cloud(cluster_address: cluster_address, **params)
+        elsif insecure_fallback_allowed?(params)
+          build_insecure(cluster_address: cluster_address, **params)
+        else
+          raise Busybee::CannotDetectCredentials,
+                "Cannot detect credential type from provided params: #{params.keys.join(', ')}. " \
+                "Set Busybee.credential_type explicitly or provide complete params for a credential type."
+        end
+      end
+
+      # Insecure fallback is only allowed when no credential params were provided,
+      # or when `insecure: true` is the only param.
+      def insecure_fallback_allowed?(params)
+        params.empty? || params == { insecure: true }
+      end
+
+      def id_and_secret?(params)
+        params[:client_id] && params[:client_secret]
+      end
+
+      def tls_keys?(params)
+        !id_and_secret?(params) && (params[:certificate_file] || params[:tls])
+      end
+
+      def oauth_keys?(params)
+        id_and_secret?(params) && params[:token_url] && params[:audience]
+      end
+
+      def camunda_cloud_keys?(params)
+        id_and_secret?(params) && params[:cluster_id] && params[:region]
+      end
+
+      def build_insecure(cluster_address: nil, **_)
+        require "busybee/credentials/insecure"
+        Insecure.new(cluster_address: cluster_address)
+      end
+
+      def build_tls(cluster_address: nil, certificate_file: nil, **_)
+        require "busybee/credentials/tls"
+        TLS.new(cluster_address: cluster_address, certificate_file: certificate_file)
+      end
+
+      def build_oauth( # rubocop:disable Metrics/ParameterLists
+        cluster_address: nil,
+        token_url: nil,
+        client_id: nil,
+        client_secret: nil,
+        audience: nil,
+        scope: nil,
+        certificate_file: nil,
+        **_
+      )
+        require "busybee/credentials/oauth"
+        OAuth.new(
+          cluster_address: cluster_address,
+          token_url: token_url,
+          client_id: client_id,
+          client_secret: client_secret,
+          audience: audience,
+          scope: scope,
+          certificate_file: certificate_file
+        )
+      end
+
+      # NOTE: cluster_address is intentionally omitted - CamundaCloud constructs it from cluster_id and region
+      def build_camunda_cloud(client_id: nil, client_secret: nil, cluster_id: nil, region: nil, scope: nil, **_) # rubocop:disable Metrics/ParameterLists
+        require "busybee/credentials/camunda_cloud"
+        CamundaCloud.new(
+          client_id: client_id,
+          client_secret: client_secret,
+          cluster_id: cluster_id,
+          region: region,
+          scope: scope
+        )
+      end
+
+      # Attempt to extract credentials from environment variables, if present.
+      def extract_possible_credential_params_from_env
+        {
+          cluster_address: ENV.fetch("CLUSTER_ADDRESS", nil),
+          # Camunda Cloud params
+          client_id: ENV.fetch("CAMUNDA_CLIENT_ID", nil),
+          client_secret: ENV.fetch("CAMUNDA_CLIENT_SECRET", nil),
+          cluster_id: ENV.fetch("CAMUNDA_CLUSTER_ID", nil),
+          region: ENV.fetch("CAMUNDA_CLUSTER_REGION", nil),
+          # OAuth params
+          token_url: ENV.fetch("ZEEBE_TOKEN_URL", nil),
+          audience: ENV.fetch("ZEEBE_AUDIENCE", nil),
+          scope: ENV.fetch("ZEEBE_SCOPE", nil),
+          # TLS params
+          certificate_file: ENV.fetch("ZEEBE_CERTIFICATE_FILE", nil)
+        }.compact
+      end
+    end
+
+    # @param cluster_address [String, nil] Zeebe cluster address (host:port)
+    #   If nil, falls back to Busybee.cluster_address
+    def initialize(cluster_address: nil)
+      @cluster_address = cluster_address || Busybee.cluster_address
+    end
+
+    # Returns a ready-to-use gRPC stub for the Zeebe Gateway API.
+    # The stub is memoized internally - callers should not cache it themselves.
+    # For credentials that handle token refresh (like OAuth), this ensures
+    # the stub can be replaced transparently when tokens are refreshed.
+    #
+    # @return [Busybee::GRPC::Gateway::Stub]
+    def grpc_stub
+      @grpc_stub ||= begin
+        require "busybee/grpc"
+        Busybee::GRPC::Gateway::Stub.new(cluster_address, grpc_channel_credentials)
+      end
+    end
+
+    # Returns gRPC channel credentials for authentication.
+    # Subclasses must implement this method.
+    #
+    # @return [Symbol, GRPC::Core::ChannelCredentials]
+    #   - :this_channel_is_insecure for insecure connections
+    #   - GRPC::Core::ChannelCredentials for TLS/OAuth
+    def grpc_channel_credentials
+      raise NotImplementedError, "#{self.class} must implement #grpc_channel_credentials"
+    end
+  end
+end

data/lib/busybee/defaults.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Busybee
+  # Default values for client and worker operations.
+  # Can be overridden per-call or via gem configuration.
+  module Defaults
+    DEFAULT_FAIL_JOB_BACKOFF_MS = 5_000
+    DEFAULT_GRPC_RETRY_DELAY_MS = 500
+    DEFAULT_JOB_REQUEST_TIMEOUT_MS = 60_000
+    DEFAULT_JOB_LOCK_TIMEOUT_MS = 60_000
+    DEFAULT_INPUT_REQUIRED = true
+    DEFAULT_MAX_JOBS = 25
+    DEFAULT_MESSAGE_TTL_MS = 10_000
+    DEFAULT_OUTPUT_REQUIRED = true
+    DEFAULT_BUFFER_THROTTLE_MS = false
+    DEFAULT_BACKPRESSURE_DELAY_MS = 2_000
+    DEFAULT_WORKER_MODE = :hybrid
+    DEFAULT_STREAMING_BUFFER = true
+  end
+end

data/lib/busybee/error.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Busybee
+  # Base class for all gem operation errors.
+  # Never raised directly; exists for `rescue Busybee::Error`.
+  Error = Class.new(StandardError)
+
+  # There are two error classes not contained here which serve special purposes:
+  # - Busybee::GRPC::Error is used by the GRPC layer to wrap GRPC::BadStatus errors
+  # - Busybee::Worker::Shutdown is used to signal the need to shut down a running process
+  # Both of these inherit from Busybee::Error. See their class files for details.
+
+  # Errors below this point are specific and semantic -- they are used in just one or two
+  # places, and their name tells you exactly what went wrong:
+
+  # Raised when Credentials.build cannot determine credential type from provided params.
+  # This happens when params are provided but don't match any known credential type pattern,
+  # and no explicit credential_type is configured.
+  CannotDetectCredentials = Class.new(Error)
+
+  # Raised when job variables or headers JSON cannot be parsed
+  InvalidJobJson = Class.new(Error)
+
+  # Raised when OAuth2 token endpoint returns invalid JSON
+  InvalidOAuthResponse = Class.new(Error)
+
+  # Raised when a Worker DSL declaration is invalid (conflicting options, bad values, etc.)
+  InvalidWorkerDefinition = Class.new(Error)
+
+  # Raised when required inputs are missing from job variables/headers
+  MissingInput = Class.new(Error)
+
+  # Raised when required outputs are missing from perform's return value
+  MissingOutput = Class.new(Error)
+
+  # Raised when the CLI is invoked with no worker class arguments
+  NoWorkersSpecified = Class.new(Error)
+
+  # Raised when attempting to complete, fail, or throw error on a job that has already been handled
+  JobAlreadyHandled = Class.new(Error)
+
+  # Raised when OAuth2 token refresh fails (HTTP error from token endpoint)
+  OAuthTokenRefreshFailed = Class.new(Error)
+
+  # Raised when attempting to iterate a stream that has been closed
+  StreamAlreadyClosed = Class.new(Error)
+
+  # Raised when a worker class name cannot be resolved to a constant
+  WorkerNotFound = Class.new(Error)
+end

data/lib/busybee/grpc/error.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "busybee/error"
+
+module Busybee
+  module GRPC
+    # Wraps GRPC::BadStatus errors with Ruby-friendly interface.
+    # Preserves original error via automatic exception chaining.
+    #
+    # @example
+    #   begin
+    #     stub.some_call(request)
+    #   rescue ::GRPC::BadStatus
+    #     raise Busybee::GRPC::Error.new("Operation failed")
+    #   end
+    #
+    class Error < Busybee::Error
+      def initialize(message = "GRPC request failed")
+        super
+      end
+
+      # Returns the error message, automatically incorporating GRPC error details.
+      # If the cause is a GRPC::BadStatus, appends "(grpc_details)" to the message.
+      def message
+        base = super
+
+        if cause.is_a?(::GRPC::BadStatus)
+          "#{base} (#{cause.details})"
+        else
+          base
+        end
+      end
+
+      # Returns the GRPC status code as an integer (e.g., 14 for Unavailable).
+      # Returns nil if the cause is not a GRPC::BadStatus error.
+      def grpc_code
+        return nil unless cause.is_a?(::GRPC::BadStatus)
+
+        cause.code
+      end
+
+      # Returns the GRPC status as a symbol (e.g., :unavailable).
+      # Returns nil if the cause is not a GRPC::BadStatus error.
+      def grpc_status
+        return nil unless cause.is_a?(::GRPC::BadStatus)
+
+        # GRPC::Unavailable -> :unavailable
+        cause.class.name.split("::").last.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+      end
+
+      # Returns the GRPC error details string.
+      # Returns nil if the cause is not a GRPC::BadStatus error.
+      def grpc_details
+        return nil unless cause.is_a?(::GRPC::BadStatus)
+
+        cause.details
+      end
+    end
+  end
+end

data/lib/busybee/grpc.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 
-require_relative "grpc/gateway_pb"
-require_relative "grpc/gateway_services_pb"
+require "busybee/grpc/gateway_pb"
+require "busybee/grpc/gateway_services_pb"

data/lib/busybee/job.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "busybee/serialization"
+
+module Busybee
+  # Represents a job activated from Zeebe for processing by a worker.
+  #
+  # Wraps the raw GRPC ActivatedJob protobuf with a Ruby-idiomatic interface.
+  # Tracks job status to prevent double-completion bugs.
+  #
+  # @example Complete a job
+  #   job = Busybee::Job.new(raw_job, client: client)
+  #   job.complete!(result: "success")
+  #
+  # @example Fail a job with retry
+  #   job.fail!("Payment gateway timeout", retries: 3, backoff: 30.seconds)
+  #
+  # @example Throw a BPMN error
+  #   job.throw_bpmn_error!(:order_not_found, "Order #{order_id} not found")
+  #
+  class Job
+    attr_reader :status
+
+    # Create a new Job wrapper.
+    #
+    # @param raw_job [Busybee::GRPC::ActivatedJob] The raw GRPC job protobuf
+    # @param client [Busybee::Client] The client instance for completing/failing jobs
+    def initialize(raw_job, client:)
+      @raw_job = raw_job
+      @client = client
+      @status = :ready
+    end
+
+    # Job key (unique identifier)
+    # @return [Integer]
+    def key
+      @raw_job.key
+    end
+
+    # Job type (task definition type from BPMN)
+    # @return [String]
+    def type
+      @raw_job.type
+    end
+
+    # Process instance key
+    # @return [Integer]
+    def process_instance_key
+      @raw_job.processInstanceKey
+    end
+
+    # BPMN process ID
+    # @return [String]
+    def bpmn_process_id
+      @raw_job.bpmnProcessId
+    end
+
+    # Number of retries remaining
+    # @return [Integer]
+    def retries
+      @retries_override || @raw_job.retries
+    end
+
+    # Job deadline as a frozen Time object
+    # @return [Time]
+    def deadline
+      @deadline ||= Time.at(@raw_job.deadline / 1000.0).utc.freeze
+    end
+
+    # Job variables with indifferent access and method-style access.
+    # Returns a frozen hash that supports both hash[:key] and hash.key access.
+    # Nested hashes also support method access.
+    #
+    # @return [ActiveSupport::HashWithIndifferentAccess] frozen hash with method access
+    def variables
+      @variables ||= parse_and_freeze_hash(@raw_job.variables, "variables")
+    end
+
+    # Job custom headers with indifferent access and method-style access.
+    # Returns a frozen hash that supports both hash[:key] and hash.key access.
+    #
+    # @return [ActiveSupport::HashWithIndifferentAccess] frozen hash with method access
+    def headers
+      @headers ||= parse_and_freeze_hash(@raw_job.customHeaders, "headers")
+    end
+
+    # Complete the job with optional output variables.
+    #
+    # @param vars [Hash] Variables to return to the workflow engine
+    # @return [Object] Response from complete_job operation
+    # @raise [Busybee::JobAlreadyHandled] if job has already been completed, failed, or errored
+    def complete!(vars = {})
+      raise Busybee::JobAlreadyHandled, "Cannot complete job #{key} because it is already #{status}" unless ready?
+
+      @client.complete_job(key, vars: vars).tap do
+        @status = :complete
+        # [hook: job.completed]
+      end
+    end
+
+    # Fail the job with an error message.
+    #
+    # @param error_message_or_exception [String, Exception] Error message or exception
+    # @param retries [Integer, nil] Override retry count
+    # @param backoff [Integer, ActiveSupport::Duration, nil] Backoff before retry
+    # @return [Object] Response from fail_job operation
+    # @raise [Busybee::JobAlreadyHandled] if job has already been completed, failed, or errored
+    def fail!(error_message_or_exception, retries: nil, backoff: nil)
+      raise Busybee::JobAlreadyHandled, "Cannot fail job #{key} because it is already #{status}" unless ready?
+
+      message = format_error_message(error_message_or_exception)
+
+      @client.fail_job(key, message, retries: retries, backoff: backoff).tap do
+        @status = :failed
+        # [hook: job.failed]
+      end
+    end
+
+    # Throw a BPMN error to be caught by an error boundary event.
+    #
+    # @param code_or_exception [String, Symbol, Exception] Error code or exception
+    # @param message [String] Optional error message
+    # @return [Object] Response from throw_bpmn_error operation
+    # @raise [Busybee::JobAlreadyHandled] if job has already been completed, failed, or errored
+    def throw_bpmn_error!(code_or_exception, message = "")
+      unless ready?
+        raise Busybee::JobAlreadyHandled,
+              "Cannot throw BPMN error on job #{key} because it is already #{status}"
+      end
+
+      code = format_error_code(code_or_exception)
+      message = code_or_exception.message if code_or_exception.is_a?(Exception) && message.empty?
+
+      @client.throw_bpmn_error(key, code, message: message).tap do
+        @status = :error
+        # [hook: job.error]
+      end
+    end
+
+    # Update the retry count for this job.
+    #
+    # @param count [Integer] The new number of retries
+    # @return [Object] Response from update_job_retries operation
+    # @raise [Busybee::GRPC::Error] if the update fails
+    def update_retries(count)
+      @client.update_job_retries(key, count).tap do
+        @retries_override = count
+      end
+    end
+
+    # Update the timeout for this job.
+    #
+    # @param duration [Integer, ActiveSupport::Duration] New timeout in milliseconds
+    # @return [Object] Response from update_job_timeout operation
+    # @raise [Busybee::GRPC::Error] if the update fails
+    def update_timeout(duration)
+      duration_seconds = duration.is_a?(ActiveSupport::Duration) ? duration.in_seconds : duration / 1000.0
+      @client.update_job_timeout(key, duration).tap do
+        @deadline = (Time.now.utc + duration_seconds).freeze
+      end
+    end
+
+    # Is the job ready for processing?
+    # @return [Boolean]
+    def ready?
+      status == :ready
+    end
+
+    # Has the job been completed?
+    # @return [Boolean]
+    def complete?
+      status == :complete
+    end
+
+    # Has the job failed?
+    # @return [Boolean]
+    def failed?
+      status == :failed
+    end
+
+    # Has the job thrown a BPMN error?
+    # @return [Boolean]
+    def error?
+      status == :error
+    end
+
+    private
+
+    def parse_and_freeze_hash(json_string, attribute_name)
+      Busybee::Serialization.from_json(json_string)
+    rescue Busybee::InvalidJobJson => e
+      # Re-raise with attribute context for better error messages
+      message = "Failed to parse job #{attribute_name}: #{e.cause.message}"
+      raise Busybee::InvalidJobJson, message, e.backtrace, cause: e.cause
+    end
+
+    def format_error_message(error_message_or_exception)
+      return error_message_or_exception unless error_message_or_exception.is_a?(Exception)
+
+      message = "[#{error_message_or_exception.class.name}] #{error_message_or_exception.message}"
+      if (cause = error_message_or_exception.cause)
+        message += " (caused by: [#{cause.class.name}] #{cause.message})"
+      end
+      message
+    end
+
+    def format_error_code(code_or_exception)
+      case code_or_exception
+      when Symbol
+        code_or_exception.to_s.upcase
+      when Exception
+        # Convert MyApp::Domain::OrderNotFoundError to MY_APP_DOMAIN_ORDER_NOT_FOUND_ERROR
+        code_or_exception.class.name.gsub("::", "_").underscore.upcase
+      else
+        code_or_exception.to_s
+      end
+    end
+  end
+end

data/lib/busybee/job_stream.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "busybee/job"
+require "busybee/grpc/error"
+
+module Busybee
+  # Wraps a gRPC server stream of activated jobs with a Ruby-idiomatic interface.
+  #
+  # JobStream is Enumerable, providing `each`, `map`, `select`, and other
+  # collection methods. Each yielded element is a {Busybee::Job} instance.
+  #
+  # @note Streams are single-pass. Once consumed via `each`, `map`, etc., the
+  #   stream is exhausted. Subsequent iteration yields nothing. This is inherent
+  #   to streaming. To process jobs multiple times, collect them into an array first.
+  #
+  # @example Process jobs from a stream
+  #   stream = client.open_job_stream("send-email", job_timeout: 60.seconds)
+  #   trap("INT") { stream.close }
+  #
+  #   stream.each do |job|
+  #     send_email(job.variables.to, job.variables.subject)
+  #     job.complete!
+  #   end
+  #
+  # @example Using Enumerable methods
+  #   stream = client.open_job_stream("process-order")
+  #   high_priority = stream.select { |job| job.variables.priority == "high" }
+  #
+  class JobStream
+    include Enumerable
+
+    # Create a new JobStream wrapper.
+    #
+    # @param operation [GRPC::ActiveCall::Operation] The gRPC operation (from return_op: true)
+    # @param client [Busybee::Client] The client for job operations
+    def initialize(operation, client:)
+      @operation = operation
+      @enumerator = operation.execute
+      @client = client
+      @closed = false
+    end
+
+    # Iterate over jobs in the stream.
+    #
+    # @yield [job] Yields each job to the block
+    # @yieldparam job [Busybee::Job] The activated job
+    # @return [Enumerator] If no block given
+    # @return [self] If block given
+    # @raise [Busybee::StreamAlreadyClosed] If the stream has been closed
+    # @raise [Busybee::GRPC::Error] If the stream encounters a gRPC error
+    def each
+      raise Busybee::StreamAlreadyClosed, "Cannot iterate a closed stream" if closed?
+      return enum_for(:each) unless block_given?
+
+      @enumerator.each do |raw_job|
+        yield Busybee::Job.new(raw_job, client: @client)
+      end
+    rescue ::GRPC::Cancelled
+      # Expected when stream is closed via #close - exit gracefully
+      nil
+    rescue ::GRPC::BadStatus
+      raise Busybee::GRPC::Error, "Job stream failed"
+    end
+
+    # Close the stream.
+    #
+    # Cancels the underlying gRPC operation. This method is idempotent;
+    # calling it multiple times has no additional effect.
+    #
+    # @return [void]
+    def close
+      return if @closed
+
+      @operation.cancel
+      @closed = true
+    end
+
+    # Check if the stream has been closed.
+    #
+    # @return [Boolean] true if the stream has been closed
+    def closed?
+      @closed
+    end
+  end
+end