interlock 1.0

data/lib/interlock/action_view.rb

@@ -0,0 +1,34 @@
+
+module ActionView #:nodoc:
+  module Helpers #:nodoc:
+    module CacheHelper 
+     
+     #
+     # Mark a corresponding view block for caching. Accepts a :tag key for 
+     # explicit scoping. You can specify dependencies here if you really want
+     # to, for example, if you don't have any controller block at all.
+     #
+     
+     def view_cache(*args, &block)
+       conventional_class = begin; controller.controller_name.classify.constantize; rescue NameError; end
+       options, dependencies = Interlock.extract_options_and_dependencies(args, conventional_class)  
+       
+       key = controller.caching_key(options.value_for_indifferent_key(:ignore), options.value_for_indifferent_key(:tag))      
+       Interlock.register_dependencies(dependencies, key)
+       
+       # Interlock.say key "is rendering"
+   
+       @controller.cache_erb_fragment(
+         block, 
+         key, 
+         :ttl => (options.value_for_indifferent_key(:ttl) or Interlock.config[:ttl])
+       )
+     end
+     
+    #:stopdoc:
+    alias :caching :view_cache # Deprecated
+    #:startdoc:
+     
+    end
+  end
+end

data/lib/interlock/active_record.rb

@@ -0,0 +1,29 @@
+
+module ActiveRecord #:nodoc:
+  class Base
+    
+    #
+    # Convert this record to a tag string.
+    #
+    def to_interlock_tag
+      "#{self.class.name}-#{self.id}".escape_tag_fragment
+    end        
+
+    #
+    # The expiry callback.
+    #
+    
+    def expire_interlock_keys
+      (CACHE.get(Interlock.dependency_key(self.class)) || {}).each do |key, scope|
+        if scope == :all or (scope == :id and key.field(4) == self.to_param.to_s)
+          Interlock.say key, "invalidated by rule #{self.class} -> #{scope.inspect}."
+          Interlock.invalidate key
+        end
+      end
+    end
+    
+    before_save :expire_interlock_keys
+    after_destroy :expire_interlock_keys
+
+  end
+end

data/lib/interlock/config.rb

@@ -0,0 +1,78 @@
+
+module Interlock
+
+  DEFAULTS = {
+    :ttl => 1.day,
+    :namespace => 'app',
+    :servers => ['localhost:11211']
+  }    
+
+  mattr_accessor :config 
+  @@config = DEFAULTS
+  
+  module Config
+    
+    CONFIG_FILE = "#{RAILS_ROOT}/config/memcached.yml"
+  
+    class << self
+  
+      #
+      # Load the configuration file, if available, and then set up the Memcached instance,
+      # Rails settings, and CACHE constants. Should be more or less compatible with
+      # cache_fu.
+      #
+      def run!
+        if File.exist?(CONFIG_FILE)
+          config = YAML.load_file(CONFIG_FILE)
+          config.deep_symbolize_keys!
+
+          Interlock.config.merge!(config[:defaults] || {})
+          Interlock.config.merge!(config[RAILS_ENV.to_sym] || {})
+        end
+        
+        memcached!
+        rails!
+      end
+  
+      # 
+      # Configure memcached for this app.
+      #
+      def memcached!
+        Interlock.config[:namespace] << "-#{RAILS_ENV}"
+  
+        unless defined? Object::CACHE
+          klass = MemCacheWithConsistentHashing rescue MemCache
+          Object.const_set('CACHE', klass.new(Interlock.config))
+          CACHE.servers = Array(Interlock.config[:servers])
+        end
+        
+        class << CACHE
+          def read(*args)
+            get args.first
+          end
+          
+          def write(name, content, options = {})             
+            set(name, 
+              content, 
+              options.is_a?(Hash) ? options[:ttl] : Interlock.config[:ttl] )
+          end          
+        end  
+              
+      end
+      
+      #
+      # Configure Rails to use the memcached store for fragments, and optionally, sessions.
+      #    
+      def rails!
+        # Memcached fragment caching is mandatory
+        ActionController::Base.fragment_cache_store = CACHE
+  
+        if Interlock.config[:sessions]
+          ActionController::Base.session_store = :mem_cache_store
+          ActionController::CgiRequest::DEFAULT_SESSION_OPTIONS.update 'cache' => CACHE      
+        end      
+      end    
+
+    end      
+  end
+end

data/lib/interlock/core_extensions.rb

