trailblazer-endpoint 0.0.2 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2223ccae09c1e72ad993d75dae43dbeb60d2194b924006caa44e606d0f41e162
-  data.tar.gz: c9a7580cef40249013d4069356edd3e260b820026101bea28c01f39e6d65935e
+  metadata.gz: d241ba658c264d5ec48e241c59abe89811646109f07a1f900231d7963245bcad
+  data.tar.gz: '0682d8ad85197f3049c481f3868ae87982991c913ffd8e5f3ae8185b2554a274'
 SHA512:
-  metadata.gz: 8f31213731d9bcd5267019ab3e5027e873d63cdf31cb0e418e48c70b0bf13ef3012c040deeb1a01fb171cb28aa9e1e64a5a0057218d9030679748c76ce57009e
-  data.tar.gz: 457aa56b0e109053568351a46fbc3f3dc487280e0937f88d2ed60297ee456078c64399422f6acb2ec7129c48c36db18aef406f257f17d43c0b60578e242043d7
+  metadata.gz: 0c7b9c72993a46d19c81307a94423e732b7eb0d433526cb9d32e9f7e70e54fa4eb36e3cf062eb3d77eebc9372955c8853ddbbb2b13ef9a22e711c0c7b09a9cad
+  data.tar.gz: ac107aae848481b55309b9c4fc607dd42c505fc16c1a267657cba4852660ecd72c8de4dcc9036b8a09bcf99d0d7d4c75d6fca9a956ba53562b8769f2913801a3

data/.gitignore

@@ -0,0 +1,16 @@
+.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/log
+tmp
+.DS_Store
+log/
+*.iml
+.idea
+*.swp
+gemfiles/*.lock

data/Appraisals

@@ -0,0 +1,5 @@
+appraise 'rails-app' do
+  gem 'rails', '6.0.3.1'
+  gem 'sqlite3', '~> 1.4'
+  gem "trailblazer-operation"
+end

data/CHANGES.md

@@ -1,3 +1,31 @@
+# 0.0.7
+
+* BREAKING: Remove `:domain_ctx_filter` in favor of `Controller.insert_copy_to_domain_ctx!`.
+* Add support for serializing `:suspend_data` and deserializing `:resume_data` so session data can get automatically encrypted and passed to the next action. This used to sit in `workflow`.
+* Add `:find_process_model`. This introduces a new protocol step before `policy` to find the "process model" instead of letting the domain operation or even the policy (or both!) find the "current model".
+
+# 0.0.6
+
+* `Controller::endpoint` short form introduced.
+* Minor changes for `Controller.module`.
+* Lots of cleanups.
+
+# 0.0.5
+
+* Removed `Protocol::Failure`. Until we have `Railway::End::Failure`, use a normal `Activity::End` everywhere instead of introducing our own.
+* Default `with_or_etc:invoke` is `TaskWrap.invoke`.
+
+# 0.0.4
+
+* Use new `context-0.3.1`.
+* Don't use `wtf?`.
+* Don't create a `Context` anymore in `Endpoint.arguments_for`.
+
+# 0.0.3
+
+* Introduce `Options`.
+* Introduce `Controller::DSL`.
+
 # 0.0.2
 
 The `:collaboration` and `:dictionary` options for `arguments_for` are now optional and figured out by `workflow`.

data/README.md

@@ -1,11 +1,46 @@
 # Trailblazer::Endpoint
 
-*Generic HTTP handlers for operation results.*
+*Endpoints handle authentication, authorization, calling the business logic and response rendering.*
 
-Decouple finding out *what happened* from *what to do*.
+## Overview
 
-t test/controllers/songs_controller_test.rb --backtrace
+An endpoint links your routing with your business code. The idea is that your controllers are pure HTTP routers, calling the respective endpoint for each action. From there, the endpoint takes over, handles authentication, policies, executing the domain code, interpreting the result, and providing hooks to render a response.
 
-## TODO
+Instead of dealing with a mix of `before_filter`s, Rack-middlewares, controller code and callbacks, an endpoint is just another activity and allows to be customized with the well-established Trailblazer mechanics.
 
-* make travis build run `cd test/rails-app/ && rake`
+
+In a Rails controller, a controller action could look as follows.
+
+```ruby
+class DiagramsController < ApplicationController
+  endpoint Diagram::Operation::Create, [:is_logged_in?, :can_add_diagram?]
+
+  def create
+    endpoint Diagram::Operation::Create do |ctx, **|
+      redirect_to diagram_path(ctx[:diagram].id)
+    end.Or do |ctx, **|
+      render :form
+    end
+  end
+end
+```
+
+While routing and redirecting/rendering still happens in Rails, all remaining steps are handled in the endpoint.
+
+An API controller action, where the rendering is done generically, could look much simpler.
+
+```ruby
+class API::V1::DiagramsController < ApplicationController
+  endpoint Diagram::Operation::Create, [:is_logged_in?, :can_add_diagram?]
+
+  def create
+    endpoint Diagram::Operation::Create
+  end
+end
+```
+
+Endpoints are easily customized but their main intent is to reduce fuzzy controller code and providing best practices for both HTML-rendering controllers and APIs.
+
+## Documentation
+
+Read the [full documentation for endpoint](https://trailblazer.to/2.1/docs/endpoint.html) on our website.

data/Rakefile

@@ -5,6 +5,12 @@ 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.test_files = FileList['test/endpoint_test.rb', 'test/docs/*_test.rb', "test/adapter/*_test.rb", "test/config_test.rb"]
+  test.verbose = true
+end
+
+Rake::TestTask.new('test-rails-app') do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/rails-app/test/test_helper.rb', 'test/rails-app/test/**/*.rb']
   test.verbose = true
 end

