bluepill 0.1.3 → 0.1.4

data/lib/bluepill/controller.rb

@@ -2,12 +2,56 @@ require 'fileutils'
 require 'bluepill/system'
 
 module Bluepill
+  # Run the bluepill CLI's commands, and send them to the daemon
+  #
+  # The CLI and the daemon talk over a socket of the application's in the
+  # base directory.
+  #
+  # @api private
   class Controller
     attr_accessor :base_dir, :log_file, :sockets_dir, :pids_dir
 
-    def initialize(options = {})
+    # @!attribute [rw] base_dir
+    #   The directory with the daemons' sockets and pid files
+    #
+    #   @return [String]
+    #
+    #   @api private
+
+    # @!attribute [rw] log_file
+    #   The log file to tail when the daemon doesn't name one
+    #
+    #   @return [String, nil]
+    #
+    #   @api private
+
+    # @!attribute [rw] sockets_dir
+    #   The directory with the daemons' sockets
+    #
+    #   @return [String]
+    #
+    #   @api private
+
+    # @!attribute [rw] pids_dir
+    #   The directory with the daemons' pid files
+    #
+    #   @return [String]
+    #
+    #   @api private
+
+    # Create the controller, and clean up after daemons that died
+    #
+    # It creates the sockets and pids directories, and removes the socket
+    # and pid file of each daemon that's no longer running.
+    #
+    # @param [Hash{Symbol => Object}] options :base_dir, and :log_file
+    #
+    # @return [void]
+    #
+    # @api private
+    def initialize(options)
       self.log_file = options[:log_file]
-      self.base_dir = options[:base_dir]
+      self.base_dir = options.fetch(:base_dir)
       self.sockets_dir = File.join(base_dir, 'socks')
       self.pids_dir = File.join(base_dir, 'pids')
 
@@ -15,17 +59,35 @@ module Bluepill
       cleanup_bluepill_directory
     end
 
+    # Return the names of the applications with a daemon's socket
+    #
+    # @return [Array<String>]
+    #
+    # @api private
     def running_applications
       Dir[File.join(sockets_dir, '*.sock')].collect { |x| File.basename(x, '.sock') }
     end
 
+    # Run a CLI command and print what it did
+    #
+    # status prints the daemon's status, quit stops the daemon, log tails
+    # the log for a process or group, and the PROCESS_COMMANDS go to the
+    # daemon. It exits with status 1 for an unknown command.
+    #
+    # @param [String] application the application's name
+    # @param [String, Symbol] command the command
+    # @param [Array<String>] args the group or process, for example
+    #
+    # @return [void]
+    #
+    # @api private
     def handle_command(application, command, *args)
       case command.to_sym
       when :status
         puts send_to_daemon(application, :status, *args)
       when :quit
         pid = pid_for(application)
-        if System.pid_alive?(pid)
+        if pid && System.pid_alive?(pid)
           ::Process.kill('TERM', pid)
           puts "Killing bluepilld[#{pid}]"
         else
@@ -33,12 +95,12 @@ module Bluepill
         end
       when :log
         log_file_location = send_to_daemon(application, :log_file)
-        log_file_location = log_file if log_file_location.to_s.strip.empty?
+        log_file_location = log_file if log_file_location.to_s.rstrip.empty?
 
         requested_pattern = args.first
-        grep_pattern = self.grep_pattern(application, requested_pattern)
+        pattern = grep_pattern(application, requested_pattern)
 
-        tail = "tail -n 100 -f #{log_file_location} | grep -E '#{grep_pattern}'"
+        tail = "tail -n 100 -f #{log_file_location} | grep -E '#{pattern}'"
         puts "Tailing log for #{requested_pattern}..."
         Kernel.exec(tail)
       when *Application::PROCESS_COMMANDS
@@ -58,6 +120,19 @@ module Bluepill
       end
     end
 
+    # Send a command to an application's daemon, and return its answer
+    #
+    # It first checks that the daemon runs this version of bluepill. It
+    # prints an error that the daemon raised and exits with status 8, and
+    # aborts if the daemon isn't running.
+    #
+    # @param [String] application the application's name
+    # @param [String, Symbol] command the command
+    # @param [Array<String>] args the command's arguments
+    #
+    # @return [Object] what the daemon answered
+    #
+    # @api private
     def send_to_daemon(application, command, *args)
       verify_version!(application)
 
