busybee 0.1.0 → 0.3.0

data/lib/busybee/client/variable_operations.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "busybee/grpc"
+require "busybee/serialization"
+
+module Busybee
+  class Client
+    # Variable and incident operations for managing process instance state.
+    module VariableOperations
+      # Set variables on a process instance or element instance.
+      #
+      # @param element_instance_key [Integer, String] The element instance key
+      #   (process instance key or service task key)
+      # @param vars [Hash] Variables to set
+      # @param local [Boolean] If true, variables are set only in the local scope
+      #   (not propagated to parent scopes)
+      # @return [Integer] The variable set operation key
+      # @raise [ArgumentError] if vars is not a Hash
+      # @raise [Busybee::GRPC::Error] if setting variables fails
+      #
+      # @example Set variables on a process instance
+      #   key = client.set_variables(process_instance_key, vars: { status: "approved" })
+      #   # => 12345
+      #
+      # @example Set local variables on an element
+      #   client.set_variables(element_key, vars: { tempData: "value" }, local: true)
+      #
+      def set_variables(element_instance_key, vars: {}, local: false)
+        raise ArgumentError, "vars must be a Hash" unless vars.is_a?(Hash)
+
+        request = Busybee::GRPC::SetVariablesRequest.new(
+          elementInstanceKey: element_instance_key.to_i,
+          variables: Busybee::Serialization.to_json(vars),
+          local: local
+        )
+
+        with_retry do
+          stub.set_variables(request).key
+        end
+      end
+
+      # Resolve an incident.
+      #
+      # @param incident_key [Integer, String] The incident key to resolve
+      # @return [Boolean] true if resolved
+      # @raise [Busybee::GRPC::Error] if resolving the incident fails
+      #
+      # @example Resolve an incident
+      #   client.resolve_incident(54321)
+      #   # => true
+      #
+      def resolve_incident(incident_key)
+        request = Busybee::GRPC::ResolveIncidentRequest.new(
+          incidentKey: incident_key.to_i
+        )
+
+        with_retry do
+          stub.resolve_incident(request)
+          true
+        end
+      end
+    end
+  end
+end

data/lib/busybee/client.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/duration"
+require "busybee/credentials"
+require "busybee/client/error_handling"
+require "busybee/client/job_operations"
+require "busybee/client/message_operations"
+require "busybee/client/process_operations"
+require "busybee/client/variable_operations"
+
+module Busybee
+  # Ruby-idiomatic wrapper around Zeebe GRPC API.
+  #
+  # @example Basic usage with local Zeebe
+  #   client = Busybee::Client.new(insecure: true)
+  #   client.deploy_process("workflow.bpmn")
+  #
+  # @example With explicit credentials
+  #   credentials = Busybee::Credentials::Insecure.new
+  #   client = Busybee::Client.new(credentials)
+  #
+  # @example With gem-level configuration
+  #   Busybee.credential_type = :insecure
+  #   client = Busybee::Client.new
+  #
+  class Client
+    include ErrorHandling
+    include JobOperations
+    include MessageOperations
+    include ProcessOperations
+    include VariableOperations
+
+    attr_reader :credentials
+
+    # Create a new client.
+    #
+    # @param credentials [Credentials, nil] Explicit credentials object (first positional arg)
+    # @param params [Hash, nil] Credential kwargs (passed to Credentials.build if no explicit credentials)
+    # @raise [ArgumentError] if both credentials object and credential params are provided
+    #
+    # @example With credential parameters:
+    #   Client.new(insecure: true, cluster_address: "localhost:26500")
+    #
+    # @example With explicit credentials:
+    #   creds = Credentials::Insecure.new(cluster_address: "localhost:26500")
+    #   Client.new(creds)
+    #
+    # @example Inferred entirely from gem configuration or env vars:
+    #   Client.new
+    #
+    def initialize(credentials = nil, **params)
+      if credentials && params.any?
+        raise ArgumentError, "cannot pass both explicit credentials and credential parameters"
+      end
+
+      @credentials = if credentials
+                       credentials
+                     elsif params.empty? && Busybee.credentials.is_a?(Busybee::Credentials)
+                       Busybee.credentials
+                     else
+                       Credentials.build(**params) # will attempt to autodetect from env if no params are given
+                     end
+    end
+
+    # Returns the cluster address from credentials.
+    # @return [String] Cluster address (host:port)
+    def cluster_address
+      credentials.cluster_address
+    end
+
+    private
+
+    # Returns the GRPC stub for making API calls.
+    # @return [Busybee::GRPC::Gateway::Stub]
+    def stub
+      credentials.grpc_stub
+    end
+
+    # Ensures a value is in milliseconds.
+    # @param value [Integer, ActiveSupport::Duration] Value to convert
+    # @return [Integer] Value in milliseconds
+    def milliseconds_from(value)
+      value.is_a?(ActiveSupport::Duration) ? value.in_milliseconds.to_i : value.to_i
+    end
+  end
+end

