trailblazer 0.3.3 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c6355544b09375074e8ef41304a2ccdf99d5bdf9
-  data.tar.gz: 5c80ec4a93e1628e84aa6a83290027ccfdb02cca
+  metadata.gz: 4c67bd17df3cf4afa247418e31cf3747e07ae7f1
+  data.tar.gz: ceb2f1a7f81c63d82152938607f4c46cb4b075fc
 SHA512:
-  metadata.gz: 6c27cbe26a73a84c413341a2d9ec528c80083d98b4110b71f8569a72961a3932790347c47389a7fda74d3aa61a5c196e8178fa186c86fa1016048726e71705eb
-  data.tar.gz: 4c359e9e33ea39d269710a04d615a59a4d8e53225f9438e2f70b3f83eb6182c85beea60479b54b34d6a193216ba61b86b12719e9f88df51bc5fd13b11364be29
+  metadata.gz: 633a5a70e6b0f362247be2509dd637e234d10135f0d6c1917c81d3646646e12ae5efdaa964468592203f5eabafc274b1620c2d48b6b5870c26551bc92e11f971
+  data.tar.gz: 6276f20bc9d09a11d8dc313efd964383a04d1e05f77d87eded95e64953c8e854ecdaf0ec5be23f916fbafef0a867bffd6b89fc8b5b73ddd5e41cbddf1d3ef055

data/.travis.yml

@@ -3,4 +3,4 @@ rvm:
   - 2.2.0
   - 2.1.2
   - 2.0.0
-  - 1.9.3
+  # - 1.9.3

data/CHANGES.md

@@ -1,3 +1,15 @@
+# 1.0.0
+
+* `Operation[{..}]` is deprecated in favor of `Operation.({..})`.
+setup in initialize: when Op.run() with Worker, the policy will be run "delayed" and not with the actual permission set. this will result in many crashing sidekiq workers.
+* `Operation::CRUD` is now `Operation::Model`.
+* `Controller#form` now invokes `#prepopulate!` before rendering the view. Use `#present` if you don't want that.
+
+# 0.3.4
+
+* Added `Operation::Policy`.
+* Added `Operation::Resolver`.
+
 # 0.3.3
 
 * Add `Operation::reject` which will run the block when _invalid_.

data/Gemfile

@@ -4,8 +4,9 @@ source 'https://rubygems.org'
 gemspec
 
 # gem "representable", path: "../representable"
-# gem "reform", path: "../reform"
 # gem "disposable", path: "../disposable"
 gem "virtus"
 # gem "reform", github: "apotonick/reform"
 gem "reform", "~> 2.0.0"
+# gem "reform", path: "../reform"
+gem "multi_json"

data/README.md

@@ -2,7 +2,23 @@
 
 _Trailblazer is a thin layer on top of Rails. It gently enforces encapsulation, an intuitive code structure and gives you an object-oriented architecture._
 
