gin 0.0.0 → 1.0.0

data/.autotest

@@ -2,12 +2,12 @@
 
 require 'autotest/restart'
 
-# Autotest.add_hook :initialize do |at|
+Autotest.add_hook :initialize do |at|
 #   at.extra_files << "../some/external/dependency.rb"
 #
 #   at.libs << ":../some/external"
 #
-#   at.add_exception 'vendor'
+  at.add_exception 'test/app'
 #
 #   at.add_mapping(/dependency.rb/) do |f, _|
 #     at.files_matching(/test_.*rb$/)
@@ -16,7 +16,7 @@ require 'autotest/restart'
 #   %w(TestA TestB).each do |klass|
 #     at.extra_class_map[klass] = "test/test_misc.rb"
 #   end
-# end
+end
 
 # Autotest.add_hook :run_command do |at|
 #   system "rake build"

data/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+pkg/
+TODO.rdoc
+*.swo
+*.swp
+.*.swo
+.*.swp

data/History.rdoc

@@ -1,6 +1,3 @@
-=== 0.0.0 / 2013-02-13
-
-* 1 major enhancement
-
-  * Birthday!
-
+=== 1.0.0 / 2013-03-07
+ 
+* Birthday!

data/Manifest.txt

@@ -1,8 +1,42 @@
 .autotest
+.gitignore
 History.rdoc
 Manifest.txt
 README.rdoc
 Rakefile
-bin/gin
 lib/gin.rb
-test/gin_test.rb
+lib/gin/app.rb
+lib/gin/config.rb
+lib/gin/controller.rb
+lib/gin/core_ext/cgi.rb
+lib/gin/core_ext/gin_class.rb
+lib/gin/errorable.rb
+lib/gin/filterable.rb
+lib/gin/reloadable.rb
+lib/gin/request.rb
+lib/gin/response.rb
+lib/gin/router.rb
+lib/gin/stream.rb
+public/400.html
+public/404.html
+public/500.html
+public/error.html
+public/favicon.ico
+public/gin.css
+public/gin_sm.png
+test/app/app_foo.rb
+test/app/controllers/app_controller.rb
+test/app/controllers/foo_controller.rb
+test/mock_config/backend.yml
+test/mock_config/memcache.yml
+test/mock_config/not_a_config.txt
+test/test_app.rb
+test/test_config.rb
+test/test_controller.rb
+test/test_errorable.rb
+test/test_filterable.rb
+test/test_gin.rb
+test/test_helper.rb
+test/test_request.rb
+test/test_response.rb
+test/test_router.rb

data/README.rdoc

@@ -1,29 +1,39 @@
-= gin
+= Gin
 
-* https://github.com/yaks/gin
+* http://yaks.me/gin
 
-== DESCRIPTION:
+== Description
 
-Something fun coming soon.
+Gin is a small web framework built from the redistillation of
+Sinatra and Rails idioms. Specifically, it uses much of Sinatra's
+request flow and HTTP helper methods with dedicated controller classes
+that support Rails-like filters.
 
-== REQUIREMENTS:
+== Hello World
 
-* rack
+  # config.ru
+  require 'gin'
 
-== INSTALL:
+  class HelloWorldCtrl < Gin::Controller
+    def index; "Hello World!"; end
+  end
 
-* gem install gin
+  class MyApp < Gin::App
+    mount HelloWorldCtrl, "/"
+  end
 
-== DEVELOPERS:
+  run MyApp.new
 
-After checking out the source, run:
+== Requirements
 
-  $ rake newb
+* rack
+* rack-protection
 
-This task will install any missing dependencies, run the tests/specs,
-and generate the RDoc.
+== Install
+
+* gem install gin
 
-== LICENSE:
+== License
 
 (The MIT License)
 

data/Rakefile

@@ -3,21 +3,14 @@
 require 'rubygems'
 require 'hoe'
 
