outpost 0.1.0 → 0.2.0

data/lib/outpost/expectations/response_code.rb

@@ -1,10 +1,15 @@
 module Outpost
   module Expectations
+    # Module containing response_code logic. It is the simplest of all,
+    # it is a simple direct equality check. Extend your Scout to win instant
+    # response_code checking.
     module ResponseCode
+      # Installs the response code expectation
       def self.extended(base)
         base.expect :response_code, base.method(:evaluate_response_code)
       end
 
+      # Method that will be used as an expectation to evaluate response code
       def evaluate_response_code(scout, response_code)
         scout.response_code == response_code.to_i
       end

data/lib/outpost/expectations/response_time.rb

@@ -1,17 +1,26 @@
 module Outpost
   module Expectations
+    # Module containing response_time matching expectations. Extend your Scout
+    # with ResponseTime and it will evaluate timely expressions, all in
+    # milisseconds.
+    #
+    # It respond to the following rules:
+    # * less_than => If the response time is less than the associated number
+    # * more_than => If the response time is below than the associated number
     module ResponseTime
       RESPONSE_TIME_MAPPING = {
         :less_than => "<",
         :more_than => ">",
       }.freeze
 
+      # Installs the response time expectation
       def self.extended(base)
         base.expect :response_time, base.method(:evaluate_response_time)
       end
 
+      # Method that will be used as an expectation to evaluate response time
       def evaluate_response_time(scout, rules)
-        rules.all? do |rule,comparison|
+        rules.all? do |rule, comparison|
           scout.response_time.send(RESPONSE_TIME_MAPPING[rule], comparison)
         end
       end

data/lib/outpost/notifiers.rb

@@ -0,0 +1,2 @@
+require 'outpost/notifiers/email'
+require 'outpost/notifiers/campfire'

data/lib/outpost/notifiers/campfire.rb

@@ -0,0 +1,50 @@
+begin
+  require 'tinder'
+rescue LoadError => e
+  puts "Please install tinder gem: gem install tinder"
+  raise
+end
+
+module Outpost
+  module Notifiers
+    # The Campfire notifier issues Outpost notifications to the 37signals'
+    # Campfire web app (http://campfirenow.com). It issues messages about
+    # the system status in the specified subdomain and room.
+    #
+    # This requires the 'tinder' gem to be installed.
+    class Campfire
+
+      # @param [Hash] Options to create a campfire notification.
+      # @option options [String] :subdomain The subdomain of your campfire
+      #   rooms
+      # @option options [String] :token An access token, can be found
+      #   in your Account info
+      # @option options [String] :room The room notifications will be sent to
+      # @option options [Class] :campfire_notifier Another Campfire
+      #   notification class. Defaults to Tinder's gem
+      def initialize(options={})
+        @subdomain         = options[:subdomain]         || ''
+        @token             = options[:token]             || ''
+        @room              = options[:room]              || ''
+        @campfire_notifier = options[:campfire_notifier] || Tinder::Campfire
+
+        if [@subdomain, @token, @room].any?(&:empty?)
+          raise ArgumentError, 'You need to supply :token, :subdomain and :room.'
+        end
+      end
+
+      # Issues a notification to a Campfire room. This is a callback, called by
+      # an Outpost instance.
+      # @param [Outpost::Application, #read] outpost an instance of an outpost, containing
+      #   latest status, messages and reports that can be queried to build
+      #   a notification message.
+      def notify(outpost)
+        campfire = @campfire_notifier.new @subdomain, :token => @token
+        room     = campfire.find_room_by_name @room
+
+        status = outpost.last_status.to_s
+        room.speak "System is #{status}: #{outpost.messages.join(',')}"
+      end
+    end
+  end
+end

data/lib/outpost/notifiers/email.rb

@@ -0,0 +1,59 @@
+begin
+  require 'mail'
+rescue LoadError => e
+  puts "Please install mail gem: gem install mail"
+  raise
+end
+
+module Outpost
+  module Notifiers
+    # The Email notifier issues Outpost notifications to through email.  It
+    # uses the 'mail' gem send the emails. You can see mail's documentation
+    # in order to change how emails will be delivered:
+    # https://github.com/mikel/mail
+    #
+    # This requires the 'mail' gem to be installed.
+    class Email
+
+      # @param [Hash] Options to create an email notification.
+      # @option options [String] :from The "from" email field
+      # @option options [String] :to Where e-mails will be delivered
+      # @option options [String] :subject The email's subject
+      def initialize(options={})
+        @from    = options[:from]
+        @to      = options[:to]
+        @subject = options[:subject] || 'Outpost notification'
+
+        unless @from && @to
+          raise ArgumentError, 'You need to set :from and :to to send emails.'
+        end
+      end
+
+      # Issues a notification through email. This is a callback, called by
+      # an Outpost instance.
+      # @param [Outpost::Application, #read] outpost an instance of an outpost, containing
+      #   latest status, messages and reports that can be queried to build
+      #   a notification message.
+      def notify(outpost)
+        mail         = Mail.new
+        mail.from    = @from
+        mail.to      = @to
+        mail.subject = @subject
+        mail.body    = build_message(outpost)
+
+        mail.deliver
+      end
+
+      private
+      def build_message(outpost)
+        status = outpost.last_status.to_s
+
+        message  = "This is the report for #{outpost.name}: "
+        message += "System is #{status.upcase}!\n\n"
+
+        message += outpost.messages.join("\n")
+      end
+    end
+  end
+end
+

