halcyon 0.3.7 → 0.3.18

data/Rakefile

@@ -4,7 +4,7 @@ $:.unshift(File.expand_path(File.join(File.dirname(__FILE__), "lib")))
 
 include FileUtils
 
-require 'halcyon'
+require 'lib/halcyon'
 
 project = {
   :name => "halcyon",
@@ -21,9 +21,16 @@ project = {
     --op rdoc
     --line-numbers
     --inline-source
-    --title "Halcyon\ documentation"
-    --exclude "^(_darcs|spec|pkg)/"
-  ]
+    --title "Halcyon\ Documentation"
+    --exclude "^(_darcs|spec|pkg|.svn)/"
+  ],
+  :dependencies => {
+    'json_pure' => '>=1.1.1',
+    'rack' => '>=0.2.0',
+    'merb' => '>=0.4.1'
+  },
+  :requirements => 'install the json gem to get faster JSON parsing',
+  :ruby_version_required => '>=1.8.6'
 }
 
 BASEDIR = File.expand_path(File.dirname(__FILE__))
@@ -43,10 +50,11 @@ spec = Gem::Specification.new do |s|
   s.executables = project[:bin_files]
   s.bindir = "bin"
   s.require_path = "lib"
-  s.add_dependency('rack', '>=0.2.0')
-  s.add_dependency('json', '>=1.1.1')
-  s.add_dependency('merb', '>=0.4.1')
-  s.required_ruby_version = '>= 1.8.6'
+  project[:dependencies].each{|dep|
+    s.add_dependency(dep[0], dep[1])
+  }
+  s.requirements << project[:requirements]
+  s.required_ruby_version = project[:ruby_version_required]
   s.files = (project[:rdoc_files] + %w[Rakefile] + Dir["{spec,lib}/**/*"]).uniq
 end
 
@@ -133,3 +141,8 @@ task :pushsite => [:rdoc] do
   sh "rsync -avz doc/ mtodd@halcyon.rubyforge.org:/var/www/gforge-projects/halcyon/doc/"
   sh "rsync -avz site/ mtodd@halcyon.rubyforge.org:/var/www/gforge-projects/halcyon/"
 end
+
+desc "find . -name \"*.rb\" | xargs wc -l | grep total"
+task :loc do
+  sh "find . -name \"*.rb\" | xargs wc -l | grep total"
+end

data/bin/halcyon

@@ -12,20 +12,14 @@
 # dependencies
 #++
 
-%w(optparse).each{|dep|require dep}
+%w(rubygems halcyon/server optparse).each{|dep|require dep}
 
 #--
 # default options
 #++
 
 $debug = false
-options = {
-  :environment => 'none',
-  :port => 9267,
-  :host => 'localhost',
-  :server => 'mongrel',
-  :log_file => '/tmp/halcyon.log'
-}
+options = Halcyon::Server::DEFAULT_OPTIONS
 
 #--
 # parse options
@@ -35,15 +29,18 @@ opts = OptionParser.new("", 24, '  ') do |opts|
   opts.banner << "Halcyon, JSON Server Framework\n"
   opts.banner << "http://halcyon.rubyforge.org/\n"
   opts.banner << "\n"
-  opts.banner << "Usage: halcyon [options] appname"
+  opts.banner << "Usage: halcyon [options] appname\n"
+  opts.banner << "\n"
+  opts.banner << "Put -c or --config first otherwise it will overwrite higher precedence options."
   
   opts.separator ""
   opts.separator "Options:"
   
-  opts.on("-d", "--debug", "set debugging flags (set $debug to true)") { $debug = true }
+  opts.on("-d", "--debug", "set debugging flag (set $debug to true)") { $debug = true }
+  opts.on("-D", "--Debug", "enable verbose debugging (set $debug and $DEBUG to true)") { $debug = true; $DEBUG = true }
   opts.on("-w", "--warn", "turn warnings on for your script") { $-w = true }
   
-  opts.on("-I", "--include PATH", "specify $LOAD_PATH (may be used more than once)") do |path|
+  opts.on("-I", "--include PATH", "specify $LOAD_PATH (multiples OK)") do |path|
     $:.unshift(*path.split(":"))
   end
   
@@ -51,8 +48,44 @@ opts = OptionParser.new("", 24, '  ') do |opts|
     require library
   end
   
