attr_encodable 0.0.6

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Flip Sasser
+
+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,143 @@
+attr_encodable
+=
+
+Never override `as_json` again! **attr_encodable** adds attribute black- or white-listing for ActiveRecord serialization, as well as default serialization options. This is especially useful for protecting private attributes when building a public API.
+
+Install
+==
+
+Install using Rubygems:
+
+	gem install attr_encodable
+
+Install using Bundler:
+
+	gem 'attr_encodable'
+
+Install in Rails 2.x (in your environment.rb file)
+
+	config.gem 'attr_encodable'
+
+Usage
+==
+
+White-listing
+===
+
+You can whitelist or blacklist attributes for serialization using the `attr_encodable` and `attr_unencodable` class methods. Let's look at an example. For this example, we'll use the following classes:
+
+	class User < ActiveRecord::Base
+		has_many :permissions
+		validates_presence_of :email, :password
+		
+		def foobar
+			"baz"
+		end
+	end
+	
+	class Permission < ActiveRecord::Base
+		belongs_to :user
+		validates_presence_of :name, :user
+
+		def hello
+			"World!"
+		end
+	end
+ 
+... with the following schema:
+
+	create_table :permissions, :force => true do |t|
+		t.belongs_to :user
+		t.string :name
+	end
+	
+	create_table :users, :force => true do |t|
+		t.string :login, :limit => 48
+		t.string :email, :limit => 128
+		t.string :name, :limit => 32
+		t.string :password, :limit => 60
+		t.boolean :admin, :default => false
+	end
+
+Let's make a user and try encoding them:
+
+	@user = User.create(:name => "Flip", :email => "flip@x451.com", :password => "awesomesauce", :admin => true)
+ 	=> #<User id: 1, login: nil, email: "flip@x451.com", name: "Flip", password: "awesomesauce", admin: true> 
+	@user.to_json
+ 	=> {"name":"Flip","admin":true,"id":1,"password":"awesomesauce","login":null,"email":"flip@x451.com"}
+
+Trouble is, we don't want their admin status OR their password coming through in our API. So why not protect their information a little bit?
+
+	User.attr_encodable :id, :name, :login, :email
+	@user.to_json
+	 => {"name":"Flip","id":1,"login":null,"email":"flip@x451.com"}
+
+Ah, that's so much better! Now whenever we encode a user instance we'll be showing only some default information.
+
+`attr_unencodable` is similar, except that it bans an attribute. Following along with the example above, if we then called `attr_unencodable`, we could
+restrict our user's information even more. Let's say I don't want my e-mail getting out:
+
+	User.attr_unencodable :email
+	@user.to_json
+	 => {"name":"Flip","id":1,"login":null}
+
+Alright! Now you can't see my e-mail. Sucker.
+
+Default `:include` and `:method` options
+===
+
+`to_json` isn't just concerned with attributes. It also supports `:include`, which includes a relationship with `to_json` called on **it**, as well `:methods`, which adds the result of calling methods on the instance as well.
+
+Let's try it out.
+
+	User.attr_encodable :foobar
+	@user.to_json
+	 => {"name":"Flip","foobar":"baz","id":1,"login":null}
+
+With includes, our example might look like this:
+
+	class User < ActiveRecord::Base
+		attr_encodable :id, :name, :login, :permissions
+		has_many :permissions
+	end
+	
+	@user.to_json
+	=> {"name":"Flip","foobar":"baz","id":1,"login":null,"permissions":[]}
+
+Neato! And of course, when `:permissions` is serialized, it will take into account any `attr_encodable` settings the Permissions class has!
+
+Renaming Attributes
+===
+
+Sometimes you don't want an attribute to come out in JSON named what it's named in the database. There are two options you can pursue here.
+
+Prefix it!
+====
+
+**attr_encodable** supports prefixing of attribute names. Just pass an options hash onto the end of the method with a :prefix key and you're good to go. Example:
+
+	class User < ActiveRecord::Base
+		attr_encodable :ed, :prefix => :i_will_hunt
+	end
+
+	@user.to_json
+	=> {"i_will_hunt_ed":true}
+
+Rename it completely!
+====
+
+If you don't want to prefix, just rename the whole damn thing:
+
+	class User < ActiveRecord::Base
+		attr_encodable :admin => :superuser
+	end
+	
+	@user.to_json
+	#=> {"superuser":true}
+
+Renaming and prefixing work for any `:include` and `:methods` arguments you pass in as well!
+
+Okay, that's all. Thanks for stopping by.
+
+Copyright &copy; 2011 Flip Sasser
+

data/lib/attr_encodable.rb

