busybee 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c005e2f714f3f1ea1b3eedf3d8e7b6ce72ad88fe27cf2a8e84637ca4fe3de281
-  data.tar.gz: cbefb422a412d32143493b8903886e6429f59bd639a3a05de052f89a94be9edb
+  metadata.gz: eeb297a403676c22e7055dbb550d541c6f12fbc29f16caa8550bc625b6265857
+  data.tar.gz: 2a0930162e3b589cf65c85ded384b4b6e2c8100a45da3213c40dac324b5b340d
 SHA512:
-  metadata.gz: e812d00b20c0ff7395b72db6225d57a2adcdee6ad9ecf7381215cd5352b5b034458df6bb3728a3cd25429effee83bc1f85c941dc2f4a7937f86cfb3d64f21688
-  data.tar.gz: 61a813477c650a801a04d6d5ed50dc2a5bbef5686de5690599943a61898d2b77a3d66c52109c037c4e99fcf0cfb02c2393cb9f369cac9a65d3ef9da20a8d9da2
+  metadata.gz: 7ab1f433f8c1266d9a45c966ec4819f6eb1565c00e3013f44f96d3072dc173f50cd41e8c725f588cc9b19026995e0820700bea4e2adb18fb006181ae6a809e27
+  data.tar.gz: b92c2655751b7bf4070c5fa3bd55ea70a0d687f5725786763c55bdb7b470622c5d567b6c74362831f93963c2e639ecae9878a588164a552605e7c16209a314d7

data/CHANGELOG.md

@@ -1,10 +1,36 @@
-## [Unreleased]
+# Changelog
 
-## [0.1.0] - 2025-12-29
+## v0.2.0 (2026-02-05)
+
+Production-ready Client API with Rails integration.
+
+### New Features:
+
+- **Client class** (`Busybee::Client`) - a Ruby-idiomatic wrapper around the Zeebe gRPC API:
+  - Pluggable authentication with four credential types: `Insecure`, `TLS`, `OAuth`, and `CamundaCloud`
+    - Automatic credential type detection from parameters
+  - Almost all GRPC operations, including `deploy_process`, `start_instance`, `cancel_instance`, `publish_message`, `broadcast_signal` `set_variables`, `resolve_incident`, `complete_job`, `fail_job`, `throw_bpmn_error`, `update_job_retries`, `update_job_timeout`
+  - Two job activation methods: `with_each_job` (long-polling), and `open_job_stream` (continuous stream) with Enumerable wrapper class
+  - Rich wrapper class (`Busybee::Job`) for activated jobs:
+    - `variables` and `headers` with indifferent access (string or symbol keys)
+    - Status tracking (`:ready`, `:complete`, `:failed`) to prevent double-completion
+    - Action methods: `complete!`, `fail!`, `throw_bpmn_error!`
+  - Variable serialization handles ActiveRecord or other custom objects
+
+- **Rails integration** - Automatic configuration from `config.x.busybee.*`, works seamlessly with Rails secrets
+  - Defaults to using Rails logger
+  - Structured logs with a `[busybee]` prefix, supporting text or JSON modes
+
+### Breaking Changes:
+
+- **Testing helpers** now use `Busybee.cluster_address` instead of `Busybee::Testing.address`, which has been removed
+- **Testing::Helpers** was refactored for namespace safety and some methods are no longer accessible within specs
+
+## v0.1.0 (2025-12-29)
 
 Initial public release with foundational components for testing BPMN workflows.
 
-### Added
+### New Features:
 
 - **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
@@ -18,6 +44,8 @@ Initial public release with foundational components for testing BPMN workflows.
 
 - **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
+## v0.0.1 (2025-12-03)
+
+- Initial development, not released
+
 
-- Initial development, not for release

data/README.md

@@ -2,9 +2,9 @@
 
 **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.
+If you're a Ruby shop considering workflow orchestration, you might have noticed: 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:
+Busybee provides everything you need to work with Camunda Platform or self-hosted Zeebe in a Ruby world:
 
 - **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.
@@ -17,10 +17,10 @@ Busybee provides everything you need to work with Camunda Platform or self-hoste
 | Version | Features | Status |
 |---------|---------|--------|
 | v0.1 | BPMN Testing Tools, GRPC Layer | Available now! |
-| v0.2 | Client, Rails Integration | January 2026 |
+| v0.2 | Client, Rails Integration | Available now! |
 | 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 |
