fastr 0.0.3 → 0.1.0

data/README.rdoc

@@ -2,6 +2,16 @@
 
 Micro web framework for Ruby. Should be used with an EventMachine rack server.
 
+== Guide
+
+The guide is a work in progress, check it out here: http://chrismoos.com/fastr
+
+You can help with the guide by forking this repository: http://github.com/chrismoos/fastr_doc
+
+== API Documentation
+
+You can see the latest API documentation here: http://rdoc.info/projects/chrismoos/fastr
+
 == Getting Started
 
   $ sudo gem install fastr
@@ -24,16 +34,20 @@ The routes are configured in app/config/routes.rb
 
   router.draw do |route|
   	route.for '/:controller/:action'
-  	#route.for '/home/:action', :action => '[A-Za-z]+'
-  	#route.for '/test', :to => 'home#index'
+  	# route.for '/home/:action', :action => '[A-Za-z]+'
+  	# route.for '/test', :to => 'home#index'
+  	# route.for '/users/:id', :to => 'users#create', :methods => [:post]
   end
   
+By default a route will match against all HTTP methods (GET, POST, etc,.).
+  
 == Settings
 
 Various settings can be configured in app/config/settings.rb
 
   config.log_level = Logger::DEBUG
   config.cache_templates = true
+  config.plugins << MyPluginModule
   
 == Controller
   
