picnic 0.5.0

data/lib/picnic/cli.rb

@@ -0,0 +1,112 @@
+require 'optparse'
+
+module Picnic
+  # Provides a command-line interface for your app. 
+  # This is useful for creating a 'bin' file for launching your application.
+  #
+  # Usage example (put this in a file called 'foo'):
+  #
+  #   #!/usr/bin/env ruby
+  #
+  #   require 'rubygems'
+  #   require 'picnic'
+  #
+  #   require 'picnic/cli'
+  #
+  #   cli = Picnic::Cli.new(
+  #     'foo',
+  #     :app_path => File.expand_path(File.dirname(File.expand_path(__FILE__)))
+  #   )
+  #
+  #   cli.handle_cli_input   
+  #
+  # Also see the ServiceControl class for info on how to use your cli script
+  # as a service.
+  class Cli
+    attr_accessor :app, :options
+    
+    # Creates a new command-line interface handler.
+    #
+    # +app+:: The name of the application. This should match the name of the
+    #         binary, which by default is expected to be in the same directory
+    #         as the service control script.
+    # +options+:: A hash overriding default options. The options are:
+    #             +app_path+:: The path to your application's main Ruby file.
+    #                          By default this is expected to be <tt>../lib/<app>.rb</tt>
+    #             +pid_file+:: Where the app's PID file (containing the app's
+    #                          process ID) should be placed. By default this is
+    #                          <tt>/etc/<app>/<app>.pid</tt>
+    #             +verbose+::  True if the cli handler should report
+    #                          everything that it's doing to STDOUT. 
+    def initialize(app, options = {})
+      @app = app
+      
+      @options = {}
+      @options[:app_path]  ||= File.expand_path(File.dirname(File.expand_path(__FILE__))+"/../lib/#{app}.rb")
+      @options[:pid_file]  ||= "/etc/#{app}/#{app}.pid"
+      @options[:conf_file] ||= nil
+      @options[:verbose]   ||= false
+      
+      @options = options
+    end
+    
+    # Parses command line options given to the script.
+    def handle_cli_input
+      if File.exists? options[:app_path]
+        # try to use given app base path
+        $: << File.dirname(options[:app_path])
+        path = File.dirname(options[:app_path])+"/"
+      else
+        # fall back to using gem installation
+        path = ""
+        require 'rubygems'
+        gem(app)
+      end
+      
+      $PID_FILE = "/etc/#{app}/#{app}.pid" 
+      
+      OptionParser.new do |opts|
+        opts.banner = "Usage: #{app} [options]"
+      
+        opts.on("-c", "--config FILE", "Use config file (default is /etc/#{app}/config.yml)") do |c|
+          puts "Using config file #{c}"
+          $CONFIG_FILE = c
+        end
+        
+        opts.on("-d", "--daemonize", "Run as a daemon (only when using webrick or mongrel)") do |c|
+          $DAEMONIZE = true
+        end
+      
+        opts.on("-P", "--pid_file FILE", "Use pid file (default is /etc/#{app}/#{app}.pid)") do |c|
+          if $DAEMONIZE && !File.exists?(c)
+            puts "Using pid file '#{c}'"
+            $PID_FILE = c
+          elsif File.exists?(c)
+            puts "The pid file already exists.  Is #{app} running?\n" +
+              "You will have to first manually remove the pid file at '#{c}' to start the server as a daemon."
+            exit 1
+          else
+            puts "Not running as daemon.  Ignoring pid option"
+          end
+        end
+      
+        opts.on_tail("-h", "--help", "Show this message") do
+          puts opts
+          exit
+        end
+        
+        opts.on_tail("-V", "--version", "Show version number") do
+          require "#{path}/lib/#{app}/version"
+          puts "#{app}-#{VERSION::STRING}"
+          exit
+        end
+      end.parse!
+      
+      $APP_PATH = options[:app_path]
+      
+      load "#{path}/lib/#{app}.rb"
+    end
+  end
+end
+
+

data/lib/picnic/conf.rb

