trailblazer-endpoint 0.0.1 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a13cc4ea9b50a656f620578a75ccd11aa01106bc22be8975e8758a660d1a13aa
-  data.tar.gz: 4c006bbfeab10458615ee658e862cf152b42b17f1c0d8302f9d1308b8cdc1425
+  metadata.gz: 4dd0d753bd8dc039e3f55e66d80d3d9d4904fcc0d442ea62860fbab4a0b05d5e
+  data.tar.gz: 0ecfa53ed1607d4d3785d47ffef3f817033b18ec29c6cbbf06e4f466c90a2638
 SHA512:
-  metadata.gz: 53dfeec3df63a69bbe4f481f58eaa6c71e32d55044066fda4eb7dc8579ef1b973079ff8fa6b7cbd7a6f4ce4ecdb767d25f37a6bf68eee99626557f1a1de2ab71
-  data.tar.gz: 99b9e753a78f182ad274c677aa9f1c33bc85fbd8ad4ce57c2574a4b4ef29d3400e3553c6484674e3d75cec41dcacea76f601db77aee7273fdd066ec3c41c17c7
+  metadata.gz: 7762ada8e3fafbd1a68e5f4045af8e57b03568745ac55236d756da6a4fe681f6818abd4e27b737b162872b9ebd4589f440b1b7ebee01729d2cfd6dd88702d980
+  data.tar.gz: 6f56d293369de1da783002e8d9f602f2847eafbe2f7ad80f5f6a08fc305542f3d432d7c9878376cc421a38de58e19d60eac2d436fe2650191b36f66d149bb722

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,29 @@
+# 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`.
+
 # 0.0.1
 
 * Provides very simple `Protocol` implementations for `Web` and `API`, same for `Adapter`.

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,7 @@ 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, domain_ctx_filter: nil, protocol_block: ->(*) { Hash.new })
       # special considerations around the {domain_activity} and its taskWrap:
       #
       #  1. domain_ctx_filter (e.g. to filter {current_user})
@@ -24,16 +23,21 @@ module Trailblazer
       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
 
+      # puts Trailblazer::Developer.render(protocol)
+      # puts
+
       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
 
+      # puts Trailblazer::Developer.render(app_protocol)
+
       Class.new(adapter) do
         step(Subprocess(app_protocol), {inherit: true, id: :protocol, replace: :protocol})
       end # app_adapter
@@ -47,12 +51,25 @@ module Trailblazer
       }
     end
 
+    def self.domain_ctx_filter(variables)
+      ->(_ctx, ((ctx, a), b)) do # taskWrap interface
+        variables.each do |variable|
+          ctx[:domain_ctx][variable] = ctx[variable]
+        end
+
+        [_ctx, [[ctx, a], b]]
+      end
+    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:)
+    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?
@@ -75,27 +92,22 @@ module Trailblazer
       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)
+    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)
 
       [
         [
           {
-              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,
+              **endpoint_options,
           },
           flow_options
         ],
@@ -131,3 +143,6 @@ end
 
 require "trailblazer/endpoint/protocol"
 require "trailblazer/endpoint/adapter"
+require "trailblazer/endpoint/dsl"
+require "trailblazer/endpoint/controller"
+require "trailblazer/endpoint/options"

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

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