url_keyed_object 0.1.0

data/.document

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

data/.gitignore

@@ -0,0 +1,21 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Matt Patterson
+
+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.rdoc

@@ -0,0 +1,29 @@
+= Url-keyed Object
+
+Makes it easy to work with ActiveRecord (and other) objects in Rails (and anything else) which want to use an opaque alphanumeric ID in URLs to identify themselves, rather than their database ID.
+
+    /model/1
+    
+versus
+
+    /model/a1c5t
+    
+One exposes your database IDs in your URLs, and the other doesn't. There are cases when that's genuinely useful not to expose IDs directly (changing your Database from MySQL to Something Else, say, or some radical horiztonal partitioning scheme, or easier data migration), but mostly it's a matter of personal taste.
+
+== Documentation
+
+I'm trying to make executable documentation, so all the docs are in the form of Cucumber features, under the +features+ dir. 
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Matt Patterson. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,78 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "url_keyed_object"
+    gem.summary = %Q{Making it easy to work with objects with URL keys}
+    gem.description = %Q{Making it easy to work with Rails objects which use a URL key in their URL instead of their database ID.}
+    gem.email = "matt@reprocessed.org"
+    gem.homepage = "http://github.com/fidothe/url_keyed_object"
+    gem.authors = ["Matt Patterson"]
+    gem.add_development_dependency "rspec", ">= 1.2.9"
+    gem.add_development_dependency "cucumber", ">= 0.5"
+    gem.add_development_dependency "activerecord", ">= 2.3"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+begin
+  require 'cucumber/rake/task'
+  namespace :cucumber do
+    Cucumber::Rake::Task.new(:ok, 'Run features that should pass') do |t|
+      t.fork = true # You may get faster startup if you set this to false
+      t.profile = 'default'
+    end
+    
+    Cucumber::Rake::Task.new(:wip, 'Run features that are being worked on') do |t|
+      t.fork = true # You may get faster startup if you set this to false
+      t.profile = 'wip'
+    end
+    
+    desc 'Run all features'
+    task :all => [:ok, :wip]
+  end
+  desc 'Alias for cucumber:ok'
+  task :cucumber => 'cucumber:ok'
+  
+  task :default => :cucumber
+  
+  task :features => :cucumber do
+    STDERR.puts "*** The 'features' task is deprecated. See rake -T cucumber ***"
+  end
+rescue LoadError
+  desc 'cucumber rake task not available (cucumber not installed)'
+  task :cucumber do
+    abort 'Cucumber rake task is not available. Be sure to install cucumber as a gem or plugin'
+  end
+end
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "url_keyed_object #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/cucumber.yml

@@ -0,0 +1,2 @@
+default: --format pretty --tags ~@wip
+wip:     --format pretty --tags @wip

data/features/fixtures/.gitignore

@@ -0,0 +1 @@
+*.sqlite3

data/features/step_definitions/database_steps.rb

@@ -0,0 +1,7 @@
+require 'tmpdir'
+
+Given /^a database, with this table defined:$/ do |db_string|
+  eval(["class FeatureMigration < ActiveRecord::Migration; def self.up", 
+        db_string, "end; end"].join("\n"))
+  FeatureMigration.migrate(:up)
+end

data/features/step_definitions/eval_steps.rb

@@ -0,0 +1,15 @@
+Given /^this class:$/ do |string|
+  eval string
+end
+
+When /^I (?:make|do) .+:$/ do |string|
+  eval string
+end
+
+Then /^(@[a-zA-Z_0-9]+)\.([a-zA-Z_0-9?!]+) should match \/(.+)\/$/ do |ivar, method, regex|
+  instance_variable_get(ivar).send(method).should match(regex)
+end
+
+Then /^(@[a-zA-Z_0-9]+)\.([a-zA-Z_0-9?!]+) should be (.+)$/ do |ivar, method, value|
+  instance_variable_get(ivar).send(method).should send("be_#{value}")
+end

data/features/step_definitions/feedback_steps.rb

@@ -0,0 +1,8 @@
+Then /^an? (warning|error|debug message|fatal error|info message|unknown) should have been logged$/ do |message_kind|
+  severity = {
+               'warning' => Logger::WARN, 'error' => Logger::ERROR, 
+               'debug message' => Logger::DEBUG, 'info message' => Logger::INFO, 
+               'fatal error' => Logger::FATAL, 'unknown' => Logger::UNKNOWN
+             }[message_kind]
+  @recording_logger.has_message_for_severity?(severity).should be_true
+end

data/features/support/env.rb

@@ -0,0 +1,4 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../../lib')
+require 'url_keyed_object'
+
+require 'spec/expectations'

