billfold 1.0.0

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/.rvmrc

@@ -0,0 +1 @@
+rvm 1.9.2

data/Gemfile

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

data/README.md

@@ -0,0 +1,39 @@
+## Billfold
+
+Billfold provides backend Rails support for OmniAuth. Specifically, it
+routes `/auth/:provider/callback` to
+`Billfold::IdentitiesController#update_or_create!`, which handles
+identity management.
+
+### Requirements
+
+ * Rails 3.x
+
+### Installation
+
+1. Add `gem 'billfold'` to your `Gemfile`
+1. Run `bundle` (or `bundle install`)
+1. Run `rails g billfold:migration`
+
+### Configuration
+
+#### With ActiveRecord
+
+If you don't have User and Identity model classes, run
+`rails g billfold:models` to create them. Otherwise, include
+`Billfold::ActiveRecordUser` and `Billfold::ActiveRecordIdentity` in
+them respectively. You *may* wish to define
+`User#perform_additional_merge_operations!` if you need to do additional
+logic during a user merge.
+
+#### Without ActiveRecord
+
+Include `Billfold::User` and `Billfold::Identity` in the model classes.
+You'll also have do define the following methods:
+
+ * `User.find_by_id(id)`
+ * `User#merge_into!(other_user)`
+ * `Identity.with_provider_and_value(provider, value)`
+ * `Identity#user`
+ * `Identity#update_attributes!`
+ * `Identity#save!`

data/Rakefile

