tellmewhen 1.0.0

data/README.textile

@@ -0,0 +1,50 @@
+h1. tellmewhen
+
+Tell me when another program has finshed.  Show me when it started, when it finished and how long it took.  Show me the output and if it errored.
+
+I created this utility because I had long running database scripts that I wanted a completion notification for - including a summary of the time and exit code.  I had done this various ways in the past by using bash and other shell utilities.  This program captures all of the features and behavior I wanted without having to script it from scratch again every time I needed it.
+
+* YML Based Configuration in an rc file
+* easy default configuration
+* sends email
+* includes start/stop/elapsed timing
+* success/fail based on exit code
+* watch an already running process (by pid, by grep pattern over 'ps aux')
+* release as a gem so it's easy to use/install
+
+h1. Configuration
+
+Configuration Defaults:
+
+Configuration is then merged from @$HOME/.tellmewhenrc@ if the file exists in @$HOME@.  Configuration is also merged from @./.tellmewhenrc@ in the current directory, if the file exists.  This allows you some flexibility in overriding settings.
+
+h1. Usage
+
+pre. Usage: ./tellmewhen command args...
+    -v, --[no-]verbose               Run Verbosely.
+    -c, --config=file                Use alternate configuration file.
+    -p, --pid=pid                    Wait for <pid> to terminate.
+    -e, --exists=file                Wait for <file> to exist.
+    -m, --modified=file              Wait for <file> to be modified.
+    -t, --timeout=seconds            Wait for up to <seconds> seconds for the command before sendin a 'pending' notification.
+    -w, --write-config=file          Write [fully merged] configuration to <file> (NB: will not be clobber).
+
+
+h1. Examples
+
+pre.    ./tellmewhen 'sleep 3; ls'
+    ./tellmewhen -p 12345
+    ./tellmewhen -e some-file.txt    # await existance
+    ./tellmewhen -m some-file.txt    # await update
+
+h1. Authors
+
+h1. License
+
+h1. Patches Welcome
+
+I'd like to clean up the internals: how emails are composed.
+
+I'd like to support other notification channels, like Instant Messaging or SMS.  Multiple at one time, controlled through the configuration yaml.
+
+What would you like?

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rubygems'
+require 'rake'
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+load 'tellmewhen.gemspec'
+ 
+ 
+Rake::GemPackageTask.new(SPEC) do |t|
+  t.need_tar = true
+end

data/bin/tellmewhen

