objectify 0.0.3 → 0.0.5

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.gitignore

@@ -1,3 +1,48 @@
+# rcov generated
+coverage
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
 .bundle
-.idea
-pkg
+
+# built gems
+*.gem
+
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+#
+# * Create a file at ~/.gitignore
+# * Include files you want ignored
+# * Run: git config --global core.excludesfile ~/.gitignore
+#
+# After doing this, these files will be ignored in all your git projects,
+# saving you from having to 'pollute' every project you touch with them
+#
+# Not sure what to needs to be ignored for particular editors/OSes? Here's some ideas to get you started. (Remember, remove the leading # of the line)
+#
+# For MacOS:
+#
+#.DS_Store
+
+# For TextMate
+#*.tmproj
+#tmtags
+
+# For emacs:
+#*~
+#\#*
+#.\#*
+
+# For vim:
+#*.swp
+
+# For redcar:
+#.redcar
+
+# For rubinius:
+#*.rbc

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -1,3 +1,3 @@
-source "http://rubygems.org"
+source "https://rubygems.org"
 
 gemspec

data/Gemfile.lock

@@ -1,28 +1,117 @@
 PATH
   remote: .
   specs:
-    objectify (0.0.2)
-      activesupport (>= 2.3)
+    bitlove-objectify (0.0.1)
+      i18n
+      rails (>= 3.0.0)
 
 GEM
-  remote: http://rubygems.org/
+  remote: https://rubygems.org/
   specs:
