ruil 0.0.1 → 0.1.0

data/README.rdoc

@@ -1,9 +1,10 @@
 = ruil
 
-Basic tools for build web appplications on top of rack
+Basic tools for build web applications on top of rack
 
 == Install
 
+    !!!sh
     $ gem install ruil
 
 == Usage
@@ -14,15 +15,18 @@ Basic tools for build web appplications on top of rack
 
 First download the code from the repository:
 
-    $ git clone git@github.com:danielhz/ruil.git
+    !!!sh
+    $ git clone git://github.com/danielhz/ruil.git
 
 This project uses jeweler to build the gem, so you can use this commands:
 
+    !!!sh
     $ rake build            # to build the gem
     $ rake install          # to build and install the gem in one step
 
 Also, if you want test the gem you can use the spec task:
 
+    !!!sh
     $ rake spec
 
 This project uses rcov so you can check the coverage opening the HTML

data/VERSION

@@ -1 +1 @@
-0.0.1
+0.1.0

data/lib/ruil/html_responder.rb

@@ -0,0 +1,88 @@
+require 'rubygems'
+require 'tenjin'
+require 'uagent_rack'
+
+module Ruil
+
+  # {Ruil::HTMLResponder} objects implement receive requests and respond
+  # with Rack::Response where bodies are HTML documents and the media
+  # type is "text/html" or "application/xhtml+xml".
+  class HTMLResponder
+
+    # Initialize a new template object using the template file name
+    # prefix. Also a layout could be defined with the template.
+    #
+    # Template files name must follow the pattern "foo.key.tenjin.html",
+    # where foo is the name of the template, tipically related with
+    # the resource, key is the key that indentify different
+    # templates for the same resource and html is the indentifier
+    # for the template media type.
+    #
+    # We use distinct templates for the same resource to send
+    # different representations of the resource depending the client
+    # user agent and preferences.
+    def initialize(file_prefix, layout = nil)
+      @templates = []
+      Dir[file_prefix + ".*.*.*"].select{ |f| ! (/\.cache$/ === f) }.each do |file|
+        a = File.basename(file).split('.')
+        # Mode
+        mode = a[1].to_sym
+        # Media type
+        media_type = case a[3]
+                     when "html"
+                       "text/html"
+                     when "xhtml"
+                       "application/xhtml+xml"
+                     else
+                       next
+                     end
+        # Add template
+        engine = case a[2]
+                 when "tenjin"
+                   require "tenjin"
+                   Tenjin::Engine.new({:layout => layout})
+                 else
+                   raise "Template engine unknown #{a[2]}"
+                 end
+        @templates << {
+          :mode       => mode.to_sym,
+          :engine     => engine,
+          :file       => file,
+          :media_type => media_type,
+          :suffix     => a[3].to_sym
+        }
+      end
+      @uagent_parser = UAgent::Parser.new
+    end
+
+    # Creates a resource representation using a template for the
+    # data contained in the request.
+    #
+    # @param [Ruil::Request] request the request to respond.
+    # @return [Rack::Response] the response.
+    def call(request)
+      path_info = request.rack_request.path_info
+      suffix = path_info.sub(/^.*\./, '')
+      suffix = 'html' if suffix == path_info
+      template = @templates.select{
+        |t| t[:suffix] == suffix.to_sym and t[:mode] == mode(request)
+      }.map.first
+
+      unless template.nil?
+        body = template[:engine].render(template[:file], request.generated_data)
+        Rack::Response.new(body, 200, {'Content-Type' => template[:media_type]})
+      else
+        return false
+      end
+    end
+
+    def mode(request)
+      r = request.rack_request
+      r.session[:mode] = r.params['mode'].to_sym unless r.params['mode'].nil?
+      r.session[:mode] = @uagent_parser.call(request.rack_request.env) if r.session[:mode].nil?
+      r.session[:mode]
+    end
+
+  end
+
+end

data/lib/ruil/json_responder.rb

