halcyon 0.4.0 → 0.5.0

data/lib/halcyon/application.rb

@@ -0,0 +1,247 @@
+module Halcyon
+  
+  # The core of Halcyon on the server side is the Halcyon::Application class
+  # which handles dispatching requests and responding with appropriate messages
+  # to the client (which can be specified).
+  # 
+  # Manages shutting down and starting up hooks, routing, dispatching, etc.
+  # Also restricts the requests to acceptable clients, defaulting to all.
+  # 
+  class Application 
+    include Exceptions
+    
+    autoload :Router, 'halcyon/application/router'
+    
+    attr_accessor :session
+    
+    DEFAULT_OPTIONS = {
+      :root => Dir.pwd,
+      :logging => {
+        :type => 'Logger',
+        :level => 'info'
+      },
+      :allow_from => :all
+    }.to_mash
+    
+    # Initializes the app:
+    # * runs startup hooks
+    # * registers shutdown hooks
+    # 
+    def initialize
+      self.logger.info "Starting up..."
+      
+      self.hooks[:startup].call(Halcyon.config) if self.hooks[:startup]
+      
+      # clean after ourselves and get prepared to start serving things
+      self.logger.debug "Starting GC."
+      GC.start
+      
+      self.logger.info "Started. PID is #{$$}"
+      
+      at_exit do
+        self.logger.info "Shutting down #{$$}."
+        self.hooks[:shutdown].call(Halcyon.config) if self.hooks[:shutdown]
+        self.logger.info "Done."
+      end
+    end
+    
+    # Sets up the request and response objects for use in the controllers and
+    # dispatches requests. Renders response data as JSON for response.
+    #   +env+ the request environment details
+    # 
+    # The internal router (which inherits from the Merb router) is sent the
+    # request to pass back the route for the dispatcher to call. This route is
+    # stored in <tt>env['halcyon.route']</tt> (as per the Rack spec).
+    # 
+    # Configs
+    #   <tt>Halcyon.config[:allow_from]</tt> #=> (default) <tt>:all</tt>
+    #     :all              => does not restrict requests from any User-Agent
+    #     :local            => restricts requests to only local requests (from
+    #                          localhost, 0.0.0.0, 127.0.0.1)
+    #     :halcyon_clients  => restricts to only Halcyon clients (identified by
+    #                          User-Agent)
+    # 
+    # Exceptions
+    #   If a request raises an exception that inherits from
+    #   <tt>Halcyon::Exceptions::Base</tt> (<tt>NotFound</tt>, etc), then the
+    #   response is sent with this information.
+    #   If a request raises any other kind of <tt>Exception</tt>, it is logged
+    #   as an error and a <tt>500 Internal Server Error</tt> is returned.
+    # 
+    # Returns [Fixnum:status, {String:header => String:value}, [String:body].to_json]
+    # 
+    def call(env)
+      timing = {:started => Time.now}
+      
+      request = Rack::Request.new(env)
+      response = Rack::Response.new
+      
+      response['Content-Type'] = "application/json"
+      response['User-Agent'] = "JSON/#{JSON::VERSION} Compatible (en-US) Halcyon::Application/#{Halcyon.version}"
+      
+      begin
+        acceptable_request!(env)
+        
+        env['halcyon.route'] = Router.route(request)
+        result = dispatch(env)
+      rescue Exceptions::Base => e
+        result = {:status => e.status, :body => e.body}
+        self.logger.info e.message
+      rescue Exception => e
+        result = {:status => 500, :body => 'Internal Server Error'}
+        self.logger.error "#{e.message}\n\t" << e.backtrace.join("\n\t")
+      end
+      
+      response.status = result[:status]
+      response.write result.to_json
+      
+      timing[:finished] = Time.now
+      timing[:total] = (((timing[:finished] - timing[:started])*1e4).round.to_f/1e4)
+      timing[:per_sec] = (((1.0/(timing[:total]))*1e2).round.to_f/1e2)
+      
+      self.logger.info "[#{response.status}] #{URI.parse(env['REQUEST_URI'] || env['PATH_INFO']).path} (#{timing[:total]}s;#{timing[:per_sec]}req/s)"
+      # self.logger << "Session ID: #{self.session.id}\n" # TODO: Implement session
+      self.logger << "Params: #{filter_params_for_log(request, env).inspect}\n\n"
+      
+      response.finish
+    end
+    
+    # Dispatches the controller and action according the routed request.
+    #   +env+ the request environment details, including "halcyon.route"
+    # 
+    # If no <tt>:controller</tt> is specified, the default <tt>Application</tt>
+    # controller is dispatched to.
+    # 
+    # Once the controller is selected and instantiated, the action is called,
+    # defaulting to <tt>:default</tt> if no action is provided.
+    # 
+    # If the action called is not defined, a <tt>404 Not Found</tt> exception
+    # will be raised. This will be sent to the client as such, or handled by
+    # the Rack application container, such as the Rack Cascade middleware to
+    # failover to another application (such as Merb or Rails).
+    # 
+    # Refer to Halcyon::Application::Router for more details on defining routes
+    # and for where to get further documentation.
+    # 
+    # Returns (String|Array|Hash):body
+    # 
+    def dispatch(env)
+      route = env['halcyon.route']
+      # make sure that the right controller/action is called based on the route
+      controller = case route[:controller]
+      when NilClass
+        # default to the Application controller
+        ::Application.new(env)
+      when String
+        # pulled from URL, so camelize (from merb/core_ext) and symbolize first
+        begin
+          Object.const_get(route[:controller].camel_case.to_sym).new(env)
+        rescue NameError => e
+          raise NotFound.new
+        end
+      end
+      
+      # Establish the selected action, defaulting to +default+.
+      action = (route[:action] || 'default').to_sym
+      
+      # Respond correctly that a non-existent action was specified if the
+      # method does not exist.
+      raise NotFound.new unless controller.methods.include?(action.to_s)
+      
+      # if no errors have occured up to this point, the route should be fully
+      # valid and all exceptions raised should be treated as
+      # <tt>500 Internal Server Error</tt>s, which is handled by <tt>call</tt>.
+      controller.send(action)
+    end
+    
+    # Filters unacceptable requests depending on the configuration of the
+    # <tt>:allow_from</tt> option.
+    # 
+    # This method is not directly called by the user, instead being called
+    # in the #call method.
+    # 
+    # Acceptable values include:
+    #   <tt>:all</tt>:: allow every request to go through
+    #   <tt>:halcyon_clients</tt>:: only allow Halcyon clients
+    #   <tt>:local</tt>:: do not allow for requests from an outside host
+    # 
+    # Raises Forbidden
+    # 
+    def acceptable_request!(env)
+      case Halcyon.config[:allow_from].to_sym
+      when :all
+        # allow every request to go through
+      when :halcyon_clients
+        # only allow Halcyon clients
+        raise Forbidden.new unless env['USER_AGENT'] =~ /JSON\/1\.1\.\d+ Compatible \(en-US\) Halcyon::Client\(\d+\.\d+\.\d+\)/
+      when :local
+        # do not allow for requests from an outside host
+        raise Forbidden.new unless ['localhost', '127.0.0.1', '0.0.0.0'].member? env["REMOTE_ADDR"]
+      else
+        logger.warn "Unrecognized allow_from configuration value (#{Halcyon.config[:allow_from].to_s}); use all, halcyon_clients, or local. Allowing all requests."
+      end
+    end
+    
+    # Assemble params for logging.
+    # 
+    # This method exists to be overridden or method-chained to filter out params
+    # from being logged for applications with sensitive data like passwords.
+    # 
+    # Returns Hash:params_to_log
+    # 
+    def filter_params_for_log(request, env)
+      request.params.merge(env['halcyon.route'])
+    end
+    
+    # See the documentation for generated apps in <tt>config/initialze/hooks.rb</tt>
+    # 
+    def hooks
+      self.class.hooks
+    end
+    
+    class << self
+      
+      attr_accessor :hooks
+      
+      # See the documentation for generated apps in <tt>config/initialze/hooks.rb</tt>
+      # 
+      def hooks
+        @hooks ||= {}
+      end
+      
+      # Defines routes for the application.
+      # 
+      # Refer to Halcyon::Application::Router for documentation and resources.
+      # 
+      def route
+        if block_given?
+          Router.prepare do |router|
+            Router.default_to yield(router) || {:controller => 'application', :action => 'not_found'}
+          end
+        end
+      end
+      
+      # Sets the startup hook to the proc.
+      # 
+      # Use this to initialize application-wide resources, such as database
+      # connections.
+      # 
+      # Use initializers where possible.
+      # 
+      def startup &hook
+        self.hooks[:startup] = hook
+      end
+      
+      # Sets the shutdown hook to the proc.
+      # 
+      # Close any resources opened in the +startup+ hook.
+      # 
+      def shutdown &hook
+        self.hooks[:shutdown] = hook
+      end
+      
+    end
+    
+  end
+  
+end

