patchbay 0.0.1.pre2 → 0.0.1.pre3

data/lib/patchbay.rb

@@ -25,15 +25,42 @@ EOT
 </body></html>
 EOT
 
+private
+    # Checks if the `path_to_test` falls within the `root_path`.
+    # This can be used to test for directory-traversal attacks.
+    #
+    # == Parameters:
+    # path_to_test:: 
+    #   A path which is to be checked against the root path.
+    #
+    # root_path::
+    #   A path that `path_to_test` will be checked against.
+    #
+    # == Returns:
+    # `true` if `path_to_test` resides within `root_path`.
+    # `false` otherwise.
+    #
     def path_is_subdir_of(path_to_test, root_path)
         File.fnmatch(File.join(root_path, '**'), File.realpath(path_to_test))
     end
 
-    class Router
+    # Parses URLs and matches them to handlers.
+    class Router        
         def initialize
             @routes = []
         end
 
+        private
+
+        # Check if the given route data matches the split-up URL.
+        #
+        # == Parameters:
+        # route::
+        #   An object that responds to `handler`, `url_parts`, and `verb`.
+        #
+        # url_parts::
+        #   An array of Strings corresponding to a split URL.
+        #
         def matches?(route, url_parts)
             if route.url_parts.size != url_parts.size
                 return false
@@ -57,6 +84,20 @@ EOT
             return params
         end
 
+        public
+
+        # Find a handler matching an HTTP request.
+        #
+        # == Parameters:
+        # verb::
+        #   The HTTP verb (GET, POST etc)
+        # url::
+        #   The requested URL
+        #
+        # == Returns:
+        # A 2-element array consisting of the handler
+        # followed by a hash of parameters extracted from the URL.
+        #
         def match(verb, url)
             parts = url.gsub(/^\/+/,'').split('/')
 
@@ -72,6 +113,16 @@ EOT
             return [ nil, nil ]
         end
 
+        # Add a route matching a certain URL pattern and verb.
+        #
+        # == Parameters:
+        # verb::
+        #   The HTTP verb (GET, POST etc)
+        # route::
+        #   The URL template to match.
+        #   This may contain symbols of the form `:xxxx`;
+        #   these represent variable parameters to be extracted from the URL
+        #   when it is matched.
         def add(verb, route, handler)
             parts = route.gsub(/^\/+/,'').split('/')
             routeObj = Route.new
@@ -82,6 +133,7 @@ EOT
         end
     end
 
+protected
     def self.router
         @router ||= Router.new
         @router
@@ -91,42 +143,107 @@ EOT
         self.class.router
     end
 
+public
+    # Set up a handler for GET requests matching a given route.
+    #
+    # == Parameters:
+    # route: 
+    #   Route pattern to match (see Patchbay::Router::add)
+    # action:
+    #   Block to be executed to fulfill the request
+    #
     def self.get(route, &action)
         router.add('GET', route, action)
     end
 
+    # Set up a handler for PUT requests matching a given route.
+    #
+    # == Parameters:
+    # route: 
+    #   Route pattern to match (see Patchbay::Router::add)
+    # action:
+    #   Block to be executed to fulfill the request
+    #
     def self.put(route, &action)
         router.add('PUT', route, action)
     end
 
+    # Set up a handler for POST requests matching a given route.
+    #
+    # == Parameters:
+    # route: 
+    #   Route pattern to match (see Patchbay::Router::add)
+    # action:
+    #   Block to be executed to fulfill the request
+    #
     def self.post(route, &action)
         router.add('POST', route, action)
     end
 
+    # Set up a handler for DELETE requests matching a given route.
+    #
+    # == Parameters:
+    # route: 
+    #   Route pattern to match (see Patchbay::Router::add)
+    # action:
+    #   Block to be executed to fulfill the request
+    #
     def self.delete(route, &action)
         router.add('DELETE', route, action)
     end
 
+    # Get directory from which static files are being served
+    #
+    # == Returns:
+    # The absolute path to the directory from which static files
+    # may be served.
+    #
     def self.files_dir
         @files_dir
     end
 
+    # Set directory from which static files may be served
+    #
+    # == Parameters:
+    # new_dir:
+    #   Path (relative or absolute) from which static files may
+    #   be served.
     def self.files_dir=(new_dir)
         @files_dir = File.realpath(new_dir)
     end
 
+    # Convenience function for accessing files_dir without writing 
+    # self.class.files_dir
+    #
     def files_dir
         self.class.files_dir
     end
 
