svdir 0.2

data/CHANGELOG

@@ -0,0 +1,29 @@
+2011-02-28 mjp version 0.2
+  [doc] Documentation touch-up, move from Qualys SVN to github.
+
+2011-02-17 mjp
+  [api] Remove #epoch() method, #pid() now returns nil if service is not
+  running (formerly returned zero).
+  [int] Remove Forwardable delegation, refactor SvDir and StatusBytes
+  accordingly.  A skosh more efficient, but also puts method documentation
+  in the class that needs it.
+  [tst] Update tests for API changes, delegation refactoring and corrupt
+  status file handling.
+  [doc] update LICENSE, copyright notice, README
+  [pkg] remove Echoe dependency, generate gem with vanilla rake tasks
+  (Rakefile)
+
+2008-10-13 mjp
+  [api] make that ENXIO/EWHATEVER on non-running supervisor.  Raise
+  EPROTO specifically on truncated 'status' file.
+  [tst] Fixtures::TempSvDir makes bona fide FIFOs, correctly makes
+  incremented tempdirs.  ts_control renamed ts_signal, also test non-
+  running supervisor (ts_nosupervisor).
+  [doc] note Errno:: conventions, use "supervisor" consistently.
+
+2008-10-10 mjp
+  [bug] qualify 'ok' FIFO path (cpforbes).
+  [api] raise EPROTO for non-running supervisor.
+
+2008-10-06 mjp
+  Initial check-in.

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2011 Qualys, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,67 @@
+Copyright (c) 2010, 2011 Qualys, Inc.
+
+Copyright (c) 2008 - 2010 Nemean Networks, LLC.
+
+= Overview
+
++svdir+ is a Ruby interface to the "service directory" style of robust daemon
+process supervision introducted in Dan Bernstein's +daemontools+ software and
+compatibly extended in Gerit Pape's +runit+ package.
+
+It exposes a programmatic interface to reliably starting, stopping, signalling
+and interrogating services all implemented directly -- no need to shell out to
+separate utilities.  See the documentation for Sys::Sv::SvDir for complete
+information.
+
+More information on +daemontools+ is available at
+http://cr.yp.to/daemontools.html.  More information on +runit+ is available at
+http://smarden.org/runit/.
+
+== Example
+
+The <tt>example/</tt> subdirectory in the source distribution contains a
+demonstration program which a system adminstrator might use to control daemons.
+
+Typical programmatic use of this software might look like this:
+
+    #! /usr/bin/env ruby
+
+    require 'sys/sv/svdir'
+    include Sys::Sv
+
+    # shut down all daemons running under /service
+    Dir["/service"].each do |svpath|
+      s = SvDir.new(svpath)
+
+      # force the .../log to shut down, ignoring services without loggers
+      s.log.signal(:exit) rescue nil
+
+      pid = s.pid
+      if pid != 0
+      	s.signal(:exit)
+        puts "Told #{s.path} (pid #{pid}) to exit"
+      end
+    end
+
+= Installation
+
+Look for the gem on http://rubygems.org.
+
+`rake package` will build a .gem under pkg/, and `rake rdoc` will
+generate module documentation.
+
+`rake test` and `rake rcov` will give a good idea of where the code is.
+
+= To Do
+
+* Further testing
+  - log()
+  - TAI64 testing
+
+* Possible extensions
+  - <tt>SvDir.new(d) &block</tt> - persist StatusBytes object for block?
+  - <tt>normally_down!</tt> and <tt>normally_up!</tt>
+
+= Author
+
+Mike Pomraning ("mpomraning" at "qualys" dot "com")

data/Rakefile