@@ -0,0 +1,64 @@
+
+class Object
+  def to_interlock_tag
+    string = to_s
+    string = "empty_string" if string.empty? 
+    string.escape_tag_fragment
+  end
+end
+
+class NilClass
+  def to_interlock_tag
+    "untagged".escape_tag_fragment
+  end
+end
+
+class Hash
+  alias :fetch_safely :[]
+
+  def value_for_indifferent_key(key)
+    fetch_safely(key) or fetch_safely(key.to_s) or fetch_safely(key.to_sym)
+  end
+  
+  alias :v :value_for_indifferent_key
+  
+  def indifferentiate!
+    class << self
+      def [](key); value_for_indifferent_key(key); end
+    end        
+    self
+  end
+
+  def indifferentiate
+    self.dup.indifferentiate!    
+  end
+  
+  def deep_symbolize_keys!
+    symbolize_keys!
+    values.each do |value|
+      value.deep_symbolize_keys! if value.is_a? Hash
+    end
+  end
+  
+end
+
+class Array  
+  unless Array.instance_methods.include? "extract_options!"
+  
+    def extract_options!
+      # Method added in Rails rev 7217
+      last.is_a?(Hash) ? pop : {}
+    end
+    
+  end  
+end
+
+class String
+  def field(i)
+    split(":")[i]
+  end
+  
+  def escape_tag_fragment
+    gsub(':', '-').gsub(/[^\w\d\-;]/, '_')
+  end
+end

data/lib/interlock/interlock.rb

@@ -0,0 +1,112 @@
+
+module Interlock
+
+  class InterlockError < StandardError #:nodoc:
+  end  
+  class DependencyError < InterlockError #:nodoc:
+  end  
+  class UsageError < InterlockError #:nodoc:
+  end
+  
+  SCOPE_KEYS = [:controller, :action, :id]
+  
+  mattr_accessor :local_cache
+    
+  class << self
+    #
+    # Extract the dependencies from the rest of the arguments and registers
+    # them with the appropriate models.
+    # 
+    def extract_options_and_dependencies(dependencies, default = nil) 
+      options = dependencies.extract_options!
+      
+      # Hook up the dependencies nested array.
+      dependencies.map! { |klass| [klass, :all] }
+      options.each do |klass, scope| 
+        if klass.is_a? Class 
+          #
+          # Beware! Scoping to :id means that a request's params[:id] must equal 
+          # klass#id or the rule will not trigger. This is because params[:id] is the
+          # only record-specific scope include in the key. 
+          #
+          # If you want fancier invalidation, think hard about whether it really 
+          # matters. Over-invalidation is rarely a problem, but under-invalidation
+          # frequently is. 
+          #
+          # "But I need it!" you say. All right, then start using key tags.
+          #
+          raise Interlock::DependencyError, "#{scope.inspect} is not a valid scope" unless [:all, :id].include?(scope)
+          dependencies << [klass, scope.to_sym]
+        end
+      end    
+
+      unless dependencies.any?
+        # Use the conventional controller/model association if none are provided
+        # Can be skipped by calling caching(nil)
+        dependencies = [[default, :all]]
+      end
+      
+      # Remove nils
+      dependencies.reject! {|klass, scope| klass.nil? }
+      
+      [options.indifferentiate, dependencies]
+    end 
+    
+    #
+    # Add each key with scope to the appropriate dependencies array.
+    #
+    def register_dependencies(dependencies, key)
+      Array(dependencies).each do |klass, scope|
+        dep_key = dependency_key(klass)
+        
+        # Get the value for this class/key out of the global store.
+        this = (CACHE.get(dep_key) || {})[key]
+
+        # Make sure to not overwrite broader scopes.
+        unless this == :all or this == scope
+          # We need to write, so acquire the lock.            
+          CACHE.lock(dep_key) do |hash|
+            Interlock.say key, "registered a dependency on #{klass} -> #{scope.inspect}."
+            (hash || {}).merge({key => scope})
+          end
+        end
+        
+      end
+    end
+
+    def say(key, msg) #:nodoc:
+      RAILS_DEFAULT_LOGGER.warn "** fragment #{key.inspect[1..-2]} #{msg}"
+    end
+     
+    #   
+    # Get the Memcached key for a class's dependency list. We store per-class 
+    # to reduce lock contention.
+    #
+    def dependency_key(klass) 
+      "interlock:#{ENV['RAILS_ASSET_ID']}:dependency:#{klass.name}"
+    end
+    
+    # 
+    # Build a fragment key for an explicitly passed context. Shouldn't be called
+    # unless you need to write your own fine-grained invalidation rules. Make sure
+    # the default ones are really unacceptable before you go to the trouble of
+    # rolling your own.
+    #
+    def caching_key(controller, action, id, tag)
+      raise ArgumentError, "Both controller and action must be specified" unless controller and action
+      
+      id = (id or 'all').to_interlock_tag
+      tag = tag.to_interlock_tag
+
+      "interlock:#{ENV['RAILS_ASSET_ID']}:#{controller}:#{action}:#{id}:#{tag}"
+    end
+    
+    #
+    # Invalidate a particular key.
+    #
+    def invalidate(key)
+      ActionController::Base.fragment_cache_store.delete key
+    end    
+    
+  end    
+end