@@ -0,0 +1,132 @@
+require 'active_record'
+
+module Encodable
+  module ClassMethods
+    def attr_encodable(*attributes)
+      prefix = begin
+        if attributes.last.is_a?(Hash)
+          attributes.last.assert_valid_keys(:prefix)
+          prefix = attributes.extract_options![:prefix]
+        end
+      rescue ArgumentError
+      end
+      unless @encodable_whitelist_started
+        # Since we're white-listing, make sure we black-list every attribute to begin with
+        unencodable_attributes.push *column_names.map(&:to_sym)
+        @encodable_whitelist_started = true
+      end
+      stash_encodable_attribute = lambda {|method, value|
+        if prefix
+          value = "#{prefix}_#{value}"
+        end
+        method = method.to_sym
+        value = value.to_sym
+        renamed_encoded_attributes.merge!({method => value}) if method != value
+        # Un-black-list any attribute we white-listed
+        unencodable_attributes.delete method
+        default_attributes.push method
+      }
+      attributes.each do |attribute|
+        if attribute.is_a?(Hash)
+          attribute.each do |method, value|
+            stash_encodable_attribute.call(method, value)
+          end
+        else
+          stash_encodable_attribute.call(attribute, attribute)
+        end
+      end
+    end
+
+    def attr_unencodable(*attributes)
+      unencodable_attributes.push *attributes.map(&:to_sym)
+    end
+
+    def default_attributes
+      @default_attributes ||= begin
+        default_attributes = []
+        superk = superclass
+        while superk.respond_to?(:default_attributes)
+          default_attributes.push(*superk.default_attributes)
+          superk = superk.superclass
+        end
+        default_attributes
+      end
+    end
+
+    def renamed_encoded_attributes
+      @renamed_encoded_attributes ||= begin
+        renamed_encoded_attributes = {}
+        superk = superclass
+        while superk.respond_to?(:renamed_encoded_attributes)
+          renamed_encoded_attributes.merge!(superk.renamed_encoded_attributes)
+          superk = superk.superclass
+        end
+        renamed_encoded_attributes
+      end
+    end
+
+    def unencodable_attributes
+      @unencodable_attributes ||= begin
+        unencodable_attributes = []
+        superk = superclass
+        while superk.respond_to?(:unencodable_attributes)
+          unencodable_attributes.push(*superk.unencodable_attributes)
+          superk = superk.superclass
+        end
+        unencodable_attributes
+      end
+    end
+  end
+
+  module InstanceMethods
+    def serializable_hash(options = {})
+      if options && options[:only]
+        # We DON'T want to fuck with :only and :except showing up in the same call. This is a disaster.
+        super
+      else
+        options ||= {}
+        original_except = if options[:except]
+          options[:except] = Array(options[:except]).map(&:to_sym)
+        else
+          options[:except] = []
+        end
+        # This is a little bit confusing. ActiveRecord's default behavior is to apply the :except arguments you pass
+        # in to any :include options UNLESS it's overridden on the :include option. In the event that we have some
+        # *default* excepts that come from Encodable, we want to ignore those and pass only whatever the original
+        # :except options from the user were on down to the :include guys.
+        inherited_except = original_except - self.class.default_attributes
+        case options[:include]
+        when Array, Symbol
+          # Convert includes arrays or singleton symbols into a hash with our original_except scope
+          includes = Array(options[:include])
+          options[:include] = Hash[*includes.map{|association| [association, {:except => inherited_except}]}.flatten]
+        else
+          options[:include] ||= {}
+        end
+        # Exclude the black-list
+        options[:except].push *self.class.unencodable_attributes
+        # Include any default :include or :methods arguments that were passed in earlier
+        self.class.default_attributes.each do |attribute, as|
+          if association = self.class.reflect_on_association(attribute)
+            options[:include][attribute] = {:except => inherited_except}
+          elsif respond_to?(attribute) && !self.class.column_names.include?(attribute.to_s)
+            options[:methods] ||= Array(options[:methods]).compact
+            options[:methods].push attribute
+          end
+        end
+        as_json = super(options)
+        unless self.class.renamed_encoded_attributes.empty?
+          self.class.renamed_encoded_attributes.each do |attribute, as|
+            as_json[as.to_s] = as_json.delete(attribute) || as_json.delete(attribute.to_s)
+          end
+        end
+        as_json
+      end
+    end
+  end
+end
+
+if defined? ActiveRecord::Base
+  ActiveRecord::Base.extend Encodable::ClassMethods
+  ActiveRecord::Base.send(:include, Encodable::InstanceMethods)
+end

data/spec/attr_encodable_spec.rb