data/lib/halcyon/application/router.rb

@@ -0,0 +1,86 @@
+%w(rubygems merb-core/core_ext merb-core/dispatch/router uri).each {|dep|require dep}
+
+module Halcyon
+  class Application
+    
+    # = Routing
+    # 
+    # Handles routing.
+    # 
+    # == Usage
+    # 
+    #   class Halcyon::Application
+    #     route do |r|
+    #       r.match('/path/to/match').to(:controller => 'a', :action => 'b')
+    #       {:action => 'not_found'} # the default route
+    #     end
+    #   end
+    # 
+    # == Default Routes
+    # 
+    # Supplying a default route if none of the others match is good practice,
+    # but is unnecessary as the predefined route is always, automatically,
+    # going to contain a redirection to the +not_found+ method which already
+    # exists in Halcyon::Controller. This method is freely overwritable, and
+    # is recommended for those that wish to handle unroutable requests
+    # themselves.
+    # 
+    # In order to set a different default route, simply end the call to +route+
+    # with a hash containing the action (and optionally the module) to run.
+    # 
+    # == The Hard Work
+    # 
+    # The mechanics of the router are solely from the efforts of the Merb
+    # community. This functionality is completely ripped right out of Merb
+    # and makes it functional. All credit to them, and be sure to check out
+    # their great framework: if Halcyon isn't quite what you need, maybe Merb
+    # is.
+    # 
+    # http://merbivore.com/
+    class Router < Merb::Router
+      
+      class << self
+        
+        # Retrieves the last value from the +route+ call in Halcyon::Controller
+        # and, if it's a Hash, sets it to +@@default_route+ to designate the
+        # failover route. If +route+ is not a Hash, though, the internal default
+        # should be used instead (as the last returned value is probably a Route
+        # object returned by the +r.match().to()+ call).
+        #   +route+ the default route, or nothing to use <tt>not_found</tt>
+        # 
+        # Used exclusively internally.
+        # 
+        # Returns nothing
+        def default_to(route)
+          @@default_route = route.is_a?(Hash) ? route : {:action => 'not_found'}
+        end
+        
+        # Called internally by the Halcyon::Controller#call method to match
+        # the current request against the currently defined routes. Returns the
+        # params list defined in the +to+ routing definition, opting for the
+        # default route if no match is made.
+        #   +request+ the request object to route against
+        # 
+        # Returns Hash:{:controller=>..., :action=>..., ...}
+        def route(request)
+          req = Struct.new(:path, :method, :params).new(request.path_info, request.request_method.downcase.to_sym, request.params)
+          
+          # perform match
+          route = self.match(req)
+          
+          # make sure a route is returned even if no match is found
+          if route[0].nil?
+            #return default route
+            self.logger.debug "No route found. Using default."
+            @@default_route
+          else
+            # params (including action and module if set) for the matching route
+            route[1]
+          end
+        end
+        
+      end
+      
+    end
+  end
+end