data/features/support/hooks.rb

@@ -0,0 +1,24 @@
+require 'fileutils'
+
+Before("@db") do |scenario|
+  require 'activerecord'
+  @db_dir = ::Dir.mktmpdir
+  begin
+    # Create the SQLite database
+    ActiveRecord::Base.establish_connection({'adapter' => 'sqlite3',
+    'database' => "#{@db_dir}/feature.sqlite3", 'pool' => 5, 'timeout' => 5000
+    })
+    ActiveRecord::Base.connection
+    @recording_logger = RecordingLogger.new($stderr)
+    ActiveRecord::Base.logger = @recording_logger
+  rescue
+    $stderr.puts $!, *($!.backtrace)
+    $stderr.puts "Couldn't create database for #{"#{@db_dir}/feature.sqlite3".inspect}"
+  end
+end
+
+After("@db") do |scenario|
+  ActiveRecord::Base.connection.disconnect!
+  FileUtils.remove_entry_secure @db_dir
+  @recording_logger.reset_recorder!
+end

data/features/support/recording_logger.rb

@@ -0,0 +1,28 @@
+require 'logger'
+
+class RecordingLogger < Logger
+  def recorded_messages
+    @recorded_messages ||= {}
+  end
+  
+  alias_method :add_original, :add
+  def add(severity, message = nil, progname = nil, &block)
+    record_it(severity, message)
+    super
+  end
+  
+  
+  def reset_recorder!
+    @recorded_messages = {}
+  end
+  
+  def has_message_for_severity?(severity)
+    (!recorded_messages[severity].nil? && !recorded_messages[severity].empty?)
+  end
+  
+  private
+  
+  def record_it(severity, message)
+    (recorded_messages[severity] ||= []) << message
+  end
+end

data/features/with_active_record-basic.feature

@@ -0,0 +1,58 @@
+@db
+Feature: Using with ActiveRecord
+  In order to generate and validate URL keys in an ActiveRecord::Base object
+  A Rails developer
+  Wants to include and use UrlKeyedObject
+  
+  # The most basic use case is for a 5-character ID, stored in the url_key column.
+  # 
+  # Simply including the UrlKeyedObject::ActiveRecord module is enough. 
+  # This makes the url_key attribute protected from mass assignment and read-only.
+  Background:
+    Given a database, with this table defined:
+      """
+      create_table :things do |t|
+        t.string    :url_key, :null => false
+        
+        t.timestamps
+      end
+      """
+    And this class:
+      """
+      class Thing < ActiveRecord::Base
+        include UrlKeyedObject::ActiveRecord
+      end
+      """
+  
+  Scenario: An unsaved model object with UrlKeyedObject included
+    When I make a bare instance:
+      """
+        @instance = Thing.new
+      """
+    Then @instance.url_key should be nil
+  
+  Scenario: A saved model object with UrlKeyedObject included
+    When I make and save an instance:
+      """
+        @instance = Thing.new
+        @instance.save!
+      """
+    Then @instance.url_key should match /[a-z0-9]{5}/
+  
+  Scenario: Attempting to mass-assign url_key ought to fail
+    When I make an instance using mass-assignment:
+      """
+        @instance = Thing.new(:url_key => 'abcde')
+      """
+    Then @instance.url_key should be nil
+    And a warning should have been logged
+  
+  Scenario: Attempting to set url_key ought to fail
+    When I make an instance using mass-assignment:
+      """
+        @instance = Thing.new
+        @instance.url_key = 'abcde'
+      """
+    Then @instance.url_key should be nil
+    And a warning should have been logged
+

data/lib/url_keyed_object/active_record.rb

@@ -0,0 +1,41 @@
+module UrlKeyedObject
+  module ActiveRecord
+    # --
+    # the stuff that actually gets included.
+    # comment included for my benefit, in case I forget (quite likely)
+    # ++
+    
+    def to_param
+      url_key
+    end
+    
+    def url_key=(value)
+      logger.warn('Attempt to set #url_key!')
+      nil
+    end
+    
+    # --
+    # Validations
+    # ++
+    
+    def self.included(model)
+      model.class_eval do
+        before_create :generate_valid_url_key
+      end
+    end
+    
+    protected
+    
+    def generate_valid_url_key
+      new_url_key = UrlKeyedObject.generate_unchecked_url_key
+      while !self.valid_url_key?(new_url_key) do
+        new_url_key = UrlKeyedObject.generate_unchecked_url_key
+      end
+      write_attribute(:url_key, new_url_key)
+    end
+    
+    def valid_url_key?(url_key)
+      self.class.find_by_url_key(url_key).nil?
+    end
+  end
+end