@@ -0,0 +1,133 @@
+module Picnic
+  # Provides an interface for accessing your Picnic app's configuration file.
+  #
+  # Usage example:
+  #
+  #   # Load the configuration from /etc/foo/config.yml
+  #   Conf.load('foo')
+  #
+  #   # The contents of config.yml is now available as follows:
+  #   puts Conf[:server]
+  #   puts Conf[:authentication][:username]
+  #   # ... etc.
+  class Conf
+    $CONF ||= HashWithIndifferentAccess.new
+    $CONF[:log] ||= HashWithIndifferentAccess.new
+    $CONF[:log][:file]  ||= STDOUT
+    $CONF[:log][:level] ||= 'DEBUG'
+    $CONF[:uri_path]    ||= "/"
+    
+    # Read a configuration option.
+    #
+    # For example:
+    #   puts Conf[:server]
+    def self.[](key)
+      $CONF[key]
+    end
+    
+    # Another way of reading a configuration option.
+    #
+    # The following statements are equivalent:
+    #   puts Conf[:server]
+    #   puts Conf.server
+    def self.method_missing(method, *args)
+      self[method]
+    end
+    
+    # Returns the path to your application's example config file.
+    #
+    # The example config file should be in the root directory of
+    # your application's distribution package and should be called
+    # <tt>config.example.yml</tt>. This file is used as a template
+    # for your app's configuration, to be customized by the end
+    # user. 
+    def self.example_config_file_path
+      if $APP_PATH
+        app_path = File.expand_path($APP_PATH)
+      else
+        caller.last =~ /^(.*?):\d+$/
+        app_path = File.dirname(File.expand_path($1))
+      end
+      app_path+'/../config.example.yml'
+    end
+    
+    # Copies the example config file into the appropriate
+    # configuration directory.
+    #
+    # +app+:: The name of your application. For example: <tt>foo</tt>
+    # +dest_conf_file:: The path where the example conf file should be copied to.
+    #                   For example: <tt>/etc/foo/config.yml</tt>
+    def self.copy_example_config_file(app, dest_conf_file)
+      require 'fileutils'
+          
+      example_conf_file = example_config_file_path
+      
+      puts "\n#{app.to_s.upcase} SERVER HAS NOT YET BEEN CONFIGURED!!!\n"
+      puts "\nAttempting to copy sample configuration from '#{example_conf_file}' to '#{dest_conf_file}'...\n"
+      
+      unless File.exists? example_conf_file 
+        puts "\nThe example conf file does not exist! The author of #{app} may have forgotten to include it. You'll have to create the config file manually.\n"
+        exit 2
+      end
+      
+      begin
+        dest_conf_file_dir = File.dirname(dest_conf_file)
+        FileUtils.mkpath(dest_conf_file_dir) unless File.exists? dest_conf_file_dir
+        FileUtils.cp(example_conf_file, dest_conf_file)
+      rescue Errno::EACCES
+        puts "\nIt appears that you do not have permissions to create the '#{dest_conf_file}' file. Try running this command using sudo (as root).\n"
+        exit 2
+      rescue => e
+        puts "\nFor some reason the '#{dest_conf_file}' file could not be created (#{e})."
+        puts "You'll have to copy the file manually. Use '#{example_conf_file}' as a template.\n"  
+        exit 2
+      end
+      
+      puts "\nA sample configuration has been created for you in '#{dest_conf_file}'. Please edit this file to" +
+        " suit your needs and then run #{app} again.\n"
+      exit 1
+    end
+    
+    # Loads the configuration from the yaml file for the given app.
+    #
+    # <tt>app</tt> should be the name of your app; for example: <tt>foo</tt>.
+    #
+    # By default, the configuration will be loaded from <tt>/etc/<app>/config.yml</tt>.
+    # You can override this by setting a global <tt>$CONFIG_FILE</tt> variable.
+    def self.load(app)
+      
+      conf_file = $CONFIG_FILE || "/etc/#{app.to_s.downcase}/config.yml"
+      
+      puts "Loading configuration for #{app} from '#{conf_file}'..."
+      
+      begin
+        conf_file = etc_conf = conf_file
+        unless File.exists? conf_file 
+          # can use local config.yml file in case we're running non-gem installation
+          conf_file = File.dirname(File.expand_path(__FILE__))+"/../../config.yml"
+        end
+      
+        unless File.exists? conf_file  
+          copy_example_config_file(app, etc_conf)
+        end
+        
+        loaded_conf = HashWithIndifferentAccess.new(YAML.load_file(conf_file))
+        
+        if $CONF
+          $CONF = HashWithIndifferentAccess.new($CONF)
+          $CONF = $CONF.merge(loaded_conf)
+        else
+          $CONF = loaded_conf
+        end
+        
+        $CONF[:log][:file] = STDOUT unless $CONF[:log][:file]
+        
+      rescue
+          raise "Your #{app} configuration may be invalid."+
+            " Please double-check check your config.yml file."+
+            " Make sure that you are using spaces instead of tabs for your indentation!!" +
+            "\n\nTHE UNDERLYING ERROR WAS:\n#{$!}"
+      end
+    end
+  end
+end

data/lib/picnic/controllers.rb

