bluepill 0.1.2 → 0.1.4

data/lib/bluepill/triggers/flapping.rb

@@ -1,13 +1,69 @@
 module Bluepill
+  # The triggers a process can have
+  #
+  # @api private
   module Triggers
+    # Stops a process that keeps restarting, and retries it later
+    #
+    # A config names it `checks :flapping`, with times: how many starts or
+    # restarts count as flapping (5 by default), within: the seconds they
+    # must happen in (1 by default), and retry_in: the seconds to wait before
+    # starting the process again (5 by default, and 0 never to retry). When
+    # the process flaps, the trigger unmonitors it, and starts it again
+    # after retry_in.
+    #
+    # @example
+    #   process.checks :flapping, times: 2, within: 30.seconds, retry_in: 7.seconds
+    #
+    # @api private
     class Flapping < Bluepill::Trigger
-      TRIGGER_STATES = [:starting, :restarting]
+      # The states that a start or a restart moves the process to
+      #
+      # @api private
+      TRIGGER_STATES = [:starting, :restarting].freeze
 
-      PARAMS = [:times, :within, :retry_in]
+      # The options the trigger takes
+      #
+      # @api private
+      PARAMS = [:times, :within, :retry_in].freeze
 
-      attr_accessor(*PARAMS)
+      # Return how many starts or restarts count as flapping
+      #
+      # @return [Integer] the number of transitions
+      #
+      # @api private
+      attr_accessor :times
+
+      # Return the seconds the starts or restarts must happen in to flap
+      #
+      # @return [Integer] the seconds
+      #
+      # @api private
+      attr_accessor :within
+
+      # Return the seconds to wait before starting a flapping process again
+      #
+      # @return [Integer] the seconds, or 0 never to start it again
+      #
+      # @api private
+      attr_accessor :retry_in
+
+      # Return when the last starts and restarts happened
+      #
+      # @return [Util::RotationalArray<Integer>] their times, in seconds
+      #
+      # @api private
       attr_reader :timeline
 
+      # Create the trigger for a process
+      #
+      # @param [Process] process the process to watch
+      # @param [Hash{Symbol => Object}] options the trigger's options, with
+      #   :times, :within, :retry_in and :logger
+      #
+      # @return [void]
+      #
+      # @api private
       def initialize(process, options = {})
         options.reverse_merge!(times: 5, within: 1, retry_in: 5)
 
@@ -19,20 +75,45 @@ module Bluepill
         super
       end
 
+      # Record a start or a restart, and check whether the process flaps
+      #
+      # @param [StateMachine::Transition] transition the transition, which
+      #   the trigger records if it's to starting or restarting
+      #
+      # @return [void]
+      #
+      # @api private
       def notify(transition)
         return unless TRIGGER_STATES.include?(transition.to_name)
-        timeline << Time.now.to_i
+
+        timeline << Integer(Time.now)
         check_flapping
       end
 
+      # Forget the recorded starts and cancel the scheduled events
+      #
+      # @return [void]
+      #
+      # @api private
       def reset!
         @timeline.clear
         super
       end
 
+      # Unmonitor the process and schedule its retry, if it's flapping
+      #
+      # It flaps when the last times starts or restarts happened within
+      # within seconds.
+      #
+      # @return [void]
+      #
+      # @raise [UncaughtThrowError] :halt, which state_machine catches to stop
+      #   the transition that flapped
+      #
+      # @api private
       def check_flapping
         # The process has not flapped if we haven't encountered enough incidents
-        return unless @timeline.compact.length == times
+        return unless @timeline.length == times
 
         # Check if the incident happend within the timeframe
         return unless @timeline.last - @timeline.first <= within

data/lib/bluepill/util/rotational_array.rb

@@ -1,19 +1,42 @@
 module Bluepill
+  # Small helpers for the rest of bluepill
+  #
+  # @api private
   module Util
+    # An array that drops its oldest element when it grows past its capacity
+    #
+    # Watches keep their last few values in one, and processes their last
+    # few events.
+    #
+    # @api private
     class RotationalArray < Array
+      # Create an empty array that holds at most size elements
+      #
+      # @param [Integer] size the most elements it holds
+      #
+      # @return [void]
+      #
+      # @api private
       def initialize(size)
         @capacity = size
 
         super() # no size - intentionally
       end
 