@@ -0,0 +1,66 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+
+FILES = FileList['Rakefile', 'CHANGELOG', 'LICENSE', 'README',
+                 'lib/**/*.rb', 'test/**/*', 'example/*'].to_a
+TESTS = FileList['test/ts_*.rb']
+
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.author = "Mike Pomraning"
+  s.summary = "An interface to service directories ala supervise/runsv"
+  s.name = 'svdir'
+  s.version = '0.2'
+  s.require_path = 'lib'
+  s.description = <<eodesc
+The svdir package controls service directories, a scheme for reliably
+controlling daemon processes as implemented in Dan Bernstein's daemontools
+software ("supervise") or Gerit Pape's runit software ("runsv").
+eodesc
+  s.files = FILES
+  s.test_files = TESTS
+  s.has_rdoc = true
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+    pkg.package_dir = 'pkg'
+    pkg.need_tar = true
+end
+
+desc "Generate rdoc"
+Rake::RDocTask.new("rdoc") do |rdoc|
+  rdoc.rdoc_dir = 'doc/rdoc'
+  rdoc.title    = "svdir"
+  # Show source inline with line numbers
+  rdoc.options << "--inline-source" << "--line-numbers"
+  # Make the readme file the start page for the generated html
+  rdoc.options << '--main' << 'README'
+  rdoc.rdoc_files.include('lib/**/*.rb',
+                          'CHANGELOG',
+                          'README',
+                          'LICENSE')
+end
+
+desc "Run included tests"
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = TESTS
+  t.libs << "lib"
+end
+
+desc "Run test coverage (rcov)"
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |t|
+    t.test_files = TESTS
+    t.libs << "test" << "lib"
+    t.rcov_opts << '--exclude /gems/,/Library/,/usr/,spec,lib/tasks'
+  end
+rescue LoadError
+  task :rcov do
+    puts "Error - you seem to be missing 'rcov'"
+    exit 1
+  end
+end

data/example/svctl

@@ -0,0 +1,117 @@
+#! /usr/bin/env ruby
+
+require 'sys/sv/svdir'
+include Sys::Sv
+
+USAGE = <<'__eousage'
+Usage:  svctl [cmd] service_dir [service_dir ...]
+        svctl [-h|--help]
+
+If 'cmd' is 'status', print a summary of the current state of each
+given service directory and its subordinate log directory, if any.
+
+Issue 'cmd' to the given service directories in turn.  Behavior
+varies with the command:
+
+  status ...... summarize status of service and log service, if any
+  up .......... start and, as needed, restart the service
+  down ........ TERM+CONT a running service, do not restart
+  exit ........ "down" a service, TERM its log service, then exit
+  once ........ start but do not restart the service
+
+Other values of 'cmd' instruct the supervisory process to send a
+UNIX signal to its service, if running:
+
+  pause, STOP, continue, CONT, hangup, HUP, alarm, ALRM, interrupt, INT,
+  terminate, TERM, kill, KILL, user1, USR1, user2, USR2
+
+Note that the 'user'/'USR' commands are extensions to the original
+process supervision implementation, and not supported by all supervisors.
+__eousage
+
+def usage_exit(errmsg = nil)
+  outio, rc = [$stdout, 0]
+
+  if errmsg
+    outio = $stderr
+    rc    = 1
+    outio.puts errmsg
+  end
+
+  outio.puts USAGE
+
+  exit(rc)
+end
+
+def formatted_status(sv, name = nil)
+  # sv(1)-inspired status
+  #
+  # For each SvDir argument, show:
+  #   current state:  running, paused ("running" but SIGSTOP'd), or down
+  #   service name:   supplied by caller
+  #   elapsed time:   time since begun running or since stopped
+  #   pid:            if applicable
+  #   typical state:  normally up/down? (only if different than current)
+  #   want up/down?:  if applicable
+  #   
+  name = File.basename(sv.path) unless name
+
+  runstate, elapsed, pid_str, unusual_state = [nil, nil, nil, nil]
+
+  if sv.up?
+    runstate      = sv.paused? ? "paused" : "run"
+    elapsed       = sv.uptime
+    pid_str       = "(pid #{sv.pid})"
+    unusual_state = "normally down" if sv.normally_down?  # Hmm!
+  else
+    runstate      = "down"
+    elapsed       = sv.downtime
+    unusual_state = "normally up" if sv.normally_up?      # Hmm!
+  end
+
+  elapsed = elapsed.round.to_s + 's'
+  want_state = sv.want_up?   ? "want up"   :
+               sv.want_down? ? "want down" :
+               ""
+
+  ["#{runstate}: #{name}:", pid_str, elapsed, unusual_state].compact.join(" ")
+rescue SystemCallError => e
+  "err: #{name}: No supervisor detected (#{e})"
+end
+
+def do_signal(sig, *dirs)
+  dirs.each do |dir|
+    begin
+      SvDir.new(dir).signal(sig)
+    rescue SystemCallError => e
+      $stderr.puts "error signalling #{dir}: #{e.message}"
+    end
+  end
+end
+
+def main
+  # A quick demonstration of Sys::Sv::SvDir ...
+  cmd = ARGV.shift
+
+  case cmd
+  when '--help', '-h', nil
+    usage_exit
+  when 'status'
+    ARGV.each do |dir|
+      sv = SvDir.new(dir)
+      sv_stat = formatted_status(sv, dir)
+      if log = sv.log
+        sv_stat += '; ' + formatted_status(log, 'log')
+      end
+      puts sv_stat
+    end
+  else
+    begin
+      do_signal(cmd, *ARGV)
+    rescue Exception => e
+      usage_exit("error: #{e.message}")
+    end
+  end
+end
+
+main if __FILE__ == $0