@@ -0,0 +1,31 @@
+module Picnic
+  module Controllers
+    # Provides a controller for serving up static content from your app's <tt>/public</tt> directory.
+    # This can be used to serve css, js, jpg, png, and gif files. Anything you put in your app's
+    # '/public' directory will be served up under the '/public' path.
+    #
+    # That is, say you have:
+    #   /srv/www/camping/my_app/public/test.jpg
+    # This should be availabe at:
+    #   http://myapp.com/public/test.jpg
+    #
+    # This controller is automatically enabled for all Picnic-enabled apps. 
+    class Public < Camping::Controllers::R '/public/(.+)'
+      BASE_PATH = ("#{$APP_PATH}/.." || File.expand_path(File.dirname(__FILE__)))+'/lib/public'
+      
+      MIME_TYPES = {'.css' => 'text/css', '.js' => 'text/javascript', 
+                    '.jpg' => 'image/jpeg', '.png' => 'image/png', 
+                    '.gif' => 'image/gif'}
+  
+      def get(path)
+        @headers['Content-Type'] = MIME_TYPES[path[/\.\w+$/, 0]] || "text/plain"
+        unless path.include? ".." # prevent directory traversal attacks
+          @headers['X-Sendfile'] = "#{BASE_PATH}/#{path}"
+        else
+          @status = "403"
+          "403 - Invalid path"
+        end
+      end
+    end
+  end
+end

data/lib/picnic/postambles.rb