@@ -0,0 +1,35 @@
+require 'rubygems'
+require 'json'
+require 'singleton'
+
+module Ruil
+
+  # The {Ruil::JSONResponder} singleton object recive a request and gets
+  # a Rack::Response serializing the {Ruil::Request#generated_data} in the 
+  # JSON format as the response body.
+  #
+  # === Usage
+  #
+  #    request = Ruil::Request.new(Rack::Request.new({}))
+  #    request.generated_data['some'] = ['data'] 
+  #    responder = JSONResponder.instance
+  #    response  = responder.call(request)
+  #    response.status                    # => 200
+  #    response.header['Content-Type']    # => "application/json"
+  #    response.body                      # => ["{'some':['data']}"]
+  #
+  class JSONResponder
+    include Singleton
+
+    # Responds a request.
+    # @param request[Ruil::Request] the request
+    # @return [Rack::Response] the response
+    def call(request)
+      return false unless /\.js$/ === request.rack_request.path_info
+      body = [request.generated_data.to_json]
+      Rack::Response.new(body, 200, {'Content-Type' => 'application/json'})
+    end
+
+  end
+
+end

data/lib/ruil/mongo_resource.rb

@@ -0,0 +1,128 @@
+require 'rubygems'
+require 'mongo'
+
+require 'ruil/resource'
+
+module Ruil
+
+  # {Ruil::MongoResource} objects get a CRUD interface to resources stored in
+  # colletions of a Mongo database.
+  #
+  #    db = Mongo::Connection.new.db('mydb')
+  #    resource = Ruil::MongoResource.new(db, 'mycollection')
+  #
+  # You could generate a CRUD for all the collections in a database.
+  #
+  #    db.collection_names.each do |collection_name|
+  #      Ruil::MongoResource.new(db, 'mycollection')
+  #    end
+  #
+  # You could access to initialized resources using the {Ruil::MongoResource.[]}
+  # method.
+  #
+  #    resource = Ruil::MongoResource[:my_collection_name]
+  class MongoResource
+
+    @@resources = {}
+
+    # The items per page when listing resources.
+    # @return [Fixnum] the items per page
+    attr_accessor :page_size
+
+    # A procedure to map items when listing resources.
+    # @return [Proc] a mapping when listing resources
+    attr_accessor :map_list_item
+
+    # A procedure to map a resource to show.
+    # @return [Proc] a mapping when showing resources.
+    attr_accessor :map_show_item
+
+    # The directory where templates are.
+    # @return [String] the templates directory
+    attr_accessor :templates_dir
+
+    # The actions associated with the mongo resource.
+    # This attribute allows you to redefine the behavior of actions
+    # for any {Ruil::MongoResource}.
+    # @return [Hash<Symbol><Ruil::MongoResource] the actions.
+    attr_accessor :actions
+
+    # Creates a new {Ruil::MongoResource}.
+    #
+    # @param [Mongo::DB] db
+    #   the resource database
+    #
+    # @param [String] collection_name
+    #   the name of the collection that stores the resources
+    def initialize(db, collection_name)
+      @db              = db
+      @collection_name = collection_name
+      @collection      = @db[@collection_name]
+      @page_size       = 10
+      @map_list_item   = Proc.new { |item| item }
+      @map_show_item   = Proc.new { |item| item }
+      @templates_dir   = File.join("dynamic", "templates")
+      @actions         = {}
+      @@resources[@collection_name.to_sym] = self
+      yield self if block_given?
+      # Procedure to load resource templates
+      @load_templates  = Proc.new do |resource, action|
+        Dir[File.join(@templates_dir, @collection_name, "#{action}.*.*.*")].each do |t|
+          if /\.(html|xhtml)$/ === t
+            resource << Ruil::Template.new(t)
+          end
+        end
+      end
+      # List resources
+      @actions[:list] = Ruil::Resource.new("GET", "/#{@collection_name}/list") do |r|
+        r.content_generator = Proc.new do |e|
+          e[:page] = ( e[:request].params['page'] || 0 )
+          items = @collection.find().skip(e[:page]).limit(@page_size)
+          { :items => items.map { |item| @map_list_item.call(item) } }
+        end
+        @load_templates.call r, 'list'
+      end
+      # Show a resource
+      @actions[:show] = Ruil::Resource.new("GET", "/#{@collection_name}/:_id") do |r|
+        r.content_generator = Proc.new do |e|
+          id = BSON::ObjectId.from_string(e[:path_info_params][:_id])
+          item = @collection.find(:_id => id).first
+          { :item => @map_show_item.call(item) }
+        end
+        @load_templates.call r, 'show'
+      end
+      # Create a new resource
+      @actions[:post] = Ruil::Resource.new("POST", "/#{@collection_name}") do |r|
+        # TODO
+      end
+      # Update a resource
+      @actions[:put] = Ruil::Resource.new("PUT", "/#{@collection_name}/:_id") do |r|
+        # TODO
+      end
+      # Delete a resource
+      @actions[:delete] = Ruil::Resource.new("DELETE", "/#{@collection_name}/:_id") do |r|
+        # TODO'
+      end
+    end
+
+    # Get the resource names.
+    #
+    # @return [Array<Symbol>] the resource names.
+    def self.resource_names
+      @@resources.keys
+    end
+
+    # Get the resource for a collection.
+    #
+    # @param [Symbo] collection_name
+    #   the collection name
+    #
+    # @return [Ruil::MongoResource]
+    #   the resource for the collection
+    def self.[](collection_name)
+      @@resources[collection_name]
+    end
+
+  end
+
+end