data/lib/outpost/report.rb

@@ -1,13 +1,19 @@
 module Outpost
+  # Contain the status report of an Outpost execution. Holds the name,
+  # description and status of the reported item.
   class Report
-    # summarizes the list of statuses in a single status only.
+    # Summarizes the list of statuses in a single status only.
     # The logic is rather simple - it will return the lowest status
     # present in the list.
     #
     # Examples:
     #
     # if passed [:up, :up, :up], will result on :up
+    #
     # if passed [:up, :down, :up], will result on :down
+    #
+    # @params [Array] status_list a list of statuses to be analyzed
+    # @return [Symbol] the final status to be considered.
     def self.summarize(status_list)
       return :down if status_list.empty? || status_list.include?(:down)
       return :up

data/lib/outpost/scout.rb

@@ -1,11 +1,69 @@
 module Outpost
+  # Scouts are responsible for gathering data about a something specific that is
+  # a part of your system. For example, a HTTP Scout is responsible for getting
+  # the response code (200 for OK, 404 for Page Not Found, etc.), response
+  # body and any other thing you might want to know.
+  #
+  #
+  # Scouts must also contain expectations. They must be registered into the
+  # Scout that wish to support different types of expectations. You can supply
+  # a block or an object that respond to #call and return true if any of the
+  # rules match. It will receive an instance of the scout (so you can query
+  # current system state) as the first parameter and the state defined by the
+  # Outpost as the second.
+  #
+  #
+  # Example:
+  #   expect(:response_code) do |scout, code|
+  #     scout.response_code == code
+  #   end
+  #
+  # @example an example of a Scout that parses the HTTP response code
+  #   module Outpost
+  #     module Scouts
+  #       class Http < Outpost::Scout
+  #         expect(:response_code) { |scout,code| scout.response_code == code }
+  #
+  #         attr_reader :response_code
+  #
+  #         def setup(options)
+  #           @host = options[:host]
+  #           @port = options[:port] || 80
+  #           @path = options[:path] || '/'
+  #         end
+  #
+  #         def execute
+  #           response = Net::HTTP.get_response(@host, @path, @port)
+  #           @response_code = response.code.to_i
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # @abstract Subclasses must override {#setup} and {#execute} to be a valid
+  #   Scout
   class Scout
     class << self
 
+      # Returns the hash of expectations, where the key is the name of the
+      # expectation and the value is the callable Object (object that responds
+      # to #call)
+      #
+      # @return [Hash<Symbol, Object>]
       def expectations
         @expectations ? @expectations.dup : []
       end
 
+      # Registers a new expectation into the Scout. If the callable does not
+      # respond to #call, an ArgumentError will be raised.
+      #
+      # @param [Symbol, #read] expectation The name of the expectation
+      #   (examples: :response_code, :response_time)
+      # @param [Object, #read] callable An object that responds to call and
+      #   returns a Boolean. It will be executed whenever a Scout is run.
+      #   A block is also accepted.
+      # @raise [ArgumentError] raised when the callable parameter does not
+      #   respond to #call method.
       def expect(expectation, callable=nil, &callable_block)
         callable ||= callable_block
 
@@ -18,6 +76,10 @@ module Outpost
       end
     end
 
+    # @param [String, #read] description A string containing a description of
+    #   the Scout so it may be identified in the construction of status reports.
+    # @param [Hash, #read] config A hash containing any number of
+    #   configurations that will be passed to the #setup method
     def initialize(description, config)
       @description = description
       @config      = config
@@ -25,9 +87,21 @@ module Outpost
       setup(config.options)
     end
 
+    # Executes the Scout and go through all the registered expectations to find
+    # out all expectations that match and return the associated status.
+    #
+    # @return [Symbol] the current status of the Scout (:up, :down)
+    # @raise [NotImplementedError] raised when a configured expectation was not
+    #   registered in the Scout.
     def run
       statuses = []
       execute
+      # Response_pair contains the expectation as key and the expected value as
+      # value.
+      # Example: {:response_time => 200}
+      #
+      # status is the status (:up or :down, for example) that will be returned
+      # in case the expectation match current system status.
       @config.reports.each do |response_pair, status|
         response_pair.each do |expectation, value|
           if self.class.expectations[expectation].nil?
@@ -44,10 +118,18 @@ module Outpost
       Report.summarize(statuses)
     end
 
+    # Called when the scout object is being constructed. Arguments can be
+    # everything the developer set in the creation of Outpost.
+    #
+    # @raise [NotImplementedError] raised when method is not overriden.
     def setup(*args)
       raise NotImplementedError, 'You must implement the setup method for Scout to work correctly.'
     end
 
