busybee 0.1.0

data/lib/busybee/testing/helpers.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "base64"
+require "json"
+require "busybee/grpc"
+require_relative "activated_job"
+
+module Busybee
+  module Testing
+    # Raised when no job is available for activation
+    class NoJobAvailable < StandardError; end
+
+    # RSpec helper methods for testing BPMN workflows against Zeebe.
+    module Helpers
+      # Deploy a BPMN process file to Zeebe.
+      #
+      # By default, deploys the BPMN file as-is using its original process ID.
+      # Optionally, you can uniquify the process ID for test isolation.
+      #
+      # @param path [String] path to BPMN file
+      # @param uniquify [nil, true, String] uniquification behavior:
+      #   - nil (default): deploy as-is with original process ID
+      #   - true: auto-generate unique process ID like "test-process-abc123"
+      #   - String: use provided string as custom process ID
+      # @return [Hash] deployment info with keys:
+      #   - :process [ProcessMetadata] - GRPC process metadata object
+      #   - :process_id [String] - the BPMN process ID (uniquified or original)
+      #
+      # @example Deploy as-is (most common)
+      #   result = deploy_process("path/to/process.bpmn")
+      #   result[:process_id] #=> "simple-process" (from BPMN file)
+      #
+      # @example Deploy with auto-generated unique ID (for test isolation)
+      #   result = deploy_process("path/to/process.bpmn", uniquify: true)
+      #   result[:process_id] #=> "test-process-a1b2c3d4e5f6"
+      #
+      # @example Deploy with custom ID
+      #   result = deploy_process("path/to/process.bpmn", uniquify: "my-test-process")
+      #   result[:process_id] #=> "my-test-process"
+      def deploy_process(path, uniquify: nil)
+        if uniquify
+          process_id = uniquify == true ? unique_process_id : uniquify
+          bpmn_content = bpmn_with_unique_id(path, process_id)
+        else
+          bpmn_content = File.read(path)
+          process_id = extract_process_id(bpmn_content)
+        end
+
+        resource = Busybee::GRPC::Resource.new(
+          name: File.basename(path),
+          content: bpmn_content
+        )
+
+        request = Busybee::GRPC::DeployResourceRequest.new(
+          resources: [resource]
+        )
+
+        response = grpc_client.deploy_resource(request)
+
+        {
+          process: response.deployments.first.process,
+          process_id: process_id
+        }
+      end
+
+      # Create a process instance, yield its key, and cancel on block exit.
+      #
+      # @param process_name [String] BPMN process ID
+      # @param variables [Hash] variables to start the process with
+      # @yield [Integer] the process instance key
+      def with_process_instance(process_name, variables = {})
+        request = Busybee::GRPC::CreateProcessInstanceRequest.new(
+          bpmnProcessId: process_name,
+          version: -1,
+          variables: JSON.generate(variables)
+        )
+
+        response = grpc_client.create_process_instance(request)
+        @current_process_instance_key = response.processInstanceKey
+
+        yield @current_process_instance_key
+      ensure
+        if @current_process_instance_key
+          cancel_process_instance(@current_process_instance_key)
+          @last_process_instance_key = @current_process_instance_key
+          @current_process_instance_key = nil
+        end
+      end
+
+      # Returns the current process instance key (set by with_process_instance).
+      #
+      # @return [Integer, nil]
+      def process_instance_key
+        @current_process_instance_key
+      end
+
+      # Returns the last process instance key from the most recent with_process_instance call.
+      # Useful for debugging failed tests by tying failures to residual data in ElasticSearch.
+      #
+      # @return [Integer, nil]
+      def last_process_instance_key
+        @last_process_instance_key
+      end
+
+      # Checks if Zeebe is available and responsive.
+      #
+      # This method attempts to connect to Zeebe and call the topology endpoint
+      # to verify the service is running and healthy.
+      #
+      # @param timeout [Integer] timeout in seconds for the connection check
+      # @return [Boolean] true if Zeebe is available, false otherwise
+      def zeebe_available?(timeout: 5)
+        request = Busybee::GRPC::TopologyRequest.new
+        grpc_client.topology(request, deadline: Time.now + timeout)
+        true
+      rescue GRPC::Unavailable, GRPC::DeadlineExceeded, GRPC::Core::CallError, GRPC::Unauthenticated
+        false
+      end
+
+      # Activate a single job of the given type.
+      #
+      # @param type [String] job type
+      # @return [ActivatedJob]
+      # @raise [NoJobAvailable] if no job is available
+      def activate_job(type)
+        jobs = activate_jobs_raw(type, max_jobs: 1)
+        raise NoJobAvailable, "No job of type '#{type}' available" if jobs.empty?
+
+        ActivatedJob.new(jobs.first, client: grpc_client)
+      end
+
+      # Activate multiple jobs of the given type.
+      #
+      # @param type [String] job type
+      # @param max_jobs [Integer] maximum number of jobs to activate
+      # @return [Enumerator<ActivatedJob>]
+      def activate_jobs(type, max_jobs:)
+        Enumerator.new do |yielder|
+          activate_jobs_raw(type, max_jobs: max_jobs).each do |raw_job|
+            yielder << ActivatedJob.new(raw_job, client: grpc_client)
+          end
+        end
+      end
+
+      # Publish a message to Zeebe.
+      #
+      # @param name [String] message name
+      # @param correlation_key [String] correlation key
+      # @param variables [Hash] message variables
+      # @param ttl_ms [Integer] time-to-live in milliseconds
+      def publish_message(name, correlation_key:, variables: {}, ttl_ms: 5000)
+        request = Busybee::GRPC::PublishMessageRequest.new(
+          name: name,
+          correlationKey: correlation_key,
+          variables: JSON.generate(variables),
+          timeToLive: ttl_ms
+        )
+        grpc_client.publish_message(request)
+      end
+
+      # Set variables on a process scope.
+      #
+      # @param scope_key [Integer] element instance key
+      # @param variables [Hash] variables to set
+      # @param local [Boolean] whether variables are local to scope
+      def set_variables(scope_key, variables, local: true)
+        request = Busybee::GRPC::SetVariablesRequest.new(
+          elementInstanceKey: scope_key,
+          variables: JSON.generate(variables),
+          local: local
+        )
+        grpc_client.set_variables(request)
+      end
+
+      # Assert that the current process instance has completed.
+      #
+      # @param wait [Float] seconds to wait before checking
+      # @raise [RuntimeError] if process is still running
+      def assert_process_completed!(wait: 0.25)
+        sleep(wait) if wait.positive?
+
+        request = Busybee::GRPC::CancelProcessInstanceRequest.new(
+          processInstanceKey: process_instance_key
+        )
+
+        begin
+          grpc_client.cancel_process_instance(request)
+        rescue ::GRPC::NotFound
+          true # Expected - process has completed
+        else
+          raise "Process instance #{process_instance_key} is still running (expected it to be completed)"
+        end
+      end
+
+      private
+
+      def unique_process_id
+        "test-process-#{SecureRandom.hex(6)}"
+      end
+
+      def extract_process_id(bpmn_content)
+        match = bpmn_content.match(/<bpmn:process id="([^"]+)"/)
+        match ? match[1] : nil
+      end
+
+      def bpmn_with_unique_id(bpmn_path, process_id)
+        bpmn_content = File.read(bpmn_path)
+        bpmn_content
+          .gsub(/(<bpmn:process id=")[^"]+/, "\\1#{process_id}")
+          # Possessive quantifiers (++, *+) prevent polynomial backtracking
+          .gsub(/(<bpmndi:BPMNPlane\s++[^>]*+bpmnElement=")[^"]++/, "\\1#{process_id}")
+      end
+
+      def cancel_process_instance(key)
+        request = Busybee::GRPC::CancelProcessInstanceRequest.new(
+          processInstanceKey: key
+        )
+        grpc_client.cancel_process_instance(request)
+        true
+      rescue ::GRPC::NotFound
+        # Process already completed, ignore
+        false
+      end
+
+      def activate_jobs_raw(type, max_jobs:)
+        worker = "#{type}-#{SecureRandom.hex(4)}"
+        request = Busybee::GRPC::ActivateJobsRequest.new(
+          type: type,
+          worker: worker,
+          timeout: 30_000,
+          maxJobsToActivate: max_jobs,
+          requestTimeout: Busybee::Testing.activate_request_timeout
+        )
+
+        jobs = []
+        grpc_client.activate_jobs(request).each do |response|
+          jobs.concat(response.jobs.to_a)
+        end
+        jobs
+      end
+
+      def grpc_client
+        @grpc_client ||= Busybee::GRPC::Gateway::Stub.new(
+          Busybee::Testing.address,
+          :this_channel_is_insecure
+        )
+      end
+    end
+  end
+end

