bluepill 0.1.3 → 0.1.4

data/lib/bluepill/dsl/process_proxy.rb

@@ -1,41 +1,159 @@
 module Bluepill
+  # The self of a process block in a config file
+  #
+  # Any of the process's attributes can be set with `name = value`,
+  # `name value`, or `name!` for true, and read back with `name`. See
+  # {Process::CONFIGURABLE_ATTRIBUTES} for the attributes a process has.
+  #
+  # @example
+  #   app.process('web') do |process|
+  #     process.start_command = '/usr/bin/my_server'
+  #     process.daemonize!
+  #     process.checks :mem_usage, every: 10.seconds, below: 100.megabytes
+  #   end
+  #
+  # @api public
   class ProcessProxy
-    attr_reader :attributes, :watches, :name
+    # Return the attributes that the block set, by name
+    #
+    # @return [Hash{Symbol => Object}] the attributes
+    #
+    # @api private
+    attr_reader :attributes
+
+    # Return the checks that the block added, with their options, by name
+    #
+    # @return [Hash{Symbol => Hash{Symbol => Object}}] the checks
+    #
+    # @api private
+    attr_reader :watches
+
+    # Return the process's name
+    #
+    # @return [String] the name
+    #
+    # @api private
+    attr_reader :name
+
+    # Create the proxy of a process, and run its block
+    #
+    # @param [String] process_name the process's name
+    # @param [Hash{Symbol => Object}] attributes the attributes the process
+    #   starts with, which the block adds to
+    # @param [Proc] process_block the block that configures the process
+    #
+    # @return [void]
+    #
+    # @api private
     def initialize(process_name, attributes, process_block)
       @name = process_name
       @attributes = attributes
       @watches = {}
 
-      if process_block.arity.zero?
-        instance_eval(&process_block)
-      else
-        instance_exec(self, &process_block)
-      end
+      # instance_eval also passes the proxy to a block that takes an argument
+      instance_eval(&process_block)
     end
 
+    # Set or read an attribute of the process
+    #
+    # A name ending in `=`, or one given a value, sets the attribute. A name
+    # ending in `!` sets it to true. A name alone reads an attribute that's
+    # set.
+    #
+    # @example
+    #   process.start_command = '/usr/bin/my_server'
+    #   process.stop_grace_time 10.seconds
+    #   process.daemonize!
+    #   process.start_command # => "/usr/bin/my_server"
+    #
+    # @param [Symbol] name the attribute's name
+    # @param [Array<Object>] args the value, if it's set
+    #
+    # @return [Object] the value that was set or read
+    #
+    # @raise [NoMethodError] for an attribute that isn't set, or more than one
+    #   value
+    #
+    # @api public
     def method_missing(name, *args)
-      if args.size == 1 && name.to_s =~ /^(.*)=$/
-        @attributes[Regexp.last_match[1].to_sym] = args.first
-      elsif args.size == 1
-        @attributes[name.to_sym] = args.first
-      elsif args.empty? && name.to_s =~ /^(.*)!$/
-        @attributes[Regexp.last_match[1].to_sym] = true
-      elsif args.empty? && @attributes.key?(name.to_sym)
-        @attributes[name.to_sym]
+      attribute = name.to_s
+      case args.size
+      when 1
+        value, = args
+        @attributes[attribute.chomp('=').to_sym] = value
+      when 0
+        if attribute.end_with?('!')
+          @attributes[attribute.chomp('!').to_sym] = true
+        elsif @attributes.key?(name)
+          @attributes.fetch(name)
+        else
+          super
+        end
       else
         super
       end
     end
 
+    # Return whether the proxy answers a name through method_missing
+    #
+    # Ruby turns a String name into a Symbol before calling this.
+    #
+    # @param [Symbol] name the method's name
+    # @param [Boolean, nil] _include_private ignored
+    #
+    # @return [Boolean] true for a setter, a `name!`, or an attribute that's
+    #   set
+    #
+    # @api private
+    def respond_to_missing?(name, _include_private)
+      ['=', '!'].include?(name[-1]) || @attributes.key?(name)
+    end
+
+    # Add a check of the process, or a trigger such as :flapping
+    #
+    # @example
+    #   process.checks :cpu_usage, every: 10.seconds, below: 50, times: [3, 5]
+    #   process.checks :flapping, times: 2, within: 30.seconds, retry_in: 7.seconds
+    #
+    # @param [Symbol] name the check's name, such as :mem_usage
+    # @param [Hash{Symbol => Object}] options the check's options, such as
+    #   :every, :below and :times
+    #
+    # @return [Hash{Symbol => Object}] the options
+    #
+    # @api public
     def checks(name, options = {})
       @watches[name] = options
     end
 
