trailblazer-endpoint 0.0.2 → 0.0.7

data/lib/trailblazer/endpoint/builder.rb

@@ -35,7 +35,7 @@ module Trailblazer
         def endpoint_for(id:, builder:, default_options:, **config)
           options = build_options_for(builder: builder, **config)
 
-          return id, Trailblazer::Endpoint.build(default_options.merge(options[:options_for_build]), &options[:protocol_block])
+          return id, Trailblazer::Endpoint.build(default_options.merge(options[:options_for_build]).merge(protocol_block: options[:protocol_block]))
         end
 
         # {dsl_options} being something like

data/lib/trailblazer/endpoint/controller.rb

@@ -0,0 +1,223 @@
+module Trailblazer
+  class Endpoint
+    module Controller
+      def self.extended(extended)
+        extended.extend Trailblazer::Endpoint::Options::DSL           # ::directive
+        extended.extend Trailblazer::Endpoint::Options::DSL::Inherit
+        extended.extend Trailblazer::Endpoint::Options                # ::options_for
+        extended.extend DSL::Endpoint
+
+        extended.include InstanceMethods # {#endpoint_for}
+
+        # DISCUSS: hmm
+        extended.directive :generic_options,          ->(*) { Hash.new } # for Controller::endpoint
+        extended.directive :options_for_flow_options, ->(*) { Hash.new }
+        extended.directive :options_for_endpoint,     ->(*) { Hash.new }
+        extended.directive :options_for_domain_ctx,   ->(*) { Hash.new }
+      end
+
+      # @experimental
+      # TODO: test application_controller with and without dsl/api
+
+      def self.module(framework: :rails, api: false, dsl: false, application_controller: false)
+        if application_controller && !api && !dsl # FIXME: not tested! this is useful for an actual AppController with block_options or flow_options settings, "globally"
+          Module.new do
+            def self.included(includer)
+              includer.extend(Controller) # only ::directive and friends.
+            end
+          end
+        elsif api
+          Module.new do
+            @application_controller = application_controller
+            def self.included(includer)
+              if @application_controller
+                includer.extend Controller
+              end
+              includer.include(InstanceMethods::API)
+            end
+          end
+        elsif dsl
+          Module.new do
+            @application_controller = application_controller
+            def self.included(includer)
+              if @application_controller
+                includer.extend Controller
+              end
+              includer.include Trailblazer::Endpoint::Controller::InstanceMethods::DSL
+              includer.include Trailblazer::Endpoint::Controller::Rails
+              includer.extend Trailblazer::Endpoint::Controller::Rails::DefaultBlocks
+              includer.extend Trailblazer::Endpoint::Controller::Rails::DefaultParams
+              includer.include Trailblazer::Endpoint::Controller::Rails::Process
+            end
+          end # Module
+        else
+          raise
+        end
+      end
+
+      module Rails
+        module Process
+          def send_action(action_name)
+      puts "@@@@@>>>>>>> #{action_name.inspect}"
+
+            dsl = send(action_name) # call the actual controller action.
+
+            options, block_options = dsl.to_args(self.class.options_for(:options_for_block_options, controller: self)) # {success_block:, failure_block:, protocol_failure_block:}
+            # now we know the authorative blocks
+
+            Controller.advance_endpoint_for_controller(**options, block_options: block_options, config_source: self.class, controller: self)
+          end
+
+        end # Process
+
+        # The three default handlers for {Endpoint::with_or_etc}
+        # @experimental
+        module DefaultBlocks
+          def self.extended(extended)
+            extended.directive :options_for_block_options, Controller.method(:options_for_block_options)
+          end
+        end
+        # @experimental
+        module DefaultParams
+          def self.extended(extended)
+            extended.directive :options_for_domain_ctx, ->(ctx, controller:, **) { {params: controller.params} }
+          end
+        end
+
+      end # Rails
+
+      module DSL
+        module Endpoint
+          def self.extended(extended)
+            extended.directive(:endpoints, ->(*) { {} })
+          end
+
+          # Builds and registers an endpoint in a controller class.
+          def endpoint(name, **options, &block)
+            options = options.merge(protocol_block: block) if block_given?
+
+            return generic_endpoint_config(**name, **options) if name.is_a?(Hash)
+            build_endpoint(name, **options)
+          end
+
+          # Configures generic {:adapter}, {:protocol}, etc.
+          def generic_endpoint_config(**options)
+            self.singleton_class.define_method :generic_options do |ctx,**|
+              {
+                **options
+              }
+            end
+
+            directive :generic_options, method(:generic_options) # FIXME: do we need this?
+          end
+
+          def build_endpoint(name, domain_activity: name, **options)
+            build_options = options_for(:generic_options, {}).merge(domain_activity: domain_activity, **options) # DISCUSS: why don't we add this as another directive option/step?
+
+            endpoint = Trailblazer::Endpoint.build(build_options)
+
+            directive :endpoints, ->(*) { {name.to_s => endpoint} }
+          end
+
+        end
+      end
+
+      module InstanceMethods
+
+        def endpoint_for(name, config_source: self.class)
+          config_source.options_for(:endpoints, {}).fetch(name.to_s) # TODO: test non-existant endpoint
+        end
+
+        module DSL
+          def endpoint(name, **action_options, &block)
+            action_options = {controller: self}.merge(action_options) # FIXME: redundant with {API#endpoint}
+
+            endpoint = endpoint_for(name)
+
+            invoke_endpoint_with_dsl(endpoint: endpoint, **action_options, &block)
+          end
+
+          def invoke_endpoint_with_dsl(options, &block)
+            _dsl = Trailblazer::Endpoint::DSL::Runtime.new(options, block) # provides #Or etc, is returned to {Controller#call}
+          end
+        end
+
+        module API
+          def endpoint(name, config_source: self.class, **action_options)
+            endpoint = endpoint_for(name, config_source: config_source)
+
+            action_options = {controller: self}.merge(action_options) # FIXME: redundant with {InstanceMethods#endpoint}
+
+            block_options = config_source.options_for(:options_for_block_options, **action_options)
+            block_options = Trailblazer::Endpoint::Options.merge_with(action_options, block_options)
+
+            signal, (ctx, _) = Trailblazer::Endpoint::Controller.advance_endpoint_for_controller(
+              endpoint:       endpoint,
+              block_options:  block_options,
+              config_source:  config_source,
+              **action_options
+            )
+
+            ctx
+          end
+        end # API
+      end
+
+
+      def self.advance_endpoint_for_controller(endpoint:, block_options:, **action_options)
+        domain_ctx, endpoint_options, flow_options = compile_options_for_controller(**action_options) # controller-specific, get from directives.
+
+        endpoint_options = endpoint_options.merge(action_options) # DISCUSS
+
+        Endpoint::Controller.advance_endpoint(
+          endpoint:      endpoint,
+          block_options: block_options,
+
+          domain_ctx:       domain_ctx,
+          endpoint_options: endpoint_options,
+          flow_options:     flow_options,
+        )
+      end
+
+      def self.compile_options_for_controller(options_for_domain_ctx: nil, config_source:, **action_options)
+        flow_options     = config_source.options_for(:options_for_flow_options, **action_options)
+        endpoint_options = config_source.options_for(:options_for_endpoint, **action_options) # "class level"
+        domain_ctx       = options_for_domain_ctx || config_source.options_for(:options_for_domain_ctx, **action_options)
+
+        return domain_ctx, endpoint_options, flow_options
+      end
+
+      # Ultimate low-level entry point.
+      # Remember that you don't _have_ to use Endpoint.with_or_etc to invoke an endpoint.
+      def self.advance_endpoint(endpoint:, block_options:, domain_ctx:, endpoint_options:, flow_options:)
+
+        # build Context(ctx),
+        args, _ = Trailblazer::Endpoint.arguments_for(
+          domain_ctx:   domain_ctx,
+          flow_options: flow_options,
+          **endpoint_options,
+        )
+
+        signal, (ctx, _ ) = Trailblazer::Endpoint.with_or_etc(
+          endpoint,
+          args, # [ctx, flow_options]
+
+          **block_options,
+          # success_block: success_block,
+          # failure_block: failure_block,
+          # protocol_failure_block: protocol_failure_block,
+        )
+      end
+
+      # Default blocks for the {Adapter}.
+      def self.options_for_block_options(ctx, controller:, **)
+        {
+          success_block:          ->(ctx, endpoint_ctx:, **) { controller.head 200 },
+          failure_block:          ->(ctx, **) { controller.head 422 },
+          protocol_failure_block: ->(ctx, endpoint_ctx:, **) { controller.head endpoint_ctx[:status] }
+        }
+      end
+
+    end # Controller
+  end
+end

data/lib/trailblazer/endpoint/dsl.rb

@@ -0,0 +1,31 @@
+module Trailblazer
+  class Endpoint
+    module DSL
+      # Run before the endpoint is invoked. This collects the blocks from the controller.
+      class Runtime < Struct.new(:options, :success_block, :failure_block, :protocol_failure_block)
+
+        def failure(&block)
+          self.failure_block = block
+          self
+        end
+
+        alias_method :Or, :failure
+
+        def protocol_failure(&block)
+          self.protocol_failure_block = block
+          self
+        end
+
+        # #call
+        def to_args(default_block_options)
+          return options,
+          default_block_options.merge( # this adds :invoke.
+            success_block:          success_block || default_block_options[:success_block],
+            failure_block:          failure_block || default_block_options[:failure_block],
+            protocol_failure_block: protocol_failure_block || default_block_options[:protocol_failure_block]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/endpoint/options.rb

@@ -0,0 +1,92 @@
+# DISCUSS: the generic inheritance/Options logic might be extracted to trailblazer-config or something.
+#          it is completely independent and could be helpful for many other configurations.
+module Trailblazer
+  class Endpoint
+    module Options
+      module DSL
+        def directive(directive_name, *callables, inherit: superclass)
+          options = {}
+
+          if inherit
+            options[:base_class] = instance_variable_get(:@normalizers)[directive_name] || Trailblazer::Activity::Path # FIXME
+          end
+
+          @normalizers[directive_name] = Trailblazer::Endpoint::Normalizer.Options(directive_name, *callables, **options) # DISCUSS: allow multiple calls?
+        end
+
+        # Called in {Endpoint::Controller}.
+        def self.extended(extended) # TODO: let's hope this is only called once per hierachy :)
+          extended.instance_variable_set(:@normalizers, {})
+        end
+
+        module Inherit
+          def inherited(subclass)
+            super
+
+            subclass.instance_variable_set(:@normalizers, @normalizers.dup)
+          end
+        end
+      end
+
+      def options_for(directive_name, runtime_options)
+        normalizer = @normalizers.fetch(directive_name)
+
+        ctx = Trailblazer::Context(runtime_options, {})
+
+        # signal, (ctx, ) = Trailblazer::Developer.wtf?(normalizer, [ctx])
+        signal, (ctx, ) = Trailblazer::Activity::TaskWrap.invoke(normalizer, [ctx])
+
+        _, options = ctx.decompose
+        options
+      end
+
+
+      # Merge {merged} into {hash}, but only keys that exist in {hash}.
+      def self.merge_with(merged, hash)
+        keys = hash.keys
+        merged = keys.collect { |key| merged.key?(key) ? [key, merged[key]] : nil }.compact.to_h
+        hash.merge(merged)
+      end
+    end # Options
+
+    module Normalizer
+      def self.Options(directive_name, *callables, base_class: Trailblazer::Activity::Path)
+        normalizer = Class.new(base_class) do
+        end
+
+        Normalizer.add(normalizer, directive_name, callables)
+      end
+
+      def self.DefaultToEmptyHash(config_name)
+        -> (ctx, **) { ctx[config_name] ||= {} }
+      end
+
+      def self.add_normalizer!(target, normalizer, config)
+        normalizer = Normalizer.add(normalizer, target, config) # add configure steps for {subclass} to the _new_ normalizer.
+        target.instance_variable_set(:@normalizer, normalizer)
+        target.instance_variable_set(:@config, config)
+      end
+
+      def self.add(normalizer, directive_name, options)
+        Class.new(normalizer) do
+          options.collect do |callable|
+            step task: Normalizer.CallDirective(callable, directive_name), id: "#{directive_name}=>#{callable}"
+          end
+        end
+      end
+
+      def self.CallDirective(callable, option_name)
+        ->((ctx, flow_options), *) {
+          config = callable.(ctx, **ctx) # e.g. ApplicationController.options_for_endpoint
+
+          # ctx[option_name] = ctx[option_name].merge(config)
+          config.each do |k, v|
+            ctx[k] = v
+          end
+
+          return Trailblazer::Activity::Right, [ctx, flow_options]
+        }
+      end
+    end # Normalizer
+  end
+end

data/lib/trailblazer/endpoint/protocol.rb

@@ -1,3 +1,5 @@
+require "trailblazer/activity/dsl/linear"
+
 module Trailblazer
   class Endpoint
     # The {Protocol} implements auth*, and calls the domain OP/WF.
@@ -16,18 +18,13 @@ module Trailblazer
       class Noop < Trailblazer::Activity::Railway
       end
 
-      class Failure < Trailblazer::Activity::End # DISCUSS: move to Act::Railway?
-        # class Authentication < Failure
-        # end
-      end
-
       def self._Path(semantic:, &block) # DISCUSS: the problem with Path currently is https://github.com/trailblazer/trailblazer-activity-dsl-linear/issues/27
-        Path(track_color: semantic, end_id: "End.#{semantic}", end_task: Failure.new(semantic: semantic), &block)
+        Path(track_color: semantic, end_id: "End.#{semantic}", end_task: Activity::End.new(semantic: semantic), &block)
       end
 
       step :authenticate, Output(:failure) => _Path(semantic: :not_authenticated) do
           # step :handle_not_authenticated
-        end
+      end
 
       step :policy, Output(:failure) => _Path(semantic: :not_authorized) do # user from cookie, etc
         # step :handle_not_authorized
@@ -43,8 +40,8 @@ module Trailblazer
       # termini for the Adapter this is the only way to get it working right now.
       # FIXME: is this really the only way to add an {End} to all this?
       @state.update_sequence do |sequence:, **|
-        sequence = Activity::Path::DSL.append_end(sequence, task: Failure.new(semantic: :not_found), magnetic_to: :not_found, id: "End.not_found")
-        sequence = Activity::Path::DSL.append_end(sequence, task: Failure.new(semantic: :invalid_data), magnetic_to: :invalid_data, id: "End.invalid_data")
+        sequence = Activity::Path::DSL.append_end(sequence, task: Activity::End.new(semantic: :not_found), magnetic_to: :not_found, id: "End.not_found")
+        sequence = Activity::Path::DSL.append_end(sequence, task: Activity::End.new(semantic: :invalid_data), magnetic_to: :invalid_data, id: "End.invalid_data")
 
         recompile_activity!(sequence)
 
@@ -116,7 +113,6 @@ module Trailblazer
           [[Trailblazer::Activity::TaskWrap::Pipeline.method(:insert_after), "task_wrap.call_task", ["endpoint.end_signal", method(:terminus_handler)]]]
         end
       end
-
-    end
+    end # Protocol
   end
 end

data/lib/trailblazer/endpoint/protocol/cipher.rb

@@ -0,0 +1,27 @@
+require "openssl"
+
+module Trailblazer
+  class Endpoint::Protocol
+    module Controller
+      module Cipher # FIXME: copied from Tyrant!
+        module_function
+
+        def encrypt_value(ctx, value:, cipher_key:, **)
+          cipher = OpenSSL::Cipher.new('DES-EDE3-CBC').encrypt
+          cipher.key = Digest::SHA1.hexdigest(cipher_key)[0..23] # ArgumentError: key must be 24 bytes
+          s = cipher.update(value) + cipher.final
+
+          ctx[:encrypted_value] = s.unpack('H*')[0].upcase
+        end
+
+        def decrypt_value(ctx, encrypted_value:, cipher_key:, **)
+          cipher = OpenSSL::Cipher.new('DES-EDE3-CBC').decrypt
+          cipher.key = Digest::SHA1.hexdigest(cipher_key)[0..23]
+          s = [encrypted_value].pack("H*").unpack("C*").pack("c*")
+
+          ctx[:decrypted_value] = cipher.update(s) + cipher.final
+        end
+      end # Cipher
+    end
+  end
+end

data/lib/trailblazer/endpoint/protocol/controller.rb

@@ -0,0 +1,93 @@
+module Trailblazer
+  class Endpoint::Protocol
+    # Deserialize incoming state.
+    # Serialize outgoing state.
+    # What else?
+    module Controller
+      module_function
+
+      def decrypt?(ctx, encrypted_resume_data:, **)
+        encrypted_resume_data
+      end
+
+      def deserialize_resume_data(ctx, decrypted_value:, **)
+        ctx[:resume_data] = JSON.parse(decrypted_value)
+      end
+
+      def deserialize_process_model?(ctx, process_model_from_resume_data:, **)
+        process_model_from_resume_data
+      end
+
+      def deserialize_process_model_id(ctx, resume_data:, **)
+        ctx[:process_model_id] = resume_data["id"] # DISCUSS: overriding {:process_model_id}?
+      end
+
+      def encrypt?(ctx, domain_ctx:, **)
+        ctx[:suspend_data] = domain_ctx[:suspend_data]
+      end
+
+      def serialize_suspend_data(ctx, suspend_data:, **)
+        ctx[:serialized_suspend_data] = JSON.dump(suspend_data)
+      end
+
+      def copy_suspend_data_to_endpoint_ctx(ctx, domain_ctx:, **)
+        ctx[:suspend_data] = domain_ctx[:suspend_data]
+      end
+
+# FIXME: use Model() mechanics.
+      def deserialize_process_model_id_from_resume_data(ctx, resume_data:, **)
+        # DISCUSS: should we warn when overriding an existing {process_model_id}?
+        ctx[:process_model_id] = resume_data["id"] # DISCUSS: overriding {:process_model_id}? # FIXME: stolen from Advance___::Controller
+      end
+
+      def insert_deserialize_steps!(activity, deserialize_before: :policy)
+        activity.module_eval do
+          step Controller.method(:decrypt?), id: :decrypt?, before: deserialize_before # error out if no serialized_resume_data given.
+          step Controller::Cipher.method(:decrypt_value), id: :decrypt,
+              input: {cipher_key: :cipher_key, encrypted_resume_data: :encrypted_value}    , before: deserialize_before,
+              # Output(:failure) => Track(:success),
+              Output(:success) => Path(connect_to: Track(:success), track_color: :deserialize, before: deserialize_before) do # usually, Path goes into {policy}
+
+            step Controller.method(:deserialize_resume_data), id: :deserialize_resume_data
+            # DISCUSS: unmarshall?
+            # step Controller.method(:deserialize_process_model_id?), id: :deserialize_process_model_id?, activity.Output(Trailblazer::Activity::Left, :failure) => activity.Id(around_activity_id)
+            # step Controller.method(:deserialize_process_model_id), id: :deserialize_process_model_id
+
+            step ->(*) { true } # FIXME: otherwise we can't insert an element AFTER :deserialize_resume_data
+          end
+        end
+      end
+
+      def insert_serialize_steps!(activity, serialize_after: :domain_activity)
+        activity.module_eval do
+            # FIXME: reverse order for insertion
+          step Controller::Cipher.method(:encrypt_value), id: :encrypt                                                , after: serialize_after,
+              input: {cipher_key: :cipher_key, serialized_suspend_data: :value}, output: {encrypted_value: :encrypted_suspend_data}
+          step Controller.method(:serialize_suspend_data), id: :serialize_suspend_data                                , after: serialize_after
+          pass Controller.method(:copy_suspend_data_to_endpoint_ctx), id: :copy_suspend_data_to_endpoint_ctx          , after: serialize_after
+        end
+      end
+
+      # Insert the "experimental" {find_process_model} steps
+      def insert_find_process_model!(protocol, **options)
+        protocol.module_eval do
+          step Subprocess(FindProcessModel), Output(:failure) => End(:not_found),
+          id: :find_process_model,
+          **options
+            # after: :authenticate
+        end
+
+        insert_copy_to_domain_ctx!(protocol, :process_model => :model)
+      end
+
+      def insert_copy_to_domain_ctx!(protocol, variables)
+        variables.each do |original_name, domain_name|
+          protocol.module_eval do
+            pass ->(ctx, domain_ctx:, **) { domain_ctx[domain_name] = ctx[original_name] if ctx.key?(original_name) },
+              id: :"copy_[#{original_name.inspect}]_to_domain_ctx[#{domain_name.inspect}]", before: :domain_activity
+          end
+        end
+      end
+    end
+  end
+end