-    activesupport (3.0.5)
-    diff-lcs (1.1.2)
-    rake (0.8.7)
-    rspec (2.5.0)
-      rspec-core (~> 2.5.0)
-      rspec-expectations (~> 2.5.0)
-      rspec-mocks (~> 2.5.0)
-    rspec-core (2.5.1)
-    rspec-expectations (2.5.0)
+    actionmailer (3.1.1)
+      actionpack (= 3.1.1)
+      mail (~> 2.3.0)
+    actionpack (3.1.1)
+      activemodel (= 3.1.1)
+      activesupport (= 3.1.1)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      i18n (~> 0.6)
+      rack (~> 1.3.2)
+      rack-cache (~> 1.1)
+      rack-mount (~> 0.8.2)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.0.2)
+    activemodel (3.1.1)
+      activesupport (= 3.1.1)
+      builder (~> 3.0.0)
+      i18n (~> 0.6)
+    activerecord (3.1.1)
+      activemodel (= 3.1.1)
+      activesupport (= 3.1.1)
+      arel (~> 2.2.1)
+      tzinfo (~> 0.3.29)
+    activeresource (3.1.1)
+      activemodel (= 3.1.1)
+      activesupport (= 3.1.1)
+    activesupport (3.1.1)
+      multi_json (~> 1.0)
+    arel (2.2.3)
+    bourne (1.0)
+      mocha (= 0.9.8)
+    builder (3.0.0)
+    diff-lcs (1.1.3)
+    erubis (2.7.0)
+    git (1.2.5)
+    hike (1.2.1)
+    i18n (0.6.0)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    json (1.7.3)
+    mail (2.3.3)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.18)
+    mocha (0.9.8)
+      rake
+    multi_json (1.3.5)
+    polyglot (0.3.3)
+    rack (1.3.6)
+    rack-cache (1.2)
+      rack (>= 0.4)
+    rack-mount (0.8.3)
+      rack (>= 1.0.0)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.1)
+      rack (>= 1.0)
+    rails (3.1.1)
+      actionmailer (= 3.1.1)
+      actionpack (= 3.1.1)
+      activerecord (= 3.1.1)
+      activeresource (= 3.1.1)
+      activesupport (= 3.1.1)
+      bundler (~> 1.0)
+      railties (= 3.1.1)
+    railties (3.1.1)
+      actionpack (= 3.1.1)
+      activesupport (= 3.1.1)
+      rack-ssl (~> 1.3.2)
+      rake (>= 0.8.7)
+      rdoc (~> 3.4)
+      thor (~> 0.14.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
       diff-lcs (~> 1.1.2)
-    rspec-mocks (2.5.0)
+    rspec-mocks (2.4.0)
+    sprockets (2.0.4)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (!= 1.3.0, ~> 1.1)
+    thor (0.14.6)
+    tilt (1.3.3)
+    treetop (1.4.10)
+      polyglot
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.33)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  objectify!
-  rake
-  rspec
+  bitlove-objectify!
+  bourne (= 1.0)
+  bundler (~> 1.0.0)
+  jeweler (~> 1.6.4)
+  mocha (= 0.9.8)
+  rspec (~> 2.4.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 James Golick, BitLove Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,230 @@
+# objectify
+
+Objectify is a framework that codifies good object oriented design practices for building maintainable rails applications.
+
+## How it works
+
+Objectify has two primary components:
+
+  1. A request execution framework that separates the responsibilities that are typically jammed together in rails controller actions in to 3 types of components: Policies, Services, and Responders. Properly separating and assigning these responsibilities makes for far more testable code, and facilitates better reuse of components.
+
+  The flow of an objectify request is as follows:
+
+    0. Objectify actions are configured in the routes file:
+
+      ```ruby
+        # config/routes.rb
+        # ... snip ...
+        objectify.resources :pictures
+      ```
+
+      Objectify currently only supports resourceful actions, but that's just a temporary thing.
+
+    1. The policy chain is resolved (based on the various levels of configuration) and executed. Objectify calls the #allowed?(...) method on each policy in the chain. If one of the policies fails, the chain short-circuits at that point, and objectify executes the configured responder for that policy.
+
+      An example Policy:
+
+      ```ruby
+        class RequiresLoginPolicy
+          # more on how current user gets injected below
+          def allowed?(current_user) 
+            !current_user.nil?
+          end
+        end
+      ```
+
+      A responder, in case that policy fails.
+
+      ```ruby
+        class UnauthenticatedResponder
+          # yes, at some point we probably need a better interface
+          # for handling responses, but this'll do for now.
+          def call(controller, renderer)
+            renderer.redirect_to controller.login_url
+          end
+        end
+      ```
+
+      Here's how you setup the RequiresLoginPolicy to run by default (you can configure specific actions to ignore it), and connect the policy with its responder.
+
+      ```ruby
+        # config/routes.rb
+        MyApp::Application.routes.draw do
+          objectify.defaults :policies => :requires_login
+          objectify.policy_responders :requires_login => :unauthenticated
+        end
+      ```
+
+    2. If all the policies succeed, the service for that action is executed. A service is typically responsible for fetching and / or manipulating data.
+
+      A very simple example of a service:
+
+      ```ruby
+        class PicturesCreateService
+          # the current_user and the request's params will be automatically injected here.
+          def call(current_user, params)
+            current_user.pictures.create params[:picture]
+          end
+        end
+      ```
+
+    3. Finally, the responder is executed. Following with our Pictures#create example:
+
+      ```ruby
+        class PicturesCreateResponder
+          # service_result is exactly what it sounds like
+          def call(service_result, controller, renderer)
+            if service_result.persisted?
+              renderer.redirect_to service_result
+            else
+              # this is the only way that you can pass data to the view layer
+              # and you can only pass one thing. Hint: use a presenter.
+              renderer.data(service_result)
+              renderer.render :template => "pictures/edit.html.erb"
+            end
+          end
+        end
+      ```
+
+  2. A dependency injection framework. Objectify automatically injects dependencies in to objects it manages based on parameter names. So, if you have a service method signature like: PictureCreationService#call(params), objectify will automatically inject the request's params when it calls that method. It's very simple to create custom injections by implementing Resolver classes. More on that below.
+
+
+## What if I have a bunch of existing rails code?
+
+Objectify has a legacy mode that allows you to execute the policy chain as a before_filter in your ApplicationController. You can also configure policies (and skip_policies) for your "legacy" actions. That way, access control code is shared between the legacy and objectified components of your application.
+
+I completely rewrote our legacy authentication system as a set of objectify policies, resolvers, and services - I'm gonna package that up and release it soon.
+
+Here's how to run the policy chain in your ApplicationController - it'll figure out which policies to run itself:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Objectify::Rails::ControllerHelpers
+
+  around_filter :objectify_around_filter
+  before_filter :execute_policy_chain
+end
+```
+
+And to configure policies for a legacy action:
+
+```ruby
+# config/routes.rb
+MyApp::Application.routes.draw do
+  objectify.defaults :policies => :requires_login
+  objectify.policy_responders :requires_login => :unauthenticated
+  objectify.legacy_action :controller, :action, :policies => [:x, :y, :z],
+                                                :skip_policies => [:requires_login]
+end
+```
+
+Then, you need to create an ObjectifyController that inherits from ApplicationController, and configure objectify to use that:
+
+```ruby
+# app/controllers/objectify_controller.rb
+class ObjectifyController < ApplicationController
+  include Objectify::Rails::LegacyControllerBehaviour
+end
+```
+
+```ruby
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+    # ...snip...
+    objectify.objectify_controller = "objectify"
+  end
+end
+```
+
+
+## Custom Injections
+
+Several of the above methods have parameters named 'current_user'. By default, objectify won't know how to inject a parameter by that name, so it'll raise an error when it encounters one. Here's how to create a custom resolver for it that'll automatically get found by name.
+
+```ruby
+# app/resolvers/current_user_resolver.rb
+class CurrentUserResolver
+  def initialize(user_finder = User)
+    @user_finder = user_finder
+  end
+
+  # note that resolvers themselves get injected
+  def call(session)
+    @user_finder.find_by_id(session[:current_user_id])
+  end
+end
+```
+
+### Why did you constructor-inject the User constant in to the CurrentUserResolver?
+  
+Because that makes it possible to test in isolation.
+
+```ruby
+describe "CurrentUserResolver" do
+  before do
+    @user        = stub("User")
+    @user_finder = stub("UserFinder", :find_by_id => nil)
+    @user_finder.stubs(:find_by_id).with(10).returns(@user)
+
+    @resolver = CurrentUserResolver.new(@user_finder)
+  end
+
+  it "returns whatever the finder returns" do
+    @resolver.call({:current_user_id => 42}).should be_nil
+    @resolver.call({:current_user_id => 10}).should == @user
+  end
+end
+```
+
+## Views
+
+Objectify has two major impacts on your views.
+
+  1. You can only pass one variable from an objectified action to the controller. You do that by calling renderer.data(the_object_you_want_to_pass). Then, you call objectify_data in the view to fetch the data. If it's not there, it'll raise an error. Use a presenter or some kind of other struct object to pass multiple objects to your views.
+
+  2. You can reuse your policies in your views. require "objectify/rails/helpers" and add Objectify::Rails::Helpers to your helpers list, and you'll get a helper called #policy_allowed?(policy_name). Yay code reuse.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "objectify", "> 0"
+
+# config/application.rb
+module MyApp
+  class Application < Rails::Application
+    require "objectify/rails/application"
+    require "objectify/rails/controller"
+    # only have to require this if you want objectify logging
+    require "objectify/rails/log_subscriber" 
+    include Objectify::Rails::Application
+  end
+end
+```
+
+## Issues
+
+We're using this thing in production to serve millions of requests every day. However, it's far from being complete. Here are some of the problems that still need solving:
+
+  * Support for all the kinds of routing that rails does.
+  * Caching of policy results per-request, so we don't have to run them twice if they're used in views.
+  * Smarter injection strategies, and possibly caching.
+  * ???
+
+## Credits
+
+  * Author: James Golick @jamesgolick
+  * Advice (and the idea for injections based on method parameter names): Gary Bernhardt @garybernhardt
+  * Feedback: Jake Douglas @jakedouglas
+  * Feedback: Julie Haché @juliehache
+  * The gem name: Andrew Kiellor @akiellor
+
+## The other objectify gem
+
+  If you were looking for the gem that *used* to be called objectify on rubygems.org, it's here: https://github.com/akiellor/objectify
+
+## Copyright
+
+Copyright (c) 2012 James Golick, BitLove Inc. See LICENSE.txt for
+further details.