@@ -0,0 +1,26 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+require 'rdoc/task'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Default: run the unit tests."
+task :default => [:spec]
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = "Billfold #{File.read './VERSION'}"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('app/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/app/controllers/billfold/identities_controller.rb

@@ -0,0 +1,53 @@
+module Billfold
+  class IdentitiesController < ApplicationController
+
+    before_filter :require_sign_in, :only => [ :index, :destroy ]
+
+    respond_to :html, :json, :xml
+    helper_method :identities, :identity
+
+    def index
+      respond_to do |format|
+        format.html {}
+        format.json { render :json => identities }
+        format.xml  { render :xml  => identities }
+      end
+    end
+
+    def update_or_create
+      omniauth_hash = request.env['omniauth.auth'] || {}
+      identity = Billfold.identity_class.update_or_create!({
+        :provider => params[:provider],
+        :value    => omniauth_hash['uid'],
+        :data     => omniauth_hash['user_info'],
+        :user     => current_user
+      })
+      self.current_user ||= identity.user
+      respond_to do |format|
+        format.html { redirect_to '/' }
+        format.json { head 201 }
+        format.xml  { head 201 }
+      end
+    end
+
+    def destroy
+      identity.destroy
+      respond_to do |format|
+        format.html { redirect_to :index }
+        format.json { head 200 }
+        format.xml  { head 200 }
+      end
+    end
+
+    private
+
+    def identities
+      @identities ||= current_user.identities
+    end
+
+    def identity
+      @identity ||= current_user.identities.find_by_id(params[:identity_id] || params[:id])
+    end
+
+  end
+end

data/app/views/billfold/identities/_list.html.erb

@@ -0,0 +1,8 @@
+<ul class='identities'>
+  <% identities.each do |id| %>
+    <li class="identity <%= id.provider %>">
+      <%= id.value %>
+      <%= button_to t('billfold.delete'), identity_path(id), :method => :delete, :remote => true, :confirm => true %>
+    </li>
+  <% end %>
+</ul>

data/app/views/billfold/identities/index.html.erb

@@ -0,0 +1,2 @@
+<h2><%= t '.title' %></h2>
+<%= render :partial => 'list', :identities => identities %>

data/billfold.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |gem|
+  gem.name = 'billfold'
+  gem.version = File.read('VERSION')
+  gem.description = %q{Identity Management with OmniAuth}
+  gem.summary = gem.description
+  gem.email = ['james.a.rosen@gmail.com']
+  gem.homepage = 'http://github.com/jamesarosen/billfold'
+  gem.authors = ['James A. Rosen']
+  gem.executables = `git ls-files -- bin/*`.split("\n").map{|f| File.basename(f)}
+  gem.files = `git ls-files`.split("\n")
+  gem.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.require_paths = ['lib']
+  gem.required_rubygems_version = Gem::Requirement.new('>= 1.3.6') if gem.respond_to? :required_rubygems_version=
+
+  gem.add_development_dependency  'rails',        '~> 3.1'
+  gem.add_development_dependency  'bundler'
+  gem.add_development_dependency  'mocha'
+  gem.add_development_dependency  'rake'
+  gem.add_development_dependency  'rspec-rails'
+  gem.add_development_dependency  'sqlite3'
+  gem.add_development_dependency  'factory_girl'
+end

data/config/locales/en.yml

@@ -0,0 +1,6 @@
+en:
+  billfold:
+    delete: delete
+    identities:
+      index:
+        title: Your Identities

data/config/routes.rb

@@ -0,0 +1,11 @@
+Rails.application.routes.draw do
+
+  mount_at = Billfold::Engine.config.mount_at
+
+  post "#{mount_at}auth/:provider/callback" => 'billfold/identities#update_or_create'
+
+  resources :identities, :only => [ :index, :destroy ],
+                         :module => 'billfold',
+                         :path => "#{mount_at}/identities"
+
+end

data/lib/billfold.rb

@@ -0,0 +1,56 @@
+module Billfold
+
+  autoload :ControllerSupport,    'billfold/controller_support'
+  autoload :Identity,             'billfold/identity'
+  autoload :User,                 'billfold/user'
+  autoload :ActiveRecordIdentity, 'billfold/active_record_identity'
+  autoload :ActiveRecordUser,     'billfold/active_record_user'
+
+  class <<self
+    # ## Billfold.user_class
+    #
+    # Used by `Billfold::Identity.update_or_create!` when building new users
+    # and `Billfold::ControllerSupport` when looking up the current user
+    # from the session. Calculated from `Billfold.user_class_name`.
+    def user_class
+      constantize user_class_name
+    end
+
+    # Used by `Billfold::ActiveRecordIdentity` for the `belongs_to :user`
+    # association and by `Billfold.user_class` for getting the actual
+    # class. By default, "User"
+    def user_class_name
+      @user_class ||= 'User'
+    end
+
+    attr_writer :user_class_name
+
+    # ## Billfold.identity_class
+    #
+    # Used by `Billfold::IdentitiesController.update_or_create`. Calculated
+    # from `Billfold.identity_class_name`.
+    def identity_class
+      constantize identity_class_name
+    end
+
+    def identity_class_name
+      @identity_class ||= 'Identity'
+    end
+
+    attr_writer :identity_class_name
+
+    private
+
+    def constantize(string)
+      return nil if string.blank?
+      return string.constantize if string.respond_to?(:constantize)
+      string.to_s.split('::').inject(Object) do |memo, name|
+        raise "#{memo}::#{name} does not exist" unless memo.const_defined?(name)
+        memo = memo.const_get(name)
+      end
+    end
+  end
+
+  require 'billfold/identity'
+  require 'billfold/engine' if defined?(Rails) && Rails::VERSION::MAJOR == 3
+end

data/lib/billfold/active_record_identity.rb

@@ -0,0 +1,47 @@
+require 'active_support/concern'
+require 'billfold/identity'
+
+module Billfold
+
+  # ## Billfold::ActiveRecordIdentity
+  #
+  # Support for an ActiveRecord Identity class. (Builds on top of
+  # `Billfold::Identity`)
+  module ActiveRecordIdentity
+
+    extend ActiveSupport::Concern
+
+    included do
+      raise "Cannot define identity class until Billfold.user_class_name is set" unless Billfold.user_class_name.present?
+      belongs_to :user, :class_name => ::Billfold.user_class_name
+      serialize  :data
+      validates_presence_of :user, :provider, :value
+
+      # There can only be one identity with a given provider and value
+      validates_uniqueness_of :value, :scope => [ :provider ]
+    end
+
+    module ClassMethods
+
+      include Billfold::Identity::ClassMethods
+
+      # ### Billfold::Identity.with_provider_and_value
+      #
+      # Return the identity with the given `provider` and `value`, or `nil`,
+      # if no such identity exists. Including classes *must* redefine this
+      # method.
+      def with_provider_and_value(provider, value)
+        where(:provider => provider, :value => value).first
+      end
+
+    end
+
+    module InstanceMethods
+
+      include Billfold::Identity::InstanceMethods
+
+    end
+
+  end
+
+end

data/lib/billfold/active_record_user.rb

@@ -0,0 +1,46 @@
+require 'active_support/concern'
+require 'billfold/user'
+
+module Billfold
+
+  # ## Billfold::ActiveRecordUser
+  #
+  # Support for an ActiveRecord User class. (Builds on top of
+  # `Billfold::User`)
+  module ActiveRecordUser
+
+    extend ActiveSupport::Concern
+
+    included do
+      raise "Cannot define user class until Billfold.identity_class_name is set" unless Billfold.identity_class_name.present?
+      validates_presence_of :name
+      has_many :identities, :class_name => ::Billfold.identity_class_name
+    end
+
+    module InstanceMethods
+
+      # Merge this user into another user, deleting this user and moving its
+      # identities to the other.
+      def merge_into!(other)
+        raise ArgumentError.new("#{other} is not a #{Billfold.user_class}") unless other.kind_of?(Billfold.user_class)
+        raise ArgumentError.new("#{other} is not saved") if other.new_record?
+        transaction do
+          identities.update_all({ :user_id => other.id })
+          perform_additional_merge_operations!(other)
+          destroy
+        end
+      end
+
+      private
+
+      # This method is called after all identities have been moved from
+      # `other` to `self`, but before `other` has been destroyed and before the
+      # end of the transaction. By default, it does nothing.
+      def perform_additional_merge_operations!(other)
+      end
+
+    end
+
+  end
+
+end

data/lib/billfold/controller_support.rb

@@ -0,0 +1,51 @@
+require 'active_support/concern'
+require 'billfold'
+
+module Billfold
+
+  # ## Billfold::ControllerSupport
+  #
+  # Gets mixed in to `ApplicationController` automatically.
+  module ControllerSupport
+
+    extend ActiveSupport::Concern
+
+    included do
+      helper_method :current_user
+    end
+
+    module InstanceMethods
+
+      protected
+
+      # ### Billfold::ControllerSupport#current_user
+      #
+      # Return the current user, if signed in.
+      def current_user
+        @current_user ||= ::Billfold::user_class.find_by_id(session[:user_id])
+      end
+
+      # ### Billfold::ControllerSupport#current_user=
+      #
+      # Set the signed-in user.
+      def current_user=(user)
+        session[:user_id] = user ? user.id : nil
+        @current_user = user
+      end
+
+      # ### Billfold::ControllerSupport#require_sign_in
+      #
+      # A before filter that requires a user to be signed in. The default
+      # implementation adds a flash message and redirects to /
+      def require_sign_in
+        unless current_user
+          flash['info'] = 'Please sign in'
+          redirect_to root_path
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/billfold/engine.rb

@@ -0,0 +1,25 @@
+require 'billfold'
+require 'rails'
+
+module Billfold
+  class Engine < Rails::Engine
+    engine_name :my_rails_engine
+
+    # Config defaults
+    config.mount_at = '/'
+
+    # Check the gem config
+    initializer "check config" do |app|
+      # make sure mount_at ends with trailing slash
+      config.mount_at += '/' unless config.mount_at.last == '/'
+    end
+
+    initializer "static assets" do |app|
+      app.middleware.use ::ActionDispatch::Static, "#{root}/public"
+    end
+
+    ActiveSupport.on_load(:action_controller) do
+      include Billfold::ControllerSupport
+    end
+  end
+end

data/lib/billfold/identity.rb

@@ -0,0 +1,99 @@
+require 'billfold'
+
+module Billfold
+
+  # ## Billfold::Identity
+  #
+  # Support for an identity class. If you are using ActiveRecord, you
+  # probably want `Billfold::ActiveRecordIdentity`, which includes everything
+  # in this module.
+  #
+  # Requires the following attributes
+  #  * `user` -- the owning `Billfold::User` instance; required
+  #  * `provider` -- the OmniAuth provider name (e.g. "twitter"); required
+  #  * `value` -- the unique identifier (within the scope of `provider`) of
+  #               the identity (e.g. "my_twitter_handle"); required
+  #  * `data` -- additional information passed in from OmniAuth under the
+  #              `"user_info"` key
+  module Identity
+
+    def self.included(base)
+      base.extend ClassMethods
+      base.send(:include, InstanceMethods)
+    end
+
+    module ClassMethods
+
+      # ### Billfold::Identity.with_provider_and_value
+      #
+      # Return the identity with the given `provider` and `value`, or `nil`,
+      # if no such identity exists. Including classes *must* redefine this
+      # method.
+      def with_provider_and_value(provider, value)
+        raise NotImplementedError.new('classes including Billfold::Identity MUST redefine class method with_provider_and_value')
+      end
+
+      # ### Billfold::Identity.update_or_create!
+      #
+      # Updates or creates a `Billfold::Identity`.
+      #
+      # ### Parameters: a single `Hash` with the following keys:
+      #  * `:provider` -- the name of an OmniAuth provider (e.g. "twitter")
+      #  * `:user` -- if nil, creates a new `User` for the `Identity`
+      #  * `:value` -- the unique identifier
+      #  * `:data` -- extra data for the Identity
+      #
+      # ### Behavior
+      #
+      # If `:provider` or `:value` is `nil`, this method raises an
+      # `ArgumentError`.
+      #
+      # If `:user` is `nil`, this method creates a new `User` for the `Identity`.
+      #
+      # If `:user` exists and there is no other `Identity` with the
+      # same `:value`, this method adds a new `Identity` to the `User`.
+      #
+      # If there exists another `Identity` with the same `:value` and
+      # that `Identity` is owned by the given `User`, this method updates that
+      # `Identity`.
+      #
+      # If `:user` exists and there exists another `Identity` with
+      # the same `:value` and that `Identity` is owned by a *different* `User`,
+      # this method merges that User into `:user` and updates the `Identity`.
+      def update_or_create!(attributes = {})
+        raise ArgumentError.new("provider must not be blank") if attributes[:provider].blank?
+        raise ArgumentError.new("value must not be blank") if attributes[:value].blank?
+        identity = with_provider_and_value(attributes[:provider], attributes[:value])
+        if identity
+          old_owner, new_owner = identity.user, attributes[:user]
+          transaction do
+            identity.update_attributes!(attributes)
+            old_owner.merge_into!(new_owner) if old_owner != new_owner
+          end
+        else
+          identity = new(attributes)
+          identity.user = attributes[:user] || ::Billfold.user_class.new(:name => identity.name_for_user)
+          identity.save!
+        end
+        identity
+      end
+
+    end
+
+    module InstanceMethods
+
+      # ### Billfold::Identity#name_for_user
+      #
+      # When creating a new user from an identity, this method is used to
+      # generate a display name. By default, it tries to get the user's name
+      # from the OmniAuth data and falls back on using the identity's provider
+      # and value, but subclasses may have something better to do.
+      def name_for_user
+        (data && data['name']) || "#{provider} #{value}"
+      end
+
+    end
+
+  end
+
+end