beez 0.1.0 → 0.2.0

data/README.md

@@ -1,76 +1,104 @@
-# Beez
+<h1 align="center">
+  <br>
+  <a href="https://github.com/gottfrois/beez"><img src="https://github.com/gottfrois/beez/blob/master/assets/images/bee.png?raw=true" alt="Beez" width="200"></a>
+  <br>
+  Beez
+</h1>
 
-Simple, efficient ruby workers for [Zeebe](https://zeebe.io/) business processes.
+<h4 align="center">
+  Simple, efficient ruby workers for <a href="https://zeebe.io/" target="_blank">Zeebe</a>.
+</h4>
 
-Beez uses threads to handle many jobs at the same time in the same process. It
-does not require Rails but will integrate tightly with Rails to start working
-with workflows.
+<p align="center">
+  <a href="https://badge.fury.io/rb/beez"><img src="https://badge.fury.io/rb/beez.svg" alt="Gem Version" height="18"></a>
+</p>
 
-## Disclaimer
+<p align="center">
+  <a href="#features-">Features</a> •
+  <a href="#disclaimer-%EF%B8%8F">Disclaimer</a> •
+  <a href="#getting-started-">Getting Started</a> •
+  <a href="#usage-">Usage</a> •
+  <a href="#configuration-">Configuration</a> •
+  <a href="#example-">Example</a> •
+  <a href="#license-">License</a> •
+  <a href="#credits-">Credits</a>
+</p>
+<br>
 
-Beez is currently **not production ready**. It hasn't been tested under a
-production application yet. Beside, the gem is missing all its specs at the
-moment.
+<p align="center">
+  <img src="https://github.com/gottfrois/beez/blob/master/assets/images/zeebe-operate.jpeg?raw=true" alt="Zeebe Operate">
+  <em>Beez lets you consume Zeebe workflows like this one!</em>
+</p>
 
-I'm working on this project on my free time. If you want to help, be my guest! I
-love the concepts behind Zeebe, this is why I bootstraped this library.
+## Features ✨
 
-Please bare with me while it matures.
+- Beez integrates with [Zeebe](https://zeebe.io/), a free and source-available workflow engine for microservices orchestration
+- Beez integrates with you Rails application
+- Beez runs your workers asynchronously
+- Beez automatically marks your jobs as failures uppon Ruby exceptions
+- Beez has very few dependencies
 
-## Installation
+## Disclaimer ⚠️
 
-Add this line to your application's Gemfile:
+- Beez is currently a pre-release
+- Beez has currently **not being tested in production**
+- Beez is currently lacking unit tests, any help is welcome!
 
-```ruby
-gem 'beez'
-```
+## Getting Started 🎓
 
-And then execute:
+These instructions will help you get started with [Zeebe](https://zeebe.io/)
+and Beez. [Zeebe](https://zeebe.io/) already provides an extensive [documentation](https://docs.zeebe.io/)
+I highly suggest you to check it out before.
 
-    $ bundle
+### Prerequisites ☔️
 
-Or install it yourself as:
+- You need [Zeebe up and running](https://docs.zeebe.io/introduction/install.html)
+- Ruby >= 2.5 & < 2.7
+- Rails >= 4 (optional)
 
-    $ gem install beez
+### How It Works ⚙️
 
-## Usage
+Workflows are flowchart-like blueprints that define the orchestration of tasks.
+Every task represents a piece of business logic such that the ordered execution
+produces a meaningful result.
 
-The following guide assumes you already have the Zeebe stack up and running and
-a workflow deployed. If not, please head to [Zeebe official documentation](https://docs.zeebe.io/).
+Beez lets you define job workers as Ruby classes which is your implementation of
+the business logic required to complete a task.
 
-We will be taking the classic Order Process workflows as an example.
+Running a workflow then requires two steps:
 
-![Order Process](https://docs.zeebe.io/getting-started/img/tutorial-3.0-complete-workflow.png)
+1. Submitting the workflow to Zeebe
+2. Creating job workers that can request jobs from Zeebe and complete them
 
-### Rails
+### Installation ☕️
 
-1. Create the workers anywhere you want in your Rails application:
+Add this line to your application's Gemfile:
 
 ```ruby
-class InitiatePaymentWorker
-  include ::Beez::Worker
+gem 'beez', '~> 0.1'
+```
 
-  type "initiate-payment"
+And then execute:
 
-  def process(job)
-    # do something
-  end
-end
+    $ bundle
 
-class ShipWithInsuranceWorker
-  include ::Beez::Worker
+Or install it yourself as:
 
-  type "ship-with-insurance"
+    $ gem install beez
 
-  def process(job)
-    # do something
-  end
-end
+### Usage 🎆
+
+Let's start by creating some workers. In your Rails application, those would be
+defined under `app/jobs` or `app/workers` for example.
 
-class ShipWithoutInsuranceWorker
+```ruby
+class MyWorker
   include ::Beez::Worker
 
-  type "ship-without-insurance"
+  type "service-task-name"
+  max_jobs_to_activate 5 # optional, default to 1
+  poll_interval 1 # optional, default to 5
+  timeout 30 # optional, default to 30
 
   def process(job)
     # do something
@@ -78,9 +106,17 @@ class ShipWithoutInsuranceWorker
 end
 ```
 
-*You can find the available properties of the `job` variable [here](https://github.com/zeebe-io/zeebe-client-ruby/blob/master/lib/zeebe/client/proto/gateway_pb.rb#L20-L32).*
+Each worker automatically polls for new jobs at `poll_interval` interval. They
+are configured to accepts a `max_jobs_to_activate` jobs at the same time.
+Workers have exactly `timeout` seconds to process the job before the broker
+consider it as expired and schedule it to another worker.
+
+The `process` instance method receives a `job` instance which holds the job's
+attributes such as the `variables` the job received. You can get the complete
+list of attributes available [here](https://github.com/zeebe-io/zeebe-client-ruby/blob/master/lib/zeebe/client/proto/gateway_pb.rb#L20-L32)
 
-2. Start Beez from the root of your Rails application:
+Assuming you have [Zeebe](https://zeebe.io/) up and running, simply start Beez
+from the root of your Rails application:
 
 ```sh
 bundle exec beez
@@ -88,35 +124,69 @@ bundle exec beez
 
 That's it.
 
-### Plain Ruby
+### Configuration 🔧
+
+Beez comes configured with global sane defaults but you can always
+overrides them using either env variables in some cases or the `configure`
+block:
+
+```ruby
+# Here are the global defaults already configured for you
+Beez.configure do |config|
+  config.env = ENV["APP_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+  config.logger = Logger.new($stdout)
+  config.require = "."
+  config.timeout = 30
+  config.zeebe_url = ENV['ZEEBE_URL'] || 'localhost:26500'
+end
+```
+
+### Example 📘
 
-You can skip loading the Rails application entirely by specifying workers within
-a ruby file when starting Beez:
+Let's get the full picture by deploying a dummy [Order Process](https://github.com/gottfrois/beez/blob/master/bpmn/order-process.bpmn) workflow to Zeebe and
+define simple workers as plain Ruby objects.
+
+![Order Process](https://github.com/gottfrois/beez/blob/master/assets/images/order-process.png?raw=true)
+
+1. Start Zeebe and Zeebe Operate:
 
 ```sh
-bundle exec beez -r ./workers.rb
+git clone https://github.com/camunda-cloud/camunda-cloud-get-started/
+docker-compose up
 ```
 
-*Check out our examples in `examples/` folder.*
+2. Head to [http://localhost:8080](http://localhost:8080)
 
-### Zeebe Client
+- Login: `demo`
+- Password: `demo`
 
-You can interact with Zeebe and your workflows directly from Beez:
+3. Start Beez using our example workers located at [`examples/workers.rb`](https://github.com/gottfrois/beez/blob/master/examples/workers.rb):
 
-```ruby
-client = Beez.client
+```sh
+beez --timeout 5 --require ./examples/workers.rb
+```
 
-# Deploys a new version of the Order Process workflow
-client.deploy_workflow(name: "order-process", type: :BPMN, definition: File.read('./bnmn/order-process.bpmn'))
+4. Start an `irb` session:
 
-# Creates a new Order Process workflow instance
-client.create_workflow_instance(bpmnProcessId: "order-process", version: 1, variables: { orderId: "1234", orderValue: 94 }.to_json)
+```sh
+irb -r beez
+```
+
+5. Interact with Zeebe directly from the gem:
 
-# Publishes a business message
-client.publish_message(name: "payment-received", correlationKey: "1234")
+```ruby
+2.6.6 :001 > # Deploy a process to Zeebe
+2.6.6 :002 > Beez.client.deploy_process(processes: [name: "order-process", definition: File.read('/path/to/beez/bpmn/order-process.bpmn')])
+2.6.6 :003 > # Create a new instance of this process
+2.6.6 :004 > Beez.client.create_process_instance(bpmnProcessId: "order-process", version: 1, variables: { orderId: "1234", orderValue: 94 }.to_json)
+2.6.6 :005 > # Watch Beez automatically executing the first task!
+2.6.6 :006 > # Publish a business message to simulate a payment received event
+2.6.6 :007 > Beez.client.publish_message(name: "payment-received", correlationKey: "1234")
 ```
 
-*Check out all the available commands in `lib/beez/client.rb`.*
+That's it!
+
+_Check out all the available commands in [`lib/beez/client.rb`](https://github.com/gottfrois/beez/blob/master/lib/beez/client.rb)._
 
 ## Development
 
@@ -124,16 +194,16 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-## Contributing
+## Contributing 🤝
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/gottfrois/beez.
 
-## License
+## License 📜
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Thanks
+## Credits 👏
 
-I would like to thank you the authors and contributors behind
-[Sidekiq](https://github.com/mperham/sidekiq) on which I have taken lots of good
-ideas to build this gem.
+- The [Sidekiq](https://github.com/mperham/sidekiq) authors and contributors for
+  their inspirational codebase which helped me to build this gem
+- [Logo vector created by raftel - www.freepik.com](https://www.freepik.com/free-photos-vectors/logo)

data/Rakefile

@@ -1,5 +1,5 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 

data/beez.gemspec

@@ -1,36 +1,39 @@
 require_relative 'lib/beez/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "beez"
+  spec.name          = 'beez'
   spec.version       = Beez::VERSION
-  spec.authors       = ["Pierre-Louis Gottfrois"]
-  spec.email         = ["pierrelouis.gottfrois@gmail.com"]
+  spec.authors       = ['Pierre-Louis Gottfrois']
+  spec.email         = ['pierrelouis.gottfrois@gmail.com']
 
-  spec.summary       = %q{Simple, efficient ruby workers for Zeebe business processes.}
-  spec.description   = %q{Simple, efficient ruby workers for Zeebe business processes.}
-  spec.homepage      = "https://github.com/gottfrois/beez"
-  spec.license       = "MIT"
-  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+  spec.summary       = 'Simple, efficient ruby workers for Zeebe business processes.'
+  spec.description   = 'Simple, efficient ruby workers for Zeebe business processes.'
+  spec.homepage      = 'https://github.com/gottfrois/beez'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
 
-  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
-  spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/gottfrois/beez"
-  spec.metadata["changelog_uri"] = "https://github.com/gottfrois/beez/CHANGELOG.md"
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/gottfrois/beez'
+  spec.metadata['changelog_uri'] = 'https://github.com/gottfrois/beez/CHANGELOG.md'
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_dependency "zeebe-client", "~> 0.7"
-  spec.add_dependency "concurrent-ruby", "~> 1.0"
+  spec.add_dependency 'concurrent-ruby', '~> 1.0'
+  spec.add_dependency 'zeebe-client', '~> 0.7'
 
-  spec.add_development_dependency "pry"
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency 'bundler'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'rubocop-rake', '~> 0.6'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.0'
 end

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
-require "bundler/setup"
-require "beez"
+require 'bundler/setup'
+require 'beez'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +10,5 @@ require "beez"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/examples/workers.rb

@@ -1,17 +1,16 @@
-require "beez"
+require 'beez'
 
 module Workers
   class InitiatePaymentWorker
     include ::Beez::Worker
 
-    type "initiate-payment"
-    max_jobs_to_activate 5
+    type 'initiate-payment'
+    max_jobs_to_activate 20
     poll_interval 1
     timeout 30
 
-    def process(job)
-      rand(35).times do |i|
-        logger.info "Processing job #{job.type} #{job.key} by waiting #{i}s"
+    def process(_job)
+      rand(5).times do |_i|
         sleep 1
       end
     end
@@ -20,13 +19,12 @@ module Workers
   class ShipWithInsuranceWorker
     include ::Beez::Worker
 
-    type "ship-with-insurance"
+    type 'ship-with-insurance'
     max_jobs_to_activate 5
     poll_interval 1
 
-    def process(job)
-      rand(35).times do |i|
-        logger.info "Processing job #{job.type} #{job.key} by waiting #{i}s"
+    def process(_job)
+      rand(5).times do |_i|
         sleep 1
       end
     end
@@ -35,13 +33,14 @@ module Workers
   class ShipWithoutInsuranceWorker
     include ::Beez::Worker
 
-    type "ship-without-insurance"
+    type 'ship-without-insurance'
     max_jobs_to_activate 5
     poll_interval 1
 
     def process(job)
-      rand(35).times do |i|
-        logger.info "Processing job #{job.type} #{job.key} by waiting #{i}s"
+      raise ArgumentError, "orderValue can't be < 10" if JSON.parse(job.variables)['orderValue'].to_i < 10
+
+      rand(5).times do |_i|
         sleep 1
       end
     end

data/exe/beez

@@ -1,14 +1,15 @@
 #!/usr/bin/env ruby
-require "bundler/setup"
-require "beez/cli"
+require 'bundler/setup'
+require 'beez/cli'
 
 begin
   cli = ::Beez::CLI.instance
   cli.parse
   cli.run
-rescue => e
+rescue StandardError => e
   raise e if $DEBUG
-  STDERR.puts e.message
-  STDERR.puts e.backtrace.join("\n")
+
+  warn e.message
+  warn e.backtrace.join("\n")
   exit 1
 end

data/lib/beez/cli.rb

@@ -38,83 +38,88 @@ module Beez
       option_parser.parse!(argv)
     end
 
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/BlockLength
     def option_parser
       OptionParser.new.tap do |p|
-        p.on "-e", "--env ENV", "Application environment" do |arg|
+        p.on '-e', '--env ENV', 'Application environment' do |arg|
           config.env = arg
         end
 
-        p.on "-r", "--require [PATH|DIR]", "Location of Rails application with workers or file to require" do |arg|
+        p.on '-r', '--require [PATH|DIR]', 'Location of Rails application with workers or file to require' do |arg|
           if !File.exist?(arg) ||
-              (File.directory?(arg) && !File.exist?("#{arg}/config/application.rb"))
+             (File.directory?(arg) && !File.exist?("#{arg}/config/application.rb"))
             raise ArgumentError, "#{arg} is not a ruby file nor a rails application"
           else
             config.require = arg
           end
         end
 
-        p.on "-t", "--timeout NUM", "Shutdown timeout" do |arg|
+        p.on '-t', '--timeout NUM', 'Shutdown timeout' do |arg|
           timeout = Integer(arg)
-          raise ArgumentError, "timeout must be a positive integer" if timeout <= 0
+          raise ArgumentError, 'timeout must be a positive integer' if timeout <= 0
+
           config.timeout = timeout
         end
 
-        p.on "-v", "--verbose", "Print more verbose output" do |arg|
+        p.on '-v', '--verbose', 'Print more verbose output' do |_arg|
           ::Beez.logger.level = ::Logger::DEBUG
         end
 
-        p.on "-V", "--version", "Print version and exit" do |arg|
+        p.on '-V', '--version', 'Print version and exit' do |_arg|
           puts "Beez #{::Beez::VERSION}"
           exit(0)
         end
 
-        p.banner = "Usage: beez [options]"
-        p.on_tail "-h", "--help", "Show help" do
+        p.banner = 'Usage: beez [options]'
+        p.on_tail '-h', '--help', 'Show help' do
           puts p
 
           exit(1)
         end
       end
     end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/BlockLength
 
+    # rubocop:disable Metrics/AbcSize
     def boot
-      ENV["RACK_ENV"] = ENV["RAILS_ENV"] = config.env
-
-      if File.directory?(config.require)
-        require 'rails'
-        if ::Rails::VERSION::MAJOR < 4
-          raise "Beez does not supports this version of Rails"
-        else
-          require File.expand_path("#{config.require}/config/environment.rb")
-          logger.info "Booted Rails #{::Rails.version} application in #{config.env} environment"
-        end
-      else
-        require config.require
-      end
+      ENV['RACK_ENV'] = ENV['RAILS_ENV'] = config.env
+
+      require config.require and return unless File.directory?(config.require)
+
+      require 'rails'
+      raise 'Beez does not supports this version of Rails' if ::Rails::VERSION::MAJOR < 4
+
+      require File.expand_path("#{config.require}/config/environment.rb")
+      logger.info "Booted Rails #{::Rails.version} application in #{config.env} environment"
     end
+    # rubocop:enable Metrics/AbcSize
 
+    # rubocop:disable Metrics/AbcSize
     def launch(self_read)
       @launcher = ::Beez::Launcher.new
 
-      if config.env == "development" && $stdout.tty?
-        logger.info "Starting processing, hit Ctrl-C to stop"
-      end
+      logger.info 'Starting processing, hit Ctrl-C to stop' if config.env == 'development' && $stdout.tty?
 
       begin
         launcher.start
 
-        while readable_io = IO.select([self_read])
+        while (readable_io = IO.select([self_read]))
           signal = readable_io.first[0].gets.strip
           handle_signal(signal)
         end
       rescue Interrupt
-        logger.info "Shutting down"
+        logger.info 'Shutting down'
         launcher.stop
-        logger.info "Bye!"
+        logger.info 'Bye!'
 
         exit(0)
       end
     end
+    # rubocop:enable Metrics/AbcSize
 
     def handle_signal(signal)
       handler = signal_handlers[signal]
@@ -127,8 +132,8 @@ module Beez
 
     def signal_handlers
       {
-        "INT" => ->(cli) { raise Interrupt },
-        "TERM" => ->(cli) { raise Interrupt },
+        'INT' => ->(_cli) { raise Interrupt },
+        'TERM' => ->(_cli) { raise Interrupt }
       }
     end