@@ -66,27 +141,41 @@ module Bluepill
       if response.is_a?(Exception)
         $stderr.puts 'Received error from server:'
         $stderr.puts response.inspect
-        $stderr.puts response.backtrace.join("\n")
+        # join flattens the backtrace and makes a missing one empty
+        $stderr.puts [response.backtrace].join("\n")
         exit(8)
       else
         response
       end
-
     rescue Errno::ECONNREFUSED
       abort('Connection Refused: Server is not running')
     end
 
+    # Return the pattern that finds a process or group's lines in the log
+    #
+    # @param [String] application the application's name
+    # @param [String, nil] query the process or group
+    #
+    # @return [String] an extended regular expression for grep
+    #
+    # @api private
     def grep_pattern(application, query = nil)
       pattern = [application, query].compact.join(':')
-      ['\[.*', Regexp.escape(pattern), '.*'].compact.join
+      ['\[.*', Regexp.escape(pattern), '.*'].join
     end
 
   private
 
+    # Remove the socket and pid file of each daemon that's not running
+    #
+    # @return [void]
+    #
+    # @api private
     def cleanup_bluepill_directory
       running_applications.each do |app|
         pid = pid_for(app)
         next if pid && System.pid_alive?(pid)
+
         pid_file = File.join(pids_dir, "#{app}.pid")
         sock_file = File.join(sockets_dir, "#{app}.sock")
         System.delete_if_exists(pid_file)
@@ -94,22 +183,44 @@ module Bluepill
       end
     end
 
+    # Return the pid in an application's pid file
+    #
+    # @param [String] app the application's name
+    #
+    # @return [Integer, false] the pid, or false without a valid one
+    #
+    # @api private
     def pid_for(app)
       pid_file = File.join(pids_dir, "#{app}.pid")
-      File.exist?(pid_file) && File.read(pid_file).to_i
+      return false unless File.exist?(pid_file)
+
+      # An empty or garbled pid file reads as 0, and signaling pid 0 would
+      # hit the CLI's own process group
+      pid = File.read(pid_file).to_i
+      pid > 0 ? pid : false
     end
 
+    # Create the sockets and pids directories
+    #
+    # @return [void]
+    #
+    # @api private
     def setup_dir_structure
       [@sockets_dir, @pids_dir].each do |dir|
         FileUtils.mkdir_p(dir) unless File.exist?(dir)
       end
     end
 
+    # Abort unless an application's daemon runs this version of bluepill
+    #
+    # @param [String] application the application's name
+    #
+    # @return [void]
+    #
+    # @api private
     def verify_version!(application)
       version = Socket.client_command(base_dir, application, 'version')
-      if version != Bluepill::Version
-        abort("The running version of your daemon seems to be out of date.\nDaemon Version: #{version}, CLI Version: #{Bluepill::Version}")
-      end
+      abort("The running version of your daemon seems to be out of date.\nDaemon Version: #{version}, CLI Version: #{Version}") unless version.equal?(Version)
     rescue ArgumentError
       abort('The running version of your daemon seems to be out of date.')
     end

data/lib/bluepill/dsl/app_proxy.rb

@@ -1,17 +1,116 @@
 module Bluepill
+  # The self of the block given to {Bluepill.application}
+  #
+  # It sets defaults that every process of the application gets, and defines
+  # the processes.
+  #
+  # @example
+  #   Bluepill.application(:my_app) do |app|
+  #     app.working_dir = '/srv/my_app'
+  #     app.process('web') { |process| process.start_command = 'bin/server' }
+  #   end
+  #
+  # @api public
   class AppProxy
+    # The attributes that every process of the application gets, unless the
+    # process sets its own
     APP_ATTRIBUTES = [:working_dir, :uid, :gid, :environment, :auto_start].freeze
 
