sidewalk 0.0.0 → 0.0.1

data/lib/sidewalk/app_uri.rb

@@ -0,0 +1,33 @@
+require 'sidewalk/controller'
+require 'sidewalk/rooted_uri'
+require 'sidewalk/request'
+
+module Sidewalk
+  # URI relative to the root of the application.
+  #
+  # For example, if your app lives at 'http://www.example.com/foo',
+  # +AppUri.new('/bar').to_s+ will reutrn 'http://www.example.com/foo/bar'.
+  #
+  # Not a real +URI+ subclass, as URI subclasses by protocol, and this
+  # might return a +URI::HTTP+ or +URI::HTTPS+ subclass.
+  module AppUri
+    # Create a URI relative to the application.
+    #
+    # If this is called, it _must_ have {Controller#call} in the call stack
+    # so that {Controller#current} works - otherwise it does not have
+    # enough information to construct the URI.
+    #
+    # @param [String] path is the path relative to the root of the
+    #   application.
+    # @param [Hash] query is a +Hash+ of key-value query data.
+    def self.new path, query = {}
+      context = Sidewalk::Controller.current
+      unless context
+        raise ScriptError.new("Only valid when called by a controller")
+      end
+      uri = context.request.root_uri
+
+      Sidewalk::RootedUri.new(uri, path, query)
+    end
+  end
+end

data/lib/sidewalk/application.rb

@@ -0,0 +1,146 @@
+require 'sidewalk/request'
+require 'sidewalk/errors'
+require 'sidewalk/redirect'
+require 'sidewalk/uri_mapper'
+
+autoload :Logger, 'logger'
+
+module Sidewalk
+  # The main Rack Application.
+  #
+  # This class is responsible for dispatch requests (based on a
+  # {Sidewalk::UriMapper}), and handling some exceptions, such as
+  # {NotFoundError}, {ForbiddenError}, or {SeeOtherRedirect}.
+  #
+  # If you want special error handling, subclass this, and reimplement
+  # {#respond_to_error}.
+  class Application
+    # The {UriMapper} class this application is using.
+    #
+    # This is constructed from the uri_map Hash argument to {#initialize}.
+    attr_reader :mapper
+
+    # The path on the server where the application code is.
+    #
+    # This should be the path containing config.ru. This will be something
+    # like +/var/www+, or +/home/fred/public_html+.
+    def self.local_root
+      @local_root ||= Dir.pwd
+    end
+
+    # Construct an instance, based on a URI-mapping Hash.
+    #
+    # @param [Hash] uri_map is a +String+ => +Class+, +Symbol+, +String+,
+    #   or +Proc+ map. See {UriMapper#initialize} for details of acceptable
+    #   keys; the short version is that they are +String+s that contain
+    #   regular expression patterns. They are not +Regexp+s.
+    def initialize uri_map
+      @mapper = Sidewalk::UriMapper.new(uri_map)
+    end
+
+    # Per-request Rack entry point.
+    #
+    # This is called for every request. It's responsible for:
+    # * Normalizing the environment parameter
+    # * Finding what should respond to the request (via {UriMapper})
+    # * Actually responding
+    # * Error handling - see {#handle_error}
+    #
+    # @param [Hash] env is an environment +Hash+, defined in the Rack
+    #   specification.
+    def call env
+      logger = ::Logger.new(env['rack.error'])
+
+      path_info = env['PATH_INFO']
+      if path_info.start_with? '/'
+        path_info[0,1] = ''
+      end
+
+      match = @mapper.map path_info
+      if match
+        env['sidewalk.urimatch'] = match
+        # Normalize reponders to Procs
+        if match.controller.is_a? Class
+          responder = lambda do |request, logger|
+            match.controller.new(request, logger).call
+          end
+        else
+          responder = match.controller
+        end
+      else
+        responder = lambda { |*args| raise NotFoundError.new }
+      end
+      request = Sidewalk::Request.new(env)
+
+      # Try and call - but it can throw special exceptions that we
+      # want to map into HTTP status codes - for example, NotFoundError
+      # is a 404
+      begin
+        responder.call(
+          request,
+          logger
+        )
+      rescue Exception => e
+        response = respond_to_error(e, request, logger)
+        raise if response.nil? || response.empty?
+        response
+      end
+    end
+
+    # Give a response for a given error.
+    #
+    # If you want custom error pages, you will want to subclass
+    # {Application}, reimplementing this method. At a minimum, you will
+    # probably want to include support for:
+    # * {HttpError}
+    # * {Redirect}
+    #
+    # This implementation has hard-coded responses in the format defined in
+    # the Rack specification.
+    #
+    # @example An implementation that uses {Controller} subclasses:
+    #   def respond_to_error(error, request, logger)
+    #     case error
+    #     when Redirect
+    #       MyRedirectController.new(error, request, logger).call
+    #     when HttpError
+    #       # ...
+    #     else
+    #       super(error, request, logger)
+    #     end
+    #   end
+    #
+    # @param [Exception] error is the error that was +raise+d
+    # @param [Request] request gives information on the request that
+    #   led to the error.
+    # @param [Logger] logger is something implementing a similiar API
+    #   to Ruby's standard +Logger+ class.
+    #
+    # @return A Rack response +Array+ - i.e.:
+    #         +[status, headers, body_parts]+ - see the specification for
+    #         details.
+    # @return +nil+ to indicate the error isn't handled - it will get
+    #         escalated to Rack and probably lead to a 500.
+    def respond_to_error(error, request, logger)
+      case error
+      when Redirect
+        [
+          error.status(request),
+          {
+            'Content-Type' => 'text/plain',
+            'Location' => error.url,
+          },
+          ["#{error.status(request)} #{error.description(request)}"]
+        ]
+      when HttpError
+        [
+          error.status(request),
+          {'Content-Type' => 'text/plain'},
+          ["#{error.status(request)} #{error.description(request)}"]
+        ]
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/sidewalk/config.rb