data/lib/url_keyed_object.rb

@@ -0,0 +1,33 @@
+module UrlKeyedObject
+  # --
+  # module-only methods
+  # ++
+  class << self
+    # holds an array so a base-31 column (units / tens / hundreds) equiv can be 
+    # encoded as an ASCII character
+    def key_encoding
+      @key_encoding ||= ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "0", 
+                         "a", "b", "c", "d", "e", "f", "g", "h", "j", "k", "m",
+                         "n", "p", "q", "r", "s", "v", "w", "x", "y", "z"]
+    end
+    
+    # generates a url key from a random 5-digit base 31 number, without checking its uniqueness
+    def generate_unchecked_url_key
+      (1..5).collect do
+        key_encoding[rand(31)]
+      end.join('')
+    end
+    
+    # Validate the well-formedness of a URL key
+    def well_formed_url_key?(url_key)
+      !url_key.match(/^[0-9abcdefghjkmnpqrsvwxyz]{5}$/).nil?
+    end
+    
+    # decode a moderately dirty URL key
+    def decode_url_key(url_key)
+      url_key.downcase.tr('o', '0').tr('il', '1')
+    end
+  end
+end
+
+require 'url_keyed_object/active_record'

data/spec/spec.opts

@@ -0,0 +1,2 @@
+--color
+--format=specdoc

data/spec/spec_helper.rb

@@ -0,0 +1,39 @@
+$:.unshift(File.dirname(__FILE__))
+$:.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'url_keyed_object'
+require 'spec'
+require 'spec/autorun'
+require 'rubygems'
+gem 'activerecord'
+
+Spec::Runner.configure do |config|
+  config.mock_with :mocha
+end
+
+Spec::Matchers.define :use_method do |method|
+  chain :for_callback do |callback|
+    @callback = callback
+  end
+
+  match do |model_class|
+    model_class.send("#{@callback.to_s}_callback_chain").find(method)
+  end
+end
+
+class Class
+  def publicize_methods
+    saved_private_instance_methods = self.private_instance_methods
+    saved_protected_instance_methods = self.protected_instance_methods
+    self.class_eval do
+      public *saved_private_instance_methods
+      public *saved_protected_instance_methods
+    end
+    
+    yield
+    
+    self.class_eval do
+      private *saved_private_instance_methods
+      protected *saved_protected_instance_methods
+    end
+  end
+end

data/spec/url_keyed_object/active_record_spec.rb

@@ -0,0 +1,104 @@
+require 'spec_helper'
+require 'active_record'
+require 'tmpdir'
+require 'fileutils'
+require 'logger'
+
+class SpecMigration < ActiveRecord::Migration
+  def self.up
+    create_table :things do |t|
+      t.string    :url_key, :null => false
+      
+      t.timestamps
+    end
+  end
+end
+
+describe UrlKeyedObject::ActiveRecord do
+  before(:all) do
+    @db_dir = ::Dir.mktmpdir
+    begin
+      # Create the SQLite database
+      ActiveRecord::Base.establish_connection({'adapter' => 'sqlite3',
+      'database' => "#{@db_dir}/spec.sqlite3", 'pool' => 5, 'timeout' => 5000
+      })
+      ActiveRecord::Base.connection
+    rescue
+      $stderr.puts $!, *($!.backtrace)
+      $stderr.puts "Couldn't create database for #{"#{@db_dir}/feature.sqlite3".inspect}"
+    end
+    
+    SpecMigration.migrate(:up)
+    
+    @url_keyed_class = Class.new(ActiveRecord::Base)
+    @url_keyed_class.class_eval do
+      set_table_name 'things'
+      def self.name
+        'UrlKeyedObjectMock'
+      end
+      
+      include UrlKeyedObject::ActiveRecord
+    end
+    
+    ActiveRecord::Base.logger = Logger.new(STDERR)
+  end
+  
+  after(:all) do
+    ActiveRecord::Base.connection.disconnect!
+    FileUtils.remove_entry_secure @db_dir
+  end
+  
+  it "should protect URL keys from mass-assignment" do
+    url_keyed_object = @url_keyed_class.new(:url_key => 'woo')
+    
+    url_keyed_object.url_key.should be_nil
+  end
+  
+  it "should not allow URL keys to be set" do
+    url_keyed_object = @url_keyed_class.new
+    
+    url_keyed_object.url_key = 'dfghj'
+    
+    url_keyed_object.url_key.should be_nil
+  end
+  
+  describe "ensuring unique URL keys get created " do
+    it "should be able to verify that a URL key is valid" do
+      @url_keyed_class.expects(:find_by_url_key).with('a_url').returns(nil)
+      url_keyed_object = @url_keyed_class.new
+      
+      @url_keyed_class.publicize_methods do
+        url_keyed_object.valid_url_key?('a_url').should be_true
+      end
+    end
+    
+    it "should be able to verify that a URL key is not valid" do
+      @url_keyed_class.expects(:find_by_url_key).with('a_url').returns(@url_keyed_class.new)
+      url_keyed_object = @url_keyed_class.new
+      
+      @url_keyed_class.publicize_methods do
+        url_keyed_object.valid_url_key?('a_url').should be_false
+      end
+    end
+    
+    it "should be able to keep attempting to create a URL key until one is valid" do
+      url_keyed_object = @url_keyed_class.new
+      valid_url_sequence = sequence('valid url sequence')
+      
+      UrlKeyedObject.expects(:generate_unchecked_url_key).in_sequence(valid_url_sequence).returns('a1url')
+      url_keyed_object.expects(:valid_url_key?).in_sequence(valid_url_sequence).returns(false)
+      UrlKeyedObject.expects(:generate_unchecked_url_key).in_sequence(valid_url_sequence).returns('a2url')
+      url_keyed_object.expects(:valid_url_key?).in_sequence(valid_url_sequence).returns(true)
+      
+      @url_keyed_class.publicize_methods do
+        url_keyed_object.generate_valid_url_key
+        
+        url_keyed_object.url_key.should == 'a2url'
+      end
+    end
+    
+    it "should use a before_create callback to ensure that a URL key is created" do
+      @url_keyed_class.should use_method(:generate_valid_url_key).for_callback(:before_create)
+    end
+  end
+end