data/lib/interlock/memcached.rb

@@ -0,0 +1,30 @@
+
+class MemCache
+
+  #
+  # Try to acquire a global lock from memcached for a particular key. 
+  # If successful, yield and set the key to the return value, then release
+  # the lock. 
+  #
+  # Based on http://rubyurl.com/Sw7 , which I partially wrote.
+  #
+
+  def lock(key, lock_expiry = 30, retries = 5)
+    retries.times do |count|
+      response = CACHE.add("lock:#{key}", "Locked by #{Process.pid}", lock_expiry)
+      if response == "STORED\r\n"
+        begin
+          value = yield(CACHE.get(key))
+          CACHE.set(key, value)
+          return value
+        ensure 
+          CACHE.delete("lock:#{key}")
+        end
+      else
+        sleep((2**count) / 2.0)
+      end
+    end
+    raise MemCacheError, "Couldn't acquire lock for #{key}"
+  end
+  
+end

data/lib/interlock.rb

@@ -0,0 +1,25 @@
+
+module Interlock
+end
+
+unless defined? MemCache or defined? MemCacheWithConsistentHashing
+  raise "Interlock requires the memcache-client gem"
+end
+
+if MemCache.constants.include?('SVNURL')
+  raise "You have the Ruby-MemCache gem installed. Interlock uses memcache-client. Please uninstall Ruby-MemCache, or otherwise guarantee that memcache-client will load instead."
+end
+
+require 'interlock/core_extensions'
+require 'interlock/config'
+require 'interlock/interlock'
+require 'interlock/memcached'
+require 'interlock/action_controller'
+require 'interlock/action_view'
+require 'interlock/active_record'
+
+unless ActionController::Base.perform_caching
+  RAILS_DEFAULT_LOGGER.warn "** interlock warning; config.perform_caching == false"
+end
+
+Interlock::Config.run!

data/test/integration/app/README

