trailblazer 0.3.3 → 1.0.0.rc1

data/lib/trailblazer/operation/builder.rb

@@ -0,0 +1,26 @@
+require "uber/builder"
+
+# Allows to add builders via ::builds.
+module Trailblazer::Operation::Builder
+  def self.extended(extender)
+    extender.send(:include, Uber::Builder)
+  end
+
+  def builder_class
+    @builders
+  end
+
+  def builder_class=(constant)
+    @builders = constant
+  end
+
+private
+  # Runs the builders for this operation class to figure out the actual class.
+  def build_operation_class(*args)
+    class_builder(self).(*args) # Uber::Builder::class_builder(context)
+  end
+
+  def build_operation(params, options={})
+    build_operation_class(params).new(params, options)
+  end
+end

data/lib/trailblazer/operation/collection.rb

@@ -1,7 +1,6 @@
 module Trailblazer::Operation::Collection
   # Collection does not produce a contract.
-  def present(*params)
-    setup!(*params)
+  def present
     self
   end
 end

data/lib/trailblazer/operation/controller.rb

@@ -2,48 +2,25 @@ require "trailblazer/endpoint"
 
 module Trailblazer::Operation::Controller
 private
-  def form(operation_class, params=self.params) # consider private.
-    process_params!(params)
-
-    @operation = operation_class.present(params)
-    @form      = @operation.contract
-    @model     = @operation.model
-
-    yield @operation if block_given?
+  def form(*args)
+    present(*args).tap do |op|
+      op.contract.prepopulate! # equals to @form.prepopulate!
+    end
   end
 
-  # Doesn't run #process.
+  # Provides the operation instance, model and contract without running #process.
+  # Returns the operation.
   def present(operation_class, params=self.params)
     res, op = operation!(operation_class, params) { [true, operation_class.present(params)] }
-
-    yield op if block_given?
-    # respond_with op
-    # TODO: implement respond(present: true)
-  end
-
-  def collection(operation_class, params=self.params)
-    # TODO: merge with #present.
-    res, op = operation!(operation_class, params) { [true, operation_class.present(params)] }
-    @collection = @model
-
-    yield op if block_given?
+    op
   end
 
-  # full-on Op[]
-  # Note: this is not documented on purpose as this concept is experimental. I don't like it too much and prefer
-  # returns in the valid block.
-  class Else
-    def initialize(op, run)
-      @op  = op
-      @run = run
-    end
-
-    def else
-      yield @op if @run
+  def collection(*args)
+    present(*args).tap do |op|
+      @collection = op.model
     end
   end
 
-  # Endpoint::Invocation
   def run(operation_class, params=self.params, &block)
     res, op = operation!(operation_class, params) { operation_class.run(params) }
 
@@ -53,19 +30,29 @@ private
   end
 
   # The block passed to #respond is always run, regardless of the validity result.
-  def respond(operation_class, params=self.params, respond_options = {}, &block)
-    res, op = operation!(operation_class, params) { operation_class.run(params) }
+  def respond(operation_class, options={}, params=self.params, &block)
+    res, op   = operation!(operation_class, params, options) { operation_class.run(params) }
+    namespace = options.delete(:namespace) || []
 
-    return respond_with op, respond_options if not block_given?
-    respond_with op, respond_options, &Proc.new { |formats| block.call(op, formats) } if block_given?
+    return respond_with *namespace, op, options if not block_given?
+    respond_with *namespace, op, options, &Proc.new { |formats| block.call(op, formats) } if block_given?
   end
 
+private
+
   def process_params!(params)
   end
 
   # Normalizes parameters and invokes the operation (including its builders).
-  def operation!(operation_class, params, &block)
-    Trailblazer::Endpoint.new(self, operation_class, params, request, self.class._operation).(&block)
+  def operation!(operation_class, params, options={}, &block)
+    # Per default, only treat :html as non-document.
+    options[:is_document] ||= request.format == :html ? false : true
+
+    process_params!(params)
+    res, op = Trailblazer::Endpoint.new(operation_class, params, request, options).(&block)
+    setup_operation_instance_variables!(op)
+
+    [res, op]
   end
 
   def setup_operation_instance_variables!(operation)
@@ -74,16 +61,17 @@ private
     @model     = operation.model
   end
 
-  def self.included(includer)
-    includer.extend Uber::InheritableAttr
-    includer.inheritable_attr :_operation
-    includer._operation = {document_formats: {}}
-    includer.extend ClassMethods
-  end
 
