logrotate 1.0.0 → 1.1.0

data/History.txt

@@ -1,2 +1,11 @@
+=== 1.1.0 / 2008-08-20
+* Enhanced the rotate file methods to return status information
+  regarding the rotation: the newly rotated file, the list of rotated
+  files, the list of deleted files, etc.
+* Refactored the implementation of the file rotation methods into a
+  separate class (LogRotate::Impl) and exposed a few of these
+  implementation methods for public use.
+
 === 1.0.0 / 2008-06-19
 Initial release of LogRotate.  This package is unit tested fully.
+

data/Manifest.txt

@@ -4,4 +4,7 @@ History.txt
 README.txt
 Rakefile
 lib/logrotate.rb
+lib/logrotate/impl.rb
+lib/logrotate/logrotate.rb
+lib/logrotate/rotateinfo.rb
 test/test_logrotate.rb

data/README.txt

@@ -1,6 +1,4 @@
-= logrotate
-* Project Page: http://rubyforge.org/projects/logrotate/
-* Documentation: http://logrotate.rubyforge.org/
+Object
 
 == DESCRIPTION:
 
@@ -24,27 +22,158 @@ None (known).
 == SYNOPSIS:
 Here are some sample invocations of the library.
 
-Rotate a log file with simple extensions: .1, .2, etc, keep 10 rotated
-files around (.1 .. .10), and gzip the rotated files (.1.gz, .2.gz, .. .10.gz): 
-======+examples/rotate_count.rb+:
+Rotate a log file with simple extensions: .1, .2, etc, keep 3 rotated
+files around (.1 .. .3), and gzip the rotated files (.1.gz, .. .3.gz): 
+======<tt>examples/rotate_count.rb</tt>:
  #!/usr/bin/env ruby
  
+ require 'fileutils'
  require 'rubygems'
  require 'logrotate'
  
  options = {
-   :count => 10, 
+   :count => 2,
    :gzip => true
  }
  
- LogRotate.rotate_file("/tmp/erwin.dat", options)
+ 1.upto(3) do |iteration|
+   
+   FileUtils.touch("/tmp/erwin.dat")
+   result = LogRotate.rotate_file("/tmp/erwin.dat", options)
+   
+   print "=================================================\n"
+   print "Iteration \##{iteration}\n"
+   print "=================================================\n"
+   print result, "\n"
+ end
+ 
+ # clean up all files created by this example
+ FileUtils.rm_f(Dir.glob('/tmp/erwin.dat.*'))
+
+======<tt>Output</tt>:
+ =================================================
+ Iteration #1
+ =================================================
+ Rotated Files And Counts:
+    file -> /tmp/erwin.dat.1.gz, index -> 1
+ Rotated Files: 
+    /tmp/erwin.dat.1.gz
+ Deleted Files:
+ New Rotated File: 
+    /tmp/erwin.dat.1.gz
+ 
+ =================================================
+ Iteration #2
+ =================================================
+ Rotated Files And Counts:
+    file -> /tmp/erwin.dat.1.gz, index -> 1
+    file -> /tmp/erwin.dat.2.gz, index -> 2
+ Rotated Files: 
+    /tmp/erwin.dat.1.gz
+    /tmp/erwin.dat.2.gz
+ Deleted Files:
+ New Rotated File: 
+    /tmp/erwin.dat.1.gz
+ 
+ =================================================
+ Iteration #3
+ =================================================
+ Rotated Files And Counts:
+    file -> /tmp/erwin.dat.1.gz, index -> 1
+    file -> /tmp/erwin.dat.2.gz, index -> 2
+ Rotated Files: 
+    /tmp/erwin.dat.1.gz
+    /tmp/erwin.dat.2.gz
+ Deleted Files:
+    /tmp/erwin.dat.2.gz
+ New Rotated File: 
+    /tmp/erwin.dat.1.gz
+ 
+
+
+Rotate a log file with date/time extensions.
+======<tt>examples/rotate_date_time.rb</tt>:
+ #!/usr/bin/env/ruby
+ 
+ require 'fileutils'
+ require 'rubygems'
+ require 'logrotate'
+ 
+ options = { 
+   :date_time_ext => true, 
+   :date_time_format => '%F_%T',
+   :count => 2
+ }
+ 
+ 1.upto(3) do |iteration|
+   
+   FileUtils.touch("/tmp/erwin.dat")
+   result = LogRotate.rotate_file("/tmp/erwin.dat", options)
+   
+   print "=================================================\n"
+   print "Iteration \##{iteration}\n"
+   print "=================================================\n"
+   print result, "\n"
+ 
+   # Sleep for a short period so that next time rotate_file is called,
+   # the current second will be different (and thus the rotated file
+   # name will be different than the last).
+   sleep(1.5)
+ end
+ 
+ # clean up all files created by this example
+ FileUtils.rm_f(Dir.glob('/tmp/erwin.dat.*'))
+
+======<tt>Output</tt>:
+ =================================================
+ Iteration #1
+ =================================================
+ Rotated Files And Dates:
+    file -> /tmp/erwin.dat.2008-08-21_12:37:39, date_time -> 2008-08-21T12:37:39+00:00
+    file -> /tmp/erwin.dat.2008-08-21_12:37:37, date_time -> 2008-08-21T12:37:37+00:00
+ Rotated Files: 
+    /tmp/erwin.dat.2008-08-21_12:37:39
+    /tmp/erwin.dat.2008-08-21_12:37:37
+ Deleted Files:
+ New Rotated File: 
+    /tmp/erwin.dat.2008-08-21_12:37:39
+ 
+ =================================================
+ Iteration #2
+ =================================================
+ Rotated Files And Dates:
+    file -> /tmp/erwin.dat.2008-08-21_12:37:41, date_time -> 2008-08-21T12:37:41+00:00
+    file -> /tmp/erwin.dat.2008-08-21_12:37:39, date_time -> 2008-08-21T12:37:39+00:00
+ Rotated Files: 
+    /tmp/erwin.dat.2008-08-21_12:37:41
+    /tmp/erwin.dat.2008-08-21_12:37:39
+ Deleted Files:
+    /tmp/erwin.dat.2008-08-21_12:37:37
+ New Rotated File: 
+    /tmp/erwin.dat.2008-08-21_12:37:41
+ 
+ =================================================
+ Iteration #3
+ =================================================
+ Rotated Files And Dates:
+    file -> /tmp/erwin.dat.2008-08-21_12:37:42, date_time -> 2008-08-21T12:37:42+00:00
+    file -> /tmp/erwin.dat.2008-08-21_12:37:41, date_time -> 2008-08-21T12:37:41+00:00
+ Rotated Files: 
+    /tmp/erwin.dat.2008-08-21_12:37:42
+    /tmp/erwin.dat.2008-08-21_12:37:41
+ Deleted Files:
+    /tmp/erwin.dat.2008-08-21_12:37:39
+ New Rotated File: 
+    /tmp/erwin.dat.2008-08-21_12:37:42
+ 
 
 
 Rotate a set of log files with date extensions, and move the rotated
 files to a specified directory:
-======+examples/rotate_date.rb+:
+======<tt>examples/rotate_date.rb</tt>:
  #!/usr/bin/env ruby
  
+ require 'fileutils'
  require 'rubygems'
  require 'logrotate'
  
@@ -64,29 +193,19 @@ files to a specified directory:
  }
  
  LogRotate.rotate_files(files, options)
-
-
-Rotate a log file with date/time extensions.
-======+examples/rotate_date_time.rb+:
- #!/usr/bin/env/ruby
  
- require 'rubygems'
- require 'logrotate'
- 
- options = { 
-   :date_time_ext => true, 
-   :date_time_format => '%F_%T'
- }
- 
- LogRotate.rotate_file("/tmp/erwin.dat", options)
+ # clean up all files and directories created by this example
+ FileUtils.rm_f(Dir.glob"/tmp/erwin*.dat")
+ FileUtils.rm_rf("/tmp/archives")
 
 
 Rotate a log file that is currently being written to by a live
 process.  After the file is rotated, notify the live process to reopen
 its log file.  
-======+examples/rotate_live.rb+:
+======<tt>examples/rotate_live.rb</tt>:
  #!/usr/bin/env ruby
  
+ require 'fileutils'
  require 'rubygems'
  require 'logrotate'
  
@@ -104,6 +223,9 @@ its log file.
  }
  
  LogRotate.rotate_file("/tmp/hupper.dat", options)
+ 
+ # clean up all files created by this example
+ FileUtils.rm_rf(Dir.glob("/tmp/hupper*"))
 
 
 == REQUIREMENTS:
@@ -119,12 +241,12 @@ Hoe is required but only for running the tests.
 * Homepage: http://www.designingpatterns.com
 * Blogs: http://blogs.designingpatterns.com
 
-== SUPPORT
+== SUPPORT:
 Please post questions, concerns, or requests for enhancement to the forums on
 the project page.  Alternatively, direct contact information for
 Designing Patterns can be found on the project page for this gem.
 
-== ENHANCEMENTS
+== ENHANCEMENTS:
 Please feel free to contact us with any ideas; we will try our best to
 enhance the software and respond to user requests.  Of course, we are more
 likely to work on a particular enhancement if we know that there are users

data/Rakefile

@@ -2,7 +2,7 @@
 require 'rubygems'
 require 'hoe'
 