+      # Add an element, dropping the oldest one when it's full
+      #
+      # @param [Object] value the element to add
+      #
+      # @return [RotationalArray] self
+      #
+      # @api private
       def push(value)
-        super(value)
+        super
 
         shift if length > @capacity
         self
       end
-      alias_method :<<, :push
+      alias << push
     end
   end
 end

data/lib/bluepill/version.rb

@@ -1,29 +1,67 @@
 module Bluepill
+  # The version of bluepill
+  #
+  # @example
+  #   Bluepill::Version.to_s # => "0.1.4"
+  #
+  # @api public
   module Version
-  module_function
-
-    # @return [Integer]
-    def major
+    # Return the major version
+    #
+    # @example
+    #   Bluepill::Version.major # => 0
+    #
+    # @return [Integer] the major version
+    #
+    # @api public
+    def self.major
       0
     end
 
-    # @return [Integer]
-    def minor
+    # Return the minor version
+    #
+    # @example
+    #   Bluepill::Version.minor # => 1
+    #
+    # @return [Integer] the minor version
+    #
+    # @api public
+    def self.minor
       1
     end
 
-    # @return [Integer]
-    def patch
-      2
+    # Return the patch version
+    #
+    # @example
+    #   Bluepill::Version.patch # => 4
+    #
+    # @return [Integer] the patch version
+    #
+    # @api public
+    def self.patch
+      4
     end
 
-    # @return [Integer, NilClass]
-    def pre
-      nil
-    end
+    # Return the pre-release version
+    #
+    # @example
+    #   Bluepill::Version.pre # => nil
+    #
+    # @return [Integer, nil] the pre-release version, or nil for a release
+    #
+    # @api public
+    def self.pre; end
 
-    # @return [Hash]
-    def to_h
+    # Return the version's parts by name
+    #
+    # @example
+    #   Bluepill::Version.to_h # => {major: 0, minor: 1, patch: 4, pre: nil}
+    #
+    # @return [Hash{Symbol => Integer, nil}] the major, minor, patch and
+    #   pre-release versions
+    #
+    # @api public
+    def self.to_h
       {
         major: major,
         minor: minor,
@@ -32,13 +70,27 @@ module Bluepill
       }
     end
 
-    # @return [Array]
-    def to_a
+    # Return the version's parts, without a missing pre-release version
+    #
+    # @example
+    #   Bluepill::Version.to_a # => [0, 1, 4]
+    #
+    # @return [Array<Integer>] the parts of the version
+    #
+    # @api public
+    def self.to_a
       to_h.values.compact
     end
 
-    # @return [String]
-    def to_s
+    # Return the version as a string
+    #
+    # @example
+    #   Bluepill::Version.to_s # => "0.1.4"
+    #
+    # @return [String] the version, such as "0.1.4"
+    #
+    # @api public
+    def self.to_s
       to_a.join('.')
     end
   end

data/lib/bluepill.rb

@@ -1,10 +1,33 @@
 require 'rubygems'
 
-require 'bundler/setup' if ENV['BUNDLE_GEMFILE'] && File.exist?(ENV['BUNDLE_GEMFILE'])
+# A process monitor that keeps daemons running
+#
+# A config file calls {Bluepill.application} to describe an application's
+# processes, and the bluepill daemon monitors and restarts them.
+#
+# @api public
+module Bluepill
+  # Set up Bundler when bluepill runs with a Gemfile
+  #
+  # Bluepill calls this once, when it's loaded, so that it runs with the
+  # app's bundle, such as under bundle exec.
+  #
+  # @param [String, nil] gemfile the path of the Gemfile, BUNDLE_GEMFILE by
+  #   default
+  #
+  # @return [Boolean, nil] what requiring bundler/setup returned, or nil
+  #   when there's no Gemfile
+  #
+  # @api private
+  def self.setup_bundler(gemfile = ENV['BUNDLE_GEMFILE'])
+    require 'bundler/setup' if gemfile && File.exist?(gemfile)
+  end
+end
+
+Bluepill.setup_bundler
 
 require 'thread'
 require 'monitor'
-require 'syslog'
 require 'timeout'
 require 'logger'