-# Hoe.plugin :compiler
-# Hoe.plugin :gem_prelude_sucks
-# Hoe.plugin :inline
-# Hoe.plugin :isolate
-# Hoe.plugin :racc
-# Hoe.plugin :rcov
-# Hoe.plugin :rubyforge
-
 Hoe.spec 'gin' do
   developer('Jeremie Castagna', 'yaksnrainbows@gmail.com')
   self.readme_file      = "README.rdoc"
   self.history_file     = "History.rdoc"
   self.extra_rdoc_files = FileList['*.rdoc']
 
-  self.extra_deps << ['rack', '>=1.5.2']
+  self.extra_deps << ['rack',            '~>1.1']
+  self.extra_deps << ['rack-protection', '~>1.0']
 end
 
 # vim: syntax=ruby

data/lib/gin.rb

@@ -1,3 +1,124 @@
+require 'logger'
+
+require 'rack'
+require 'rack-protection'
+
+
 class Gin
-  VERSION = '0.0.0'
+  VERSION = '1.0.0'
+
+  LIB_DIR    = File.expand_path("..", __FILE__)            #:nodoc:
+  PUBLIC_DIR = File.expand_path("../../public/", __FILE__) #:nodoc:
+
+  class Error < StandardError; end
+
+  class BadRequest < ArgumentError
+    def http_status; 400; end
+  end
+
+  class NotFound < NameError
+    def http_status; 404; end
+  end
+
+
+  ##
+  # Change string to underscored version.
+
+  def self.underscore str
+    str = str.dup
+    str.gsub!('::', '/')
+    str.gsub!(/([A-Z]+?)([A-Z][a-z])/, '\1_\2')
+    str.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+    str.downcase
+  end
+
+
+  ##
+  # Create a URI query from a Hash.
+
+  def self.build_query value, prefix=nil
+    case value
+    when Array
+      raise ArgumentError, "no prefix given" if prefix.nil?
+      value.map { |v|
+        build_query(v, "#{prefix}[]")
+      }.join("&")
+
+    when Hash
+      value.map { |k, v|
+        build_query(v, prefix ?
+          "#{prefix}[#{CGI.escape(k.to_s)}]" : CGI.escape(k.to_s))
+      }.join("&")
+
+    when String, Integer, Float, TrueClass, FalseClass
+      raise ArgumentError, "value must be a Hash" if prefix.nil?
+      "#{prefix}=#{CGI.escape(value.to_s)}"
+
+    else
+      prefix
+    end
+  end
+
+
+  ##
+  # Returns the full path to the file given based on the load paths.
+
+  def self.find_loadpath file
+    name = file.dup
+    name << ".rb" unless name[-3..-1] == ".rb"
+
+    return name if name[0] == ?/ && File.file?(name)
+
+    filepath = nil
+
+    dir = $:.find do |path|
+      filepath = File.expand_path(name, path)
+      File.file? filepath
+    end
+
+    dir && filepath
+  end
+
+
+  ##
+  # Get a namespaced constant.
+
+  def self.const_find str_or_ary, parent=Object
+    const = nil
+    names = Array === str_or_ary ? str_or_ary : str_or_ary.split("::")
+    names.each do |name|
+      const  = parent.const_get(name)
+      parent = const
+    end
+
+    const
+  end
+
+
+  APP_START_MATCH = %r{/gin/app\.rb:\d+:in `dispatch'} #:nodoc:
+
+  ##
+  # Get the application backtrace only.
+  # Removes gem and Gin paths from the trace.
+
+  def self.app_trace trace
+    trace = trace.dup
+    trace.pop until trace.last.nil? || trace.last =~ APP_START_MATCH
+    trace.pop while trace.last && trace.last.start_with?(LIB_DIR)
+    trace
+  end
+
+
+  require 'gin/core_ext/cgi'
+  require 'gin/core_ext/gin_class'
+
+  require 'gin/app'
+  require 'gin/router'
+  require 'gin/config'
+  require 'gin/request'
+  require 'gin/response'
+  require 'gin/stream'
+  require 'gin/errorable'
+  require 'gin/filterable'
+  require 'gin/controller'
 end

data/lib/gin/app.rb

@@ -0,0 +1,595 @@
+##
+# The Gin::App is the entry point for Rack, for all Gin Applications.
+# This class MUST be subclassed and initialized.
+#   # my_app.rb
+#   class MyApp < Gin::App
+#     require 'my_controller'
+#     mount MyController, "/"
+#   end
+#
+#   # config.ru
+#   require 'my_app'
+#   run MyApp.new
+
+class Gin::App
+  extend GinClass
+
+  class RouterError < Gin::Error; end
+
+  RACK_KEYS = { #:nodoc:
+    :stack       => 'gin.stack'.freeze,
+    :path_params => 'gin.path_query_hash'.freeze,
+    :reloaded    => 'gin.reloaded'.freeze,
+    :errors      => 'gin.errors'.freeze
+  }.freeze
+
+
+  CALLERS_TO_IGNORE = [ # :nodoc:
+    /\/gin(\/(.*?))?\.rb$/,             # all gin code
+    /lib\/tilt.*\.rb$/,                 # all tilt code
+    /^\(.*\)$/,                         # generated code
+    /rubygems\/custom_require\.rb$/,    # rubygems require hacks
+    /active_support/,                   # active_support require hacks
+    /bundler(\/runtime)?\.rb/,          # bundler require hacks
+    /<internal:/,                       # internal in ruby >= 1.9.2
+    /src\/kernel\/bootstrap\/[A-Z]/     # maglev kernel files
+  ]
+
+
+  def self.inherited subclass   #:nodoc:
+    caller_line = caller.find{|line| !CALLERS_TO_IGNORE.any?{|m| line =~ m} }
+    filepath = File.expand_path(caller_line.split(/:\d+:in `/).first)
+    dir      = File.dirname(filepath)
+    subclass.root_dir dir
+    subclass.instance_variable_set("@source_file", filepath)
+    subclass.instance_variable_set("@source_class", subclass.to_s)
+  end
+
+
+  ##
+  # Create a new intance of the app and call it.
+
+  def self.call env
+    @instance ||= self.new
+    @instance.call env
+  end
+
+
+  ##
+  # Enable or disable auto-app reloading.
+  # On by default in development mode.
+  #
+  # In order for an app to be reloadable, the libs and controllers must be
+  # required from the Gin::App class context, or use MyApp.require("lib").
+  #
+  # Reloading is not supported for applications defined in the config.ru file.
+
+  def self.autoreload val=nil
+    @autoreload = val unless val.nil?
+
+    if @autoreload.nil?
+      @autoreload = File.extname(source_file) != ".ru" && development?
+    end
+
+    if @autoreload && (!defined?(Gin::Reloadable) || !include?(Gin::Reloadable))
+      require 'gin/reloadable'
+      include Gin::Reloadable
+    end
+
+    @autoreload
+  end
+
+
+  ##
+  # Mount a Gin::Controller into the App and specify a base path. If controller
+  # mounts at root, use "/" as the base path.
+  #   mount UserController, "/user" do
+  #     get  :index,  "/"
+  #     get  :show,   "/:id"
+  #     post :create, "/"
+  #     get  :stats        # mounts to "/stats" by default
+  #     any  :logged_in    # any HTTP verb will trigger this action
+  #   end
+  #
+  # Controllers with non-mounted actions will throw a warning at boot time.
+  #
+  # Restful routes are automatically mounted when no block is given:
+  #
+  #   mount UserController
+  #   # restfully mounted to /user
+  #   # non-canonical actions are mounted to /user/<action_name>
+  #
+  # Mount blocks also support routing whatever actions are left to their restful
+  # defaults:
+  #
+  #   mount UserController do
+  #     get :foo, "/"
+  #     defaults
+  #   end
+  #
+  # All Gin::Controller methods are considered actions and will be mounted in
+  # restful mode. For helper methods, include a module into your controller.
+
+  def self.mount ctrl, base_path=nil, &block
+    router.add ctrl, base_path, &block
+  end
+
+
+  ##
+  # Returns the source file of the current app.
+
+  def self.source_file
+    @source_file
+  end
+
+
+  def self.namespace #:nodoc:
+    # Parent namespace of the App class. Used for reloading purposes.
+    Gin.const_find(@source_class.split("::")[0..-2]) if @source_class
+  end
+
+
+  def self.source_class #:nodoc:
+    # Lookup the class from its name. Used for reloading purposes.
+    Gin.const_find(@source_class) if @source_class
+  end
+
+
+  ##
+  # Get or set the root directory of the application.
+  # Defaults to the app file's directory.
+
+  def self.root_dir dir=nil
+    @root_dir = dir if dir
+    @root_dir
+  end
+
+
+  ##
+  # Get or set the path to the config directory.
+  # Defaults to root_dir + "config"
+  #
+  # Configs are expected to be YAML files following this pattern:
+  #   default: &default
+  #     key: value
+  #
+  #   development: *default
+  #     other_key: value
+  #
+  #   production: *default
+  #     ...
+  #
+  # Configs will be named according to the filename, and only the config for
+  # the current environment will be accessible.
+
+  def self.config_dir dir=nil
+    @config_dir = dir if dir
+    @config_dir ||= File.join(root_dir, "config")
+  end
+
+
+  ##
+  # Access the config for your application, loaded from the config_dir.
+  #   # config/memcache.yml
+  #   default: &default
+  #     host: example.com
+  #     connections: 1
+  #   development: *default
+  #     host: localhost
+  #
+  #   # access from App class or instance
+  #   config.memcache['host']
+
+  def self.config
+    @config ||= Gin::Config.new environment, config_dir
+  end
+
+
+  ##
+  # Loads all configs from the config_dir.
+
+  def self.load_config
+    return unless File.directory?(config_dir)
+    config.dir = config_dir
+    config.load!
+  end
+
+
+  ##
+  # Get or set the path to the public directory.
+  # Defaults to root_dir + "public"
+
+  def self.public_dir dir=nil
+    @public_dir = dir if dir
+    @public_dir ||= File.join(root_dir, "public")
+  end
+
+
+  ##
+  # Get or set the CDN asset host (and path).
+  # If block is given, evaluates the block on every read.
+
+  def self.asset_host host=nil, &block
+    @asset_host = host  if host
+    @asset_host = block if block_given?
+    host = @asset_host.respond_to?(:call) ? @asset_host.call : @asset_host
+  end
+
+
+  ##
+  # Returns the asset host for a given asset name. This is useful when assigning
+  # a block for the asset_host. The asset_name argument is passed to the block.
+
+  def self.asset_host_for asset_name
+     @asset_host.respond_to?(:call) ? @asset_host.call(asset_name) : @asset_host
+  end
+
+
+  ##
+  # Returns the first 8 bytes of the asset file's md5.
+  # File path is assumed relative to the public_dir.
+
+  def self.asset_version path
+    path = File.expand_path(File.join(public_dir, path))
+    return unless File.file?(path)
+
+    @asset_versions       ||= {}
+    @asset_versions[path] ||= md5(path)
+  end
+
+
+  MD5 = RUBY_PLATFORM =~ /darwin/ ? 'md5 -q' : 'md5sum' #:nodoc:
+
+  def self.md5 path #:nodoc:
+    `#{MD5} #{path}`[0...8]
+  end
+
+
+  ##
+  # Define a Gin::Controller as a catch-all error rendering controller.
+  # This can be a dedicated controller, or a parent controller
+  # such as AppController. Defaults to Gin::Controller.
+  #
+  # The error delegate should handle the following errors
+  # for creating custom pages for Gin errors:
+  #   Gin::NotFound, Gin::BadRequest, ::Exception
+
+  def self.error_delegate ctrl=nil
+    @error_delegate = ctrl if ctrl
+    @error_delegate ||= Gin::Controller
+  end
+
+
+  ##
+  # Router instance that handles mapping Rack-env -> Controller#action.
+
+  def self.router
+    @router ||= Gin::Router.new
+  end
+
+
+  ##
+  # Lookup or register a mime type in Rack's mime registry.
+
+  def self.mime_type type, value=nil
+    return type if type.nil? || type.to_s.include?('/')
+    type = ".#{type}" unless type.to_s[0] == ?.
+    return Rack::Mime.mime_type(type, nil) unless value
+    Rack::Mime::MIME_TYPES[type] = value
+  end
+
+
+  ##
+  # Provides all mime types matching type, including deprecated types:
+  #   mime_types :html # => ['text/html']
+  #   mime_types :js   # => ['application/javascript', 'text/javascript']
+
+  def self.mime_types type
+    type = mime_type type
+    type =~ /^application\/(xml|javascript)$/ ? [type, "text/#$1"] : [type]
+  end
+
+
+  ##
+  # Add middleware internally to the app.
+  # Middleware statuses and Exceptions will NOT be
+  # handled by the error_delegate.
+
+  def self.use middleware, *args, &block
+    ary = [middleware, *args]
+    ary << block if block_given?
+    self.middleware << ary
+  end
+
+
+  ##
+  # List of internal app middleware.
+
+  def self.middleware
+    @middleware ||= []
+  end
+
+
+  ##
+  # Use rack sessions or not. Supports assigning
+  # hash for options. Defaults to true.
+
+  def self.sessions opts=nil
+    @session = opts unless opts.nil?
+    @session = true if @session.nil?
+    @session
+  end
+
+
+  ##
+  # Get or set the session secret String.
+  # Defaults to a new random value on boot.
+
+  def self.session_secret val=nil
+    @session_secret = val if val
+    @session_secret ||= "%064x" % Kernel.rand(2**256-1)
+  end
+
+
+  ##
+  # Use rack-protection or not. Supports assigning
+  # hash for options. Defaults to true.
+
+  def self.protection opts=nil
+    @protection = opts unless opts.nil?
+    @protection = true if @protection.nil?
+    @protection
+  end
+
+
+  ##
+  # Get or set the current environment name,
+  # by default ENV ['RACK_ENV'], or "development".
+
+  def self.environment env=nil
+    @environment = env if env
+    @environment ||= ENV['RACK_ENV'] || "development"
+  end
+
+
+  ##
+  # Check if running in development mode.
+
+  def self.development?
+    self.environment == "development"
+  end
+
+
+  ##
+  # Check if running in test mode.
+
+  def self.test?
+    self.environment == "test"
+  end
+
+
+  ##
+  # Check if running in staging mode.
+
+  def self.staging?
+    self.environment == "staging"
+  end
+
+
+  ##
+  # Check if running in production mode.
+
+  def self.production?
+    self.environment == "production"
+  end
+
+
+  class_proxy :protection, :sessions, :session_secret, :middleware, :autoreload
+  class_proxy :error_delegate, :router
+  class_proxy :root_dir, :public_dir
+  class_proxy :mime_type, :asset_host_for, :asset_host, :asset_version
+  class_proxy :environment, :development?, :test?, :staging?, :production?
+  class_proxy :load_config, :config, :config_dir
+
+  # Application logger. Defaults to log to $stdout.
+  attr_accessor :logger
+
+  # App to fallback on if Gin::App is used as middleware and no route is found.
+  attr_reader :rack_app
+
+  # Internal Rack stack.
+  attr_reader :stack
+
+
+  ##
+  # Create a new Rack-mountable Gin::App instance, with an optional
+  # rack_app and logger.
+
+  def initialize rack_app=nil, logger=nil
+    load_config
+
+    if !rack_app.respond_to?(:call) && rack_app.respond_to?(:log) && logger.nil?
+      @rack_app = nil
+      @logger   = rack_app
+    else
+      @rack_app = rack_app
+      @logger   = Logger.new $stdout
+    end
+
+    validate_all_controllers!
+
+    @app   = self
+    @stack = build_app Rack::Builder.new
+  end
+
+
+  ##
+  # Used for auto reloading the whole app in development mode.
+  # Will only reload if Gin::App.autoreload is set to true.
+  #
+  # If you use this in production, you're gonna have a bad time.
+
+  def reload!
+    return unless autoreload
+    self.class.erase! [self.class.source_file],
+                      [self.class.name.split("::").last],
+                      self.class.namespace
+
+    self.class.erase_dependencies!
+    Object.send(:require, self.class.source_file)
+    @app = self.class.source_class.new @rack_app, @logger
+  end
+
+
+  ##
+  # Default Rack call method.
+
+  def call env
+    if filename = static?(env)
+      return error_delegate.exec(self, env){ send_file filename }
+    end
+
+    if autoreload && !env[RACK_KEYS[:reloaded]]
+      env[RACK_KEYS[:reloaded]] = true
+      reload!
+      @app.call env
+
+    elsif env[RACK_KEYS[:stack]]
+      env.delete RACK_KEYS[:stack]
+      @app.call! env
+
+    else
+      env[RACK_KEYS[:stack]] = true
+      @stack.call env
+    end
+  end
+
+
+  ##
+  # Call App instance without internal middleware or reloading.
+
+  def call! env
+    ctrl, action, env[RACK_KEYS[:path_params]] =
+      router.resources_for env['REQUEST_METHOD'], env['PATH_INFO']
+
+    dispatch env, ctrl, action
+  end
+
+
+  STATIC_PATH_CLEANER = %r{\.+/|/\.+}  #:nodoc:
+
+  ##
+  # Check if the request is for a static file.
+
+  def static? env
+    %w{GET HEAD}.include?(env['REQUEST_METHOD']) && asset(env['PATH_INFO'])
+  end
+
+
+  ##
+  # Check if an asset exists.
+  # Returns the full path to the asset if found, otherwise nil.
+
+  def asset path
+    path = path.gsub STATIC_PATH_CLEANER, ""
+
+    filepath = File.expand_path(File.join(public_dir, path))
+    return filepath if File.file? filepath
+
+    filepath = File.expand_path(File.join(Gin::PUBLIC_DIR, path))
+    return filepath if File.file? filepath
+  end
+
+
+  ##
+  # Dispatch the Rack env to the given controller and action.
+
+  def dispatch env, ctrl, action
+    raise Gin::NotFound,
+      "No route exists for: #{env['REQUEST_METHOD']} #{env['PATH_INFO']}" unless
+      ctrl && action
+
+    ctrl.new(self, env).call_action action
+
+  rescue Gin::NotFound => err
+    @rack_app ? @rack_app.call(env) : handle_error(err, env)
+
+  rescue ::Exception => err
+    handle_error(err, env)
+  end
+
+
+  ##
+  # Handle error with error_delegate if available, otherwise re-raise.
+
+  def handle_error err, env
+    delegate = error_delegate
+
+    begin
+      trace = Gin.app_trace(Array(err.backtrace)).join("\n")
+      logger.error("#{err.class.name}: #{err.message}\n#{trace}")
+      delegate.exec(self, env){ handle_error(err) }
+
+    rescue ::Exception => err
+      delegate = Gin::Controller and retry unless delegate == Gin::Controller
+      raise
+    end
+  end
+
+
+  private
+
+
+  def build_app builder
+    setup_sessions   builder
+    setup_protection builder
+    middleware.each do |args|
+      block = args.pop if Proc === args.last
+      builder.use(*args, &block)
+    end
+
+    builder.run self
+    builder.to_app
+  end
+
+
+  def setup_sessions builder
+    return unless sessions
+    options = {}
+    options[:secret] = session_secret if session_secret
+    options.merge! sessions.to_hash if sessions.respond_to? :to_hash
+    builder.use Rack::Session::Cookie, options
+  end
+
+
+  def setup_protection builder
+    return unless protection
+    options = Hash === protection ? protection.dup : {}
+    options[:except] = Array options[:except]
+    options[:except] += [:session_hijacking, :remote_token] unless sessions
+    options[:reaction] ||= :drop_session
+    builder.use Rack::Protection, options
+  end
+
+
+  ##
+  # Make sure all controller actions have a route, or raise a RouterError.
+
+  def validate_all_controllers!
+    actions = {}
+
+    router.each_route do |route, ctrl, action|
+      (actions[ctrl] ||= []) << action
+    end
+
+    actions.each do |ctrl, actions|
+      not_mounted   = ctrl.actions - actions
+      raise RouterError, "#{ctrl}##{not_mounted[0]} has no route." unless
+        not_mounted.empty?
+
+      extra_mounted = actions - ctrl.actions
+      raise RouterError, "#{ctrl}##{extra_mounted[0]} is not a method" unless
+        extra_mounted.empty?
+    end
+  end
+end