+private
+    # Get the Rack environment corresponding to the current request.
+    #
+    # == Returns:
+    # The Rack environment corresponding to the ongoing request.
+    #
     def environment
         @environment
     end
 
+    # Get the parameters parsed from the request URL.
+    #
+    # == Returns:
+    # A Hash-like object representing the passed parameters.
+    #
     def params
         @params
     end
 
+    # Handle requests that match no route, when we have a public files directory.
+    # Sets up the response appropriately for that case.
+    #
+    # == Returns:
+    # None.
+    #
     def handle_file
         url_parts = environment['PATH_INFO'].split('/')
         file_path = File.join(files_dir, url_parts)
@@ -144,11 +261,19 @@ EOT
         end
     end
 
+    # Set up the response to send a file once its absolute path is known.
+    #
     def send_file(file_path)
         mime_type = Rack::Mime.mime_type(File.extname(file_path))
         @response = [200, { "Content-Type" => mime_type }, File.new(file_path)]
     end
 
+public
+    # Rack callable interface.
+    #
+    # == Returns:
+    # A 3-element array of [status, response_headers, body].
+    #
     def call(env)
         # find a handler for this request
         handler, route_params = router.match(env['REQUEST_METHOD'], env['PATH_INFO'])
@@ -180,6 +305,16 @@ EOT
         @response
     end
 
+private
+    # Set response content and type.
+    #
+    # == Parameters:
+    # options::
+    #   A Hash of parameters.
+    #   `:error => 404`: set response error code
+    #   `:html => '<html>...</html>'`, `:json => '{...}'` etc: set response content and content type.
+    #    Content type is guessed automatically.
+    #
     def render(options={})
         if @response
             fail "can only render once per request"
@@ -197,20 +332,32 @@ EOT
         end
     end
 
+    # Set up response for 404 (route/page not found) error.
+    #
     def handle_no_route
         @response = [404, { "Content-Type" => "text/html" }, [NoRoute_Message]]
     end
 
+    # Handle exceptions occurring during route-handler execution.
+    #
     def handle_exception(e)
         @response = [500, { "Content-Type" => "text/html" }, [Exception_Message]]
         $stderr.puts e.inspect
         e.backtrace.each { |bt| $stderr.puts bt }
     end
 
+    # Set up response when permission was denied attempting to read a local file.
+    #
     def handle_forbidden
         @response = [403, { "Content-Type" => "text/html" }, [Forbidden_Message]]
     end
 
+public
+    # Start an appropriate server to run the application.
+    #
+    # == Parameters:
+    # options::
+    #   Options hash to be passed to the Rack handler.
     def run(options={})
         handler = find_rack_handler
         handler_name = handler.name.gsub(/.*::/,'')
@@ -219,6 +366,8 @@ EOT
     end
 
 private
+    # Search through installed Rack handlers for ones we like
+    #
     def find_rack_handler
         servers = %w/thin mongrel webrick/
         servers.each do |server|

metadata

@@ -1,57 +1,89 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: patchbay
-version: !ruby/object:Gem::Version
-  version: 0.0.1.pre2
+version: !ruby/object:Gem::Version 
+  hash: 3457254002499246909
   prerelease: 6
+  segments: 
+  - 0
+  - 0
+  - 1
+  - pre
+  - 3
+  version: 0.0.1.pre3
 platform: ruby
-authors:
+authors: 
 - Andrew Armenia
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-13 00:00:00.000000000Z
-dependencies:
-- !ruby/object:Gem::Dependency
+
+date: 2011-09-13 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
   name: rack
-  requirement: &14329380 !ruby/object:Gem::Requirement
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
         version: 1.3.0
   type: :runtime
-  prerelease: false
-  version_requirements: *14329380
-description: ! "Patchbay is the web framework for non-web apps. \nIt's designed for
-  simplicity, minimalism, and easy integration.\n"
+  version_requirements: *id001
+description: |
+  Patchbay is the web framework for non-web apps. 
+  It's designed for simplicity, minimalism, and easy integration.
+
 email: andrew@asquaredlabs.com
 executables: []
+
 extensions: []
+
 extra_rdoc_files: []
-files:
+
+files: 
 - lib/patchbay.rb
+has_rdoc: true
 homepage: http://rubygems.org/gems/patchbay
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>'
-    - !ruby/object:Gem::Version
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      hash: 25
+      segments: 
+      - 1
+      - 3
+      - 1
       version: 1.3.1
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 1.8.6
+rubygems_version: 1.5.2
 signing_key: 
 specification_version: 3
 summary: Embed HTTP APIs in non-web apps easily
 test_files: []
+