trailblazer-future 2.1.0.rc1

data/lib/trailblazer/v2_1/operation/model.rb

@@ -0,0 +1,50 @@
+class Trailblazer::V2_1::Operation
+  def self.Model(model_class, action=nil, find_by_key=nil)
+    task = Trailblazer::V2_1::Activity::TaskBuilder::Binary(Model.new)
+
+    extension = Trailblazer::V2_1::Activity::TaskWrap::Merge.new(
+      Wrap::Inject::Defaults(
+        "model.class"          => model_class,
+        "model.action"         => action,
+        "model.find_by_key"    => find_by_key
+      )
+    )
+
+    { task: task, id: "model.build", Trailblazer::V2_1::Activity::DSL::Extension.new(extension) => true }
+  end
+
+  class Model
+    def call(options, params:,  **)
+      builder                 = Model::Builder.new
+      options[:model]         = model = builder.call(options, params)
+      options["result.model"] = result = Result.new(!model.nil?, {})
+
+      result.success?
+    end
+
+    class Builder
+      def call(options, params)
+        action        = options["model.action"] || :new
+        model_class   = options["model.class"]
+        find_by_key   = options["model.find_by_key"] || :id
+        action        = :pass_through unless %i[new find_by].include?(action)
+
+        send("#{action}!", model_class, params, options["model.action"], find_by_key)
+      end
+
+      def new!(model_class, params, *)
+        model_class.new
+      end
+
+      # Doesn't throw an exception and will return false to divert to Left.
+      def find_by!(model_class, params, action, find_by_key, *)
+        model_class.find_by(find_by_key.to_sym => params[find_by_key])
+      end
+
+      # Call any method on the model class and pass find_by_key, for example find(params[:id]).
+      def pass_through!(model_class, params, action, find_by_key, *)
+        model_class.send(action, params[find_by_key])
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/module.rb

@@ -0,0 +1,29 @@
+module Trailblazer::V2_1::Operation::Module
+  def self.included(base)
+    base.extend ClassMethods
+    base.extend Included
+  end
+
+  module Included # TODO: use representable's inheritance mechanism.
+    def included(base)
+      super
+      instructions.each { |cfg|
+        method  = cfg[0]
+        args    = cfg[1].dup
+        block   = cfg[2]
+        # options = args.extract_options!.dup # we need to duplicate options has as AM::Validations messes it up later.
+
+        base.send(method, *args, &block) } # property :name, {} do .. end
+    end
+  end
+
+  module ClassMethods
+    def method_missing(method, *args, &block)
+      instructions << [method, args, block]
+    end
+
+    def instructions
+      @instructions ||= []
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/nested.rb