data/lib/ruil/path_info_parser.rb

@@ -0,0 +1,50 @@
+module Ruil
+
+  # Each instance of {Ruil::PathInfoParser} matches path info strings
+  # with a pattern and return variables matching it if
+  # the pattern is matched. Else, it returns false.
+  #
+  # === Usage
+  #
+  #    parser = PathInfoParser.new('/foo/:type/:id')
+  #    parser === '/foo/bar/1'      # => {:type => 'bar', :id => '1'}
+  #    parser === '/foo/bar/3.js'   # => {:type => 'bar', :id => '3'}
+  #    parser === '/foo'            # => false
+  #    parser === '/bar'            # => false
+  #
+  class PathInfoParser
+
+    # Initialize a new parser
+    # 
+    # @param pattern[String] the pattern to match
+    def initialize(pattern)
+      @pattern = pattern.split('/').map do |s|
+       ( s[0,1] == ':' ) ? eval(s) : s
+      end
+      @pattern = ['', ''] if @pattern.empty?
+    end
+
+    # Match a path info.
+    #
+    # @param path_info[String] the path info to match.
+    # @return [Hash,false] a hash with variables matched with the
+    #   pattern or false if the path info doesn't match the pattern.
+    def ===(path_info)
+      s = path_info.split('/')
+      s = ['', ''] if s.empty?
+      s.last.gsub!(/\..*$/, '')
+      return false unless s.size == @pattern.size
+      matchs = {}
+      s.each_index do |i|
+        if Symbol === @pattern[i]
+          matchs[@pattern[i]] = s[i]
+        else
+          return false unless @pattern[i] == s[i]
+        end
+      end
+      matchs
+    end
+
+  end
+
+end

data/lib/ruil/redirector.rb

@@ -0,0 +1,33 @@
+module Ruil
+
+  # {Ruil::Redirector} instances redirects requests to other resources.
+  #
+  # === Usage
+  #
+  # Tipically it could be used when access is unauthorized.
+  #
+  #     rack_request = Rack::Request.new({})
+  #     rack_request.path_info = '/unauthorized_url'
+  #     ruil_request = Ruil::Request.new(rack_request)
+  #     response = Ruil::Redirector.new('/login').call(ruil_request)
+  #     response.status              # => 302
+  #     response.header['Location']  # => "/login?redirected_from=/unauthorized_url"
+  #
+  class Redirector
+
+    # Initialize a {Ruil::Redirector}.
+    def initialize(redirect_to)
+      @redirect_to = redirect_to
+    end
+
+    # Responds a request with a redirection.
+    # @param request[Ruil::Request] the request.
+    # @return [Rack::Response] the response.
+    def call(request)
+      headers = {'Location'=> @redirect_to + "?redirected_from=" + request.rack_request.path_info}
+      Rack::Response.new([], 302, headers)
+    end
+
+  end
+
+end

data/lib/ruil/register.rb