+| v0.4 | Instrumentation Hooks, Deployment Tools | Mid 2026 |
+| v1.0 | Production Polish | Late 2026 |
 
 ## Installation
 
@@ -74,20 +74,20 @@ Planned capabilities:
 - Graceful shutdown on SIGTERM
 - CLI for running workers: `bundle exec busybee work` or similar
 
-### Idiomatic Zeebe Client (coming in January 2026)
+### Idiomatic Zeebe Client (available now!)
 
 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
+# Connect to Camunda Cloud with environment variables
+# (CAMUNDA_CLIENT_ID, CAMUNDA_CLIENT_SECRET, CAMUNDA_CLUSTER_ID, CAMUNDA_CLUSTER_REGION)
 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",
+instance_key = client.start_instance("order-fulfillment",
   vars: { order_id: "123", items: ["widget", "gadget"] }
 )
 
@@ -96,19 +96,27 @@ client.publish_message("payment-received",
   correlation_key: "order-123",
   vars: { amount: 99.99 }
 )
+
+# Process jobs
+client.with_each_job("send-confirmation") do |job|
+  EmailService.send(job.variables.customer_email)
+  job.complete!(sent_at: Time.now.iso8601)
+end
 ```
 
-Planned capabilities:
+Capabilities:
+
+- Multiple credential types (Insecure, TLS, OAuth, Camunda Cloud) with automatic detection
+- Complete process lifecycle: deploy, start, cancel, set variables, resolve incidents
+- Job operations: activate, complete, fail, throw BPMN errors, streaming
+- Rails integration via Railtie with `config.x.busybee.*` configuration
+- GRPC error wrapping with configurable retry
 
-- 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)
+**[Full client documentation →](docs/client.md)**
 
 ### 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.
+Allows you to unit test your BPMN files. Deploy processes, create instances, activate jobs, and verify workflow behavior against a real Zeebe instance.
 
 #### Setup
 
@@ -117,8 +125,9 @@ Deploy processes, create instances, activate jobs, and verify workflow behavior
 require "rspec"
 require "busybee/testing"
 
-Busybee::Testing.configure do |config|
-  config.address = "localhost:26500"  # or use ZEEBE_ADDRESS env var
+# Optional: defaults to localhost:26500, or set CLUSTER_ADDRESS env var
+Busybee.configure do |config|
+  config.cluster_address = "localhost:26500"
 end
 ```
 
@@ -156,7 +165,7 @@ end
 - `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)**
+**For more info, see our [full testing documentation here](docs/testing.md).**
 
 ### Deployment Tools (coming in early 2026)
 
@@ -166,6 +175,8 @@ CI/CD tooling for deploying BPMN processes to your Zeebe clusters. Version track
 
 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.
 
+> Most users won't need this, as the Testing module, Client class, and Worker pattern cover most common use cases.
+
 ```ruby
 require "busybee/grpc"
 
@@ -179,17 +190,17 @@ 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.
+**For more info, see the [full GRPC documentation here](docs/grpc.md).**
 
 ## 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.
