fiksu-af 1.1.0

data/.gitignore

@@ -0,0 +1,24 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile ~/.gitignore_global
+
+# Ignore bundler config
+/.bundle
+
+# Ignore the default SQLite database.
+/db/*.sqlite3
+
+# Ignore all logfiles and tempfiles.
+/log/*.log
+/tmp
+.idea/*
+database.yml
+/log/*.pid
+spec/dummy/db/*.sqlite3
+spec/dummy/log/*.log
+spec/dummy/tmp/
+spec/dummy/.sass-cache
+spec/dummy/config/database.yml
+spec/dummy/db/schema.rb

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+rvm:
+  - 1.9.3
+bundler_args: --without staging development deploy
+before_install:
+before_script: cp spec/dummy/config/database-sample.yml spec/dummy/config/database.yml; cd spec/dummy; bundle exec rake db:create;
+script: rspec spec
+branches:
+  only:
+    - master
+notifications:
+  hipchat: 5d580c1746812c946d9cb0b58f7a66@FMA
+  email:
+    - dev-fma@fiksu.com

data/Gemfile

@@ -0,0 +1,22 @@
+source "http://rubygems.org"
+
+# Declare your gem's dependencies in partitioned.gemspec.
+# Bundler will treat runtime dependencies like base dependencies, and
+# development dependencies will be added by default to the :development group.
+gemspec
+
+gem 'pg_application_name', '>= 1.0.0'
+gem 'pg_advisory_locker', '>= 0.9.0'
+gem 'log4r', '1.1.10'
+gem 'reasonable_log4r', '>= 0.9.0'
+gem 'uuid', '2.3.5'
+
+gem 'awesome_print'
+
+# Declare any dependencies that are still in development here instead of in
+# your gemspec. These might include edge Rails or gems from your path or
+# Git. Remember to move these dependencies to your gemspec before releasing
+# your gem to rubygems.org.
+
+# To use debugger
+# gem 'ruby-debug'

data/LICENSE

@@ -0,0 +1,30 @@
+Copyright (c) 2010-2013, Fiksu, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+ o Redistributions of source code must retain the above copyright
+    notice, this list of conditions and the following disclaimer.
+
+ o Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the
+   distribution.
+
+ o Fiksu, Inc. nor the names of its contributors may be used to
+   endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,175 @@
+# Af - an application framework
+
+gem 'fiksu-af'
+
+This application framework supports:
+
+* an Application class with supporting infrastruction
+* command line options integrated into instance (and class) variables
+* logging via log4r with support for papertrail
+* postgres advisory locking via pg_advisor_locker gem
+* postgres database connection updates via pg_application_name gem
+* threads and message passing
+* application components adding loggers and command line options
+
+## Application class
+
+The class ::Af::Application provides a basic interface to the start-up
+and management of Ruby on Rails scripts.
+
+A simple example of an application which logs its startup and exits
+is:
+
+```
+class MyApplication < ::Af::Application
+  opt :word, "the word", :short => :w, :default => "bird"
+
+  def work
+    logger.info "Started up: #{@word} is the word"
+    exit 0
+  end
+end
+```
+
+Class-method "opt" specifies command line parameter(s) whose arguments
+are stored in instance variables.  MyApplication specifies a single
+parameter "--word" with a short alias "-w" that accepts a string
+argument (whose default is "bird", so we know it should be a string).
+The parameters value will be stored in class instance variable: @word.
+More information on command line option glue is provided in the
+Command Line Options section.
+
+The method "logger" is available to ::Af::Application to create and
+fetch log4r loggers.  In this case, we use the basic application
+logger (named "MyApplication") and logs an INFO level message.  More
+information on the glue ::Af::Application provides with Log4r is
+in the logging section below.
+
+This application would be run from the command line as:
+
+```
+$ script/rails runner MyApplication.run --word grease
+```
+
+The class method #run provides start-up glue for applications, parsing
+command line options, environment variables and configuration files.
+The instance method #work is where application codes start their work.
+
+## Command Line Options
+
+a more interesting example of options from multiple classes
+
+```
+class AfSideComponent
+  include Af::Application::Component
+
+  opt_group :side_component_stuff, "options associated with this side component" do
+    opt :a_side_component_option, :default => "foo"
+  end
+
+  opt :basic_option_from_component, "this is a switch from the side component, in the basic (default) group"
+
+  create_proxy_logger :foo
+
+  def do_something
+    foo_logger.info "doing something @@a_side_component_option='#{@@a_side_component_option}'"
+    foo_logger.info "did something @@basic_option_from_component=#{@@basic_option_from_component.inspect}"
+  end
+end
+```
+
+```
+class AfScriptWithOptions < ::Af::Application
+  opt_group :singles, "parameters whose types are a single value" do
+    opt :a_switch, "a switch"
+    opt :an_int, "an integer of some sort", :default => 1
+    opt :a_float, "a float of some sort whose default is PI", :default => 3.14
+    opt :a_string, "a string of some sort", :type => :string
+    opt :a_uri, "some uri", :type => :uri
+    opt :a_date, "a date", :type => :date
+    opt :a_time, "a time", :type => :time
+    opt :a_datetime, "a datetime", :type => :datetime
+    opt :a_choice, "a choice", :argument_note => "COLOR", :choices => [:red, :blue, :green, :yellow, :white, :black, :orange]
+  end
+
+  # there is already an advanced option group -- it is set to hidden by default
+  opt_group :advanced, "advanced parameters", :hidden => false do
+    opt :a_small_integer, "another integer", :default => 10, :argument_note => "[1 >= INTEGER <= 10]" do |argument,option|
+      argument = argument.to_i
+      if (argument < 1 || argument > 10)
+        opt_error "ERROR: #{option.long_name}: value must be between 1 and 10 (inclusive)"
+      end
+      argument
+    end
+    opt :a_constrained_number, "a number which is not an integer", :requirement => :required, :argument_note => "NON-INTEGER" do |argument,option|
+      i_argument = argument.to_i
+      f_argument = argument.to_f
+      if (i_argument == f_argument)
+        opt_error "ERROR: #{option.long_name}: value must not be an integer"
+      end
+      f_argument
+    end
+  end
+
+  opt_group :collections, "parameters whose types are collections" do
+    opt :a_hash, "a key value pair", :type => :hash
+    opt :some_ints, "a list of integer", :type => :ints
+    opt :some_integers, "a list of integer", :type => :integers
+    opt :some_floats, "a list of floats", :type => :floats
+    opt :some_numbers, "a list of numbers", :type => :numbers
+    opt :some_strings, "a list of strings", :type => :strings
+    opt :some_uris, "a list of uris", :type => :uris
+    opt :some_dates, "a list of dates", :type => :dates
+    opt :some_times, "a list of times", :type => :times
+    opt :some_datetimes, "a list of datetimes", :type => :datetimes
+    opt :some_choices, "a list of choices", :choices => [:foo, :bar, :baz, :beltch]
+  end
+
+  opt_group :blank, "a blank group that won't be seen"
+
+  opt :word, "the word to print", :default => :foo, :choices => [:foo, :bar, :baz, :beltch]
+  opt :words, "the words to print", :default => [:foo], :choices => [:foo, :bar, :baz, :beltch]
+  opt :numbers, "the number lists", :default => [1,2,3]
+  opt :switcher, "this is a switch"
+
+  def af_opt_class_path
+    [AfSideComponent] + super
+  end
+
+  def logger
+    super('Process::T')
+  end
+
+  def work
+    logger.info "switcher: #{switcher.inspect}"
+    logger.info "WORK STARTED: #{@word}"
+    logger.info @words.inspect
+    logger.info "NUMBERS: #{@numbers.inspect}"
+
+    AfSideComponent.new.do_something
+
+    logger.info "WORK COMPLETED: #{@word}"
+  end
+end
+
+```
+
+## Logging with Log4r
+
+Some changes to Log4r:
+
+* root loggers are no longer null loggers -- you can add outputters to them
+* the global logger is used to set a global log level (root is no longer used for this)
+* yaml configurator has been updated to handle new root logger semantics
+* yaml configurator has been updated to accept a set of files AND sections (default section: log4r_config)
+
+What this really means is that you can set up one outputter in the root
+logger to manage the default logging behavior.
+
+## Thread Pool
+
+*TODO*
+
+## TCP Message Passing
+
+*TODO*

data/Rakefile

@@ -0,0 +1,42 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Af'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# Eventually we will want a test application to use this Engine
+# to see if it works!
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+
+require 'rake'
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+desc 'Default: Run all specs.'
+task :default => :spec

data/examples/af_script_with_options.rb

@@ -0,0 +1,73 @@
+class AfScriptWithOptions < ::Af::Application
+  opt_group :singles, "parameters whose types are a single value" do
+    opt :a_switch, "a switch"
+    opt :an_int, "an integer of some sort", :default => 1
+    opt :a_float, "a float of some sort whose default is PI", :default => 3.14
+    opt :a_string, "a string of some sort", :type => :string
+    opt :a_uri, "some uri", :type => :uri
+    opt :a_date, "a date", :type => :date
+    opt :a_time, "a time", :type => :time
+    opt :a_datetime, "a datetime", :type => :datetime
+    opt :a_choice, "a choice", :argument_note => "COLOR", :choices => [:red, :blue, :green, :yellow, :white, :black, :orange]
+  end
+
+  # there is already an advanced option group -- it is set to hidden by default
+  opt_group :advanced, "advanced parameters", :hidden => false do
+    opt :a_small_integer, "another integer", :default => 10, :argument_note => "[1 >= INTEGER <= 10]" do |argument,option|
+      argument = argument.to_i
+      if (argument < 1 || argument > 10)
+        opt_error "ERROR: #{option.long_name}: value must be between 1 and 10 (inclusive)"
+      end
+      argument
+    end
+    opt :a_constrained_number, "a number which is not an integer", :requirement => :required, :argument_note => "NON-INTEGER" do |argument,option|
+      i_argument = argument.to_i
+      f_argument = argument.to_f
+      if (i_argument == f_argument)
+        opt_error "ERROR: #{option.long_name}: value must not be an integer"
+      end
+      f_argument
+    end
+  end
+
+  opt_group :collections, "parameters whose types are collections" do
+    opt :a_hash, "a key value pair", :type => :hash
+    opt :some_ints, "a list of integer", :type => :ints
+    opt :some_integers, "a list of integer", :type => :integers
+    opt :some_floats, "a list of floats", :type => :floats
+    opt :some_numbers, "a list of numbers", :type => :numbers
+    opt :some_strings, "a list of strings", :type => :strings
+    opt :some_uris, "a list of uris", :type => :uris
+    opt :some_dates, "a list of dates", :type => :dates
+    opt :some_times, "a list of times", :type => :times
+    opt :some_datetimes, "a list of datetimes", :type => :datetimes
+    opt :some_choices, "a list of choices", :choices => [:foo, :bar, :baz, :beltch]
+  end
+
+  opt_group :blank, "a blank group that won't be seen"
+
+  opt :word, "the word to print", :default => :foo, :choices => [:foo, :bar, :baz, :beltch]
+  opt :words, "the words to print", :default => [:foo], :choices => [:foo, :bar, :baz, :beltch]
+  opt :numbers, "the number lists", :default => [1,2,3]
+  opt :switcher, "this is a switch"
+
+  def af_opt_class_path
+    [AfSideComponent] + super
+  end
+
+  def logger
+    super('Process::T')
+  end
+
+  def work
+    logger.info "switcher: #{switcher.inspect}"
+    logger.info "WORK STARTED: #{@word}"
+    logger.info @words.inspect
+    logger.info "NUMBERS: #{@numbers.inspect}"
+
+    AfSideComponent.new.do_something
+
+    logger.info "WORK COMPLETED: #{@word}"
+  end
+end
+

data/examples/af_side_component.rb

@@ -0,0 +1,16 @@
+class AfSideComponent
+  include Af::Application::Component
+
+  opt_group :side_component_stuff, "options associated with this side component" do
+    opt :a_side_component_option, :default => "foo"
+  end
+
+  opt :basic_option_from_component, "this is a switch from the side component, in the basic (default) group"
+
+  create_proxy_logger :foo
+
+  def do_something
+    foo_logger.info "doing something @@a_side_component_option='#{@@a_side_component_option}'"
+    foo_logger.info "did something @@basic_option_from_component=#{@@basic_option_from_component.inspect}"
+  end
+end

data/examples/my_application.rb

@@ -0,0 +1,8 @@
+class MyApplication < ::Af::Application
+  opt :word, "the word", :short => :w, :default => "bird"
+
+  def work
+    logger.info "Started up: #{@word} is the word"
+    exit 0
+  end
+end

data/fiksu-af.gemspec

@@ -0,0 +1,27 @@
+$LOAD_PATH.push File.expand_path("../lib", __FILE__)
+
+# Maintain your gem's version:
+require "fiksu-af/version"
+
+Gem::Specification.new do |s|
+ s.name        = 'fiksu-af'
+ s.version     = Af::VERSION
+ s.license     = 'New BSD License'
+ s.date        = '2013-10-11'
+ s.summary     = "An application framework for ruby on rails based scripts."
+ s.description = "Af groups together gems and provides some glue and helper classes to easily creating applications in a ruby on rails environment."
+ s.authors     = ["Keith Gabryelski", "Leonardo Meira"]
+ s.email       = ['keith@fiksu.com', 'lmeira@fiksu.com']
+ s.files       = `git ls-files`.split("\n")
+ s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+ s.require_path = 'lib'
+ s.homepage    = 'http://github.com/fiksu/af'
+ s.add_dependency 'pg_application_name', '>= 1.0.0'
+ s.add_dependency 'pg_advisory_locker', '>= 0.9.0'
+ s.add_dependency 'log4r', '1.1.10'
+ s.add_dependency "log4r_remote_syslog_outputter", "0.0.1"
+ s.add_dependency 'reasonable_log4r', '>= 0.9.0'
+ s.add_dependency 'uuid'
+ s.add_dependency "rails", '>= 3.0.0'
+ s.add_dependency 'rspec-rails', '>=2.12.0'
+end

data/lib/fiksu-af/application/component.rb

@@ -0,0 +1,95 @@
+module Af
+  class Application
+    # Proxy's are used by dependant classes to interact with the Application framework
+    #
+    # consider a model that wishes to use the logging functionality of Af:
+    #
+    #    class Foo < ActiveRecord::Base
+    #      include ::Af::Application::Component
+    #
+    #      after_create :do_something_after_create
+    #
+    #      create_proxy_logger :foo
+    #
+    #      private
+    #      def do_something_after_create
+    #        foo_logger.info "created: #{self.inspect}"
+    #      end
+    #    end
+    #
+    module Component
+      def self.included(base)
+        base.extend(ClassMethods)
+        base.send(:include, ::Af::Logging)
+      end
+
+      module ClassMethods
+        def create_proxy_logger(prefix = "", logger_name = self.name, create_class_method = false)
+          prefix = prefix.to_s
+          if !prefix.blank? && prefix[-1] != '_'
+            prefix = "#{prefix}_"
+          end
+
+          method_name = "#{prefix}logger"
+          class_eval <<-CLASS_EVAL
+            def #{create_class_method ? 'self.' : ''}#{method_name}
+              return Log4r::Logger['#{logger_name}'] || Log4r::Logger.new('#{logger_name}')
+            end
+          CLASS_EVAL
+        end
+
+        def create_class_proxy_logger(prefix = "", logger_name = self.name)
+          create_proxy_logger(prefix, logger_name, true)
+        end
+
+        def opt(long_name, *extra_stuff, &b)
+          add_target_container(extra_stuff)
+          return ::Af::Application.opt(long_name, *extra_stuff, &b)
+        end
+
+        def opt_group(group_name, *extra_stuff, &b)
+          add_target_container(extra_stuff)
+          return ::Af::Application.opt_group(group_name, *extra_stuff, &b)
+        end
+
+        def opt_check(var_name, *extra_stuff, &b)
+          add_target_container(extra_stuff)
+          return ::Af::Application.opt_check(var_name, *extra_stuff, &b)
+        end
+
+        def opt_select(var_name, *extra_stuff, &b)
+          add_target_container(extra_stuff)
+          return ::Af::Application.opt_select(var_name, *extra_stuff, &b)
+        end
+
+        def add_target_container(extra_stuff)
+          extra_hash = {}
+          if extra_stuff[-1].is_a? Hash
+            extra_hash = extra_stuff.pop
+          end
+          extra_stuff.push extra_hash.merge({ target_container: self })
+        end
+      end
+
+      def af_logger(logger_name = (af_name || "Unknown"))
+        return ::Af::Application.singleton.logger(logger_name)
+      end
+
+      def af_name
+        return ::Af::Application.singleton.try(:af_name)
+      end
+
+      def periodic_application_checkpoint
+        af_application.try(:periodic_application_checkpoint)
+      end
+
+      def protect_from_signals
+        af_application.try(:protect_from_signals)
+      end
+
+      def af_application
+        return ::Af::Application.singleton
+      end
+    end
+  end
+end