evanescent 1.0.3 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f2393af3e93eeb53ec45a8392fa56b72a35735a5
-  data.tar.gz: 8c5e60dc35ff8ea1c57a236bc3930965f67ded39
+  metadata.gz: 6f14da7d6ca2902263af5f1beb2ed7e5dcf1292b
+  data.tar.gz: fd56792706e49bf8b2a6b4bae1462cdfc07748cc
 SHA512:
-  metadata.gz: bc1391185e9633931792141d36dbfd28b0f86bb861e0a4fdb9b8471ad2288c8c1dbd7f8c2385cf942248c3d6853ccf8cfb1a34f3ce0bfdcb7d5b5fd9c88b2367
-  data.tar.gz: f8fac72778804d08224ae46abe08d3fbc046ed5604c09d6936d07164e805e7d1e7c0cec239956fa4794defe5a30873782dd499cef3ba001cf3f42791010dc803
+  metadata.gz: 14749bb864d45f29e2149d99f34ff6570172ac1d7063f57995047a9665a88429bd0c1f8df352cbde8a534c39e95511464f7a05b4c8da427997723024febe1362
+  data.tar.gz: 4d587a7ebed997339cb32c668d4e1074db764fa78387a1c4e27c2ed26a9d1141f1d89740b423baa418f028df72f0a169b9961c002c83c8c6bb574e628813b38d

data/README.md