+Busybee currently only supports MRI (CRuby). This is due to the state of `grpc` support on other implementations. 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!
+If you successfully run busybee on an alternative Ruby implementation, please open a GitHub issue to let us know! 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.
+Busybee includes a Docker Compose setup for running Zeebe locally, plus rake tasks for common development workflows:
 
 ```bash
 bin/setup              # Install dependencies
@@ -199,7 +210,7 @@ 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.
+**The full development guide for contributors [is available here](docs/development.md),** including local environment setup, running tests, regenerating GRPC classes, and release procedures.
 
 ## Contributing
 

data/docs/client/quick_start.md

@@ -0,0 +1,279 @@
+# Busybee::Client Quick Start
+
+This tutorial gets you from zero to a deployed process and running instance in about 10 minutes. By the end, you'll have:
+
+1. A Zeebe environment (local or Camunda Cloud)
+2. Busybee configured with appropriate credentials
+3. A BPMN process deployed
+4. A running process instance
+
+## Prerequisites
+
+Before starting, you'll need:
+
+- Ruby 3.2+
+- A Zeebe environment (see "Choose Your Environment" below)
+- A BPMN process file (we'll create a simple one, or you can use an existing one)
+
+## Step 1: Install Busybee
+
+Add to your Gemfile:
+
+```ruby
+gem "busybee"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Step 2: Choose Your Environment
+
+Busybee supports both local Zeebe (typical for development) and Camunda Cloud (recommended for production).
+
+### Option A: Local Zeebe
+
+For local development, you can run Zeebe using Docker. The simplest setup is:
+
+```bash
+docker run -d --name zeebe -p 26500:26500 camunda/zeebe:latest
+```
+
+For a more complete setup with Operate (the web UI for monitoring workflows), see the [Camunda Docker Compose documentation](https://docs.camunda.io/docs/self-managed/setup/deploy/local/docker-compose/).
+
+When using local Zeebe, you'll use insecure (non-TLS) connections.
+
+### Option B: Camunda Cloud
+
+Camunda Cloud is Camunda's managed SaaS offering. To get started:
+
+1. Create a free account at [camunda.io](https://camunda.io/)
+2. Create a cluster (the free tier includes a development cluster)
+3. Create API credentials:
+   - Go to your cluster's "API" tab
+   - Click "Create new client"
+   - Select "Zeebe" scope
+   - Save the credentials (you'll need: Client ID, Client Secret, Cluster ID, and Region)
+
+For detailed setup instructions, see [Camunda Cloud Getting Started](https://docs.camunda.io/docs/guides/getting-started/).
+
+## Step 3: Configure Credentials
+
+A Busybee::Client needs to know where to find the Zeebe cluster and how to authenticate to it. There are many ways to provide or configure this information, which you can find in the [Client reference](../client.md). For the purpose of this tutorial, we'll pass this information directly to `new`:
+
+### For Local Zeebe
+
+```ruby
+require "busybee"
+
+client = Busybee::Client.new(
+  cluster_address: "localhost:26500",
+  insecure: true
+)
+```
+
+### For Camunda Cloud
+
+```ruby
+require "busybee"
+
+client = Busybee::Client.new(
+  client_id: "your client ID",
+  client_secret: "your client secret",
+  cluster_id: "your cluster ID (typically a UUID)",
+  region: "your cluster region (e.g. 'bru-2')"
+)
+```
+
+### Rails Configuration
+
+In a Rails app, configure via `config/application.rb` or an initializer:
+
+```ruby
+# config/application.rb or config/initializers/busybee.rb
+Rails.application.configure do
+  config.x.busybee.credential_type = :camunda_cloud
+  config.x.busybee.cluster_address = ENV["CLUSTER_ADDRESS"]  # for local/TLS
+  # OAuth credentials are passed to Client.new, not configured globally
+end
+```
+
+## Step 4: Create a BPMN Process
+
+BPMN (Business Process Model and Notation) files define your workflows. You can create them using:
+
+- **Camunda Modeler** (desktop app) - Download from [camunda.com/download/modeler](https://camunda.com/download/modeler/)
+- **Camunda Cloud Web Modeler** - Available in your Camunda Cloud console
+- **Any BPMN 2.0 editor** - Busybee works with standard BPMN files
+
+Here's a minimal example you can save as `simple_process.bpmn`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+                  xmlns:zeebe="http://camunda.org/schema/zeebe/1.0"
+                  id="Definitions_1"
+                  targetNamespace="http://bpmn.io/schema/bpmn">
+  <bpmn:process id="hello-world" name="Hello World" isExecutable="true">
+    <bpmn:startEvent id="Start">
+      <bpmn:outgoing>Flow1</bpmn:outgoing>
+    </bpmn:startEvent>
+    <bpmn:endEvent id="End">
+      <bpmn:incoming>Flow1</bpmn:incoming>
+    </bpmn:endEvent>
+    <bpmn:sequenceFlow id="Flow1" sourceRef="Start" targetRef="End"/>
+  </bpmn:process>
+</bpmn:definitions>
+```
+
+This creates a process that starts and immediately ends. Real processes would include service tasks, gateways, and other BPMN elements.
+
+For more about BPMN modeling, see the [Camunda BPMN documentation](https://docs.camunda.io/docs/components/modeler/bpmn/).
+
+## Step 5: Deploy the Process
+
+Deploy your BPMN file to Zeebe:
+
+```ruby
+# Deploy a single file
+result = client.deploy_process("simple_process.bpmn")
+# => { "hello-world" => 2251799813685249 }
+
+# The result maps process IDs to definition keys
+process_id = result.keys.first       # => "hello-world"
+definition_key = result.values.first # => 2251799813685249
+
+# Deploy multiple files at once
+result = client.deploy_process("order.bpmn", "payment.bpmn")
+# => { "order-process" => 123, "payment-process" => 456 }
+```
+
+The returned hash maps BPMN process IDs (the `id` attribute on the `<bpmn:process>` element) to process definition keys (unique identifiers assigned by Zeebe).
+
+## Step 6: Start a Process Instance
+
+Now start an instance of your deployed process:
+
+```ruby
+# Start a basic instance
+instance_key = client.start_instance("hello-world")
+# => 2251799813685300
+
+# Start with variables
+instance_key = client.start_instance("order-process",
+  vars: { order_id: "ORD-123", customer: "Alice", total: 99.99 }
+)
+
+# Start a specific version (not the latest)
+instance_key = client.start_instance("order-process",
+  vars: { order_id: "ORD-456" },
+  version: 2
+)
+```
+
+The returned `instance_key` is the unique identifier for this process instance.
+
+## Putting It All Together
+
+Here's a complete example:
+
+```ruby
+require "busybee"
+
+# Configure for local development
+client = Busybee::Client.new(insecure: true)
+
+# Deploy the process
+deployments = client.deploy_process("workflows/order-fulfillment.bpmn")
+puts "Deployed: #{deployments.keys.join(', ')}"
+
+# Start an instance
+instance_key = client.start_instance("order-fulfillment",
+  vars: {
+    order_id: "ORD-2024-001",
+    items: ["widget", "gadget"],
+    total: 149.99
+  }
+)
+puts "Started instance: #{instance_key}"
+
+# You can now monitor this instance in Operate (web UI)
+# or interact with it via messages and signals
+```
+
+## What's Next?
+
+Now that you have a running process instance, you might want to:
+
+- **Cancel an instance**: `client.cancel_instance(instance_key)`
+- **Publish a message** to trigger a message catch event: `client.publish_message("payment-received", correlation_key: "ORD-2024-001", vars: { amount: 149.99 })`
+- **Broadcast a signal** to all waiting instances: `client.broadcast_signal("system-shutdown")`
+- **Set variables** on a running instance: `client.set_variables(instance_key, vars: { status: "approved" })`
+
+See the API Reference section below for complete documentation of all available methods.
+
+# Credential Types
+
+Busybee supports four credential types for different environments:
+
+| Type | Use Case | TLS | Authentication |
+|------|----------|-----|----------------|
+| `:insecure` | Local development, Docker, CI | No | None |
+| `:tls` | Self-hosted with TLS | Yes | Server cert only |
+| `:oauth` | Self-hosted with OAuth | Yes | OAuth2 client credentials |
+| `:camunda_cloud` | Camunda Cloud SaaS | Yes | OAuth2 (auto-configured) |
+
+## Insecure Credentials
+
+For local development with no TLS or authentication:
+
+```ruby
+client = Busybee::Client.new(insecure: true)
+
+# Or with explicit address
+client = Busybee::Client.new(insecure: true, cluster_address: "zeebe:26500")
+```
+
+## TLS Credentials
+
+For self-hosted Zeebe with TLS but no client authentication:
+
+```ruby
+client = Busybee::Client.new(
+  cluster_address: "zeebe.example.com:443",
+  certificate_file: "/path/to/ca.crt"  # Optional: custom CA certificate
+)
+```
+
+## OAuth Credentials
+
+For self-hosted Zeebe with OAuth2 authentication:
+
+```ruby
+client = Busybee::Client.new(
+  cluster_address: "zeebe.example.com:443",
+  token_url: "https://auth.example.com/oauth/token",
+  client_id: "my-client-id",
+  client_secret: "my-client-secret",
+  audience: "zeebe.example.com"
+)
+```
+
+## Camunda Cloud Credentials
+
+For Camunda Cloud, the cluster address and OAuth configuration are derived automatically:
+
+```ruby
+client = Busybee::Client.new(
+  client_id: ENV["CAMUNDA_CLIENT_ID"],
+  client_secret: ENV["CAMUNDA_CLIENT_SECRET"],
+  cluster_id: ENV["CAMUNDA_CLUSTER_ID"],
+  region: ENV["CAMUNDA_CLUSTER_REGION"]  # e.g., "bru-2", "us-east-1"
+)
+```
+
+# Next Steps
+
+For complete API documentation, error handling details, and advanced usage, see the [Client documentation](../client.md).