+    # Monitor the process's children too
+    #
+    # The block configures each child the way a process block configures a
+    # process. It must set a stop_command.
+    #
+    # @example
+    #   process.monitor_children do |child|
+    #     child.stop_command = 'kill -QUIT {{PID}}'
+    #     child.checks :mem_usage, every: 10.seconds, below: 200.megabytes
+    #   end
+    #
+    # @yield [child] configures each child
+    # @yieldparam [ProcessProxy] child the child's proxy, which is also self
+    # @yieldreturn [void]
+    #
+    # @return [Proc, nil] the block
+    #
+    # @api public
     def monitor_children(&child_process_block)
       @attributes[:monitor_children] = true
       @attributes[:child_process_block] = child_process_block
     end
 
+    # Create the process that the block described
+    #
+    # @return [Process] the process
+    #
+    # @api private
     def to_process
       Process.new(@name, @watches, @attributes)
     end

data/lib/bluepill/dsl.rb

@@ -1,11 +1,33 @@
 module Bluepill
+  # Load an application from a config file
+  #
+  # The block describes the application's processes. It runs with self set
+  # to an {AppProxy}, and also gets the proxy as an argument. Bluepill then
+  # loads the application, which starts its daemon.
+  #
+  # @example
+  #   Bluepill.application(:my_app, log_file: '/var/log/bluepill.log') do |app|
+  #     app.process('web') do |process|
+  #       process.start_command = '/usr/bin/my_server'
+  #       process.pid_file = '/var/run/my_server.pid'
+  #     end
+  #   end
+  #
+  # @param [#to_s] app_name the application's name
+  # @param [Hash{Symbol => Object}] options the application's options, such
+  #   as :log_file, :foreground and :base_dir
+  #
+  # @yield [app] describes the application's processes
+  # @yieldparam [AppProxy] app the application's proxy, which is also self
+  # @yieldreturn [void]
+  #
+  # @return [void]
+  #
+  # @api public
   def self.application(app_name, options = {}, &block)
     app_proxy = AppProxy.new(app_name, options)
-    if block.arity == 0
-      app_proxy.instance_eval(&block)
-    else
-      app_proxy.instance_exec(app_proxy, &block)
-    end
+    # instance_eval also passes the proxy to a block that takes an argument
+    app_proxy.instance_eval(&block)
     app_proxy.app.load
   end
 end

data/lib/bluepill/group.rb

@@ -1,30 +1,149 @@
 module Bluepill
+  # The processes of an application that share a group name
+  #
+  # A config puts a process in a group with `process.group = "name"`.
+  # Processes without one are in the application's nameless group. A
+  # command such as `bluepill restart name` acts on every process in the
+  # group.
+  #
+  # @api private
   class Group
-    attr_accessor :name, :processes, :logger
+    # Return the group's name
+    #
+    # @return [String, nil] the name, or nil for the application's nameless
+    #   group
+    #
+    # @api private
+    attr_accessor :name
+
+    # Return the group's processes
+    #
+    # @return [Array<Process>] the processes
+    #
+    # @api private
+    attr_accessor :processes
+
+    # Return the group's logger, which its processes' loggers prefix
+    #
+    # @return [Logger] the logger
+    #
+    # @api private
+    attr_accessor :logger
+
+    # Return a logger for processes, which bluepill doesn't use
+    #
+    # @return [Object] whatever was set
+    #
+    # @api private
     attr_accessor :process_logger
 
+    # Create an empty group
+    #
+    # @param [String, nil] name the group's name, or nil for the nameless
+    #   group
+    # @param [Hash{Symbol => Object}] options the group's options, with
+    #   :logger
+    #
+    # @return [void]
+    #
+    # @api private
     def initialize(name, options = {})
       self.name = name
       self.processes = []
-      self.logger = options[:logger]
+      logger = options[:logger] #: Logger
+      self.logger = logger
     end
 
+    # Add a process, giving it a logger prefixed with its name
+    #
+    # @param [Process] process the process
+    #
+    # @return [Array<Process>] the group's processes
+    #
+    # @api private
     def add_process(process)
       process.logger = logger.prefix_with(process.name)
       processes << process
     end
 
+    # Tick every process in the group
+    #
+    # @return [void]
+    #
+    # @api private
     def tick
       processes.each(&:tick)
     end
 
+    # Set each process's state from whether it's running
+    #
+    # Bluepill does this once, when it loads the config.
+    #
+    # @return [void]
+    #
+    # @api private
     def determine_initial_state
       processes.each(&:determine_initial_state)
     end
 