data/lib/sys/sv/statusbytes.rb

@@ -0,0 +1,53 @@
+#
+# Author::  Mike Pomraning
+# Copyright:: Copyright (c) 2011 Qualys, Inc.
+# License:: MIT (see the file LICENSE)
+# 
+
+module Sys # :nodoc:
+module Sv  # :nodoc:
+
+  # The StatusBytes class interprets state files maintained by a SvDir's
+  # _monitor_ process.  It should normally not be instantiated directly.
+  class StatusBytes # :nodoc:
+    BUFLEN    = 18                  # TODO - grok runit extended info (20 bytes)
+    TAI_EPOCH = 4611686018427387914 # time_t 0 on the TAI scale
+
+    attr_reader :pid, :pauseflag, :wantflag
+
+    def initialize(bytes) # :nodoc:
+      if bytes.size < BUFLEN
+        raise ::Errno::EPROTO.new("corrupt status buffer")
+      end
+
+      @bytes = bytes
+      @pid, @pauseflag, @wantflag = @bytes.unpack('x12 V c a')
+      @epoch = nil # computed if needed
+    end
+
+    # Number of seconds since service was most recently started or
+    # stopped.
+    def elapsed
+      ::Time.now.to_f - epoch()
+    end
+
+    # Returns the number of seconds since the UNIX epoch since the
+    # service was most recently started or stopped.
+    def epoch
+      return @epoch if @epoch
+
+      # assemble UNIX-scale seconds from TAI64N label
+      hi32, lo32, nano = @bytes.unpack('N N N')
+      @epoch = (hi32 << 32) + lo32 - TAI_EPOCH
+      if @epoch <= 0
+        @epoch = 0.0
+      else
+        @epoch += nano/10e9
+      end
+
+      @epoch
+    end
+  end
+
+end #-- module Sv
+end #-- module Sys

data/lib/sys/sv/svdir.rb