-  module ClassMethods
-    def operation(options)
-      _operation[:document_formats][options[:document_formats]] = true
+  # Note: this is not documented on purpose as this concept is experimental. I don't like it too much and prefer
+  # returns in the valid block.
+  class Else
+    def initialize(op, run)
+      @op  = op
+      @run = run
+    end
+
+    def else
+      yield @op if @run
     end
   end
 end

data/lib/trailblazer/operation/dispatch.rb

@@ -1,6 +1,12 @@
 require "disposable/callback"
 
 module Trailblazer::Operation::Dispatch
+  def self.included(base)
+    base.extend ClassMethods
+    base.inheritable_attr :callbacks
+    base.callbacks = Representable::Cloneable::Hash.new
+  end
+
   def dispatch!(name=:default)
     group = self.class.callbacks[name].new(contract)
     group.(context: self)
@@ -12,18 +18,12 @@ module Trailblazer::Operation::Dispatch
     @invocations ||= {}
   end
 
-
   module ClassMethods
-    def callback(name=:default, *args, &block)
-      callbacks[name] ||= Class.new(Disposable::Callback::Group).extend(Representable::Cloneable)
-      callbacks[name].class_eval(&block)
-    end
-  end
+    def callback(name=:default, constant=nil, &block)
+      return callbacks[name] unless constant or block_given?
 
-  def self.included(base)
-    base.extend ClassMethods
-    base.extend Uber::InheritableAttr
-    base.inheritable_attr :callbacks
-    base.callbacks = Representable::Cloneable::Hash.new
+      callbacks[name] ||= Class.new(constant || Disposable::Callback::Group).extend(Representable::Cloneable) # FIXME: why Representable?
+      callbacks[name].class_eval(&block) if block_given?
+    end
   end
 end

data/lib/trailblazer/operation/model.rb

@@ -0,0 +1,50 @@
+require "trailblazer/operation/model/dsl"
+
+module Trailblazer
+  class Operation
+    # The Model module will automatically create/find models for the configured +action+.
+    # It adds a public  +Operation#model+ reader to access the model (after performing).
+    module Model
+      def self.included(base)
+        base.extend DSL
+      end
+
+      # Methods to create the model according to class configuration and params.
+      module BuildModel
+        def model!(params)
+          instantiate_model(params)
+        end
+
+        def instantiate_model(params)
+          send("#{action_name}_model", params)
+        end
+
+        def create_model(params)
+          model_class.new
+        end
+
+        def update_model(params)
+          model_class.find(params[:id])
+        end
+
+        alias_method :find_model, :update_model
+      end
+
+
+      # #validate no longer accepts a model since this module instantiates it for you.
+      def validate(params, model=self.model, *args)
+        super(params, model, *args)
+      end
+
+    private
+      include BuildModel
+
+      def model_class
+        self.class.model_class
+      end
+      def action_name
+        self.class.action_name
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+class Trailblazer::Operation
+  module Model
+    # Imports ::model and ::action into an operation.
+    module DSL
+      def self.extended(extender)
+        extender.extend Uber::InheritableAttr
+        extender.inheritable_attr :config
+        extender.config = {}
+      end
+
+      def model(name, action=nil)
+        self.config[:model] = name
+        action(action) if action # coolest line ever.
+      end
+
+      def action(name)
+        self.config[:action] = name
+      end
+
+      def action_name # considered private.
+        self.config[:action] or :create
+      end
+
+      def model_class # considered private.
+        self.config[:model] or raise "[Trailblazer] You didn't call Operation::model."
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+require "trailblazer/operation/model"
+
+class Trailblazer::Operation
+  module Model
+    # Builds (finds or creates) the model _before_ the operation is instantiated.
+    # Passes the model instance into the builder with the following signature.
+    #
+    #   builds ->(model, params)
+    #
+    # The initializer will now expect you to pass the model in via options[:model]. This
+    # happens automatically when coming from a builder.
+    module External
+      def self.included(includer)
+        includer.extend Model::DSL
+        includer.extend Model::BuildModel
+        includer.extend ClassMethods
+      end
+
+      def assign_model!(*) # i don't like to "disable" the `@model =` like this but it's the simplest for now.
+        @model = @options[:model]
+      end
+
+
+      module ClassMethods
+      private
+        def build_operation(params, options={}) # TODO: merge with Resolver::build_operation.
+          model = model!(params)
+          build_operation_class(model, params). # calls builds->(model, params).
+            new(params, options.merge(model: model))
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/policy.rb