-Hoe.new('logrotate', "1.0.0") do |p|
+Hoe.new('logrotate', "1.1.0") do |p|
   p.remote_rdoc_dir = ''
   p.developer('DesigningPatterns', 'technical.inquiries@designingpatterns.com')
 end

data/lib/logrotate.rb

@@ -1,246 +1,3 @@
-#!/usr/bin/env ruby 
-
-require 'English'
-require 'zlib'
-require 'date'
-
-#
-# This module provides a few methods for log rotation.
-#
-
-module LogRotate
-
-  DEFAULT_COUNT = 5
-  DEFAULT_GZIP = false
-  DEFAULT_DATE_TIME_EXTENSION = false
-  
-  DEFAULT_DATE_TIME_FORMAT = '%F'
-
-  # 
-  # ====Description: This method rotates the given files.  
-  # 
-  # ====Parameters:
-  # [file(s)]
-  #      The files to be rotated.
-  # [options = {}]
-  #      A list of optional arguments.
-  #
-  # See rotate_file for details.
-  #
-  def self.rotate_files(files, options)
-    files.each do |file|
-      rotate_single_file(file, options)
-    end
-  end
-  
-  # 
-  # ====Description: This method rotates the given file(s).  
-  # There are 2 types of extensions that can be used: the default
-  # extension which is an integer value (".1", ".2", ..), and a
-  # date/time extension (".2008-08-01", ..).  If a date/time extension
-  # is chosen, the caller can specify a date/time format for this
-  # extension.
-  # 
-  # ====Parameters:
-  # [file]
-  #      The file to be rotated.
-  # [options = {}]
-  #      A list of optional arguments.
-  #
-  # The optional arguments are listed below:
-  # +count+:: The number of rotated files to be kept.
-  # +directory+:: The directory to store the newly rotated file.  If this
-  #               option is unspecified, the original file's directory 
-  #               will be used.
-  # +date_time_ext+:: Whether the extension on the rotated files should be
-  #                   a date.  Possible values are: +true+, +false+.
-  # +date_time_format+:: For use with +date_time_ext+.  This specifies the
-  #                      format of the date / time extension.
-  # +date_time+:: For use with +date_time_ext+.  The +DateTime+ that will be
-  #               used to construct the extension of the newly rotated file.  
-  #               If this option is not specified, the current date and time 
-  #               will be used.
-  # +pre_rotate+:: A +Proc+ to be executed before the rotation is started.
-  # +post_rotate+:: A +Proc+ to be executed after the rotation is finished,
-  #                 and before the newly rotated file is zipped.
-  # +gzip+:: Whether the newly rotated file should be gzipped.  Possible 
-  #          values are: +true+, +false+.
-  #
-  def self.rotate_file(file, options)
-      rotate_single_file(file, options)
-  end
-    
-  def self.rotate_single_file(file, options = {})
-    gzip = options[:gzip] ? options[:gzip] : DEFAULT_GZIP
-    
-    # error checking
-    if (!File.exist?(file)) then raise "File does not exist: #{file}." end
-    if (!File.readable?(file)) then raise "File is not readable: #{file}." end
-    
-    if (options[:pre_rotate]) then options[:pre_rotate].call() end
-    
-    new_backup = ""
-    if (options[:date_time_ext])
-      new_backup = rotate_file_date_extension(file, options)
-    else
-      new_backup = rotate_file_integer_extension(file, options)
-    end
-    
-    if (options[:post_rotate]) then options[:post_rotate].call() end
-    
-    if (gzip) then gzip_file(new_backup) end
-  end
-  private_class_method(:rotate_single_file)
-
-  def self.rotate_file_date_extension(file, options)
-    count = options[:count] ? options[:count] : DEFAULT_COUNT
-    
-    now = options[:date_time] ? options[:date_time] : DateTime.now()
-    
-    date_time_format = options[:date_time_format] ? options[:date_time_format] : DEFAULT_DATE_TIME_FORMAT
-    
-    # Get a list of the rotated files.
-    (source_directory, base_name) = File.split(file)
-    directory = options[:directory] ? options[:directory] : source_directory
-    
-    rotated_files = Dir.entries(directory).map do |entry| 
-      rslt = nil
-      
-      # Validate the rotated file.  Since the caller is allowed to
-      # specify the date/time format, here we do not have a regular
-      # expression to match the date/time portion of the rotated
-      # file's extension.  As a result, some foreign files can sneak
-      # into our list of rotated files (eg. base_file.GARBAGE.gz).  Thus,
-      # the rotated file is validated below, and if invalid, it is 
-      # skipped / left alone / not considered in the rotation.
-      
-      if (entry.match("^#{base_name}\..+(\.gz)?$"))
-
-        # Validation #1: convert the date/time portion of the
-        # extension to a DateTime object and skip the file if an
-        # exception is thrown.
-        begin
-          match_data = entry.match("\.([^.]+)(\.gz)?$")
-          date_time = DateTime.strptime(match_data[1], date_time_format)
-          gz = match_data[2] ? match_data[2] : ""
-          
-          # Validation #2: convert the date/time portion of the
-          # extension to a DateTime object and back to a string again.
-          # Then reconstruct the rotated file name with this string,
-          # and ensure the reconstructed rotated file matches the
-          # original.  This will take into account cases where
-          # strptime succeeded but had additional garbage characters
-          # present.  
-          # eg: date_time_format = '%F', file = 'mysql_backup.2008-08-04.BACK.gz'
-          reconstructed_file = "#{base_name}.#{date_time.strftime(date_time_format)}#{gz}"
-          if (entry == reconstructed_file)
-            rslt = { :date_time => date_time, :file => entry }        
-          end
-        rescue => e
-        end
-        
-        rslt
-      end
-    end
-    
-    rotated_files = rotated_files.select { |rotated_file| rotated_file }
-    
-    # Sort files by date (newer to older).
-    rotated_files.sort! { |left, right| right[:date_time] <=> left[:date_time] }
-    
-    # Remove the oldest files so that there are count rotated files remaining.
-    
-    # Determine how many old files to be removed.  
-    new_backup_base_name = base_name + "." + now.strftime(date_time_format)
-
-    # Add 1 to account for the additional rotated file that will be
-    # created after the original file passed in is rotated.
-    num_old_files = rotated_files.length() - count + 1
-
-    # There is a chance that the newly rotated file will have the same
-    # name as one of the already existing rotated files (eg. if the
-    # extension is simply the date, and the job is ran a second time
-    # in the same day).  In this case, there will be 1 less rotated
-    # file (and thus 1 less to delete).
-    if (rotated_files.find {|rotated_file| rotated_file[:file] == new_backup_base_name})
-      num_old_files -= 1
-    end
-    
-    if (num_old_files > 0)
-      old_files = rotated_files.slice!(-num_old_files, num_old_files)
-      File.unlink(*old_files.map {|old_file| File.join(directory, old_file[:file]) })
-    end
-    
-    # Rename the original file.
-    new_backup = File.join(directory, new_backup_base_name)
-    File.rename(file, new_backup)
-    
-    return new_backup
-  end
-  private_class_method(:rotate_file_date_extension)
-  
-  def self.rotate_file_integer_extension(file, options)
-    count = options[:count] ? options[:count] : DEFAULT_COUNT
-    
-    # Get a list of the backed up files.
-    (source_directory, base_name) = File.split(file)
-    directory = options[:directory] ? options[:directory] : source_directory
-    
-    rotated_files = Dir.entries(directory).select do |entry| 
-      entry.match("#{base_name}\.[0-9]+(\.gz)?$") 
-    end
-
-    rotated_files.map! do |rotated_file|
-      index = rotated_file.match("\.([0-9]+)(\.gz)?$")[1].to_i()
-      { :index => index, :file => rotated_file }
-    end
-    
-    # Delete old files.
-    old_files = rotated_files.select { |rotated_file| rotated_file[:index] >= count }
-    File.unlink(*old_files.map {|old_file| File.join(directory, old_file[:file]) })
-    
-    rotated_files = rotated_files - old_files
-    
-    # Sort files such that the back up count is descending (eg. [hello.txt.5, hello.txt.4, ..]).
-    rotated_files.sort! { |left, right| right[:index] <=> left[:index] }
-
-    # Rotate - Increment the back up index on each file.
-    rotated_files.each do |rotated_file|
-
-      new_index = rotated_file[:index] + 1
-      new_file = rotated_file[:file].sub(/(^.*\.)(#{rotated_file[:index]})(.gz)?$/, 
-                                           "\\1#{new_index}\\3")
-      File.rename(File.join(directory, rotated_file[:file]), 
-                  File.join(directory, new_file))
-    end
-    
-    # Rename the original file.
-    new_backup = File.join(directory, base_name + ".1")
-    File.rename(file, new_backup)
-    
-    return new_backup
-  end
-  private_class_method(:rotate_file_integer_extension)
-
-  def self.gzip_file(file)
-    # Zip the original file if necessary.
-    gzip_file = file + ".gz"
-
-    begin
-      File.open(file) do |file_stream|
-        Zlib::GzipWriter.open(gzip_file) do |gz|
-          while (buffer = file_stream.read(1024))
-            gz.write(buffer)
-          end
-        end
-      end
-    rescue => error
-      raise "Unable to zip file: #{file}. Error: #{error}\n"
-    end
-    
-    File.unlink(file)
-  end
-  private_class_method(:gzip_file)
-
-end
+#!/usr/bin/env ruby
 
+require 'logrotate/logrotate'