@@ -0,0 +1,224 @@
+#!/usr/bin/env ruby
+
+# Author::  Mike Pomraning
+# Copyright:: Copyright (c) 2011 Qualys, Inc.
+# License:: MIT (see the file LICENSE)
+#
+
+require 'sys/sv/statusbytes' # class StatusBytes
+require 'sys/sv/util'        # Util::open_write(), open_read()
+
+module Sys # :nodoc
+module Sv  # :nodoc:
+
+  # The SvDir class encapsulates service directories, a scheme for
+  # reliably controlling daemon processes (services) introduced in Dan
+  # Bernstein's +daemontools+ software.
+  #
+  # Each service is monitored by a _supervisor_, which is responsible
+  # for starting, stopping, restarting and generally controlling the
+  # service.  Examples of such supervisors include +supervise+ from
+  # the +daemontools+ package and +runsv+ from Gerit Pape's compatible
+  # +runit+ software.
+  #
+  # Most SvDir methods will raise <tt>Errno::</tt> exceptions (each
+  # a subclass of +SystemCallException+) if the underlying filesystem
+  # representation of the service directory is not as expected.  For
+  # example, +EACCESS+ or +ENOENT+ may be raised if the _supervisor_'s
+  # status directory or state files are missing or unreadable.  Additionally,
+  # +ENXIO+ is raised if the _supervisor_ itself isn't running.
+  #
+ 
+  class SvDir
+
+    VERSION = '0.2'
+
+    attr_reader :path
+
+    # ...SvDir::Commands = { :alarm => 'a', :ALRM => 'a', :exit => 'x' ... }
+    begin
+      h = {}
+      {
+        [:up               ] => 'u',
+        [:down             ] => 'd',
+        [:once             ] => 'o',
+        [:pause,     :STOP ] => 'p',
+        [:continue,  :CONT ] => 'c',
+        [:hangup,    :HUP  ] => 'h',
+        [:alarm,     :ALRM ] => 'a',
+        [:interrupt, :INT  ] => 'i',
+        [:terminate, :TERM ] => 't',
+        [:kill,      :KILL ] => 'k',
+        [:exit             ] => 'x',
+        [:user1,     :USR1 ] => '1', # runit and some patches to daemontools
+        [:user2,     :USR2 ] => '2',
+      }.each do | cmds, byte |
+        cmds.each { |c| h[c] = byte }
+      end
+      const_set(:Commands, h)
+    end
+
+    # Create a new SvDir corresponding to the service directory +path+.
+    def initialize(path)
+      @path        = path
+    end
+
+    # Send a signal to the service via its _supervisor_.
+    #
+    # [<tt>:up</tt>] start the service if not running, restarting as necessary.
+    # [<tt>:down</tt>] stop the service, issuing a TERM followed by a CONT.  Do not restart it if it stops.
+    # [<tt>:once</tt>] start the service if not running, but do not restart it if it stops.
+    # [<tt>:pause</tt> or <tt>:STOP</tt>] issue a STOP signal.  See also #paused?.
+    # [<tt>:continue</tt> or <tt>:CONT</tt>] issue a CONT signal.  See also #paused?.
+    # [<tt>:hangup</tt> or <tt>:HUP</tt>] issue a HUP signal.
+    # [<tt>:alarm</tt> or <tt>:ALRM</tt>] issue an ALRM signal.
+    # [<tt>:interrupt</tt> or <tt>INT</tt>] issue an INT signal.
+    # [<tt>:terminate</tt> or <tt>TERM</tt>] issue a TERM signal.
+    # [<tt>:kill</tt> or <tt>KILL</tt>] issue a KILL signal.
+    # [<tt>:exit</tt>] tell the _supervisor_ to exit as soon as the service stops.
+    # [<tt>:user1</tt> or <tt>:USR1</tt>] issue a USR1 signal.  <i>Not supported by all supervisors</i>
+    # [<tt>:user2</tt> or <tt>:USR2</tt>] issue a USR2 signal.  <i>Not supported by all supervisors</i>
+    def signal(cmd)
+      unless byte = Commands[cmd.to_sym]
+        raise ArgumentError.new("unsupported SvDir signal `#{cmd}'")
+      end
+      Util::open_write(svfn('control')) do |f|
+        f.syswrite(byte)
+      end
+    end
+
+    # Return a SvDir object representing this service's attendant +log+
+    # service, otherwise +nil+.
+    #
+    # Typical SvDir daemons contain a "nested" SvDir responsible for
+    # logging the stdout of the base service.  E.g.:
+    #
+    #   /path/to/services/webserver     # <--- base service
+    #   /path/to/services/webserver/log # <--- logger
+    # 
+    # The +log+ service is supervised and controllable just like the base
+    # service.  (Also, the pipe connecting the base service's stdout to
+    # the +log+ service's stdin is maintained by a common parent, so that
+    # restarting either service won't lose data in the pipe.)
+    #
+    # Example:
+    #
+    #   my_serv = Sys::Sv::SvDir.new("path/to/my_serv")
+    #   my_serv.signal(:down)
+    #   if logger = my_serv.log
+    #     logger.signal(:down)
+    #   end
+    def log
+      fn = File.join(@path, 'log')
+      return self.class.new(fn) if File.exists? fn
+    end
+
+    # Returns +true+ if the service directory's _supervisor_ is running.
+    # 
+    # To determine whether the service itself is running, see #up?, #down?
+    # and #paused?
+    def svok?
+      Util::open_write(svfn('ok')) { true }
+    rescue Errno::ENXIO, Errno::ENOENT
+      false # No pipe reader, or no pipe!
+    end
+
+    # Returns +true+ if the service is typically running, i.e., if the
+    # service directory lacks a <tt>./down</tt> file.
+    #
+    # Note that this method functions whether or not the service is
+    # running, and whether or not a supervisor is running.
+    #
+    # See also the #want_up? method documentation.
+    def normally_up?
+      ! normally_down?
+    end
+
+    # Returns +true+ if a _supervisor_ will not start the service without
+    # explicit instruction to do so.
+    #
+    # Note that this method functions whether or not the service is
+    # running, and whether or not a supervisor is running.
+    # 
+    # See also the #want_down? method documentation.
+    def normally_down?
+      File.exists? File.join(@path, 'down')
+    end
+
+    # Returns the number of seconds the service has been down,
+    # as a float, or +nil+ if the service is in fact running.
+    def downtime
+      return elapsed() if down?
+    end
+
+    # Returns the number of seconds the service has been running,
+    # as a float, or +nil+ if the service is not running.
+    def uptime
+      return elapsed() if up?
+    end
+
+    # Return the pid of the service running under this SvDir, or
+    # +nil+ if no service is running.
+    def pid
+      p = statusbytes.pid
+      return p == 0 ? nil : p
+    end
+
+    # +true+ if the service is not running.
+    def down?
+      pid.nil?
+    end
+
+    # +true+ if the service is running, even if paused.
+    def up?
+      !down?
+    end
+
+    # Returns +true+ if the service is paused, that is, has received
+    # a SIGSTOP.
+    def paused?
+      statusbytes.pauseflag != 0
+    end
+
+    # Returns +true+ if the service's supervisor has been instructed to
+    # bring the service down.
+    def want_down?
+      statusbytes.wantflag == 'd'
+    end
+
+    # Returns +true+ if the service's supervisor has been instructed to
+    # bring the service up.
+    def want_up?
+      statusbytes.wantflag == 'u'
+    end
+
+    private
+
+    def elapsed
+      statusbytes.elapsed
+    end
+
+    def svfn(basename)
+      File.join(@path, 'supervise', basename)
+    end
+
+    # Instantiate our one-time, delegate helper class
+    def statusbytes
+      # We _want_ to pass Errno back to caller, which is why we don't
+      # simply call #svok?() here.
+      Util::open_write(svfn('ok')) {true}
+
+      buf = Util::open_read(svfn('status')) do |f|
+              begin
+                f.sysread( StatusBytes::BUFLEN )
+              rescue ::EOFError
+                ""
+              end
+            end
+      StatusBytes.new(buf)
+    end
+
+  end
+
+end #-- module Sv
+end #-- module Sys