@@ -0,0 +1,227 @@
+module Picnic
+  # In Camping, "postambles" are wrappers used to make your application run under
+  # some given web server. They are called "postambles" because traditionally this
+  # was a piece of code included at the bottom of your Camping script. Picnic
+  # provides postambles for two popular Ruby-based web servers: webrick and mongrel.
+  # These postambles take care of all the complications of launching and managing
+  # the web server for you.
+  module Postambles
+    
+    # Launches your Camping application using a webrick server.
+    #
+    # It is possible to run using SSL by providing an <tt>:ssl_cert</tt> path in your
+    # app's configuration file, pointing to a valid SSL certificate file.
+    #
+    # If $DAEMONIZE is true, the webrick server will be forked to a background process.
+    # Note that this may have some strange effects, since any open IOs or threads will not
+    # be carried over to the forked daemon process.
+    #
+    # Module#start_picnic automatically calls this method to launch your Picnic app if
+    # your app's <tt>:server</tt> configuration option is set to <tt>'webrick'</tt>.
+    #
+    # Usage example:
+    #
+    #   require 'picnic/postambles'
+    #   self.extend self::Postambles
+    #   webrick
+    #
+    def webrick
+      require 'webrick/httpserver'
+      require 'webrick/https'
+      require 'camping/webrick'
+      
+      # TODO: verify the certificate's validity
+      # example of how to do this is here: http://pablotron.org/download/ruri-20050331.rb
+      
+      cert_path = Picnic::Conf.ssl_cert
+      key_path = Picnic::Conf.ssl_key || Picnic::Conf.ssl_cert
+        # look for the key in the ssl_cert if no ssl_key is specified
+            
+      begin
+        s = WEBrick::HTTPServer.new(
+          :BindAddress => "0.0.0.0",
+          :Port => Picnic::Conf.port
+        )
+      rescue Errno::EACCES
+        puts "\nThe server could not launch. Are you running on a privileged port? (e.g. port 443) If so, you must run the server as root."
+        exit 2
+      end
+      
+      self.create
+      s.mount "#{Picnic::Conf.uri_path}", WEBrick::CampingHandler, self
+    
+      # This lets Ctrl+C shut down your server
+      trap(:INT) do
+        s.shutdown
+      end
+      trap(:TERM) do
+        s.shutdown
+      end
+            
+      if $DAEMONIZE
+        puts "\n** #{self} will run at http://#{ENV['HOSTNAME'] || 'localhost'}:#{Picnic::Conf.port}#{Picnic::Conf.uri_path} and log to #{Picnic::Conf.log[:file].inspect}. "
+        puts "** Check the log file for further messages!\n\n"
+        
+        logdev = $LOG.instance_variable_get(:@logdev).instance_variable_get(:@filename)
+        if logdev == 'STDOUT' || logdev == nil
+          puts "\n!!! Warning !!!\nLogging to the console (STDOUT) is not possible once the server daemonizes. "+
+            "You should change the logger configuration to point to a real file."
+        end
+        
+        WEBrick::Daemon.start do
+          begin
+            write_pid_file if $PID_FILE
+            $LOG.info "Starting #{self} as a WEBrick daemon with process id #{Process.pid}."
+            self.prestart if self.respond_to? :prestart
+            s.start
+            $LOG.info "Stopping #{self} WEBrick daemon with process id #{Process.pid}."
+            clear_pid_file
+          rescue => e
+            $LOG.error e
+            raise e
+          end
+        end
+      else
+        puts "\n** #{self} is running at http://#{ENV['HOSTNAME'] || 'localhost'}:#{Picnic::Conf.port}#{Picnic::Conf.uri_path} and logging to #{Picnic::Conf.log[:file].inspect}\n\n"
+        self.prestart if self.respond_to? :prestart
+        s.start
+      end
+    end
+    
+    # Launches your Camping application using a mongrel server.
+    #
+    # Mongrel is much faster than webrick, but has two limitations:
+    # 1. You must install the mongrel gem before you can run your server using mongrel.
+    #    This is not necessary with webrick, since webrick is included by default with Ruby.
+    # 2. Unlike webrick, mongrel can't be run using SSL. You will have to use a reverse
+    #    proxy like Pound or Apache if you want to use mongrel with SSL. 
+    #
+    # If $DAEMONIZE is true, the mongrel server will be forked to a background process.
+    # Note that this may have some strange effects, since any open IOs or threads will not
+    # be carried over to the forked daemon process.
+    #
+    # Module#start_picnic automatically calls this method to launch your Picnic app if
+    # your app's <tt>:server</tt> configuration option is set to <tt>'mongrel'</tt>.
+    #
+    # Usage example:
+    #
+    #   require 'picnic/postambles'
+    #   self.extend self::Postambles
+    #   mongrel
+    #
+    def mongrel
+      require 'rubygems'
+      require 'mongrel/camping'
+      
+      if $DAEMONIZE
+        # check if log and pid are writable before daemonizing, otherwise we won't be able to notify
+        # the user if we run into trouble later (since once daemonized, we can't write to stdout/stderr)
+        check_pid_writable if $PID_FILE
+        check_log_writable
+      end
+      
+      self.create
+      
+      puts "\n** #{self} is starting. Look in #{Picnic::Conf.log[:file].inspect} for further notices."
+      
+      settings = {:host => "0.0.0.0", :log_file => Picnic::Conf.log[:file], :cwd => $APP_PATH}
+      
+      # need to close all IOs before daemonizing
+      $LOG.close if $DAEMONIZE
+      
+      begin
+        app_mod = self
+        config = Mongrel::Configurator.new settings  do
+          daemonize :log_file => Picnic::Conf.log[:file], :cwd => $APP_PATH if $DAEMONIZE
+          
+          listener :port => Picnic::Conf.port do
+            uri Picnic::Conf.uri_path, :handler => Mongrel::Camping::CampingHandler.new(app_mod)
+            setup_signals
+          end
+        end
+      rescue Errno::EADDRINUSE
+        exit 1
+      end
+      
+      
+      config.run
+      
+      self.init_logger
+      #self.init_db_logger
+      
+      if $DAEMONIZE && $PID_FILE
+        write_pid_file
+        unless File.exists? $PID_FILE
+          $LOG.error "#{self} could not start because pid file #{$PID_FILE.inspect} could not be created."
+          exit 1
+        end
+      end
+      
+      puts "\n** #{self} is running at http://#{ENV['HOSTNAME'] || 'localhost'}:#{Picnic::Conf.port}#{Picnic::Conf.uri_path} and logging to '#{Picnic::Conf.log[:file]}'"
+      
+      self.prestart if self.respond_to? :prestart
+      config.join
+
+      clear_pid_file
+
+      puts "\n** #{self} is stopped (#{Time.now})"
+    end
+    
+    # Theoretically this should launch your Picnic app as a FastCGI process.
+    # I say "theoretically" because this has never actually been tested.
+    def fastcgi
+      require 'camping/fastcgi'
+      Dir.chdir('.')
+      
+      self.create
+      Camping::FastCGI.start(self)
+    end
+    
+    # Theoretically this should launch your Picnic app as a CGI process.
+    # I say "theoretically" because this has never actually been tested.
+    def cgi
+      self.create
+      puts self.run
+    end
+    
+    private
+    # Prints an error message to stderr if the log file is not writable.
+    def check_log_writable
+      log_file = Picnic::Conf.log['file']
+      begin
+        f = open(log_file, 'w')
+      rescue
+        $stderr.puts "Couldn't write to log file at '#{log_file}' (#{$!})."
+        exit 1
+      end
+      f.close
+    end
+    
+    # Prints an error message to stderr if the pid file is not writable.
+    def check_pid_writable
+      $LOG.debug "Checking if pid file #{$PID_FILE.inspect} is writable"
+      begin        
+        f = open($PID_FILE, 'w')
+      rescue
+        $stderr.puts "Couldn't write to log at #{$PID_FILE.inspect} (#{$!})."
+        exit 1
+      end
+      f.close
+    end
+    
+    # Writes the pid file.
+    def write_pid_file
+      $LOG.debug "Writing pid #{Process.pid.inspect} to pid file #{$PID_FILE.inspect}"
+      open($PID_FILE, "w") { |file| file.write(Process.pid) }
+    end
+    
+    # Removes the pid file.
+    def clear_pid_file
+      if $PID_FILE && File.exists?($PID_FILE)
+        $LOG.debug "Clearing pid file #{$PID_FILE.inspect}"
+        File.unlink $PID_FILE
+      end
+    end
+  
+  end
+end