@@ -0,0 +1,98 @@
+# per default, everything we pass into a circuit is immutable. it's the ops/act's job to allow writing (via a Context)
+module Trailblazer::V2_1
+  class Operation
+    # {Nested} macro.
+    def self.Nested(callable, id: "Nested(#{callable})", input: nil, output: nil)
+      task_wrap_extensions        = Module.new do
+        extend Activity::Path::Plan()
+      end
+
+      input_output = Nested.input_output_extensions_for(input, output) # TODO: deprecate this?
+
+      task, operation, is_dynamic = Nested.build(callable)
+
+      if is_dynamic
+        task_wrap_extensions.task task.method(:compute_nested_activity), id: ".compute_nested_activity",  after: "Start.default", group: :start
+        task_wrap_extensions.task task.method(:compute_return_signal),   id: ".compute_return_signal",    after: "task_wrap.call_task"
+      end
+
+      options = {
+        task:      task,
+        id:        id,
+        Trailblazer::V2_1::Activity::DSL::Extension.new(Trailblazer::V2_1::Activity::TaskWrap::Merge.new(task_wrap_extensions)) => true,
+        outputs:   operation.outputs,
+      }.merge(input_output)
+    end
+
+    # @private
+    module Nested
+      def self.input_output_extensions_for(input, output)
+        return {} unless input || output
+
+        input  = input  || ->(original_ctx, **) { original_ctx }
+        output = output || ->(new_ctx, **)      { new_ctx.decompose.last } # merges "mutable" part into original, since it's in Unscoped.
+
+        {
+          Activity::TaskWrap::VariableMapping(input: input, output: output) => true
+        }
+      end
+
+      # DISCUSS: use builders here?
+      def self.build(nested_operation)
+        return dynamic = Dynamic.new(nested_operation), dynamic, true unless nestable_object?(nested_operation)
+
+        # The returned {Nested} instance is a valid circuit element and will be `call`ed in the circuit.
+        # It simply returns the nested activity's `signal,options,flow_options` return set.
+        # The actual wiring - where to go with that - is done by the step DSL.
+        return nested_operation, nested_operation, false
+      end
+
+      def self.nestable_object?(object)
+        object.is_a?( Trailblazer::V2_1::Activity::Interface )
+      end
+
+      def self.operation_class
+        Operation
+      end
+
+      # For dynamic `Nested`s that do not expose an {Activity} interface.
+      # Since we do not know its outputs, we have to map them to :success and :failure, only.
+      #
+      # This is what {Nested} in 2.0 used to do, where the outcome could only be true/false (or success/failure).
+      class Dynamic
+        def initialize(nested_activity)
+          @nested_activity = Trailblazer::V2_1::Option::KW(nested_activity)
+          @outputs         = {
+            :success => Activity::Output( Railway::End::Success.new(semantic: :success), :success ),
+            :failure => Activity::Output( Railway::End::Failure.new(semantic: :failure), :failure ),
+          }
+        end
+
+        attr_reader :outputs
+
+        # TaskWrap step.
+        def compute_nested_activity((wrap_ctx, original_args), **circuit_options)
+          (ctx,), original_circuit_options = original_args
+
+          # TODO: evaluate the option to get the actual "object" to call.
+          activity = @nested_activity.call(ctx, original_circuit_options)
+
+          # Overwrite :task so task_wrap.call_task will call this activity.
+          # This is a trick so we don't have to repeat logic from #call_task here.
+          wrap_ctx[:task] = activity
+
+          return Activity::Right, [wrap_ctx, original_args]
+        end
+
+        def compute_return_signal((wrap_ctx, original_args), **circuit_options)
+          # Translate the genuine nested signal to the generic Dynamic end (success/failure, only).
+          # Note that here we lose information about what specific event was emitted.
+          wrap_ctx[:return_signal] = wrap_ctx[:return_signal].kind_of?(Railway::End::Success) ?
+            @outputs[:success].signal : @outputs[:failure].signal
+
+          return Activity::Right, [wrap_ctx, original_args]
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/persist.rb

@@ -0,0 +1,14 @@
+module Trailblazer::V2_1
+  class Operation
+    module Contract
+      def self.Persist(method: :save, name: "default")
+        path = "contract.#{name}"
+        step = ->(options, **) { options[path].send(method) }
+
+        task = Activity::TaskBuilder::Binary( step )
+
+        { task: task, id: "persist.save" }
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/policy.rb

@@ -0,0 +1,44 @@
+class Trailblazer::V2_1::Operation
+  module Policy
+    # Step: This generically `call`s a policy and then pushes its result to `options`.
+    # You can use any callable object as a policy with this step.
+    class Eval
+      def initialize(name:nil, path:nil)
+        @name = name
+        @path = path
+      end
+
+      # incoming low-level {Task API}.
+      # outgoing Task::Binary API.
+      def call((options, flow_options), **circuit_options)
+        condition = options[ @path ] # this allows dependency injection.
+        result    = condition.( [options, flow_options], **circuit_options )
+
+        options["policy.#{@name}"]        = result["policy"] # assign the policy as a skill.
+        options["result.policy.#{@name}"] = result
+
+        # flow control
+        signal = result.success? ? Trailblazer::V2_1::Activity::Right : Trailblazer::V2_1::Activity::Left # since we & this, it's only executed OnRight and the return boolean decides the direction, input is passed straight through.
+
+        return signal, [ options, flow_options ]
+      end
+    end
+
+    # Adds the `yield` result to the pipe and treats it like a
+    # policy-compatible  object at runtime.
+    def self.step(condition, options, &block)
+      name = options[:name]
+      path = "policy.#{name}.eval"
+
+      task = Eval.new( name: name, path: path )
+
+      extension = Trailblazer::V2_1::Activity::TaskWrap::Merge.new(
+        Trailblazer::V2_1::Operation::Wrap::Inject::Defaults(
+          path => condition
+        )
+      )
+
+      { task: task, id: path, Trailblazer::V2_1::Activity::DSL::Extension.new(extension) => true }
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/public_call.rb

@@ -0,0 +1,55 @@
+module Trailblazer::V2_1
+  module Operation::PublicCall
+    # This is the outer-most public `call` method that gets invoked when calling `Create.()`.
+    # The signature of this is `params, options, *containers`. This was a mistake, as the
+    # first argument could've been part of `options` hash in the first place.
+    #
+    # Create.(params, runtime_data, *containers)
+    #   #=> Result<Context...>
+    #
+    # In workflows/Nested compositions, this method is not used anymore and it might probably
+    # get removed in future versions of TRB. Currently, we use Operation::__call__ as an alternative.
+    #
+    #
+    # @note Do not override this method as it will be removed in future versions. Also, you will break tracing.
+    # @return Operation::Railway::Result binary result object
+    def call(*args)
+      return call_with_circuit_interface(*args) if args.any? && args[0].is_a?(Array) # This is kind of a hack that could be well hidden if Ruby had method overloading. Goal is to simplify the call/__call__ thing as we're fading out Operation::call anyway.
+      call_with_public_interface(*args)
+    end
+
+    def call_with_public_interface(*args)
+      ctx = Operation::PublicCall.options_for_public_call(*args)
+
+      # call the activity.
+      # This will result in invoking {::call_with_circuit_interface}.
+      last_signal, (options, flow_options) = Activity::TaskWrap.invoke(self, [ctx, {}], {})
+
+      # Result is successful if the activity ended with an End event derived from Railway::End::Success.
+      Operation::Railway::Result(last_signal, options, flow_options)
+    end
+
+    # This interface is used for all nested OPs (and the outer-most, too).
+    def call_with_circuit_interface(args, circuit_options)
+      @activity.(
+        args,
+        circuit_options.merge(
+          exec_context: new
+        )
+      )
+    end
+
+    # Compile a Context object to be passed into the Activity::call.
+    # @private
+    def self.options_for_public_call(options={}, *containers)
+      # generate the skill hash that embraces runtime options plus potential containers, the so called Runtime options.
+      # This wrapping is supposed to happen once in the entire system.
+
+      hash_transformer = ->(containers) { containers[0].to_hash } # FIXME: don't transform any containers into kw args.
+
+      immutable_options = Trailblazer::V2_1::Context::ContainerChain.new( [options, *containers], to_hash: hash_transformer ) # Runtime options, immutable.
+
+      ctx = Trailblazer::V2_1::Context(immutable_options)
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/pundit.rb

@@ -0,0 +1,38 @@
+class Trailblazer::V2_1::Operation
+  module Policy
+    def self.Pundit(policy_class, action, name: :default)
+      Policy.step( Pundit.build(policy_class, action), name: name )
+    end
+
+    module Pundit
+      def self.build(*args, &block)
+        Condition.new(*args, &block)
+      end
+
+      # Pundit::Condition is invoked at runtime when iterating the pipe.
+      class Condition
+        def initialize(policy_class, action)
+          @policy_class, @action = policy_class, action
+        end
+
+        # Instantiate the actual policy object, and call it.
+        def call((options), *)
+          policy = build_policy(options)          # this translates to Pundit interface.
+          result!(policy.send(@action), policy)
+        end
+
+      private
+        def build_policy(options)
+          @policy_class.new(options[:current_user], options[:model])
+        end
+
+        def result!(success, policy)
+          data = { "policy" => policy }
+          data["message"] = "Breach" if !success # TODO: how to allow messages here?
+
+          Result.new(success, data)
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/railway.rb

@@ -0,0 +1,32 @@
+module Trailblazer::V2_1
+  # Operations is simply a thin API to define, inherit and run circuits by passing the options object.
+  # It encourages the linear railway style (http://trb.to/gems/workflow/circuit.html#operation) but can
+  # easily be extend for more complex workflows.
+  class Operation
+    # End event: All subclasses of End:::Success are interpreted as "success".
+    module Railway
+      # @param options Context
+      # @param end_event The last emitted signal in a circuit is usually the end event.
+      def self.Result(end_event, options, *)
+        Result.new(end_event.kind_of?(End::Success), options, end_event)
+      end
+
+      # The Railway::Result knows about its binary state, the context (data), and the last event in the circuit.
+      class Result < Result # Operation::Result
+        def initialize(success, data, event)
+          super(success, data)
+
+          @event = event
+        end
+
+        attr_reader :event
+      end
+
+      module End
+        class Success < Activity::End; end
+        class Failure < Activity::End; end
+      end
+
+    end # Railway
+  end
+end

