trailblazer-activity 0.7.1 → 0.8.0

data/lib/trailblazer/activity/task_wrap/runner.rb

@@ -1,4 +1,4 @@
-class Trailblazer::Activity < Module
+class Trailblazer::Activity
   module TaskWrap
     # The runner is passed into Activity#call( runner: Runner ) and is called for every task in the circuit.
     # It runs the TaskWrap per task.
@@ -12,18 +12,15 @@ class Trailblazer::Activity < Module
       def self.call(task, args, circuit_options)
         wrap_ctx = { task: task }
 
-        # this activity is "wrapped around" the actual `task`.
-        task_wrap_activity = merge_static_with_runtime(task, circuit_options)
+        # this pipeline is "wrapped around" the actual `task`.
+        task_wrap_pipeline = merge_static_with_runtime(task, circuit_options) || raise
 
         # We save all original args passed into this Runner.call, because we want to return them later after this wrap
         # is finished.
         original_args = [ args, circuit_options ]
 
         # call the wrap {Activity} around the task.
-        wrap_end_signal, ( wrap_ctx, _ ) = task_wrap_activity.(
-          [ wrap_ctx, original_args ], # we omit circuit_options here on purpose, so the wrapping activity uses the default, plain Runner.
-          {}
-        )
+        wrap_ctx, _ = task_wrap_pipeline.(wrap_ctx, original_args) # we omit circuit_options here on purpose, so the wrapping activity uses the default, plain Runner.
 
         # don't return the wrap's end signal, but the one from call_task.
         # return all original_args for the next "real" task in the circuit (this includes circuit_options).
@@ -39,24 +36,18 @@ class Trailblazer::Activity < Module
       # unnecessary computations at `call`-time since steps might not even be executed.
       # TODO: make this faster.
       def self.merge_static_with_runtime(task, wrap_runtime:, **circuit_options)
-        wrap_activity = TaskWrap.wrap_static_for(
-          task,
-          circuit_options
-        )  # find static wrap for this specific task, or default wrap activity.
+        static_wrap = TaskWrap.wrap_static_for(task, circuit_options) # find static wrap for this specific task [, or default wrap activity].
 
         # Apply runtime alterations.
-        # Grab the additional wirings for the particular `task` from `wrap_runtime` (returns default otherwise).
-        wrap_runtime[task] ? Trailblazer::Activity::Path::Plan.merge(wrap_activity, wrap_runtime[task]) : wrap_activity
+        # Grab the additional wirings for the particular `task` from `wrap_runtime`.
+        (dynamic_wrap = wrap_runtime[task]) ? dynamic_wrap.(static_wrap) : static_wrap
       end
     end # Runner
 
     # Retrieve the static wrap config from {activity}.
-    # I do not like this part too much, I'd prefer computing the {:wrap_static} at compile-time for the entire
-    # object graph (including nesteds) and simply pass it through to all Runner calls.
-    # TODO: simplify that. See above
-    def self.wrap_static_for(task, activity:, default_activity: TaskWrap.initial_activity, **)
-      wrap_static = activity[:wrap_static] || {}
-      wrap_static[task] || default_activity
+    def self.wrap_static_for(task, activity:, **)
+      wrap_static = activity[:wrap_static]
+      wrap_static[task] or raise "#{task}"
     end
   end
 end

data/lib/trailblazer/activity/task_wrap/variable_mapping.rb

@@ -1,6 +1,4 @@
-require "trailblazer/context"
-
-class Trailblazer::Activity < Module
+class Trailblazer::Activity
   module TaskWrap
     # Creates taskWrap steps to map variables before and after the actual step.
     # We hook into the Normalizer, process `:input` and `:output` directives and
@@ -9,55 +7,25 @@ class Trailblazer::Activity < Module
     # Note that the two options are not the only way to create filters, you can use the
     # more low-level {Scoped()} etc., too, and write your own filter logic.
     module VariableMapping