data/lib/halcyon/client.rb

@@ -1,49 +1,201 @@
-#--
-#  Created by Matt Todd on 2007-12-14.
-#  Copyright (c) 2007. All rights reserved.
-#++
-
-$:.unshift File.dirname(File.join('..', __FILE__))
-$:.unshift File.dirname(__FILE__)
-
-#--
-# dependencies
-#++
-
-%w(rubygems halcyon).each {|dep|require dep}
-begin
-  require 'json/ext'
-rescue LoadError => e
-  warn 'Using the Pure Ruby JSON... install the json gem to get faster JSON parsing.'
-  require 'json/pure'
-end
-
-#--
-# module
-#++
+%w(net/http uri json).each {|dep|require dep}
 
 module Halcyon
   
-  # The Client library provides a simple way to package up a client lib to
-  # simplify communicating with the accompanying Halcyon server app.
+  # = Building Custom Clients
+  # 
+  # Once your Halcyon JSON Server App starts to take shape, it may be useful
+  # to begin to write tests on expected functionality, and then to implement
+  # API calls with a designated Client lib for your Ruby or Rails apps, etc.
+  # The Base class provides a standard implementation and several options for
+  # wrapping up functionality of your app from the server side into the
+  # client side so that you may begin to use response data.
+  # 
+  # == Creating Your Client
+  # 
+  # Creating a simple client can be as simple as this:
   # 