+    # Called when the Scout must take action and gather all the data needed to
+    # be analyzed.
+    #
+    # @raise [NotImplementedError] raised when method is not overriden.
     def execute(*args)
       raise NotImplementedError, 'You must implement the execute method for Scout to work correctly.'
     end

data/lib/outpost/scout_config.rb

@@ -1,9 +1,16 @@
 module Outpost
+  # Provides the DSL used to configure Scouts in Outposts.
   class ScoutConfig
     attr_reader :options, :reports
 
-    # Reads/writes any options. It will passed
-    # down to the scout.
+    def initialize
+      @reports = {}
+      @options = {}
+    end
+
+    # Reads/writes any options. It will passed down to the Scout.
+    # @param [Object] args Any argument that will be passed to the Scout.
+    # Rreturn [Object] The associated option
     def options(args=nil)
       if args.nil?
         @options
@@ -21,10 +28,9 @@ module Outpost
     #   status = 200
     #   params = {:response_code => 200}
     #
-    #   gets stored as:
+    # gets stored as:
     #    {:response_code => 200} = up
     def report(status, params)
-      @reports ||= {}
       @reports[params] = status
     end
   end

data/lib/outpost/scouts/http.rb

@@ -1,27 +1,48 @@
 require 'net/http'
-require 'outpost'
-
 require 'outpost/expectations'
 
 module Outpost
   module Scouts
+    # Uses ruby's own Net:HTTP to send HTTP requests and evaluate response
+    # body, response time and response code.
+    #
+    # * Responds to response_time expectation
+    #   ({Outpost::Expectations::ResponseTime})
+    # * Responds to response_code expectation
+    #   ({Outpost::Expectations::ResponseCode})
+    # * Responds to response_body expectation
+    #   ({Outpost::Expectations::ResponseBody})
+    #
     class Http < Outpost::Scout
       extend Outpost::Expectations::ResponseCode
       extend Outpost::Expectations::ResponseBody
 
       attr_reader :response_code, :response_body
 
+      # Configure the scout with given options.
+      # @param [Hash] Options to setup the scout
+      # @option options [String] :host The host that will be connected to.
+      # @option options [Number] :port The port that will be used to.
+      # @option options [String] :path The path that will be fetched from the
+      #   host.
+      # @option options [String] :http_class The class that will be used to
+      #   fetch the page, defaults to Net::HTTP
       def setup(options)
-        @host = options[:host]
-        @port = options[:port] || 80
-        @path = options[:path] || '/'
+        @host       = options[:host]
+        @port       = options[:port]       || 80
+        @path       = options[:path]       || '/'
+        @http_class = options[:http_class] || Net::HTTP
       end
 
+      # Runs the scout, connecting to the host and getting the response code,
+      # body and time.
       def execute
-        # FIXME Apply Dependency Injection Principle here
-        response = Net::HTTP.get_response(@host, @path, @port)
+        response = @http_class.get_response(@host, @path, @port)
+
         @response_code = response.code.to_i
         @response_body = response.body
+      rescue SocketError, Errno::ECONNREFUSED
+        @response_code = @response_body = nil
       end
     end
   end

data/lib/outpost/scouts/ping.rb

@@ -1,21 +1,41 @@
-require 'net/ping/external'
+begin
+  require 'net/ping/external'
+rescue LoadError => e
+  puts "Please install net-ping gem: gem install net-ping".
+  raise
+end
+
+require 'outpost/expectations'
 
 module Outpost
   module Scouts
+    # Uses system's "ping" command line tool to check if the server is
+    # responding in a timely manner.
+    #
+    # * Responds to response_time expectation
+    #   ({Outpost::Expectations::ResponseTime})
+    #
+    # It needs the 'net-ping' gem.
     class Ping < Outpost::Scout
       extend Outpost::Expectations::ResponseTime
       attr_reader :response_time
 
+
+      # Configure the scout with given options.
+      # @param [Hash] Options to setup the scout
+      # @option options [String] :host The host that will be "pinged".
+      # @option options [Object] :pinger An object that can ping hosts.
+      #   Defaults to Net::Ping::External.new
       def setup(options)
-        @host = options[:host]
+        @host   = options[:host]
+        @pinger = options[:pinger] || Net::Ping::External.new
       end
 
+      # Runs the scout, pinging the host and getting the duration.
       def execute
-        # FIXME Apply Dependency Injection Principle here
-        pinger = Net::Ping::External.new
-        if pinger.ping(@host)
+        if @pinger.ping(@host)
           # Miliseconds
-          @response_time = pinger.duration * 100
+          @response_time = @pinger.duration * 1000
         end
       end
     end

data/lib/outpost/version.rb

@@ -1,3 +1,6 @@
 module Outpost
-  VERSION = "0.1.0".freeze
+  PATCH = 0
+  MINOR = 2
+  MAJOR = 0
+  VERSION = "#{MAJOR}.#{MINOR}.#{PATCH}".freeze
 end