data/lib/busybee/testing/matchers/have_activated.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+require_relative "../activated_job"
+
+RSpec::Matchers.define :have_activated do |job_type|
+  match do |helper|
+    @job_type = job_type
+    @helper = helper
+
+    begin
+      @activated_job = helper.activate_job(job_type)
+      @job_activated = true
+    rescue Busybee::Testing::NoJobAvailable
+      @job_activated = false
+      return false
+    end
+
+    # If we have chained expectations, validate them
+    if @expected_variables
+      expected_stringified = @expected_variables.transform_keys(&:to_s)
+      actual = @activated_job.variables
+      unless actual.slice(*expected_stringified.keys) == expected_stringified
+        @variables_mismatch = true
+        @actual_variables = actual
+        return false
+      end
+    end
+
+    if @expected_headers
+      expected_stringified = @expected_headers.transform_keys(&:to_s)
+      actual = @activated_job.headers
+      unless actual.slice(*expected_stringified.keys) == expected_stringified
+        @headers_mismatch = true
+        @actual_headers = actual
+        return false
+      end
+    end
+
+    true
+  end
+
+  chain :with_variables do |expected|
+    @expected_variables = expected
+  end
+
+  chain :with_headers do |expected|
+    @expected_headers = expected
+  end
+
+  failure_message do
+    if !@job_activated
+      "No job of type '#{@job_type}' was activated"
+    elsif @variables_mismatch
+      "expected job variables to include #{@expected_variables.inspect}\n" \
+        "actual variables: #{@actual_variables.inspect}"
+    elsif @headers_mismatch
+      "expected job headers to include #{@expected_headers.inspect}\n" \
+        "actual headers: #{@actual_headers.inspect}"
+    end
+  end
+
+  failure_message_when_negated do
+    "expected no job of type '#{@job_type}' to be activated, but one was"
+  end
+end