@@ -0,0 +1,87 @@
+# evanescent
+
+[![Build Status](https://travis-ci.org/fornellas/evanescent.svg?branch=master)](https://travis-ci.org/fornellas/evanescent)
+[![Gem Version](https://badge.fury.io/rb/evanescent.svg)](http://badge.fury.io/rb/evanescent)
+[![GitHub issues](https://img.shields.io/github/issues/fornellas/evanescent.svg)](https://github.com/fornellas/evanescent/issues)
+[![GitHub license](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://raw.githubusercontent.com/fornellas/evanescent/master/LICENSE)
+[![Downloads](http://ruby-gem-downloads-badge.herokuapp.com/evanescent?type=total)](https://rubygems.org/gems/evanescent)
+
+* Home: [https://github.com/fornellas/evanescent/](https://github.com/fornellas/evanescent/)
+* Bugs: [https://github.com/fornellas/evanescent/issues](https://github.com/fornellas/evanescent/issues)
+
+## Description
+
+This gem provides an IO like object, that can be used with any logging class (such as Ruby's native Logger). This object will save its input to a file, and allows:
+
+* Hourly or daily rotation.
+* Compression of rotated files.
+* Removal of old compressed files.
+
+This functionality supplement logging classes, allowing everything related to logging management, to be done within Ruby, without relying on external tools (such as logrotate).
+
+## Install
+
+    gem install evanescent
+
+This gem uses [Semantic Versioning](http://semver.org/), so you should add to your .gemspec something like:
+
+```ruby
+  s.add_runtime_dependency 'evanescent', '~> 1.0'
+```
+
+Please, always check latest [available](https://rubygems.org/gems/evanescent) version!
+
+## Example
+
+### Logger
+
+```ruby
+require 'evanescent'
+require 'timecop'
+
+logger = Evanescent.logger(
+  path: 'test.log',
+  rotation: :hourly,
+  keep: '2 hours',
+)
+
+logger.class # => Logger
+
+# Within first hour, only test.log will exist.
+Timecop.freeze(Time.now)
+logger.info 'first message'
+Dir.entries('.') # => [".", "..", "test.log"]
+
+# One hour later, rotation and compression will happen.
+Timecop.freeze(Time.now + 3600)
+logger.info 'second message'
+Dir.entries('.') # => [".", "..", "test.log", "test.log.2015122315.gz"]
+
+# Another hour later, we'll have 2 compressed files.
+Timecop.freeze(Time.now + 3600)
+logger.info 'third message'
+Dir.entries('.') # => [".", "..", "test.log", "test.log.2015122315.gz", "test.log.2015122316.gz"]
+
+# At last, after keep period, old compressed files are purged.
+Timecop.freeze(Time.now + 3600)
+logger.info 'fourth message'
+Dir.entries('.') # => [".", "..", "test.log", "test.log.2015122316.gz", "test.log.2015122317.gz"]
+```
+
+### Generic usage
+
+Evanescent is an IO like object: it responds to <tt>:write</tt> and <tt>:close</tt>:
+
+```ruby
+io = Evanescent.new(
+  path: 'test.log',
+  rotation: :hourly,
+  keep: '2 hours',
+)
+io.write('message') # writes message to test.log
+io.close
+```
+
+## Limitations
+
+Although Evanescent supports mult-thread operation, inter-process locking is not currently implemented, and behavior is unpredicted in this situation.

data/lib/evanescent.rb

@@ -3,10 +3,12 @@ require 'fileutils'
 require 'zlib'
 
 # IO like object, that can be used with any logging class (such as Ruby's native Logger). This object will save its input to a file, and allows:
-#* Rotation by time / date.
-#* Compression of old files.
-#* Removal of old compressed files.
-# Its purpuse is to supplement logging classes, allowing everything related to logging management, to be done within Ruby, without relying on external tools (such as logrotate).
+#
+# * Hourly or daily rotation.
+# * Compression of rotated files.
+# * Removal of old compressed files.
+#
+# This functionality supplement logging classes, allowing everything related to logging management, to be done within Ruby, without relying on external tools (such as logrotate).
 class Evanescent
   # Current path being written to.
   attr_reader :path
@@ -17,16 +19,27 @@ class Evanescent
   # How long rotated files are kept (in seconds).
   attr_reader :keep
 
+  # Shortcut for: <tt>Logger.new(Evanescent.new(opts))</tt>.
+  # Requires logger if needed.
+  def self.logger opts
+    unless Object.const_defined? :Logger
+      require 'logger'
+    end
+    Logger.new(
+      self.new(opts)
+    )
+  end
+
   # Must receive a Hash with:
   # +:path+:: Path where to write to.
   # +:rotation+:: Either +:hourly+ or +:daily+.
-  # +:keep+:: For how long to keep rotated files. It is parsed with ChronicDuration's natural language features. Examples: '1 day', '1 month'.
+  # +:keep+:: For how long to keep rotated files. It is parsed with chronic_duration Gem natural language features. Examples: '1 day', '1 month'.
   def initialize opts
     @path = opts[:path]
     @rotation = opts[:rotation]
     @keep = ChronicDuration.parse(opts[:keep])
     @mutex = Mutex.new
-    @last_prefix = make_prefix(Time.now)
+    @last_prefix = make_suffix(Time.now)
     @io = nil
     @compress_thread = nil
   end
@@ -34,11 +47,22 @@ class Evanescent
   # Writes to #path and rotate, compress and purge if necessary.
   def write string
     @mutex.synchronize do
-      rotate
-      compress
-      purge
+      if new_path = rotation_path
+        # All methods here must have exceptions threated. See:
+        # https://github.com/ruby/ruby/blob/3e92b635fb5422207b7bbdc924e292e51e21f040/lib/logger.rb#L647
+        purge
+        mv_path(new_path)
+        compress
+      end
       open_io
-      @io.write(string)
+      if @io
+        # No exceptions threated here, they should be handled by caller. See:
+        # https://github.com/ruby/ruby/blob/3e92b635fb5422207b7bbdc924e292e51e21f040/lib/logger.rb#L653
+        @io.write(string)
+      else
+        warn("Unable to log: '#{path}' not open!")
+        0
+      end
     end
   end
 
@@ -49,13 +73,13 @@ class Evanescent
     end
   end
 
-  # Compression is done in a separate thread. Thus method suspends current thread execution until existing compression thread returns. If no compression thread is running, returns immediately.
+  # Compression is done in a separate thread. This method suspends current thread execution until existing compression thread returns. If no compression thread is running, returns immediately.
   def wait_compression
     if @compress_thread
       begin
         @compress_thread.join
       rescue
-        warn("Compression thread failed: #{$!}")
+        warn("Compression thread failed: #{$!} (#{$!.class})")
       ensure
         @compress_thread = nil
       end
@@ -64,13 +88,6 @@ class Evanescent
 
   private
 
-  def open_io
-    unless @io
-      @io = File.open(path, File::APPEND | File::CREAT | File::WRONLY)
-      @io.sync = true
-    end
-  end
-
   PARAMS = {
     hourly: {
       strftime: '%Y%m%d%H',
@@ -84,42 +101,63 @@ class Evanescent
     }
   }
 
-  def make_prefix time
+  def make_suffix time
     time.strftime(PARAMS[rotation][:strftime])
   end
 
-  def rotate
-    if @io
-      rotate_with_open_io
-    else
-      rotate_with_closed_io
+  def open_io
+    unless @io
+      @io = File.open(path, File::APPEND | File::CREAT | File::WRONLY)
+      @io.sync = true
     end
+  rescue
+    warn("Unable to open '#{path}': #{$!} (#{$!.class})")
   end
 
-  def rotate_with_open_io
-    curr_suffix = make_prefix(Time.now)
-    return if curr_suffix == @last_prefix
-    @io.close
-    @io = nil
-    do_rotation("#{path}.#{curr_suffix}")
-    @last_prefix = curr_suffix
+  # Returns new path for rotation. If no rotation is needed, returns nil.
+  def rotation_path
+    if @io
+      curr_suffix = make_suffix(Time.now)
+      return nil if curr_suffix == @last_prefix
+      # Same as https://github.com/ruby/ruby/blob/3e92b635fb5422207b7bbdc924e292e51e21f040/lib/logger.rb#L760
+      begin
+        @io.close
+      rescue
+        warn("Error closing '#{path}': #{$!} (#{$!.class})")
+      end
+      @io = nil
+      @last_prefix = curr_suffix
+      "#{path}.#{curr_suffix}"
+    else
+      return nil unless File.exist?(path)
+      curr_suffix = make_suffix(Time.now+PARAMS[rotation][:interval])
+      rotation_suffix = make_suffix(File.mtime(path) + PARAMS[rotation][:interval])
+      return nil if curr_suffix == rotation_suffix
+      @last_prefix = curr_suffix
+      "#{path}.#{rotation_suffix}"
+    end
   end
 
-  def rotate_with_closed_io
-    return unless File.exist?(path)
-    curr_suffix = make_prefix(Time.now+PARAMS[rotation][:interval])
-    rotation_suffix = make_prefix(File.mtime(path) + PARAMS[rotation][:interval])
-    return if curr_suffix == rotation_suffix
-    do_rotation("#{path}.#{rotation_suffix}")
-    @last_prefix = curr_suffix
+  def purge
+    Dir.glob("#{path}.#{PARAMS[rotation][:glob]}.gz").each do |compressed|
+      time_extractor = Regexp.new(
+        '^' + Regexp.escape("#{path}.") + "(?<time>.+)" + Regexp.escape(".gz") + '$'
+      )
+      time_string = compressed.match(time_extractor)[:time]
+      compressed_time = Time.strptime(time_string, PARAMS[rotation][:strftime])
+      age = Time.now - compressed_time
+      if age >= keep
+        File.delete(compressed)
+      end
+    end
+  rescue
+    warn("Error purging old files: #{$!} (#{$!.class})")
   end
 
-  def do_rotation new_path
-    begin
-      FileUtils.mv(path, new_path)
-    rescue
-      warn("Error renaming '#{path}' to '#{new_path}': #{$!}")
-    end
+  def mv_path new_path
+    FileUtils.mv(path, new_path)
+  rescue
+    warn("Error renaming '#{path}' to '#{new_path}': #{$!} (#{$!.class})")
   end
 
   def compress
@@ -141,23 +179,7 @@ class Evanescent
       end
     end
   rescue
-    warn("Error compressing files: #{$!}")
-  end
-
-  def purge
-    Dir.glob("#{path}.#{PARAMS[rotation][:glob]}.gz").each do |compressed|
-      time_extractor = Regexp.new(
-        '^' + Regexp.escape("#{path}.") + "(?<time>.+)" + Regexp.escape(".gz") + '$'
-      )
-      time_string = compressed.match(time_extractor)[:time]
-      compressed_time = Time.strptime(time_string, PARAMS[rotation][:strftime])
-      age = Time.now - compressed_time
-      if age > keep
-        File.delete(compressed)
-      end
-    end
-  rescue
-    warn("Error purging old files: #{$!}")
+    warn("Error compressing files: #{$!} (#{$!.class})")
   end
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: evanescent
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.1.0
 platform: ruby
 authors:
 - Fabio Pugliese Ornellas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-17 00:00:00.000000000 Z
+date: 2015-12-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chronic_duration
@@ -123,13 +123,19 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/evanescent.rb
 homepage: https://github.com/fornellas/evanescent
 licenses:
 - GPLv3
 metadata: {}
 post_install_message: 
-rdoc_options: []
+rdoc_options:
+- "--markup=rdoc"
+- "--main=README.md"
+- "--visibility=public"
+- lib/
+- README.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement