logging-email 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1bec69b79f5915cefb82f3e508cab7ad91a39db5
+  data.tar.gz: ab809782f91dfd82dcba5db696d82995f66f0c02
+SHA512:
+  metadata.gz: a38bb7864a2b3b7f1cb9a0270a31b141099d13a59d3df015b904611a3a4475141a1226f5d0a3f463558fa85b47554019290ccc98ce24535893db30528037042d
+  data.tar.gz: 1d23540f311dc715ab8b3952bc67b37698cf6a50bf38610e1b24ba45c76045efd0b21d45d79e91fbc922403b61cca5f3d7bda5f3199f14927bcfbb23a484442f

data/.gitignore

@@ -0,0 +1,14 @@
+# git-ls-files --others --exclude-from=.git/info/exclude
+# Lines that start with '#' are comments.
+# For a project mostly in C, the following would be a good set of
+# exclude patterns (uncomment them if you want to use them):
+# *.[oa]
+# *~
+announcement.txt
+coverage/
+doc/
+pkg/
+tmp/
+vendor/
+.rbx
+.rvmrc

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+
+before_install: "gem install bones"
+install:        "rake gem:install_dependencies"
+
+script: "rake"
+
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.5
+  - 2.2.1
+

data/README.md

@@ -0,0 +1,114 @@
+## Logging Email Appender
+by Tim Pease [![](https://secure.travis-ci.org/TwP/logging-email.png)](https://travis-ci.org/TwP/logging-email)
+
+* [Homepage](http://rubygems.org/gems/logging-email)
+* [Github Project](https://github.com/TwP/logging-email)
+
+### Description
+
+The Logging email appender provides a way to send log messages via email from
+a Ruby application. This is useful if you wish to be notified of exceptions or
+fatal errors as they arise.
+
+The email appender was originally part of the Logging framework proper, but with
+the release of Logging 2.0.0, it has been extracted into its own gem.
+
+### Installation
+
+The Logging framework uses the [little-plugger](https://github.com/twp/little-plugger)
+gem based plugin system. All that needs to be done to start using the email
+appender is to install the gem.
+
+```
+gem install logging-email
+```
+
+The plugin system will automatically detect and load the plugin when the Logging
+framework is first initialized.
+
+### Examples
+
+The example below configures an email appender and gives it the name "gmail".
+This name will be used later to add the appender to our logger.
+
+The appender itself is configured to send email via the Google's Gmail servers.
+This requires a user name and password; we load these from environment
+variables. The Gmail SMTP servers also require `STARTTLS` to be enabled so that
+TLS or SSL encryption can be used for communication.
+
+The email appender is configured to buffer log messages. The log messages will
+be sent in a single email when either 20 log messages have been buffered or one
+minute has passed since the first log message was buffered. This helps reduce
+the overall volume of email. The caveat here is that if there is a fatal error
+and the application crashes, these log message **will not** be sent out via
+email; they will be lost.
+
+```ruby
+require 'logging'
+Logging.init      # initialize the framework and load plugins
+
+Logger.appenders.email 'gmail',
+    :from       => "server@example.com",
+    :to         => "developers@example.com",
+    :subject    => "Application Error [#{%x(uname -n).strip}]",
+    :address    => "smtp.gmail.com",
+    :port       => 443,
+    :domain     => "gmail.com",
+    :user_name  => ENV["GMAIL_USER"],
+    :password   => ENV["GMAIL_PASS"],
+    :authentication => :plain,
+    :enable_starttls_auto => true,
+    :auto_flushing => 20,      # send an email after 20 messages have been buffered
+    :flush_period  => 60,      # send an email after one minute
+    :level         => :error   # only process log events that are "error" or "fatal"
+
+logger = Logging.logger['example_logger']
+logger.level = :info
+
+logger.add_appenders \
+    Logging.appenders['gmail'],             # lookup the gmail email appender
+    Logging.appenders.file('example.log')
+
+logger.debug "this debug message will not be output by the logger"
+logger.info "just some friendly advice"
+logger.error exception                      # this `exception` will be emailed
+```
+
+### Development
+
+The `logging-email` source code relies on the Mr Bones project for default rake
+tasks. You will need to install the Mr Bones gem if you want to build or test
+the `logging-email` gem. Conveniently there is a bootstrap script that you can
+run to setup your development environment.
+
+```
+script/bootstrap
+```
+
+This will install the Mr Bones gem and the required Ruby gems for development.
+After this is done you can rake `rake -T` to see the available rake tasks.
+
+### License
+
+The MIT License
+
+Copyright (c) 2015 Tim Pease
+
+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/Rakefile

@@ -0,0 +1,29 @@
+begin
+  require 'bones'
+rescue LoadError
+  abort '### please install the "bones" gem ###'
+end
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'logging/plugins/email'
+
+task :default => 'test:run'
+task 'gem:release' => 'test:run'
+
+Bones {
+  name         'logging-email'
+  summary      'An email appender for the Ruby Logging framework'
+  authors      'Tim Pease'
+  email        'tim.pease@gmail.com'
+  url          'http://rubygems.org/gems/logging-email'
+  version      Logging::Plugins::Email::VERSION
+
+  use_gmail
+
+  depend_on 'logging',   '~> 2.0'
+
+  depend_on 'flexmock',  '~> 1.0', :development => true
+  depend_on 'bones-git', '~> 1.3', :development => true
+}

data/lib/logging/appenders/email.rb

@@ -0,0 +1,176 @@
+require 'net/smtp'
+require 'time' # get rfc822 time format
+
+module Logging
+  module Appenders
+
+    # Accessor / Factory for the Email appender.
+    def self.email( *args )
+      return ::Logging::Appenders::Email if args.empty?
+      ::Logging::Appenders::Email.new(*args)
+    end
+
+    # Provides an appender that can send log messages via email to a list of
+    # recipients.
+    #
+    class Email < ::Logging::Appender
+      include Buffering
+
+      attr_reader :authentication, :to, :port
+      attr_accessor :address, :domain, :from, :subject
+      attr_accessor :user_name, :password, :enable_starttls_auto
+
+      # call-seq:
+      #    Email.new( name, :from => 'me@example.com', :to => 'you@example.com', :subject => 'Whoops!' )
+      #
+      # Create a new email appender that will buffer messages and then send them
+      # out in batches to the listed recipients. See the options below to
+      # configure how emails are sent through you mail server of choice. All the
+      # buffering options apply to the email appender.
+      #
+      # The following options are required:
+      #
+      #  :from - The base filename to use when constructing new log
+      #          filenames.
+      #  :to   - The list of email recipients either as an Array or a comma
+      #          separated list.
+      #
+      # The following options are optional:
+      #
+      #  :subject   - The subject line for the email.
+      #  :address   - Allows you to use a remote mail server. Just change it
+      #               from its default "localhost" setting.
+      #  :port      - On the off chance that your mail server doesn't run on
+      #               port 25, you can change it.
+      #  :domain    - If you need to specify a HELO domain, you can do it here.
+      #  :user_name - If your mail server requires authentication, set the user
+      #               name in this setting.
+      #  :password  - If your mail server requires authentication, set the
+      #               password in this setting.
+      #  :authentication - If your mail server requires authentication, you need
+      #                    to specify the authentication type here. This is a
+      #                    symbol and one of :plain (will send the password in
+      #                    the clear), :login (will send password Base64
+      #                    encoded) or :cram_md5 (combines a Challenge/Response
+      #                    mechanism to exchange information and a cryptographic
+      #                    Message Digest 5 algorithm to hash important
+      #                    information)
+      #  :enable_starttls_auto - When set to true, detects if STARTTLS is
+      #                          enabled in your SMTP server and starts to use it.
+      #
+      # Example:
+      #
+      # Setup an email appender that will buffer messages for up to 1 minute,
+      # and only send messages for ERROR and FATAL messages. This example uses
+      # Google's Gmail SMTP server with authentication to send out messages.
+      #
+      #   Logger.appenders.email( 'gmail',
+      #       :from       => "server@example.com",
+      #       :to         => "developers@example.com",
+      #       :subject    => "Application Error [#{%x(uname -n).strip}]",
+      #
+      #       :address    => "smtp.gmail.com",
+      #       :port       => 443,
+      #       :domain     => "gmail.com",
+      #       :user_name  => ENV["GMAIL_USER"],
+      #       :password   => ENV["GMAIL_PASS"],
+      #       :authentication => :plain,
+      #       :enable_starttls_auto => true,
+      #
+      #       :auto_flushing => 200,     # send an email after 200 messages have been buffered
+      #       :flush_period  => 60,      # send an email after one minute
+      #       :level         => :error   # only process log events that are "error" or "fatal"
+      #   )
+      #
+      def initialize( name, opts = {} )
+        opts[:header] = false
+        super(name, opts)
+
+        af = opts.fetch(:buffsize, opts.fetch(:buffer_size, 100))
+
+        configure_buffering({:auto_flushing => af}.merge(opts))
+
+        # get the SMTP parameters
+        self.from = opts.fetch(:from, nil)
+        raise ArgumentError, 'Must specify from address' if @from.nil?
+
+        self.to = opts.fetch(:to, nil)
+        raise ArgumentError, 'Must specify recipients' if @to.empty?
+
+        self.subject   = opts.fetch(:subject, "Message from #{$0}")
+        self.address   = opts.fetch(:server, opts.fetch(:address, 'localhost'))
+        self.port      = opts.fetch(:port, 25)
+        self.domain    = opts.fetch(:domain, (ENV['HOSTNAME'] || 'localhost.localdomain'))
+        self.user_name = opts.fetch(:acct,   opts.fetch(:user_name, nil))
+        self.password  = opts.fetch(:passwd, opts.fetch(:password,  nil))
+        self.enable_starttls_auto = opts.fetch(:enable_starttls_auto, false)
+        self.authentication = opts.fetch(:authtype, opts.fetch(:authentication, :plain))
+      end
+
+      # Close the email appender. If the layout contains a foot, it will not be
+      # sent as an email.
+      #
+      def close( *args )
+        super(false)
+      end
+
+      # If your mail server requires authentication, you need to specify the
+      # authentication type here. This is a symbol and one of :plain (will send
+      # the password in the clear), :login (will send password Base64 encoded)
+      # or :cram_md5 (combines a Challenge/Response mechanism to exchange
+      # information and a cryptographic Message Digest 5 algorithm to hash
+      # important information)
+      #
+      def authentication=( val )
+        @authentication = val.to_s.to_sym
+      end
+
+      # On the off chance that your mail server doesn't run on port 25, you can
+      # change it.
+      #
+      def port=( val )
+        @port = Integer(val)
+      end
+
+      # The list of email recipients. This can either be an Array of recipients
+      # or a comma separated list. A single recipient is also valid.
+      #
+      #   email.to = ['mike@example.com', 'tony@example.com']
+      #   email.to = 'alicia@example.com'
+      #   email.to = 'bob@example.com, andy@example.com, john@example.com'
+      #
+      def to=( val )
+        @to = val.respond_to?(:split) ?  val.split(',') : Array(val)
+      end
+
+
+    private
+
+      # This method is called by the buffering code when messages need to be
+      # sent out as an email.
+      #
+      def canonical_write( str )
+        ### build a mail header for RFC 822
+        rfc822msg =  "From: #{@from}\n"
+        rfc822msg << "To: #{@to.join(",")}\n"
+        rfc822msg << "Subject: #{@subject}\n"
+        rfc822msg << "Date: #{Time.new.rfc822}\n"
+        rfc822msg << "Message-Id: <#{"%.8f" % Time.now.to_f}@#{@domain}>\n\n"
+
+        rfc822msg = rfc822msg.force_encoding(encoding) if encoding and rfc822msg.encoding != encoding
+        rfc822msg << str
+
+        ### send email
+        smtp = Net::SMTP.new(@address, @port)
+        smtp.enable_starttls_auto if @enable_starttls_auto and smtp.respond_to? :enable_starttls_auto
+        smtp.start(@domain, @user_name, @password, @authentication) { |s| s.sendmail(rfc822msg, @from, @to) }
+        self
+      rescue StandardError, TimeoutError => err
+        self.level = :off
+        ::Logging.log_internal {'e-mail notifications have been disabled'}
+        ::Logging.log_internal_error(err)
+      end
+
+    end
+  end
+end

data/lib/logging/plugins/email.rb

@@ -0,0 +1,15 @@
+module Logging
+  module Plugins
+    module Email
+      extend self
+
+      VERSION = '0.0.1'.freeze
+
+      # This method will be called by the Logging framework when it first
+      # initializes. Here we require the email appender code.
+      def initialize_email
+        require File.expand_path('../../appenders/email', __FILE__)
+      end
+    end
+  end
+end

data/script/bootstrap

@@ -0,0 +1,15 @@
+#!/usr/bin/env sh
+
+gem list -i bones >/dev/null 2>&1
+rc=$?
+if [[ $rc != 0 ]]; then
+  gem install bones
+fi
+
+gem list -i rdoc >/dev/null 2>&1
+rc=$?
+if [[ $rc != 0 ]]; then
+  gem install rdoc
+fi
+
+rake gem:install_dependencies

data/test/test_email.rb

@@ -0,0 +1,170 @@
+require 'flexmock'
+require 'logging'
+require Logging.path(%w[test setup])
+
+# initialize the Logging framework plugins
+Logging.initialize_plugins
+
+module TestLogging
+  module TestAppenders
+
+    class TestEmail < Test::Unit::TestCase
+      include FlexMock::TestCase
+      include LoggingTestCase
+
+      def setup
+        super
+
+        flexmock(Net::SMTP).new_instances do |m|
+          m.should_receive(:start).at_least.once.with(
+              'test.logging', 'test', 'test', :plain, Proc).and_yield(m)
+          m.should_receive(:sendmail).at_least.once.with(String, 'me', ['you'])
+        end
+
+        @appender = Logging.appenders.email('email',
+            :from => 'me', :to => 'you',
+            :buffer_size => '3', :immediate_at => 'error, fatal',
+            :domain => 'test.logging', :user_name => 'test', :password => 'test'
+        )
+        @levels = Logging::LEVELS
+      end
+
+      def test_initialize
+        assert_raise(ArgumentError, 'Must specify from address') {
+          Logging.appenders.email('email')
+        }
+        assert_raise(ArgumentError, 'Must specify to address') {
+          Logging.appenders.email('email', :from => 'me')
+        }
+        assert_nothing_raised {
+          Logging.appenders.email('email', :from => 'me', :to => 'you')
+        }
+
+        appender = Logging.appenders.email('email', :from => 'me', :to => 'you')
+
+        assert_equal(100, appender.auto_flushing)
+        assert_equal([], appender.instance_variable_get(:@immediate))
+        assert_equal('localhost', appender.address)
+        assert_equal(25, appender.port)
+
+        domain = ENV['HOSTNAME'] || 'localhost.localdomain'
+        assert_equal(domain, appender.domain)
+        assert_equal(nil, appender.user_name)
+        assert_equal(:plain, appender.authentication)
+        assert_equal("Message from #{$0}", appender.subject)
+
+        appender = Logging.appenders.email('email',
+            :from => 'lbrinn@gmail.com', :to => 'everyone',
+            :buffsize => '1000', :immediate_at => 'error, fatal',
+            :address => 'smtp.google.com', :port => '443',
+            :domain => 'google.com', :user_name => 'lbrinn',
+            :password => '1234', :authentication => 'plain', :enable_starttls_auto => true,
+            :subject => "I'm rich and you're not"
+        )
+
+        assert_equal('lbrinn@gmail.com', appender.instance_variable_get(:@from))
+        assert_equal(['everyone'], appender.instance_variable_get(:@to))
+        assert_equal(1000, appender.auto_flushing)
+        assert_equal('1234', appender.password)
+        assert_equal([nil, nil, nil, true, true],
+                     appender.instance_variable_get(:@immediate))
+        assert_equal('smtp.google.com', appender.address)
+        assert_equal(443, appender.port)
+        assert_equal('google.com', appender.domain)
+        assert_equal('lbrinn', appender.user_name)
+        assert_equal(:plain, appender.authentication)
+        assert(appender.enable_starttls_auto)
+        assert_equal("I'm rich and you're not", appender.subject)
+
+        appender = Logging.appenders.email('email',
+            :from => 'me', :to => 'you', :auto_flushing => 42
+        )
+        assert_equal(42, appender.auto_flushing)
+      end
+
+      def test_append
+        # with auto_flushing enabled, mail will be sent each time a log event
+        # occurs
+        @appender.auto_flushing = true
+        event = Logging::LogEvent.new('TestLogger', @levels['warn'],
+                                      [1, 2, 3, 4], false)
+        @appender.append event
+        assert_not_equal(@levels.length, @appender.level)
+        assert_equal(0, @appender.buffer.length)
+
+        # increase the buffer size and log a few events
+        @appender.auto_flushing = 3
+        @appender.append event
+        @appender.append event
+        assert_equal(2, @appender.buffer.length)
+
+        @appender.append event
+        assert_not_equal(@levels.length, @appender.level)
+        assert_equal(0, @appender.buffer.length)
+
+        # error and fatal messages should be send immediately (no buffering)
+        error = Logging::LogEvent.new('ErrLogger', @levels['error'],
+                                      'error message', false)
+        fatal = Logging::LogEvent.new('FatalLogger', @levels['fatal'],
+                                      'fatal message', false)
+
+        @appender.append event
+        @appender.append fatal
+        assert_not_equal(@levels.length, @appender.level)
+        assert_equal(0, @appender.buffer.length)
+
+        @appender.append error
+        assert_not_equal(@levels.length, @appender.level)
+        assert_equal(0, @appender.buffer.length)
+
+        @appender.append event
+        assert_equal(1, @appender.buffer.length)
+      end
+
+      def test_concat
+        # with auto_flushing enabled, mail will be sent each time a log event
+        # occurs
+        @appender.auto_flushing = true
+        @appender << 'test message'
+        assert_not_equal(@levels.length, @appender.level)
+        assert_equal(0, @appender.buffer.length)
+
+        # increase the buffer size and log a few events
+        @appender.auto_flushing = 3
+        @appender << 'another test message'
+        @appender << 'a second test message'
+        assert_equal(2, @appender.buffer.length)
+
+        @appender << 'a third test message'
+        assert_not_equal(@levels.length, @appender.level)
+        assert_equal(0, @appender.buffer.length)
+      end
+
+      def test_flush
+        event = Logging::LogEvent.new('TestLogger', @levels['info'],
+                                      [1, 2, 3, 4], false)
+        @appender.append event
+        @appender << 'test message'
+        assert_equal(2, @appender.buffer.length)
+
+        @appender.flush
+        assert_not_equal(@levels.length, @appender.level)
+        assert_equal(0, @appender.buffer.length)
+      end
+
+      def test_close
+        event = Logging::LogEvent.new('TestLogger', @levels['info'],
+                                      [1, 2, 3, 4], false)
+        @appender.append event
+        @appender << 'test message'
+        assert_equal(2, @appender.buffer.length)
+
+        @appender.close
+        assert_not_equal(@levels.length, @appender.level)
+        assert_equal(0, @appender.buffer.length)
+        assert(@appender.closed?)
+      end
+
+    end
+  end
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: logging-email
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Tim Pease
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logging
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: flexmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bones-git
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: bones
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.8.3
+description: |-
+  The Logging email appender provides a way to send log messages via email from
+  a Ruby application. This is useful if you wish to be notified of exceptions or
+  fatal errors as they arise.
+
+  The email appender was originally part of the Logging framework proper, but with
+  the release of Logging 2.0.0, it has been extracted into its own gem.
+email: tim.pease@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- README.md
+- Rakefile
+- lib/logging/appenders/email.rb
+- lib/logging/plugins/email.rb
+- script/bootstrap
+- test/test_email.rb
+homepage: http://rubygems.org/gems/logging-email
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: logging-email
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: An email appender for the Ruby Logging framework
+test_files:
+- test/test_email.rb