@@ -0,0 +1,203 @@
+== Welcome to Rails
+
+Rails is a web-application and persistence framework that includes everything
+needed to create database-backed web-applications according to the
+Model-View-Control pattern of separation. This pattern splits the view (also
+called the presentation) into "dumb" templates that are primarily responsible
+for inserting pre-built data in between HTML tags. The model contains the
+"smart" domain objects (such as Account, Product, Person, Post) that holds all
+the business logic and knows how to persist themselves to a database. The
+controller handles the incoming requests (such as Save New Account, Update
+Product, Show Post) by manipulating the model and directing data to the view.
+
+In Rails, the model is handled by what's called an object-relational mapping
+layer entitled Active Record. This layer allows you to present the data from
+database rows as objects and embellish these data objects with business logic
+methods. You can read more about Active Record in
+link:files/vendor/rails/activerecord/README.html.
+
+The controller and view are handled by the Action Pack, which handles both
+layers by its two parts: Action View and Action Controller. These two layers
+are bundled in a single package due to their heavy interdependence. This is
+unlike the relationship between the Active Record and Action Pack that is much
+more separate. Each of these packages can be used independently outside of
+Rails.  You can read more about Action Pack in
+link:files/vendor/rails/actionpack/README.html.
+
+
+== Getting Started
+
+1. At the command prompt, start a new Rails application using the <tt>rails</tt> command
+   and your application name. Ex: rails myapp
+   (If you've downloaded Rails in a complete tgz or zip, this step is already done)
+2. Change directory into myapp and start the web server: <tt>script/server</tt> (run with --help for options)
+3. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!"
+4. Follow the guidelines to start developing your application
+
+
+== Web Servers
+
+By default, Rails will try to use Mongrel and lighttpd if they are installed, otherwise
+Rails will use WEBrick, the webserver that ships with Ruby. When you run script/server,
+Rails will check if Mongrel exists, then lighttpd and finally fall back to WEBrick. This ensures
+that you can always get up and running quickly.
+
+Mongrel is a Ruby-based webserver with a C component (which requires compilation) that is
+suitable for development and deployment of Rails applications. If you have Ruby Gems installed,
+getting up and running with mongrel is as easy as: <tt>gem install mongrel</tt>.
+More info at: http://mongrel.rubyforge.org
+
+If Mongrel is not installed, Rails will look for lighttpd. It's considerably faster than
+Mongrel and WEBrick and also suited for production use, but requires additional
+installation and currently only works well on OS X/Unix (Windows users are encouraged
+to start with Mongrel). We recommend version 1.4.11 and higher. You can download it from
+http://www.lighttpd.net.
+
+And finally, if neither Mongrel or lighttpd are installed, Rails will use the built-in Ruby
+web server, WEBrick. WEBrick is a small Ruby web server suitable for development, but not
+for production.
+
+But of course its also possible to run Rails on any platform that supports FCGI.
+Apache, LiteSpeed, IIS are just a few. For more information on FCGI,
+please visit: http://wiki.rubyonrails.com/rails/pages/FastCGI
+
+
+== Debugging Rails
+
+Sometimes your application goes wrong.  Fortunately there are a lot of tools that
+will help you debug it and get it back on the rails.
+
+First area to check is the application log files.  Have "tail -f" commands running
+on the server.log and development.log. Rails will automatically display debugging
+and runtime information to these files. Debugging info will also be shown in the
+browser on requests from 127.0.0.1.
+
+You can also log your own messages directly into the log file from your code using
+the Ruby logger class from inside your controllers. Example:
+
+  class WeblogController < ActionController::Base
+    def destroy
+      @weblog = Weblog.find(params[:id])
+      @weblog.destroy
+      logger.info("#{Time.now} Destroyed Weblog ID ##{@weblog.id}!")
+    end
+  end
+
+The result will be a message in your log file along the lines of:
+
+  Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1
+
+More information on how to use the logger is at http://www.ruby-doc.org/core/
+
+Also, Ruby documentation can be found at http://www.ruby-lang.org/ including:
+
+* The Learning Ruby (Pickaxe) Book: http://www.ruby-doc.org/docs/ProgrammingRuby/
+* Learn to Program: http://pine.fm/LearnToProgram/  (a beginners guide)
+
+These two online (and free) books will bring you up to speed on the Ruby language
+and also on programming in general.
+
+
+== Debugger
+
+Debugger support is available through the debugger command when you start your Mongrel or
+Webrick server with --debugger. This means that you can break out of execution at any point
+in the code, investigate and change the model, AND then resume execution! Example:
+
+  class WeblogController < ActionController::Base
+    def index
+      @posts = Post.find(:all)
+      debugger
+    end
+  end
+
+So the controller will accept the action, run the first line, then present you
+with a IRB prompt in the server window. Here you can do things like:
+
+  >> @posts.inspect
+  => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>,
+       #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
+  >> @posts.first.title = "hello from a debugger"
+  => "hello from a debugger"
+
+...and even better is that you can examine how your runtime objects actually work:
+
+  >> f = @posts.first
+  => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
+  >> f.
+  Display all 152 possibilities? (y or n)
+
+Finally, when you're ready to resume execution, you enter "cont"
+
+
+== Console
+
+You can interact with the domain model by starting the console through <tt>script/console</tt>.
+Here you'll have all parts of the application configured, just like it is when the
+application is running. You can inspect domain models, change values, and save to the
+database. Starting the script without arguments will launch it in the development environment.
+Passing an argument will specify a different environment, like <tt>script/console production</tt>.
+
+To reload your controllers and models after launching the console run <tt>reload!</tt>
+
+
+== Description of Contents
+
+app
+  Holds all the code that's specific to this particular application.
+
+app/controllers
+  Holds controllers that should be named like weblogs_controller.rb for
+  automated URL mapping. All controllers should descend from ApplicationController
+  which itself descends from ActionController::Base.
+
+app/models
+  Holds models that should be named like post.rb.
+  Most models will descend from ActiveRecord::Base.
+
+app/views
+  Holds the template files for the view that should be named like
+  weblogs/index.erb for the WeblogsController#index action. All views use eRuby
+  syntax.
+
+app/views/layouts
+  Holds the template files for layouts to be used with views. This models the common
+  header/footer method of wrapping views. In your views, define a layout using the
+  <tt>layout :default</tt> and create a file named default.erb. Inside default.erb,
+  call <% yield %> to render the view using this layout.
+
+app/helpers
+  Holds view helpers that should be named like weblogs_helper.rb. These are generated
+  for you automatically when using script/generate for controllers. Helpers can be used to
+  wrap functionality for your views into methods.
+
+config
+  Configuration files for the Rails environment, the routing map, the database, and other dependencies.
+
+db
+  Contains the database schema in schema.rb.  db/migrate contains all
+  the sequence of Migrations for your schema.
+
+doc
+  This directory is where your application documentation will be stored when generated
+  using <tt>rake doc:app</tt>
+
+lib
+  Application specific libraries. Basically, any kind of custom code that doesn't
+  belong under controllers, models, or helpers. This directory is in the load path.
+
+public
+  The directory available for the web server. Contains subdirectories for images, stylesheets,
+  and javascripts. Also contains the dispatchers and the default HTML files. This should be
+  set as the DOCUMENT_ROOT of your web server.
+
+script
+  Helper scripts for automation and generation.
+
+test
+  Unit and functional tests along with fixtures. When using the script/generate scripts, template
+  test files will be generated for you and placed in this directory.
+
+vendor
+  External libraries that the application depends on. Also includes the plugins subdirectory.
+  This directory is in the load path.

data/test/integration/app/Rakefile

@@ -0,0 +1,10 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require(File.join(File.dirname(__FILE__), 'config', 'boot'))
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+require 'tasks/rails'

data/test/integration/app/app/controllers/application.rb

@@ -0,0 +1,10 @@
+# Filters added to this controller apply to all controllers in the application.
+# Likewise, all the methods added will be available for all controllers.
+
+class ApplicationController < ActionController::Base
+  helper :all # include all helpers, all the time
+
+  # See ActionController::RequestForgeryProtection for details
+  # Uncomment the :secret if you're not using the cookie session store
+  protect_from_forgery # :secret => '491bb7f9ad07a91046fcc3756839524b'
+end

data/test/integration/app/app/controllers/eval_controller.rb

@@ -0,0 +1,7 @@
+class EvalController < ApplicationController
+
+  def index
+    render :text => eval(params['string']).inspect
+  end
+  
+end

data/test/integration/app/app/controllers/items_controller.rb

@@ -0,0 +1,32 @@
+class ItemsController < ApplicationController
+
+  before_filter :related
+
+  def index
+    behavior_cache do
+      @items = Item.find(:all)
+    end
+    render :action => 'list'
+  end
+  
+  def show
+    behavior_cache Item => :id do
+      @item = Item.find(params['id'])
+    end
+  end
+  
+  def recent
+    behavior_cache nil, :tag => [:seconds] do
+      @items = Item.find(:all, :conditions => ['updated_at >= ?', params['seconds'].to_i.ago])
+    end
+  end
+  
+  private
+  
+  def related
+    behavior_cache :ignore => :all, :tag => 'related' do
+      @related = "Delicious cake"
+    end
+  end
+  
+end

data/test/integration/app/app/helpers/application_helper.rb

@@ -0,0 +1,3 @@
+# Methods added to this helper will be available to all templates in the application.
+module ApplicationHelper
+end

data/test/integration/app/app/helpers/eval_helper.rb

@@ -0,0 +1,2 @@
+module EvalHelper
+end

data/test/integration/app/app/helpers/items_helper.rb

@@ -0,0 +1,2 @@
+module ItemsHelper
+end

data/test/integration/app/app/models/item.rb

@@ -0,0 +1,2 @@
+class Item < ActiveRecord::Base
+end

data/test/integration/app/app/views/items/list.html.erb

@@ -0,0 +1,10 @@
+
+<h1>List</h1>
+<% view_cache do %>
+  <% @items.each do |item| %>
+    <h3><%= item.name %></h3>
+    <p><%= item.description %></p>
+  <% end %>
+<% end %>
+
+<%= render :partial => 'shared/related' %>

data/test/integration/app/app/views/items/recent.html.erb

@@ -0,0 +1,14 @@
+
+<h1>Recent</h1>
+<% view_cache :tag => [:seconds] do %>
+  <% if @items.any? %>
+    <% @items.each do |item| %>
+      <h3><%= item.name %></h3>
+      <p><%= item.description %></p>
+    <% end %>
+  <% else  %>
+    <h3>Nothing found</h3>
+  <% end  %>
+<% end %>
+
+<%= render :partial => 'shared/related' %>