@@ -0,0 +1,45 @@
+module Ruil
+
+  # Ruil::Register module allow us to register resources. When a Ruil::Resource
+  # object is created it is automatically registered using the +register+ method.
+  # The +call+ method answer a request with the first registered resource that
+  # match the request. Matches are checked using the order of resource registrations.
+  module Register
+
+    @@resources = {
+      'GET'    => [],
+      'POST'   => [],
+      'PUT'    => [],
+      'DELETE' => []
+    }
+
+    # Register a resource.
+    def self.<<(resource)
+      resource.request_methods.each do |request_method|
+        @@resources[request_method] << resource
+      end
+    end
+
+    # Answer a request with the response of the matched resource for that request.
+    #
+    # @param request_or_env[Rack::Request, Hash] the request.
+    # @return [Rack::Response] the response to the request.
+    def self.call(request_or_env)
+      case request_or_env
+      when Rack::Request
+        request = request_or_env
+      when Hash
+        request = Rack::Request.new(request_or_env)
+      else
+        raise "Invalid request: #{request_or_env.inspect}"
+      end
+      @@resources[request.request_method].each do |resource|
+        response = resource.call(request)
+        return response.finish if response
+      end
+      raise "No resource matching the request"
+    end
+
+  end
+
+end

data/lib/ruil/request.rb

@@ -0,0 +1,49 @@
+module Ruil
+
+  # Instances of {Ruil::Request} encapsulate Rack::Requests
+  # and extend it with data generated when processing the request.
+  #
+  # === Usage
+  #
+  #     rack_request = Rack::Request.new
+  #     ruil_request = Ruil::Request.new(rack_request)
+  #     ruil_request.rack_request              # => rack_request
+  #     ruil_request.generated_data            # => {}
+  #     ruil_request.generated_data[:x] = "y"
+  #     ruil_request.generated_data            # => {:x => "y"}
+  #     ruil_request.html_mode                 # => :desktop
+  #
+  class Request
+
+    # The generated data.
+    # @return [Hash]
+    attr_accessor :generated_data
+
+    # The selected responder.
+    # @return [Object]
+    attr_accessor :responder
+
+    # The rack request
+    # @return [Rack::Request]
+    attr_accessor :rack_request
+
+    # Initialize a new Ruil::Request unsing a Rack::Request.
+    # @param request[Rack::Request] the request to be encapsulated.
+    def initialize(request)
+      @rack_request   = request
+      @generated_data = {}
+    end
+
+    # Return the mode for the view (:desktop, :mobile,...).
+    # @return [Symbol]
+    def html_mode
+      if @html_mode.nil?
+        # TODO: Get it from session
+        # TODO: Get it from device parser
+        @html_mode = :desktop
+      end
+      @html_mode
+    end
+  end
+
+end

data/lib/ruil/resource.rb

@@ -1,82 +1,123 @@
 require 'rubygems'
+require 'rack'
+require 'ruil/path_info_parser'
+require 'ruil/register'
 
 module Ruil
 
+  # {Ruil::Resource} objects answer requests (see the method {#call}) with
+  # an array following the Rack interface. If the request not match the
+  # resource, +false+ is returned.
+  # Also, a resource includes a set of templates to delegate the action of
+  # rendering a resource.
+  #
+  # === Use example
+  #
+  # The next example shows how to create and use a resource.
+  #
+  #    resource = Resource.new('GET', "/index")
+  #    puts resource.call(request)        # => the response to the request
+  #
+  # Every resource is automatically regitered into {Ruil::Register} when it
+  # is created. Thus, you may use {Ruil::Register.call} to call resource
+  # instead using {#call} directly.
+  #
+  #    resource = Resource.new('GET', "/index")
+  #    puts Ruil::Register.call(request)  # => the response using the register
+  #
+  # === Templates
+  #
+  # The interface of templates consists in the +new+, +key+ and +call+ methods.
+  # Classes that satisfy that interface are {Ruil::Template} and
+  # {Ruil::JSONTemplate}. Every resource have a {Ruil::JSONTemplate} as a
+  # default template.
+  #
+  #    resource = Resource.new('GET', "/index") do |res|
+  #      Dir['path_to_templates/*'].each do |file|
+  #        res << Ruil::Template.new(file)
+  #      end
+  #    end
+  #
+  # === Path patterns
+  #
+  # Path patterns are strings that are matched with the request path info.
+  # Patterns may include named parameters accessibles via the hash that
+  # the {Ruil::PathInfoParser#===} method returns after a match check.
+  #   
+  #    resource = Ruil::Resource.new(:get, "/users/:user_id/pictures/:picture_id")
+  #    env['PATH_INFO'] = "/users/23/pictures/56"
+  #    resource.call(env)    # matches are { :user_id => "232, :picture_id => "56" }
+  #    env['PATH_INFO'] = "/users/23/pictures"
+  #    resource.call(env)    # match is false
   class Resource
-    
-    # Initialize a new resource.
-    #
-    # Parameters:
-    # - templates: a hash with procedures or objects with method call(options),
-    #     used to generate the resource.
-    # - user_agent_parser: is an object with a method call that analize the
-    #     request to get the key for the template to use.
-    def initialize(user_agent_parser, &block)
-      @templates         = {}
-      @user_agent_parser = user_agent_parser
-      yield self
-    end
-
-    def add_template(key, template)
-      @templates[key] = template
-    end
-
-    # The regular expression for the url of this resource.
-    def path_pattern
-      '/'
-    end
 
-    # The regular expression for the url of this resource.
-    def template_pattern
-      '*.*.html'
-    end
-
-    # Authorize the access to this resource.
-    def authorize(env)
-      true
-    end
-
-    # Build options to render the resource.
-    def options(env)
-      {
-        :env => env,
-        :template_key => template_key(env)
-      }
-    end
-
-    # Selects the template key
-    def template_key(env)
-      @user_agent_parser.call(env) || @templates.keys.sort.first
-    end
+    # Methods that a resource responds.
+    # 
+    # @return [Array<String>]
+    attr_reader :request_methods
 
-    # Selectes a template to render the resource
-    def template(env)
-      @templates[template_key(env)]
+    # Initialize a new resource.
+    #
+    # @param request_methods [String, Array<String>]
+    #   indentify the request methods that this resource responds. Valid
+    #   methods are: <tt>"GET"</tt>, <tt>"POST"</tt>, <tt>"PUT"</tt> and
+    #   <tt>"DELETE"</tt>.
+    #
+    # @param path_pattern [String]
+    #   defines a pattern to match paths.
+    #   Patterns may include named parameters accessibles via the hash that
+    #   the {Ruil::PathInfoParser#===} method returns after a match check.
+    #
+    # @param authorizer [lambda(Ruil::Request)]
+    #   A procedure that checks if the user is allowed to access the resource.
+    #
+    # @param responders [Array<Responder>] an array with responders.
+    def initialize(request_methods, path_pattern, authorizer = nil, responders = [], &block)
+      # Set request methods
+      @request_methods =
+        case request_methods
+        when String
+          [request_methods]
+        when Array
+          request_methods
+        else
+          raise "Invalid value for request_methods: #{request_methods.inspect}"
+        end
+      # Set the path info parser
+      @path_info_parser = Ruil::PathInfoParser.new(path_pattern)
+      # Set the authorizer method
+      @authorizer = authorizer
+      # Set responders
+      @responders = [Ruil::JSONResponder.instance] + responders
+      # Block that generates data
+      @block = Proc.new { |request| yield request } if block_given?
+      # Register
+      Ruil::Register << self
     end
 
-    # Call the resource
-    def call(env)
-      if authorize(env)
-        render_html(env)
+    # Respond a request
+    #
+    # @param request [Rack::Request] a request to the resource.
+    # @return [Rack::Response] a response for the request.
+    def call(rack_request)
+      path_info = rack_request.path_info
+      path_info_params = ( @path_info_parser === path_info )
+      return false unless path_info_params
+      unless @authorizer.nil?
+        return @autorizer.unauthorized unless @authorizer.authorize(request)
+      end
+      request = Ruil::Request.new(rack_request)
+      request.generated_data[:path_info_params] = path_info_params
+      @block.call(request) unless @block.nil?
+      if request.responder.nil?
+        @responders.each do |responder|
+          response = responder.call(request)
+          return response if response
+        end
       else
-        unauthorized(env)
+        return request.responder.call(request)
       end
-    end
-
-    # Action if the resource is unauthorized
-    def unauthorized(env)
-      redirect("/unauthorized")      
-    end
-
-    # Render
-    def render_html(env)
-      content = template(env).call(options(env))
-      [200, {"Content-Type" => "text/html"}, [content]]
-    end
-
-    # Redirect
-    def redirect(url)
-      [ 302, {"Content-Type" => "text/html", 'Location'=> url }, [] ]
+      raise "Responder not found for #{request.inspect}"
     end
 
   end