gin 1.0.4 → 1.1.0

data/lib/gin/cache.rb

@@ -0,0 +1,65 @@
+##
+# Gin::Cache is a bare-bones in-memory data store.
+# It's thread-safe and built for read-bound data.
+# Reads are lock-less when no writes are queued.
+
+class Gin::Cache
+
+  def initialize
+    @data = {}
+    @lock = Gin::RWLock.new
+  end
+
+
+  ##
+  # Set the write timeout when waiting for reader thread locks.
+  # Defaults to 0.05 sec. See Gin::RWLock for more details.
+
+  def write_timeout= sec
+    @lock.write_timeout = sec
+  end
+
+
+  ##
+  # Get the write timeout when waiting for reader thread locks.
+  # See Gin::RWLock for more details.
+
+  def write_timeout
+    @lock.write_timeout
+  end
+
+
+  ##
+  # Get a value from the cache with the given key.
+
+  def [] key
+    @lock.read_sync{ @data[key] }
+  end
+
+
+  ##
+  # Set a value in the cache with the given key and value.
+
+  def []= key, val
+    @lock.write_sync{ @data[key] = val }
+  end
+
+
+  ##
+  # Check if the current key exists in the cache.
+
+  def has_key? key
+    @lock.read_sync{ @data.has_key? key }
+  end
+
+
+  ##
+  # Returns a cache value if it exists. Otherwise, locks and assigns the
+  # provided value or block result. Blocks get executed with the write lock
+  # to prevent redundant operations.
+
+  def cache key, value=nil, &block
+    return self[key] if self.has_key?(key)
+    @lock.write_sync{ @data[key] = block_given? ? yield() : value }
+  end
+end

data/lib/gin/config.rb

@@ -1,50 +1,206 @@
 require 'yaml'
 
+##
+# Environment-specific config files loading mechanism.
+#
+#   # config_dir/memcache.yml
+#   default: &default
+#     host: http://memcache.example.com
+#     connections: 5
+#
+#   development: &dev
+#     host: localhost:123321
+#     connections: 1
+#
+#   test: *dev
+#
+#   staging:
+#     host: http://stage-memcache.example.com
+#
+#   production: *default
+#
+#
+#   # config.rb
+#   config = Gin::Config.new 'staging', :dir => 'config/dir'
+#
+#   config['memcache.host']
+#   #=> "http://stage-memcache.example.com"
+#
+#   config['memcache.connections']
+#   #=> 5
+#
+# Config files get loaded on demand. They may also be reloaded on demand
+# by setting the :ttl option to expire values. Values are only expired
+# for configs with a source file whose mtime value differs from the one
+# it had at its previous load time.
+#
+#   # 5 minute expiration
+#   config = Gin::Config.new 'staging', :ttl => 300
+
 class Gin::Config
 
-  attr_reader :dir
+  attr_accessor :dir, :logger, :ttl, :environment
+
+  ##
+  # Create a new config instance for the given environment name.
+  # The environment dictates which part of the config files gets exposed.
 
-  def initialize environment, dir=nil
-    self.dir = dir
+  def initialize environment, opts={}
     @environment = environment
-    @meta = class << self; self; end
-    @data = {}
-    self.load!
+    @logger      = opts[:logger] || $stdout
+    @ttl         = opts[:ttl]    || false
+    @dir         = opts[:dir]    || "./config"
+
+    @data       = {}
+    @load_times = {}
+    @mtimes     = {}
+
+    @lock = Gin::RWLock.new(opts[:write_timeout])
   end
 
 
-  def dir= val
-    @dir = File.join(val, "*.yml") if val
+  ##
+  # Get or set the write timeout when waiting for reader thread locks.
+  # Defaults to 0.05 sec. See Gin::RWLock for more details.
+
+  def write_timeout sec=nil
+    @lock.write_timeout = sec if sec
+    @lock.write_timeout
   end
 
 
+  ##
+  # Force-load all the config files in the config directory.
+
   def load!
     return unless @dir
-    Dir[@dir].each do |filepath|
-      c = YAML.load_file(filepath)
-      c = (c['default'] || {}).merge (c[@environment] || {})
+    Dir[File.join(@dir, "*.yml")].each do |filepath|
+      load_config filepath
+    end
+    self
+  end
+
 
