caixanegra 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd21dec4c184b88b2898d5f011eb9e7288562c28f2204db0a6e85cca004153de
-  data.tar.gz: 49b39b216ac37609aa921ece85a263de64a7e932082d80761388e41d5c5eaf3d
+  metadata.gz: df3d38ccee4981c27d6acb8e72bc4c40c00537c6c370cdc17581de1dc179ac3f
+  data.tar.gz: 4bad76dfbfb9834d19389a28f92a7b3a7a1208c9cdf230a43fc4f9faf6322fb4
 SHA512:
-  metadata.gz: 8dcad855ae35dc5241379f3f4acc574ec4b0204877cea2d8770a08cf9774ffe7257f0a873ac0e067048ea432ee4c2689c94afea393aecd94942764b42ea67e06
-  data.tar.gz: a636a4d03ab305b54464f2003488fdb21f756f3876f4899da6b026b53e6f3326a4909a860ec7cb3390eecb68530e9070c44ed794a9fa484fbf25dbd35411d424
+  metadata.gz: 464c5ebbc06fa24c1f6f9261dd9e4241dff7bbfc8ccca0f067de5f289e5bda3a4e658475c8b15fa72971574748927016e5e23eed6020a0eda94580e7e85128ed
+  data.tar.gz: 55fcf0df7d3aac4d6e4458728cab6f3cfe874014903d47b5e4de1976290d8728cccdd28a687a748e43b5338bb6090b94596bb56fb43437ebbf203934c525717a

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2021 sergiorribeiro
+Copyright 2023 sergiorribeiro
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,18 +1,69 @@
 # caixanegra
 ![Gem](https://img.shields.io/gem/v/caixanegra?logo=ruby&logoColor=red)
 
-## Getting Started
+An unopinionated flow oriented blackbox designer, executor and debugger to interface your service classes and allow users to manipulate or completely redesign processes using your code.
 
+# Installation
+Add this line to your application's Gemfile:
 
+```ruby
+gem 'caixanegra'
+```
 
+or 
 
+```
+bundler add caixanegra
+```
+# Getting Started
+**caixanegra** implements a self-contained designer, which only requires Redis to be able to receive and report back flow descriptors.  
+To get started, the only thing you need is to point to your Redis instance and point which classes on your codebase should represent units.
 
+First, mount the engine. Add the line below to `routes.rb` file:
 
-## Installation
-Add this line to your application's Gemfile:
+```ruby
+mount Caixanegra::Engine, at: "/caixanegra", as: :caixanegra
+```
+
+Then, let's create a `caixanegra.rb` initializer (or any name you prefer)
 
 ```ruby
-gem 'caixanegra'
+Caixanegra.setup do |config|
+  config.units = {
+    awesome_unit: Caixanegra::Units::AU,
+    another_awesome_unit: Some::Other::Namespace::AAU,
+    you_can_also: {
+      scope_units: Caixanegra::Units::ScopedUnit,
+    },
+  }
+  config.redis = Redis.new
+end
+```
+
+With the designer configured, you can use `Caixanegra::Manager` to handle the previously stored definition (or an empty one).  
+This will give you the UID that **caixanegra** designer will understand.  
+
+```ruby
+my_flow = somewhere.get_flow # get from your own persistence or transport solution
+uid = Caixanegra::Manager.handler(my_flow || {})
 ```
-## License
+
+You can then safely navigate to the designer.
+
+```ruby
+link_to "Some flow", "/caixanegra/design/#{@uid}?unit_scope=optional_scope,another_optional_scope", target: :_blank
+```
+
+Saved changes will update the flow definition on Redis, and you must then persist them. You can get the flow definition for any specified **caixanegra** handled UID:
+
+```ruby
+updated_flow = Caixanegra::Manager.get(my_uid)
+persist_flow(updated_flow) # your own persistence or transport solution. It's a JSON
+```
+
+**NOTE:** There's currently no managed way to set callbacks on save actions from the designer. Working on it
+
+Please, refer to [the wiki](https://github.com/sergiorribeiro/caixanegra/wiki) to get to know more about [units](https://github.com/sergiorribeiro/caixanegra/wiki/Anatomy-of-a-unit).
+
+# License
 **caixanegra** is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/assets/javascripts/caixanegra/designer.js

@@ -166,9 +166,9 @@ window.Caixanegra.Designer = {
             ctx.beginPath();
             ctx.moveTo(this.#drawValues.position.x + this.size.x, exit.markerY);
             ctx.lineTo(this.#drawValues.position.x + this.size.x + 25, exit.markerY);
-            
+
             if (this.connectingExit === exit && context.mouse.move) {
-              ctx.lineTo(context.mouse.move.x, context.mouse.move.y);
+              ctx.lineTo(context.mouse.move.x + context.referential.x, context.mouse.move.y + context.referential.y);
             } else if (exit.reference.target) {
               const targetCenter = exit.reference.target.getCenter(context.referential);
               ctx.lineTo(targetCenter.x, targetCenter.y);
@@ -382,10 +382,10 @@ window.Caixanegra.Designer = {
     }
 
     deleteUnit() {
-      this.removeUnit(this.selectedUnit.oid);
-      this.toggleDeleteConfirmation();
       this.unitDetailPane.classList.remove("-open");
       this.unitDebugHitsPane.classList.remove("-open");
+      this.removeUnit(this.selectedUnit.oid);
+      this.toggleDeleteConfirmation();
     }
 
     flushToConsole(entries) {

data/app/controllers/caixanegra/api/designer/flows_controller.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Caixanegra
-  module API
+  module Api
     module Designer
-      class FlowsController < ::Caixanegra::APIController
+      class FlowsController < ::Caixanegra::ApiController
         before_action :set_flow, only: %i[show debug_run]
 
         def show
@@ -20,7 +20,6 @@ module Caixanegra
           execution = Caixanegra::Executor.new(
             initial_carryover: initial_carryover,
             flow_definition: @flow,
-            unit_scope: params[:unit_scope],
             debug_mode: true
           ).run
 

data/app/controllers/caixanegra/api/designer/units_controller.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Caixanegra
-  module API
+  module Api
     module Designer
-      class UnitsController < ::Caixanegra::APIController
+      class UnitsController < ::Caixanegra::ApiController
         def index
           render json: units
         end
@@ -15,26 +15,20 @@ module Caixanegra
         end
 
         def units
-          @units ||= begin
-            base_units = Caixanegra.units.reject { |_, v| v.is_a? Hash }
-            scope_units = Caixanegra.units[unit_scope] if unit_scope.present?
-            all_units = base_units.merge(scope_units || {})
+          @units ||= ::Caixanegra::UnitHelper.scoped_units(unit_scope).map do |k, v|
+            base = {
+              title: v.name,
+              type: v.type,
+              description: v.description,
+              class: k,
+              exits: v.exits&.map { |e| { name: e } },
+              inputs: v.inputs,
+              assignments: v.assignments
+            }
 
-            all_units.map do |k, v|
-              base = {
-                title: v.name,
-                type: v.type,
-                description: v.description,
-                class: k,
-                exits: v.exits&.map { |e| { name: e } },
-                inputs: v.inputs,
-                assignments: v.assignments
-              }
+            base[:set] = v.set if base[:set]
 
-              base[:set] = v.set if base[:set]
-
-              base
-            end
+            base
           end
         end
       end

data/app/controllers/caixanegra/api_controller.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Caixanegra
-  class APIController < ActionController::API
+  class ApiController < ActionController::API
   end
 end

data/app/models/caixanegra/unit.rb

@@ -36,6 +36,12 @@ module Caixanegra
       }
     end
 
+    def exit_and_return
+      {
+        carry_over: @carry_over
+      }
+    end
+
     def flow
       exit_through exits.first
     end
@@ -64,7 +70,10 @@ module Caixanegra
 
         input_value = result
       end
+
       input_value.presence || @inputs[id][:default]
+    rescue StandardError
+      raise(UnitIOException.new, "Unable to fetch input '#{id}'")
     end
 
     def name

data/lib/caixanegra/engine.rb

@@ -6,13 +6,13 @@ module Caixanegra
   self.units = []
 
   def self.setup(&block)
-     yield self
+    yield self
   end
 
   class Engine < ::Rails::Engine
     isolate_namespace Caixanegra
 
-    initializer "caixanegra.assets.precompile" do |app|
+    initializer 'caixanegra.assets.precompile' do |app|
       app.config.assets.precompile += %w[
         caixanegra/api.js
         caixanegra/caixanegra.js

data/lib/caixanegra/exceptions.rb

@@ -2,4 +2,6 @@
 
 module Caixanegra
   class UnitScopedException < StandardError; end
+  class UnitIOException < StandardError; end
+  class ContinuityException < StandardError; end
 end

data/lib/caixanegra/executor.rb

@@ -5,7 +5,6 @@ module Caixanegra
     def initialize(params)
       @initial_carryover = params[:initial_carryover] || {}
       @flow = (params[:flow_definition] || {}).deep_symbolize_keys
-      @unit_scope = params[:unit_scope]
       @debug_mode = params[:debug_mode] == true
       @execution = { history: [], steps: [] }
       @storage = {}
@@ -27,7 +26,7 @@ module Caixanegra
     end
 
     def run_and_report_result
-      log_console_entry "Started"
+      log_console_entry 'Started'
       set_start_unit
       format_result(flow_through)
     rescue Caixanegra::UnitScopedException => e
@@ -113,6 +112,8 @@ module Caixanegra
           raise exception
         end
         next_unit = next_unit(result)
+        raise(ContinuityException.new, "Unable to choose a valid exit") if next_unit.nil?
+
         log_step_result(result, next_unit)
         @execution[:steps] += feeder_steps
         @step_unit = next_unit
@@ -143,6 +144,8 @@ module Caixanegra
     end
 
     def next_unit(result)
+      return nil if result.nil?
+
       exit_name = result[:exit_through]
       metadata = unit_metadata(@step_unit.oid)
       log_console_entry "Next unit found through '#{exit_name}': '#{@step_unit.oid}'"
@@ -187,15 +190,13 @@ module Caixanegra
       unit_class = scoped_units[unit_data[:class].to_sym]
       inputs = unit_class.inputs
       unit_class.new(unit_data[:oid], inputs, mappings, carry_over, @storage)
+    rescue
+      log_console_entry "Unable to load unit instance of type '#{unit_data[:class]}'"
+      nil
     end
 
     def scoped_units
-      @scoped_units ||= begin
-        base_units = Caixanegra.units.reject { |_, v| v.is_a? Hash }
-        scope_units = Caixanegra.units[@unit_scope] if @unit_scope.present?
-
-        base_units.merge(scope_units || {})
-      end
+      @scoped_units ||= UnitHelper.all_units
     end
   end
 end

data/lib/caixanegra/manager.rb

@@ -4,7 +4,7 @@ module Caixanegra
   class Manager
     class << self
       def handler(flow_definition = {})
-        uid = SecureRandom.uuid.gsub("-", "")
+        uid = SecureRandom.uuid.gsub('-', '')
 
         Caixanegra.redis.multi do |pipeline|
           pipeline.hset(:caixanegra, uid, JSON.dump(flow_definition))

data/lib/caixanegra/unit_helper.rb

@@ -0,0 +1,32 @@
+module Caixanegra
+  class UnitHelper
+    class << self
+      def scoped_units(scope)
+        all_units = {}
+        all_units = all_units.merge(Caixanegra.units.reject { |_, v| v.is_a? Hash })
+
+        (scope || "").split(",").each do |current_scope|
+          all_units = all_units.merge(Caixanegra.units[current_scope.to_sym])
+        end
+
+        all_units
+      end
+
+      def all_units
+        all_units = {}
+
+        Caixanegra.units.each do |k, v|
+          if v.is_a? Hash
+            v.each do |ik, iv|
+              all_units[ik] = iv
+            end
+          else
+            all_units[k] = v
+          end
+        end
+
+        all_units
+      end
+    end
+  end
+end

data/lib/caixanegra/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Caixanegra
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/caixanegra.rb

@@ -1,8 +1,10 @@
-require "caixanegra/exceptions"
-require "caixanegra/engine"
-require "caixanegra/version"
-require "caixanegra/executor"
-require "caixanegra/manager"
+# frozen_string_literal: true
 
-module Caixanegra  
-end
+require 'caixanegra/exceptions'
+require 'caixanegra/unit_helper'
+require 'caixanegra/engine'
+require 'caixanegra/version'
+require 'caixanegra/executor'
+require 'caixanegra/manager'
+
+module Caixanegra ; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: caixanegra
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - sergiorribeiro
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-08 00:00:00.000000000 Z
+date: 2023-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -38,7 +38,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: TBD
+description: An unopinionated, flow oriented blackbox designer and executor to interface
+  your service classes
 email:
 - sergio.r.ribeiro@live.com
 executables: []
@@ -71,13 +72,13 @@ files:
 - lib/caixanegra/exceptions.rb
 - lib/caixanegra/executor.rb
 - lib/caixanegra/manager.rb
+- lib/caixanegra/unit_helper.rb
 - lib/caixanegra/version.rb
 - lib/tasks/caixanegra_tasks.rake
-homepage: http://sergioribeiro.com
+homepage: https://github.com/sergiorribeiro/caixanegra/wiki
 licenses:
 - MIT
-metadata:
-  allowed_push_host: https://rubygems.org
+metadata: {}
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -86,7 +87,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.7.5
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -96,5 +97,5 @@ requirements: []
 rubygems_version: 3.3.17
 signing_key:
 specification_version: 4
-summary: TBD
+summary: Unopinionated flow oriented blackbox designer, executor and debugger
 test_files: []