backup 3.0.3.build.0 → 3.0.3

data/lib/backup/notifier/base.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+module Backup
+  module Notifier
+    class Base
+      include Backup::Configuration::Helpers
+
+      ##
+      # When set to true, the user will be notified by email
+      # when a backup process ends without raising any exceptions
+      attr_accessor :on_success
+      alias :notify_on_success? :on_success
+
+      ##
+      # When set to true, the user will be notified by email
+      # when a backup process raises an exception before finishing
+      attr_accessor :on_failure
+      alias :notify_on_failure? :on_failure
+
+      ##
+      # Logs a message to the console and log file to inform
+      # the client that Backup is notifying about the process
+      def log!
+        Logger.message "#{ self.class } started notifying about the process."
+      end
+
+    end
+  end
+end

data/lib/backup/notifier/binder.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+
+module Backup
+  module Notifier
+    class Binder
+
+      ##
+      # Shortcut to create a new instance of a binder, setting
+      # the instance variables using a Hash of key/values and getting
+      # the instance's binding. This returns the binding of the new Binder instance
+      def self.bind(key_and_values = {})
+        Binder.new(key_and_values).get_binding
+      end
+
+      ##
+      # Creates a new Backup::Notifier::Binder instance. Loops through the provided
+      # Hash to set instance variables
+      def initialize(key_and_values)
+        key_and_values.each do |key, value|
+          instance_variable_set("@#{key}", value)
+        end
+      end
+
+      ##
+      # Returns the binding (needs a wrapper method because #binding is a private method)
+      def get_binding
+        binding
+      end
+
+    end
+  end
+end

data/lib/backup/notifier/mail.rb

@@ -0,0 +1,141 @@
+# encoding: utf-8
+
+##
+# Only load the Mail gem and Erb library when using Mail notifications
+require 'mail'
+require 'erb'
+
+module Backup
+  module Notifier
+    class Mail < Base
+
+      ##
+      # Container for the Mail object
+      attr_accessor :mail
+
+      ##
+      # Container for the Model object
+      attr_accessor :model
+
+      ##
+      # Sender and Receiver email addresses
+      # Examples:
+      #  sender   - my.email.address@gmail.com
+      #  receiver - your.email.address@gmail.com
+      attr_accessor :from, :to
+
+      ##
+      # The address to use
+      # Example: smtp.gmail.com
+      attr_accessor :address
+
+      ##
+      # The port to connect to
+      # Example: 587
+      attr_accessor :port
+
+      ##
+      # Your domain (if applicable)
+      # Example: mydomain.com
+      attr_accessor :domain
+
+      ##
+      # Username and Password (sender email's credentials)
+      # Examples:
+      #  user_name - meskyanichi
+      #  password  - my_secret_password
+      attr_accessor :user_name, :password
+
+      ##
+      # Authentication type
+      # Example: plain
+      attr_accessor :authentication
+
+      ##
+      # Automatically set TLS
+      # Example: true
+      attr_accessor :enable_starttls_auto
+
+      ##
+      # Instantiates a new Backup::Notifier::Mail object
+      def initialize(&block)
+        load_defaults!
+
+        instance_eval(&block) if block_given?
+
+        set_defaults!
+      end
+
+      ##
+      # Performs the notification
+      # Takes an exception object that might've been created if an exception occurred.
+      # If this is the case it'll invoke notify_failure!(exception), otherwise, if no
+      # error was raised, it'll go ahead and notify_success!
+      #
+      # If'll only perform these if on_success is true or on_failure is true
+      def perform!(model, exception = false)
+        @model = model
+
+        if notify_on_success? and exception.eql?(false)
+          log!
+          notify_success!
+        elsif notify_on_failure? and not exception.eql?(false)
+          log!
+          notify_failure!(exception)
+        end
+      end
+
+    private
+
+      ##
+      # Sends an email informing the user that the backup operation
+      # proceeded without any errors
+      def notify_success!
+        mail[:subject] = "[Backup::Succeeded] #{model.label} (#{model.trigger})"
+        mail[:body]    = read_template('notify_success', Binder.bind(:model => @model))
+        mail.deliver!
+      end
+
+      ##
+      # Sends an email informing the user that the backup operation
+      # raised an exception and will send the user the error details
+      def notify_failure!(exception)
+        mail[:subject] = "[Backup::Failed] #{model.label} (#{model.trigger})"
+        mail[:body]    = read_template('notify_failure', Binder.bind(:model => @model, :exception => exception))
+        mail.deliver!
+      end
+
+      ##
+      # Configures the Mail gem by setting the defaults.
+      # Instantiates the @mail object with the @to and @from attributes
+      def set_defaults!
+        defaults = {
+          :address              => @address,
+          :port                 => @port,
+          :domain               => @domain,
+          :user_name            => @user_name,
+          :password             => @password,
+          :authentication       => @authentication,
+          :enable_starttls_auto => @enable_starttls_auto
+        }
+
+        ::Mail.defaults do
+          delivery_method :smtp, defaults
+        end
+
+        @mail        = ::Mail.new
+        @mail[:from] = @from
+        @mail[:to]   = @to
+      end
+
+      ##
+      # Returns the path to the templates, appended by the passed in argument
+      def read_template(file, binder)
+        ERB.new(File.read(
+          File.join( File.dirname(__FILE__), "templates", "#{file}.erb" )
+        )).result(binder)
+      end
+
+    end
+  end
+end