-  opts.on("-c", "--config PATH", "configuration stored in PATH") do |conf|
-    options[:config_file] = conf
+  opts.on("-c", "--config PATH", "load configuration (YAML) from PATH") do |conf_file|
+    if File.exist?(conf_file)
+      require 'yaml'
+      
+      # load the config file
+      begin
+        conf = YAML.load_file(conf_file)
+      rescue Errno::EACCES
+        abort("Can't access #{conf_file}, try 'sudo #{$0}'")
+      end
+      
+      # store config file path so SIGHUP and SIGUSR2 will reload the config in case it changes
+      options[:config_file] = conf_file
+      
+      # parse config
+      case conf
+      when String
+        # config file given was just the commandline options
+        ARGV.replace(conf.split)
+        opts.parse! ARGV
+      when Hash
+        conf.symbolize_keys!
+        options = options.merge(conf)
+      when Array
+        # TODO (MT) support multiple servers (or at least specifying which
+        # server's configuration to load)
+        warn "Your configuration file is setup for multiple servers. This is not a supported feature yet."
+        warn "However, we've pulled the first server entry as this server's configuration."
+        # an array of server configurations
+        # default to the first entry since multiple server configurations isn't
+        # precisely worked out yet.
+        options = options.merge(conf[0])
+      else
+        abort "Config file in an unsupported format. Config files must be YAML or the commandline flags"
+      end
+    else
+      abort "Config file failed to load. #{conf_file} was not found. Correct the path and try again."
+    end
   end
   
   opts.on("-s", "--server SERVER", "serve using SERVER (default: #{options[:server]})") do |serv|
@@ -71,6 +104,14 @@ opts = OptionParser.new("", 24, '  ') do |opts|
     options[:log_file] = log_file
   end
   
+  opts.on("-L", "--loglevel LEVEL", "log level (default: #{options[:log_level]})") do |log_file|
+    options[:log_level] = log_file
+  end
+  
+  opts.on("-P", "--pidfile PATH", "save PID to PATH (default: #{options[:pid_file]})") do |log_file|
+    options[:pid_file] = log_file
+  end
+  
   opts.on("-e", "--env ENVIRONMENT", "use ENVIRONMENT for defaults (default: #{options[:environment]})") do |env|
     options[:environment] = env
   end
@@ -96,15 +137,6 @@ end
 abort "Halcyon needs an app to run. Try: halcyon -h" if ARGV.empty? 
 options[:app] = ARGV.shift
 
-#--
-# load dependencies
-#++
-
-%w(rubygems rack).each{|dep|require dep}
-
-$:.unshift '/Users/mtodd/Sites/halcyon/trunk/lib/'
-%w(halcyon/server).each {|dep|require dep}
-
 #--
 # load app
 #++
@@ -113,15 +145,29 @@ if !File.exists?("#{options[:app]}.rb")
   abort "Halcyon did not find the app #{options[:app]}. Check your path and try again."
 end
 
-require options[:app]
-app = Object.const_get(File.basename(options[:app]).capitalize.gsub(/_([a-z])/){|m|m[1].chr.capitalize})
+begin
+  require options[:app]
+  app = Object.const_get(File.basename(options[:app]).capitalize.gsub(/_([a-z])/){|m|m[1].chr.capitalize})
+rescue NameError => e
+  abort "Unable to load #{File.basename(options[:app]).capitalize.gsub(/_([a-z])/){|m|m[1].chr.capitalize}}. Please ensure your server is so named."
+end
 
 #--
 # prepare server
 #++
-
-require options[:server]
-server = Rack::Handler.const_get(options[:server].capitalize)
+begin
+  server = Rack::Handler.const_get(options[:server].capitalize)
+rescue NameError
+  servers = {
+    'cgi'     => 'CGI',
+    'fastcgi' => 'FastCGI',
+    'lsws'    => 'LSWS',
+    'mongrel' => 'Mongrel',
+    'webrick' => 'WEBrick'
+  }
+  abort "Unsupported server (missing Rack Handler). Did you mean to specify #{options[:server]}?" unless servers.key? options[:server]
+  server = Rack::Handler.const_get(servers[options[:server]])
+end
 
 #--
 # prepare app environment

data/lib/halcyon/client/base.rb

@@ -188,7 +188,7 @@ module Halcyon
         req = Net::HTTP::Post.new(uri)
         req["Content-Type"] = CONTENT_TYPE
         req["User-Agent"] = USER_AGENT
-        req.body = data.to_json
+        req.body = format_body(data)
         request(req)
       end
       
@@ -205,7 +205,7 @@ module Halcyon
         req = Net::HTTP::Put.new(uri)
         req["Content-Type"] = CONTENT_TYPE
         req["User-Agent"] = USER_AGENT
-        req.body = data.to_json
+        req.body = format_body(data)
         request(req)
       end
       
@@ -215,19 +215,37 @@ module Halcyon
       # 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::Client::Exceptions::Base+. It is up to the client to handle
+      # these exceptions specifically.
       def request(req)
         # prepare and send HTTP request
         res = Net::HTTP.start(@uri.host, @uri.port) {|http|http.request(req)}