-  # = Usage
+  #   class Simple < Halcyon::Client
+  #     def greet(name)
+  #       get("/hello/#{name}")
+  #     end
+  #   end
+  # 
+  # The only thing simply may be actually using the Simple client you just
+  # created.
+  # 
+  # But to actually get in and use the library, one has to take full
+  # advantage of the HTTP request methods, +get+, +post+, +put+, and
+  # +delete+. These methods simply return the JSON-parsed data from the
+  # server, effectively returning a hash with two key values, +status+ which
+  # contains the HTTP status code, and +body+ which contains the body of the
+  # content returned which can be any number of objects, including, but not
+  # limited to Hash, Array, Numeric, Nil, Boolean, String, etc.
+  # 
+  # You are not limited to what your methods can call: they are arbitrarily
+  # and solely up to your whims and needs. It is simply a matter of good
+  # design and performance when it comes to structuring and implementing
+  # client actions which can be complex or simple series of requests to the
+  # server.
   # 
-  # For documentation on using Halcyon, check out the Halcyon::Server::Base and
-  # Halcyon::Client::Base classes which contain much more usage documentation.
   class Client
-    def self.version
-      VERSION.join('.')
+    include Exceptions
+    
+    USER_AGENT = "JSON/#{JSON::VERSION} Compatible (en-US) Halcyon::Client/#{Halcyon.version}"
+    CONTENT_TYPE = 'application/json'
+    DEFAULT_OPTIONS = {
+      :raise_exceptions => false
+    }
+    
+    attr_accessor :uri # The server URI
+    attr_accessor :headers # Instance-wide headers
+    attr_accessor :options # Options
+    
+    #--
+    # Initialization and setup
+    #++
+    
+    # = Connecting to the Server
+    # 
+    # Creates a new Client object to allow for requests and responses from
+    # the specified server.
+    # 
+    # The +uri+ param contains the URL to the actual server, and should be in
+    # the format: "http://localhost:3801" or "http://app.domain.com:3401/"
+    # 
+    # == Server Connections
+    # 
+    # Connecting only occurs at the actual event that a request is performed,
+    # so there is no need to worry about closing connections or managing
+    # connections in general other than good object housecleaning. (Be nice
+    # to your Garbage Collector.)
+    # 
+    # == Usage
+    # 
+    # You can either provide a block to perform all of your requests and
+    # processing inside of or you can simply accept the object in response
+    # and call your request methods off of the returned object.
+    # 
+    # Alternatively, you could do both.
+    # 
+    # An example of creating and using a Simple client:
+    # 
+    #   class Simple < Halcyon::Client
+    #     def greet(name)
+    #       get("/hello/#{name}")
+    #     end
+    #   end
+    #   Simple.new('http://localhost:3801') do |s|
+    #     puts s.greet("Johnny").inspect
+    #   end
+    # 
+    # This should effectively call +inspect+ on a response hash similar to
+    # this:
+    # 
+    #   {:status => 200, :body => 'Hello Johnny'}
+    # 
+    # Alternatively, you could perform the same with the following:
+    # 
+    #   s = Simple.new('http://localhost:3801')
+    #   puts s.greet("Johnny").inspect
+    # 
+    # This should generate the exact same outcome as the previous example,
+    # except that it is not executed in a block.
+    # 
+    # The differences are purely semantic and of personal taste.
+    def initialize(uri, headers = {})
+      self.uri = URI.parse(uri)
+      self.headers = headers
+      self.options = DEFAULT_OPTIONS
+      if block_given?
+        yield self
+      end
+    end
+    
+    def raise_exceptions!(setting = true)
+      self.options[:raise_exceptions] = setting
     end
     
     #--
