paparazzi 0.1.1 → 0.2.0

data/README.md

@@ -10,8 +10,8 @@ to previously existing unchanged files, allowing for frequent backups to be made
 directories (see 'How it works' below). Older snapshots maintain versions of files as they existed
 at the time that snapshot was made.
 
-Paparazzi automatically purges out old hourly, daily, weekly, and monthly snapshots. Yearly
-snapshots are not automatically purged and need to be removed manually when necessary.
+Paparazzi automatically purges out old snapshots, and allows you to define how many of each snapshot
+to keep in reserve.
 
 Installation
 ------------
@@ -30,11 +30,36 @@ Create a ruby script that you'll run hourly from a cron.
     settings = {
       :source => '/full/path/to/source/directory/',           # note the trailing '/'
       :destination => '/mnt/external_drive/backup_folder',
-      :rsync_flags => '-L  --exclude lost+found'              # see 'man rsync' for available options.
-    }                                                         # Paparazzi sends '-aq --delete', plus whatever you add.
+      :rsync_flags => '-L --exclude lost+found'
+    }                                                         
 
     Paparazzi::Camera.trigger(settings)
     
+    
+Available Settings
+------------------
+
+  * `:source`      : **required** The source folder to be backed up. Trailing '/' recommended. See rsync manpage
+                     for explanation of trailing '/' 
+  * `:destination` : **required** The destination folder for backups to be written to, preferably on a different
+                     physical drive.
+  * `:reserves`    : A hash of snapshot intervals and number of snapshots of each to keep before purging.
+                     default: {:hourly => 24, :daily => 7, :weekly => 5, :monthly => 12, :yearly => 9999} 
+  * `:rsync_flags` : additional flags to pass to rsync. Paparazzi uses -aq, --delete, & --link_dest, plus
+                     whatever you add. The author suggests considering -L and --exclude.
+
+
+Supported Operating Systems
+---------------------------
+
+Paparazzi is developed and tested on Ubuntu Linux and should work fine on all other flavors. As of version 0.1.1, all
+tests reportedly passed on Max OSX, and it is expected that Paparazzi will probably run very well in that environment
+(although it is not actively tested, so run at your own risk).
+
+It is highly unlikely that Paparazzi will run on an MS Windows based machine without a whole lot of TLC by the user,
+if it runs at all. At a minimum, the user will need to get rsync installed on the machine, possibly through cygwin,
+but this is not supported at all by the author and users are entirely on their own.
+
 
 How it works.
 -------------

data/lib/paparazzi/camera.rb

@@ -1,19 +1,19 @@
 require 'admit_one'
 require 'yaml'
 require 'fileutils'
+require 'digest/md5'
 
 module Paparazzi
   class Camera
-    FREQUENCIES = [:hourly,:daily,:weekly,:monthly,:yearly]
     REQUIRED_SETTINGS = [:source,:destination]
       
     class << self
-      attr_accessor :source, :destination, :rsync_flags
+      attr_accessor :source, :destination, :rsync_flags, :reserves
       
       def trigger(settings = {})
         validate_and_cache_settings(settings)
-        AdmitOne::LockFile.new(:paparazzi) do
-          initialize
+        AdmitOne::LockFile.new("paparazzi-#{Digest::MD5.hexdigest(destination)}") do
+          setup
           purge_old_snapshots
           make_snapshots
         end
@@ -25,7 +25,7 @@ module Paparazzi
       #######
       
       def validate_and_cache_settings(settings)
-        [:source,:destination,:rsync_flags].each do |setting_name|
+        [:source,:destination,:rsync_flags,:reserves].each do |setting_name|
           if REQUIRED_SETTINGS.include?(setting_name) and settings[setting_name].nil?
             raise MissingSettingError, "#{setting_name} is required"
           else
@@ -40,18 +40,18 @@ module Paparazzi
         raise MissingFolderError, destination unless File.exist?(destination) and File.directory?(destination)
       end
       
-      def initialize
+      def setup
         @previous_snapshot_name = {}
-        FREQUENCIES.each do |frequency|
+        frequencies.each do |frequency|
           Dir.mkdir(destination(frequency)) unless File.exists?(destination(frequency)) && File.directory?(destination(frequency))
         
           full_path = Dir[destination(frequency)+'/*'].sort{|a,b| File.ctime(b) <=> File.ctime(a) }.first
           @previous_snapshot_name[frequency] = full_path ? File.basename(full_path) : ''
         end
         
-        if @previous_snapshot_name[:hourly] != last_successful_hourly_snapshot and !last_successful_hourly_snapshot.nil? and File.exists?(destination(:hourly) + '/' + last_successful_hourly_snapshot)
-          File.rename(previous_snapshot(:hourly), current_snapshot(:hourly))
-          @previous_snapshot_name[:hourly] = last_successful_hourly_snapshot
+        if @previous_snapshot_name[frequencies.first] != last_successful_snapshot and !last_successful_snapshot.nil? and File.exists?(destination(frequencies.first) + '/' + last_successful_snapshot)
+          File.rename(previous_snapshot(frequencies.first), current_snapshot(frequencies.first))
+          @previous_snapshot_name[frequencies.first] = last_successful_snapshot
         end
       end
       