data/lib/busybee/configure.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module Busybee
+  # Validated setters for gem-level configuration.
+  # Included into Busybee's singleton class; readers live in busybee.rb.
+  module Configure # rubocop:disable Metrics/ModuleLength
+    # --- String configs ---
+
+    def cluster_address=(value)
+      if value.nil?
+        @cluster_address = nil
+        return
+      end
+
+      validate_string!(:cluster_address, value)
+      @cluster_address = value.to_s
+    end
+
+    def worker_name=(value)
+      if value.nil?
+        @worker_name = nil
+        return
+      end
+
+      validate_string!(:worker_name, value)
+      @worker_name = value.to_s
+    end
+
+    # --- Boolean configs ---
+
+    def default_input_required=(value)
+      if value.nil?
+        @default_input_required = nil
+        return
+      end
+
+      validate_boolean!(:default_input_required, value)
+      @default_input_required = value
+    end
+
+    def default_max_jobs=(value)
+      @default_max_jobs = value.nil? ? nil : validate_positive_integer!(:default_max_jobs, value)
+    end
+
+    def default_output_required=(value)
+      if value.nil?
+        @default_output_required = nil
+        return
+      end
+
+      validate_boolean!(:default_output_required, value)
+      @default_output_required = value
+    end
+
+    def default_buffer=(value)
+      if value.nil?
+        @default_buffer = nil
+        return
+      end
+
+      validate_boolean!(:default_buffer, value)
+      @default_buffer = value
+    end
+
+    def grpc_retry_enabled=(value)
+      if value.nil?
+        @grpc_retry_enabled = nil
+        return
+      end
+
+      validate_boolean!(:grpc_retry_enabled, value)
+      @grpc_retry_enabled = value
+    end
+
+    # --- Duration configs (Integer ms or ActiveSupport::Duration) ---
+
+    def default_fail_job_backoff=(value)
+      @default_fail_job_backoff = value.nil? ? nil : validate_duration!(:default_fail_job_backoff, value)
+    end
+
+    def default_job_lock_timeout=(value)
+      @default_job_lock_timeout = value.nil? ? nil : validate_duration!(:default_job_lock_timeout, value)
+    end
+
+    def default_job_request_timeout=(value)
+      @default_job_request_timeout = value.nil? ? nil : validate_duration!(:default_job_request_timeout, value)
+    end
+
+    def default_message_ttl=(value)
+      @default_message_ttl = value.nil? ? nil : validate_duration!(:default_message_ttl, value)
+    end
+
+    def grpc_retry_delay_ms=(value)
+      @grpc_retry_delay_ms = value.nil? ? nil : validate_duration!(:grpc_retry_delay_ms, value)
+    end
+
+    def default_backpressure_delay=(value)
+      @default_backpressure_delay = value.nil? ? nil : validate_duration!(:default_backpressure_delay, value)
+    end
+
+    # --- Buffer throttle (three-state: false/nil = off, true → 0, Numeric = ms) ---
+
+    def default_buffer_throttle=(value)
+      @default_buffer_throttle = value.nil? ? nil : validate_buffer_throttle!(:default_buffer_throttle, value)
+    end
+
+    # --- Worker mode ---
+
+    def default_worker_mode=(value)
+      if value.nil?
+        @default_worker_mode = nil
+        return
+      end
+
+      validate_worker_mode!(:default_worker_mode, value)
+      @default_worker_mode = value.to_sym
+    end
+
+    # --- Error class list ---
+
+    def grpc_retry_errors=(value)
+      if value.nil?
+        @grpc_retry_errors = nil
+        return
+      end
+
+      validate_error_classes!(:grpc_retry_errors, value)
+      @grpc_retry_errors = value
+    end
+
+    # --- Shutdown errors (Array coercion, validates each is Exception subclass) ---
+
+    def shutdown_on_errors=(value)
+      coerced = Array(value)
+      coerced.each do |klass|
+        unless klass.is_a?(Class) && klass <= Exception
+          raise ArgumentError,
+                "shutdown_on_errors expects exception classes, got #{klass.inspect} (#{klass.class})"
+        end
+      end
+      @shutdown_on_errors = coerced
+    end
+
+    # --- Log format ---
+
+    def log_format=(value)
+      if value.nil?
+        @log_format = nil
+        return
+      end
+
+      str_value = value.to_s
+      if VALID_LOG_FORMATS.include?(str_value)
+        @log_format = str_value.to_sym
+      else
+        Logging.warn("Invalid log_format: #{str_value.inspect}. Valid formats: #{VALID_LOG_FORMATS.join(', ')}")
+      end
+    end
+
+    # --- Credential type ---
+
+    def credential_type=(value)
+      if value.nil?
+        @credential_type = nil
+        return
+      end
+
+      str_value = value.to_s
+      if VALID_CREDENTIAL_TYPES.include?(str_value)
+        @credential_type = str_value.to_sym
+      else
+        Logging.warn("Invalid credential_type: #{str_value.inspect}. Valid types: #{VALID_CREDENTIAL_TYPES.join(', ')}")
+      end
+    end
+
+    # --- Credentials object ---
+
+    def credentials=(value)
+      if value.nil?
+        @credentials = nil
+        return
+      end
+
+      unless value.is_a?(Busybee::Credentials)
+        raise ArgumentError, "credentials must be a Busybee::Credentials object, got #{value.class}"
+      end
+
+      @credentials = value
+    end
+
+    private
+
+    # Validates and coerces a duration config value.
+    # Returns the (possibly coerced) value to assign.
+    def validate_duration!(name, value) # rubocop:disable Metrics/AbcSize
+      return value if value.is_a?(Integer)
+      return value if defined?(ActiveSupport::Duration) && value.is_a?(ActiveSupport::Duration)
+
+      if value.is_a?(String)
+        return value.to_f.to_i if value.match?(/\A\d+(\.\d+)?\z/)
+
+        raise ArgumentError,
+              "#{name} accepts Integer, ActiveSupport::Duration, or numeric String, " \
+              "got non-numeric String #{value.inspect}"
+      end
+
+      if value.is_a?(Numeric)
+        Logging.warn("#{name}: coercing #{value.class} #{value.inspect} to Integer #{value.to_i}")
+        return value.to_i
+      end
+
+      raise ArgumentError,
+            "#{name} accepts Integer, ActiveSupport::Duration, or numeric String, got #{value.class}"
+    end
+
+    def validate_boolean!(name, value)
+      return if [true, false].include?(value)
+
+      raise ArgumentError, "#{name} accepts true or false, got #{value.inspect} (#{value.class})"
+    end
+
+    def validate_positive_integer!(name, value)
+      if value.is_a?(Integer)
+        raise ArgumentError, "#{name} must be positive, got #{value}" unless value.positive?
+
+        return value
+      end
+
+      if value.is_a?(String) && value.match?(/\A\d+\z/)
+        int_value = value.to_i
+        raise ArgumentError, "#{name} must be positive, got #{int_value}" unless int_value.positive?
+
+        return int_value
+      end
+
+      raise ArgumentError,
+            "#{name} accepts a positive Integer or numeric String, got #{value.inspect} (#{value.class})"
+    end
+
+    def validate_string!(name, value)
+      return if value.is_a?(String) || value.is_a?(Symbol)
+
+      raise ArgumentError, "#{name} accepts String or Symbol, got #{value.inspect} (#{value.class})"
+    end
+
+    # Validates and coerces a buffer throttle value.
+    # Returns the (possibly coerced) value to assign.
+    def validate_buffer_throttle!(name, value)
+      return 0 if value == true
+      return false if value == false
+
+      if value.is_a?(Numeric)
+        raise ArgumentError, "#{name} must be non-negative, got #{value.inspect}" if value.negative?
+
+        return value
+      end
+
+      if value.is_a?(String)
+        return value.to_f if value.match?(/\A\d+(\.\d+)?\z/)
+
+        raise ArgumentError,
+              "#{name} accepts Numeric, boolean, or numeric String, got non-numeric String #{value.inspect}"
+      end
+
+      raise ArgumentError, "#{name} accepts Numeric, boolean, or numeric String, got #{value.inspect} (#{value.class})"
+    end
+
+    def validate_worker_mode!(name, value)
+      sym = value.to_sym
+      return if VALID_WORKER_MODES.include?(sym)
+
+      raise ArgumentError,
+            "#{name} must be one of #{VALID_WORKER_MODES.map(&:inspect).join(', ')}, got #{value.inspect}"
+    rescue NoMethodError
+      raise ArgumentError,
+            "#{name} accepts Symbol or String, got #{value.inspect} (#{value.class})"
+    end
+
+    def validate_error_classes!(name, value)
+      raise ArgumentError, "#{name} accepts an Array of exception classes, got #{value.class}" unless value.is_a?(Array)
+
+      value.each do |klass|
+        unless klass.is_a?(Class) && klass <= Exception
+          raise ArgumentError,
+                "#{name} expects exception classes, got #{klass.inspect} (#{klass.class})"
+        end
+      end
+    end
+  end
+end

