operaton-bpm-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 74b372ece74dbf5d488be16d79062fd5dc13c3d513704a992b60e5e9e267ffd2
+  data.tar.gz: bf39b3e8e4dc77fb7feb41445e4745945f9894f4de58e466a5f03831d0bd0290
+SHA512:
+  metadata.gz: 159410691b053c0ad712df52d59151fc85bb6b6c4f6d0c22b854451a63b145bb46b997f6f5cc3c9193c39dc1ee8e8800ea2c9ee9c1a225301289bc66f0b743d4
+  data.tar.gz: 930f1a568192d5eae7e895703b62abfe823d19d2b990efbde7feec89eb66c9639841da9393d3d084cfd9823d6452b7cf829ec18070fe0d924d6ee10350f95072

data/README.md

@@ -0,0 +1,134 @@
+# Operaton External Task Client for Ruby
+
+A faithful Ruby recreation of the [Operaton](https://github.com/operaton/operaton)
+Java external task client (`org.operaton.bpm.client`). The class structure,
+method contract, defaults, validation rules, REST payloads, and error handling
+mirror the Java implementation one-to-one; names are translated from Java
+camelCase to Ruby snake_case.
+
+```
+org.operaton.bpm.client              -> Operaton::Bpm::Client
+org.operaton.bpm.client.impl         -> Operaton::Bpm::Client::Impl
+org.operaton.bpm.client.task         -> Operaton::Bpm::Client::Task
+org.operaton.bpm.client.topic        -> Operaton::Bpm::Client::Topic
+org.operaton.bpm.client.backoff      -> Operaton::Bpm::Client::Backoff
+org.operaton.bpm.client.interceptor  -> Operaton::Bpm::Client::Interceptor
+org.operaton.bpm.client.variable     -> Operaton::Bpm::Client::Variable
+org.operaton.bpm.engine.variable     -> Operaton::Bpm::Engine::Variable (shim)
+```
+
+Exception classes from `org.operaton.bpm.client.exception` live directly under
+`Operaton::Bpm::Client` (`BadRequestException`, `NotFoundException`,
+`EngineException`, `ConnectionLostException`, `UnknownHttpErrorException`,
+`ValueMapperException`, ...).
+
+## Usage
+
+```ruby
+require "operaton-bpm-client"
+
+client = Operaton::Bpm::Client::ExternalTaskClient.create
+  .base_url("http://localhost:8080/engine-rest")
+  .worker_id("my-worker")                # optional; defaults to hostname + UUID
+  .max_tasks(10)                         # default 10
+  .lock_duration(20_000)                 # default 20s (milliseconds)
+  .async_response_timeout(30_000)        # optional long polling
+  .add_interceptor(
+    Operaton::Bpm::Client::Interceptor::Auth::BasicAuthProvider.new("demo", "demo")
+  )
+  .build                                 # starts fetching immediately
+
+subscription = client.subscribe("invoice-topic")
+  .lock_duration(10_000)
+  .process_definition_key("invoice")
+  .handler do |task, service|
+    amount = task.variable("amount")
+
+    if amount.nil?
+      service.handle_bpmn_error(task, "MISSING_AMOUNT")
+    elsif amount.negative?
+      service.handle_failure(task, "negative amount", nil, (task.retries || 3) - 1, 5_000)
+    else
+      service.complete(task, { "approved" => true })
+    end
+  end
+  .open
+
+sleep
+
+# later:
+subscription.close
+client.stop
+```
+
+Like the Java client, `create` returns a fluent `ExternalTaskClientBuilder`,
+`build` validates the configuration and (unless `disable_auto_fetching` was
+called) starts the `TopicSubscriptionManager` polling thread, and `subscribe`
+returns a fluent `TopicSubscriptionBuilder` whose `open` activates the
+subscription. Handlers may be blocks, lambdas, or objects responding to
+`execute(task, service)`.
+
+## Typed variables
+
+The engine's typed value API is recreated under `Operaton::Bpm::Engine::Variable`
+and extended by `ClientValues`:
+
+```ruby
+Variables = Operaton::Bpm::Engine::Variable::Variables
+ClientValues = Operaton::Bpm::Client::Variable::ClientValues
+
+service.complete(task, {
+  "count"    => 3,                                     # -> Integer
+  "big"      => 2**40,                                 # -> Long
+  "rate"     => 0.19,                                  # -> Double
+  "ok"       => true,                                  # -> Boolean
+  "when"     => Time.now,                              # -> Date
+  "payload"  => { "items" => [1, 2, 3] },              # -> Object (application/json)
+  "explicit" => Variables.long_value(5),               # force Long
+  "raw"      => Variables.byte_array_value("\x00\x01"),# -> Bytes (base64)
+  "doc"      => ClientValues.json_value('{"a":1}'),    # -> Json
+  "xml"      => ClientValues.xml_value("<a/>"),        # -> Xml
+})
+
+task.variable("payload")            # deserialized value
+task.variable_typed("payload")      # ObjectValue (lazily deserialized)
+task.all_variables                  # Hash of plain values
+task.all_variables_typed            # VariableMap of typed values
+```
+
+File variables are received as deferred values whose content is fetched from
+the engine on first access, mirroring `DeferredFileValue`.
+
+## Deviations from the Java client
+
+Necessary adaptations to the Ruby ecosystem; everything else follows the Java
+source:
+
+- **HTTP**: `Net::HTTP` replaces Apache HttpClient. `customize_http_client`
+  accepts a block invoked with the `Net::HTTP` instance of each request.
+- **JSON**: Ruby's `json` replaces Jackson. Object values serialize any
+  JSON-mappable Ruby value; `objectTypeName` records the Ruby class name.
+- **Date format**: configured as a Ruby `strftime` pattern; the default
+  `"%Y-%m-%dT%H:%M:%S.%L%z"` matches the Java default
+  `"yyyy-MM-dd'T'HH:mm:ss.SSSZ"`.
+- **SPI**: `java.util.ServiceLoader` is replaced by explicit registries
+  (`Spi::DataFormatProvider.register`, `Spi::DataFormatConfigurator.register`).
+  The JSON data format is registered by default; the Java-serialization and
+  DOM/XML object data formats have no Ruby equivalent (string-typed `xml`
+  values are fully supported).
+- **Overloads**: Java method overloads collapse into single Ruby methods that
+  accept either an `ExternalTask` or an id, with optional trailing arguments.
+- **`useCreateTime(true)`**: the Java implementation appends the same ordering
+  property twice (producing a duplicated sorting entry in the request); the
+  Ruby port configures it once.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+The spec suite covers builder validation, variable serialization round-trips,
+every REST endpoint payload, HTTP error translation, interceptors, backoff
+strategies, and the polling/dispatch loop (84 examples).

data/lib/operaton/bpm/client/backoff/backoff_strategy.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Operaton
+  module Bpm
+    module Client
+      module Backoff
+        # Mirrors org.operaton.bpm.client.backoff.BackoffStrategy
+        module BackoffStrategy
+          def reconfigure(external_tasks)
+            raise NotImplementedError, "#{self.class} must implement #reconfigure"
+          end
+
+          def calculate_backoff_time
+            raise NotImplementedError, "#{self.class} must implement #calculate_backoff_time"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/backoff/error_aware_backoff_strategy.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "backoff_strategy"
+
+module Operaton
+  module Bpm
+    module Client
+      module Backoff
+        # Mirrors org.operaton.bpm.client.backoff.ErrorAwareBackoffStrategy.
+        # Implementations receive the exception (or nil) of the last
+        # fetch-and-lock attempt in addition to the fetched tasks.
+        module ErrorAwareBackoffStrategy
+          include BackoffStrategy
+
+          def reconfigure(external_tasks, exception = nil)
+            raise NotImplementedError, "#{self.class} must implement #reconfigure"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/backoff/exponential_backoff_strategy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "backoff_strategy"
+
+module Operaton
+  module Bpm
+    module Client
+      module Backoff
+        # Mirrors org.operaton.bpm.client.backoff.ExponentialBackoffStrategy
+        class ExponentialBackoffStrategy
+          include BackoffStrategy
+
+          def initialize(init_time = 500, factor = 2, max_time = 60_000)
+            @init_time = init_time
+            @factor = factor
+            @level = 0
+            @max_time = max_time
+          end
+
+          def reconfigure(external_tasks)
+            if external_tasks.empty?
+              @level += 1
+            else
+              @level = 0
+            end
+          end
+
+          def calculate_backoff_time
+            return 0 if @level.zero?
+
+            backoff_time = (@init_time * (@factor**(@level - 1))).to_i
+            [backoff_time, @max_time].min
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/backoff/exponential_error_backoff_strategy.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "error_aware_backoff_strategy"
+
+module Operaton
+  module Bpm
+    module Client
+      module Backoff
+        # Mirrors org.operaton.bpm.client.backoff.ExponentialErrorBackoffStrategy
+        class ExponentialErrorBackoffStrategy
+          include ErrorAwareBackoffStrategy
+
+          def initialize(init_time = 500, factor = 2, max_time = 60_000)
+            @init_time = init_time
+            @factor = factor
+            @level = 0
+            @max_time = max_time
+          end
+
+          def reconfigure(_external_tasks, error = nil)
+            if error
+              @level += 1
+            else
+              @level = 0
+            end
+          end
+
+          def calculate_backoff_time
+            return 0 if @level.zero?
+
+            backoff_time = (@init_time * (@factor**(@level - 1))).to_i
+            [backoff_time, @max_time].min
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/exceptions.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Mirrors the org.operaton.bpm.client.exception package. The classes live
+# directly under Operaton::Bpm::Client to avoid shadowing Ruby's ::Exception.
+module Operaton
+  module Bpm
+    module Client
+      # Mirrors org.operaton.bpm.client.exception.ExternalTaskClientException
+      class ExternalTaskClientException < StandardError
+        def initialize(message = nil, cause = nil)
+          super(message)
+          @wrapped_cause = cause
+        end
+
+        def cause
+          @wrapped_cause || super
+        end
+      end
+
+      # Mirrors org.operaton.bpm.client.exception.RestException
+      class RestException < ExternalTaskClientException
+        attr_reader :type, :code
+
+        def initialize(message, type_or_cause = nil, code = nil)
+          if type_or_cause.is_a?(::Exception)
+            super(message, type_or_cause)
+            @type = nil
+            @code = nil
+          else
+            super(message)
+            @type = type_or_cause
+            @code = code
+          end
+          @http_status_code = nil
+        end
+
+        def http_status_code
+          cause.is_a?(RestException) ? cause.http_status_code : @http_status_code
+        end
+
+        attr_writer :http_status_code
+
+        def type
+          cause.is_a?(RestException) ? cause.type : @type
+        end
+
+        def code
+          cause.is_a?(RestException) ? cause.code : @code
+        end
+      end
+
+      # Thrown when the engine responds with HTTP 400
+      class BadRequestException < RestException; end
+
+      # Thrown when the engine responds with HTTP 500
+      class EngineException < RestException; end
+
+      # Thrown when the engine responds with HTTP 404
+      class NotFoundException < RestException; end
+
+      # Thrown when the engine responds with an HTTP status code not known by the client
+      class UnknownHttpErrorException < RestException; end
+
+      # Thrown when the connection to the engine could not be established
+      class ConnectionLostException < ExternalTaskClientException; end
+
+      # Thrown when a data format error occurs
+      class DataFormatException < ExternalTaskClientException; end
+
+      # Thrown when a variable value cannot be mapped
+      class ValueMapperException < ExternalTaskClientException; end
+    end
+  end
+end

data/lib/operaton/bpm/client/external_task_client.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Operaton
+  module Bpm
+    module Client
+      # Mirrors org.operaton.bpm.client.ExternalTaskClient. The static create()
+      # factory returns a fluent builder; the built client is an
+      # Impl::ExternalTaskClientImpl responding to #subscribe, #start, #stop
+      # and #active?.
+      module ExternalTaskClient
+        # Creates a fluent builder to configure the Operaton client.
+        def self.create
+          Impl::ExternalTaskClientBuilderImpl.new
+        end
+      end
+    end
+  end
+end
+
+require_relative "impl/external_task_client_builder_impl"

data/lib/operaton/bpm/client/external_task_client_builder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Operaton
+  module Bpm
+    module Client
+      # Mirrors org.operaton.bpm.client.ExternalTaskClientBuilder. Documents
+      # the fluent contract implemented by Impl::ExternalTaskClientBuilderImpl.
+      module ExternalTaskClientBuilder
+        INTERFACE_METHODS = %i[
+          base_url url_resolver worker_id add_interceptor max_tasks use_priority
+          use_create_time order_by_create_time asc desc default_serialization_format
+          date_format async_response_timeout lock_duration disable_auto_fetching
+          backoff_strategy disable_backoff_strategy customize_http_client build
+        ].freeze
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/impl/engine_client.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require_relative "permanent_url_resolver"
+require_relative "request_executor"
+require_relative "../task/impl/external_task_impl"
+require_relative "../task/impl/dto/bpmn_error_request_dto"
+require_relative "../task/impl/dto/complete_request_dto"
+require_relative "../task/impl/dto/extend_lock_request_dto"
+require_relative "../task/impl/dto/failure_request_dto"
+require_relative "../task/impl/dto/lock_request_dto"
+require_relative "../task/impl/dto/set_variables_request_dto"
+require_relative "../task/ordering_config"
+require_relative "../topic/impl/dto/fetch_and_lock_request_dto"
+
+module Operaton
+  module Bpm
+    module Client
+      module Impl
+        # Mirrors org.operaton.bpm.client.impl.EngineClient
+        class EngineClient
+          EXTERNAL_TASK_RESOURCE_PATH = "/external-task"
+          EXTERNAL_TASK_PROCESS_RESOURCE_PATH = "/process-instance"
+          FETCH_AND_LOCK_RESOURCE_PATH = "#{EXTERNAL_TASK_RESOURCE_PATH}/fetchAndLock"
+          ID_PATH_PARAM = "{id}"
+          ID_RESOURCE_PATH = "#{EXTERNAL_TASK_RESOURCE_PATH}/#{ID_PATH_PARAM}"
+          LOCK_RESOURCE_PATH = "#{ID_RESOURCE_PATH}/lock"
+          EXTEND_LOCK_RESOURCE_PATH = "#{ID_RESOURCE_PATH}/extendLock"
+          SET_VARIABLES_RESOURCE_PATH = "#{EXTERNAL_TASK_PROCESS_RESOURCE_PATH}/#{ID_PATH_PARAM}/variables"
+          UNLOCK_RESOURCE_PATH = "#{ID_RESOURCE_PATH}/unlock"
+          COMPLETE_RESOURCE_PATH = "#{ID_RESOURCE_PATH}/complete"
+          FAILURE_RESOURCE_PATH = "#{ID_RESOURCE_PATH}/failure"
+          BPMN_ERROR_RESOURCE_PATH = "#{ID_RESOURCE_PATH}/bpmnError"
+          NAME_PATH_PARAM = "{name}"
+          PROCESS_INSTANCE_RESOURCE_PATH = "/process-instance"
+          PROCESS_INSTANCE_ID_RESOURCE_PATH = "#{PROCESS_INSTANCE_RESOURCE_PATH}/#{ID_PATH_PARAM}"
+          GET_BINARY_VARIABLE = "#{PROCESS_INSTANCE_ID_RESOURCE_PATH}/variables/#{NAME_PATH_PARAM}/data"
+
+          attr_reader :worker_id, :max_tasks, :async_response_timeout, :ordering_config
+          attr_accessor :typed_values
+
+          def initialize(worker_id, max_tasks, async_response_timeout, url_resolver, engine_interaction,
+                         use_priority = true, ordering_config = Task::OrderingConfig.empty)
+            @worker_id = worker_id
+            @max_tasks = max_tasks
+            @async_response_timeout = async_response_timeout
+            @url_resolver = url_resolver.respond_to?(:base_url) ? url_resolver : PermanentUrlResolver.new(url_resolver)
+            @engine_interaction = engine_interaction
+            @use_priority = use_priority
+            @ordering_config = ordering_config
+          end
+
+          def fetch_and_lock(topics)
+            payload = Topic::Impl::Dto::FetchAndLockRequestDto.new(
+              worker_id, max_tasks, async_response_timeout, topics, @use_priority, ordering_config
+            )
+            resource_url = base_url + FETCH_AND_LOCK_RESOURCE_PATH
+            @engine_interaction.post_request(resource_url, payload, [Task::Impl::ExternalTaskImpl])
+          end
+
+          def lock(task_id, lock_duration)
+            payload = Task::Impl::Dto::LockRequestDto.new(worker_id, lock_duration)
+            post_task_request(LOCK_RESOURCE_PATH, task_id, payload)
+          end
+
+          def unlock(task_id)
+            post_task_request(UNLOCK_RESOURCE_PATH, task_id, nil)
+          end
+
+          def complete(task_id, variables, local_variables)
+            payload = Task::Impl::Dto::CompleteRequestDto.new(
+              worker_id,
+              typed_values.serialize_variables(variables),
+              typed_values.serialize_variables(local_variables)
+            )
+            post_task_request(COMPLETE_RESOURCE_PATH, task_id, payload)
+          end
+
+          def set_variables(process_id, variables)
+            payload = Task::Impl::Dto::SetVariablesRequestDto.new(
+              worker_id, typed_values.serialize_variables(variables)
+            )
+            resource_url = base_url + SET_VARIABLES_RESOURCE_PATH.sub(ID_PATH_PARAM, process_id)
+            @engine_interaction.post_request(resource_url, payload, RequestExecutor::VOID)
+          end
+
+          def failure(task_id, error_message, error_details, retries, retry_timeout, variables, local_variables)
+            payload = Task::Impl::Dto::FailureRequestDto.new(
+              worker_id, error_message, error_details, retries, retry_timeout,
+              typed_values.serialize_variables(variables),
+              typed_values.serialize_variables(local_variables)
+            )
+            post_task_request(FAILURE_RESOURCE_PATH, task_id, payload)
+          end
+
+          def bpmn_error(task_id, error_code, error_message, variables)
+            payload = Task::Impl::Dto::BpmnErrorRequestDto.new(
+              worker_id, error_code, error_message, typed_values.serialize_variables(variables)
+            )
+            post_task_request(BPMN_ERROR_RESOURCE_PATH, task_id, payload)
+          end
+
+          def extend_lock(task_id, new_duration)
+            payload = Task::Impl::Dto::ExtendLockRequestDto.new(worker_id, new_duration)
+            post_task_request(EXTEND_LOCK_RESOURCE_PATH, task_id, payload)
+          end
+
+          def get_local_binary_variable(variable_name, execution_id)
+            resource_url = base_url + GET_BINARY_VARIABLE
+                           .sub(ID_PATH_PARAM, execution_id)
+                           .sub(NAME_PATH_PARAM, variable_name)
+            @engine_interaction.get_request(resource_url)
+          end
+
+          def base_url
+            @url_resolver.base_url
+          end
+
+          def use_priority?
+            @use_priority
+          end
+
+          private
+
+          def post_task_request(resource_path, task_id, payload)
+            resource_url = base_url + resource_path.sub(ID_PATH_PARAM, task_id)
+            @engine_interaction.post_request(resource_url, payload, RequestExecutor::VOID)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/impl/engine_client_exception.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "../exceptions"
+
+module Operaton
+  module Bpm
+    module Client
+      module Impl
+        # Mirrors org.operaton.bpm.client.impl.EngineClientException — the
+        # internal exception wrapping transport/REST failures before they are
+        # translated into the public exception hierarchy.
+        class EngineClientException < StandardError
+          def initialize(message = nil, cause = nil)
+            super(message)
+            @wrapped_cause = cause
+          end
+
+          def cause
+            @wrapped_cause || super
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/impl/engine_client_logger.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "external_task_client_logger"
+require_relative "engine_client_exception"
+
+module Operaton
+  module Bpm
+    module Client
+      module Impl
+        # Mirrors org.operaton.bpm.client.impl.EngineClientLogger
+        class EngineClientLogger < ExternalTaskClientLogger
+          def exception_while_receiving_response(http_request, error)
+            EngineClientException.new(exception_message(
+              "001", "Request '{}' returned error: status code '{}' - message: {}",
+              http_request, error.http_status_code, error.message), error)
+          end
+
+          def exception_while_establishing_connection(http_request, error)
+            EngineClientException.new(exception_message(
+              "002", "Exception while establishing connection for request '{}'", http_request), error)
+          end
+
+          def exception_while_closing_resource_stream(response, error)
+            log_error("003", "Exception while closing resource stream of response '{}': ", error, response)
+          end
+
+          def exception_while_parsing_json_object(response_dto_class, error)
+            EngineClientException.new(exception_message(
+              "004", "Exception while parsing json object to response dto class '{}'", response_dto_class), error)
+          end
+
+          def exception_while_mapping_json_object(response_dto_class, error)
+            EngineClientException.new(exception_message(
+              "005", "Exception while mapping json object to response dto class '{}'", response_dto_class), error)
+          end
+
+          def exception_while_deserializing_json_object(response_dto_class, error)
+            EngineClientException.new(exception_message(
+              "006", "Exception while deserializing json object to response dto class '{}'", response_dto_class), error)
+          end
+
+          def exception_while_serializing_json_object(dto, error)
+            EngineClientException.new(exception_message(
+              "007", "Exception while serializing json object to '{}'", dto), error)
+          end
+
+          def request_interceptor_exception(error)
+            log_error("008", "Exception while executing request interceptor: {}", error)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/operaton/bpm/client/impl/engine_rest_exception_dto.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "../exceptions"
+
+module Operaton
+  module Bpm
+    module Client
+      module Impl
+        # Mirrors org.operaton.bpm.client.impl.EngineRestExceptionDto
+        class EngineRestExceptionDto
+          attr_accessor :message, :type, :code
+
+          def self.from_json(hash)
+            dto = new
+            dto.message = hash["message"]
+            dto.type = hash["type"]
+            dto.code = hash["code"]
+            dto
+          end
+
+          def to_rest_exception
+            RestException.new(message, type, code)
+          end
+        end
+      end
+    end
+  end
+end