@@ -0,0 +1,383 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'yaml'
+require 'optparse'
+require 'tempfile'
+require 'net/smtp'
+
+class TellMeWhen
+  RC_FILE = "#{ENV['HOME']}/.tellmewhenrc"
+  LOCAL_FILE = ".tellmewhenrc"
+
+  def initialize
+    @stdout_file = Tempfile.new('tellmewhen.stdout').path
+    @stderr_file = Tempfile.new('tellmewhen.stdout').path
+  end
+
+  def hostname
+    `hostname`.chomp
+  end
+
+  def load_settings
+    @settings ||= {
+      'notify-via' => 'email',
+      'email' => {
+         'to'   => "#{ENV['LOGNAME']}@#{hostname}",
+         'from' => "#{ENV['LOGNAME']}@#{hostname}",
+         'smtp_host' => 'localhost',
+         'smtp_port' => '25'
+      }
+    }
+
+    if File.exist? RC_FILE
+      settings = YAML.load_file RC_FILE
+      @settings = @settings.merge(settings)
+      puts "Loaded Settings [#{RC_FILE}]: #{@settings.inspect}"
+    end
+
+    if File.exist? LOCAL_FILE
+      settings = YAML.load_file LOCAL_FILE
+      @settings = @settings.merge(settings)
+      puts "Loaded Settings [#{LOCAL_FILE}]: #{@settings.inspect}"
+    end
+  end
+
+  def save_settings target_file=RC_FILE
+    if ! File.exist? target_file
+      File.open(target_file,"w") do |f|
+        f.write @settings.to_yaml
+      end
+    end
+  end
+
+  def parse_options
+    @options = {
+      :wait_on => :command,
+      :wait_timeout => 600  # every 10 min send a 'pending' email
+    }
+    OptionParser.new do |opts|
+      opts.banner = "Usage: #$0 command args..."
+
+      opts.on("-v","--[no-]verbose", "Run Verbosely.") do |v|
+        @options[:verbose] = v
+      end
+
+      opts.on("-c","--config=file", "Use alternate configuration file.") do |file|
+        @options[:config_file] = file
+      end
+
+      opts.on("-p","--pid=pid", "Wait for <pid> to terminate.") do |pid|
+        @options[:wait_on] = :pid
+        @options[:pid]     = pid
+      end
+
+      opts.on("-e","--exists=file", "Wait for <file> to exist.") do |file|
+        @options[:wait_on] = :file_exists
+        @options[:trigger_file] = file
+      end
+
+      opts.on("-m","--modified=file", "Wait for <file> to be modified.") do |file|
+        @options[:wait_on]       = :file_modified
+        @options[:trigger_file]  = file
+      end
+
+      opts.on("-t","--timeout=seconds", "Wait for up to <seconds> seconds for the command before sendin a 'pending' notification.") do |seconds|
+        @options[:wait_timeout] = seconds
+      end
+
+      opts.on("-w","--write-config=file", "Write [fully merged] configuration to <file> (NB: will not be clobber).") do |file|
+        @options[:write_config_to] = file
+      end
+
+    end.parse!
+
+    puts "Options: #{@options.inspect}"
+  end
+
+  def self.main args
+    app = self.new
+    app.parse_options
+    app.load_settings
+    exit app.run args
+  end
+
+  def elapsed_time
+    Time.now.to_i - @start_time.to_i
+  end
+
+  def wait_timeout
+    @options[:wait_timeout]
+  end
+
+  def wait_on_command args
+    puts "Do run: #{args}"
+    if args.to_s.empty?
+      raise "Error: you must supply a command to execute"
+    end
+    child_pid = Kernel.fork
+    if child_pid.nil?
+      # in child
+      STDOUT.reopen(File.open(@stdout_file, 'w+'))
+      STDERR.reopen(File.open(@stderr_file, 'w+'))
+      STDIN.close
+      exec "bash", "-c", args.to_s
+    else
+      # in parent
+      child_exited = false
+      while ! child_exited
+        if Process.wait child_pid, Process::WNOHANG
+          puts "Child exited: #{$?.exitstatus}"
+          @exit_status = $?.exitstatus
+          child_exited = true
+        end
+        sleep(0.250)
+        if elapsed_time > wait_timeout
+          puts "Exceeded timeout #{wait_timeout}, sending 'pending' notificaiton"
+          send_pending_notification
+        end
+      end
+    end
+
+    @end_time = Time.now
+    if @exit_status == 0
+      body = <<-BODY
+Just wanted to let you know that:
+
+      #{args.to_s}
+
+completed on #{hostname}, with an exit code of: #{@exit_status}
+
+It started at #{@start_time.to_s} (#{@start_time.to_i}), finished at #{@end_time.to_s} (#{@end_time.to_i}) and took a total of #{elapsed_time} seconds.
+
+May your day continue to be full of win.
+
+Sincerely,
+
+Tellmewhen
+
+#{email_footer}
+BODY
+
+      send_email_notification "When! SUCCESS for #{args.to_s.split.first}...", body
+    else
+      body = <<-BODY
+Just wanted to let you know that:
+
+      #{args.to_s}
+
+FAILED! on #{hostname}, with an exit code of: #{@exit_status}
+
+It started at #{@start_time.to_s} (#{@start_time.to_i}), finished at #{@end_time.to_s} (#{@end_time.to_i}) and took a total of #{elapsed_time} seconds to collapse in a steaming heap of failure.
+
+Have a nice day.
+
+Warmest Regards,
+
+Tellmewhen
+
+#{email_footer}
+BODY
+
+      send_email_notification "When! FAILURE for #{args.split.first}...", body
+    end
+  end
+
+  def send_pending_notification
+    body = <<-BODY
+Just wanted to let you know that:
+
+    #{args.to_s}
+
+Is _STILL_ running on #{hostname}, it has not exited.  You did want me to let you know didn't you?
+
+I started the darn thing at #{@start_time.to_s} (#{@start_time.to_i}) and it has taken a total of #{elapsed_time} seconds so far.
+
+Just thought you'd like to know.  I'll continue to keep watching what you asked me to. (boor-ring!)
+
+Cordially,
+
+Tellmewhen
+
+#{email_footer}
+BODY
+
+    send_email_notification "When! [NOT] I'm _still_ waiting for #{args.split.first}...", body
+  end
+
+  def email_footer
+    return <<-END
+P.S. stderr says:
+--
+#{File.read(@stderr_file)}
+--
+
+P.S. stdout says:
+--
+#{File.read(@stdout_file)}
+--
+    END
+  end
+
+  def pid_running? pid
+    lines = `ps #{pid}`.split "\n"
+    lines.count > 1
+  end
+
+  def wait_on_pid args
+    # wait until pid exits
+    while pid_running? @options[:pid]
+      sleep 0.250
+      if elapsed_time > wait_timeout
+        puts "Exceeded timeout #{wait_timeout}, sending 'pending' notificaiton"
+        send_email_notification "When! [NOT] still awaiting pid:#{pid} to exit", <<-END
+
+I started watching #{pid} on #{hostname} at #{@start_time.to_s} (#{@start_time.to_i}), I've been watching 'em for  #{elapsed_time} seconds so far.
+
+Awaiting it's demise,
+
+TellMeWhen
+        END
+      end
+    end
+
+    @end_time = Time.now
+
+    send_email_notification "When! pid:#{@options[:pid]} has come to its end", <<-END
+
+I started watching #{@options[:pid]} on #{hostname} at #{@start_time.to_s} (#{@start_time.to_i}), and now, after #{elapsed_time} seconds it has finally gone bellly up.  #{@options[:pid]} will rest in peace as of #{@end_time.to_s} (#{@end_time.to_i})
+
+#{@options[:pid]} will be missed, it was a good little process.  :,)
+
+TellMeWhen
+        END
+
+  end
+
+  def wait_on_file_exists args
+    while !File.exist? @options[:trigger_file]
+      sleep 0.250
+      if elapsed_time > wait_timeout
+        puts "Exceeded timeout #{wait_timeout}, sending 'pending' notificaiton"
+        send_email_notification "When! [NOT] still awaiting #{@options[:trigger_file]} to exist", <<-END
+
+I started watching for #{@options[:trigger_file]} on #{hostname} at #{@start_time.to_s} (#{@start_time.to_i}), I've been watching for it #{elapsed_time} seconds so far.
+
+Awaiting it's arrival,
+
+TellMeWhen
+        END
+      end
+    end
+    @end_time = Time.now
+
+    send_email_notification "When! #{@options[:trigger_file]} now exists.", <<-END
+
+I started watching for #{@options[:trigger_file]} on #{hostname} at #{@start_time.to_s} (#{@start_time.to_i}), and now, after #{elapsed_time} seconds it has finally shown up as of #{@end_time.to_s} (#{@end_time.to_i})
+
+What is thy next bidding my master?
+
+TellMeWhen
+        END
+  end
+
+  def wait_on_file_modified args
+    trigger_file = @options[:trigger_file]
+    initial_mtime = File.mtime trigger_file
+
+    while initial_mtime == File.mtime(trigger_file)
+      sleep 0.250
+      if elapsed_time > wait_timeout
+        puts "Exceeded timeout #{wait_timeout}, sending 'pending' notificaiton"
+        send_email_notification "When! [NOT] still awaiting #{@options[:trigger_file]} to change", <<-END
+
+I started watching for #{@options[:trigger_file]} to be updated on #{hostname} at #{@start_time.to_s} (#{@start_time.to_i}), I've been watching for it #{elapsed_time} seconds so far.
+
+Awaiting it's update,
+
+TellMeWhen
+        END
+      end
+    end
+
+    @end_time = Time.now
+
+    send_email_notification "When! #{@options[:trigger_file]} was updated.", <<-END
+
+I started watching for #{@options[:trigger_file]} to be updated on #{hostname} at #{@start_time.to_s} (#{@start_time.to_i}), and now, after #{elapsed_time} seconds it has finally been modified as of #{@end_time.to_s} (#{@end_time.to_i})
+
+POSIX is my zen,
+
+TellMeWhen
+        END
+  end
+
+  def smtp_host
+    @settings["email"]["smtp_host"]
+  end
+
+  def smtp_port
+    @settings["email"]["smtp_port"]
+  end
+
+  def send_email_notification subject, body
+    # optionally send via /usr/bin/mail or sendmail binary if it exists...
+    puts "Sending email: from:#{@settings["email"]["from"]} to:#{@settings["email"]["to"]}"
+    begin
+      Net::SMTP.start(smtp_host, smtp_port) do |smtp|
+        smtp.open_message_stream('from_addr', @settings["email"]["to"].split(',')) do |f|
+          f.puts "From: #{@settings["email"]["from"]}"
+          f.puts "To: #{@settings["email"]["to"]}"
+          f.puts "Subject: #{subject}"
+          f.puts ""
+          f.puts body
+        end
+      end
+    end
+  rescue Errno::ECONNREFUSED => e
+    if File.exist? "/usr/sbin/sendmail"
+      body_file = Tempfile.new("tellmewhen.mail.body")
+      File.open(body_file.path,"w") do |f|
+        f.puts "From: #{@settings["email"]["from"]}"
+        f.puts "To: #{@settings["email"]["to"]}"
+        f.puts "Subject: #{subject}"
+        f.puts ""
+        f.write body
+      end
+      system "/usr/sbin/sendmail -f #{@settings["email"]["from"]} '#{@settings["email"]["to"]}' < #{body_file.path}"
+    elsif File.exist? "/usr/bin/mail"
+      raise "Implement sending via /usr/bin/mail"
+      body_file = Tempfile.new("tellmewhen.mail.body")
+      File.open(body_file.path,"w") do |f|
+        f.puts "From: #{@settings["email"]["from"]}"
+        f.puts "To: #{@settings["email"]["to"]}"
+        f.puts "Subject: #{subject}"
+        f.puts ""
+        f.write body
+      end
+      system "/usr/bin/mail '#{@settings["email"]["to"]}' < #{body_file.path}"
+    else
+      raise "No smtp server (that we can connect to) at #{smtp_host}:#{smtp_port}, could not fall back to /usr/bin/mail either (doesn't exist).  Sorry, tried my best."
+    end
+  end
+
+  def run args
+    @command = args
+    action = "wait_on_#{@options[:wait_on].to_s}".to_sym
+    if ! self.respond_to? action
+      raise "Error: don't know how to wait on: #{@options[:wait_on]}"
+    end
+
+    @start_time = Time.now
+    if @options[:write_config_to]
+      save_settings @options[:write_config_to]
+    end
+    save_settings 
+    self.send action, args
+    return 1
+  end
+end
+
+if $0 == __FILE__
+  TellMeWhen.main(ARGV)
+end