data/lib/busybee/testing/matchers/have_received_headers.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+RSpec::Matchers.define :have_received_headers do |expected|
+  match do |job|
+    expected_stringified = expected.transform_keys(&:to_s)
+    @actual = job.headers
+    @actual.slice(*expected_stringified.keys) == expected_stringified
+  end
+
+  failure_message do
+    "expected job headers to include #{expected.inspect}\n" \
+      "actual headers: #{@actual.inspect}"
+  end
+
+  failure_message_when_negated do
+    "expected job headers not to include #{expected.inspect}\n" \
+      "actual headers: #{@actual.inspect}"
+  end
+end

data/lib/busybee/testing/matchers/have_received_variables.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "rspec/expectations"
+
+RSpec::Matchers.define :have_received_variables do |expected|
+  match do |job|
+    expected_stringified = expected.transform_keys(&:to_s)
+    @actual = job.variables
+    @actual.slice(*expected_stringified.keys) == expected_stringified
+  end
+
+  failure_message do
+    "expected job variables to include #{expected.inspect}\n" \
+      "actual variables: #{@actual.inspect}"
+  end
+
+  failure_message_when_negated do
+    "expected job variables not to include #{expected.inspect}\n" \
+      "actual variables: #{@actual.inspect}"
+  end
+end

data/lib/busybee/testing.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "busybee/grpc"
+
+module Busybee
+  # Testing support for BPMN workflows with RSpec.
+  #
+  # @example Configuration
+  #   Busybee::Testing.configure do |config|
+  #     config.address = "localhost:26500"
+  #     config.username = "demo"
+  #     config.password = "demo"
+  #     config.activate_request_timeout = 2000
+  #   end
+  #
+  module Testing
+    class << self
+      attr_writer :address, :username, :password, :activate_request_timeout
+
+      def configure
+        yield self
+      end
+
+      def address
+        @address || ENV["ZEEBE_ADDRESS"] || "localhost:26500"
+      end
+
+      def username
+        @username || ENV["ZEEBE_USERNAME"] || "demo"
+      end
+
+      def password
+        @password || ENV["ZEEBE_PASSWORD"] || "demo"
+      end
+
+      def activate_request_timeout
+        @activate_request_timeout || 1000
+      end
+    end
+  end
+end
+
+# Auto-load RSpec integration if RSpec is available
+if defined?(RSpec)
+  require "busybee/testing/helpers"
+  require "busybee/testing/activated_job"
+  require "busybee/testing/matchers/have_received_variables"
+  require "busybee/testing/matchers/have_received_headers"
+  require "busybee/testing/matchers/have_activated"
+
+  RSpec.configure do |config|
+    config.include Busybee::Testing::Helpers
+  end
+end

data/lib/busybee/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Busybee
+  VERSION = "0.1.0"
+end

data/lib/busybee.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "busybee/version"
+
+# Top-level gem module, only holds configuration values.
+module Busybee
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: busybee
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andy Rusterholz
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.76'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.76'
+description: The missing Ruby gem for Camunda 8. Production-ready worker framework
+  that runs out of the box - define your job handlers and go. Idiomatic Zeebe client
+  with sensible defaults and configuration where you want it. RSpec testing helpers
+  and CI/CD deployment tooling for BPMNs.
+email:
+- andyrusterholz@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/grpc.md
+- docs/testing.md
+- lib/busybee.rb
+- lib/busybee/grpc.rb
+- lib/busybee/grpc/gateway_pb.rb
+- lib/busybee/grpc/gateway_services_pb.rb
+- lib/busybee/testing.rb
+- lib/busybee/testing/activated_job.rb
+- lib/busybee/testing/helpers.rb
+- lib/busybee/testing/matchers/have_activated.rb
+- lib/busybee/testing/matchers/have_received_headers.rb
+- lib/busybee/testing/matchers/have_received_variables.rb
+- lib/busybee/version.rb
+homepage: https://github.com/rusterholz/busybee
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rusterholz/busybee
+  source_code_uri: https://github.com/rusterholz/busybee
+  changelog_uri: https://github.com/rusterholz/busybee/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A complete Ruby toolkit for BPMN workflow orchestration.
+test_files: []