@@ -68,15 +82,76 @@ The return for a controller is just a rack response, i.e [200, {"Content-Type" =
 You can also use the following render methods:
 
   render(:text, "My text")
-  
-With HAML, the template is rendered and any instance variables in your controller are available in the template.
 
-  render(:haml, :template => "index") # this searches for index.haml in your app/views/ folder
-  
+Fastr currently has support for HAML and eRuby templates. Any instance variables in your controller are available in the template. The correct template engine will be chosen based on the file extension. By default no template engines will be loaded, you need to explicitly require the engine(s) you will be using in your init.rb file (below the require 'fastr' line):
+
+  require 'fastr'
+  require 'fastr/template/erubis'
+  require 'fastr/template/haml'
+
+Some rendering examples:
+
+  render(:template, "users/index.haml") # this path is relative to your app/views/ folder
+  render(:template, "users/index.html.erb") # this path is relative to your app/views/ folder
+
+You can also specify a hash of data that will be available in the @vars instance variable from your template:
+
+  render(:template, "users/index.html.erb", {:vars => {:greeting => "Aloha!"}})
+
+This is particularly useful when you render a partial:
+
+  render(:partial, "users/_greeting.html.erb", {:vars => {:message => "Welcome!"}})
+
+It's also possible to specify a response code and headers:
+
+  render(:template, "users/index.html.erb", {:vars => {:greeting => "Aloha!"}, :response_code => 200, :headers => "Content-Type" => "text/html"})
+
 JSON:
 
   render(:json, {:status => "ok", :message => "done"})
 
+== Async Responses
+
+You should never block EventMachine. If you're doing any kind of I/O in your controller action you need to render your response asynchronously:
+
+  class DemoController < Fastr::Controller
+    def fast_index
+      EM.add_timer(1) do
+        async_resp { render(:text, "fast_index\n") }
+      end
+      render_async
+    end
+  
+    def slow_index
+      sleep(1)
+      render(:text, "slow_index\n")
+    end
+  end
+
+Here's the difference:
+
+  $ ab -n 10 -c 10 "http://127.0.0.1:4444/demo/fast_index"
+  Concurrency Level:      10
+  Time taken for tests:   1.010 seconds
+  Requests per second:    9.90 [#/sec] (mean)
+
+  $ ab -n 10 -c 10 "http://127.0.0.1:4444/demo/slow_index"
+  Concurrency Level:      10
+  Time taken for tests:   10.011 seconds
+  Requests per second:    1.00 [#/sec] (mean)
+
+If all your actions in a controller are async you can use an after_filter to make things cleaner:
+
+  class DemoController < Fastr::Controller
+    after_filter :render_async
+  
+    def index
+      EM.add_timer(1) do
+        async_resp { render(:text, "fast_index\n") }
+      end
+    end
+  end
+
 == Deferred Responses
 
 fastr also lets you return a deferred response. This is useful if you want to chunk the response back to the client, or have a long running operation that you want to perform without blocking EventMachine.
@@ -112,8 +187,79 @@ The following is an example of a controller action.
     end
   end
   
+== AsyncRecord (experimental database support)
+
+One of the greatest things about running on an event-based server is that you can get accelerated performance in database access. 
+
+Usually there is a lot of time spent blocking for a database query to return. In Fastr, using AsyncRecord, your queries don't block the request. You will receive a callback once the query has completed. This has major performance implications. 
+
+NOTE: Even though your connections are non-blocking to the database server, the database server is still blocking when accessing IO (disk/memory). 
+
+To use AsyncRecord, do the following:
+
+Setup your init.rb file:
+  
+  require 'async_record'
+  conn = AsyncRecord::Connection::MySQL.new(:host => "127.0.0.1", :port => 3306, :user => "root", :database => "database")
+  conn.connect
+  AsyncRecord::Base.set_connection(conn)
+  
+Define a model (app/models/user.rb):
+
+  class User < AsyncRecord::Base
+    set_table_name "users"
+  end
+
+=== Controller  
+  
+In your controller, try the following (remember to put the following in a deferred response):
+  
+=== Get all the rows in the table:
+
+  User.all(:limit => 256) do |users|
+    users.each do |user|
+      response.send_data("#{user.username}\n")
+    end
+    response.succeed
+  end
+  
+=== Find a row by ID
+
+  User.find(1) do |user|
+    if user.nil?
+      response.send_data("User not found")
+    else
+      response.send_data("User: #{user.username}\n")
+    end
+    response.succeed
+  end
+  
+=== Get the count of rows in the table
+
+  User.count do |count|
+    response.send_data("Count: #{count}")
+    response.succeed
+  end
+  
+=== Run a custom query
+
+  User.query("select username from users") do |results|
+    response.send_data("Results: #{results.inspect}")
+    response.succeed
+  end
+  
+WARNING: AsyncRecord is under heavy development, but its pretty cool :).
+  
 == Plugins
 
+=== Loading manually
+
+To explicitly load a plugin that doesn't exist in your custom/plugins directory, you can do the following in your *settings.rb* file:
+
+  config.plugins << MyPluginModule
+
+=== Loading from custom directory
+
 Fastr searches the custom/plugins directory in your application's root directory for loading plugins.
 
 Example structure:
@@ -145,6 +291,36 @@ Here is an example plugin and what is currently supported:
     end
   end
   
+== Filters
+
+You can add before and after filters to your controller. The filters are executed before an action is called, and after.
+
+=== Before Filters
+
+  before_filter :my_before_filter_noop, :my_before_filter_halt
+  
+  def my_before_filter_noop
+    filter_continue # use this if you want the filter chain to continue
+  end
+  
+  def my_before_filter_halt
+    [200, {}, ["STOP HERE AND RETURN"]] # Return a rack response if you want the chain to halt
+  end
+  
+=== After Filters
+
+  after_filter :my_after_filter
+  
+  def my_after_filter(response)
+    # here you can modify the response
+    # response is just a rack response, i.e [200, {}, "Hello, Filter!"]
+    # This filter adds a custom header
+    code, headers, body = *response
+    headers['My-Custom-Header'] = 'vall'
+    
+    [code, headers, body]
+  end
+
 == Static Files
 
 Anything stored in the public folder in your project's root directory will be served as a static file. This directory is checked before the routes. The mime type is set based on the file's extension.

data/bin/fastr

@@ -1,5 +1,7 @@
 #!/usr/bin/env ruby
 
+require 'rubygems'
+require 'fastr'
 require 'fileutils'
 
 module Fastr
@@ -11,7 +13,8 @@ module Fastr
     
     # Directory Structre
 
-    dirs = ['app/config', 'app/controllers', 'app/views', 'app/models', 'lib', 'test', 'public', 'custom/plugins']
+    dirs = ['app/config', 'app/controllers', 'app/views', 'app/models', 'lib', 'test', 'public', 'custom/plugins',
+      'test/unit']
     dirs.each do |dir| 
       FileUtils.mkdir_p("#{app_name}/#{dir}")
     end 
@@ -20,8 +23,9 @@ module Fastr
     File.open("#{app_name}/app/config/routes.rb", "w") do |f|
       f.write("router.draw do |route|\n")
       f.write("\troute.for '/:controller/:action'\n")
-      f.write("\t#route.for '/home/:action', :action => '[A-Za-z]+'\n")
-      f.write("\t#route.for '/test', :to => 'home#index'\n")
+      f.write("\t# route.for '/home/:action', :action => '[A-Za-z]+'\n")
+      f.write("\t# route.for '/test', :to => 'home#index'\n")
+    	f.write("\t# route.for '/users/:id', :to => 'users#create', :methods => [:post]\n")      
       f.write("end")
       f.close
     end
@@ -31,7 +35,7 @@ module Fastr
       f.puts("require 'fastr'")
       f.puts("EM.kqueue = true if EM.kqueue?")
       f.puts("EM.epoll = true if EM.epoll?")
-      f.puts("fastrApp = Fastr::Application.new(File.expand_path(File.dirname(__FILE__)))")
+      f.puts("fastrApp = Fastr::Application.new(::File.expand_path(::File.dirname(__FILE__)))")
       f.puts("app = lambda { |env|")
       f.puts("\tfastrApp.dispatch(env)")
       f.puts("}")
@@ -49,14 +53,33 @@ module Fastr
     # Gemfile
     File.open("#{app_name}/Gemfile", 'a') do |f|
       f.puts "source :gemcutter"
-
-      f.puts "gem 'jeweler'"
-      f.puts "gem 'eventmachine'"
-      f.puts "gem 'haml'"
-      f.puts "\ngem 'fastr'"
+      f.puts "gem 'fastr'"
       f.close
     end
     
+    # init.rb
+    File.open("#{app_name}/app/config/init.rb", "w") do |f|
+      f.puts('# Enable AsyncRecord support (experimental)')
+      f.puts("# you must add \"require 'async_record'\" to your config.ru file ")
+      f.puts('#conn = AsyncRecord::Connection::MySQL.new(:host => "127.0.0.1", :port => 3306, :user => "root", :database => "database")')
+      f.puts('#conn.connect')
+      f.puts('#AsyncRecord::Base.set_connection(conn)')
+    end
+    
+    # Rakefile
+    File.open("#{app_name}/Rakefile", "w") do |f|
+      f.puts("require 'fastr/test/tasks'")
+    end
+    
+    # Test Helper
+    File.open("#{app_name}/test/test_helper.rb", "w") do |f|
+      f.puts("require 'rubygems'")
+      f.puts("require 'fastr/test'")
+      f.puts("require 'test/unit'")
+      f.puts("require 'fastr'")
+      f.puts("\nload(File.expand_path('../app/config/init.rb', File.expand_path(File.dirname(__FILE__))))")
+    end
+    
     puts "#{app_name} initialized!"
   end
   
@@ -87,7 +110,20 @@ elsif command == 'generate' and ARGV.length > 2
     
     puts "Creating controller: #{path}"
     File.open(path, "w") do |f|
-      f.puts("class #{name.capitalize}Controller < Fastr::Controller")
+      f.puts("class #{name.camelcase}Controller < Fastr::Controller")
+      f.puts("end")
+      f.close
+    end
+    
+    path = "test/unit/test_#{name}_controller.rb"
+    puts "Creating test class: #{path}"
+    File.open(path, "w") do |f|
+      f.puts("require 'test_helper'\n\n")
+      f.puts("class #{name.camelcase}ControllerTest < Test::Unit::TestCase")
+      f.puts("\tinclude Fastr::Test::Controller\n\n")
+      f.puts("\tdef test_something")
+      f.puts("\t\tassert(true)")
+      f.puts("\tend")
       f.puts("end")
       f.close
     end

data/lib/fastr.rb

@@ -12,4 +12,9 @@ module Fastr
   autoload :Deferrable,       "#{ROOT}/fastr/deferrable"
   autoload :Settings,         "#{ROOT}/fastr/settings"
   autoload :Plugin,           "#{ROOT}/fastr/plugin"
+  autoload :Cookie,           "#{ROOT}/fastr/cookie"
+  autoload :Filter,           "#{ROOT}/fastr/filter"
+  autoload :Async,            "#{ROOT}/fastr/async"
+  autoload :HTTP,             "#{ROOT}/fastr/http"
+  autoload :Dispatch,         "#{ROOT}/fastr/dispatch"
 end

data/lib/fastr/application.rb

@@ -2,15 +2,34 @@ require 'logger'
 require 'cgi'
 require 'mime/types'
 
-module Fastr  
+module Fastr
+  # This class represents a fastr application.
+  # @author Chris Moos
   class Application
     include Fastr::Log
-    
+    include Fastr::Dispatch
+
+    # The file that contains application settings.
     SETTINGS_FILE = "app/config/settings.rb"
+
+    # The file that is evaluated when fastr finishes booting.
     INIT_FILE = "app/config/init.rb"
-    PUBLIC_FOLDER = "public"
 
-    attr_accessor :router, :app_path, :settings, :plugins
+    # The router for this application.
+    # @return [Fastr::Router]
+    attr_accessor :router
+
+    # The full path the application's path.
+    # @return [String]
+    attr_accessor :app_path
+
+    # The settings for this application.
+    # @return [Fastr::Settings]
+    attr_accessor :settings
+
+    # The list of plugins enabled for this application.
+    # @return [Array]
+    attr_accessor :plugins
 
     # These are resources we are watching to change.
     # They will be reloaded upon change.
@@ -28,45 +47,7 @@ module Fastr
       @booting = true
       boot
     end
-    
-    # Convenience wrapper for do_dispatch
-    # This is the heart of the server, called indirectly by a Rack aware server. 
-    def dispatch(env)
-      return [500, {}, "Server Not Ready"] if @booting
-      
-      begin 
-        new_env = plugin_before_dispatch(env)
-        plugin_after_dispatch(new_env, do_dispatch(new_env))
-      rescue Exception => e
-        bt = e.backtrace.join("\n")
-        [500, {}, "Exception: #{e}\n\n#{bt}"]
-      end
-    end
-    
-    def plugin_before_dispatch(env)
-      new_env = env
-      
-      self.plugins.each do |plugin|
-        if plugin.respond_to? :before_dispatch
-          new_env = plugin.send(:before_dispatch, self, env)
-        end
-      end
-      
-      new_env
-    end
-    
-    def plugin_after_dispatch(env, response)
-      new_response = response
-      
-      self.plugins.each do |plugin|
-        if plugin.respond_to? :after_dispatch
-          new_response = plugin.send(:after_dispatch, self, env, response)
-        end
-      end
-      
-      new_response
-    end
-    
+
     def plugin_after_boot
       self.plugins.each do |plugin|
         if plugin.respond_to? :after_boot
@@ -74,97 +55,9 @@ module Fastr
         end
       end
     end
-    
-    # Route, instantiate controller, return response from controller's action.
-    def do_dispatch(env)      
-      path = env['PATH_INFO']
-      
-      # Try to serve a public file
-      ret = dispatch_public(env, path)
-      return ret if not ret.nil?
-      
-      log.debug "Checking for routes that match: #{path}"
-      route = router.match(env)
 
-      if route.has_key? :ok
-        vars = route[:ok]        
-        controller = vars[:controller]
-        action = vars[:action]
-        
-        raise Fastr::Error.new("Controller and action not present in route") if controller.nil? or action.nil?
-        
-        
-        klass = "#{controller.capitalize}Controller"
-        
-        log.info "Routing to controller: #{klass}, action: #{action}"
-        
-        obj = Module.const_get(klass).new
-        setup_controller(obj, env)
-        
-        code, hdrs, body = *obj.send(action)
-
-        # Merge headers with anything specified in the controller
-        hdrs.merge!(obj.headers)
-        
-        [code, hdrs, body]
-      else
-        [404, {"Content-Type" => "text/plain"}, "404 Not Found: #{path}"]
-      end
-    end
-    
     private
-    
-    def dispatch_public(env, path)
-      path = "#{self.app_path}/#{PUBLIC_FOLDER}/#{path[1..(path.length - 1)]}"
-      if not File.directory? path and File.exists? path
-        f = File.open(path)
-        hdrs = {}
-        
-        type = MIME::Types.type_for(File.basename(path))
-        
-        hdrs["Content-Type"] = type.to_s if not type.nil?
-        
-        return [200, hdrs, f.read]
-      else
-        return nil
-      end
-    end
-    
-    def setup_controller(controller, env)
-      controller.env = env
-      controller.params = {}
-      controller.headers = {}
 
-      CGI::parse(env['QUERY_STRING']).each do |k,v|
-        if v.length == 1
-          controller.params[k] = v[0]
-        else
-          controller.params[k] = v
-        end
-      end
-      
-      controller.cookies = get_cookies(env)
-      
-      
-      controller.app = self
-    end
-    
-    def get_cookies(env)
-      if env.has_key? "HTTP_COOKIE"
-        cookies = env['HTTP_COOKIE'].split(';')
-        c = {}
-        cookies.each do |cookie|
-          info = cookie.strip.split("=")
-          if info.length == 2
-            c[info[0].strip] = info[1].strip 
-          end
-        end
-        c
-      else
-        {}
-      end
-    end
-    
     #
     # This is used to initialize the application.
     # It runs in a thread because startup depends on EventMachine running
@@ -172,22 +65,21 @@ module Fastr
     def boot
       Thread.new do
         sleep 1 until EM.reactor_running?
-        
+
         begin
           log.info "Loading application..."
-          
+          app_init
           load_settings
           Fastr::Plugin.load(self)
           load_app_classes
           setup_router
           setup_watcher
-          
+
           log.info "Application loaded successfully."
-          
+
           @booting = false
-          
+
           plugin_after_boot
-          app_init
         rescue Exception => e
           log.error "#{e}"
           puts e.backtrace
@@ -196,62 +88,77 @@ module Fastr
         end
       end
     end
-    
+
     # Initializes the router and loads the routes.
     def setup_router
       self.router = Fastr::Router.new(self)
       self.router.load
     end
-  
+
     # Loads all application classes. Called on startup.
     def load_app_classes
       @@load_paths.each do |name, path|
         log.debug "Loading #{name} classes..."
-        
+
         Dir["#{self.app_path}/#{path}"].each do |f|
           log.debug "Loading: #{f}"
           load(f)
         end
       end
     end
-    
+
     def app_init
       return if not File.exists? INIT_FILE
-      
+
       init_file = File.open(INIT_FILE)
       self.instance_eval(init_file.read)
     end
-    
+
     def load_settings
-      return if not File.exists? SETTINGS_FILE
-      
-      config_file = File.open(SETTINGS_FILE)
+      settings_file = "#{self.app_path}/#{SETTINGS_FILE}"
+      return if not File.exists? settings_file
+
+      config_file = File.open(settings_file)
       self.instance_eval(config_file.read)
     end
-    
+
     # Watch for any file changes in the load paths.
     def setup_watcher
       this = self
-      Handler.send(:define_method, :app) do 
+      Handler.send(:define_method, :app) do
         this
       end
-      
+
       @@load_paths.each do |name, path|
         Dir["#{self.app_path}/#{path}"].each do |f|
           EM.watch_file(f, Handler)
         end
       end
     end
-    
+
     def config
       return self.settings
     end
-    
+
     module Handler
       def file_modified
         app.log.debug "Reloading file: #{path}"
+        reload(path)
+      end
+
+      def reload(path)
+        filename = File.basename(path)
+
+        # Is it a controller?
+        match = /^((\w+)_controller).rb$/.match(filename)
+        reload_controller(match[1]) if not match.nil?
+
         load(path)
       end
+
+      def reload_controller(name)
+        Object.send(:remove_const, name.camelcase.to_sym)
+      end
     end
   end
-end
+end