+  ##
+  # Load the given config name, or filename.
+  #   # Loads @dir/my_config.yml
+  #   config.load_config 'my_config'
+  #   config['my_config']
+  #   #=> data from file
+  #
+  #   # Loads the given file if it exists.
+  #   config.load_config 'path/to/my_config.yml'
+  #   config['my_config']
+  #   #=> data from file
+
+  def load_config name
+    name = name.to_s
+
+    if File.file?(name)
+      filepath = name
       name = File.basename(filepath, ".yml")
-      set name, c
+    else
+      filepath = filepath_for(name)
     end
-    self
+
+    raise Gin::MissingConfig, "No config file at #{filepath}" unless
+      File.file?(filepath)
+
+    @lock.write_sync do
+      @load_times[name] = Time.now
+
+      mtime = File.mtime(filepath)
+      return if mtime == @mtimes[name]
+
+      @mtimes[name] = mtime
+
+      c = YAML.load_file(filepath)
+      c = (c['default'] || {}).merge(c[@environment] || {})
+
+      @data[name] = c
+    end
+
+  rescue Psych::SyntaxError
+    @logger.write "[ERROR] Could not parse config `#{filepath}' as YAML"
+    return nil
   end
 
 
+  ##
+  # Sets a new config name and value. Configs set in this manner do not
+  # qualify for reloading as they don't have a source file.
+
   def set name, data
-    @data[name] = data
-    define_method(name){ @data[name] } unless respond_to? name
+    @lock.write_sync{ @data[name] = data }
   end
 
 
+  ##
+  # Get a config value from its name.
+  # Setting safe to true will return nil instead of raising errors.
+  # Reloads the config if reloading is enabled and value expired.
+
+  def get name, safe=false
+    return @lock.read_sync{ @data[name] } if
+      current?(name) || safe && !File.file?(filepath_for(name))
+
+    load_config(name) || @lock.read_sync{ @data[name] }
+  end
+
+
+  ##
+  # Checks if the given config is outdated.
+
+  def current? name
+    @lock.read_sync do
+      @ttl == false && @data.has_key?(name) ||
+        !@load_times[name] && @data.has_key?(name) ||
+        @load_times[name] && Time.now - @load_times[name] <= @ttl
+    end
+  end
+
+
+  ##
+  # Checks if a config exists in memory or on disk, by its name.
+  #   # If foo config isn't loaded, looks for file under @dir/foo.yml
+  #   config.has? 'foo'
+  #   #=> true
+
   def has? name
-    @data.has_key?(name) && respond_to?(name)
+    @lock.read_sync{ @data.has_key?(name) } || File.file?(filepath_for(name))
+  end
+
+
+  ##
+  # Non-raising config lookup. The following query the same value:
+  #   # Raises an error if the 'user' key is missing.
+  #   config.get('remote_shell')['user']['name']
+  #
+  #   # Doesn't raise an error if a key is missing.
+  #   # Doesn't support configs with '.' in the key names.
+  #   config['remote_shell.user.name']
+
+  def [] key
+    chain = key.to_s.split(".")
+    name = chain.shift
+    curr = get(name, true)
+    return unless curr
+
+    chain.each do |k|
+      return unless Array === curr || Hash === curr
+      val = curr[k]
+      val = curr[k.to_i] if val.nil? && k.to_i.to_s == k
+      curr = val
+    end
+
+    curr
   end
 
 
   private
 
-  def define_method name, &block
-    @meta.send :define_method, name, &block
+
+  def filepath_for name
+    File.join(@dir, "#{name}.yml")
   end
 end

data/lib/gin/constants.rb

@@ -38,10 +38,14 @@ module Gin::Constants
   GIN_RELOADED    = 'gin.reloaded'.freeze
   GIN_ERRORS      = 'gin.errors'.freeze
   GIN_TIMESTAMP   = 'gin.timestamp'.freeze
+  GIN_TEMPLATES   = 'gin.templates'.freeze
 
   # Environment names
   ENV_DEV   = "development".freeze
   ENV_TEST  = "test".freeze
   ENV_STAGE = "staging".freeze
   ENV_PROD  = "production".freeze
+
+  # Other
+  SESSION_SECRET = "%064x" % Kernel.rand(2**256-1)
 end

data/lib/gin/controller.rb