@@ -59,20 +59,20 @@ module Paparazzi
         frequency.nil? ? @destination : "#{@destination}/#{frequency}"
       end
       
-      def last_successful_hourly_snapshot
-        @last_successful_hourly_snapshot ||= File.exists?("#{destination}/.paparazzi.yml") ? YAML.load_file("#{destination}/.paparazzi.yml")[:last_successful_snapshot] : nil
+      def last_successful_snapshot
+        @last_successful_snapshot ||= File.exists?("#{destination}/.paparazzi.yml") ? YAML.load_file("#{destination}/.paparazzi.yml")[:last_successful_snapshot] : nil
       end
       
-      def last_successful_hourly_snapshot=(string)
+      def last_successful_snapshot=(string)
         cached_data ||= File.exists?("#{destination}/.paparazzi.yml") ? YAML.load_file("#{destination}/.paparazzi.yml") : {}
         cached_data[:last_successful_snapshot] = string
         File.open("#{destination}/.paparazzi.yml", 'w') {|file| file.write(cached_data.to_yaml) }
       end
     
       def purge_old_snapshots
-        keepers = {:hourly => 24, :daily => 7, :weekly => 5, :monthly => 12}
-        keepers.keys.each do |frequency|
-          while Dir[destination(frequency)+'/*'].size > keepers[frequency]-1
+        frequencies.each do |frequency|
+          #raise RuntimeError, frequency if reserves[frequency].nil?
+          while Dir[destination(frequency)+'/*'].size > (reserves[frequency]-1)
             full_path = Dir[destination(frequency)+'/*'].sort{|a,b| File.ctime(a) <=> File.ctime(b) }.first
             FileUtils.rm_rf(full_path)
           end
@@ -80,14 +80,14 @@ module Paparazzi
       end
 
       def make_snapshots
-        FREQUENCIES.each do |frequency|
+        frequencies.each do |frequency|
           Dir.mkdir(current_snapshot(frequency)) unless File.exists?(current_snapshot(frequency))
-          if frequency == :hourly and previous_snapshot_name(frequency) == ''
+          if frequency == frequencies.first and previous_snapshot_name(frequency) == ''
             system 'rsync', *(['-aq', '--delete'] + rsync_flags + [source, current_snapshot(frequency)])
-            self.last_successful_hourly_snapshot = current_snapshot_name(:hourly)
+            self.last_successful_snapshot = current_snapshot_name(frequency)
           elsif previous_snapshot_name(frequency) != current_snapshot_name(frequency)
             system 'rsync', *(['-aq', '--delete', "--link-dest=#{link_destination(frequency)}"] + rsync_flags + [source, current_snapshot(frequency)])
-            self.last_successful_hourly_snapshot = current_snapshot_name(:hourly)
+            self.last_successful_snapshot = current_snapshot_name(frequencies.first)
           end
         end
       end
@@ -116,7 +116,17 @@ module Paparazzi
       end
       
       def link_destination(frequency)
-        frequency == :hourly ? "../#{previous_snapshot_name(:hourly)}" : "../../hourly/#{current_snapshot_name(:hourly)}"
+        frequency == frequencies.first ? "../#{previous_snapshot_name(frequencies.first)}" : "../../#{frequencies.first}/#{current_snapshot_name(frequencies.first)}"
+      end
+      
+      def reserves
+        @reserves ||= {:hourly => 24, :daily => 7, :weekly => 5, :monthly => 12, :yearly => 9999}
+      end
+      
+      def frequencies
+        reserves.keys.select{ |key| reserves[key] > 0 }.sort{ |a,b| 
+          [:hourly,:daily,:weekly,:monthly,:yearly].find_index(a) <=> [:hourly,:daily,:weekly,:monthly,:yearly].find_index(b)
+        }  
       end
       
     end

data/lib/paparazzi/version.rb

@@ -1,3 +1,3 @@
 module Paparazzi
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/test/unit/camera_test.rb

@@ -3,9 +3,10 @@ require 'test/unit'
 require 'fileutils'
 
 class CameraTest < Test::Unit::TestCase
+  FREQUENCIES = [:hourly,:daily,:weekly,:monthly,:yearly]
   
   def setup
-    Paparazzi::Camera::FREQUENCIES.each do |frequency|
+    FREQUENCIES.each do |frequency|
       FileUtils.rm_rf("#{destination}/#{frequency}")
     end
     FileUtils.rm_rf("#{destination}/.paparazzi.yml")
@@ -31,18 +32,18 @@ class CameraTest < Test::Unit::TestCase
   end
   
   def test_should_create_frequency_folders_on_initialization
-    Paparazzi::Camera::FREQUENCIES.each do |frequency|
+    FREQUENCIES.each do |frequency|
       assert(!File.exists?("#{destination}/#{frequency}"))
     end
     Paparazzi::Camera.trigger(default_test_settings)
-    Paparazzi::Camera::FREQUENCIES.each do |frequency|
+    FREQUENCIES.each do |frequency|
       assert(File.exists?("#{destination}/#{frequency}"))
     end
   end
   
   def test_should_make_all_first_snapshots_of_source
     Paparazzi::Camera.trigger(default_test_settings)