-    # module dependencies
+    # Request Handling
     #++
     
-    autoload :Base, 'halcyon/client/base'
-    autoload :Router, 'halcyon/client/router'
+    # Performs a GET request on the URI specified.
+    def get(uri, headers={})
+      req = Net::HTTP::Get.new(uri)
+      request(req, headers)
+    end
+    
+    # Performs a POST request on the URI specified.
+    def post(uri, data = {}, headers={})
+      req = Net::HTTP::Post.new(uri)
+      req.body = format_body(data)
+      request(req, headers)
+    end
+    
+    # Performs a DELETE request on the URI specified.
+    def delete(uri, headers={})
+      req = Net::HTTP::Delete.new(uri)
+      request(req, headers)
+    end
+    
+    # Performs a PUT request on the URI specified.
+    def put(uri, data = {}, headers={})
+      req = Net::HTTP::Put.new(uri)
+      req.body = format_body(data)
+      request(req, headers)
+    end
+    
+  private
+    
+    # Performs an arbitrary HTTP request, receive the response, parse it with
+    # JSON, and return it to the caller. This is a private method because the
+    # user/developer should be quite satisfied with the +get+, +post+, +put+,
+    # and +delete+ methods.
+    # 
+    # == Request Failures
+    # 
+    # If the server responds with any kind of failure (anything with a status
+    # that isn't 200), Halcyon will in turn raise the respective exception
+    # (defined in Halcyon::Exceptions) which all inherit from
+    # +Halcyon::Exceptions+. It is up to the client to handle these
+    # exceptions specifically.
+    def request(req, headers={})
+      # set default headers
+      req["Content-Type"] = CONTENT_TYPE
+      req["User-Agent"] = USER_AGENT
+      
+      # apply provided headers
+      self.headers.merge(headers).each do |(header, value)|
+        req[header] = value
+      end
+      
+      # prepare and send HTTP request
+      res = Net::HTTP.start(self.uri.host, self.uri.port) {|http|http.request(req)}
+      
+      # parse response
+      body = JSON.parse(res.body).to_mash
+      
+      # handle non-successes
+      if self.options[:raise_exceptions] && !res.kind_of?(Net::HTTPSuccess)
+        raise self.class.const_get(Exceptions::HTTP_STATUS_CODES[body[:status]].tr(' ', '_').camel_case.gsub(/( |\-)/,'')).new
+      end
+      
+      # return response
+      body
+    rescue Halcyon::Exceptions::Base => e
+      # log exception if logger is in place
+      raise
+    end
+    
+    # Formats the data of a POST or PUT request (the body) into an acceptable
+    # format according to Net::HTTP for sending through as a Hash.
+    def format_body(data)
+      data = {:body => data} unless data.is_a? Hash
+      data.to_mash
+      # uses the Merb Hash#to_params method defined in merb/core_ext.
+      data.to_params
+    end
     
   end
 end
-
-%w(halcyon/client/exceptions).each {|dep|require dep}