@@ -1,3 +1,52 @@
+#  Gin controllers follow only a few rules:
+#
+#  * ALL instance methods are actions (put your helper methods in a module or
+#    parent class not mounted to the app).
+#  * Filters are defined by blocks passed to special class methods.
+#  * Controller-level error handlers are defined by blocks passed to the 'error'
+#    class method.
+#
+#  Gin controller actions are any instance method defined on the controller
+#  class. The HTTP response body takes the value of the method's return value.
+#
+#  If the instance method takes arguments, matching params will be assigned to
+#  them. A required argument with a missing param triggers a Gin::BadRequest
+#  error, resulting in a 400 response.
+#
+#    class UserController < Gin::Controller
+#      # Get params id and email
+#      def show id, email=nil
+#        ...
+#      end
+#    end
+#
+#  Gin actions also support Ruby 2.0 keyed arguments, which are more flexible
+#  for assigning default values when dealing with missing params.
+#
+#    class UserController < Gin::Controller
+#      def show(id, email: nil, full: false)
+#        ...
+#      end
+#    end
+#
+#  Views are rendered by calling the 'view' method from a controller instance.
+#  Views don't halt the action but return a String of the rendered view.
+#  If a layout was set, the rendered view will include the layout.
+#
+#    class UserController < Gin::Controller
+#      layout :user
+#
+#      def show id
+#        # Renders <app.views_dir>/show_user.* with the layout <app.layouts_dir>/user.*
+#        view :show_user
+#      end
+#
+#      def tos
+#        # Renders <app.views_dir>/tos.* with no layout
+#        view :tos, :layout => false
+#      end
+#    end
+
 class Gin::Controller
   extend  GinClass
   include Gin::Constants
@@ -17,6 +66,20 @@ class Gin::Controller
   end
 
 
+  def self.inherited subclass
+    subclass.setup
+    super
+  end
+
+
+  def self.setup   # :nodoc:
+    @layout = nil
+    @ctrl_name = Gin.underscore(self.to_s).gsub(/_?controller_?/,'')
+  end
+
+  setup
+
+
   ##
   # Array of action names for this controller.
 
@@ -31,8 +94,9 @@ class Gin::Controller
   #   MyApp::FooController.controller_name
   #   #=> "my_app/foo"
 
-  def self.controller_name
-    @ctrl_name ||= Gin.underscore(self.to_s).gsub(/_?controller_?/,'')
+  def self.controller_name new_name=nil
+    @ctrl_name = new_name if new_name
+    @ctrl_name
   end
 
 
@@ -41,10 +105,10 @@ class Gin::Controller
   # Default value is "text/html". This attribute is inherited.
 
   def self.content_type new_type=nil
-    return @content_type = new_type if new_type
-    return @content_type if @content_type
-    self.superclass.respond_to?(:content_type) ?
-      self.superclass.content_type.dup : "text/html"
+    @content_type = new_type if new_type
+    return @content_type if defined?(@content_type) && @content_type
+    self.superclass.respond_to?(:content_type) &&
+      self.superclass.content_type || "text/html"
   end
 
 
@@ -59,9 +123,36 @@ class Gin::Controller
   end
 
 
-  class_proxy :controller_name
+  ##
+  # Get or set a layout for a given controller.
+  # Value can be a symbol or filepath.
+  # Layout file is expected to be in the Gin::App.layout_dir directory
+  # Defaults to the parent class layout, or Gin::App.layout.
+
+  def self.layout name=nil
+    @layout = name if name
+    return @layout if @layout
+    return self.superclass.layout if self.superclass.respond_to?(:layout)
+  end
+
+
+  class_rproxy :controller_name, :actions
+
+  # The Gin::App instance used by the controller. The App instance is meant for
+  # read-only use. Writes are not thread-safe and at your own risk.
+  attr_reader :app
+
+  # Gin::Request instance representing the HTTP request.
+  attr_reader :request
 
-  attr_reader :app, :request, :response, :action, :env
+  # Gin::Response instance representing the HTTP response.
+  attr_reader :response
+
+  # The action that the HTTP request resolved to, based on the App's router.
+  attr_reader :action
+
+  # The Rack env hash.
+  attr_reader :env
 
 
   def initialize app, env
@@ -99,6 +190,14 @@ class Gin::Controller
   end
 
 
+  ##
+  # Accessor for @app.config.
+
+  def config
+    @app.config
+  end
+
+
   ##
   # Get the normalized mime-type matching the given input.
 
@@ -109,6 +208,9 @@ class Gin::Controller
 
   ##
   # Get or set the HTTP response Content-Type header.
+  #   content_type :json
+  #   content_type 'application/json;charset=us-ascii'
+  #   content_type :json, charset: 'us-ascii'
 
   def content_type type=nil, params={}
     return @response[CNT_TYPE] unless type
@@ -296,6 +398,7 @@ class Gin::Controller
   #   path_to :show, :id => 123
   #   #=> "/foo/123"
   #
