cognizant 0.0.1

data/lib/cognizant/process/actions/start.rb

@@ -0,0 +1,70 @@
+module Cognizant
+  class Process
+    module Actions
+      module Start
+        # Environment variables for process during start.
+        # @return [Hash] Defaults to {}
+        attr_accessor :start_env
+
+        # The command to run before the process is started. The exit status
+        # of this command determines whether or not to proceed.
+        # @return [String] Defaults to nil
+        attr_accessor :start_before_command
+
+        # The command to start the process with.
+        # e.g. "/usr/bin/redis-server"
+        # @return [String] Defaults to nil
+        attr_accessor :start_command
+
+        # Start the process with this in it's STDIN.
+        # e.g. "daemonize no"
+        # @return [String] Defaults to nil
+        attr_accessor :start_with_input
+
+        # Start the process with this file's data in it's STDIN.
+        # e.g. "/etc/redis/redis.conf"
+        # @return [String] Defaults to nil
+        attr_accessor :start_with_input_file
+
+        # Start the process with this command's output in it's (process') STDIN.
+        # e.g. "cat /etc/redis/redis.conf"
+        # @return [String] Defaults to nil
+        attr_accessor :start_with_input_command
+
+        # The grace time period in seconds for the process to start within.
+        # Covers the time period for the input and start command. After the
+        # timeout is over, the process the considered not started and it
+        # re-enters the auto start lifecycle based on conditions.
+        # @return [String] Defaults to 10
+        attr_accessor :start_timeout
+
+        # The command to run after the process is started.
+        # @return [String] Defaults to nil
+        attr_accessor :start_after_command
+
+        def start_process
+          result_handler = Proc.new do |result|
+            if result.respond_to?(:succeeded?) and result.succeeded?
+              write_pid(result.pid) if result.pid != 0
+            end
+          end
+          execute_action(
+            result_handler,
+            name:          self.name,
+            daemonize:     self.daemonize || true,
+            env:           (self.env || {}).merge(self.start_env || {}),
+            logfile:       self.logfile,
+            errfile:       self.errfile,
+            before:        self.start_before_command,
+            command:       self.start_command,
+            input:         self.start_with_input,
+            input_file:    self.start_with_input_file,
+            input_command: self.start_with_input_command,
+            after:         self.start_after_command,
+            timeout:       self.start_timeout
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cognizant/process/actions/stop.rb

@@ -0,0 +1,59 @@
+module Cognizant
+  class Process
+    module Actions
+      module Stop
+        # Environment variables for process during stop.
+        # @return [Hash] Defaults to {}
+        attr_accessor :stop_env
+
+        # The command to run before the process is stopped. The exit status
+        # of this command determines whether or not to proceed.
+        # @return [String] Defaults to nil
+        attr_accessor :stop_before_command
+
+        # The command to stop the process with.
+        # e.g. "/usr/bin/redis-server"
+        # @return [String] Defaults to nil
+        attr_accessor :stop_command
+
+        # The signals to pass to the process one by one attempting to stop it.
+        # Each signal is passed within the timeout period over equally
+        # distributed intervals (min. 2 seconds). Override with signals without
+        # "KILL" to never force kill the process.
+        # e.g. ["TERM", "INT"]
+        # @return [Array] Defaults to ["TERM", "INT", "KILL"]
+        attr_accessor :stop_signals
+
+        # The grace time period in seconds for the process to stop within.
+        # Covers the time period for the stop command or signals. After the
+        # timeout is over, the process is checked for running status and if
+        # not stopped, it re-enters the auto start lifecycle based on
+        # conditions.
+        # @return [String] Defaults to 10
+        attr_accessor :stop_timeout
+
+        # The command to run after the process is stopped.
+        # @return [String] Defaults to nil
+        attr_accessor :stop_after_command
+
+        def stop_process
+          result_handler = Proc.new do |result|
+            # If it is a boolean and value is true OR if it's an execution result and it succeeded.
+            if (!!result == result and result) or (result.respond_to?(:succeeded?) and result.succeeded?)
+              unlink_pid unless pid_running?
+            end
+          end
+          execute_action(
+            result_handler,
+            env:     (self.env || {}).merge(self.stop_env || {}),
+            before:  self.stop_before_command,
+            command: self.stop_command,
+            signals: self.stop_signals,
+            after:   self.stop_after_command,
+            timeout: self.stop_timeout
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cognizant/process/actions.rb

@@ -0,0 +1,96 @@
+require "cognizant/process/actions/start"
+require "cognizant/process/actions/stop"
+require "cognizant/process/actions/restart"
+
+module Cognizant
+  class Process
+    module Actions
+      include Cognizant::Process::Actions::Start
+      include Cognizant::Process::Actions::Stop
+      include Cognizant::Process::Actions::Restart
+
+      private
+
+      def execute_action(result_handler, options)
+        before_command = options[:before]
+        command        = options[:command]
+        after_command  = options[:after]
+        signals        = options[:signals]
+        timeout        = options[:timeout] || 10
+
+        # TODO: Works well but can some refactoring make it more declarative?
+        @action_thread = Thread.new do
+          result = false
+          queue = Queue.new
+          thread = Thread.new do
+            if before_command and not success = run(before_command).succeeded?
+              queue.push(success)
+              Thread.exit
+            end
+
+            if (command and success = run(command, options) and success.succeeded?)
+              run(after_command) if after_command
+              queue.push(success)
+              Thread.exit
+            end
+
+            # If the caller has attempted to set signals, then it can handle it's result.
+            if success = send_signals(signals: signals, timeout: timeout)
+              run(after_command) if after_command
+              queue.push(success)
+              Thread.exit
+            end
+
+            queue.push(false)
+            Thread.exit
+          end
+
+          timeout_left = timeout + 1
+          while (timeout_left -= 1) > 0 do
+            # If there is something in the queue, we have the required result.
+            if result = queue.pop
+              # Rollback the pending skips, since we finished before timeout.
+              skip_ticks_for(-timeout_left)
+              break
+            end
+            sleep 1
+          end
+        
+          # Kill the nested thread.
+          thread.kill
+
+          # Action callback.
+          result_handler.call(result) if result_handler.respond_to?(:call)
+
+          # Kill self.
+          Thread.kill
+        end
+
+        # We skip so that we're not reinformed about the required transition by the tick.
+        skip_ticks_for(timeout)
+      end
+
+      def send_signals(options = {})
+        # Return if the process is already stopped.
+        return true unless pid_running?
+
+        signals = options[:signals] || ["TERM", "INT", "KILL"]
+        timeout = options[:timeout] || 10
+
+        catch :stopped do
+          signals.each do |stop_signal|
+            # Send the stop signal and wait for it to stop.
+            signal(stop_signal, @process_pid)
+
+            # Poll to see if it's stopped yet. Minimum 2 so that we check at least once again.
+            ([timeout / signals.size, 2].max).times do
+              throw :stopped unless pid_running?
+              sleep 1
+            end
+          end
+        end
+        not pid_running?
+      end
+    end
+  end
+end

data/lib/cognizant/process/attributes.rb

@@ -0,0 +1,81 @@
+module Cognizant
+  class Process
+    module Attributes
+      # Unique name for the process.
+      # @return [String]
+      attr_accessor :name
+
+      # Group classification for the process.
+      # @return [String] Defaults to nil
+      attr_accessor :group
+
+      # Whether or not to daemonize the process. It is recommended that
+      # cognizant managed your process completely by process not
+      # daemonizing itself. Find a non-daemonizing option in your process'
+      # documentation.
+      # @return [true, false] Defaults to true
+      attr_accessor :daemonize
+
+      # Whether or not to auto start the process on initial run. Afterwards,
+      # this attribute is overwritten by stop or restart request.
+      # @return [true, false] Defaults to true
+      attr_accessor :autostart
+
+      # The pid lock file for the process. Required when daemonize is set to
+      # false.
+      # @return [String] Defaults to value of pids_dir/name.pid
+      attr_accessor :pidfile
+
+      # The file to log the process' STDOUT stream into.
+      # @return [String] Defaults to value of logs_dir/name.log
+      attr_accessor :logfile
+
+      # The file to log the daemon's STDERR stream into.
+      # @return [String] Defaults to value of logfile
+      attr_accessor :errfile
+
+      # Environment variables for process.
+      # @return [Hash] Defaults to {}
+      attr_accessor :env
+
+      # The chroot directory to change the process' idea of the file system
+      # root.
+      # @return [String] Defaults to nil
+      attr_accessor :chroot
+
+      # The current working directory for the process to start with.
+      # @return [String] Defaults to nil
+      attr_accessor :chdir
+
+      # Limit the permission modes for files and directories created by the
+      # process.
+      # @return [Integer] Defaults to nil
+      attr_accessor :umask
+
+      # Run the process as the given user.
+      # e.g. "deploy", 1000
+      # @return [String] Defaults to nil
+      attr_accessor :uid
+
+      # Run the process as the given user group.
+      # e.g. "deploy"
+      # @return [String] Defaults to nil
+      attr_accessor :gid
+
+      # Supplementary user groups for the process.
+      # e.g. ["staff"]
+      # @return [Array] Defaults to []
+      attr_accessor :groups
+
+      # The command to check the running status of the process with. The exit
+      # status of the command is used to determine the status.
+      # e.g. "/usr/bin/redis-cli PING"
+      # @return [String] Defaults to nil
+      attr_accessor :ping_command
+
+      # The command that returns the pid of the process.
+      # @return [String] Defaults to nil
+      attr_accessor :pid_command
+    end
+  end
+end

data/lib/cognizant/process/execution.rb

@@ -0,0 +1,176 @@
+module Cognizant
+  class Process
+    module Execution
+      ExecutionResult = Struct.new(
+        :pid,
+        :stdout,
+        :stderr,
+        :exit_code,
+        :succeeded
+      ) do alias succeeded? succeeded end
+
+      def execute(command, options = {})
+        options[:groups] ||= []
+        options[:env]    ||= {}
+
+        pid, pid_w = IO.pipe
+
+        unless options[:daemonize]
+          # Stdout and stderr file descriptors.
+          out_r, out_w = IO.pipe
+          err_r, err_w = IO.pipe
+        end
+
+        # Run the following in a fork so that the privilege changes do not affect the parent process.
+        fork_pid = ::Process.fork do
+          # Set the user and groups for the process in context.
+          drop_privileges(options)
+
+          if options[:daemonize]
+            # Create a new session to detach from the controlling terminal.
+            unless ::Process.setsid
+              # raise Koth::RuntimeException.new('cannot detach from controlling terminal')
+            end
+
+            # TODO: Set pgroup: true so that the spawned process is the group leader, and it's death would kill all children as well.
+
+            # Prevent inheriting signals from parent process.
+            Signal.trap('TERM', 'SIG_DFL')
+            Signal.trap('INT',  'SIG_DFL')
+            Signal.trap('HUP',  'SIG_DFL')
+
+            # Give the process a name.
+            $0 = options[:name] if options[:name]
+
+            # Collect logs only when daemonizing.
+            stdout = [options[:logfile] || "/dev/null", "a"]
+            stderr = [options[:errfile] || options[:logfile] || "/dev/null", "a"]
+          else
+            stdout = out_w
+            stderr = err_w
+          end
+
+          # TODO: Run popen as spawned process before privileges are dropped for increased abilities?
+          stdin_data = options[:input] if options[:input]
+          stdin_data = IO.popen(options[:input_command]).gets if options[:input_command]
+
+          if stdin_data
+            stdin, stdin_w = IO.pipe
+            stdin_w.write stdin_data
+            stdin_w.close # stdin is closed by ::Process.spawn.
+          elsif options[:input_file] and File.exists?(options[:input_file])
+            stdin = options[:input_file]
+          else
+            stdin = "/dev/null"
+          end
+
+          # Merge spawn options.
+        	spawn_options = construct_spawn_options(options, {
+        		:in  => stdin,
+        		:out => stdout,
+        		:err => stderr
+        	})
+
+          # Spawn a process to execute the command.
+          process_pid = ::Process.spawn(options[:env], command, spawn_options)
+          # puts "process_pid: #{process_pid} (#{command})"
+          pid_w.write(process_pid)
+
+          if options[:daemonize]
+            # We do not care about actual status or output when daemonizing.
+            exit(0)
+          else
+            # TODO: Timeout here, in case the process doesn't daemonize itself.
+
+            # Wait (blocking) until the command has finished running.
+            status = ::Process.waitpid2(process_pid)[1]
+
+            # Pass on the exit status to the parent.
+            exit(status.exitstatus || 0) # TODO: This 0 or something else should be controlled by timeout handler.
+          end
+        end
+
+        # Close the pid file descriptor.
+        pid_w.close
+
+        if options[:daemonize]
+          # Detach (non blocking) the process executing the command and move on.
+          ::Process.detach(fork_pid)
+
+          return ExecutionResult.new(
+            pid.read.to_i,
+            nil,
+            nil,
+            0,
+            true
+          )
+        else
+          # Wait until the fork has finished running and accept the exit status.
+          status = ::Process.waitpid2(fork_pid)[1]
+
+          # Timeout and try (detach + pid_running?)?
+
+          # Close the file descriptors.
+          out_w.close
+          err_w.close
+
+          # Collect and return stdout, stderr and exitcode.
+          return ExecutionResult.new(
+            pid.read.to_i,
+            out_r.read,
+            err_r.read,
+            status.exitstatus,
+            status.exitstatus.zero?
+          )
+        end
+      end
+
+      private
+
+      def drop_privileges(options = {})
+        # Cannot drop privileges unless we are superuser.
+        if ::Process.euid == 0
+          # Drop ~= decrease, since we can only decrease privileges.
+
+          # For clarity.
+          uid    = options[:uid]
+          gid    = options[:gid]
+          groups = options[:groups]
+
+          # Find the user and primary group in the password and group database.
+          user  = (uid.is_a? Integer) ? Etc.getpwuid(uid) : Etc.getpwnam(uid) if uid
+          group = (gid.is_a? Integer) ? Etc.getgruid(gid) : Etc.getgrnam(gid) if gid
+
+          # Collect the secondary groups' GIDs.
+          group_ids = groups.map { |g| Etc.getgrnam(g).gid } if groups
+
+          # Set the fork's secondary user groups for the spawn process to inherit.
+          ::Process.groups = [group.gid] if group # Including the primary group.
+          ::Process.groups |= group_ids if groups and !group_ids.empty?
+
+          # Set the fork's user and primary group for the spawn process to inherit.
+          ::Process.uid = user.uid  if user
+          ::Process.gid = group.gid if group
+
+          # Find and set the user's HOME environment variable for fun.
+          options[:env] = options[:env].merge({ 'HOME' => user.dir }) if user and user.dir
+
+          # Changes the process' idea of the file system root.
+          Dir.chroot(options[:chroot]) if options[:chroot]
+
+          # umask and chdir drops are managed by ::Process.spawn.
+        end
+      end
+
+      private
+
+      def construct_spawn_options(options, overrides = {})
+        spawn_options = {}
+        [:chdir, :umask].each do |o|
+          spawn_options[o] = options[o] if options[o]
+        end
+        spawn_options.merge(overrides)
+      end
+    end
+  end
+end

data/lib/cognizant/process/pid.rb

@@ -0,0 +1,28 @@
+module Cognizant
+  class Process
+    module PID
+      def read_pid
+        if self.pid_command
+          str = execute(self.pid_command).stdout.to_i
+          @process_pid = str unless not str or str.zero? # TODO: Also check if the pid is alive.
+        elsif self.pidfile and File.exists?(self.pidfile)
+          str = File.read(self.pidfile).to_i
+          @process_pid = str unless not str or str.zero? # TODO: Also check if the pid is alive.
+        end
+        @process_pid
+      end
+
+      def write_pid(pid = nil)
+        @process_pid = pid if pid
+        File.open(self.pidfile, "w") { |f| f.write(@process_pid) } if self.pidfile and @process_pid
+      end
+
+      def unlink_pid
+        File.unlink(self.pidfile) if self.pidfile
+      rescue Errno::ENOENT
+        # It got deleted before we could. Perhaps it was a process managed pidfile.
+        true
+      end
+    end
+  end
+end

data/lib/cognizant/process/status.rb

@@ -0,0 +1,27 @@
+module Cognizant
+  class Process
+    module Status
+      def pid_running?
+        pid = read_pid
+        return false unless pid and pid != 0
+        signal(0, pid)
+        # It's running since no exception was raised.
+        true
+      rescue Errno::ESRCH
+        # No such process.
+        false
+      rescue Errno::EPERM
+        # Probably running, but we're not allowed to pass signals.
+        # TODO: Is this a sign of problems ahead?
+        true
+      else
+        # Possibly running.
+        true
+      end
+
+      def signal(signal, pid = nil)
+        ::Process.kill(signal, (pid || read_pid))
+      end
+    end
+  end
+end

data/lib/cognizant/process.rb

@@ -0,0 +1,149 @@
+require 'state_machine'
+
+require "cognizant/process/pid"
+require "cognizant/process/status"
+require "cognizant/process/execution"
+require "cognizant/process/attributes"
+require "cognizant/process/actions"
+
+module Cognizant
+  class Process
+    include Cognizant::Process::PID
+    include Cognizant::Process::Status
+    include Cognizant::Process::Execution
+    include Cognizant::Process::Attributes
+    include Cognizant::Process::Actions
+
+    state_machine :initial => :unmonitored do
+      # These are the idle states, i.e. only an event (either external or internal) will trigger a transition.
+      # The distinction between stopped and unmonitored is that stopped
+      # means we know it is not running and unmonitored is that we don't care if it's running.
+      state :unmonitored, :running, :stopped
+
+      # These are transitionary states, we expect the process to change state after a certain period of time.
+      state :starting, :stopping, :restarting
+
+      event :tick do
+        transition :starting   => :running,   :if     => :process_running?
+        transition :starting   => :stopped,   :unless => :process_running?
+
+        transition :running    => :stopped,   :unless => :process_running?
+
+        # The process failed to die after entering the stopping state. Change the state to reflect reality.
+        transition :stopping   => :running,   :if     => :process_running?
+        transition :stopping   => :stopped,   :unless => :process_running?
+
+        transition :stopped    => :running,   :if     => :process_running?
+        transition :stopped    => :starting,  :if     => lambda { |p| p.autostart and not p.process_running? }
+
+        transition :restarting => :running,   :if     => :process_running?
+        transition :restarting => :stopped,   :unless => :process_running?
+      end
+
+      event :monitor do
+        transition :unmonitored => :stopped
+      end
+
+      event :start do
+        transition [:unmonitored, :stopped] => :starting
+      end
+
+      event :stop do
+        transition :running => :stopping
+      end
+
+      event :restart do
+        transition [:running, :stopped] => :restarting
+      end
+
+      event :unmonitor do
+        transition any => :unmonitored
+      end
+
+      after_transition  any      => :starting,   :do => :start_process
+      before_transition :running => :stopping,   :do => lambda { |p| p.autostart = false }
+      after_transition  any      => :stopping,   :do => :stop_process
+      before_transition any      => :restarting, :do => lambda { |p| p.autostart = true }
+      after_transition  any      => :restarting, :do => :restart_process
+
+      before_transition any => any, :do => :record_transition_start
+      after_transition  any => any, :do => :record_transition_end
+    end
+
+    def initialize(process_name = nil, options = {})
+      # Default.
+      self.autostart = true
+      self.name = process_name if process_name
+
+      options.each do |attribute_name, value|
+        self.send("#{attribute_name}=", value) if self.respond_to?("#{attribute_name}=")
+      end
+
+      @ticks_to_skip = 0
+
+      yield(self) if block_given?
+
+      # Let state_machine initialize as well.
+      super
+    end
+
+    def tick
+      return if skip_tick?
+      @action_thread.kill if @action_thread # TODO: Ensure if this is really needed.
+
+      # Invoke the state_machine event.
+      super
+    end
+
+    def record_transition_start
+      print "#{name}: changing state from `#{state}`"
+    end
+
+    def record_transition_end
+      puts " to `#{state}`"
+    end
+
+    def process_running?
+      @process_running = begin
+        # Do not assume change when we're giving time to an execution by skipping ticks.
+        if @ticks_to_skip > 0
+          @process_running
+        elsif self.ping_command and run(self.ping_command).succeeded?
+          true
+        elsif pid_running?
+          true
+        else
+          false
+        end
+      end
+    end
+
+    def pidfile
+      @pidfile = @pidfile || File.join(Cognizant::Server.daemon.pids_dir, self.name + '.pid')
+    end
+
+    def logfile
+      @logfile = @logfile || File.join(Cognizant::Server.daemon.logs_dir, self.name + '.log')
+    end
+
+    private
+
+    def skip_ticks_for(skips)
+      # Accept negative skips with the result being >= 0.
+      @ticks_to_skip = [@ticks_to_skip + (skips.to_i + 1), 0].max # +1 so that we don't have to >= and ensure 0 in "skip_tick?".
+    end
+
+    def skip_tick?
+      (@ticks_to_skip -= 1) > 0 if @ticks_to_skip > 0
+    end
+
+    def run(command, action_overrides = {})
+      options = { daemonize: false }
+      # Options from daemon config.
+      [:uid, :gid, :groups, :chroot, :chdir, :umask].each do |attribute|
+        options[attribute] = self.send(attribute)
+      end
+      execute(command, options.merge(action_overrides))
+    end
+  end
+end