@@ -0,0 +1,193 @@
+require "lib/attr_encodable"
+
+describe Encodable do
+  it "should automatically extend ActiveRecord::Base" do
+    ActiveRecord::Base.should respond_to(:attr_encodable)
+    ActiveRecord::Base.should respond_to(:attr_unencodable)
+  end
+
+  before :each do
+    ActiveRecord::Base.include_root_in_json = false
+    ActiveRecord::Base.establish_connection({:adapter => 'sqlite3', :database => ':memory:', :pool => 5, :timeout => 5000})
+    class ::Permission < ActiveRecord::Base; belongs_to :user; def hello; "World!"; end; end
+    class ::User < ActiveRecord::Base; has_many :permissions; def foobar; "baz"; end; end
+    silence_stream(STDOUT) do
+      ActiveRecord::Schema.define do
+        create_table :permissions, :force => true do |t|
+          t.belongs_to :user
+          t.string :name
+        end
+        create_table :users, :force => true do |t|
+          t.string   "login",              :limit => 48
+          t.string   "email",              :limit => 128
+          t.string   "first_name",         :limit => 32
+          t.string   "last_name",          :limit => 32
+          t.string   "encrypted_password", :limit => 60
+          t.boolean  "developer",                         :default => false
+          t.boolean  "admin",                          :default => false
+          t.boolean  "password_set",                      :default => true
+          t.boolean  "verified",                          :default => false
+          t.datetime "created_at"
+          t.datetime "updated_at"
+          t.integer  "notifications"
+        end
+      end
+    end
+    @user = User.create({
+      :login => "flipsasser",
+      :first_name => "flip",
+      :last_name => "sasser",
+      :email => "flip@foobar.com",
+      :encrypted_password => ActiveSupport::SecureRandom.hex(30),
+      :developer => true,
+      :admin => true,
+      :password_set => true,
+      :verified => true,
+      :notifications => 7
+    })
+    @user.permissions.create(:name => "create_blog_posts")
+    @user.permissions.create(:name => "edit_blog_posts")
+    # Reset the options for each test
+    [Permission, User].each do |klass|
+
+      klass.class_eval do
+        @default_attributes = nil
+        @encodable_whitelist_started = nil
+        @renamed_encoded_attributes = nil
+        @unencodable_attributes = nil
+      end
+    end
+  end
+
+  it "should favor whitelisting to blacklisting" do
+    User.unencodable_attributes.should == []
+    User.attr_unencodable 'foo', 'bar', 'baz'
+    User.unencodable_attributes.should == [:foo, :bar, :baz]
+    User.attr_encodable :id, :first_name
+    User.unencodable_attributes.map(&:to_s).should == ['foo', 'bar', 'baz'] + User.column_names - ['id', 'first_name']
+  end
+
+  describe "at the parent model level" do
+    it "should not mess with to_json unless when attr_encodable and attr_unencodable are not set" do
+      @user.as_json == @user.attributes
+    end
+
+    it "should not mess with :include options" do
+      @user.as_json(:include => :permissions) == @user.attributes.merge(:permissions => @user.permissions.as_json)
+    end
+
+    it "should not mess with :methods options" do
+      @user.as_json(:methods => :foobar) == @user.attributes.merge(:foobar => "baz")
+    end
+
+    it "should allow me to whitelist attributes" do
+      User.attr_encodable :login, :first_name, :last_name
+      @user.as_json.should == @user.attributes.slice('login', 'first_name', 'last_name')
+    end
+
+    it "should allow me to blacklist attributes" do
+      User.attr_unencodable :login, :first_name, :last_name
+      @user.as_json.should == @user.attributes.except('login', 'first_name', 'last_name')
+    end
+
+    # Of note is the INSANITY of ActiveRecord in that it applies :only / :except to :include as well. Which is
+    # obviously insane. Similarly, it doesn't allow :methods to come along when :only is specified. Good god, what
+    # a shame.
+    it "should allow me to whitelist attributes without messing with :include" do
+      User.attr_encodable :login, :first_name, :last_name
+      @user.as_json(:include => :permissions).should == @user.attributes.slice('login', 'first_name', 'last_name').merge(:permissions => @user.permissions.as_json)
+    end
+
+    it "should allow me to blacklist attributes without messing with :include and :methods" do
+      User.attr_unencodable :login, :first_name, :last_name
+      @user.as_json(:include => :permissions, :methods => :foobar).should == @user.attributes.except('login', 'first_name', 'last_name').merge(:permissions => @user.permissions.as_json, :foobar => "baz")
+    end
+
+    it "should not screw with :include if it's a hash" do
+      User.attr_unencodable :login, :first_name, :last_name
+      @user.as_json(:include => {:permissions => {:methods => :hello, :except => :id}}, :methods => :foobar).should == @user.attributes.except('login', 'first_name', 'last_name').merge(:permissions => @user.permissions.as_json(:methods => :hello, :except => :id), :foobar => "baz")
+    end
+  end
+
+  describe "at the child model level when the paren model has attr_encodable set" do
+    before :each do
+      User.attr_encodable :login, :first_name, :last_name
+    end
+
+    it "should not mess with to_json unless when attr_encodable and attr_unencodable are not set on the child, but are on the parent" do
+      @user.permissions.as_json == @user.permissions.map(&:attributes)
+    end
+
+    it "should not mess with :include options" do
+      # This is testing that the implicit ban on the :id attribute from User.attr_encodable is not
+      # applying to serialization of permissions
+      @user.as_json(:include => :permissions)[:permissions].first['id'].should_not be_nil
+    end
+
+    it "should inherit any attr_encodable options from the child model" do
+      User.attr_encodable :id
+      Permission.attr_encodable :name
+      as_json = @user.as_json(:include => :permissions)
+      as_json[:permissions].first['id'].should be_nil
+      as_json['id'].should_not be_nil
+    end
+    
+    # it "should allow me to whitelist attributes" do
+    #   User.attr_encodable :login, :first_name, :last_name
+    #   @user.as_json.should == @user.attributes.slice('login', 'first_name', 'last_name')
+    # end
+    # 
+    # it "should allow me to blacklist attributes" do
+    #   User.attr_unencodable :login, :first_name, :last_name
+    #   @user.as_json.should == @user.attributes.except('login', 'first_name', 'last_name')
+    # end
+  end
+
+  it "should let me specify automatic includes as well as attributes" do
+    User.attr_encodable :login, :first_name, :id, :permissions
+    @user.as_json.should == @user.attributes.slice('login', 'first_name', 'id').merge(:permissions => @user.permissions.as_json)
+  end
+
+  it "should let me specify methods as well as attributes" do
+    User.attr_encodable :login, :first_name, :id, :foobar
+    @user.as_json.should == @user.attributes.slice('login', 'first_name', 'id').merge(:foobar => "baz")
+  end
+
+  describe "reassigning" do
+    it "should let me reassign attributes" do
+      User.attr_encodable :id => :identifier
+      @user.as_json.should == {'identifier' => @user.id}
+    end
+
+    it "should let me reassign attributes alongside regular attributes" do
+      User.attr_encodable :login, :last_name, :id => :identifier
+      @user.as_json.should == {'identifier' => 1, 'login' => 'flipsasser', 'last_name' => 'sasser'}
+    end
+    
+    it "should let me reassign multiple attributes with one delcaration" do
+      User.attr_encodable :id => :identifier, :first_name => :foobar
+      @user.as_json.should == {'identifier' => 1, 'foobar' => 'flip'}
+    end
+
+    it "should let me reassign :methods" do
+      User.attr_encodable :foobar => :w00t
+      @user.as_json.should == {'w00t' => 'baz'}
+    end
+
+    it "should let me reassign :include" do
+      User.attr_encodable :permissions => :deez_permissions
+      @user.as_json.should == {'deez_permissions' => @user.permissions.as_json}
+    end
+
+    it "should let me specify a prefix to a set of attr_encodable's" do
+      User.attr_encodable :id, :first_name, :foobar, :permissions, :prefix => :t
+      @user.as_json.should == {'t_id' => @user.id, 't_first_name' => @user.first_name, 't_foobar' => 'baz', 't_permissions' => @user.permissions.as_json}
+    end
+  end
+
+  it "should propagate down subclasses as well" do
+    User.attr_encodable :name
+    class SubUser < User; end
+    SubUser.unencodable_attributes.should == User.unencodable_attributes
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification 
+name: attr_encodable
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 6
+  version: 0.0.6
+platform: ruby
+authors: 
+- Flip Sasser
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-15 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 41
+        segments: 
+        - 0
+        - 9
+        - 9
+        version: 0.9.9
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 2
+        - 0
+        version: "2.0"
+  type: :development
+  version_requirements: *id002
+description: "\n    attr_encodable enables you to set up defaults for what is included or excluded when you serialize an ActiveRecord object. This is especially useful for protecting private attributes when building a public API.\n  "
+email: flip@x451.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.md
+files: 
+- LICENSE
+- README.md
+- lib/attr_encodable.rb
+- spec/attr_encodable_spec.rb
+has_rdoc: true
+homepage: http://github.com/Plinq/attr_encodable
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: An attribute black- or white-list for ActiveRecord serialization
+test_files: 
+- spec/attr_encodable_spec.rb