+        
+        # parse response
         body = JSON.parse(res.body)
         body.symbolize_keys! if body.respond_to? :symbolize_keys!
         
         # handle non-successes
         raise Halcyon::Client::Base::Exceptions.lookup(body[:status]).new unless res.kind_of? Net::HTTPSuccess
         
-        # parse response
+        # return response
         body
       rescue Halcyon::Client::Base::Exceptions::Base => e
-        puts "#{e.status}: #{e.error}"
+        # 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.map{|key,value|"&#{key}=#{value}&"}.join
       end
       
     end

data/lib/halcyon/client/exceptions.rb

@@ -16,7 +16,7 @@ module Halcyon
         # Base Halcyon Exception
         #++
         
-        class Base < Exception #:nodoc:
+        class Base < StandardError #:nodoc:
           attr_accessor :status, :error
           def initialize(status, error)
             @status = status
@@ -31,7 +31,7 @@ module Halcyon
         Halcyon::Exceptions::HTTP_ERROR_CODES.to_a.each do |http_error|
           status, body = http_error
           class_eval(
-            "class #{body.gsub(/ /,'')} < Base\n"+
+            "class #{body.gsub(/( |\-)/,'')} < Base\n"+
             "  def initialize(s=#{status}, e='#{body}')\n"+
             "    super s, e\n"+
             "  end\n"+
@@ -44,7 +44,7 @@ module Halcyon
         #++
         
         def self.lookup(status)
-          self.const_get(Halcyon::Exceptions::HTTP_ERROR_CODES[status].gsub(/ /,'').to_sym)
+          self.const_get(Halcyon::Exceptions::HTTP_ERROR_CODES[status].gsub(/( |\-)/,''))
         end
         
       end

data/lib/halcyon/client.rb

@@ -10,7 +10,13 @@ $:.unshift File.dirname(__FILE__)
 # dependencies
 #++
 
-%w(halcyon rubygems json).each {|dep|require dep}
+%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
@@ -26,7 +32,6 @@ module Halcyon
   # For documentation on using Halcyon, check out the Halcyon::Server::Base and
   # Halcyon::Client::Base classes which contain much more usage documentation.
   class Client
-    VERSION.replace [0,2,12]
     def self.version
       VERSION.join('.')
     end
@@ -36,8 +41,9 @@ module Halcyon
     #++
     
     autoload :Base, 'halcyon/client/base'
-    autoload :Exceptions, 'halcyon/client/exceptions'
     autoload :Router, 'halcyon/client/router'
     
   end
 end
+
+%w(halcyon/client/exceptions).each {|dep|require dep}

data/lib/halcyon/exceptions.rb

@@ -10,10 +10,71 @@
 module Halcyon
   module Exceptions #:nodoc:
     HTTP_ERROR_CODES = {
-      403 => "Forbidden",
-      404 => "Not Found",
-      406 => "Not Acceptable",
-      415 => "Unsupported Media Type"
+      400  => 'Bad Request',
+      401  => 'Unauthorized',
+      402  => 'Payment Required',
+      403  => 'Forbidden',
+      404  => 'Not Found',
+      405  => 'Method Not Allowed',
+      406  => 'Not Acceptable',
+      407  => 'Proxy Authentication Required',
+      408  => 'Request Time-out',
+      409  => 'Conflict',
+      410  => 'Gone',
+      411  => 'Length Required',
+      412  => 'Precondition Failed',
+      413  => 'Request Entity Too Large',
+      414  => 'Request-URI Too Large',
+      415  => 'Unsupported Media Type',
+      500  => 'Internal Server Error',
+      501  => 'Not Implemented',
+      502  => 'Bad Gateway',
+      503  => 'Service Unavailable',
+      504  => 'Gateway Time-out',
+      505  => 'HTTP Version not supported'
     }
   end
 end
+
+# Taken from Rack's definition:
+# http://chneukirchen.org/darcs/darcsweb.cgi?r=rack;a=plainblob;f=/lib/rack/utils.rb
+# 
+# HTTP_STATUS_CODES = {
+#   100  => 'Continue',
+#   101  => 'Switching Protocols',
+#   200  => 'OK',
+#   201  => 'Created',
+#   202  => 'Accepted',
+#   203  => 'Non-Authoritative Information',
+#   204  => 'No Content',
+#   205  => 'Reset Content',
+#   206  => 'Partial Content',
+#   300  => 'Multiple Choices',
+#   301  => 'Moved Permanently',
+#   302  => 'Moved Temporarily',
+#   303  => 'See Other',
+#   304  => 'Not Modified',
+#   305  => 'Use Proxy',
+#   400  => 'Bad Request',
+#   401  => 'Unauthorized',
+#   402  => 'Payment Required',
+#   403  => 'Forbidden',
+#   404  => 'Not Found',
+#   405  => 'Method Not Allowed',
+#   406  => 'Not Acceptable',
+#   407  => 'Proxy Authentication Required',
+#   408  => 'Request Time-out',
+#   409  => 'Conflict',
+#   410  => 'Gone',
+#   411  => 'Length Required',
+#   412  => 'Precondition Failed',
+#   413  => 'Request Entity Too Large',
+#   414  => 'Request-URI Too Large',
+#   415  => 'Unsupported Media Type',
+#   500  => 'Internal Server Error',
+#   501  => 'Not Implemented',
+#   502  => 'Bad Gateway',
+#   503  => 'Service Unavailable',
+#   504  => 'Gateway Time-out',
+#   505  => 'HTTP Version not supported'
+# }

data/lib/halcyon/server/base.rb

@@ -16,12 +16,25 @@
 module Halcyon
   class Server
     
-    DEFAULT_OPTIONS = {}
+    DEFAULT_OPTIONS = {
+      :environment => 'none',
+      :port => 9267,
+      :host => 'localhost',
+      :server => 'mongrel',
+      :pid_file => '/var/run/halcyon.{server}.{app}.{port}.pid',
+      :log_file => '/var/log/halcyon.{app}.log',
+      :log_level => 'info',
+      :log_format => proc{|s,t,p,m|"#{s} [#{t.strftime("%Y-%m-%d %H:%M:%S")}] (#{$$}) #{p} :: #{m}\n"},
+      # handled internally
+      :acceptable_requests => [],
+      :acceptable_remotes => []
+    }
     ACCEPTABLE_REQUESTS = [
+      # ENV var to check, Regexp the value should match, the status code to return in case of failure, the message with the code
       ["HTTP_USER_AGENT", /JSON\/1\.1\.\d+ Compatible( \(en-US\) Halcyon\/(\d+\.\d+\.\d+) Client\/(\d+\.\d+\.\d+))?/, 406, 'Not Acceptable'],
       ["CONTENT_TYPE", /application\/json/, 415, 'Unsupported Media Type']
     ]
-    ACCEPTABLE_REMOTES = ['localhost', '127.0.0.1']
+    ACCEPTABLE_REMOTES = ['localhost', '127.0.0.1', '0.0.0.0']
     
     # = Building Halcyon Server Apps
     # 
@@ -86,7 +99,40 @@ module Halcyon
     # route actually matches, so it doesn't need any of the extra path to match
     # against.
     # 
-    # == 
+    # == The Filesystem
+    # 
+    # It's important to note that the +halcyon+ commandline tool expects the to
+    # find your server inheriting +Halcyon::Server::Base+ with the same exact
+    # name as its filename, though with special rules.
+    # 
+    # To clarify, when your server is stored in +app_server.rb+, it expects
+    # that your server's class name be +AppServer+ as it capitalizes each word
+    # and removes all underscores, etc.
+    # 
+    # Keep this in mind when naming your class and your file.
+    # 
+    # NOTE: This really isn't a necessary step if you write your own deployment
+    # script instead of using the +halcyon+ commandline tool (as it is simply
+    # a convenience tool). In such, feel free to name your server however you
+    # prefer and the file likewise.
+    # 
+    # == Running Your Server On Your Own
+    # 
+    # If you're wanting to run your server without the help of the +halcyon+
+    # commandline tool, you will simply need to initialize the server as you
+    # pass it to the Rack handler of choice along with any configuration
+    # options you desire.
+    # 
+    # The following should be enough:
+    # 
+    #   Rack::Handler::Mongrel.run YourAppName.new(options), :Port => 9267
+    # 
+    # Of course Halcyon already handles most of your dependencies for you, so
+    # don't worry about requiring Rack, et al. And again, the options are not
+    # mandatory as the default options are certainly acceptable.
+    # 
+    # NOTE: If you want to provide debugging information, just set +$debug+ to
+    # +true+ and you should receive all the debugging information available.
     class Base
       
       #--
@@ -115,8 +161,52 @@ module Halcyon
       # 
       # DO NOT try to call +to_json+ on the +body+ contents as this will cause
       # errors when trying to parse JSON.
+      # 
+      # == Request and Response
+      # 
+      # If you need access to the Request and Response, the instance variables
+      # +@req+ and +@res+ will be sufficient for you.
+      # 
+      # If you need specific documentation for these objects, check the
+      # corresponding docs in the Rack documentation.
+      # 
+      # == Requests and POST Data
+      # 
+      # Most of your requests will have all the data it needs inside of the
+      # +params+ you receive for your action, but for POST and PUT requests
+      # (you are being RESTful, right?) you will need to retrieve your data
+      # from the +POST+ property of the +@req+ request. Here's how:
+      # 
+      #   @req.POST['key'] => "value"
+      # 
+      # As you can see, keys specifically are strings and values as well. What
+      # this means is that your POST data that you send to the server needs to
+      # be careful to provide a flat Hash (if anything other than a Hash is
+      # passed, it is packed up into a hash similar to +{:body=>data}+) or at
+      # least send a complicated structure as a JSON object so that transport
+      # is clean. Resurrecting the object is still on your end for POST data
+      # (though this could change). Here's how you would reconstruct your
+      # special hash:
+      # 
+      #   value = JSON.parse(@req.POST['key'])
+      # 
+      # That will take care of reconstructing your Hash.
+      # 
+      # And that is essentially all you need to worry about for retreiving your
+      # POST contents. Sending POST contents should be documented well enough
+      # in Halcyon::Client::Base.
+      # 
+      # == Logging
+      # 
+      # Logging can be done by logging to +@logger+ when inside the scope of
+      # application instance (inside of your instance methods and modules).
+      # 
+      # The +@env+ instance variable has been modified to include a
+      # +halcyon.logger+ property including the given logger. Use this for
+      # logging if you need to step outside of the scope of the current
+      # application instance (just be sure to pass @env along with you).
       def call(env)
-        @start_time = Time.now if $debug
+        @time_started = Time.now
         
         # collect env information, create request and response objects, prep for dispatch
         # puts env.inspect if $debug # request information (huge)
@@ -124,18 +214,32 @@ module Halcyon
         @res = Rack::Response.new
         @req = Rack::Request.new(env)
         
-        ACCEPTABLE_REMOTES.replace([@env["REMOTE_ADDR"]]) if $debug
+        # add the logger to the @env instance variable for global access if for
+        # some reason the environment needs to be passed outside of the
+        # instance
+        @env['halcyon.logger'] = @logger
+        
+        # set the acceptable remotes to include the remote IP if debugging is enabled
+        @config[:acceptable_remotes] << @env["REMOTE_ADDR"] if $debug
         
         # pre run hook
-        before_run(Time.now - @start_time) if respond_to? :before_run
+        before_run(Time.now - @time_started) if respond_to? :before_run
+        
+        # prepare route and provide it for callers
+        route = Router.route(@env)
+        @env['halcyon.route'] = route
         
         # dispatch
-        @res.write(run(Router.route(env)).to_json)
+        @res.write(run(route).to_json)
         
         # post run hook
-        after_run(Time.now - @start_time) if respond_to? :after_run
+        after_run(Time.now - @time_started) if respond_to? :after_run
         
-        puts "Served #{env['REQUEST_URI']} in #{(Time.now - @start_time)}" if $debug
+        @time_finished = Time.now - @time_started
+        
+        # logs access in the following format: [200] / => index (0.0029s;343.79req/s)
+        req_time, req_per_sec = ((@time_finished*1e4).round.to_f/1e4), (((1.0/@time_finished)*1e2).round.to_f/1e2)
+        @logger.info "[#{@res.status}] #{@env['REQUEST_URI']} => #{route[:module].to_s}#{((route[:module].nil?) ? "" : "::")}#{route[:action]} (#{req_time}s;#{req_per_sec}req/s)"
         
         # finish request
         @res.finish
@@ -206,10 +310,10 @@ module Halcyon
       # (or one of its inheriters) instead of handling them manually.
       def run(route)
         # make sure the request meets our expectations
-        ACCEPTABLE_REQUESTS.each do |req|
+        @config[:acceptable_requests].each do |req|
           raise Exceptions::Base.new(req[2], req[3]) unless @env[req[0]] =~ req[1]
         end
-        raise Exceptions::Forbidden.new unless ACCEPTABLE_REMOTES.member? @env["REMOTE_ADDR"]
+        raise Exceptions::Forbidden.new unless @config[:acceptable_remotes].member? @env["REMOTE_ADDR"]
         
         # pull params
         params = route.reject{|key, val| [:action, :module].include? key}
@@ -234,7 +338,7 @@ module Halcyon
         
         res
       rescue Exceptions::Base => e
-        # puts @env.inspect if $debug
+        @logger.warn "#{uri} => #{e.error}"
         # handles all content error exceptions
         @res.status = e.status
         {:status => e.status, :body => e.error}
@@ -246,24 +350,209 @@ module Halcyon
       
       # Called when the Handler gets started and stores the configuration
       # options used to start the server.
+      # 
+      # Feel free to define initialize for your app (which is only called once
+      # per server instance), just be sure to call +super+.
+      # 
+      # == PID File
+      # 
+      # A PID file is created when the server is first initialized with the
+      # current process ID. Where it is located depends on the default option,
+      # the config file, the commandline option, and the debug status,
+      # increasing in precedence in that order.
+      # 
+      # By default, the PID file is placed in +/var/run/+ and is named
+      # +halcyon.{server}.{app}.{port}.pid+ where +{server}+ is replaced by the
+      # running server, +{app}+ is the app name (suffixed with +#debug+ if
+      # running in debug mode), and +{port}+ being the server port (if there
+      # are multiple servers running, this helps clarify).
+      # 
+      # There is an option to numerically label your server  via the +{n}+
+      # value, but this is deprecated and will be removed soon. Using the
+      # +{port}+ option makes much more sense and creates much more meaning.
       def initialize(options = {})
-        # debug mode handling
-        if $debug
-          puts "Entering debugging mode..."
-          @logger = Logger.new(STDOUT)
-          ACCEPTABLE_REQUESTS.replace([
-            ["HTTP_USER_AGENT", /.*/, 406, 'Not Acceptable'],
-            ["HTTP_USER_AGENT", /.*/, 415, 'Unsupported Media Type'] # content type isn't set when navigating via browser
-          ])
-        end
-        
         # save configuration options
         @config = DEFAULT_OPTIONS.merge(options)
         
+        # apply name options to log_file and pid_file configs
+        apply_log_and_pid_file_name_options
+        
+        # debug mode handling
+        enable_debugging if $debug
+        
         # setup logging
-        @logger ||= Logger.new(@config[:log_file])
+        setup_logging unless $debug
+        
+        # setup request filtering
+        setup_request_filters unless $debug
+        
+        # create PID file
+        @pid = File.new(@config[:pid_file].gsub('{n}', server_cluster_number), "w", 0644)
+        @pid << "#{$$}\n"; @pid.close
+        
+        # log existence and ready status
+        @logger.info "PID file created. PID is #{$$}."
+        @logger.info "Started. Awaiting connectivity. Listening on #{@config[:port]}..."
+        
+        # trap signals to die (when killed by the user) gracefully
+        finalize =  Proc.new do
+          @logger.info "Shutting down #{$$}."
+          @logger.close
+          File.delete(@pid.path)
+          exit
+        end
+        # http://en.wikipedia.org/wiki/Signal_%28computing%29
+        %w(INT KILL TERM QUIT HUP).each{|sig|trap(sig, finalize)}
         
-        puts "Started. Awaiting input. Listening on #{@config[:port]}..." if $debug
+        # listen for USR1 signals and toggle debugging accordingly
+        trap("USR1") do
+          if $debug
+            disable_debugging
+          else
+            enable_debugging
+          end
+        end
+      end
+      
+      # Retreives the server cluster sequence number for the PID file.
+      # 
+      # This is deprecated and will be removed soon, probably for the 0.4.0
+      # release. Use of the +{port}+ value is much more appropriate and
+      # meaningful.
+      def server_cluster_number
+        # if there are no +{n}+ references in the PID file name, then simply
+        # return 0 as the cluster number. (This is the preferred behavior and
+        # this test allows the method to fail fast. +{n}+ is deprecated and
+        # will be removed before 0.4.0 is released.)
+        return 0.to_s if @config[:pid_file]['{n}'].nil?
+        
+        # warn users that they're using a deprecated convention.
+        warn "Your PID file name contains '{n}' (#{@config[:pid_file]}). This is deprecatd and will be removed by the 0.4.0 release. Use '{port}' instead."
+        
+        # counts the number of PID files already existing.
+        server_count = Dir[@config[:pid_file].gsub('{n}','*')].length
+        # since the counting starts at 0, if the file with the count exists,
+        # then one of the lesser number servers isn't running, so check each
+        # PID file until the one not running is found.
+        # if no files exist, then 0 will be the count, which won't exist, so
+        # it will be the default number.
+        while File.exist?(@config[:pid_file].gsub('{n}',server_count.to_s))
+          server_count -= 1
+        end
+        # return that number.
+        server_count.to_s
+      end
+      
+      # If the server receives a SIGUSR1 signal it will toggle debugging. This
+      # method is used to setup logging and the request handling methods for
+      # debugging.
+      def enable_debugging
+        $debug = true
+        # setup logger to STDOUT and log entering debugging mode
+        @logger = Logger.new(STDOUT)
+        @logger.progname = "#{self.class}#debug"
+        @logger.level = Logger::DEBUG
+        @logger.formatter = @config[:log_format]
+        @logger.info "Entering debugging mode..."
+        
+        # set the PID file name to /tmp/ unless PID file already exists
+        @config[:pid_file] = '/tmp/halcyon.{server}.{app}.{port}.pid' unless @pid.is_a? File
+        apply_log_and_pid_file_name_options # reapply for {server}, {app}, and {port} to be set
+        
+        # modify acceptable request's profiles
+        @config[:acceptable_requests] = [
+          ["HTTP_USER_AGENT", /.*/, 406, 'Not Acceptable'],
+          ["HTTP_USER_AGENT", /.*/, 415, 'Unsupported Media Type'] # content type isn't set when navigating via browser
+        ]
+        @logger.debug "ACCEPTABLE_REQUESTS modified to accept all User Agents (browsers)"
+      rescue Errno::EACCES
+      	abort "Can't access #{@config[:pid_file]}, try 'sudo #{$0}'"
+      end
+      
+      # Disables all of the affects of debugging mode and returns logging and
+      # request filtering back to normal.
+      # 
+      # Refer to +enable_debugging+ for more information.
+      def disable_debugging
+        # disable logging and log leaving debugging mode
+        $debug = false
+        @logger.info "Leaving debugging mode."
+        
+        # setup normal logging
+        setup_logging
+        
+        # reenable request filtering
+        setup_request_filters
+      end
+      
+      # Sets up logging based on the configuration options in +@config+, which
+      # is set (in order of lowest to highest precedence) in the default
+      # options, in the configuration file provided, on the commandline, and
+      # debug mode options.
+      # 
+      # == Levels
+      # 
+      # The accepted level values are as follows:
+      # 
+      #   debug
+      #   info
+      #   warn
+      #   error
+      #   fatal
+      #   unknown
+      # 
+      # These are the exact way you can refer to the logger level you'd like to
+      # log at from all points of option specification (listed above in order
+      # of ascending precedence).
+      # 
+      # If a bogus value is entered, a warning will be issued and the value
+      # will be defaulted to 'debug'. (So don't mess up.)
+      def setup_logging
+        # get the logging level based on the name supplied
+        level = {
+          'debug' => Logger::DEBUG,
+          'info'  => Logger::INFO,
+          'warn'  => Logger::WARN,
+          'error' => Logger::ERROR,
+          'fatal' => Logger::FATAL,
+          'unknown' => Logger::UNKNOWN # wtf?
+        }[@config[:log_level]]
+        if level.nil?
+          warn "Logging level specified not acceptable. Defaulting to 'debug'. Check the documentation for the acceptable values."
+          @config[:log_level] = 'debug'
+          level = Logger::DEBUG
+        end
+        
+        # setup the logger
+        @logger = Logger.new(@config[:log_file])
+        @logger.progname = self.class
+        @logger.level = level
+        @logger.formatter = @config[:log_format]
+      rescue Errno::EACCES
+      	abort "Can't access #{@config[:log_file]}, try 'sudo #{$0}'"
+      end
+      
+      # Sets up request filters based on User-Agent, Content-Type, and Remote
+      # IP/address values.
+      # 
+      # Extracted from +initialize+ to reduce repetition.
+      def setup_request_filters
+        @config[:acceptable_requests] = ACCEPTABLE_REQUESTS
+        @config[:acceptable_remotes] = ACCEPTABLE_REMOTES
+      end
+      
+      # Searches through the PID file name and the Log file name stored in the
+      # +@config+ variable for +{server}+, +{app}+, and +{port}+ values and
+      # sets them accordingly.
+      def apply_log_and_pid_file_name_options
+        # DEFAULT :pid_file => '/var/run/halcyon.{server}.{app}.{port}.pid',
+        @config[:pid_file].gsub!('{server}', @config[:server])
+        @config[:pid_file].gsub!('{port}', @config[:port].to_s)
+        @config[:pid_file].gsub!('{app}', File.basename(@config[:app]))
+        # DEFAULT :log_file => '/var/log/halcyon.{app}.log',
+        @config[:log_file].gsub!('{server}', @config[:server])
+        @config[:log_file].gsub!('{port}', @config[:port].to_s)
+        @config[:log_file].gsub!('{app}', File.basename(@config[:app]))
       end
       
       # = Routing
@@ -378,7 +667,9 @@ module Halcyon
       
       # Returns the URI requested
       def uri
-        @env['REQUEST_URI']
+        # special parsing is done to remove the protocol, host, and port that
+        # some Handlers leave in there. (Fixes inconsistencies.)
+        URI.parse(@env['REQUEST_URI']).path
       end
       
       # Returns the Request Method as a lowercase symbol

data/lib/halcyon/server/exceptions.rb

@@ -16,7 +16,7 @@ module Halcyon
         # Base Halcyon Exception
         #++
         
-        class Base < Exception #:nodoc:
+        class Base < StandardError #:nodoc:
           attr_accessor :status, :error
           def initialize(status, error)
             @status = status
@@ -31,7 +31,7 @@ module Halcyon
         Halcyon::Exceptions::HTTP_ERROR_CODES.to_a.each do |http_error|
           status, body = http_error
           class_eval(
-            "class #{body.gsub(/ /,'')} < Base\n"+
+            "class #{body.gsub(/( |\-)/,'')} < Base\n"+
             "  def initialize(s=#{status}, e='#{body}')\n"+
             "    super s, e\n"+
             "  end\n"+
@@ -44,7 +44,7 @@ module Halcyon
         #++
         
         def self.lookup(status)
-          self.const_get(Halcyon::Exceptions::HTTP_ERROR_CODES[status].gsub(/ /,'').to_sym)
+          self.const_get(Halcyon::Exceptions::HTTP_ERROR_CODES[status].gsub(/( |\-)/,''))
         end
         
       end

data/lib/halcyon/server/router.rb

@@ -75,7 +75,8 @@ module Halcyon
       # params list defined in the +to+ routing definition, opting for the
       # default route if no match is made.
       def self.route(env)
-        uri = env['REQUEST_URI']
+        # pull out the path requested (WEBrick keeps the host and port and protocol in REQUEST_URI)
+        uri = URI.parse(env['REQUEST_URI']).path
         
         # prepare request
         path = (uri ? uri.split('?').first : '').sub(/\/+/, '/')
@@ -88,6 +89,7 @@ module Halcyon
         # make sure a route is returned even if no match is found
         if route[0].nil?
           #return default route
+          env['halcyon.logger'].debug "No route found. Using default."
           @@default_route
         else
           # params (including action and module if set) for the matching route

data/lib/halcyon/server.rb

@@ -10,7 +10,13 @@ $:.unshift File.dirname(__FILE__)
 # dependencies
 #++
 
-%w(halcyon rubygems rack json).each {|dep|require dep}
+%w(rubygems halcyon rack).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
@@ -35,7 +41,6 @@ module Halcyon
   # For documentation on using Halcyon, check out the Halcyon::Server::Base and
   # Halcyon::Client::Base classes which contain much more usage documentation.
   class Server
-    VERSION.replace [0,3,7]
     def self.version
       VERSION.join('.')
     end
@@ -45,11 +50,13 @@ module Halcyon
     #++
     
     autoload :Base, 'halcyon/server/base'
-    autoload :Exceptions, 'halcyon/server/exceptions'
     autoload :Router, 'halcyon/server/router'
     
   end
   
 end
 
-%w(server/exceptions).each {|dep|require dep}
+# Loads the Exceptions class first which sets up all the dynamically generated
+# exceptions used by the system. Must occur before Base is loaded since Base
+# depends on it.
+%w(halcyon/server/exceptions).each {|dep|require dep}

data/lib/halcyon.rb

@@ -21,7 +21,7 @@ end
 #++
 
 module Halcyon
-  VERSION = [0,3,7]
+  VERSION = [0,3,18]
   def self.version
     VERSION.join('.')
   end
@@ -42,13 +42,7 @@ module Halcyon
   def introduction
     abort "READ THE DAMNED RDOCS FOO"
   end
-
-  #--
-  # module dependencies
-  #++
   
-  autoload :Exceptions, 'halcyon/exceptions'
-  autoload :Server, 'halcyon/server'
-  autoload :Client, 'halcyon/client'
-
 end
+
+%w(halcyon/exceptions).each {|dep|require dep}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: halcyon
 version: !ruby/object:Gem::Version 
-  version: 0.3.7
+  version: 0.3.18
 platform: ruby
 authors: 
 - Matt Todd
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2007-12-16 00:00:00 -05:00
+date: 2007-12-31 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,22 +22,22 @@ dependencies:
         version: 0.2.0
     version: 
 - !ruby/object:Gem::Dependency 
-  name: json
+  name: merb
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.1.1
+        version: 0.4.1
     version: 
 - !ruby/object:Gem::Dependency 
-  name: merb
+  name: json_pure
   version_requirement: 
   version_requirements: !ruby/object:Gem::Requirement 
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.4.1
+        version: 1.1.1
     version: 
 description: A JSON App Server Framework
 email: chiology@gmail.com
@@ -76,9 +76,9 @@ rdoc_options:
 - --line-numbers
 - --inline-source
 - --title
-- "\"Halcyon documentation\""
+- "\"Halcyon Documentation\""
 - --exclude
-- "\"^(_darcs|spec|pkg)/\""
+- "\"^(_darcs|spec|pkg|.svn)/\""
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
@@ -93,8 +93,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version 
       version: "0"
   version: 
-requirements: []
-
+requirements: 
+- install the json gem to get faster JSON parsing
 rubyforge_project: 
 rubygems_version: 0.9.5
 signing_key: