trailblazer-activity 0.9.4 → 0.11.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0b971b7f8960520b05bcc99a2fe0561056d9ec244cf9faeb072e131604e0bc12
-  data.tar.gz: ec6e1d2c4b2de4d1edfce435c08029a061df61b1b770ad174c005733238269cb
+  metadata.gz: 380d2d51d03b55dbd76b0501b67d9f16d782d1c68a62a6fe8b87ef0074480206
+  data.tar.gz: 5b5b4ebea2d846793d8ad925ac18a3c6b458857c7189894c7cd61924030b5632
 SHA512:
-  metadata.gz: 5de05a662519033f02c6e58595d502e80970b08abe7bd87caa7ff23c6acae6490498453bcf8584b8ea6dcba14ef6f00298b1aeca75c5405f8e281e4d206e44e9
-  data.tar.gz: 35c9f6d275c0da422e0597529424f005af4e44a344c63c0ca8595d87a44ad8c474be21c5e9c985d1f1a01b2d1ff0b2020da06edcc29e9871af9c174c1766d7cb
+  metadata.gz: 2e4e0b531018c3eae43d943b21a583807a494ea00e93e26f6fb3bdb13da04cdc6b7bc7b431a0bf0508b02c1571ab4e249864d77832d32405c46ee3704092770a
+  data.tar.gz: 34b9a5957cc8e59ac3862c2bdf4e4cd5b4028101f2205bcb0566a598a6539396fdd33f1c25ed161f2bc03d1da1cbb6bfd9f01e78a3d1bd3eb5573a7efb93c2f3

data/.travis.yml

@@ -1,10 +1,12 @@
-sudo: false
 language: ruby
-rvm:
-  - 2.6.0
-  - 2.5.1
-  - 2.4.4
-  # - 2.3.7
-  # - 2.2.10
-  # - 2.1.10
 before_install: gem install bundler
+cache: bundler
+rvm:
+  - ruby-head
+  - 2.7
+  - 2.6
+  - 2.5
+  - 2.4
+jobs:
+  allow_failures:
+    - rvm: ruby-head

data/CHANGES.md

@@ -1,18 +1,46 @@
+# 0.11.3
+
+* Allow `Testing.def_task` & `Testing.def_tasks` to return custom signals
+
+# 0.11.2
+
+* Updrading `trailblazer-context` version :drum:
+
+# 0.11.1
+
+* Internal warning fixes.
+
+# 0.11.0
+
+* Support for Ruby 2.7. Most warnings are gone.
+
+# 0.10.1
+
+* Update IllegalSignalError exception for more clarity
+
+# 0.10.0
+
+* Require `developer` >= 0.0.7.
+* Move `Activity::Introspect` back to this very gem.
+* This is hopefully the last release before 2.1.0. :trollface:
+
 # 0.9.4
 
-Move some test helpers to `Activity::Testing` to export them to other gems
+* Move some test helpers to `Activity::Testing` to export them to other gems
+* Remove introspection modules, it'll also be part of the `Dev` tools now.
+* Remove tracing modules, it'll be part of the `Dev` tools now.
 
 # 0.9.3
 
-Remove introspection modules, it'll also be part of the `Dev` tools now.
+Unreleased.
 
 # 0.9.2
 
-Remove tracing modules, it'll be part of the `Dev` tools now.
+Unreleased.
 
 # 0.9.1
 
-Use `context-0.9.1`.
+* Use `context-0.9.1`.
 
 # 0.9.0
 

data/Gemfile

@@ -6,8 +6,5 @@ gemspec
 gem "benchmark-ips"
 gem "minitest-line"
 
-gem "rubocop", require: false
-
 # gem "trailblazer-context", path: "../trailblazer-context"
 # gem "trailblazer-developer", path: "../trailblazer-developer"
-# gem "trailblazer-developer", github: "trailblazer/trailblazer-developer", branch: "exception-tracing"

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2018 Trailblazer GmbH
+Copyright (c) 2018-2020 Trailblazer GmbH
 
 Trailblazer is an Open Source project licensed under the terms of
 the LGPLv3 license.  Please see <http://www.gnu.org/licenses/lgpl-3.0.html>

data/README.md

@@ -1,22 +1,22 @@
 # Activity
 
