Trailblazer Macro

All common Macro's for Trailblazer::Operation, will come here

TODO

Describe the following Macros:

• Nested
• Rescue
• Wrap

Table of Contents

• Model Macro
• Policy Macro
  • Policy::Pundit - Macro
    • Policy::Pundit - API
    • Policy::Pundit - Name
    • Policy::Pundit - Dependency Injection
  • Policy::Guard - Macro
    • Policy::Guard - API
    • Policy::Guard - Callable
    • Policy::Guard - Instance Method
    • Policy::Guard - Name
    • Policy::Guard - Dependency Injection
    • Policy::Guard - Position

Model Macro

Trailblazer also has a convenient Macro to handle model creation and basic finding by id. The Model macro literally does what our model! step did.

class Song::Create < Trailblazer::Operation
  step Policy::Guard( :authorize! )
  step Model( Song, :new )
end

Note that Model is not designed for complex query logic - should you need that, you might want to use [Trailblazer Finder][trailblazer_finder_link] or simply write your own customized step.

Due to a lot of requests, we have adjusted the :find_by method so you can specify a key to find by.

class Song::Create < Trailblazer::Operation
  step Policy::Guard( :authorize! )
  step Model( Song, :find_by, :title )
end

Not specifying the third parameter in the Model Macro for :find_by, will result in defaulting it back to :id.

Policy Macro

An optional Policy Macro for Trailblazer Operations that blocks unauthorized users from running the operation.

You can abort running an operation using a policy. "Pundit-style" policy classes define the rules.

class Comment::Policy
  def initialize(user, comment)
    @user, @comment = user, comment
  end

  def create?
    @user.admin?
  end
end

The rule is enabled via the ::policy call.

class Comment::Create < Trailblazer::Operation
  step Policy( Comment::Policy, :create? )
end

The policy is evaluated in #setup!, raises an exception if false and suppresses running #process.

Policy::Pundit - Macro

The Policy::Pundit Macro allows using Pundit-compatible policy classes in an operation.

A Pundit policy has various rule methods and a special constructor that receives the current user and the current model.

class MyPolicy
  def initialize(user, model)
    @user, @model = user, model
  end

  def create?
    @user == Module && @model.id.nil?
  end

  def new?
    @user == Class
  end
end

In pundit policies, it is a convention to have access to those objects at runtime and build rules on top of those.

You can plug this policy into your pipe at any point. However, this must be inserted after the "model" skill is available.

class Create < Trailblazer::Operation
  step Model( Song, :new )
  step Policy::Pundit( MyPolicy, :create? )
  # ...
end

Note that you don’t have to create the model via the Model macro - you can use any logic you want. The Pundit macro will grab the model from ["model"], though.

This policy will only pass when the operation is invoked as follows.

Create.( {}, "current_user" => User.find(1) )

Any other call will cause a policy breach and stop the pipe from executing after the Policy::Pundit step.

Policy::Pundit - API

Add your polices using the Policy::Pundit macro. It accepts the policy class name, and the rule method to call.

class Create < Trailblazer::Operation
  step Model( Song, :new )
  step Policy::Pundit( MyPolicy, :create? )
  # ...
end

The step will create the policy instance automatically for you and passes the "model" and the "current_user" skill into the policies constructor. Just make sure those dependencies are available before the step is executed.

If the policy returns falsey, it deviates to the left track.

After running the Pundit step, its result is readable from the Result object.

result = Create.({}, "current_user" => Module)
result["result.policy.default"].success? #=> true
result["result.policy.default"]["policy"] #=> #<MyPolicy ...>

Note that the actual policy instance is available via ["result.policy.#{name}"]["policy"] to be reinvoked with other rules (e.g. in the view layer).

Policy::Pundit - Name

You can add any number of Pundit policies to your pipe. Make sure to use name: to name them, though.

class Create < Trailblazer::Operation
  step Model( Song, :new )
  step Policy::Pundit( MyPolicy, :create?, name: "after_model" )
  # ...
end

The result will be stored in "result.policy.#{name}"

result = Create.({}, "current_user" => Module)
result["result.policy.after_model"].success? #=> true

Policy::Pundit - Dependency Injection

Override a configured policy using dependency injection.

Create.({},
  "current_user"        => Module,
  "policy.default.eval" => Trailblazer::Operation::Policy::Pundit.build(AnotherPolicy, :create?)
)

You can inject it using "policy.#{name}.eval". It can be any object responding to call.

Policy::Guard - Macro

A guard is a step that helps you evaluating a condition and writing the result. If the condition was evaluated as falsey, the pipe won’t be further processed and a policy breach is reported in Result["result.policy.default"].

class Create < Trailblazer::Operation
  step Policy::Guard( ->(options, params:, **) { params[:pass] } )
  step :process

  def process(*)
    self["x"] = true
  end
end

The only way to make the above operation invoke the second step :process is as follows.

result = Create.({ pass: true })
result["x"] #=> true

Any other input will result in an abortion of the pipe after the guard.

result = Create.()
result["x"] #=> nil
result["result.policy.default"].success? #=> false

Policy::Guard - API

The Policy::Guard macro helps you inserting your guard logic. If not defined, it will be evaluated where you insert it.

class Create < Trailblazer::Operation
  step Policy::Guard( ->(options, params:, **) { params[:pass] } )
  # ...
end

The options object is passed into the guard and allows you to read and inspect data like params or current_user. Please use kw args.

Policy::Guard - Callable

As always, the guard can also be a Callable-marked object.

class MyGuard
  include Uber::Callable

  def call(options, params:, **)
    params[:pass]
  end
end

Insert the object instance via the Policy::Guard macro.

class Create < Trailblazer::Operation
  step Policy::Guard( MyGuard.new )
  # ...
end

Policy::Guard - Instance Method

As always, you may also use an instance method to implement a guard.

class Create < Trailblazer::Operation
  step Policy::Guard( :pass? )

  def pass?(options, params:, **)
    params[:pass]
  end
  # ...
end

Policy::Guard - Name

The guard name defaults to default and can be set via name:. This allows having multiple guards.

class Create < Trailblazer::Operation
  step Policy::Guard( ->(options, current_user:, **) { current_user }, name: :user )
  # ...
end

The result will sit in result.policy.#{name}.

result = Create.({}, "current_user" => true)
result["result.policy.user"].success? #=> true

Policy::Guard - Dependency Injection

Instead of using the configured guard, you can inject any callable object that returns a Result object. Do so by overriding the policy.#{name}.eval path when calling the operation.

Create.({},
  "current_user"        => Module,
  "policy.default.eval" => Trailblazer::Operation::Policy::Guard.build(->(options) { false })
)

An easy way to let Trailblazer build a compatible object for you is using Guard.build.

This is helpful to override a certain policy for testing, or to invoke it with special rights, e.g. for an admin.

Policy::Guard - Position

You may specify a position.

class Create < Trailblazer::Operation
  step :model!
  step Policy::Guard( :authorize! ), before: :model!
end

Resulting in the guard inserted before model!, even though it was added at a later point.

puts Create["pipetree"].inspect(style: :rows) #=>
 # 0 ========================>operation.new
 # 1 ==================>policy.default.eval
 # 2 ===============================>model!

This is helpful if you maintain modules for operations with generic steps.