@@ -0,0 +1,160 @@
+require 'yaml'
+
+module Sidewalk
+  autoload :Application, 'sidewalk/application'
+
+  # Class for storing application configuration.
+  #
+  # This will:
+  # * load +config/environment.rb+ (arbitrary Ruby)
+  # * read +config/environment.yaml+ into a +Hash+
+  # * the same for +config/#{ENV['RACK_ENV']}.rb+ and +.yaml+
+  #
+  # @example environment.yaml
+  #   activerecord:
+  #     adapter: sqlite
+  #     database: data.sqlite
+  #
+  # @example Reading from {Sidewalk::Config}
+  #   ActiveRecord::Base.establish_connection(
+  #     Sidewalk::Config['activerecord']
+  #   )
+  class Config
+    # Initialize a Config object at the given path.
+    #
+    # You probably want to use the class methods instead.
+    def initialize path
+      @config = Hash.new
+      @root = path
+      [
+        'environment.rb',
+        "#{Config.environment}.rb",
+      ].each{|x| load_ruby!(x, :silent => true)}
+
+      yaml_configs = [
+        'environment.yaml',
+        "#{Config.environment}.yaml",
+      ].each{|x| load_yaml!(x, :silent => true)}
+    end
+
+    # Return a configuration value from YAML.
+    #
+    # Acts like a +Hash+. Also available as a class method.
+    #
+    # @param [String] key
+    def [] key
+      @config[key]
+    end
+
+    # Store a configuration value, as if it were in the YAML.
+    #
+    # Also available as a class method.
+    #
+    # @param [String] key
+    # @param [Object] value
+    def []= key, value
+      @config[key] = value
+    end
+
+    # Execute a Ruby file.
+    #
+    # Nothing special is done, it's just evaluated.
+    #
+    # Also available as a class method.
+    #
+    # @raise [LoadError] if +file+ does not exist, unless +:silent+ is set
+    #   to true in +options+.
+    # @param [String] file the path to the file, relative to the base
+    #   configuration path.
+    # @param [Hash] options
+    def load_ruby! file, options = {}
+      path = File.join(@root, file)
+      begin
+        load path
+      rescue LoadError
+        raise unless options[:silent]
+      end
+    end
+
+    # Read a YAML file, and merge with the current config.
+    #
+    # This is available via {#[]}
+    #
+    # Also available as a class method.
+    #
+    # @raise [LoadError] if +file+ does not exist, unless +:silent+ is set
+    #   to true in +options+.
+    # @param [String] file the path to the file, relative to the base
+    #   configuration path.
+    # @param [Hash] options
+    def load_yaml! file, options = {}
+      path = File.join(@root, file)
+      if File.exists? path
+        @config.merge! YAML.load(File.read(path))
+      else
+        unless options[:silent]
+          raise LoadError.new("unable to find #{file}")
+        end
+      end
+    end
+
+    class<<self
+      # The main instance of {Config}.
+      #
+      # You probably don't want to use this - all of the methods defined on
+      # instances are usable as class methods instead, that map onto the
+      # instance.
+      #
+      # @return [Config] an instance of {Config}
+      def instance
+        @instance ||= Config.new(self.path)
+      end
+      alias :init! :instance
+
+      # Where to look for configuration files.
+      #
+      # This defaults to +config/+ underneath the application root.
+      def path
+        @path ||= Application.local_root + '/config'
+      end
+      attr_writer :path
+
+      # What the current Rack environment is.
+      #
+      # This is an arbitrary string, but will usually be:
+      # production:: this is live, probably via Passenger
+      # development:: running on a developer's local machine, probably via
+      #   +rackup+ or +shotgun+
+      # testing:: automated tests are running.
+      #
+      # This is copied from +ENV['RACK_ENV']+, but can be overridden (see
+      # {#environment=}).
+      def environment
+        @environment ||= ENV['RACK_ENV'] || raise("Unable to determine environment. Set ENV['RACK_ENV'].")
+      end
+
+      # Override the auto-detected environment.
+      #
+      # Handy for testing - especially as RACK_ENV might not even be set.
+      def environment= foo
+        @environment = foo
+      end
+
+      def production?
+        self.environment == 'production'
+      end
+
+      def development?
+        self.environment == 'development'
+      end
+
+      def testing?
+        self.environment == 'testing'
+      end
+
+      %w{[] []= load_ruby! load_yaml!}.map(&:to_sym).each do |method|
+        define_method(method, lambda{ |*args| instance.send(method, *args)})
+      end
+    end
+  end
+end