data/spec/url_keyed_object_spec.rb

@@ -0,0 +1,41 @@
+require 'spec_helper'
+
+describe UrlKeyedObject do
+  it "should be able to generate a 5-character URL key" do
+    UrlKeyedObject.generate_unchecked_url_key.should match(/[0-9abcdefghjkmnpqrsvwxyz]{5}/)
+  end
+  
+  describe "decoding a moderately dirty URL key (case insensitivity, ambiguous character replacement)" do
+    it "should be able to cope with O o 0 ambiguity" do
+      UrlKeyedObject.decode_url_key('Oo0ab').should == '000ab'
+    end
+    
+    it "should be able to cope with 1 I i L l ambiguity" do
+      UrlKeyedObject.decode_url_key('1IiLl').should == '11111'
+    end
+    
+    it "should be able to cope with uppercase" do
+      UrlKeyedObject.decode_url_key('ABCDE').should == 'abcde'
+    end
+  end
+  
+  describe "well-formedness of URL keys" do
+    it "should be able to confirm that a URL key is well-formed" do
+      UrlKeyedObject.well_formed_url_key?('0ab9d').should be_true
+    end
+    
+    it "should report that malformed URL keys are NOT well-formed" do
+      ['DfZZZ', # upper case
+       'abcdef', # too long
+       'iabcd', # ambiguous character
+       'tabcd', # ambiguous character
+       'uabcd', # ambiguous character
+       '_abcd', # illegal character
+       'ab,cd', # illegal character
+       'ab.cd', # illegal character
+      ].each do |malformed_url_key|
+        UrlKeyedObject.well_formed_url_key?(malformed_url_key).should be_false
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification 
+name: url_keyed_object
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Matt Patterson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-19 00:00:00 +00:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.2.9
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: cucumber
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0.5"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "2.3"
+    version: 
+description: Making it easy to work with Rails objects which use a URL key in their URL instead of their database ID.
+email: matt@reprocessed.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .document
+- .gitignore
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- cucumber.yml
+- features/fixtures/.gitignore
+- features/step_definitions/database_steps.rb
+- features/step_definitions/eval_steps.rb
+- features/step_definitions/feedback_steps.rb
+- features/support/env.rb
+- features/support/hooks.rb
+- features/support/recording_logger.rb
+- features/with_active_record-basic.feature
+- lib/url_keyed_object.rb
+- lib/url_keyed_object/active_record.rb
+- spec/spec.opts
+- spec/spec_helper.rb
+- spec/url_keyed_object/active_record_spec.rb
+- spec/url_keyed_object_spec.rb
+has_rdoc: true
+homepage: http://github.com/fidothe/url_keyed_object
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Making it easy to work with objects with URL keys
+test_files: 
+- spec/spec_helper.rb
+- spec/url_keyed_object/active_record_spec.rb
+- spec/url_keyed_object_spec.rb