kiss 0.9

data/lib/kiss.rb

@@ -0,0 +1,725 @@
+# Kiss - A web application framework for Ruby
+# Copyright (C) 2005-2008 MultiWidget LLC.
+# See LICENSE for details.
+
+# Author::    Shawn Van Ittersum, MultiWidget LLC
+# Copyright:: Copyright (c) 2005-2008 MultiWidget LLC.
+# License::   MIT X11 License
+
+require 'rubygems'
+require 'yaml'
+require 'rack'
+require 'rack/request'
+require 'sequel'
+require 'erubis'
+
+require 'kiss/hacks'
+
+require 'kiss/controller_accessors'
+require 'kiss/template_methods'
+require 'kiss/action'
+
+require 'kiss/model'
+
+module Rack
+  autoload :Bench, 'kiss/rack/bench'
+  autoload :EmailErrors, 'kiss/rack/email_errors'
+  autoload :Facebook, 'kiss/rack/facebook'
+  autoload :FileNotFound, 'kiss/rack/file_not_found'
+  autoload :LogExceptions, 'kiss/rack/log_exceptions'
+  autoload :ShowDebug, 'kiss/rack/show_debug'
+  autoload :ShowExceptions, 'kiss/rack/show_exceptions'
+end
+
+# Kiss - An MVC web application framework for Ruby, built on:
+# * Erubis template engine
+# * Sequel database ORM library
+# * Rack web server abstraction
+class Kiss
+  autoload :ExceptionReport, 'kiss/exception_report'
+  autoload :Mailer, 'kiss/mailer'
+  autoload :Iterator, 'kiss/iterator'
+  autoload :Form, 'kiss/form'
+  autoload :SequelSession, 'kiss/sequel_session'
+  
+  attr_reader :action, :action_subdir, :action_path, :extension, :host, :template_dir,
+    :email_template_dir, :upload_dir, :evolution_dir, :public_dir, :params, :args, :db,
+    :login, :request, :environment, :content_types
+  
+  @@default_action = 'index'
+  
+  @@cookie_name = 'Kiss'
+  
+  @@content_types = {
+    :rhtml => 'text/html',
+    :html => 'text/html',
+    :txt  => 'text/plain',
+    :xml  => 'application/xml',
+    :doc  => 'application/msword',
+    :xls  => 'application/application/vnd.ms-excel'
+  }
+  
+  # Purposely empty class.
+  # ActionDone exception is raised when render complete to abort execution.
+  # Could probably use throw...catch instead.
+  class ActionDone < Exception; end
+  
+  ### Class Methods
+  
+  # Creates a new Kiss instance and runs it.
+  def self.run(options = {})
+    new(options).run
+  end
+  
+  # Converts date strings from m/d/y to y/m/d. Useful for MySQL.
+  def self.mdy_to_ymd(date)
+    return '0000-00-00' unless date && date =~ /\S/
+    date.sub!(/\A\D+/,'')
+    date.sub!(/\D+\Z/,'')
+    
+    month, day, year = date.split(/\D+/,3).each {|s| s.to_i}
+    
+    return 0 unless month && day
+    
+    current_year = Time.now.year
+    if !year || year.length == 0
+      # use current year if year is missing.
+      year = current_year
+    else
+      # convert two-digit years to four-digit years
+      year = year.to_i
+      if year < 100
+        year += 1900
+        year += 100 if year < current_year - 95
+      end
+    end
+    
+    return sprintf("%04d-%02d-%02d",year,month.to_i,day.to_i)
+  end
+  
+  # Returns regexp and error message for validating specified format.
+  # Will likely be rewritten in a future version of Kiss.
+  def self.format_details(format)
+    if format.is_a?(Regexp)
+      return format, 'invalid value'
+    end
+    
+    case format
+    when :integer
+      return /\A\-?\d+\Z/,
+        'must be an integer'
+        
+    when :integer_positive, :positive_integer, :id
+      return /\A\d*[1-9]\d*\Z/,
+        'must be a positive integer'
+
+    when :integer_unsigned, :unsigned_integer, :id_or_zero, :id_zero
+      return /\A\d+\Z/,
+        'must be a positive integer or zero'
+
+    when :integer_negative, :negative_integer
+      return /\A\-\d*[1-9]\d*\Z/,
+        'must be a negative integer'
+        
+    when :decimal
+      return /\A\-?(\d+(\.\d*)?|\.\d+)\Z/,
+        'must be a decimal number'
+
+    when :alphanum
+      return /\A[a-z0-9]+\Z/,
+        'only letters and numbers'
+
+    when :word
+      return /\A\w+\Z/,
+        'only letters, numbers, and _'
+
+    when :email_address
+      return /\A[A-Z0-9._%+-]+\@([A-Z0-9-]+\.)+[A-Z]{2,4}\Z/i,
+        'must be a valid email address'
+
+    when :date
+      return /\A\d+\D\d+(\D\d+)?\Z/,
+        'must be a valid date'
+
+    when :time
+      return /\A\d+\:\d+\s*[ap]m\Z/i,
+        'must be a valid time'
+        
+    when :datetime
+      return /\A\d+\D\d+(\D\d+)?\s+\d{1,2}\:\d{2}\s*[ap]m\Z/i,
+        'must be a valid date and time'
+        
+    end
+  end
+  
+  # Validates value against specified format.
+  # If required is true, value must contain a non-whitespace character.
+  # If required is false, value need not match format if and only if value contains only whitespace.
+  def self.validate_value(value,format,required = false)
+    if required && (value !~ /\S/)
+      # value required
+      return 'required'
+    elsif format && (value =~ /\S/)
+      regexp,error = format_details(format)
+      return error unless value =~ regexp
+    end
+    
+    return nil
+  end
+  
+  # Generates string of random text of the specified length.
+  def self.random_text(length)
+    chars = ('A'..'Z').to_a + ('0'..'9').to_a  # array
+  
+    text = ''
+    size = chars.size
+    length.times { text += chars[rand(size)] }
+    
+    text
+  end
+  
+  # Returns exception cache, for use in Kiss::ExceptionReport.
+  def self.exception_cache
+    @@exception_cache
+  end
+  
+  ### Instance Methods
+  
+  # Adds specified data to exception cache, to be included in reports generated
+  # by Kiss::ExceptionReport in case of an exception.
+  def set_exception_cache(data)
+    @@exception_cache.merge!(data)
+  end
+  
+  # Clears exception cache.
+  def clear_exception_cache
+    @@exception_cache = {}
+  end
+  
+  # Generates string of random text of the specified length.
+  def random_text(*args)
+    self.class.random_text(*args)
+  end
+  
+  # Returns URL/URI of app root (corresponding to top level of action_dir).
+  def app(suffix = nil)
+    suffix ? @app_url + suffix : @app_url
+  end
+  
+  # Returns path of current action, under action_dir.
+  def action
+    @action
+  end
+  
+  # Kiss Model cache, used to invoke and store Kiss database models.
+  #
+  # Example:
+  # models[:users] : database model for `users' table
+  def models
+    @dbm
+  end
+  alias_method :dbm, :models
+  
+  # Returns URL/URI of app's static assets (asset_host or public_uri).
+  def pub(suffix = nil)
+    @pub ||= @options[:asset_host] || (@request.server + @options[:public_uri].to_s)
+    suffix ? @pub + '/' + suffix : @pub
+  end
+  
+  # Returns true if specified path is a directory.
+  # Cache result if file_cache_no_reload option is set; otherwise, always check filesystem.
+  def directory_exists?(dir)
+    @options[:file_cache_no_reload] ? (
+      @directory_cache.has_key?(path) ?
+        @directory_cache[dir] :
+        @directory_cache[dir] = File.directory?(dir)
+      ) : File.directory?(dir)
+  end
+  
+  # Caches the specified file and return its contents.
+  # If block given, executes block on contents, then cache and return block result.
+  # If fnf_file_type given, raises exception (of type fnf_exception_class) if file is not found.
+  def file_cache(path, fnf_file_type = nil, fnf_exception_class = Kiss::FileNotFound)
+    if (@options[:file_cache_no_reload] && @file_cache.has_key?(path)) || @files_cached_this_request[path]
+      return @file_cache[path]
+    end
+    
+    @files_cached_this_request[path] = true
+    
+    if !File.file?(path)
+      raise fnf_exception_class, "#{fnf_file_type} file missing: '#{path}'" if fnf_file_type
+      
+      @file_cache[path] = nil
+      contents = nil
+    else
+      # expire cache if file (or symlink) modified
+      # TODO: what about symlinks to symlinks?
+      if !@file_cache_time[path] ||
+        @file_cache_time[path] < File.mtime(path) ||
+        ( File.symlink?(path) && (@file_cache_time[path] < File.lstat(path).mtime) )
+      
+          @file_cache[path] = nil
+          @file_cache_time[path] = Time.now
+          contents = File.read(path)
+      end
+    end
+      
+    @file_cache[path] ||= begin
+      (block_given?) ? yield(contents) : contents
+    end
+  end
+  
+  # Merges specified options into previously defined/merged Kiss options.
+  def merge_options(config_options)
+    if config_options
+      if env_vars = config_options.delete(:ENV)
+        env_vars.each_pair {|k,v| ENV[k] = v }
+      end
+      if lib_dirs = config_options.delete(:lib_dirs)
+        @lib_dirs.push( lib_dirs )
+      end
+      if gem_dirs = config_options.delete(:gem_dirs)
+        @gem_dirs.push( gem_dirs )
+      end
+      if require_libs = config_options.delete(:require)
+        @require.push( require_libs )
+      end
+    
+      @options.merge!( config_options )
+    end
+  end
+  
+  # Create a new Kiss application instance, based on specified options.
+  def initialize(loader_options = {})
+    # store cached files
+    @file_cache = {}
+    @directory_cache = {}
+    @file_cache_time = {}
+    
+    # if loader_options is string, then it specifies environment
+    # else it should be a hash of config options
+    if loader_options.is_a?(String)
+      loader_options = { :environment => loader_options }
+    end
+    
+    # environment
+    @environment = loader_options[:environment]
+    
+    # directories
+    script_dir = $0.sub(/[^\/]+\Z/,'')
+    script_dir = '' if script_dir == './'
+    @project_dir = script_dir + (loader_options[:project_dir] || loader_options[:root_dir] || '..')
+    Dir.chdir(@project_dir)
+    
+    @config_dir = loader_options[:config_dir] || 'config'
+    
+    # get environment name from config/environment
+    if (@environment.nil?) && File.file?(env_file = @config_dir+'/environment')
+      @environment = File.read(env_file).sub(/\s+\Z/,'')
+    end
+    
+    # init options
+    @options = {}
+    @lib_dirs = ['lib']
+    @gem_dirs = ['gems']
+    @require = []
+    
+    # common (shared) config
+    if (File.file?(config_file = @config_dir+'/common.yml'))
+      merge_options( YAML::load(File.read(config_file)) )
+    end
+    # environment config
+    if (File.file?(config_file = "#{@config_dir}/environments/#{@environment}.yml"))
+      merge_options( YAML::load(File.read(config_file)) )
+    end
+    
+    merge_options( loader_options )
+    
+    # set class vars from options
+    @action_dir = @options[:action_dir] || 'actions'
+    @template_dir = @options[:template_dir] ? @options[:template_dir] : @action_dir
+    
+    @public_dir = @options[:public_dir] || 'public_html'
+    
+    @model_dir = @options[:model_dir] || 'models'
+    @evolution_dir = @options[:evolution_dir] || 'evolutions'
+    
+    @email_template_dir = @options[:email_template_dir] || 'email_templates'
+    @upload_dir = @options[:upload_dir] || 'uploads'
+    
+    @cookie_name = @options[:cookie_name] || 'Kiss'
+    @default_action = @options[:default_action] || @@default_action
+    @action_root_class = @options[:action_class] || Class.new(Kiss::Action)
+    
+    # include lib dirs
+    $LOAD_PATH.unshift(*( @lib_dirs.flatten.select {|dir| File.directory?(dir) } ))
+    
+    # add gem dir to rubygems search path
+    Gem.path.unshift(*( @gem_dirs.flatten.select {|dir| File.directory?(dir) } ))
+    
+    # require libs
+    @require.flatten.each {|lib| require lib }
+    
+    # session class
+    if (@options[:session_class])
+      @session_class = (@options[:session_class].class == Class) ? @options[:session_class] : @options[:session_class].to_const
+    end
+    
+    # load extensions to action class
+    action_extension_path = @action_dir + '/_action.rb'
+    if File.file?(action_extension_path)
+      @action_root_class.class_eval(File.read(action_extension_path),action_extension_path) rescue nil
+    end
+    
+    # set controller access variables
+    @action_root_class.set_controller(self)
+    Kiss::Model.set_controller(self)
+    Kiss::Mailer.set_controller(self)
+    
+    # database
+    if sequel = @options[:database]
+      # open database connection (if not already open)
+      @db = sequel.is_a?(String) ? (Sequel.open sequel) : sequel.is_a?(Hash) ? (Sequel.open sequel) : sequel
+      # add query logging to database class
+      @db.class.class_eval do
+        @@query = nil
+        def self.last_query
+          @@query
+        end
+  
+        alias_method :execute_old, :execute
+        def execute(sql, *args, &block)
+          @@query = sql
+          execute_old(sql, *args, &block)
+        end
+      end
+      
+      if @db.class.name == 'Sequel::MySQL::Database'
+        # fix sequel mysql bugs; add all_rows
+        require 'kiss/sequel_mysql'
+        Sequel.convert_tinyint_to_bool = false unless @options[:convert_tinyint_to_bool]
+      end
+      
+      # create models cache
+      @dbm = Kiss::ModelCache.new(self,@model_dir)
+    end
+    
+    # setup session storage, if session class specified in config
+    @session_class.setup_storage(self) if @session_class
+    
+    self
+  end
+  
+  # Sets up Rack builder options and begins Rack execution. 
+  def run(options = {})
+    merge_options(options)
+    
+    app = self
+    builder_options = @options[:rack_builder] || []
+    rack = Rack::Builder.new do
+      builder_options.each do |builder_option|
+        if builder_option.is_a?(Array)
+          builder_args = builder_option
+          builder_option = builder_args.shift
+        else
+          builder_args = []
+        end
+        
+        unless builder_option.is_a?(Class)
+          builder_option = Rack.const_get(builder_option.to_s)
+        end
+        
+        use(builder_option,*builder_args)
+      end
+
+      run app
+    end
+    
+    handler = @options[:rack_handler] || Rack::Handler::WEBrick
+    if !handler.is_a?(Class)
+      handler = Rack::Handler.const_get(handler.to_s)
+    end
+    handler.run(rack,@options[:rack_handler_options] || {:Port => 4000})
+  end
+  
+  # Processes and responds to requests received via Rack.
+  # Returns Rack::Response object.
+  def call(env)
+    clear_exception_cache
+    
+    check_evolution_number if @db
+    
+    @files_cached_this_request = {}
+    
+    get_request(env)
+    
+    @response = Rack::Response.new
+    
+    begin
+      parse_action_path(@path)
+    
+      setup_session
+      if login_session_valid?
+        load_from_login_session
+      elsif @options[:authenticate_all]
+        if (!@options[:authenticate_exclude].is_a?(Array) ||
+            @options[:authenticate_exclude].select {|action| action == @action}.size == 0)
+          authenticate
+        end
+      end
+      process.render
+    rescue Kiss::ActionDone
+    end
+    finalize_session if @session
+    
+    @response.finish
+  end
+  
+  # Sets up request-specified variables based in request information received from Rack.
+  def get_request(env)
+    @request = Rack::Request.new(env)
+    
+    @app_host = @options[:app_host] ? ('http://' + @options[:app_host]) : @request.server
+    @app_uri = @options[:app_uri] || @request.script_name || ''
+    @app_url =  @app_host + @app_uri
+    
+    @path = @request.path_info || '/'
+    @params = @request.params
+    
+    @host ||= @request.host
+    @protocol = env['HTTPS'] == 'on' ? 'https' : 'http'
+  end
+  
+  # Returns Sequel dataset to evolution_number table, which specifies app's current evolution number.
+  # Creates evolution_number table if it does not exist.
+  def evolution_number_table
+    unless db.table_exists?(:evolution_number)
+      db.create_table :evolution_number do
+        column :version, :integer, :null=> false
+      end
+      db[:evolution_number].insert(:version => 0)
+    end
+    db[:evolution_number]
+  end
+  
+  # Returns app's current evolution number.
+  def evolution_number
+    evolution_number_table.first.version
+  end
+  
+  # Sets app's current evolution number.
+  def evolution_number=(version)
+    evolution_number_table.update(:version => version)
+  end
+  
+  # Check whether there exists a file in evolution_dir whose number is greater than app's
+  # current evolution number. If so, raise an error to indicate need to apply new evolutions.
+  def check_evolution_number
+    version = evolution_number
+    if directory_exists?(@evolution_dir) &&
+        Dir.entries(@evolution_dir).select { |f| f =~ /\A0*#{version+1}_/ }.size > 0
+      raise "current evolution #{version} is outdated; apply evolutions or update evolution number"
+    end
+  end
+  
+  # Loads session from session store (specified by session_class).
+  def setup_session
+    @login = {}
+    @session = @session_class ? begin
+      session = @session_class.persist(@request.cookies[@cookie_name])
+      @_fingerprint = Marshal.dump(session.data).hash
+    
+      cookie_vars = {
+        :value => session.values[:session_id],
+        :path => @options[:cookie_path] || @app_uri,
+        :domain => @options[:cookie_domain] || @request.host
+      }
+      cookie_vars[:expires] = Time.now + @options[:cookie_lifespan] if @options[:cookie_lifespan]
+    
+      # set_cookie here or at render time
+      @response.set_cookie @cookie_name, cookie_vars
+      @login.merge!(session[:login]) if session[:login]
+      
+      session
+    end : {}
+  end
+  
+  # Saves session to session store, if session data has changed since load.
+  def finalize_session
+    @session.save if @_fingerprint != Marshal.dump(@session.data).hash
+  end
+  
+  def session
+    @session
+  end
+  
+  ##### LOGIN SESSION #####
+  
+  # Empties request and session login hashes.
+  def reset_login_session
+    @session[:login] = @login = {}
+  end
+  alias_method :reset_login_data, :reset_login_session
+  
+  # Merges data hash (key-value pairs) into request login hash.
+  def set_login_data(data)
+    @login = @login.merge(data)
+  end
+  
+  # Merges data hash (key-value pairs) into session login hash.
+  def set_login_session(data)
+    set_login_data(data)
+    @session[:login] = (@session[:login] || {}).merge(data)
+  end
+  
+  # Sets expire time of session login hash, after which time it will be reset (emptied).
+  # If given a FixNum, sets expire time to now plus number of seconds.
+  def set_login_expires(time)
+    time = Time.now + time if time.is_a?(Fixnum)
+    set_login_session(:expires_at => time)
+  end
+  
+  # Returns true if login hash is defined and not expired.
+  def login_session_valid?
+    @login && !login_session_expired?
+  end
+  
+  # Returns true if login hash is expired.
+  def login_session_expired?
+    @login && (!@login[:expires_at] || @login[:expires_at] < Time.now)
+  end
+  
+  # Calls login action's load_from_session method to populate request login hash.
+  def load_from_login_session
+    klass = action_class('login')
+    raise 'load_from_login_session called, but no login action found' unless klass
+    
+    action_handler = klass.new
+    action_handler.load_from_session
+  end
+  
+  # Returns path to login action.
+  def login_path
+    @action_dir + '/login.rb'
+  end
+  
+  # If valid login session exists, loads login action to populate request login hash data.
+  # Otherwise, loads and calls login action to authenticate user.
+  def authenticate
+    if login_session_valid?
+      load_from_login_session
+    else
+      klass = action_class('login')
+      raise 'authenticate called, but no login action found' unless klass
+      old_extension = @extension
+      @extension = 'rhtml'
+      process(klass,login_path)
+      @extension = old_extension
+      
+      unless login_session_valid?
+        #raise 'login action completed without setting valid login session'
+      end
+    end
+  end
+  
+  ##### ACTION METHODS #####
+  
+  def action_dir
+    @action_dir
+  end
+  
+  # Creates and caches anonymous class with which to invoke specified (or current) action.
+  def action_class(action = @action)
+    action_path = @action_dir + '/' + action.to_s + '.rb'
+    return nil unless action_path.is_a?(String) && action_path.length > 0
+    
+    file_cache(action_path) do |src|
+      # create new action class, subclass of shared action parent class
+      klass = Class.new(@action_root_class)
+      klass.class_eval(src,action_path) if src
+      klass
+    end
+  end
+  
+  # Parses request URI to determine action path and arguments.
+  def parse_action_path(path)
+    @action_subdir = ''
+    @action = nil
+    
+    redirect_url(app + '/') if path == ''
+    
+    path += @default_action if path =~ /\/\Z/
+    
+    parts = path.sub(/^\/*/,'').split('/')
+    
+    while part = parts.shift
+      raise 'bad action' if part !~ /\A[a-z0-9][\w\-\.]*\Z/i
+      
+      test_path = @action_dir + @action_subdir + '/' + part
+      if directory_exists?(test_path)
+        @action_subdir += '/' + part
+        next
+      end
+      
+      if part =~ /\A(.+)\.(\w+)\Z/
+        @extension = $2
+        part = $1
+      else
+        @extension = 'rhtml'
+      end
+      
+      @action = @action_subdir + '/' + part
+      break
+    end
+    
+    # if no action, must have traversed all parts to a directory
+    # add a trailing slash and try again
+    redirect_url(app + '/' + path + '/') unless @action
+    
+    @action_path = @action_dir + '/' + @action + '.rb'
+    
+    # keep rest of path_info in args
+    @args = parts
+  end
+  
+  # Processes specified (or current) action, by instantiating its anonymous
+  # action class and invoking `call' method on the instance.
+  def process(klass = action_class, action_path = @action_path)
+    action_handler = klass.new
+    action_handler.call
+    
+    # return handler to follow with render
+    action_handler
+  end
+  
+  ##### RACK OUTPUT METHODS #####
+  
+  # Prepares Rack::Response object to be returned to Rack.
+  # Raises Kiss::ActionDone exception to bypass caller stack and return directly 
+  # to Kiss#call.
+  def send_response(output = '',options = {})
+    content_type = options[:content_type] || @content_type || extension ? @@content_types[extension.to_sym] : nil
+    document_encoding ||= 'utf-8'
+    
+    @response['Content-Type'] = "#{content_type}; #{document_encoding}" if content_type
+    @response['Content-Length'] = output.length.to_s
+    @response.body = output
+    
+    raise Kiss::ActionDone
+    
+    # back to Kiss#call, which finalizes session and returns @response
+    # (throws exception if no @response set)
+  end
+  
+  # Sends HTTP 302 response to redirect client browser agent to specified URL.
+  def redirect_url(url)
+    @response.status = 302
+    @response['Location'] = url
+    send_response
+  end
+  
+  # Returns new Kiss::Mailer object using specified options.
+  def new_email(*options)
+    Kiss::Mailer.new(*options)
+  end
+end