+  #   # Default named route
   #   path_to :show_foo, :id => 123
   #   #=> "/foo/123"
 
@@ -516,6 +619,102 @@ class Gin::Controller
   end
 
 
+  ##
+  # Value of the layout to use for rendering.
+  # See also Gin::Controller.layout and Gin::App.layout.
+
+  def layout
+    self.class.layout || @app.layout
+  end
+
+
+  ##
+  # Returns the path to where the template is expected to be.
+  #   template_path :foo
+  #   #=> "<views_dir>/foo"
+  #
+  #   template_path "sub/foo"
+  #   #=> "<views_dir>/sub/foo"
+  #
+  #   template_path "sub/foo", :layout
+  #   #=> "<layouts_dir>/sub/foo"
+  #
+  #   template_path "/other/foo"
+  #   #=> "<root_dir>/other/foo"
+
+  def template_path template, is_layout=false
+    dir = if template[0] == ?/
+            @app.root_dir
+          elsif is_layout
+            @app.layouts_dir
+          else
+            @app.views_dir
+          end
+
+    path = File.join(dir, template.to_s)
+    path.gsub!('*', controller_name)
+    File.expand_path(path)
+  end
+
+
+  ##
+  # Render a template with the given view template.
+  # Options supported:
+  # :locals:: Hash - local variables used in template
+  # :layout:: Symbol/String - a custom layout to use
+  # :scope:: Object - The scope in which to render the template: default self
+  # :content_type:: Symbol/String - Content-Type header to set
+  # :engine:: String - Tilt rendering engine to use
+  # :layout_engine:: String - Tilt layout rendering engine to use
+  #
+  # The template argument may be a String or a Symbol. By default the
+  # template location will be looked for under Gin::App.views_dir, but
+  # the directory may be specified as any directory under Gin::App.root_dir
+  # by using the '/' prefix:
+  #
+  #   view 'foo/template'
+  #   #=> Renders file "<views_dir>/foo/template"
+  #
+  #   view '/foo/template'
+  #   #=> Renders file "<root_dir>/foo/template"
+  #
+  #   # Render without layout
+  #   view 'foo/template', layout: false
+
+  def view template, opts={}, &block
+    content_type(opts.delete(:content_type)) if opts[:content_type]
+
+    scope  = opts[:scope]  || self
+    locals = opts[:locals] || {}
+
+    template   = template_path(template)
+    v_template = @app.template_for template, opts[:engine]
+    raise Gin::TemplateMissing, "No such template `#{template}'" unless v_template
+
+    if opts[:layout] != false
+      r_layout   = template_path((opts[:layout] || layout), true)
+      r_template = @app.template_for r_layout, opts[:layout_engine] if r_layout
+    end
+
+    if !@response[CNT_TYPE]
+      mime_type = v_template.class.default_mime_type ||
+        r_template && r_template.class.default_mime_type
+      content_type(mime_type) if mime_type
+    end
+
+    @env[GIN_TEMPLATES] ||= []
+
+    if r_template
+      @env[GIN_TEMPLATES] << r_template.file << v_template.file
+      r_template.render(scope, locals){
+        v_template.render(scope, locals, &block) }
+    else
+      @env[GIN_TEMPLATES] << v_template.file
+      v_template.render(scope, locals, &block)
+    end
+  end
+
+
   ##
   # Taken from Sinatra.
   #
@@ -567,12 +766,13 @@ class Gin::Controller
   def html_error_page err, code=nil
     if @app.development?
       fulltrace = err.backtrace.join("\n")
-      fulltrace = "<pre>#{fulltrace}</pre>"
+      fulltrace = "<pre>#{h(fulltrace)}</pre>"
 
       apptrace  = Gin.app_trace(err.backtrace).join("\n")
-      apptrace  = "<pre>#{apptrace}</pre>" unless apptrace.empty?
+      apptrace  = "<pre>#{h(apptrace)}</pre>" unless apptrace.empty?
 
-      DEV_ERROR_HTML % [err.class, err.class, err.message, apptrace, fulltrace]
+      DEV_ERROR_HTML %
+        [h(err.class), h(err.class), h(err.message), apptrace, fulltrace]
 
     else
       code ||= status
@@ -588,6 +788,14 @@ class Gin::Controller
   end
 
 
+  ##
+  # HTML-escape the given String.
+
+  def h obj
+    CGI.escapeHTML obj.to_s
+  end
+
+
   private