-    Paparazzi::Camera::FREQUENCIES.each do |frequency|
+    FREQUENCIES.each do |frequency|
       assert(Dir["#{destination}/#{frequency}/*"].size > 0,"#{destination}/#{frequency}/ is empty")
       file = File.open(%Q{#{Dir["#{destination}/#{frequency}/*"].first}/test.txt})
       assert_equal('This is a test, this is only a test.',file.gets)
@@ -54,20 +55,22 @@ class CameraTest < Test::Unit::TestCase
     assert(YAML.load_file("#{destination}/.paparazzi.yml")[:last_successful_snapshot].match(/\d{4}-\d{2}-\d{2}\.\d{2}/))
   end
   
-  def test_purges_out_expired_snapshots
+  def test_should_purge_out_expired_snapshots
     Dir.mkdir("#{destination}/weekly")
-    (1..5).each do |x|
+    Dir.mkdir("#{destination}/weekly/1")
+    sleep 1;
+    (2..5).each do |x|
       Dir.mkdir("#{destination}/weekly/#{x}")
-      sleep 1;
     end
     assert_equal(5,Dir["#{destination}/weekly/*"].size)
     previous_folder_contents = Dir["#{destination}/weekly/*"]
     Paparazzi::Camera.trigger(default_test_settings)
     assert_equal(5,Dir["#{destination}/weekly/*"].size)
+    assert(!File.exists?("#{destination}/weekly/1"))
     assert_not_equal(previous_folder_contents,Dir["#{destination}/weekly/*"])
   end
   
-  def test_gracefully_recovers_if_last_hourly_snapshot_ended_prematurely
+  def test_should_gracefully_recover_if_last_hourly_snapshot_ended_prematurely
     Paparazzi::Camera.instance_variable_set('@start_time',Time.now - 7200)
     Paparazzi::Camera.trigger(default_test_settings)
     successful_snapshot_name = Paparazzi::Camera.send(:current_snapshot_name,:hourly)
@@ -76,7 +79,7 @@ class CameraTest < Test::Unit::TestCase
     Paparazzi::Camera.trigger(default_test_settings)
     failed_snapshot_name = Paparazzi::Camera.send(:current_snapshot_name,:hourly)
     
-    Paparazzi::Camera.send(:last_successful_hourly_snapshot=,successful_snapshot_name)
+    Paparazzi::Camera.send(:last_successful_snapshot=,successful_snapshot_name)
     assert_equal(2,Dir["#{destination}/hourly/*"].size)
     assert_equal(successful_snapshot_name,YAML.load_file("#{destination}/.paparazzi.yml")[:last_successful_snapshot])
     
@@ -88,16 +91,27 @@ class CameraTest < Test::Unit::TestCase
     assert(!Dir["#{destination}/hourly/*"].include?("#{destination}/hourly/#{failed_snapshot_name}"))
   end
   
-  def test_correct_hard_links_are_created_to_multiple_snapshots_of_same_file
+  def test_should_create_hard_links_to_multiple_snapshots_of_same_file
     Paparazzi::Camera.trigger(default_test_settings)
-    assert_equal(5,File.stat("#{destination}/hourly/#{Paparazzi::Camera.send(:current_snapshot_name,:hourly)}/test.txt").nlink)   
+    inode = File.stat("#{destination}/hourly/#{Paparazzi::Camera.send(:current_snapshot_name,:hourly)}/test.txt").ino
+    FREQUENCIES.each do |frequency|
+      assert_equal(5,File.stat("#{destination}/#{frequency}/#{Paparazzi::Camera.send(:current_snapshot_name,frequency)}/test.txt").nlink)   
+      assert_equal(inode,File.stat("#{destination}/#{frequency}/#{Paparazzi::Camera.send(:current_snapshot_name,frequency)}/test.txt").ino)
+    end
   end
   
-  def test_excluded_files_are_not_backed_up
+  def test_should_not_backup_excluded_files
     Paparazzi::Camera.trigger(default_test_settings)
     assert(!File.exists?("#{destination}/hourly/#{Paparazzi::Camera.send(:current_snapshot_name,:hourly)}/test.exclude"))
   end
   
+  def test_should_not_make_un_requested_frequency_snapshots
+    my_settings = default_test_settings
+    my_settings[:reserves][:hourly] = 0
+    Paparazzi::Camera.trigger(my_settings)
+    assert(!File.exists?("#{destination}/hourly"))
+  end
+  
   #######
   private
   #######
@@ -110,7 +124,9 @@ class CameraTest < Test::Unit::TestCase
     {
       :source => "#{File.expand_path('../../source',  __FILE__)}/",
       :destination => destination,
+      :reserves => {:hourly => 24, :daily => 7, :weekly => 5, :monthly => 12, :yearly => 9999},
       :rsync_flags => '-L --exclude test.exclude'
+      
     }
   end
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 1
-  version: 0.1.1
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Jonathan S. Garvin
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-22 00:00:00 -06:00
+date: 2011-05-23 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency