trailblazer-endpoint 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a13cc4ea9b50a656f620578a75ccd11aa01106bc22be8975e8758a660d1a13aa
+  data.tar.gz: 4c006bbfeab10458615ee658e862cf152b42b17f1c0d8302f9d1308b8cdc1425
+SHA512:
+  metadata.gz: 53dfeec3df63a69bbe4f481f58eaa6c71e32d55044066fda4eb7dc8579ef1b973079ff8fa6b7cbd7a6f4ce4ecdb767d25f37a6bf68eee99626557f1a1de2ab71
+  data.tar.gz: 99b9e753a78f182ad274c677aa9f1c33bc85fbd8ad4ce57c2574a4b4ef29d3400e3553c6484674e3d75cec41dcacea76f601db77aee7273fdd066ec3c41c17c7

data/CHANGES.md

@@ -0,0 +1,3 @@
+# 0.0.1
+
+* Provides very simple `Protocol` implementations for `Web` and `API`, same for `Adapter`.

data/Gemfile

@@ -0,0 +1,16 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in trailblazer.gemspec
+gemspec
+
+gem "multi_json"
+
+gem "minitest-line"
+
+# gem "trailblazer-activity", path: "../trailblazer-activity"
+# gem "trailblazer-activity-dsl-linear", path: "../trailblazer-activity-dsl-linear"
+# gem "trailblazer-operation", path: "../operation"
+
+gem "dry-validation"
+
+# gem "trailblazer-developer", path: "../trailblazer-developer"

data/README.md

@@ -0,0 +1,11 @@
+# Trailblazer::Endpoint
+
+*Generic HTTP handlers for operation results.*
+
+Decouple finding out *what happened* from *what to do*.
+
+t test/controllers/songs_controller_test.rb --backtrace
+
+## TODO
+
+* make travis build run `cd test/rails-app/ && rake`

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+task :default => [:test]
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/endpoint_test.rb', 'test/docs/*_test.rb', "test/adapter/*_test.rb"]
+  test.verbose = true
+end

data/lib/trailblazer-endpoint.rb

@@ -0,0 +1 @@
+require "trailblazer/endpoint"

data/lib/trailblazer/endpoint.rb

@@ -0,0 +1,133 @@
+module Trailblazer
+  class Endpoint
+    # Create an {Endpoint} class with the provided adapter and protocol.
+    # This builder also sets up taskWrap filters around the {domain_activity} execution.
+    def self.build(protocol:, adapter:, domain_activity:, scope_domain_ctx: true, domain_ctx_filter: nil,  &block)
+
+      # special considerations around the {domain_activity} and its taskWrap:
+      #
+      #  1. domain_ctx_filter (e.g. to filter {current_user})
+      #  2. :input (scope {:domain_ctx})
+      #  3. call (domain_activity)
+      #  4. :output
+      #  5. save return signal
+
+
+      extensions_options = {
+        extensions: [Trailblazer::Activity::TaskWrap::Extension(merge: Trailblazer::Endpoint::Protocol::Domain.extension_for_terminus_handler)],
+      }
+
+      # scoping: {:domain_ctx} becomes ctx
+      extensions_options.merge!(Endpoint.options_for_scope_domain_ctx) if scope_domain_ctx # TODO: test flag
+
+
+      domain_ctx_filter_callable = [[Trailblazer::Activity::TaskWrap::Pipeline.method(:insert_before), "task_wrap.call_task", ["endpoint.domain_ctx_filter", domain_ctx_filter]]]
+      extensions_options[:extensions] << Trailblazer::Activity::TaskWrap::Extension(merge: domain_ctx_filter_callable) if domain_ctx_filter
+
+      app_protocol = Class.new(protocol) do
+        step(Subprocess(domain_activity), {inherit: true, id: :domain_activity, replace: :domain_activity,
+
+# FIXME: where does this go?
+        }.
+          merge(extensions_options).
+          merge(instance_exec(&block)) # the block is evaluated in the {Protocol} context.
+        )
+      end
+
+      Class.new(adapter) do
+        step(Subprocess(app_protocol), {inherit: true, id: :protocol, replace: :protocol})
+      end # app_adapter
+
+    end
+
+    def self.options_for_scope_domain_ctx()
+      {
+        input:  ->(ctx, **) { ctx[:domain_ctx] }, # gets automatically Context()'ed.
+        output: ->(domain_ctx, **) { {:domain_ctx => domain_ctx} }
+      }
+    end
+
+    # Runtime
+    # Invokes the endpoint for you and runs one of the three outcome blocks.
+    def self.with_or_etc(activity, args, failure_block:, success_block:, protocol_failure_block:)
+      # args[1] = args[1].merge(focus_on: { variables: [:returned], steps: :invoke_workflow })
+
+      signal, (endpoint_ctx, _ ) = Trailblazer::Developer.wtf?(activity, args)
+
+      # this ctx is passed to the controller block.
+      block_ctx = endpoint_ctx[:domain_ctx].merge(endpoint_ctx: endpoint_ctx, signal: signal, errors: endpoint_ctx[:errors]) # DISCUSS: errors? status?
+
+      # if signal < Trailblazer::Activity::End::Success
+      adapter_terminus_semantic = signal.to_h[:semantic]
+
+      executed_block =
+        if adapter_terminus_semantic    == :success
+          success_block
+        elsif adapter_terminus_semantic == :fail_fast
+          protocol_failure_block
+        else
+          failure_block
+        end
+
+      executed_block.(block_ctx, **block_ctx)
+
+      # we return the original context???
+      return signal, [endpoint_ctx]
+    end
+
+    # def self.default_success_if(success_id)
+    #   ->(signal:, graph:, **) { signal[:lane_positions][suspend_activity].last == graph.find(success_id).task }
+    # end
+
+    #@ For WORKFLOW and operations. not sure this method will stay here.
+    def self.arguments_for(domain_ctx:, collaboration:, dictionary: collaboration.to_h[:dictionary], flow_options:, circuit_options: {}, **options)
+      domain_ctx      = Trailblazer::Context::IndifferentAccess.build(domain_ctx, {}, [domain_ctx, flow_options], circuit_options)
+
+      [
+        [
+          {
+              activity:                       collaboration,
+              domain_ctx:                     domain_ctx, # DISCUSS: is this where {:resume_data} comes in?
+              # process_model_class:            process_model_class,
+              # process_model_from_resume_data: process_model_from_resume_data,
+              # find_process_model:             find_process_model,
+              # encrypted_resume_data:          encrypted_resume_data,
+
+              dictionary:                     dictionary,
+              # cipher_key:                     cipher_key,
+              **options,
+          },
+          flow_options
+        ],
+        circuit_options
+      ]
+    end
+
+    # FIXME: name will change! this is for controllers, only!
+    def self.advance_from_controller(endpoint, success_block:, failure_block:, protocol_failure_block: protocol_failure_block, **argument_options)
+      args = Trailblazer::Endpoint.arguments_for(argument_options)
+
+      signal, (ctx, _ ) = Trailblazer::Endpoint.with_or_etc(
+        endpoint,
+        args[0], # [ctx, flow_options]
+
+        success_block:          success_block,
+        failure_block:          failure_block,
+        protocol_failure_block: protocol_failure_block,
+      )
+
+      ctx
+    end
+  end
+end
+#       created: Dry::Matcher::Case.new(
+#         match:   ->(result) { result.success? && result["model.action"] == :new }, # the "model.action" doesn't mean you need Model.
+#         resolve: ->(result) { result }),
+#       not_found: Dry::Matcher::Case.new(
+#         match:   ->(result) { result.failure? && result["result.model"] && result["result.model"].failure? },
+#         resolve: ->(result) { result }),
+#       # TODO: we could add unauthorized here.
+
+
+require "trailblazer/endpoint/protocol"
+require "trailblazer/endpoint/adapter"

data/lib/trailblazer/endpoint/adapter.rb

@@ -0,0 +1,197 @@
+module Trailblazer
+  class Endpoint
+
+    # The idea is to use the CreatePrototypeProtocol's outputs as some kind of protocol, outcomes that need special handling
+    # can be wired here, or merged into one (e.g. 401 and failure is failure).
+    # I am writing this class in the deep forests of the Algarve, hiding from the GNR.
+    # class Adapter < Trailblazer::Activity::FastTrack # TODO: naming. it's after the "application logic", more like Controller
+ # Currently reusing End.fail_fast as a "something went wrong, but it wasn't a real application error!"
+
+
+    module Adapter
+      class Web <Trailblazer::Activity::FastTrack
+        _404_path = ->(*) { step :_404_status }
+        _401_path = ->(*) { step :_401_status }
+        _403_path = ->(*) { step :_403_status }
+        # _422_path = ->(*) { step :_422_status } # TODO: this is currently represented by the {failure} track.
+
+        step Subprocess(Protocol), # this will get replaced
+          id: :protocol,
+          Output(:not_authorized)     => Path(track_color: :not_authorized, connect_to: Id(:protocol_failure), &_403_path),
+          Output(:not_found)          => Path(track_color: :not_found, connect_to: Id(:protocol_failure), &_404_path),
+          Output(:not_authenticated)  => Path(track_color: :not_authenticated, connect_to: Id(:protocol_failure), &_401_path),
+          Output(:invalid_data)       => Track(:failure) # application error, since it's usually a failed validation.
+
+        step :protocol_failure, magnetic_to: nil, Output(:success) => Track(:fail_fast), Output(:failure) => Track(:fail_fast)
+
+        def protocol_failure(ctx, **)
+          true
+        end
+
+
+# FIXME:::::::
+        def _401_status(ctx, **)
+          ctx[:status] = 401
+        end
+
+        def _404_status(ctx, **)
+          ctx[:status] = 404
+        end
+
+        def _403_status(ctx, **)
+          ctx[:status] = 403
+        end
+      end
+
+      class API < Web
+        step :_200_status, after: :protocol
+
+        def _200_status(ctx, **)
+          ctx[:status] = 200
+        end
+
+        fail :_422_status, before: "End.failure"
+
+        def _422_status(ctx, **)
+          ctx[:status] = 422
+        end
+
+
+        def self.insert_error_handler_steps(adapter)
+          adapter = Class.new(adapter) do
+            step :handle_not_authenticated, magnetic_to: :not_authenticated, Output(:success) => Track(:not_authenticated), Output(:failure) => Track(:not_authenticated), before: :_401_status
+            step :handle_not_authorized, magnetic_to: :not_authorized, Output(:success) => Track(:not_authorized), Output(:failure) => Track(:not_authorized), before: :_403_status
+            # step :handle_not_found, magnetic_to: :not_found, Output(:success) => Track(:not_found), Output(:failure) => Track(:not_found)
+            fail :handle_invalid_data
+          end
+        end
+
+        class Errors < Struct.new(:message, :errors) # FIXME: extract
+          module Handlers
+            def handle_not_authenticated(ctx, errors:, **)
+              errors.message = "Authentication credentials were not provided or are invalid."
+            end
+
+            def handle_not_authorized(ctx, errors:, **)
+              errors.message = "Action not allowed due to a policy setting."
+            end
+
+            def handle_invalid_data(ctx, errors:, **)
+              errors.message = "The submitted data is invalid."
+            end
+          end
+        end
+      end
+
+      # Basic endpoint adapter for a HTTP document API.
+      # As always: "work in progress" ;)
+      #
+      # {End.fail_fast} currently implies a 4xx-able error.
+      class API_ < Trailblazer::Activity::FastTrack
+        _404_path = ->(*) { step :_404_status }
+        _401_path = ->(*) { step :_401_status; step :_401_error_message }
+        _403_path = ->(*) { step :_403_status }
+        # _422_path = ->(*) { step :_422_status } # TODO: this is currently represented by the {failure} track.
+
+        # The API Adapter automatically wires well-defined outputs for you to well-defined paths. :)
+# FIXME
+
+        step Subprocess(Protocol), # this will get replaced
+          id: :protocol,
+          Output(:not_authorized)     => Path(track_color: :_403, connect_to: Id(:render_protocol_failure_config), &_403_path),
+          Output(:not_found)          => Path(track_color: :_404, connect_to: Id(:protocol_failure), &_404_path),
+          Output(:not_authenticated)  => Path(track_color: :_401, connect_to: Id(:render_protocol_failure_config), &_401_path),       # head(401), representer: Representer::Error, message: no token
+          Output(:invalid_data)       => Track(:failure) # application error, since it's usually a failed validation.
+
+            # extensions: [Trailblazer::Activity::TaskWrap::Extension(merge: TERMINUS_HANDLER)]
+            # failure is automatically wired to failure, being an "application error" vs. a "protocol error (auth, etc)"
+
+
+            fail :failure_render_config
+            fail :failure_config_status
+            fail :render_failure
+
+            step :success_render_config
+            step :success_render_status
+            step :render_success
+
+
+          # DISCUSS: "protocol failure" and "application failure" should be the same path, probably?
+          step :render_protocol_failure_config, magnetic_to: nil, Output(:success) => Path(connect_to: Id("End.fail_fast")) do
+            step :render_protocol_failure
+            step :protocol_failure
+          end
+
+=begin
+          render_protocol_failure_config # representer
+          render_protocol_failure        # Representer.new
+          protocol_failure               # true
+=end
+
+        def success_render_status(ctx, **)
+          ctx[:status] = 200
+        end
+
+        def success_render_config(ctx, representer:, **)
+          true
+        end
+
+        def render_protocol_failure_config(*args)
+          failure_render_config(*args)
+        end
+
+# ROAR
+        def render_success(ctx, representer:, domain_ctx:, **)
+          model = domain_ctx[:model]
+          ctx[:json] = representer.new(model).to_json # FIXME: use the same as render_failure.
+        end
+
+        def failure_render_config(ctx, error_representer:, **)
+          ctx[:representer] = error_representer
+        end
+
+        def failure_config_status(ctx, **)
+          ctx[:status] = 422
+        end
+
+        def protocol_failure(*args)
+          #failure_config(*args)
+          true
+        end
+        def render_protocol_failure(*args)
+          render_failure(*args)
+        end
+
+      # ROAR
+        def render_failure(ctx, error_representer:, errors:, **)
+          # render_success(*args)
+          ctx[:json] = error_representer.new(errors).to_json
+      end
+  # how/where would we configure each endpoint? (per action)
+    # class Endpoint
+    #   representer ...
+    #   message ...
+
+        def _401_status(ctx, **)
+          ctx[:status] = 401
+        end
+
+        def _404_status(ctx, **)
+          ctx[:status] = 404
+        end
+
+        def _403_status(ctx, **)
+          ctx[:status] = 403
+        end
+
+        def _401_error_message(ctx, **)
+          ctx[:error_message] = "Authentication credentials were not provided or invalid."
+        end
+
+        # def exec_success(ctx, success_block:, **)
+        #   success_block.call(ctx, **ctx.to_hash) # DISCUSS: use Nested(dynamic) ?
+        # end
+      end
+    end
+  end
+end

data/lib/trailblazer/endpoint/builder.rb

@@ -0,0 +1,56 @@
+module Trailblazer
+  class Endpoint
+    # you don't need this if you build your endpoints manually
+    class Builder < Trailblazer::Activity::Railway
+      # step :build_policy
+      step :build_protocol_block
+      step :normalize_tuple
+
+      # def build_policy(ctx, policies:, **)
+      # end
+
+      def build_protocol_block(ctx, policy:, **)
+        ctx[:protocol_block] = -> { step Subprocess(policy), id: :policy, replace: :policy, inherit: true; {} }
+      end
+
+      def normalize_tuple(ctx, protocol_block:, options_for_build: {}, **)
+        ctx[:build_options] = {
+          protocol_block:    protocol_block,
+          options_for_build: options_for_build
+        }
+      end
+
+
+      module DSL
+        module_function
+        #
+        # @return endpoint_options
+
+        def build_options_for(builder:, **options)
+          signal, (ctx, _) = builder.([options])
+
+          ctx[:build_options] # ["web:submitted?", {protocol_block: ..., options_for_build: ...}]
+        end
+
+        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])
+        end
+
+        # {dsl_options} being something like
+        #
+        #   "api:Start.default" => {policies: []},
+        #   "api:status?"       => {policies: [:user_owns_diagram]},
+        #   "api:download?"     => {policies: [:user_owns_diagram]},
+        #   "api:delete?"       => {policies: [:user_owns_diagram]},
+        def endpoints_for(dsl_options, **options)
+          endpoints = dsl_options.collect do |id, config|
+            endpoint_for(id: id, **options, **config) # config is per endpoint, options are "global"
+          end.to_h
+        end
+      end
+    end # Builder
+
+  end
+end

data/lib/trailblazer/endpoint/protocol.rb

@@ -0,0 +1,122 @@
+module Trailblazer
+  class Endpoint
+    # The {Protocol} implements auth*, and calls the domain OP/WF.
+    # You still have to implement handlers (like {#authorize} and {#handle_not_authorized}) yourself. This might change soon.
+    #
+    # Protocol must provide all ends for the Adapter (401,403 and 404 in particular), even if the ran op/workflow doesn't have it.
+    #   Still thinking about how to do that best.
+
+    # Termini and their "pendants" in HTTP, which is unrelated to protocol!! Protocol is application-focused and doesn't know about HTTP.
+    #   failure: 411
+    #   success: 200
+    #   not_found: 404
+    #   not_authenticated: 401
+    #   not_authorized: 403
+    class Protocol < Trailblazer::Activity::Railway
+      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)
+      end
+
+      step :authenticate, Output(:failure) => _Path(semantic: :not_authenticated) do
+          # step :handle_not_authenticated
+        end
+
+      step :policy, Output(:failure) => _Path(semantic: :not_authorized) do # user from cookie, etc
+        # step :handle_not_authorized
+      end
+
+      # Here, we test a domain OP with ADDITIONAL explicit ends that get wired to the Adapter (vaidation_error => failure).
+      # We still need to test the other way round: wiring a "normal" failure to, say, not_found, by inspecting the ctx.
+      step Subprocess(Noop), id: :domain_activity
+
+
+
+      # add the {End.not_found} terminus to this Protocol. I'm not sure that's the final style, but since a {Protocol} needs to provide all
+      # 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")
+
+        recompile_activity!(sequence)
+
+        sequence
+      end
+
+      # Best-practices of useful routes and handlers that work with 2.1-OPs.
+      class Standard < Protocol
+        step :handle_not_authenticated, magnetic_to: :not_authenticated, Output(:success) => Track(:not_authenticated), Output(:failure) => Track(:not_authenticated)#, before: "End.not_authenticated"
+        step :handle_not_authorized,    magnetic_to: :not_authorized, Output(:success) => Track(:not_authorized), Output(:failure) => Track(:not_authorized)
+        # step :handle_invalid_data,      magnetic_to: :invalid_data, Output(:success) => Track(:invalid_data), Output(:failure) => Track(:invalid_data)
+
+
+        # TODO: allow translation.
+        module Handler
+          def handle_not_authorized(ctx, errors:, **)
+            errors.message = "Action not allowed due to a policy setting."
+          end
+
+          def handle_not_authenticated(ctx, errors:, **)
+            errors.message = "Authentication credentials were not provided or are invalid."
+          end
+        end
+
+        class Termini # FIXME: this means with invalid_data, not_found termini? 2.1?
+
+        end
+      end
+
+      module Bridge
+        # this "bridge" should be optional for "legacy operations" that don't have explicit ends.
+        # we have to inspect the ctx to find out what "really" happened (e.g. model empty ==> 404)
+          NotFound      = Class.new(Trailblazer::Activity::Signal)
+          NotAuthorized = Class.new(Trailblazer::Activity::Signal)
+          NotAuthenticated = Class.new(Trailblazer::Activity::Signal)
+
+        def self.insert(protocol, **)
+          Class.new(protocol) do
+            fail :success?, after: :domain_activity,
+            # FIXME: how to add more signals/outcomes?
+            Output(NotFound, :not_found)            => Track(:not_found),
+
+            # FIXME: Track(:not_authorized) is defined before this step, so the Forward search doesn't find it.
+            # solution would be to walk down sequence and find the first {:magnetic_to} "not_authorized"
+            Output(NotAuthorized, :not_authorized)  => Track(:not_authorized) # FIXME: how to "insert into path"? => Track(:not_authorized) doesn't play!
+          end
+        end
+      end
+
+
+      module Domain
+        # taskWrap step that saves the return signal of the {domain_activity}.
+        # The taskWrap step is usually inserted after {task_wrap.output}.
+        def self.terminus_handler(wrap_ctx, original_args)
+
+        #      Unrecognized Signal `"bla"` returned from EndpointTest::LegacyCreate. Registered signals are,
+        # - #<Trailblazer::Activity::End semantic=:failure>
+        # - #<Trailblazer::Activity::End semantic=:success>
+        # - #<Trailblazer::Activity::End semantic=:fromail_fast>
+
+        # {:return_args} is the original "endpoint ctx" that was returned from the {:output} filter.
+          wrap_ctx[:return_args][0][:domain_activity_return_signal] = wrap_ctx[:return_signal]
+
+          return wrap_ctx, original_args
+        end
+
+        def self.extension_for_terminus_handler
+          # this is called after {:output}.
+          [[Trailblazer::Activity::TaskWrap::Pipeline.method(:insert_after), "task_wrap.call_task", ["endpoint.end_signal", method(:terminus_handler)]]]
+        end
+      end
+
+    end
+  end
+end