data/lib/backup/notifier/templates/notify_failure.erb

@@ -0,0 +1,31 @@
+
+There seemed to be a problem backing up <%= @model.label %> (<%= @model.trigger %>).
+
+===========================================================================
+Exception that got raised:
+<%= @exception.to_s %>
+===========================================================================
+<%= @exception.backtrace.join("\n") %>
+===========================================================================
+
+
+You are running Backup version:
+<%= Backup::Version.current %>
+
+You are running Ruby version:
+<%= ENV["RUBY_VERSION"] %>
+
+
+---------------------------------------------------------------------------
+
+View all Backup gem releases here:
+http://rubygems.org/gems/backup
+
+View the Backup git repository here:
+https://github.com/meskyanichi/backup
+
+View the Backup issues here:
+https://github.com/meskyanichi/backup/issues
+
+View the Backup wiki here:
+https://github.com/meskyanichi/backup/wiki

data/lib/backup/notifier/templates/notify_success.erb

@@ -0,0 +1,16 @@
+
+Backup <%= @model.label %> (<%= @model.trigger %>) finished without any errors!
+
+---------------------------------------------------------------------------
+
+View all Backup gem releases here:
+http://rubygems.org/gems/backup
+
+View the Backup git repository here:
+https://github.com/meskyanichi/backup
+
+View the Backup issues here:
+https://github.com/meskyanichi/backup/issues
+
+View the Backup wiki here:
+https://github.com/meskyanichi/backup/wiki

data/lib/backup/storage/base.rb

@@ -0,0 +1,67 @@
+# encoding: utf-8
+
+module Backup
+  module Storage
+    class Base
+      include Backup::Configuration::Helpers
+
+      ##
+      # The time when the backup initiated (in format: 2011.02.20.03.29.59)
+      attr_accessor :time
+
+      ##
+      # Sets the limit to how many backups to keep in the remote location.
+      # If the limit exceeds it will remove the oldest backup to make room for the newest
+      attr_accessor :keep
+
+      ##
+      # Returns the local path
+      def local_path
+        TMP_PATH
+      end
+
+      ##
+      # Returns the local archive filename
+      def local_file
+        @local_file ||= File.basename(Backup::Model.file)
+      end
+
+      ##
+      # Returns the name of the file that's stored on the remote location
+      def remote_file
+        @remote_file ||= local_file
+      end
+
+      ##
+      # Provider defaults to false and will be overridden when using
+      # a service-based storage such as Amazon S3, Rackspace Cloud Files or Dropbox
+      def provider
+        false
+      end
+
+      ##
+      # Checks the persisted storage data by type (S3, CloudFiles, SCP, etc)
+      # to see if the amount of stored backups is greater than the amount of
+      # backups allowed. If this is the case it'll invoke the #remove! method
+      # on each of the oldest backups that exceed the storage limit (specified by @keep).
+      # After that it'll re-assign the objects variable with an array of objects that still remain
+      # after the removal of the older objects and files (that exceeded the @keep range). And finally
+      # these remaining objects will be converted to YAML format and are written back to the YAML file
+      def cycle!
+        type           = self.class.name.split("::").last
+        storage_object = Backup::Storage::Object.new(type)
+        objects        = [self] + storage_object.load
+        if keep.is_a?(Integer) and keep > 0 and objects.count > keep
+          objects_to_remove = objects[keep..-1]
+          objects_to_remove.each do |object|
+            Logger.message "#{ self.class } started removing (cycling) \"#{ object.remote_file }\"."
+            object.send(:remove!)
+          end
+          objects = objects - objects_to_remove
+        end
+        storage_object.write(objects)
+      end
+
+    end
+  end
+end