data/lib/sidewalk/controller.rb

@@ -0,0 +1,141 @@
+require 'sidewalk/app_uri'
+
+require 'rack/utils'
+
+require 'continuation' unless RUBY_VERSION.start_with? '1.8.'
+require 'time' # Rack::Utils.set_cookie_header! on Ruby 1.8
+
+module Sidewalk
+  # Base class for page controllers.
+  #
+  # {UriMapper} maps URIs to classes or Procs. If it maps to a class, that
+  # class needs to implement {#initialize} and {#call} in the same way as
+  # this class. This class provides some added convenience.
+  #
+  # You might want to look at {ControllerMixins} for some additional
+  # optional features.
+  #
+  # To handle an URL, you will usually want to:
+  # * subclass this
+  # * implement {#response}
+  # * add your class to your application URI map.
+  class Controller
+    # Initialize a new controller instance.
+    #
+    # @param [Request] request has information on the HTTP request.
+    # @param [Logger] logger is something implement the same interface as
+    #   Ruby's +Logger+ class.
+    def initialize request, logger
+      @request, @logger = request, logger
+      @status = 200
+      @headers = {
+        'Content-Type' => 'text/html'
+      }
+    end
+
+    # The response headers.
+    #
+    # For request headers, see {#request} and {Request#headers}.
+    attr_reader :headers
+
+    # The instance of {Request} corresponding to the current HTTP request.
+    attr_reader :request
+
+    # An object implementing an interface that is compatible with +Logger+
+    attr_reader :logger
+
+    # The numeric HTTP status to return.
+    #
+    # In most cases, you won't actually want to change this - you might
+    # want to +raise+ an instance of a subclass of {HttpError} or
+    # {Redirect} instead.
+    attr_accessor :status
+
+    # Set a cookie :)
+    #
+    # Valid options are:
+    # +:expires+:: accepts a +Time+. Default is a session cookie.
+    # +:secure+:: if +true+, only send the cookie via https
+    # +:httponly+:: do not allow Flash, JavaScript etc to access the cookie
+    # +:domain+:: restrict the cookie to only be available on a given
+    #             domain, and subdomains. Default is the request domain.
+    # +:path+:: make the cookie accessible to other paths - default is the
+    #           request path.
+    #
+    # @param key [String] is the name of the cookie to set
+    # @param value [Object] is the value to set - as long as it responds to
+    #   +#to_s+, it's fine.
+    def set_cookie key, value, options = {}
+      rack_value = options.dup
+      rack_value[:value] = value.to_s
+      Rack::Utils.set_cookie_header! self.headers, key.to_s, rack_value
+    end
+
+    # What mime-type to return to the user agent.
+    #
+    # "text/html" is the default.
+    def content_type
+      headers['Content-Type']
+    end
+
+    def content_type= value
+      headers['Content-Type'] = value
+    end
+
+    # Actually respond to the request.
+    #
+    # This calls {#response}, then ties it together with {#status}
+    # and {#content_type}.
+    #
+    # @return a response in Rack's +Array+ format.
+    def call
+      cc = catch(:sidewalk_controller_current) do
+        body = self.response
+        return [status, {'Content-Type' => content_type}, [body]]
+      end
+      cc.call(self) if cc
+    end
+
+    # The body of the HTTP response to set.
+    #
+    # In most cases, this is what you'll want to implement in a subclass.
+    # You can call {#status=}, but you probably don't want to - just raise
+    # an appropriate {HttpError} subclass instead.
+    #
+    # You might be interested in {ControllerMixins::ViewTemplates}.
+    #
+    # @return [String] the body of the HTTP response
+    def response
+      raise NotImplementedError.new
+    end
+
+    # The current Controller.
+    #
+    # @return [Controller] the current Controller if {#call} is in the
+    #   stack.
+    # @return +nil+ otherwise.
+    def self.current
+      begin
+        callcc{|cc| throw(:sidewalk_controller_current, cc)}
+      rescue NameError, ArgumentError # 1.8 and 1.9 are different
+        nil
+      end
+    end
+  end
+
+  # Optional extension features to the Controller class.
+  #
+  # @example Adding +#render+ and supporting +views/+
+  #   class MyController < Sidewalk::Controller
+  #     include Sidewalk::ControllerMixins::ViewTemplates
+  #     def response
+  #       # Look for 'views/my_controller.*' - for example,
+  #       # 'views/my_controller.erb' would be rendered with ERB if
+  #       # present.
+  #       render
+  #     end
+  #   end
+  module ControllerMixins
+    # see controller_mixins/
+  end
+end