-implements Intermediate, Implementation, compiler and `Activity::Implementation`, Activity::Interface
+Implements Intermediate, Implementation and compiler
 
 The `activity` gem brings a light-weight DSL to define business processes, and the runtime logic to run those activities.
 
 A process is a set of arbitrary pieces of logic you define, chained together and put into a meaningful context by an activity. Activity lets you focus on the implementation of steps while Trailblazer takes care of the control flow.
 
-Please find the [full documentation on the Trailblazer website](http://trailblazer.to/api-docs). [Note that the docs are WIP.]
+Please find the [full documentation on the Trailblazer website](https://2019.trailblazer.to/2.1/docs/activity.html). [Note that the docs are WIP.]
 
 ## Example
 
-The `activity` gem provides three default patterns to model processes: `Path`, `Railway` and `FastTrack`. Here's an example what a railway activity could look like, along with some more complex connections.
+In conjunction with [`dsl-linear`](https://github.com/trailblazer/trailblazer-activity-dsl-linear), the `activity` gem provides three default patterns to model processes: `Path`, `Railway` and `FastTrack`. Here's an example of what a railway activity could look like, along with some more complex connections (you can read more about Railway strategy in the [docs](https://2019.trailblazer.to/2.1/docs/activity.html#activity-strategy-railway)).
 
 ```ruby
-module Memo::Update
-  extend Trailblazer::Activity::Railway()
-  module_function
+require "trailblazer-activity"
+require "trailblazer-activity-dsl-linear"
 
+class Memo::Update < Trailblazer::Activity::Railway
   # here goes your business logic
   #
   def find_model(ctx, id:, **)
@@ -39,10 +39,10 @@ module Memo::Update
 
   # here comes the DSL describing the layout of the activity
   #
-  step method(:find_model)
-  step method(:validate), Output(:failure) => End(:validation_error)
-  step method(:save)
-  fail method(:log_error)
+  step :find_model
+  step :validate, Output(:failure) => End(:validation_error)
+  step :save
+  fail :log_error
 end
 ```
 
@@ -71,17 +71,22 @@ With Activity, modeling business processes turns out to be ridiculously simple:
 ## Features
 
 * Activities can model any process with arbitrary flow and connections.
-* Nesting and compositions are allowed and encouraged.
+* Nesting and compositions are allowed and encouraged (via Trailblazer's [`dsl-linear`](https://github.com/trailblazer/trailblazer-activity-dsl-linear) gem).
 * Different step interfaces, manual processing of DSL options, etc is all possible.
 * Steps can be any kind of callable objects.
-* Tracing!
+* Tracing! (via Trailblazer's [`developer`](https://github.com/trailblazer/trailblazer-developer) gem)
 
 ## Operation
 
-Trailblazer's [`Operation`](http://trailblazer.to/2.1/operation) internally uses an activity to model the processes.
+Trailblazer's [`Operation`](https://2019.trailblazer.to/2.1/docs/operation.html#operation-overview) internally uses an activity to model the processes.
+
+## Workflow
+Activities can be formed into bigger compounds and using workflow, you can build long-running processes such as a moderated blog post or a parcel delivery. Also, you don't have to use the DSL but can use the [`editor`](https://2019.trailblazer.to/2.1/docs/pro.html#pro-editor)instead(cool for more complex, long-running flows). Here comes a sample screenshot.
+
+<img src="http://2019.trailblazer.to/2.1/dist/img/flow.png">
 
 ## License
 
 © Copyright 2018, Trailblazer GmbH
 
-Licensed under the LGPLv3 license. We also offer a [commercial-friendly license](http://trailblazer.to/pro).
+Licensed under the LGPLv3 license. We also offer a commercial-friendly [license](https://2019.trailblazer.to/2.1/docs/pro.html#pro-license).

data/Rakefile

@@ -1,13 +1,10 @@
 require "bundler/gem_tasks"
 require "rake/testtask"
-require "rubocop/rake_task"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["**/*_test.rb"] - FileList["test/docs/*"] + ["test/docs/activity_test.rb"]
+  t.test_files = FileList["test/**/*_test.rb"] - FileList["test/docs/*"] + ["test/docs/activity_test.rb"]
 end
 
-RuboCop::RakeTask.new
-
-task :default => :test
+task default: %i[test]

data/lib/trailblazer/activity.rb

@@ -7,10 +7,10 @@ module Trailblazer
       @schema = schema
     end
 
-    def call(args, circuit_options={})
+    def call(args, **circuit_options)
       @schema[:circuit].(
         args,
-        circuit_options.merge(activity: self)
+        **(circuit_options.merge(activity: self))
       )
     end
 
@@ -34,23 +34,15 @@ module Trailblazer
   end # Activity
 end
 
-# require "trailblazer/activity/interface"
 require "trailblazer/activity/structures"
 require "trailblazer/activity/schema"
-require "trailblazer/activity/schema/implementation"
-require "trailblazer/activity/schema/intermediate"
 require "trailblazer/activity/circuit"
 require "trailblazer/activity/config"
-
+require "trailblazer/activity/introspect"
 require "trailblazer/activity/task_wrap"
-require "trailblazer/activity/task_wrap/pipeline"
-require "trailblazer/activity/task_wrap/call_task"
-require "trailblazer/activity/task_wrap/runner"
-require "trailblazer/activity/task_wrap/variable_mapping"
-require "trailblazer/activity/task_wrap/inject"
+require "trailblazer/activity/task_builder"
 
 require "trailblazer/option"
 require "trailblazer/context"
-require "trailblazer/activity/task_builder"
 
 

data/lib/trailblazer/activity/circuit.rb

@@ -45,13 +45,22 @@ module Trailblazer
           last_signal, args, _discarded_circuit_options = runner.(
             task,
             args,
-            circuit_options
+            **circuit_options
           )
 
           # Stop execution of the circuit when we hit a stop event (< End). This could be an task's End or Suspend.
           return [ last_signal, args ] if @stop_events.include?(task) # DISCUSS: return circuit_options here?
 
-          task = next_for(task, last_signal) or raise IllegalSignalError.new("<#{@name}>[#{task}][ #{last_signal.inspect} ]")
+          if (next_task = next_for(task, last_signal))
+            task = next_task
+          else
+            raise IllegalSignalError.new(
+              task,
+              signal: last_signal,
+              outputs: @map[task],
+              exec_context: circuit_options[:exec_context], # passed at run-time from DSL
+            )
+          end
         end
       end
 
@@ -67,7 +76,26 @@ module Trailblazer
         outputs[signal]
       end
 
+      # Common reasons to raise IllegalSignalError are
+      #   * Returning invalid signal from custom Macros
+      #   * Returning invalid signal from steps which are not taskWrapped, for example: `step task: method(:validate)`
+      #
+      # Rest assured, it won't be raised in case of below scenarios where they can return any value,
+      #   * Steps with instance method signature, for example, `step :load_user`
+      #   * Steps with proc signature, for example `step ->(ctx, **){}`
       class IllegalSignalError < RuntimeError
+        attr_reader :task, :signal
+
+        def initialize(task, signal:, outputs:, exec_context:)
+          @task = task
+          @signal = signal
+
+          message = "#{exec_context.class}: \n\t" \
+            "\sUnrecognized Signal `#{signal.inspect}` returned from #{task.inspect}. Registered signals are, \n" \
+            "- #{outputs.keys.join("\n- ")}"
+
+          super(message)
+        end
       end
     end
   end

data/lib/trailblazer/activity/config.rb

@@ -28,6 +28,7 @@ module Trailblazer
 
         return state[directive] if args.size == 1
         return state[directive][key] if state.key?(directive)
+
         nil
       end
     end

data/lib/trailblazer/activity/introspect.rb

@@ -0,0 +1,73 @@
+module Trailblazer
+  class Activity
+    # The Introspect API provides inflections for `Activity` instances.
+    # It abstracts internals about circuits and provides a convenient API to third-parties such as
+    # tracing, rendering an activity, or finding particular tasks.
+    module Introspect
+      # TODO: order of step/fail/pass in Node would be cool to have
+
+      # @private This API is still under construction.
+      class Graph
+        def initialize(activity)
+          @activity = activity
+          @schema   = activity.to_h or raise
+          @circuit  = @schema[:circuit]
+          @map      = @circuit.to_h[:map]
+          @configs  = @schema[:nodes]
+        end
+
+        def find(id = nil, &block)
+          return find_by_id(id) unless block_given?
+
+          find_with_block(&block)
+        end
+
+        def collect(strategy: :circuit)
+          @map.keys.each_with_index.collect { |task, i| yield find_with_block { |node| node.task == task }, i }
+        end
+
+        def stop_events
+          @circuit.to_h[:end_events]
+        end
+
+        private
+
+        def find_by_id(id)
+          node = @configs.find { |_node| _node.id == id } or return
+          node_for(node)
+        end
+
+        def find_with_block
+          existing = @configs.find { |node| yield Node(node.task, node.id, node.outputs, node.data) } or return
+
+          node_for(existing)
+        end
+
+        def node_for(node_attributes)
+          Node(node_attributes.task, node_attributes.id, node_attributes.outputs, outgoings_for(node_attributes), node_attributes.data)
+        end
+
+        def Node(*args)
+          Node.new(*args).freeze
+        end
+
+        Node     = Struct.new(:task, :id, :outputs, :outgoings, :data)
+        Outgoing = Struct.new(:output, :task)
+
+        def outgoings_for(node)
+          outputs     = node.outputs
+          connections = @map[node.task]
+
+          connections.collect do |signal, target|
+            output = outputs.find { |out| out.signal == signal }
+            Outgoing.new(output, target)
+          end
+        end
+      end
+
+      def self.Graph(*args)
+        Graph.new(*args)
+      end
+    end # Introspect
+  end
+end

data/lib/trailblazer/activity/schema.rb

@@ -11,3 +11,5 @@ module Trailblazer
     end # Schema
   end
 end
+require "trailblazer/activity/schema/implementation"
+require "trailblazer/activity/schema/intermediate"

data/lib/trailblazer/activity/schema/intermediate.rb

@@ -20,7 +20,7 @@ class Trailblazer::Activity
         nodes   = node_attributes(intermediate, implementation)
         outputs = outputs(intermediate.stop_task_ids, nodes)
         config  = config(implementation, config: config_default)
-        schema  = Schema.new(circuit, outputs, nodes, config)
+        Schema.new(circuit, outputs, nodes, config)
       end
 
       # From the intermediate "template" and the actual implementation, compile a {Circuit} instance.
@@ -83,10 +83,10 @@ class Trailblazer::Activity
         config
       end
 
-      private
+
 
       # Apply to any array.
-      def self.for_semantic(outputs, semantic)
+      private_class_method def self.for_semantic(outputs, semantic)
         outputs.find { |out| out.semantic == semantic } or raise "`#{semantic}` not found"
       end
     end # Intermediate

data/lib/trailblazer/activity/structures.rb

@@ -2,13 +2,7 @@ module Trailblazer
   class Activity
     # Generic run-time structures that are built via the DSL.
 
-    # Builds an {Activity::End} instance.
-    def self.End(semantic)
-      End.new(semantic: semantic)
-    end
-
     # Any instance of subclass of End will halt the circuit's execution when hit.
-
     # An End event is a simple structure typically found as the last task invoked
     # in an activity. The special behavior is that it
     # a) maintains a semantic that is used to further connect that very event
@@ -18,8 +12,8 @@ module Trailblazer
         @options = options.merge(semantic: semantic)
       end
 
-      def call(args, circuit_options)
-        return self, args, circuit_options
+      def call(args, **circuit_options)
+        return self, args, **circuit_options
       end
 
       def to_h
@@ -27,15 +21,15 @@ module Trailblazer
       end
 
       def to_s
-        %{#<#{self.class.name} #{@options.collect{ |k,v| "#{k}=#{v.inspect}" }.join(" ")}>}
+        %{#<#{self.class.name} #{@options.collect { |k, v| "#{k}=#{v.inspect}" }.join(" ")}>}
       end
 
-      alias_method :inspect, :to_s
+      alias inspect to_s
     end
 
     class Start < End
-      def call(args, circuit_options)
-        return Activity::Right, args, circuit_options
+      def call(args, **circuit_options)
+        return Activity::Right, args, **circuit_options
       end
     end
 
@@ -53,5 +47,10 @@ module Trailblazer
     def self.Output(signal, semantic)
       Output.new(signal, semantic).freeze
     end
+
+    # Builds an {Activity::End} instance.
+    def self.End(semantic)
+      End.new(semantic: semantic)
+    end
   end
 end