-    attr_accessor(*APP_ATTRIBUTES)
+    # The directory that the application's processes start in
+    #
+    # @example
+    #   app.working_dir = '/srv/my_app'
+    #
+    # @return [String, nil] the directory, or nil for the default
+    #
+    # @api public
+    attr_accessor :working_dir
+
+    # The user that the application's processes run as
+    #
+    # @example
+    #   app.uid = 'deploy'
+    #
+    # @return [String, nil] the user's name, or nil for bluepill's own user
+    #
+    # @api public
+    attr_accessor :uid
+
+    # The group that the application's processes run as
+    #
+    # @example
+    #   app.gid = 'deploy'
+    #
+    # @return [String, nil] the group's name, or nil for bluepill's own group
+    #
+    # @api public
+    attr_accessor :gid
+
+    # The environment variables that the application's processes get
+    #
+    # @example
+    #   app.environment = {'RAILS_ENV' => 'production'}
+    #
+    # @return [Hash{#to_s => #to_s}, nil] the variables by name
+    #
+    # @api public
+    attr_accessor :environment
+
+    # Whether the application's processes start when bluepill loads
+    #
+    # @example
+    #   app.auto_start = false
+    #
+    # @return [Boolean, nil] false to leave the processes unmonitored until
+    #   they're started
+    #
+    # @api public
+    attr_accessor :auto_start
+
+    # Return the application that the config describes
+    #
+    # @return [Application] the application
+    #
+    # @api private
     attr_reader :app
 
+    # Create the proxy of a new application
+    #
+    # @param [#to_s] app_name the application's name
+    # @param [Hash{Symbol => Object}] options the application's options
+    #
+    # @return [void]
+    #
+    # @api private
     def initialize(app_name, options)
       @app = Application.new(app_name.to_s, options)
     end
 
+    # Define a process of the application
+    #
+    # The block runs with self set to a {ProcessProxy}, and also gets the
+    # proxy as an argument. The process starts with the application's
+    # attributes, which the block can override.
+    #
+    # @example
+    #   app.process('web') do |process|
+    #     process.start_command = '/usr/bin/my_server'
+    #     process.group = 'servers'
+    #   end
+    #
+    # @param [String] process_name the process's name
+    #
+    # @yield [process] configures the process
+    # @yieldparam [ProcessProxy] process the process's proxy, which is also
+    #   self
+    # @yieldreturn [void]
+    #
+    # @return [Array<Process>] the processes of the process's group
+    #
+    # @api public
     def process(process_name, &process_block)
-      attributes = {}
-      APP_ATTRIBUTES.each { |a| attributes[a] = send(a) }
+      attributes = {} #: Hash[Symbol, untyped]
+      APP_ATTRIBUTES.each { |a| attributes[a] = public_send(a) }
 
       process_factory = ProcessFactory.new(attributes, process_block)
 

data/lib/bluepill/dsl/process_factory.rb

@@ -1,29 +1,78 @@
 module Bluepill
+  # Create the processes that a config file describes, and check them
+  #
+  # A factory turns a process block into a {Process}, after it checks the
+  # config for mistakes, such as two processes with the same name or pid
+  # file. A process that monitors its children gets a factory of its own for
+  # them.
+  #
+  # @api private
   class ProcessFactory
+    # Return the attributes that each process starts with
+    #
+    # @return [Hash{Symbol => Object}] the attributes
+    #
+    # @api private
     attr_reader :attributes
 
-    @@process_keys = {}
-    @@pid_files = {}
-
+    # Only the keys matter
+    @@process_keys = {} #: Hash[Array[String?], nil]
+    @@pid_files = {} #: Hash[String, nil]
+
+    # Create a factory of processes
+    #
+    # @param [Hash{Symbol => Object}] attributes the attributes that each
+    #   process starts with
+    # @param [Proc] process_block the block that configures each process
+    #
+    # @return [void]
+    #
+    # @api private
     def initialize(attributes, process_block)
       @attributes = attributes
       @process_block = process_block
     end
 
+    # Create a process from the factory's block, and check its config
+    #
+    # A process without a pid_file gets a default one in pids_dir.
+    #
+    # @param [String] name the process's name
+    # @param [String] pids_dir the directory of the default pid file
+    #
+    # @return [Process] the process
+    #
+    # @api private
     def create_process(name, pids_dir)
-      assign_default_pid_file(name, pids_dir)
+      default_pid_file = assign_default_pid_file(name, pids_dir)
 
       process = ProcessProxy.new(name, @attributes, @process_block)
       child_process_block = @attributes.delete(:child_process_block)
       @attributes[:child_process_factory] = ProcessFactory.new(@attributes, child_process_block) if @attributes[:monitor_children]
 
       validate_process! process
+      warn_unless_pid_known(process, default_pid_file)
       process.to_process
     end
 