-In a nutshell: Trailblazer makes you write **logicless models** that purely act as data objects, don't contain callbacks, nested attributes, validations or domain logic. **Controllers** become lean HTTP endpoints. Your **business logic** (including validation) is decoupled from the actual Rails framework and modeled in _operations_.
+[![Gem Version](https://badge.fury.io/rb/trailblazer.svg)](http://badge.fury.io/rb/trailblazer)
+[![Gitter Chat](https://badges.gitter.im/trailblazer/chat.svg)](https://gitter.im/trailblazer/chat)
+
+
+## Trailblazer In A Nutshell
+
+1. All business logic is encapsulated in [operations](#operation) (service objects).
+  * An optional Reform [form](#validations) object in the operation deserializes and validates input. The form object can also be used for rendering.
+  * An optional [policy](#policies) object blocks unauthorized users from running the operation.
+  * Optional [callback](#callbacks) objects allow declaring post-processing logic.
+3. [Controllers](#controllers) instantly delegate to an operation. No business code in controllers, only HTTP-specific logic.
+4. [Models](#models) are persistence-only and solely define associations and scopes. No business code is to be found here. No validations, no callbacks.
+5. The presentation layer offers optional [view models](#cells) (Cells) and [representers](#representers) for document APIs.
+
+Trailblazer is designed to handle different contexts like user roles by applying [inheritance](#inheritance) between and [composing](#composing) of operations, form objects, policies, representers and callbacks.
+
+
 
 ## Mission
 
@@ -81,7 +97,7 @@ Operations encapsulate business logic and are the heart of a Trailblazer archite
 
 An operation is not just a monolithic replacement for your business code. An operation is a simple orchestrator between the form object, models and your business code.
 
-You don't have to use the form/contract if you don't want it, BTW.
+You don't have to use the form/contract if you don't want it.
 
 ```ruby
 class Comment < ActiveRecord::Base
@@ -158,7 +174,7 @@ class Create < Trailblazer::Operation
   end
 ```
 
-The _Imperative Callback_ pattern then allows you to call this _callback group_ whereever you need it.
+The _Imperative Callback_ pattern then allows you to call this _callback group_ wherever you need it.
 
 ```ruby
 class Create < Trailblazer::Operation
@@ -193,6 +209,52 @@ end
 
 Only operations and views/cells can access models directly.
 
+## Policies
+
+The full documentation for [Policy is here](http://trailblazerb.org/gems/operation/policy.html).
+
+You can abort running an operation using a policy. "[Pundit](https://github.com/elabs/pundit)-style" policy classes define the rules.
+
+```ruby
+class Thing::Policy
+  def initialize(user, thing)
+    @user, @thing = user, thing
+  end
+
+  def create?
+    @user.admin?
+  end
+end
+```
+
+The rule is enabled via the `::policy` call.
+
+```ruby
+class Thing::Create < Trailblazer::Operation
+  include Policy
+
+  policy Thing::Policy, :create?
+```
+
+The policy is evaluated in `#setup!`, raises an exception if `false` and suppresses running `#process`.
+
+```ruby
+Thing::Create.(current_user: User.find(1), thing: {}) # raises exception.
+```
+
+You can query the `policy` object at any point in your operation without raising an exception.
+
+To [use policies in your builders](http://trailblazerb.org/gems/operation/builder#resolver.html), please read the documentation.
+
+```ruby
+class Thing::Create < Trailblazer::Operation
+  include Resolver
+
+  builder-> (model, policy, params) do
+    return Admin if policy.admin?
+    return SignedIn if params[:current_user]
+  end
+```
 
 ## Views
 
@@ -222,13 +284,13 @@ The operation can then parse incoming JSON documents in `validate` and render a
 
 ## Tests
 
-Subject to tests are mainly _Operation_s and _View Model_s, as they encapsulate endpoint behaviour of your app. As a nice side effect, factories are replaced by simple _Operation_ calls.
+Subject to tests are mainly _Operation_s and _View Model_s, as they encapsulate endpoint behavior of your app. As a nice side effect, factories are replaced by simple _Operation_ calls.
 
 
 
 ## Overview
 
-Trailblazer is basically a mash-up of mature gems that have been developed over the past 10 years and are used in hundreds and thousands of production apps.
+Trailblazer is a collection of mature gems that have been developed over the past 10 years and are used in thousands of production apps.
 
 Using the different layers is completely optional and up to you: Both Cells and Reform can be excluded from your stack if you wish so.
 
@@ -243,26 +305,6 @@ class CommentsController < ApplicationController
   include Trailblazer::Operation::Controller
 ```
 
-### Rendering the form object
-
-Operations can populate and present their form object so it can be used with `simple_form` and other form helpers.
-
-```ruby
-
-def new
-  form Comment::Create
-end
-```
-
-This will run the operation but _not_ its `validate` code. It then sets the `@form` instance variable in the controller so it can be rendered.
-
-```haml
-= form_for @form do |f|
-  = f.input f.body
-```
-
-`#form` is meant for HTML actions like `#new` and `#edit`, only.
-
 ### Running an operation
 
 If you do not intend to maintain different request formats, the easiest is to use `#run` to process incoming data using an operation.
@@ -514,14 +556,14 @@ When inheriting, the block is `class_eval`ed in the inherited class' context and
 
 ### CRUD Semantics
 
-You can make Trailblazer find and create models for you using the `CRUD` module.
+You can make Trailblazer find and create models for you using the `Model` module.
 
 ```ruby
-require 'trailblazer/operation/crud'
+require 'trailblazer/operation/model'
 
 class Comment < ActiveRecord::Base
   class Create < Trailblazer::Operation
-    include CRUD
+    include Model
     model Comment, :create
 
     contract do
@@ -537,9 +579,9 @@ class Comment < ActiveRecord::Base
 end
 ```
 
-You have to tell `CRUD` the model class and what action to implement using `::model`.
+You have to tell `Model` the model class and what action to implement using `::model`.
 
-Note how you do not have to pass the `@model` to validate anymore. Also, the `@model` gets created automatically and is accessable using `Operation#model`.
+Note how you do not have to pass the `@model` to validate anymore. Also, the `@model` gets created automatically and is accessible using `Operation#model`.
 
 In inherited operations, you can override the action, only, using `::action`.
 
@@ -614,14 +656,6 @@ to `config/initializers/trailblazer.rb` and implementation classes like `Operati
 
 If you structure your CRUD operations using the `app/concepts/*/crud.rb` file layout we use in the book, the `crud.rb` files are not gonna be found by Rails automatically. It is a good idea to enable CRUD autoloading.
 
-At the end of your `config/application.rb` file, add the following.
-
-```ruby
-require "trailblazer/rails/railtie"
-```
-
-This will go through `app/concepts/`, find all the `crud.rb` files, autoload their corresponding namespace (e.g. `Thing`, which is a model) and then load the `crud.rb` file.
-
 
 ## Installation
 
@@ -629,6 +663,7 @@ The obvious needs to be in your `Gemfile`.
 
 ```ruby
 gem "trailblazer"
+gem "trailblazer-rails" # if you are in rails.
 gem "cells"
 ```
 

data/Rakefile

@@ -6,7 +6,7 @@ default_task = Rake::Task[:build]
 
 Rake::TestTask.new(:test) do |test|
   test.libs << 'test'
-  test.test_files = FileList['test/*_test.rb', "test/operation/*_test.rb"]
+  test.test_files = FileList['test/*_test.rb', "test/operation/**/*_test.rb"]
   test.verbose = true
 end
 

data/lib/trailblazer/autoloading.rb

@@ -1,8 +1,11 @@
 Trailblazer::Operation.class_eval do
   autoload :Controller, "trailblazer/operation/controller"
   autoload :Responder,  "trailblazer/operation/responder"
-  autoload :CRUD,       "trailblazer/operation/crud"
+  autoload :Model,      "trailblazer/operation/model"
   autoload :Collection, "trailblazer/operation/collection"
   autoload :Dispatch,   "trailblazer/operation/dispatch"
   autoload :Module,     "trailblazer/operation/module"
+  autoload :Representer,"trailblazer/operation/representer"
+  autoload :Policy,     "trailblazer/operation/policy"
+  autoload :Resolver,   "trailblazer/operation/resolver"
 end

data/lib/trailblazer/endpoint.rb

@@ -1,31 +1,25 @@
 module Trailblazer
+  # Encapsulates HTTP-specific logic needed before running an operation.
+  # Right now, all this does is #document_body!
   # To be used in Lotus, Roda, Rails, etc.
   class Endpoint
-    def initialize(controller, operation_class, params, request, config)
-      @controller = controller
+    def initialize(operation_class, params, request, options)
       @operation_class = operation_class
       @params  = params
       @request = request
-      @config  = config
+      @is_document  = options[:is_document]
     end
 
     def call
-      @controller.send(:process_params!, params) # FIXME.
-
       document_body! if document_request?
-
-      res, operation = yield # Create.run(params)
-      @controller.send(:setup_operation_instance_variables!, operation)
-
-      [res, operation] # DISCUSS: do we need result here? or can we just go pick op.valid?
+      yield # Create.run(params)
     end
 
   private
-    attr_reader :params, :operation_class, :request, :controller
+    attr_reader :params, :operation_class, :request
 
     def document_request?
-      # request.format == :html
-      @config[:document_formats][request.format.to_sym]
+      @is_document
     end
 
     def document_body!

data/lib/trailblazer/operation.rb

@@ -1,9 +1,9 @@
-require "uber/builder"
 require "reform"
 
-
 module Trailblazer
   class Operation
+    require "trailblazer/operation/builder"
+    extend Builder # imports ::builder_class and ::build_operation.
     extend Uber::InheritableAttr
     inheritable_attr :contract_class
     self.contract_class = Reform::Form.clone
@@ -15,8 +15,8 @@ module Trailblazer
     end
 
     class << self
-      def run(*params, &block) # Endpoint behaviour
-        res, op = build_operation_class(*params).new.run(*params)
+      def run(params, &block) # Endpoint behaviour
+        res, op = build_operation(params).run
 
         if block_given?
           yield op if res
@@ -30,49 +30,55 @@ module Trailblazer
       def reject(*args)
         res, op = run(*args)
         yield op if res == false
-        return op
+        op
       end
 
       # ::call only returns the Operation instance (or whatever was returned from #validate).
       # This is useful in tests or in irb, e.g. when using Op as a factory and you already know it's valid.
-      def call(*params)
-        build_operation_class(*params).new(raise_on_invalid: true).run(*params).last
+      def call(params)
+        build_operation(params, raise_on_invalid: true).run.last
       end
-      alias_method :[], :call # TODO: deprecate #[] in favor of .().
 
-      # Runs #setup! and returns the form object.
-      def present(*params)
-        build_operation_class(*params).new.present(*params)
+      def [](*args) # TODO: remove in 1.1.
+        warn "[Trailblazer] Operation[] is deprecated. Please use Operation.() and have a nice day."
+        call(*args)
       end
 
-      def contract(&block)
-        contract_class.class_eval(&block)
+      # Runs #setup! and returns the form object.
+      def present(params)
+        build_operation(params).present
       end
 
-    private
-      def build_operation_class(*params)
-        class_builder.call(*params) # Uber::Builder::class_builder
+      # This is a DSL method. Use ::contract_class and ::contract_class= for the explicit version.
+      #   Op.contract #=> returns contract class
+      #   Op.contract do .. end # defines contract
+      #   Op.contract CommentForm # copies (and subclasses) external contract.
+      #   Op.contract CommentForm do .. end # copies and extends contract.
+      def contract(constant=nil, &block)
+        return contract_class unless constant or block_given?
+
+        self.contract_class= Class.new(constant) if constant
+        contract_class.class_eval(&block) if block_given?
       end
     end
 
-    include Uber::Builder
 
-    def initialize(options={})
+    def initialize(params, options={})
+      @params           = params
+      @options          = options
       @valid            = true
-      @raise_on_invalid = options[:raise_on_invalid] || false
+
+      setup!(params) # assign/find the model
     end
 
     #   Operation.run(body: "Fabulous!") #=> [true, <Comment body: "Fabulous!">]
-    def run(*params)
-      setup!(*params) # where do we assign/find the model?
-
-      process(*params)
+    def run
+      process(@params)
 
       [valid?, self]
     end
 
-    def present(*params)
-      setup!(*params)
+    def present
       contract!
       self
     end
@@ -92,23 +98,33 @@ module Trailblazer
     end
 
   private
-    def setup!(*params)
-      setup_params!(*params)
+    module Setup
+      def setup!(params)
+        setup_params!(params)
+        build_model!(params)
+      end
 
-      @model = model!(*params)
-      setup_model!(*params)
-    end
+      def setup_params!(params)
+      end
 
-    # Implement #model! to find/create your operation model (if required).
-    def model!(*params)
-    end
+      def build_model!(*args)
+        assign_model!(*args) # @model = ..
+        setup_model!(*args)
+      end
 
-    # Override to add attributes that can be infered from params.
-    def setup_model!(*params)
-    end
+      def assign_model!(*args)
+        @model = model!(*args)
+      end
 
-    def setup_params!(*params)
+      # Implement #model! to find/create your operation model (if required).
+      def model!(params)
+      end
+
+      # Override to add attributes that can be infered from params.
+      def setup_model!(params)
+      end
     end
+    include Setup
 
     def validate(params, model=nil, contract_class=nil)
       contract!(model, contract_class)
@@ -133,7 +149,7 @@ module Trailblazer
 
     # When using Op::[], an invalid contract will raise an exception.
     def raise!(contract)
-      raise InvalidContract.new(contract.errors.to_s) if @raise_on_invalid
+      raise InvalidContract.new(contract.errors.to_s) if @options[:raise_on_invalid]
     end
 
     # Instantiate the contract, either by using the user's contract passed into #validate
@@ -153,5 +169,3 @@ module Trailblazer
     end
   end
 end
-
-require 'trailblazer/operation/crud'