data/lib/busybee/credentials/camunda_cloud.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "busybee/credentials/oauth"
+
+module Busybee
+  class Credentials
+    # Camunda Cloud-specific OAuth credentials.
+    # Automatically derives the cluster address and OAuth configuration
+    # from cluster ID and region.
+    #
+    # @example Basic usage
+    #   credentials = Busybee::Credentials::CamundaCloud.new(
+    #     client_id: ENV["CAMUNDA_CLIENT_ID"],
+    #     client_secret: ENV["CAMUNDA_CLIENT_SECRET"],
+    #     cluster_id: ENV["CAMUNDA_CLUSTER_ID"],
+    #     region: ENV["CAMUNDA_CLUSTER_REGION"]
+    #   )
+    #   stub = credentials.grpc_stub
+    #
+    # @example With scope for API access control
+    #   credentials = Busybee::Credentials::CamundaCloud.new(
+    #     client_id: ENV["CAMUNDA_CLIENT_ID"],
+    #     client_secret: ENV["CAMUNDA_CLIENT_SECRET"],
+    #     cluster_id: ENV["CAMUNDA_CLUSTER_ID"],
+    #     region: ENV["CAMUNDA_CLUSTER_REGION"],
+    #     scope: "Zeebe Tasklist Operate"
+    #   )
+    #
+    class CamundaCloud < OAuth
+      CAMUNDA_AUTH_URL = "https://login.cloud.camunda.io/oauth/token"
+      CAMUNDA_AUDIENCE = "zeebe.camunda.io"
+
+      # @param client_id [String] Camunda Cloud client ID
+      # @param client_secret [String] Camunda Cloud client secret
+      # @param cluster_id [String] Camunda Cloud cluster ID
+      # @param region [String] Camunda Cloud region (e.g., "bru-2", "us-east-1")
+      # @param scope [String, nil] Optional OAuth2 scope for API access control
+      def initialize(client_id:, client_secret:, cluster_id:, region:, scope: nil)
+        raise ArgumentError, "client_id is required" if client_id.nil?
+        raise ArgumentError, "client_secret is required" if client_secret.nil?
+        raise ArgumentError, "cluster_id is required" if cluster_id.nil?
+        raise ArgumentError, "region is required" if region.nil?
+
+        @cluster_id = cluster_id
+        @region = region
+
+        super(
+          token_url: CAMUNDA_AUTH_URL,
+          client_id: client_id,
+          client_secret: client_secret,
+          audience: CAMUNDA_AUDIENCE,
+          scope: scope,
+          cluster_address: "#{cluster_id}.#{region}.zeebe.camunda.io:443"
+        )
+      end
+    end
+  end
+end