data/lib/sidewalk/controller_mixins/view_templates.rb

@@ -0,0 +1,94 @@
+require 'sidewalk/application'
+
+require 'active_support/inflector'
+
+module Sidewalk
+  module ControllerMixins
+    # Mixin for supporting view templates.
+    #
+    # This provides {#render}, which looks in views/ for a suitably named
+    # file, such as +views/hello.erb' for HelloController.
+    #
+    # See {TemplateHandlers::Base} for a list of supported formats.
+    module ViewTemplates
+      # The local path where templates are stored
+      #
+      # This will usually be the views/ subdirectory of the application
+      # root.
+      def self.view_path
+        @templates_path ||= File.join(
+          Sidewalk::Application.local_root,
+          'views'
+        )
+      end
+
+      # What handler to use for a given extension.
+      #
+      # @example ERB
+      #   erb_handler = Sidewalk::ViewTemplates.handler('erb')
+      #   erb_handler.should == Sidewalk::TemplateHandlers::ErbHandler
+      #
+      # @param [String] a filename extension.
+      # @return [Class] a {TemplateHandlers::Base} subclass.
+      def self.handler type
+        name = type.camelize + 'Handler'
+        begin
+          Sidewalk::TemplateHandlers.const_get(name)
+        rescue NameError
+          require ('Sidewalk::TemplateHandlers::' + name).underscore
+          Sidewalk::TemplateHandlers.const_get(name)
+        end
+      end
+
+      # Get a {TemplateHandlers::Base} instance for a given path.
+      #
+      # @return [TemplateHandlers::Base]
+      def self.template path
+        self.templates[path.to_s]
+      end
+
+      # A +Hash+ of all available templates.
+      #
+      # @return [Hash] a +path+ +=>+ {TemplateHandlers::Base} map.
+      def self.templates
+        return @templates if @templates
+
+        @templates = {}
+        Dir.glob(
+          self.view_path + '/**/*'
+        ).each do |path| # eg '/path/views/foo/bar.erb'
+
+          # eg '.erb'
+          ext = File.extname(path)
+          # eg 'erb'
+          type = ext[1..-1]
+          handler = self.handler(type)
+
+          # eg 'foo/bar.erb'
+          relative = path.sub(self.view_path + '/', '')
+          # convert to 'foo/bar'
+          parts = relative.split('/')
+          parts[-1] = File.basename(path, ext)
+          key = parts.join('/')
+
+          @templates[key] = handler.new(path)
+        end
+        @templates
+      end
+
+      # Return the result of rendering a view.
+      #
+      # @param [nil,String] which view to render. The default is
+      #   +foo_controller+ if called from +FooController+.
+      # @return [String] a rendered result.
+      def render view = nil
+        view ||= self.class.name.sub('Controller', '').underscore
+        template = Sidewalk::ControllerMixins::ViewTemplates.template(view)
+        if template.nil?
+          raise ScriptError.new("Unable to find a template for #{view}")
+        end
+        template.render(self)
+      end
+    end
+  end
+end