+    # Create the process of a child that bluepill found
+    #
+    # The child gets its parent's grace times, and its state from whether
+    # it's running.
+    #
+    # @param [String] name the child's name
+    # @param [Integer] pid the child's pid
+    # @param [Logger] logger the child's logger
+    #
+    # @return [Process] the child's process
+    #
+    # @api private
     def create_child_process(name, pid, logger)
-      attributes = {}
-      [:start_grace_time, :stop_grace_time, :restart_grace_time].each { |a| attributes[a] = @attributes[a] }
+      attributes = {} #: Hash[Symbol, untyped]
+      # A grace time the parent leaves unset keeps the Process default
+      [:start_grace_time, :stop_grace_time, :restart_grace_time].each do |a|
+        attributes[a] = @attributes.fetch(a) if @attributes.key?(a)
+      end
       attributes[:actual_pid] = pid
       attributes[:logger] = logger
 
@@ -37,79 +86,153 @@ module Bluepill
 
   protected
 
+    # Set the default pid file, unless the process sets its own
+    #
+    # @param [String] process_name the process's name
+    # @param [String] pids_dir the directory of the pid file
+    #
+    # @return [String, nil] the default pid file, or nil when the process
+    #   sets its own
+    #
+    # @api private
     def assign_default_pid_file(process_name, pids_dir)
       return if @attributes.key?(:pid_file)
+
       group_name = @attributes[:group]
-      default_pid_name = [group_name, process_name].compact.join('_').gsub(/[^A-Za-z0-9_\-]/, '_')
-      @attributes[:pid_file] = File.join(pids_dir, default_pid_name + '.pid')
+      default_pid_name = [group_name, process_name].compact.join('_').gsub(/[^A-Za-z0-9_-]/, '_')
+      @attributes[:pid_file] = File.join(pids_dir, "#{default_pid_name}.pid")
     end
 
+    # Check a process's config, and exit on a mistake
+    #
+    # The process shares its attributes hash with the factory.
+    #
+    # @param [ProcessProxy] process the process's proxy
+    #
+    # @return [void]
+    #
+    # @api private
     def validate_process!(process)
-      # validate uniqueness of group:process
-      process_key = [process.attributes[:group], process.name].join(':')
-      if @@process_keys.key?(process_key)
-        $stderr.print "Config Error: You have two entries for the process name '#{process.name}'"
-        $stderr.print " in the group '#{process.attributes[:group]}'" if process.attributes.key?(:group)
-        $stderr.puts
-        exit(6)
-      else
-        @@process_keys[process_key] = 0
-      end
+      validate_unique_process!(process)
+      validate_required_attributes!(process)
+      validate_unique_pid_file!
+      validate_stop_signals!
+    end
 
-      # validate required attributes
-      [:start_command].each do |required_attr|
-        unless process.attributes.key?(required_attr)
-          $stderr.puts "Config Error: You must specify a #{required_attr} for '#{process.name}'"
-          exit(6)
-        end
+    # Exit if another process in the group has the same name
+    #
+    # @param [ProcessProxy] process the process's proxy
+    #
+    # @return [void]
+    #
+    # @api private
+    def validate_unique_process!(process)
+      # A process name may contain ':', so the key keeps the parts apart.
+      # Like Application#add_process, it treats Symbols and Strings alike.
+      process_key = [attributes[:group], process.name].collect { |part| part && part.to_s }
+      if @@process_keys.key?(process_key)
+        message = "Config Error: You have two entries for the process name '#{process.name}'"
+        message += " in the group '#{attributes.fetch(:group)}'" if attributes.key?(:group)
+        config_error!(message)
       end
+      @@process_keys[process_key] = nil
+    end
 
-      # validate uniqueness of pid files
-      pid_key = process.attributes[:pid_file].strip
-      if @@pid_files.key?(pid_key)
-        $stderr.puts "Config Error: You have two entries with the pid file: #{pid_key}"
-        exit(6)
-      else
-        @@pid_files[pid_key] = 0
-      end
+    # Exit unless the process has a start_command
+    #
+    # @param [ProcessProxy] process the process's proxy
+    #
+    # @return [void]
+    #
+    # @api private
+    def validate_required_attributes!(process)
+      return if attributes.key?(:start_command)
+
+      config_error!("Config Error: You must specify a start_command for '#{process.name}'")
+    end
 