@@ -0,0 +1,87 @@
+module Trailblazer
+  class NotAuthorizedError < RuntimeError
+  end
+
+  # Adds #evaluate_policy to #setup!, and ::policy.
+  module Operation::Policy
+    require "trailblazer/operation/policy/guard"
+
+    def self.included(includer)
+      includer.extend DSL
+    end
+
+    module DSL
+      def self.extended(extender)
+        extender.inheritable_attr :policy_config
+        extender.policy_config = Guard::Permission.new { true } # return true per default.
+      end
+
+      def policy(*args, &block)
+        self.policy_config = permission_class.new(*args, &block)
+      end
+
+      def permission_class
+        Permission
+      end
+    end
+
+    attr_reader :policy
+
+  private
+    module Setup
+      def setup!(params)
+        super
+        evaluate_policy(params)
+      end
+    end
+    include Setup
+
+
+    private
+    def evaluate_policy(params)
+      user = params[:current_user]
+
+      @policy = self.class.policy_config.(user, model, @policy) do |policy, action|
+        raise policy_exception(policy, action, model)
+      end
+    end
+
+    def policy_exception(policy, action, model)
+      NotAuthorizedError.new(query: action, record: model, policy: policy)
+    end
+
+    # Encapsulate building the Policy object and calling the defined query action.
+    # This assumes the policy class is "pundit-style", as in Policy.new(user, model).edit?.
+    class Permission
+      def initialize(policy_class, action)
+        @policy_class, @action = policy_class, action
+      end
+
+      # Without a block, return the policy object (which is usually a Pundit-style class).
+      # When block is passed evaluate the default rule and run block when false.
+      def call(user, model, external_policy=nil)
+        build_policy(user, model, external_policy).tap do |policy|
+          policy.send(@action) || yield(policy, @action) if block_given?
+        end
+      end
+
+    private
+      def build_policy(user, model, policy)
+        policy or @policy_class.new(user, model)
+      end
+    end
+  end
+
+
+  module Operation::Deny
+    def self.included(includer)
+      includer.extend ClassMethods
+    end
+
+    module ClassMethods
+      def deny!
+        raise NotAuthorizedError
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Trailblazer
+# Adds #evaluate_policy to Operation#setup!
+  module Operation::Policy
+    module Guard
+      def self.included(includer)
+        includer.extend(DSL)
+        includer.extend(ClassMethods)
+        includer.send(:include, Setup)
+      end
+
+      module ClassMethods
+        # Use Guard::Permission.
+        def permission_class
+          Permission
+        end
+      end
+
+      def evaluate_policy(params)
+        self.class.policy_config.(self, params) or raise NotAuthorizedError.new
+      end
+
+      # Encapsulates the operation's policy which is usually called in Op#setup!.
+      class Permission
+        def initialize(*args, &block)
+          @callable, @args = Uber::Options::Value.new(block), args
+        end
+
+        def call(context, *args)
+          @callable.(context, *args)
+        end
+      end
+    end
+  end
+end

data/lib/trailblazer/operation/representer.rb

@@ -7,14 +7,16 @@
 # TODO: so far, we only support JSON, but it's two lines to change to support any kind of format.
 module Trailblazer::Operation::Representer
   def self.included(base)
-    base.extend Uber::InheritableAttr
     base.inheritable_attr :_representer_class
     base.extend ClassMethods
   end
 
   module ClassMethods
-    def representer(&block)
-      representer_class.class_eval(&block)
+    def representer(constant=nil, &block)
+      return representer_class unless constant or block_given?
+
+      self.representer_class= Class.new(constant) if constant
+      representer_class.class_eval(&block) if block_given?
     end
 
     def representer_class
@@ -35,20 +37,39 @@ module Trailblazer::Operation::Representer
     end
   end
 
-
 private
-  def validate_contract(params)
-    # use the inferred representer from the contract for deserialization in #validate.
-    contract.validate(params) do |document|
-      self.class.representer_class.new(contract).from_json(document)
+  module Rendering
+    def to_json(*)
+      self.class.representer_class.new(represented).to_json
+    end
+
+    def represented
+      contract
     end
   end
+  include Rendering
 
 
-  module Rendering
-    def to_json(*)
-      self.class.representer_class.new(contract).to_json
+  module Deserializer
+    module Hash
+      def validate_contract(params)
+        # use the inferred representer from the contract for deserialization in #validate.
+        contract.validate(params) do |document|
+          self.class.representer_class.new(contract).from_hash(document)
+        end
+      end
+    end
+
+    # This looks crazy, but all it does is using a Reform hook in #validate where we can use
+    # our own representer for deserialization. After the object graph is set up, Reform will
+    # run its validation without even knowing this came from JSON.
+    module JSON
+      def validate_contract(params)
+        contract.validate(params) do |document|
+          self.class.representer_class.new(contract).from_json(document)
+        end
+      end
     end
   end
-  include Rendering
+  include Deserializer::JSON
 end