data/lib/sidewalk/errors.rb

@@ -0,0 +1,71 @@
+module Sidewalk
+  # Base class for HTTP errors.
+  #
+  # This is +raise+d by controllers.
+  class HttpError < ::RuntimeError
+    # Initialize an Error exception.
+    #
+    # If the parameters are +nil+, you will need to override {#status} and
+    # {#description} for this class to work as expected.
+    #
+    # @param [Fixnum,nil] status is the numeric status code
+    # @param [String,nil] description is a short description like 'Not
+    #   Found'
+    def initialize status, description
+      @status, @description = status, description
+    end
+
+    # The status code to return in response to the request.
+    #
+    # It takes a request to allow different responses to be given to,
+    # for example, HTTP/1.0 clients vs HTTP/1.1 clients.
+    #
+    # @param [Request] request is an object representing the current HTTP
+    #   request
+    # @return [Fixnum] a numeric HTTP status code.
+    def status request
+      @status
+    end
+
+    # The description to return in response to the request.
+    #
+    # It takes a request to allow different responses to be given to,
+    # for example, HTTP/1.0 clients vs HTTP/1.1 clients.
+    #
+    # @param [Request] request is an object representing the current HTTP
+    #   request
+    # @return [String] a text description of the code, like 'Not Found'
+    def description request
+      @description
+    end
+  end
+
+  # Request that the client provide authentication headers.
+  #
+  # This is a 401 response
+  class NotAuthorizedError < HttpError
+    def initialize
+      super 401, 'Not Authorized'
+    end
+  end
+
+  # Forbid the client from accessing a resource.
+  #
+  # Providing authentication headers will not help.
+  #
+  # This is a 403 response.
+  class ForbiddenError < HttpError
+    def initialize
+      super 403, 'Forbidden'
+    end
+  end
+
+  # Tells the client that the resource they requested does not exist.
+  #
+  # This is a 404 response.
+  class NotFoundError < HttpError
+    def initialize
+      super 404, 'Not Found'
+    end
+  end
+end