-      # validate stop_signals array
-      stop_grace_time = process.attributes[:stop_grace_time]
-      stop_signals = process.attributes[:stop_signals]
+    # Exit if another process has the same pid file
+    #
+    # @return [void]
+    #
+    # @api private
+    def validate_unique_pid_file!
+      pid_key = attributes.fetch(:pid_file).strip
+      config_error!("Config Error: You have two entries with the pid file: #{pid_key}") if @@pid_files.key?(pid_key)
+      @@pid_files[pid_key] = nil
+    end
 
+    # Exit unless stop_signals alternates signals and delays
+    #
+    # The signals and delays must alternate, starting and ending with a
+    # signal, and stop_grace_time must be longer than the delays. Checks the
+    # more specific problems before the 'odd number' message.
+    #
+    # @return [void]
+    #
+    # @api private
+    def validate_stop_signals!
+      stop_signals = attributes[:stop_signals]
       return if stop_signals.nil?
-      # Start with the more helpful error messages before the 'odd number' message.
-      delay_sum = 0
-      stop_signals.each_with_index do |s_or_d, i|
-        if i.even?
-          signal = s_or_d
-          unless signal.is_a? Symbol
-            $stderr.puts "Config Error: Invalid stop_signals!  Expected a symbol (signal) at position #{i} instead of '#{signal}'."
-            exit(6)
-          end
-        else
-          delay = s_or_d
-          unless delay.is_a? Fixnum
-            $stderr.puts "Config Error: Invalid stop_signals!  Expected a number (delay) at position #{i} instead of '#{delay}'."
-            exit(6)
-          end
-          delay_sum += delay
-        end
-      end
 
-      unless stop_signals.size.odd?
-        $stderr.puts 'Config Error: Invalid stop_signals!  Expected an odd number of elements.'
-        exit(6)
-      end
+      stop_signals.each_with_index do |value, i|
+        expected, label = i.even? ? [Symbol, 'a symbol (signal)'] : [Integer, 'a number (delay)']
+        next if value.is_a?(expected)
 
-      if stop_grace_time.nil? || stop_grace_time <= delay_sum
-        $stderr.puts 'Config Error: Stop_grace_time should be greater than the sum of stop_signals delays!'
-        exit(6)
+        config_error!("Config Error: Invalid stop_signals!  Expected #{label} at position #{i} instead of '#{value}'.")
       end
+      config_error!('Config Error: Invalid stop_signals!  Expected an odd number of elements.') unless stop_signals.size.odd?
+
+      stop_grace_time = attributes[:stop_grace_time]
+      delays = stop_signals.select.with_index { |_, i| i.odd? }
+      return unless stop_grace_time.nil? || stop_grace_time <= delays.inject(0, :+)
+
+      config_error!('Config Error: Stop_grace_time should be greater than the sum of stop_signals delays!')
+    end
+
+    # Warn when bluepill can't find the process's pid
+    #
+    # Bluepill only writes the default pid file for processes it daemonizes,
+    # so it cannot find the pid of any other process that uses it.
+    #
+    # @param [ProcessProxy] process the process's proxy
+    # @param [String, nil] default_pid_file the default pid file, or nil when
+    #   the process sets its own
+    #
+    # @return [void]
+    #
+    # @api private
+    def warn_unless_pid_known(process, default_pid_file)
+      return if attributes[:daemonize] || attributes[:pid_command] || !attributes.fetch(:pid_file).eql?(default_pid_file)
+
+      warning = "Config Warning: '#{process.name}' sets no daemonize, pid_file or pid_command, " \
+                "so bluepill cannot find its pid unless start_command writes it to #{default_pid_file}. " \
+                'Set daemonize = true if start_command runs in the foreground.'
+      $stderr.puts warning
     end
 
+    # Print a config error and exit with status 6
+    #
+    # @param [String] message the error
+    #
+    # @return [void] it never returns
+    #
+    # @api private
+    def config_error!(message)
+      $stderr.puts message
+      exit(6)
+    end
+
+    # Exit unless a monitored child has a stop_command
+    #
+    # @param [ProcessProxy] child the child's proxy
+    #
+    # @return [void]
+    #
+    # @api private
     def validate_child_process!(child)
       return if child.attributes.key?(:stop_command)
+
       $stderr.puts "Config Error: Invalid child process monitor for #{child.name}"
       $stderr.puts 'You must specify a stop command to monitor child processes.'
       exit(6)