payload 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c9e68c664efe4b32e13624aa82380db246b9774e
+  data.tar.gz: 4cf13b1014a69ec3d3faeb9d1e0fea439c33bb83
+SHA512:
+  metadata.gz: 6ca9dcd639d3c26d9f9e0598343dc0f83ed702ac303206788bbee9505240e5a4b357823a9395f1cb84ada129c4125117cfb0c3f89fd66238ca9999864d2c8876
+  data.tar.gz: 88b884efc4ebd0555b7eda0edaea9a2310d01f184ffa9a57c90a3803f9be557840926dbcb2c4b34579be973882d2853e5e3766eac3186b7f181f0d615605e0ba

data/.gitignore

@@ -0,0 +1,4 @@
+.bundle
+.yardoc
+doc
+pkg

data/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+If you'd like to contribute:
+
+1. Fork the [official repository](https://github.com/thoughtbot/payload).
+2. Make your changes in a topic branch.
+3. Submit a pull request.
+
+Notes:
+
+* Contributions without tests won't be accepted.
+* Please don't update the Gem version.

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    payload (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.5)
+    rack (1.5.2)
+    rake (10.3.2)
+    rspec (2.14.1)
+      rspec-core (~> 2.14.0)
+      rspec-expectations (~> 2.14.0)
+      rspec-mocks (~> 2.14.0)
+    rspec-core (2.14.8)
+    rspec-expectations (2.14.5)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.14.6)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  payload!
+  rack
+  rake
+  rspec (~> 2.14.1)

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2014 Joe Ferris and thoughtbot, 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,242 @@
+# Payload
+
+Payload is a lightweight framework for specifying, injecting, and using
+dependencies. It facilitates run-time assembly of dependencies and makes it
+plausible to use inversion of control beyond the controller level. It also
+attempts to remove boilerplate code for common patterns such as defining
+factories and applying decorators.
+
+Overview
+--------
+
+The framework makes it easy to define dependencies from application code without
+resorting to singletons, constants, or globals. It also won't cause any
+class-reloading issues during development.
+
+Define simple dependencies in `config/dependencies.rb` using services:
+
+    service :payment_client do |container|
+      PaymentClient.new(ENV['PAYMENT_HOST'])
+    end
+
+You can inject dependencies into controllers.
+
+For example, in `app/controllers/payments_controller.rb`:
+
+    class PaymentsController < ApplicationController
+      def create
+        payment = Payment.new(params[:payment], dependencies[:payment_client])
+        receipt = payment.process
+        redirect_to receipt
+      end
+    end
+
+You can easily test this dependency in a controller spec:
+
+    describe PaymentsController do
+      describe '#create' do
+        it 'processes a payment' do
+          payment_params = :product_id => '123', amount: '25'
+          client = stub_service(:payment_client)
+          payment = double('payment', process: true)
+          Payment.stub(:new).with(payment_params, client).and_return(payment)
+
+          post :create, payment_params
+
+          expect(payment).to have_received(:process)
+        end
+      end
+    end
+
+You can further invert control and use factories to hide low-level dependencies
+from controllers entirely.
+
+In `config/dependencies.rb`:
+
+    factory :payment do |container|
+      Payment.new(container[:attributes], container[:payment_client])
+    end
+
+In `app/controllers/payments_controller.rb`:
+
+    class PaymentsController < ApplicationController
+      def create
+        payment = dependencies[:payment].new(attributes: params[:payment])
+        payment.process
+        redirect_to payment
+      end
+    end
+
+You can also stub factories in tests:
+
+    describe PaymentsController do
+      describe '#create' do
+        it 'processes a payment' do
+          payment_params = :product_id => '123', amount: '25'
+          payment = stub_factory_instance(:payment, attributes: payment_params)
+
+          post :create, payment_params
+
+          expect(payment).to have_received(:process)
+        end
+      end
+    end
+
+The controller and its tests are now completely ignorant of `payment_client`,
+and deal only with the collaborator they need: `payment`.
+
+Setup
+-----
+
+Add payload to your Gemfile:
+
+    gem 'payload'
+
+To access dependencies from controllers, include the `Controller` module:
+
+    class ApplicationController < ActionController::Base
+      include Payload::Controller
+    end
+
+Specifying Dependencies
+-----------------------
+
+Edit `config/dependencies.rb` to specify dependencies.
+
+Use the `service` method to define dependencies which can be fully instantiated
+during application bootup:
+
+    service :payment_client do |container|
+      PaymentClient.new(ENV['PAYMENT_HOST'])
+    end
+
+Other dependencies are accessible from the container:
+
+    service :payment_notifier do |container|
+      PaymentNotifier.new(container[:mailer])
+    end
+
+Use the `factory` method to define dependencies which require dependencies from
+the container as well as runtime state which varies per-request:
+
+    factory :payment do |container|
+      Payment.new(container[:attributes], container[:payment_client])
+    end
+
+The container for factory definitions contains all dependencies defined on the
+container as well as dependencies provided when instantiating the factory.
+
+Use the `decorate` method to extend or replace a previously defined dependency:
+
+    decorate :payment do |payment, container|
+      NotifyingPayment.new(payment, container[:payment_notifier])
+    end
+
+Decorated dependencies have access to other dependencies through the container,
+as well as the current definition for that dependency.
+
+Using Dependencies
+------------------
+
+The Railtie inserts middleware into the stack which will inject a container into
+the Rack environment for each request. This is available as `dependencies` in
+controllers and `env[:dependencies]` in the Rack stack.
+
+Use `[]` to access services:
+
+    class PaymentsController < ApplicationController
+      def create
+        dependencies[:payment_client].charge(params[:amount])
+        redirect_to payments_path
+      end
+    end
+
+Use `new` to instantiate dependencies from factories:
+
+    class PaymentsController < ApplicationController
+      def create
+        payment = dependencies[:payment].new(attributes: params[:payment])
+        payment.process
+        redirect_to payment
+      end
+    end
+
+The `new` method accepts a `Hash`. Each element of the `Hash` will be accessible
+from the container in `factory` definitions.
+
+Grouping Dependencies
+---------------------
+
+You can enforce simplicity in your dependency graph by grouping dependencies and
+explicitly exporting only the dependencies you need to expose to the application
+layer.
+
+For example, you can specify payment dependencies in
+`config/dependencies/payments.rb`:
+
+    service :payment_client do |container|
+      PaymentClient.new(ENV['PAYMENT_HOST'])
+    end
+
+    service :payment_notifier do |container|
+      PaymentNotifier.new(container[:mailer])
+    end
+
+    factory :payment do |container|
+      Payment.new(container[:attributes], container[:payment_client])
+    end
+
+    decorate :payment do |payment, container|
+      NotifyingPayment.new(payment, container[:payment_notifier])
+    end
+
+    export :payment
+
+In this example, the final, decorated `:payment` dependency will be available in
+controllers, but `:payment_client` and `:payment_notifier` will not.
+
+You can use this approach to hide low-level dependencies behind a facade and
+only expose the facade to the application layer.
+
+Testing
+-------
+
+To activate testing support, require and mix in the `Testing` module:
+
+    require 'dependencies/testing'
+
+    RSpec.configure do |config|
+      config.include Payload::Testing
+    end
+
+During integration tests, the fully configured container will be used. During
+controller tests, an empty container will be initialized for each test. Tests
+can inject the dependencies they need for each interaction.
+
+This module provides two useful methods:
+
+* `stub_service`: Injects a stubbed service into the test container and returns
+  it.
+* `stub_factory_instance`: Finds or injects a stubbed factory into the test
+  container and expects an instance to be created with the given attributes.
+
+Contributing
+------------
+
+Please see the [contribution guidelines].
+
+[contribution guidelines]: https://github.com/thoughtbot/payload/blob/master/CONTRIBUTING.md
+
+License
+-------
+
+![thoughtbot](http://thoughtbot.com/assets/tm/logo.png)
+
+Payload is Copyright © 2014 Joe Ferris and thoughtbot. It is free software, and
+may be redistributed under the terms specified in the [LICENSE] file.
+
+[LICENSE]: https://github.com/thoughtbot/payload/blob/master/LICENSE
+
+Payload is maintained and funded by [thoughtbot, inc](http://thoughtbot.com/).
+
+The names and logos for thoughtbot are trademarks of thoughtbot, inc.

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rake'
+require 'rspec/core/rake_task'
+
+desc 'Default: run specs'
+task :default => [:spec]
+
+RSpec::Core::RakeTask.new(:spec)

data/lib/payload/container.rb

@@ -0,0 +1,96 @@
+require 'payload/definition_list'
+require 'payload/factory_definition'
+require 'payload/service_definition'
+
+module Payload
+  # Used for configuring and resolving dependencies.
+  #
+  # @see Railtie Railtie to configure and use dependencies in Rails
+  #   applications.
+  # @see RackContainer RackContainer to inject a container into Rack requests.
+  # @see MutableContainer MutableContainer to define dependencies in
+  #   configuration files.
+  class Container
+    # Used internally by {RailsLoader}.
+    #
+    # @api private
+    # @param [DefinitionList] definitions previously defined definitions.
+    def initialize(definitions = DefinitionList.new)
+      @definitions = definitions
+    end
+
+    # Extends or replaces an existing dependency definition.
+    #
+    # @param dependency [Symbol] the name of the dependency to decorate.
+    # @yield [Container] the resolved container.
+    # @yieldreturn the decorated instance.
+    def decorate(dependency, &block)
+      decorated = @definitions.find(dependency).decorate(block)
+      define dependency, decorated
+    end
+
+    # Defines a factory which can be used to instantiate the dependency. Useful
+    # if some dependencies come from the container but others come from runtime
+    # state.
+    #
+    # Resolving the dependency will return an object which responds to `new`.
+    # The `new` method will accept remaining dependencies and return the fully
+    # resolved dependency from the given block.
+    #
+    # @param dependency [Symbol] the name of the dependency to define.
+    # @yield [Container] the resolved container; any arguments to `new` will be
+    #   added to the container.
+    # @yieldreturn an instance of your dependency.
+    def factory(dependency, &block)
+      define dependency, FactoryDefinition.new(block)
+    end
+
+    # Defines a service which can be fully resolved from the container.
+    #
+    # @param dependency [Symbol] the name of the dependency to define.
+    # @yield [Container] the resolved container.
+    # @yieldreturn the instantiated service.
+    def service(dependency, &block)
+      define dependency, ServiceDefinition.new(block)
+    end
+
+    # Resolves and returns dependency.
+    #
+    # @param dependency [Symbol] the name of the dependency to resolve.
+    # @raise [UndefinedDependencyError] for undefined dependencies.
+    def [](dependency)
+      @definitions.find(dependency).resolve(self)
+    end
+
+    # Exports dependencies which can be imported into another container.
+    #
+    # Used internally by {MutableContainer}. Use {MutableContainer#export}.
+    #
+    # @api private
+    # @param names [Array<Symbol>] dependencies to export.
+    # @return [DependencyList] exported dependencies.
+    def export(*names)
+      @definitions.export(names)
+    end
+
+    # Import dependencies which were exported from another container.
+    #
+    # Used internally by {RailsLoader}.
+    #
+    # @api private
+    # @param definitions [DependencyList] definitions to import.
+    # @return [Container] a new container with the imported definitions.
+    def import(definitions)
+      self.class.new @definitions.import(definitions)
+    end
+
+    private
+
+    # Duplicates this object with the definition at the end of the list.
+    #
+    # @api private
+    def define(dependency, definition)
+      self.class.new(@definitions.add(dependency, definition))
+    end
+  end
+end

data/lib/payload/controller.rb

@@ -0,0 +1,12 @@
+module Payload
+  # Mixin to provide access to a {Container}.
+  #
+  # Include this mixin to access dependencies in controllers. The {Container}
+  # will be injected using {RackContainer}.
+  module Controller
+    # @return [Container] dependencies injected from {RackContainer}.
+    def dependencies
+      request.env[:dependencies]
+    end
+  end
+end