busybee 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c005e2f714f3f1ea1b3eedf3d8e7b6ce72ad88fe27cf2a8e84637ca4fe3de281
+  data.tar.gz: cbefb422a412d32143493b8903886e6429f59bd639a3a05de052f89a94be9edb
+SHA512:
+  metadata.gz: e812d00b20c0ff7395b72db6225d57a2adcdee6ad9ecf7381215cd5352b5b034458df6bb3728a3cd25429effee83bc1f85c941dc2f4a7937f86cfb3d64f21688
+  data.tar.gz: 61a813477c650a801a04d6d5ed50dc2a5bbef5686de5690599943a61898d2b77a3d66c52109c037c4e99fcf0cfb02c2393cb9f369cac9a65d3ef9da20a8d9da2

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-29
+
+Initial public release with foundational components for testing BPMN workflows.
+
+### Added
+
+- **Testing module** (`Busybee::Testing`) - RSpec helpers and matchers for testing BPMN workflows against Zeebe:
+  - `deploy_process` - Deploy BPMN files with optional unique IDs for test isolation
+  - `with_process_instance` - Create process instances with automatic cleanup
+  - `activate_job` / `activate_jobs` - Activate jobs for assertions
+  - `publish_message` - Trigger message catch events
+  - `set_variables` - Update process variables
+  - `assert_process_completed!` - Verify workflow completion
+  - `ActivatedJob` fluent API with `expect_variables`, `expect_headers`, `and_complete`, `and_fail`, `and_throw_error_event`
+  - RSpec matchers: `have_activated`, `have_received_variables`, `have_received_headers`
+
+- **GRPC layer** (`Busybee::GRPC`) - Generated protocol buffer classes from the Zeebe 8.8 proto definition for direct Zeebe API access
+
+## [0.0.1] - 2025-12-03
+
+- Initial development, not for release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andy Rusterholz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,214 @@
+# Busybee
+
+**A complete Ruby toolkit for workflow-based orchestration with BPMN, running on Camunda Platform.**
+
+If you're a Ruby shop that needs workflow orchestration, you've probably noticed the gap: Camunda Platform is powerful, but the Ruby ecosystem support is thin. Busybee fills that gap. One gem, one Camunda Cloud account, and you're ready to start building. And when you're ready to scale further, Busybee is ready to grow with you, with battle-proven patterns for large distributed systems.
+
+Busybee provides everything you need to work with Camunda Platform or self-hosted Zeebe from Ruby:
+
+- **Worker Pattern Framework** - Define job handlers as classes with a clean DSL. Busybee handles polling, execution, and lifecycle.
+- **Idiomatic Zeebe Client** - Ruby-native interface with keyword arguments, sensible defaults, and proper exception handling.
+- **RSpec Testing Integration** - Deploy BPMNs, activate jobs, and assert on workflow behavior in your test suite.
+- **Deployment Tools** - CI/CD tooling for deploying BPMN files to your clusters.
+- **Low-Level GRPC Access** - Direct access to Zeebe's protocol buffer API when you need it.
+
+## Roadmap & Availability
+
+| Version | Features | Status |
+|---------|---------|--------|
+| v0.1 | BPMN Testing Tools, GRPC Layer | Available now! |
+| v0.2 | Client, Rails Integration | January 2026 |
+| v0.3 | Worker Pattern & CLI | Early 2026 |
+| v0.4 | Instrumentation Hooks, Deployment Tools | Planned for Early 2026 |
+| v1.0 | Production Polish | Planned for Mid 2026 |
+
+## Installation
+
+Add busybee to your Gemfile:
+
+```ruby
+gem "busybee"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install busybee
+```
+
+## Usage
+
+### Worker Pattern Framework (coming in early 2026)
+
+Define job handlers as Ruby classes. Busybee manages the process lifecycle, the connection to Camunda Cloud, and requesting jobs from Zeebe. If you've used Racecar to build Kafka handlers, or Sidekiq to build background jobs, this should feel very familiar.
+
+> This feature is still being designed. The example shown here is only representative and will change before implementation.
+
+```ruby
+class ProcessOrderWorker < Busybee::Worker
+  type "process-order"
+
+  input :order_id, required: true
+  input :customer_email
+
+  output :confirmation_number
+
+  def perform
+    confirmation = OrderService.process(order_id)
+    complete(confirmation_number: confirmation)
+  end
+end
+```
+
+Planned capabilities:
+
+- Declarative input/output definitions with validation
+- Automatic job activation and completion
+- Configurable timeouts and retry behavior
+- Graceful shutdown on SIGTERM
+- CLI for running workers: `bundle exec busybee work` or similar
+
+### Idiomatic Zeebe Client (coming in January 2026)
+
+A Ruby-native client for Zeebe with keyword arguments, sensible defaults, and proper exception handling.
+
+> This feature is still being designed. The example shown here is only representative and will change before implementation.
+
+```ruby
+client = Busybee::Client.new
+
+# Deploy a workflow
+client.deploy_process("workflows/order-fulfillment.bpmn")
+
+# Start a process instance
+instance_key = client.start_process("order-fulfillment",
+  vars: { order_id: "123", items: ["widget", "gadget"] }
+)
+
+# Publish a message
+client.publish_message("payment-received",
+  correlation_key: "order-123",
+  vars: { amount: 99.99 }
+)
+```
+
+Planned capabilities:
+
+- Connection management with automatic reconnection
+- Multiple credential types (insecure, TLS, OAuth, Camunda Cloud)
+- GRPC error wrapping with preserved cause chains
+- Rails integration via Railtie and `config/busybee.yml`
+- Duration support for timeouts (works with ActiveSupport if present)
+
+### RSpec Testing Integration (available now!)
+
+Deploy processes, create instances, activate jobs, and verify workflow behavior against a real Zeebe instance. A full replacement for the [zeebe_bpmn_rspec](https://github.com/ezcater/zeebe_bpmn_rspec) gem.
+
+#### Setup
+
+```ruby
+# spec/spec_helper.rb
+require "rspec"
+require "busybee/testing"
+
+Busybee::Testing.configure do |config|
+  config.address = "localhost:26500"  # or use ZEEBE_ADDRESS env var
+end
+```
+
+#### Example
+
+```ruby
+RSpec.describe "Order Fulfillment" do
+  let(:process_id) { deploy_process("spec/fixtures/order.bpmn", uniquify: true)[:process_id] }
+
+  it "processes payment and ships order" do
+    with_process_instance(process_id, order_id: "123", total: 99.99) do
+      expect(activate_job("process-payment"))
+        .to have_activated
+        .with_variables(order_id: "123", total: 99.99)
+        .and_complete(payment_id: "pay-456")
+
+      expect(activate_job("prepare-shipment"))
+        .to have_activated
+        .with_variables(payment_id: "pay-456")
+        .and_complete(tracking_number: "TRACK789")
+
+      assert_process_completed!
+    end
+  end
+end
+```
+
+#### Helpers and Matchers
+
+- `deploy_process(path, uniquify:)` - Deploy BPMN files with optional unique IDs for test isolation
+- `with_process_instance(process_id, variables)` - Create instances with automatic cleanup
+- `activate_job(type)` / `activate_jobs(type, max_jobs:)` - Activate jobs for assertions
+- `publish_message(name, correlation_key:, variables:)` - Trigger message catch events
+- `set_variables(scope_key, variables)` - Update process variables
+- `assert_process_completed!` - Verify workflow reached an end event
+- `have_activated`, `have_received_variables`, `have_received_headers` - RSpec matchers
+
+**[Full testing documentation](docs/testing.md)**
+
+### Deployment Tools (coming in early 2026)
+
+CI/CD tooling for deploying BPMN processes to your Zeebe clusters. Version tracking, environment-specific deployments, and pre-deployment validation.
+
+### Low-Level GRPC Access (available now!)
+
+For edge cases where the higher-level abstractions don't cover what you need, busybee exposes the raw GRPC interface to Zeebe. This is a complete drop-in replacement for the now-discontinued [zeebe-client](https://github.com/zeebe-io/zeebe-client-ruby) gem.
+
+```ruby
+require "busybee/grpc"
+
+stub = Busybee::GRPC::Gateway::Stub.new(
+  "localhost:26500",
+  :this_channel_is_insecure
+)
+
+request = Busybee::GRPC::TopologyRequest.new
+response = stub.topology(request)
+puts response.brokers.map(&:host)
+```
+
+Most users won't need this—the Testing module and future Client cover common workflows. See **[GRPC documentation](docs/grpc.md)** for details.
+
+## Ruby Implementation Support
+
+Busybee currently only supports MRI (CRuby). JRuby is not supported because it cannot run C extensions (it would require `grpc-java` with a Ruby wrapper). TruffleRuby's C extension support is experimental and the `grpc` gem does not currently build on it.
+
+If you successfully run busybee on an alternative Ruby implementation, please open an issue. We'd welcome contributions to expand platform support!
+
+## Development
+
+Busybee includes a Docker Compose setup for running Zeebe locally, plus rake tasks for common development workflows.
+
+```bash
+bin/setup              # Install dependencies
+rake zeebe:start       # Start local Zeebe + ElasticSearch
+rake zeebe:health      # Wait for services to be ready
+bundle exec rspec      # Run unit tests
+RUN_INTEGRATION_TESTS=1 bundle exec rspec  # Run all tests including integration
+```
+
+**[Full development guide](docs/development.md)** — Local environment setup, running tests, regenerating GRPC classes, and release procedures.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rusterholz/busybee. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/rusterholz/busybee/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Busybee project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/rusterholz/busybee/blob/main/CODE_OF_CONDUCT.md).

data/docs/grpc.md

@@ -0,0 +1,106 @@
+# Low-Level GRPC Access
+
+The `Busybee::GRPC` module contains generated protocol buffer classes from the Zeebe proto definition. This is the lowest-level interface to Zeebe available in busybee.
+
+## When to Use This
+
+Most users should use the higher-level abstractions:
+
+- **Testing workflows?** Use `Busybee::Testing` (available now)
+- **Building applications?** Use `Busybee::Client` (coming in v0.2)
+- **Processing jobs?** Use `Busybee::Worker` (coming in v0.3)
+
+The GRPC layer is an escape hatch for edge cases where you need direct access to Zeebe APIs that the higher-level abstractions don't expose. Examples:
+
+- Calling RPCs not yet wrapped by the Client (e.g., `MigrateProcessInstance`, `ModifyProcessInstance`)
+- Building custom tooling that needs low-level control
+- Debugging or experimenting with the Zeebe API directly
+
+## Basic Usage
+
+```ruby
+require "busybee/grpc"
+
+# Create a stub (connection to Zeebe gateway)
+stub = Busybee::GRPC::Gateway::Stub.new(
+  "localhost:26500",
+  :this_channel_is_insecure
+)
+
+# Check cluster topology
+request = Busybee::GRPC::TopologyRequest.new
+response = stub.topology(request)
+
+response.brokers.each do |broker|
+  puts "Broker: #{broker.host}:#{broker.port}"
+  broker.partitions.each do |partition|
+    puts "  Partition #{partition.partition_id}: #{partition.role}"
+  end
+end
+```
+
+## Reducing Verbosity
+
+If you're making many GRPC calls, you can include the module to use class names directly:
+
+```ruby
+require "busybee/grpc"
+include Busybee::GRPC
+
+stub = Gateway::Stub.new("localhost:26500", :this_channel_is_insecure)
+
+response = stub.topology(TopologyRequest.new)
+
+request = CreateProcessInstanceRequest.new(
+  bpmn_process_id: "order-fulfillment",
+  variables: { order_id: "123" }.to_json
+)
+instance = stub.create_process_instance(request)
+```
+
+## Available Classes
+
+The GRPC module exposes:
+
+- `Busybee::GRPC::Gateway::Stub` - The gRPC client stub for making calls
+- Request/response classes for each RPC (e.g., `TopologyRequest`, `DeployResourceRequest`, `CreateProcessInstanceRequest`)
+- Enum types and nested message types from the Zeebe proto
+
+## Available RPCs
+
+The Gateway service includes these RPCs:
+
+| RPC | Description |
+|-----|-------------|
+| `Topology` | Get cluster topology (brokers, partitions) |
+| `DeployResource` | Deploy BPMN processes and other resources |
+| `CreateProcessInstance` | Start a new process instance |
+| `CancelProcessInstance` | Cancel a running process instance |
+| `ActivateJobs` | Activate jobs for processing (bounded) |
+| `StreamActivatedJobs` | Stream jobs as they become available (long-lived) |
+| `CompleteJob` | Mark a job as successfully completed |
+| `FailJob` | Mark a job as failed |
+| `ThrowError` | Throw a BPMN error from a job |
+| `PublishMessage` | Publish a message for correlation |
+| `SetVariables` | Update variables on a scope |
+| `ResolveIncident` | Resolve an incident |
+| `UpdateJobRetries` | Update retry count for a job |
+| `UpdateJobTimeout` | Extend or shorten a job's deadline |
+| `BroadcastSignal` | Broadcast a BPMN signal |
+| `ModifyProcessInstance` | Modify a running process instance |
+| `MigrateProcessInstance` | Migrate a process instance to a new version |
+
+See the [Zeebe gRPC API documentation](https://docs.camunda.io/docs/apis-tools/zeebe-api/) for full details on request/response structures.
+
+## Authentication
+
+For local development with an insecure connection:
+
+```ruby
+stub = Busybee::GRPC::Gateway::Stub.new(
+  "localhost:26500",
+  :this_channel_is_insecure
+)
+```
+
+For Camunda Cloud or TLS-secured clusters, you'll need to construct appropriate channel credentials. The upcoming `Busybee::Client` will handle this automatically; at the GRPC level, refer to the [grpc gem documentation](https://grpc.io/docs/languages/ruby/basics/) for credential setup.