-    # proxied events
+    # @!method start(process_name = nil)
+    #   Start the group's processes, or one of them
+    #
+    #   Each process runs the command on a thread of its own. Unless it's
+    #   set to run it without blocking (group_start_noblock), the group
+    #   waits for it before going on to the next process.
+    #
+    #   @param [String, nil] process_name the process to start, or nil for
+    #     every process in the group
+    #
+    #   @return [Array<String>] the processes it started, as group:process
+    #
+    #   @api private
+    #
+    # @!method unmonitor(process_name = nil)
+    #   Stop monitoring the group's processes, or one of them
+    #
+    #   Each process runs the command on a thread of its own. Unless it's
+    #   set to run it without blocking (group_unmonitor_noblock), the group
+    #   waits for it before going on to the next process.
+    #
+    #   @param [String, nil] process_name the process to unmonitor, or nil
+    #     for every process in the group
+    #
+    #   @return [Array<String>] the processes it unmonitored, as
+    #     group:process
+    #
+    #   @api private
+    #
+    # @!method stop(process_name = nil)
+    #   Stop the group's processes, or one of them
+    #
+    #   Each process runs the command on a thread of its own. Unless it's
+    #   set to run it without blocking (group_stop_noblock), the group waits
+    #   for it before going on to the next process.
+    #
+    #   @param [String, nil] process_name the process to stop, or nil for
+    #     every process in the group
+    #
+    #   @return [Array<String>] the processes it stopped, as group:process
+    #
+    #   @api private
+    #
+    # @!method restart(process_name = nil)
+    #   Restart the group's processes, or one of them
+    #
+    #   Each process runs the command on a thread of its own. Unless it's
+    #   set to run it without blocking (group_restart_noblock), the group
+    #   waits for it before going on to the next process.
+    #
+    #   @param [String, nil] process_name the process to restart, or nil for
+    #     every process in the group
+    #
+    #   @return [Array<String>] the processes it restarted, as group:process
+    #
+    #   @api private
     [:start, :unmonitor, :stop, :restart].each do |event|
-      class_eval <<-END
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{event}(process_name = nil)
           threads = []
           affected = []
@@ -44,18 +163,31 @@ module Bluepill
           threads.each { |t| t.join } unless threads.nil?
           affected
         end
-      END
+      RUBY
     end
 
+    # Return the status lines that bluepill status shows
+    #
+    # Without a process name, it's a line for each process (and each of its
+    # children, for one with monitor_children), under the group's name. For
+    # one process, it's its line and its event history.
+    #
+    # @param [String, nil] process_name the process to show, or nil for
+    #   every process in the group
+    #
+    # @return [Array<String>] the lines, ending with an empty one
+    #
+    # @api private
     def status(process_name = nil)
-      lines = []
+      lines = [] #: Array[String]
       if process_name.nil?
-        prefix = name ? '  ' : ''
+        prefix = ('  ' if name)
         lines << "#{name}:" if name
 
         processes.each do |process|
           lines << format('%s%s(pid:%s): %s', prefix, process.name, process.actual_pid, process.state)
           next unless process.monitor_children?
+
           process.children.each do |child|
             lines << format('  %s%s: %s', prefix, child.name, child.state)
           end
@@ -63,8 +195,9 @@ module Bluepill
 
       else
         processes.each do |process|
-          next if process_name != process.name
-          lines << format('%s%s(pid:%s): %s', prefix, process.name, process.actual_pid, process.state)
+          next unless process_name.eql?(process.name)
+
+          lines << format('%s(pid:%s): %s', process.name, process.actual_pid, process.state)
           lines << process.statistics.to_s
         end
       end

data/lib/bluepill/logger.rb

@@ -1,7 +1,27 @@
 module Bluepill
+  # Write bluepill's log, to syslog or a file, with prefixes
+  #
+  # A logger made with prefix_with writes through its parent, which adds
+  # its own prefix, so a process's messages are tagged with its app's name
+  # and its own, as in "[app:web] Going from up => down".
+  #
+  # @api private
   class Logger
+    # The syslog priorities, each a method that logs a message
+    #
+    # @api private
     LOG_METHODS = [:emerg, :alert, :crit, :err, :warning, :notice, :info, :debug].freeze
 
+    # Make a logger
+    #
+    # @param [Hash{Symbol => Object}] options :logger, a parent logger to
+    #   write through, :prefix, :stdout to echo messages there too,
+    #   :log_file to write to instead of syslog, and :identity, the name
+    #   syslog shows
+    #
+    # @return [void]
+    #
+    # @api private
     def initialize(options = {})
       @options  = options
       @logger   = options[:logger] || create_logger
@@ -10,8 +30,56 @@ module Bluepill
       @prefixes = {}
     end
 