data/tellmewhen.gemspec

@@ -0,0 +1,28 @@
+require 'rubygems'
+
+
+SPEC = Gem::Specification.new do |s|
+  s.name = "tellmewhen"
+  s.version = "1.0.0"
+  s.author = "Kyle Burton"
+  s.email = "kyle.burton@gmail.com"
+  s.platform = Gem::Platform::RUBY
+  s.description = <<DESC
+Notifys you when another command completes (via email).
+
+    ./tellmewhen 'sleep 3; ls'       # await a command to complete
+    ./tellmewhen -p 12345            # await a pid to exit
+    ./tellmewhen -e some-file.txt    # await existance
+    ./tellmewhen -m some-file.txt    # await update
+
+Tells you when, how long and sends you the output (for commands it runs).
+
+DESC
+  s.summary = "Notifys you when another command completes (via email)."
+  # s.rubyforge_project = "typrtail"
+  s.homepage = "http://github.com/kyleburton/tellmewhen"
+  s.files = Dir.glob("**/*")
+  s.executables << "tellmewhen"
+  s.require_path = "bin"
+  s.has_rdoc = false
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification 
+name: tellmewhen
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Kyle Burton
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-01-25 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: |+
+  Notifys you when another command completes (via email).
+  
+      ./tellmewhen 'sleep 3; ls'       # await a command to complete
+      ./tellmewhen -p 12345            # await a pid to exit
+      ./tellmewhen -e some-file.txt    # await existance
+      ./tellmewhen -m some-file.txt    # await update
+  
+  Tells you when, how long and sends you the output (for commands it runs).
+  
+email: kyle.burton@gmail.com
+executables: 
+- tellmewhen
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- bin/tellmewhen
+- Rakefile
+- README.textile
+- tellmewhen.gemspec
+has_rdoc: true
+homepage: http://github.com/kyleburton/tellmewhen
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- bin
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Notifys you when another command completes (via email).
+test_files: []
+