data/lib/busybee/credentials/insecure.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "busybee/credentials"
+
+module Busybee
+  class Credentials
+    # Insecure credentials for local development, docker-compose, and CI.
+    # No TLS, no authentication.
+    #
+    # @example Connect to local Zeebe
+    #   credentials = Busybee::Credentials::Insecure.new
+    #   stub = credentials.grpc_stub
+    #
+    # @example Connect to custom address
+    #   credentials = Busybee::Credentials::Insecure.new(cluster_address: "zeebe:26500")
+    #   stub = credentials.grpc_stub
+    #
+    class Insecure < Credentials
+      def grpc_channel_credentials
+        :this_channel_is_insecure
+      end
+    end
+  end
+end

data/lib/busybee/credentials/oauth.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/cache"
+require "grpc"
+require "json"
+require "net/http"
+
+require "busybee/credentials"
+require "busybee/error"
+
+module Busybee
+  class Credentials
+    # OAuth2 credentials with automatic token refresh.
+    # Combines TLS channel credentials with OAuth2 call credentials.
+    #
+    # Token caching uses ActiveSupport::Cache with race_condition_ttl to prevent
+    # thundering herd during refresh - multiple threads won't block waiting for
+    # a refresh when the token is still valid.
+    #
+    # @example Basic usage
+    #   credentials = Busybee::Credentials::OAuth.new(
+    #     token_url: "https://auth.example.com/oauth/token",
+    #     client_id: "my-client-id",
+    #     client_secret: "my-client-secret",
+    #     audience: "zeebe-api",
+    #     cluster_address: "zeebe.example.com:443"
+    #   )
+    #   stub = credentials.grpc_stub
+    #
+    # @example With custom CA certificate
+    #   credentials = Busybee::Credentials::OAuth.new(
+    #     token_url: "https://auth.example.com/oauth/token",
+    #     client_id: "my-client-id",
+    #     client_secret: "my-client-secret",
+    #     audience: "zeebe-api",
+    #     cluster_address: "zeebe.example.com:443",
+    #     certificate_file: "/path/to/ca-cert.pem"
+    #   )
+    #
+    class OAuth < Credentials
+      # These constants may become configuration options in a future version.
+      DEFAULT_EXPIRY_SECONDS = 60 * 50 # 50 minutes
+      RACE_CONDITION_TTL_SECONDS = 30
+      TOKEN_CACHE_SIZE_BYTES = 4 * 1024 * 1024 # 4MB
+
+      # @param token_url [String] OAuth2 token endpoint URL
+      # @param client_id [String] OAuth2 client ID
+      # @param client_secret [String] OAuth2 client secret
+      # @param audience [String] OAuth2 audience (API identifier)
+      # @param scope [String, nil] Optional OAuth2 scope for API access control
+      # @param cluster_address [String, nil] Zeebe cluster address (host:port)
+      # @param certificate_file [String, nil] Optional CA certificate file path
+      def initialize( # rubocop:disable Metrics/ParameterLists
+        token_url:,
+        client_id:,
+        client_secret:,
+        audience:,
+        scope: nil,
+        cluster_address: nil,
+        certificate_file: nil
+      )
+        raise ArgumentError, "token_url is required" if token_url.nil?
+        raise ArgumentError, "client_id is required" if client_id.nil?
+        raise ArgumentError, "client_secret is required" if client_secret.nil?
+        raise ArgumentError, "audience is required" if audience.nil?
+
+        super(cluster_address: cluster_address)
+        @token_uri = URI(token_url)
+        @client_id = client_id
+        @client_secret = client_secret
+        @audience = audience
+        @scope = scope
+        @certificate_file = certificate_file
+        @current_expiry = DEFAULT_EXPIRY_SECONDS - RACE_CONDITION_TTL_SECONDS
+      end
+
+      def grpc_channel_credentials
+        build_tls_credentials.compose(grpc_call_credentials)
+      end
+
+      private
+
+      def grpc_call_credentials
+        ::GRPC::Core::CallCredentials.new(method(:token_updater).to_proc)
+      end
+
+      def build_tls_credentials
+        if @certificate_file
+          ::GRPC::Core::ChannelCredentials.new(File.read(@certificate_file))
+        else
+          ::GRPC::Core::ChannelCredentials.new
+        end
+      end
+
+      def current_token
+        # Use race_condition_ttl to prevent thundering herd:
+        # - When token is fresh, multiple threads read from cache
+        # - 30s before expiry, first thread refreshes while others use stale token
+        fetch_options = { expires_in: @current_expiry, race_condition_ttl: RACE_CONDITION_TTL_SECONDS }
+        token_cache.fetch(cache_key, fetch_options) do |_key, options = nil|
+          token_data = fetch_token_response
+
+          @current_expiry =
+            token_data.fetch("expires_in", DEFAULT_EXPIRY_SECONDS).to_i - RACE_CONDITION_TTL_SECONDS
+
+          # Set cache expiry dynamically if possible (Rails 7.1+ only):
+          options.expires_in = @current_expiry if options&.respond_to?(:expires_in=) # rubocop:disable Lint/RedundantSafeNavigation
+
+          token_data["access_token"]
+        end
+      end
+
+      def fetch_token_response
+        response = http_client.request(build_token_request)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Busybee::OAuthTokenRefreshFailed, "HTTP #{response.code}: #{response.body}"
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise Busybee::InvalidOAuthResponse, "Invalid JSON response from token endpoint: #{e.message}"
+      end
+
+      def http_client
+        Net::HTTP.new(@token_uri.host, @token_uri.port).tap do |client|
+          client.use_ssl = (@token_uri.scheme == "https")
+        end
+      end
+
+      def build_token_request
+        Net::HTTP::Post.new(@token_uri.path).tap do |request|
+          form_data = {
+            "grant_type" => "client_credentials",
+            "client_id" => @client_id,
+            "client_secret" => @client_secret,
+            "audience" => @audience
+          }
+          form_data["scope"] = @scope if @scope
+          request.set_form_data(form_data)
+        end
+      end
+
+      def token_updater(_context)
+        { authorization: "Bearer #{current_token}" }
+      end
+
+      def cache_key
+        @cache_key ||= "busybee:oauth_token:#{@audience}:#{@client_id}"
+      end
+
+      def token_cache
+        @token_cache ||= ActiveSupport::Cache::MemoryStore.new(size: TOKEN_CACHE_SIZE_BYTES)
+      end
+    end
+  end
+end