= sqsrun

A Generics Worker Executor Service for Amazon SQS. It polls SQS queue and run command or script when a message is received. The message is removed only when the command succeeded.


== Architecture

1. sqsrun receives a message from the queue.
2. sqsrun executes a command or runs a script.
   * if the process takes long time, sqsrun extends visibility timeout. this is repeated until it is killed.
   * if the process takes more long time, sqsrun kills the process.
3. if it succeeded, sqsrun removes the message from the queue.
4. if it failed, sqsrun set the visibility timeout to 0 and expect to be retried.


== Usage

  Usage: sqsrun [options] [-- <ARGV-for-exec-or-run>]
      -k, --key-id ID                  AWS Access Key ID
      -s, --secret-key KEY             AWS Secret Access Key
      -q, --queue NAME                 SQS queue name
      -t, --timeout SEC                SQS visibility timeout (default: 30)
          --push MESSAGE               Push maessage to the queue
          --list                       List queues
          --configure PATH.yaml        Write configuration file
          --exec COMMAND               Execute command
          --run SCRIPT.rb              Run method named 'run' defined in the script
      -e, --extend-timeout SEC         Threashold time before extending visibility timeout (default: timeout * 3/4)
      -x, --kill-timeout SEC           Threashold time before killing process (default: timeout * 5)
      -i, --interval SEC               Polling interval (default: 1)
      -d, --daemon PIDFILE             Daemonize (default: foreground)
      -f, --file PATH.yaml             Read configuration file

One of --push, --list, --configure, --exec or --run is required. The behavior of the commands is described below:


=== push

Push a message to the queue. -k, -s and -q options are required.


=== list

Show list of queues. -k and -s options are required.


=== configure

Write configuration file and exit. Written configuration file can be used with -f option:

_Example:_

  ## create sqsrun.yaml file
  $ sqsrun --configure sqsrun.yaml -k KEY_ID -s SEC_KEY -q myqueue --run myrun.rb -- my run args

  ## run sqsrun using the configuration file
  $ sqsrun -f sqsrun.yaml


=== exec

Execute a command when a message is received. Body of the message is passed to the stdin. The command have to exit with status code 0 when it succeeded.

-k, -s and -q options are required.

_Example:_

  #!/usr/bin/env ruby
  require 'json'
  js = JSON.load(STDIN.read)
  puts "received: #{js.inspect}"
  
  # $ sqsrun -k AWS_KEY_ID -s AWS_SEC_KEY -q SQS_NAME --exec ./this_file


=== run

This is same as 'exec' except that this calls a method named 'run' defined in the file instead of executing the file. Body of the message is passed to the argument. It is assumed it succeeded if the method doesn't any raise errors.

_Example:_

  require 'json'
  def run(msg)
    js = JSON.load(msg)
    puts "received: #{js.inspect}"
  end
  
  # $ sqsrun -k AWS_KEY_ID -s AWS_SEC_KEY -q SQS_NAME --run ./this_file.rb