data/lib/backup/storage/cloudfiles.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+
+##
+# Only load the Fog gem when the Backup::Storage::CloudFiles class is loaded
+require 'fog'
+
+module Backup
+  module Storage
+    class CloudFiles < Base
+
+      ##
+      # Rackspace Cloud Files Credentials
+      attr_accessor :username, :api_key
+
+      ##
+      # Rackspace Cloud Files container name and path
+      attr_accessor :container, :path
+
+      ##
+      # Creates a new instance of the Rackspace Cloud Files storage object
+      # First it sets the defaults (if any exist) and then evaluates
+      # the configuration block which may overwrite these defaults
+      def initialize(&block)
+        load_defaults!
+
+        @path ||= 'backups'
+
+        instance_eval(&block) if block_given?
+
+        @time = TIME
+      end
+
+      ##
+      # This is the remote path to where the backup files will be stored
+      def remote_path
+        File.join(path, TRIGGER)
+      end
+
+      ##
+      # This is the provider that Fog uses for the Cloud Files Storage
+      def provider
+        'Rackspace'
+      end
+
+      ##
+      # Performs the backup transfer
+      def perform!
+        transfer!
+        cycle!
+      end
+
+    private
+
+      ##
+      # Establishes a connection to Rackspace Cloud Files and returns the Fog object.
+      # Not doing any instance variable caching because this object gets persisted in YAML
+      # format to a file and will issues. This, however has no impact on performance since it only
+      # gets invoked once per object for a #transfer! and once for a remove! Backups run in the
+      # background anyway so even if it were a bit slower it shouldn't matter.
+      def connection
+        Fog::Storage.new(
+          :provider           => provider,
+          :rackspace_username => username,
+          :rackspace_api_key  => api_key
+        )
+      end
+
+      ##
+      # Transfers the archived file to the specified Cloud Files container
+      def transfer!
+        begin
+          Logger.message("#{ self.class } started transferring \"#{ remote_file }\".")
+          connection.put_object(
+            container,
+            File.join(remote_path, remote_file),
+            File.open(File.join(local_path, local_file))
+          )
+        rescue Excon::Errors::SocketError => e
+          puts "\nAn error occurred while trying to transfer the backup."
+          puts "Make sure the container exists and try again.\n\n"
+          exit
+        end
+      end
+
+      ##
+      # Removes the transferred archive file from the Cloud Files container
+      def remove!
+        begin
+          connection.delete_object(container, File.join(remote_path, remote_file))
+        rescue Excon::Errors::SocketError; end
+      end
+
+    end
+  end
+end

data/lib/backup/storage/dropbox.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+
+##
+# Only load the Dropbox gem when the Backup::Storage::Dropbox class is loaded
+require 'dropbox'
+
+module Backup
+  module Storage
+    class Dropbox < Base
+
+      ##
+      # Dropbox user credentials
+      attr_accessor :email, :password
+
+      ##
+      # Dropbox API credentials
+      attr_accessor :api_key, :api_secret
+
+      ##
+      # Path to where the backups will be stored
+      attr_accessor :path
+
+      ##
+      # Creates a new instance of the Dropbox storage object
+      # First it sets the defaults (if any exist) and then evaluates
+      # the configuration block which may overwrite these defaults
+      def initialize(&block)
+        load_defaults!
+
+        @path ||= 'backups'
+
+        instance_eval(&block) if block_given?
+
+        @time = TIME
+      end
+
+      ##
+      # This is the remote path to where the backup files will be stored
+      def remote_path
+        File.join(path, TRIGGER)
+      end
+
+      ##
+      # Performs the backup transfer
+      def perform!
+        transfer!
+        cycle!
+      end
+
+    private
+
+      ##
+      # Establishes a connection to Dropbox and returns the Dropbox::Session object.
+      # Not doing any instance variable caching because this object gets persisted in YAML
+      # format to a file and will issues. This, however has no impact on performance since it only
+      # gets invoked once per object for a #transfer! and once for a remove! Backups run in the
+      # background anyway so even if it were a bit slower it shouldn't matter.
+      def connection
+        session                      = ::Dropbox::Session.new(api_key, api_secret)
+        session.mode                 = :dropbox
+        session.authorizing_user     = email
+        session.authorizing_password = password
+        session.authorize!
+        session
+      end
+
+      ##
+      # Transfers the archived file to the specified Dropbox folder
+      def transfer!
+        Logger.message("#{ self.class } started transferring \"#{ remote_file }\".")
+        connection.upload(File.join(local_path, local_file), remote_path, :timeout => 300)
+      end
+
+      ##
+      # Removes the transferred archive file from the Dropbox folder
+      def remove!
+        connection.delete(File.join(remote_path, remote_file))
+      end
+
+    end
+  end
+end