+    # @!method emerg(msg, prefix = [])
+    #   Log a message at the emergency priority
+    #   @param [String] msg the message
+    #   @param [Array<String, nil>] prefix the prefixes of the loggers below
+    #   @return [void]
+    #   @api private
+    # @!method alert(msg, prefix = [])
+    #   Log a message at the alert priority
+    #   @param [String] msg the message
+    #   @param [Array<String, nil>] prefix the prefixes of the loggers below
+    #   @return [void]
+    #   @api private
+    # @!method crit(msg, prefix = [])
+    #   Log a message at the critical priority
+    #   @param [String] msg the message
+    #   @param [Array<String, nil>] prefix the prefixes of the loggers below
+    #   @return [void]
+    #   @api private
+    # @!method err(msg, prefix = [])
+    #   Log a message at the error priority
+    #   @param [String] msg the message
+    #   @param [Array<String, nil>] prefix the prefixes of the loggers below
+    #   @return [void]
+    #   @api private
+    # @!method warning(msg, prefix = [])
+    #   Log a message at the warning priority
+    #   @param [String] msg the message
+    #   @param [Array<String, nil>] prefix the prefixes of the loggers below
+    #   @return [void]
+    #   @api private
+    # @!method notice(msg, prefix = [])
+    #   Log a message at the notice priority
+    #   @param [String] msg the message
+    #   @param [Array<String, nil>] prefix the prefixes of the loggers below
+    #   @return [void]
+    #   @api private
+    # @!method info(msg, prefix = [])
+    #   Log a message at the info priority
+    #   @param [String] msg the message
+    #   @param [Array<String, nil>] prefix the prefixes of the loggers below
+    #   @return [void]
+    #   @api private
+    # @!method debug(msg, prefix = [])
+    #   Log a message at the debug priority
+    #   @param [String] msg the message
+    #   @param [Array<String, nil>] prefix the prefixes of the loggers below
+    #   @return [void]
+    #   @api private
     LOG_METHODS.each do |method|
-      class_eval <<-END
+      class_eval <<-RUBY, __FILE__, __LINE__ + 1
         def #{method}(msg, prefix = [])
           if @logger.is_a?(self.class)
             @logger.#{method}(msg, [@prefix] + prefix)
@@ -24,16 +92,31 @@ module Bluepill
             @logger.#{method}("\#{s_prefix}\#{msg}")
           end
         end
-      END
+      RUBY
     end
 
+    # Return a logger that adds a prefix to this one's messages
+    #
+    # It's made once for each prefix, and kept.
+    #
+    # @param [String] prefix the prefix, such as a process's name
+    #
+    # @return [Logger] the prefixed logger
+    #
+    # @api private
     def prefix_with(prefix)
       @prefixes[prefix] ||= self.class.new(logger: self, prefix: prefix)
     end
 
+    # Open the log file or syslog again, such as after log rotation
+    #
+    # @return [void]
+    #
+    # @api private
     def reopen
-      if @logger.is_a?(self.class)
-        @logger.reopen
+      logger = @logger
+      if logger.instance_of?(self.class)
+        logger.reopen
       else
         @logger = create_logger
       end
@@ -41,21 +124,53 @@ module Bluepill
 
   protected
 
+    # Open the log file, or syslog if there isn't one
+    #
+    # @return [LoggerAdapter, Syslog] where the messages go
+    #
+    # @api private
     def create_logger
       if @options[:log_file]
-        LoggerAdapter.new(@options[:log_file])
+        LoggerAdapter.new(@options.fetch(:log_file))
       else
+        require_syslog
         Syslog.close if Syslog.opened? # need to explictly close it before reopening it
         Syslog.open(@options[:identity] || 'bluepilld', Syslog::LOG_PID, Syslog::LOG_LOCAL6)
       end
     end
 
+    # Load syslog, which is only loaded when it's used
+    #
+    # Ruby 3.4 and newer don't include it by default, so apps that log to a
+    # file don't need it in their Gemfile.
+    #
+    # @return [void]
+    #
+    # @raise [LoadError] with how to fix it, if syslog can't be loaded
+    #
+    # @api private
+    def require_syslog
+      require 'syslog'
+    rescue LoadError
+      message = 'Bluepill logs to syslog unless log_file is set, but the syslog library ' \
+                "could not be loaded. Since Ruby 3.4 it's a separate gem, so add gem 'syslog' " \
+                'to your Gemfile or set log_file.'
+      raise LoadError, message
+    end
+
+    # A ::Logger that also answers to the syslog priorities' names
+    #
+    # @api private
     class LoggerAdapter < ::Logger
+      # The ::Logger method for each syslog priority
+      #
+      # @api private
       LOGGER_EQUIVALENTS =
         {debug: :debug, err: :error, warning: :warn, info: :info, emerg: :fatal, alert: :warn, crit: :fatal, notice: :info}.freeze
 
       LOG_METHODS.each do |method|
         next if method == LOGGER_EQUIVALENTS[method]
+
         alias_method method, LOGGER_EQUIVALENTS[method]
       end
     end