data/lib/trailblazer/v2_1/operation/railway/fast_track.rb

@@ -0,0 +1,13 @@
+module Trailblazer::V2_1
+  module Operation::Railway
+    def self.fail!     ; Activity::Left  end
+    def self.pass!     ; Activity::Right end
+    def self.fail_fast!; Activity::FastTrack::FailFast end
+    def self.pass_fast!; Activity::FastTrack::PassFast end
+
+    module End
+      FailFast = Class.new(Operation::Railway::End::Failure)
+      PassFast = Class.new(Operation::Railway::End::Success)
+    end
+  end
+end

data/lib/trailblazer/v2_1/operation/railway/macaroni.rb

@@ -0,0 +1,23 @@
+module Trailblazer::V2_1
+  module Operation::Railway
+    # Call the user's steps with a differing API (inspired by Maciej Mensfeld) that
+    # only receives keyword args. The `options` keyword is the stateful context object
+    #
+    #   def my_step( params:, ** )
+    #   def my_step( params:, options:, ** )
+    module Macaroni
+      def self.call(user_proc)
+        Activity::TaskBuilder::Task.new( Trailblazer::V2_1::Option.build( Macaroni::Option, user_proc ), user_proc )
+      end
+
+      class Option < Trailblazer::V2_1::Option
+        # The Option#call! method prepares the arguments.
+        def self.call!(proc, options, *)
+          proc.( **options.to_hash.merge( options: options ) )
+        end
+      end
+    end
+
+    KwSignature = Macaroni
+  end
+end

data/lib/trailblazer/v2_1/operation/railway/normalizer.rb

@@ -0,0 +1,58 @@
+module Trailblazer::V2_1
+  module Operation::Railway
+    # The {Normalizer} is called for every DSL call (step/pass/fail etc.) and normalizes/defaults
+    # the user options, such as setting `:id`, connecting the task's outputs or wrapping the user's
+    # task via {TaskBuilder} in order to translate true/false to `Right` or `Left`.
+    #
+    # The Normalizer sits in the `@builder`, which receives all DSL calls from the Operation subclass.
+    module Normalizer
+      Pipeline = Activity::Magnetic::Normalizer::Pipeline.clone
+
+      Pipeline.module_eval do
+        # Handle the :override option which is specific to Operation.
+        def self.override(ctx, task:, options:, sequence_options:, **)
+          options, locals  = Activity::Magnetic::Options.normalize(options, [:override])
+          sequence_options = sequence_options.merge( replace: options[:id] ) if locals[:override]
+
+          ctx[:options], ctx[:sequence_options] = options, sequence_options
+        end
+
+        # TODO remove in 2.2
+        def self.deprecate_macro_with_two_args(ctx, task:, **)
+          return true unless task.is_a?(Array) # TODO remove in 2.2
+
+          ctx[:options] = Operation::DeprecatedMacro.( *task )
+        end
+
+        # TODO remove in 2.2
+        def self.deprecate_name(ctx, local_options:, connection_options:, **)
+          connection_options, deprecated_options = Activity::Magnetic::Options.normalize(connection_options, [:name])
+          local_options, _deprecated_options     = Activity::Magnetic::Options.normalize(local_options, [:name])
+
+          deprecated_options = deprecated_options.merge(_deprecated_options)
+
+          local_options = local_options.merge( name: deprecated_options[:name] ) if deprecated_options[:name]
+
+          local_options, locals = Activity::Magnetic::Options.normalize(local_options, [:name])
+          if locals[:name]
+            warn "[Trailblazer::V2_1] The :name option for #step, #success and #failure has been renamed to :id."
+            local_options = local_options.merge(id: locals[:name])
+          end
+
+          ctx[:local_options], ctx[:connection_options] = local_options, connection_options
+        end
+
+        def self.raise_on_missing_id(ctx, local_options:, **)
+          raise "No :id given for #{local_options[:task]}" unless local_options[:id]
+          true
+        end
+
+        # add more normalization tasks to the existing Magnetic::Normalizer::Pipeline
+        task Activity::TaskBuilder::Binary( method(:deprecate_macro_with_two_args) ), before: "split_options"
+        task Activity::TaskBuilder::Binary( method(:deprecate_name) )
+        task Activity::TaskBuilder::Binary( method(:override) )
+        task Activity::TaskBuilder::Binary( method(:raise_on_missing_id) )
+      end
+    end # Normalizer
+  end
+end