-      # DSL step for Magnetic::Normalizer.
-      # Translates `:input` and `:output` into VariableMapping taskWrap extensions.
-      def self.normalizer_step_for_input_output(ctx, *)
-        options, io_config = Magnetic::Options.normalize( ctx[:options], [:input, :output] )
-
-        return if io_config.empty?
-
-        ctx[:options] = options # without :input and :output
-        ctx[:options] = options.merge(Trailblazer::Activity::TaskWrap::VariableMapping(io_config) => true)
-      end
-
       # The taskWrap extension that's included into the static taskWrap for a task.
-      def self.extension_for(input, output)
-        Trailblazer::Activity::DSL::Extension.new(
-          Merge.new(
-            Module.new do
-              extend Path::Plan()
+      def self.Extension(input, output, id: input.object_id)
+        input  = Trailblazer::Option(input)
+        output = Trailblazer::Option(output)
 
-              task input,  id: "task_wrap.input", before: "task_wrap.call_task"
-              task output, id: "task_wrap.output", before: "End.success", group: :end
-            end
-          )
+        Trailblazer::Activity::TaskWrap::Extension(
+          merge: merge_for(input, output, id: id),
         )
       end
-    end
 
-    # @private
-    def self.filter_for(filter)
-      if filter.is_a?(::Array) || filter.is_a?(::Hash)
-        TaskWrap::DSL.filter_from_dsl(filter)
-      else
-        filter
+      # DISCUSS: do we want the automatic wrapping of {input} and {output}?
+      def self.merge_for(input, output, id:) # TODO: rename
+        [
+          [TaskWrap::Pipeline.method(:insert_before), "task_wrap.call_task", ["task_wrap.input", TaskWrap::Input.new(input, id: id)]],
+          [TaskWrap::Pipeline.method(:insert_after),  "task_wrap.call_task", ["task_wrap.output", TaskWrap::Output.new(output, id: id)]],
+        ]
       end
     end
 
-
-    # Returns an Extension instance to be thrown into the `step` DSL arguments.
-    def self.VariableMapping(input:, output:)
-      input  = Input.new(
-                Input::Scoped.new(
-                  Trailblazer::Option::KW( filter_for(input) ) ) )
-
-      output = Output.new(
-                Output::Unscoped.new(
-                  Trailblazer::Option::KW( filter_for(output) ) ) )
-
-      VariableMapping.extension_for(input, output)
-    end
-
     # TaskWrap step to compute the incoming {Context} for the wrapped task.
     # This allows renaming, filtering, hiding, of the options passed into the wrapped task.
     #
@@ -67,23 +35,25 @@ class Trailblazer::Activity < Module
 
     # Calls your {@filter} and replaces the original ctx with your returned one.
     class Input
-      def initialize(filter)
+      def initialize(filter, id:)
         @filter = filter
+        @id     = id
       end
 
+      # {input.call()} is invoked in the circuit.
       # `original_args` are the actual args passed to the wrapped task: [ [options, ..], circuit_options ]
       #
-      def call( (wrap_ctx, original_args), circuit_options )
+      def call(wrap_ctx, original_args)
         # let user compute new ctx for the wrapped task.
         input_ctx = apply_filter(*original_args)
 
-        wrap_ctx = wrap_ctx.merge( vm_original_ctx: original_args[0][0] ) # remember the original ctx
-
         # decompose the original_args since we want to modify them.
         (original_ctx, original_flow_options), original_circuit_options = original_args
 
+        wrap_ctx = wrap_ctx.merge(@id => original_ctx) # remember the original ctx by the key {@id}.
+
         # instead of the original Context, pass on the filtered `input_ctx` in the wrap.
-        return Trailblazer::Activity::Right, [ wrap_ctx, [[input_ctx, original_flow_options], original_circuit_options] ]
+        return wrap_ctx, [[input_ctx, original_flow_options], original_circuit_options]
       end
 
       private
@@ -91,71 +61,29 @@ class Trailblazer::Activity < Module
       def apply_filter((ctx, original_flow_options), original_circuit_options)
         @filter.( ctx, original_circuit_options ) # returns {new_ctx}.
       end
-
-      class Scoped
-        def initialize(filter)
-          @filter = filter
-        end
-
-        def call(original_ctx, circuit_options)
-          Trailblazer::Context( # TODO: make this interchangeable so we can work on faster contexts?
-            @filter.(original_ctx, **circuit_options)
-          )
-        end
-      end
-    end
-
-    module DSL
-      # The returned filter compiles a new hash for Scoped/Unscoped that only contains
-      # the desired i/o variables.
-      def self.filter_from_dsl(map)
-        hsh = DSL.hash_for(map)
-
-        ->(incoming_ctx, kwargs) { Hash[hsh.collect { |from_name, to_name| [to_name, incoming_ctx[from_name]] }] }
-      end
-
-      def self.hash_for(ary)
-        return ary if ary.instance_of?(::Hash)
-        Hash[ary.collect { |name| [name, name] }]
-      end
     end
 
     # TaskWrap step to compute the outgoing {Context} from the wrapped task.
     # This allows renaming, filtering, hiding, of the options returned from the wrapped task.
     class Output
-      def initialize(filter)
+      def initialize(filter, id:)
         @filter = filter
+        @id     = id
       end
 
       # Runs your filter and replaces the ctx in `wrap_ctx[:return_args]` with the filtered one.
-      def call( (wrap_ctx, original_args), **circuit_options )
+      def call(wrap_ctx, original_args)
         (original_ctx, original_flow_options), original_circuit_options = original_args
 
-        returned_ctx, _ = wrap_ctx[:return_args] # this is the Context returned from `call`ing the task.
-        original_ctx    = wrap_ctx[:vm_original_ctx]
+        returned_ctx, _ = wrap_ctx[:return_args]  # this is the Context returned from {call}ing the wrapped user task.
+        original_ctx    = wrap_ctx[@id]           # grab the original ctx from before which was set in the {:input} filter.
         # let user compute the output.
         output_ctx = @filter.(original_ctx, returned_ctx, **original_circuit_options)
 
         wrap_ctx = wrap_ctx.merge( return_args: [output_ctx, original_flow_options] )
 
         # and then pass on the "new" context.
-        return Trailblazer::Activity::Right, [ wrap_ctx, original_args ]
-      end
-
-      private
-
-      # Merge the resulting {@filter.()} hash back into the original ctx.
-      # DISCUSS: do we need the original_ctx as a filter argument?
-      class Unscoped
-        def initialize(filter)
-          @filter = filter
-        end
-
-        def call(original_ctx, new_ctx, **circuit_options)
-          original_ctx.merge(
-            @filter.(new_ctx, **circuit_options)
-          )
-        end
+        return wrap_ctx, original_args
       end
     end
   end # Wrap

data/lib/trailblazer/activity/testing.rb

@@ -1,32 +1,74 @@
 # DISCUSS: move to trailblazer-activity-test ?
 
 # Helpers to quickly create steps and tasks.
-module Trailblazer::Activity::Testing
-  # Creates a module with one step method for each name.
-  #
-  # @example
-  #   extend T.def_steps(:create, :save)
-  def self.def_steps(*names)
-    Module.new do
-      names.each do |name|
-        define_method(name) do | ctx, ** |
-          ctx[:seq] << name
-          ctx.key?(name) ? ctx[name] : true
+module Trailblazer
+  module Activity::Testing
+    # Creates a module with one step method for each name.
+    #
+    # @example
+    #   extend T.def_steps(:create, :save)
+    def self.def_steps(*names)
+      Module.new do
+        module_function
+        names.each do |name|
+          define_method(name) do | ctx, ** |
+            ctx[:seq] << name
+            ctx.key?(name) ? ctx[name] : true
+          end
         end
       end
     end
-  end
 
-  # Creates a method instance with a task interface.
-  #
-  # @example
-  #   task task: T.def_task(:create)
-  def self.def_task(name)
-    Module.new do
-      define_singleton_method(name) do | (ctx, flow_options), ** |
-        ctx[:seq] << name
-        return Trailblazer::Activity::Right, [ctx, flow_options]
+    # Creates a method instance with a task interface.
+    #
+    # @example
+    #   task task: T.def_task(:create)
+    def self.def_task(name)
+      Module.new do
+        define_singleton_method(name) do | (ctx, flow_options), ** |
+          ctx[:seq] << name
+          return Activity::Right, [ctx, flow_options]
+        end
+      end.method(name)
+    end
+
+    def self.def_tasks(*names)
+      Module.new do
+        module_function
+        names.each do |name|
+          define_method(name) do | (ctx, flow_options), ** |
+            ctx[:seq] << name
+            result = ctx.key?(name) ? ctx[name] : true
+
+            return (result ? Activity::Right : Activity::Left), [ctx, flow_options]
+          end
+        end
       end
-    end.method(name)
+    end
+
+    module Assertions
+        def Cct(activity)
+          cct = Trailblazer::Developer::Render::Circuit.(activity)
+        end
+
+        # Tests {:circuit} and {:outputs} fields so far.
+        def assert_process_for(process, *args)
+          semantics, circuit = args[0..-2], args[-1]
+
+          inspects = semantics.collect { |semantic| %{#<struct Trailblazer::Activity::Output signal=#<Trailblazer::Activity::End semantic=#{semantic.inspect}>, semantic=#{semantic.inspect}>} }
+
+          process.to_h[:outputs].inspect.must_equal %{[#{inspects.join(", ")}]}
+
+          assert_circuit(process, circuit)
+
+          process
+        end
+
+        def assert_circuit(schema, circuit)
+          cct = Cct(schema)
+          cct = cct.gsub("#<Trailblazer::Activity::TaskBuilder::Task user_proc=", "<*")
+          cct.must_equal %{#{circuit}}
+        end
+    end
   end
 end

data/lib/trailblazer/activity/trace.rb

@@ -1,77 +1,123 @@
 module Trailblazer
-  class Activity < Module   # Trace#call will call the activities and trace what steps are called, options passed,
-    # and the order and nesting.
-    #
-    #   stack, _ = Trailblazer::Activity::Trace.(activity, activity[:Start], { id: 1 })
-    #   puts Trailblazer::Activity::Present.tree(stack) # renders the trail.
-    #
-    # Hooks into the taskWrap.
+  class Activity
     module Trace
       class << self
-        # {:argumenter} API
-        # FIXME: needs Introspect.arguments_for_call
-        # FIXME: needs TaskWrap.arguments_for_call
+        # Public entry point to activate tracing when running {activity}.
+        def call(activity, (ctx, flow_options), circuit_options={})
+          activity, (ctx, flow_options), circuit_options = Trace.arguments_for_call( activity, [ctx, flow_options], circuit_options ) # only run once for the entire circuit!
+
+          signal, (ctx, flow_options) = Activity::TaskWrap.invoke(activity, [ctx, flow_options], circuit_options)
+
+          return flow_options[:stack], signal, [ctx, flow_options]
+        end
+
+        alias_method :invoke, :call
+
         def arguments_for_call(activity, (options, flow_options), **circuit_options)
           tracing_flow_options = {
-            stack:         Trace::Stack.new,
+            stack: Trace::Stack.new,
           }
 
           tracing_circuit_options = {
-            wrap_runtime:  ::Hash.new(Trace.wirings), # FIXME: this still overrides existing :wrap_runtime.
+            wrap_runtime:  ::Hash.new(Trace.merge_plan), # DISCUSS: this overrides existing {:wrap_runtime}.
           }
 
           return activity, [ options, tracing_flow_options.merge(flow_options) ], circuit_options.merge(tracing_circuit_options)
         end
+      end
 
-        def call(activity, (options, flow_options), circuit_options={})
-          activity, (options, flow_options), circuit_options = Trace.arguments_for_call( activity, [options, flow_options], circuit_options ) # only run once for the entire circuit!
+      module_function
+      # Insertions for the trace tasks that capture the arguments just before calling the task,
+      # and before the TaskWrap is finished.
+      #
+      # @private
+      def merge_plan
+        TaskWrap::Pipeline::Merge.new(
+          [TaskWrap::Pipeline.method(:insert_before), "task_wrap.call_task", ["task_wrap.capture_args",   Trace.method(:capture_args)]],
+          [TaskWrap::Pipeline.method(:append),        nil,                   ["task_wrap.capture_return", Trace.method(:capture_return)]],
+        )
+      end
 
-          last_signal, (options, flow_options) =
-            Activity::TaskWrap.invoke(activity, [options, flow_options], circuit_options)
+      # taskWrap step to capture incoming arguments of a step.
+      def capture_args(wrap_config, original_args)
+        original_args = capture_for(wrap_config[:task], *original_args)
 
-          return flow_options[:stack], last_signal, [options, flow_options]
-        end
+        return wrap_config, original_args
+      end
 
-        alias_method :invoke, :call
+      # taskWrap step to capture outgoing arguments from a step.
+      def capture_return(wrap_config, original_args)
+        (original_options, original_flow_options, _) = original_args[0]
 
-        # Insertions for the trace tasks that capture the arguments just before calling the task,
-        # and before the TaskWrap is finished.
-        #
-        # Note that the TaskWrap steps are implemented in Activity::TaskWrap::Trace.
-        #
-        # @private
-        def wirings
-          Module.new do
-            extend Activity::Path::Plan()
-
-            task TaskWrap::Trace.method(:capture_args),   id: "task_wrap.capture_args",   before: "task_wrap.call_task"
-            task TaskWrap::Trace.method(:capture_return), id: "task_wrap.capture_return", before: "End.success", group: :end
-          end
-        end
-      end
+        original_flow_options[:stack] << Entity::Output.new(
+          wrap_config[:task], {}, wrap_config[:return_signal]
+        ).freeze
+
+        original_flow_options[:stack].unindent!
 
-      Entity = Struct.new(:task, :activity, :data)
-      class Entity::Input < Entity
+
+        return wrap_config, original_args
       end
 
-      class Entity::Output < Entity
+      # It's important to understand that {flow[:stack]} is mutated by design. This is needed so
+      # in case of exceptions we still have a "global" trace - unfortunately Ruby doesn't allow
+      # us a better way.
+      def capture_for(task, (ctx, flow), activity:, **circuit_options)
+        flow[:stack].indent!
+
+        flow[:stack] << Entity::Input.new(
+          task, activity, [ctx, ctx.inspect]
+        ).freeze
+
+        return [ctx, flow], circuit_options.merge(activity: activity)
       end
 
-      class Task < Array
+      # Structures used in {capture_args} and {capture_return}.
+      # These get pushed onto one {Level} in a {Stack}.
+      #
+      #   Level[
+      #     Level[              ==> this is a scalar task
+      #       Entity::Input
+      #       Entity::Output
+      #     ]
+      #     Level[              ==> nested task
+      #       Entity::Input
+      #       Level[
+      #         Entity::Input
+      #         Entity::Output
+      #       ]
+      #       Entity::Output
+      #     ]
+      #   ]
+      Entity         = Struct.new(:task, :activity, :data)
+      Entity::Input  = Class.new(Entity)
+      Entity::Output = Class.new(Entity)
+
+      class Level < Array
         def inspect
-          %{<Task>#{super}}
+          %{<Level>#{super}}
+        end
+
+        # @param level {Trace::Level}
+        def self.input_output_nested_for_level(level)
+          input  = level[0]
+          output = level[-1]
+
+          output, nested = output.is_a?(Entity::Output) ? [output, level-[input, output]] : [nil, level[1..-1]]
+
+          return input, output, nested
         end
       end
 
       # Mutable/stateful per design. We want a (global) stack!
       class Stack
         def initialize
-          @nested  = []
+          @nested  = Level.new
           @stack   = [ @nested ]
         end
 
         def indent!
-          current << indented = Task.new
+          current << indented = Level.new
           @stack << indented
         end
 
@@ -88,6 +134,7 @@ module Trailblazer
         end
 
         private
+
         def current
           @stack.last
         end