data/gemfiles/rails_app.gemfile

@@ -0,0 +1,12 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "multi_json"
+gem "minitest-line"
+gem "dry-validation"
+gem "rails", "6.0.3.1"
+gem "sqlite3", "~> 1.4"
+gem "trailblazer-operation"
+
+gemspec path: "../"

data/lib/trailblazer/endpoint.rb

@@ -2,8 +2,12 @@ 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)
-
+    def self.build(protocol:, adapter:, domain_activity:, scope_domain_ctx: true, protocol_block: ->(*) { Hash.new },
+      serialize: false, # TODO: plug-in, not hardcoded!
+      deserialize: false,# TODO: plug-in, not hardcoded!
+      find_process_model: false, # TODO: plug-in, not hardcoded!
+      deserialize_process_model_id_from_resume_data: false # TODO: plug-in, not hardcoded!
+      )
       # special considerations around the {domain_activity} and its taskWrap:
       #
       #  1. domain_ctx_filter (e.g. to filter {current_user})
@@ -20,24 +24,49 @@ module Trailblazer
       # scoping: {:domain_ctx} becomes ctx
       extensions_options.merge!(Endpoint.options_for_scope_domain_ctx) if scope_domain_ctx # TODO: test flag
 
+      app_protocol = build_protocol(protocol, domain_activity: domain_activity, extensions_options: extensions_options, protocol_block: protocol_block, serialize: serialize, deserialize: deserialize,
+        find_process_model: find_process_model, deserialize_process_model_id_from_resume_data: deserialize_process_model_id_from_resume_data
+        )
+
+      # puts Trailblazer::Developer.render(app_protocol)
 
-      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
+      Class.new(adapter) do
+        step(Subprocess(app_protocol), {inherit: true, id: :protocol, replace: :protocol})
+      end # app_adapter
+
+    end
+
+    # @private
+    def self.build_protocol(protocol, domain_activity:, extensions_options:, protocol_block:, serialize:, deserialize:, find_process_model:, deserialize_process_model_id_from_resume_data:)
+      Class.new(protocol) do
+        if serialize
+          Protocol::Controller.insert_serialize_steps!(self)
+        end
+
+        if deserialize
+          Protocol::Controller.insert_deserialize_steps!(self)
+        end
+
+        if serialize || deserialize
+          Protocol::Controller.insert_copy_to_domain_ctx!(self, :resume_data => :resume_data)
+        end
+
+        if find_process_model
+          Protocol::Controller.insert_find_process_model!(self, before: :policy) # TODO: test before: :policy
+        end
+
+        if deserialize_process_model_id_from_resume_data
+          pass Protocol::Controller.method(:deserialize_process_model_id_from_resume_data), after: :deserialize_resume_data, magnetic_to: :deserialize, Output(:success) => Track(:deserialize)
+        end
 
-      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.
+          merge(instance_exec(&protocol_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()
@@ -49,10 +78,13 @@ module Trailblazer
 
     # 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:)
+    def self.with_or_etc(activity, args, failure_block:, success_block:, protocol_failure_block:, invoke: Trailblazer::Activity::TaskWrap.method(:invoke))
+    # def self.with_or_etc(activity, args, failure_block:, success_block:, protocol_failure_block:, invoke: Trailblazer::Developer.method(:wtf?))
+
       # args[1] = args[1].merge(focus_on: { variables: [:returned], steps: :invoke_workflow })
 
-      signal, (endpoint_ctx, _ ) = Trailblazer::Developer.wtf?(activity, args)
+      # signal, (endpoint_ctx, _ ) = Trailblazer::Developer.wtf?(activity, args)
+      signal, (endpoint_ctx, _ ) = invoke.call(activity, args) # translates to 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?
@@ -76,8 +108,9 @@ module Trailblazer
     end
 
     #@ For WORKFLOW and operations. not sure this method will stay here.
-    def self.arguments_for(domain_ctx:, flow_options:, circuit_options: {}, **options)
-      domain_ctx      = Trailblazer::Context::IndifferentAccess.build(domain_ctx, {}, [domain_ctx, flow_options], circuit_options)
+    def self.arguments_for(domain_ctx:, flow_options:, circuit_options: {}, **endpoint_options)
+      # we don't have to create the Ctx wrapping explicitly here. this is done via `:input`.
+      # domain_ctx      = Trailblazer::Context::IndifferentAccess.build(domain_ctx, {}, [domain_ctx, flow_options], circuit_options)
 
       [
         [
@@ -89,7 +122,7 @@ module Trailblazer
               # encrypted_resume_data:          encrypted_resume_data,
 
               # cipher_key:                     cipher_key,
-              **options,
+              **endpoint_options,
           },
           flow_options
         ],
@@ -125,3 +158,9 @@ end
 
 require "trailblazer/endpoint/protocol"
 require "trailblazer/endpoint/adapter"
+require "trailblazer/endpoint/dsl"
+require "trailblazer/endpoint/controller"
+require "trailblazer/endpoint/options"
+require "trailblazer/endpoint/protocol/controller"
+require "trailblazer/endpoint/protocol/find_process_model"
+require "trailblazer/endpoint/protocol/cipher"

data/lib/trailblazer/endpoint/adapter.rb

@@ -9,20 +9,32 @@ module Trailblazer
 
 
     module Adapter
-      class Web <Trailblazer::Activity::FastTrack
+      class Web < Trailblazer::Activity::Path
         _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.
 
+        # 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: Activity::End.new(semantic: :fail_fast), magnetic_to: :fail_fast, id: "End.fail_fast") # TODO: rename to {protocol_failure}
+          sequence = Activity::Path::DSL.append_end(sequence, task: Activity::End.new(semantic: :failure), magnetic_to: :failure, id: "End.failure")
+
+          recompile_activity!(sequence)
+
+          sequence
+        end
+
         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.
+          Output(:invalid_data)       => Track(:failure), # application error, since it's usually a failed validation.
+          Output(:failure)       => 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)
 
-        step :protocol_failure, magnetic_to: nil, Output(:success) => Track(:fail_fast), Output(:failure) => Track(:fail_fast)
 
         def protocol_failure(ctx, **)
           true
@@ -41,28 +53,34 @@ module Trailblazer
         def _403_status(ctx, **)
           ctx[:status] = 403
         end
-      end
+      end # Web
 
       class API < Web
         step :_200_status, after: :protocol
 
-        def _200_status(ctx, **)
-          ctx[:status] = 200
+        def _200_status(ctx, success_status: 200, **)
+          ctx[:status] = success_status
         end
 
-        fail :_422_status, before: "End.failure"
+        step :_422_status, before: "End.failure", magnetic_to: :failure, Output(:success) => Track(:failure)
 
         def _422_status(ctx, **)
           ctx[:status] = 422
         end
 
 
-        def self.insert_error_handler_steps(adapter)
+        def self.insert_error_handler_steps(adapter) # TODO: evaluate if needed?
           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
+            API.insert_error_handler_steps!(self)
+          end
+        end
+
+        def self.insert_error_handler_steps!(adapter)
+          adapter.instance_exec do
+            step :handle_not_authenticated, magnetic_to: :not_authenticated, Output(:success) => Track(:not_authenticated), before: :_401_status
+            step :handle_not_authorized, magnetic_to: :not_authorized, Output(:success) => 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
+            step :handle_invalid_data, before: :_422_status, magnetic_to: :failure, Output(:success) => Track(:failure)
           end
         end
 
@@ -81,117 +99,8 @@ module Trailblazer
             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
+      end # API
 
-        # def exec_success(ctx, success_block:, **)
-        #   success_block.call(ctx, **ctx.to_hash) # DISCUSS: use Nested(dynamic) ?
-        # end
-      end
     end
   end
 end