backup-agoddard 3.0.27

data/spec/storage/sftp_spec.rb

@@ -0,0 +1,244 @@
+# encoding: utf-8
+
+require File.expand_path('../../spec_helper.rb', __FILE__)
+
+describe Backup::Storage::SFTP do
+  let(:model)   { Backup::Model.new(:test_trigger, 'test label') }
+  let(:storage) do
+    Backup::Storage::SFTP.new(model) do |sftp|
+      sftp.username  = 'my_username'
+      sftp.password  = 'my_password'
+      sftp.ip        = '123.45.678.90'
+      sftp.keep      = 5
+    end
+  end
+
+  it 'should be a subclass of Storage::Base' do
+    Backup::Storage::SFTP.
+      superclass.should == Backup::Storage::Base
+  end
+
+  describe '#initialize' do
+    after { Backup::Storage::SFTP.clear_defaults! }
+
+    it 'should load pre-configured defaults through Base' do
+      Backup::Storage::SFTP.any_instance.expects(:load_defaults!)
+      storage
+    end
+
+    it 'should pass the model reference to Base' do
+      storage.instance_variable_get(:@model).should == model
+    end
+
+    it 'should pass the storage_id to Base' do
+      storage = Backup::Storage::SFTP.new(model, 'my_storage_id')
+      storage.storage_id.should == 'my_storage_id'
+    end
+
+    it 'should remove any preceeding tilde and slash from the path' do
+      storage = Backup::Storage::SFTP.new(model) do |sftp|
+        sftp.path = '~/my_backups/path'
+      end
+      storage.path.should == 'my_backups/path'
+    end
+
+    context 'when no pre-configured defaults have been set' do
+      it 'should use the values given' do
+        storage.username.should == 'my_username'
+        storage.password.should == 'my_password'
+        storage.ip.should       == '123.45.678.90'
+        storage.port.should     == 22
+        storage.path.should     == 'backups'
+
+        storage.storage_id.should be_nil
+        storage.keep.should       == 5
+      end
+
+      it 'should use default values if none are given' do
+        storage = Backup::Storage::SFTP.new(model)
+
+        storage.username.should be_nil
+        storage.password.should be_nil
+        storage.ip.should       be_nil
+        storage.port.should     == 22
+        storage.path.should     == 'backups'
+
+        storage.storage_id.should be_nil
+        storage.keep.should       be_nil
+      end
+    end # context 'when no pre-configured defaults have been set'
+
+    context 'when pre-configured defaults have been set' do
+      before do
+        Backup::Storage::SFTP.defaults do |s|
+          s.username  = 'some_username'
+          s.password  = 'some_password'
+          s.ip        = 'some_ip'
+          s.port      = 'some_port'
+          s.path      = 'some_path'
+          s.keep      = 'some_keep'
+        end
+      end
+
+      it 'should use pre-configured defaults' do
+        storage = Backup::Storage::SFTP.new(model)
+
+        storage.username.should == 'some_username'
+        storage.password.should == 'some_password'
+        storage.ip.should       == 'some_ip'
+        storage.port.should     == 'some_port'
+        storage.path.should     == 'some_path'
+
+        storage.storage_id.should be_nil
+        storage.keep.should       == 'some_keep'
+      end
+
+      it 'should override pre-configured defaults' do
+        storage = Backup::Storage::SFTP.new(model) do |s|
+          s.username  = 'new_username'
+          s.password  = 'new_password'
+          s.ip        = 'new_ip'
+          s.port      = 'new_port'
+          s.path      = 'new_path'
+          s.keep      = 'new_keep'
+        end
+
+        storage.username.should == 'new_username'
+        storage.password.should == 'new_password'
+        storage.ip.should       == 'new_ip'
+        storage.port.should     == 'new_port'
+        storage.path.should     == 'new_path'
+
+        storage.storage_id.should be_nil
+        storage.keep.should       == 'new_keep'
+      end
+    end # context 'when pre-configured defaults have been set'
+  end # describe '#initialize'
+
+  describe '#connection' do
+    let(:connection) { mock }
+
+    it 'should yield a connection to the remote server' do
+      Net::SFTP.expects(:start).with(
+        '123.45.678.90', 'my_username', :password => 'my_password', :port => 22
+      ).yields(connection)
+
+      storage.send(:connection) do |sftp|
+        sftp.should be(connection)
+      end
+    end
+  end
+
+  describe '#transfer!' do
+    let(:connection) { mock }
+    let(:package) { mock }
+    let(:s) { sequence '' }
+
+    before do
+      storage.instance_variable_set(:@package, package)
+      storage.stubs(:storage_name).returns('Storage::SFTP')
+      storage.stubs(:local_path).returns('/local/path')
+      storage.stubs(:connection).yields(connection)
+    end
+
+    it 'should transfer the package files' do
+      storage.expects(:remote_path_for).in_sequence(s).with(package).
+          returns('remote/path')
+      storage.expects(:create_remote_path).in_sequence(s).with(
+        'remote/path', connection
+      )
+
+      storage.expects(:files_to_transfer_for).in_sequence(s).with(package).
+        multiple_yields(
+        ['2011.12.31.11.00.02.backup.tar.enc-aa', 'backup.tar.enc-aa'],
+        ['2011.12.31.11.00.02.backup.tar.enc-ab', 'backup.tar.enc-ab']
+      )
+      # first yield
+      Backup::Logger.expects(:message).in_sequence(s).with(
+        "Storage::SFTP started transferring " +
+        "'2011.12.31.11.00.02.backup.tar.enc-aa' to '123.45.678.90'."
+      )
+      connection.expects(:upload!).in_sequence(s).with(
+        File.join('/local/path', '2011.12.31.11.00.02.backup.tar.enc-aa'),
+        File.join('remote/path', 'backup.tar.enc-aa')
+      )
+      # second yield
+      Backup::Logger.expects(:message).in_sequence(s).with(
+        "Storage::SFTP started transferring " +
+        "'2011.12.31.11.00.02.backup.tar.enc-ab' to '123.45.678.90'."
+      )
+      connection.expects(:upload!).in_sequence(s).with(
+        File.join('/local/path', '2011.12.31.11.00.02.backup.tar.enc-ab'),
+        File.join('remote/path', 'backup.tar.enc-ab')
+      )
+
+      storage.send(:transfer!)
+    end
+  end # describe '#transfer!'
+
+  describe '#remove!' do
+    let(:package) { mock }
+    let(:connection) { mock }
+    let(:s) { sequence '' }
+
+    before do
+      storage.stubs(:storage_name).returns('Storage::SFTP')
+      storage.stubs(:connection).yields(connection)
+    end
+
+    it 'should remove the package files' do
+      storage.expects(:remote_path_for).in_sequence(s).with(package).
+          returns('remote/path')
+
+      storage.expects(:transferred_files_for).in_sequence(s).with(package).
+        multiple_yields(
+        ['2011.12.31.11.00.02.backup.tar.enc-aa', 'backup.tar.enc-aa'],
+        ['2011.12.31.11.00.02.backup.tar.enc-ab', 'backup.tar.enc-ab']
+      )
+      # first yield
+      Backup::Logger.expects(:message).in_sequence(s).with(
+        "Storage::SFTP started removing " +
+        "'2011.12.31.11.00.02.backup.tar.enc-aa' from '123.45.678.90'."
+      )
+      connection.expects(:remove!).in_sequence(s).with(
+        File.join('remote/path', 'backup.tar.enc-aa')
+      )
+      # second yield
+      Backup::Logger.expects(:message).in_sequence(s).with(
+        "Storage::SFTP started removing " +
+        "'2011.12.31.11.00.02.backup.tar.enc-ab' from '123.45.678.90'."
+      )
+      connection.expects(:remove!).in_sequence(s).with(
+        File.join('remote/path', 'backup.tar.enc-ab')
+      )
+
+      connection.expects(:rmdir!).with('remote/path').in_sequence(s)
+
+      storage.send(:remove!, package)
+    end
+  end # describe '#remove!'
+
+  describe '#create_remote_path' do
+    let(:connection)  { mock }
+    let(:remote_path) { 'backups/folder/another_folder' }
+    let(:s) { sequence '' }
+    let(:sftp_response) { stub(:code => 11, :message => nil) }
+    let(:sftp_status_exception) { Net::SFTP::StatusException.new(sftp_response) }
+
+    context 'while properly creating remote directories one by one' do
+      it 'should rescue any SFTP::StatusException and continue' do
+        connection.expects(:mkdir!).in_sequence(s).
+            with("backups").raises(sftp_status_exception)
+        connection.expects(:mkdir!).in_sequence(s).
+            with("backups/folder")
+        connection.expects(:mkdir!).in_sequence(s).
+            with("backups/folder/another_folder")
+
+        expect do
+          storage.send(:create_remote_path, remote_path, connection)
+        end.not_to raise_error
+      end
+    end
+  end
+
+end

data/spec/syncer/base_spec.rb

@@ -0,0 +1,109 @@
+# encoding: utf-8
+
+require File.expand_path('../../spec_helper.rb', __FILE__)
+
+describe Backup::Syncer::Base do
+  let(:syncer)    { Backup::Syncer::Base.new }
+
+  it 'should include CLI::Helpers' do
+    Backup::Syncer::Base.
+      include?(Backup::CLI::Helpers).should be_true
+  end
+
+  it 'should include Configuration::Helpers' do
+    Backup::Syncer::Base.
+      include?(Backup::Configuration::Helpers).should be_true
+  end
+
+  describe '#initialize' do
+    after { Backup::Syncer::Base.clear_defaults! }
+
+    it 'should load pre-configured defaults through Base' do
+      Backup::Syncer::Base.any_instance.expects(:load_defaults!)
+      syncer
+    end
+
+    it 'should establish a new array for @directories' do
+      syncer.directories.should == []
+    end
+
+    context 'when no pre-configured defaults have been set' do
+      it 'should set default values' do
+        syncer.path.should    == 'backups'
+        syncer.mirror.should  == false
+      end
+    end # context 'when no pre-configured defaults have been set'
+
+    context 'when pre-configured defaults have been set' do
+      before do
+        Backup::Syncer::Base.defaults do |s|
+          s.path   = 'some_path'
+          s.mirror = 'some_mirror'
+        end
+      end
+
+      it 'should use pre-configured defaults' do
+        syncer.path.should    == 'some_path'
+        syncer.mirror.should  == 'some_mirror'
+      end
+    end # context 'when pre-configured defaults have been set'
+  end # describe '#initialize'
+
+  describe '#directories' do
+    before do
+      syncer.instance_variable_set(
+        :@directories,  ['/some/directory', '/another/directory']
+      )
+    end
+
+    context 'when no block is given' do
+      it 'should return @directories' do
+        syncer.directories.should ==
+            ['/some/directory', '/another/directory']
+      end
+    end
+
+    context 'when a block is given' do
+      it 'should evalute the block, allowing #add to add directories' do
+        syncer.directories do
+          add '/new/path'
+          add '/another/new/path'
+        end
+        syncer.directories.should == [
+          '/some/directory',
+          '/another/directory',
+          '/new/path',
+          '/another/new/path'
+        ]
+      end
+    end
+  end # describe '#directories'
+
+  describe '#add' do
+    before do
+      syncer.instance_variable_set(
+        :@directories,  ['/some/directory', '/another/directory']
+      )
+    end
+
+    it 'should add the given path to @directories' do
+      syncer.add '/my/path'
+      syncer.directories.should ==
+          ['/some/directory', '/another/directory', '/my/path']
+    end
+
+    # Note: Each Syncer should handle this as needed.
+    # For example, expanding these here would break RSync::Pull
+    it 'should not expand the given paths' do
+      syncer.add 'relative/path'
+      syncer.directories.should ==
+          ['/some/directory', '/another/directory', 'relative/path']
+    end
+  end
+
+  describe '#syncer_name' do
+    it 'should return the class name with the Backup:: namespace removed' do
+      syncer.send(:syncer_name).should == 'Syncer::Base'
+    end
+  end
+end

data/spec/syncer/cloud/base_spec.rb

@@ -0,0 +1,515 @@
+# encoding: utf-8
+require File.expand_path('../../../spec_helper.rb', __FILE__)
+
+describe 'Backup::Syncer::Cloud::Base' do
+  let(:syncer) { Backup::Syncer::Cloud::Base.new }
+  let(:s)      { sequence '' }
+
+  it 'should be a subclass of Syncer::Base' do
+    Backup::Syncer::Cloud::Base.
+      superclass.should == Backup::Syncer::Base
+  end
+
+  it 'should establish a class constant for a Mutex' do
+    Backup::Syncer::Cloud::Base::MUTEX.should be_an_instance_of Mutex
+  end
+
+  describe '#initialize' do
+    after { Backup::Syncer::Cloud::Base.clear_defaults! }
+
+    it 'should load pre-configured defaults through Syncer::Base' do
+      Backup::Syncer::Cloud::Base.any_instance.expects(:load_defaults!)
+      syncer
+    end
+
+    context 'when no pre-configured defaults have been set' do
+      it 'should use default values if none are given' do
+        syncer.path.should    == 'backups'
+        syncer.mirror.should  == false
+        syncer.concurrency_type.should  == false
+        syncer.concurrency_level.should == 2
+      end
+    end # context 'when no pre-configured defaults have been set'
+
+    context 'when pre-configured defaults have been set' do
+      before do
+        Backup::Syncer::Cloud::Base.defaults do |cloud|
+          cloud.concurrency_type  = 'default_concurrency_type'
+          cloud.concurrency_level = 'default_concurrency_level'
+        end
+      end
+
+      it 'should use pre-configured defaults' do
+        syncer.path.should    == 'backups'
+        syncer.mirror.should  == false
+        syncer.concurrency_type.should  == 'default_concurrency_type'
+        syncer.concurrency_level.should == 'default_concurrency_level'
+      end
+    end # context 'when pre-configured defaults have been set'
+  end # describe '#initialize'
+
+  describe '#perform' do
+    let(:sync_context) { mock }
+
+    before do
+      syncer.stubs(:repository_object).returns(:a_repository_object)
+
+      Backup::Logger.expects(:message).with(
+        "Syncer::Cloud::Base started the syncing process:\n" +
+        "\s\sConcurrency: false Level: 2"
+      )
+      Backup::Logger.expects(:message).with(
+        'Syncer::Cloud::Base Syncing Complete!'
+      )
+    end
+
+    it 'should sync each directory' do
+      syncer.directories do
+        add '/dir/one'
+        add '/dir/two'
+      end
+
+      Backup::Syncer::Cloud::Base::SyncContext.expects(:new).in_sequence(s).with(
+        '/dir/one', :a_repository_object, 'backups'
+      ).returns(sync_context)
+      sync_context.expects(:sync!).in_sequence(s).with(
+        false, false, 2
+      )
+      Backup::Syncer::Cloud::Base::SyncContext.expects(:new).in_sequence(s).with(
+        '/dir/two', :a_repository_object, 'backups'
+      ).returns(sync_context)
+      sync_context.expects(:sync!).in_sequence(s).with(
+        false, false, 2
+      )
+
+      syncer.perform!
+    end
+
+    it 'should ensure each directory path is expanded with no trailing slash' do
+      syncer.directories do
+        add '/dir/one/'
+        add 'dir/two'
+      end
+
+      Backup::Syncer::Cloud::Base::SyncContext.expects(:new).with(
+        '/dir/one', :a_repository_object, 'backups'
+      ).returns(sync_context)
+
+      Backup::Syncer::Cloud::Base::SyncContext.expects(:new).with(
+        File.expand_path('dir/two'), :a_repository_object, 'backups'
+      ).returns(sync_context)
+
+      sync_context.stubs(:sync!)
+
+      syncer.perform!
+    end
+  end # describe '#perform'
+
+  describe 'Cloud::Base::SyncContext' do
+    let(:bucket) { mock }
+    let(:sync_context) do
+      Backup::Syncer::Cloud::Base::SyncContext.new(
+        '/dir/to/sync', bucket, 'backups'
+      )
+    end
+
+    describe '#initialize' do
+      it 'should set variables' do
+        sync_context.directory.should   == '/dir/to/sync'
+        sync_context.bucket.should      == bucket
+        sync_context.path.should        == 'backups'
+        sync_context.remote_base.should == 'backups/sync'
+      end
+    end
+
+    describe '#sync!' do
+      let(:all_files_array) { mock }
+
+      before do
+        sync_context.stubs(:all_file_names).returns(all_files_array)
+      end
+
+      context 'when concurrency_type is set to `false`' do
+        it 'syncs files without concurrency' do
+          all_files_array.expects(:each).in_sequence(s).
+            multiple_yields('foo.file', 'foo_dir/foo.file')
+
+          sync_context.expects(:sync_file).in_sequence(s).
+              with('foo.file', :mirror)
+          sync_context.expects(:sync_file).in_sequence(s).
+              with('foo_dir/foo.file', :mirror)
+
+          sync_context.sync!(:mirror, false, :foo)
+        end
+      end
+
+      context 'when concurrency_type is set to `:threads`' do
+        it 'uses `concurrency_level` number of threads for concurrency' do
+          Parallel.expects(:each).in_sequence(s).with(
+            all_files_array, :in_threads => :num_of_threads
+          ).multiple_yields('foo.file', 'foo_dir/foo.file')
+
+          sync_context.expects(:sync_file).in_sequence(s).
+              with('foo.file', :mirror)
+          sync_context.expects(:sync_file).in_sequence(s).
+              with('foo_dir/foo.file', :mirror)
+
+          sync_context.sync!(:mirror, :threads, :num_of_threads)
+        end
+      end
+
+      context 'when concurrency_type is set to `:processes`' do
+        it 'uses `concurrency_level` number of processes for concurrency' do
+          Parallel.expects(:each).in_sequence(s).with(
+            all_files_array, :in_processes => :num_of_processes
+          ).multiple_yields('foo.file', 'foo_dir/foo.file')
+
+          sync_context.expects(:sync_file).in_sequence(s).
+              with('foo.file', :mirror)
+          sync_context.expects(:sync_file).in_sequence(s).
+              with('foo_dir/foo.file', :mirror)
+
+          sync_context.sync!(:mirror, :processes, :num_of_processes)
+        end
+      end
+
+      context 'when concurrency_type setting is invalid' do
+        it 'should raise an error' do
+          expect do
+            sync_context.sync!(:foo, 'unknown type', :foo)
+          end.to raise_error(
+            Backup::Errors::Syncer::Cloud::ConfigurationError,
+            'Syncer::Cloud::ConfigurationError: ' +
+            "Unknown concurrency_type setting: \"unknown type\""
+          )
+        end
+      end
+    end # describe '#sync!'
+
+    describe '#all_file_names' do
+      let(:local_files_hash) do
+        { 'file_b' => :foo, 'file_a' => :foo, 'dir_a/file_b' => :foo }
+      end
+      let(:remote_files_hash) do
+        { 'file_c' => :foo, 'file_a' => :foo, 'dir_a/file_a' => :foo }
+      end
+      let(:local_remote_union_array) do
+        ['dir_a/file_a', 'dir_a/file_b', 'file_a', 'file_b', 'file_c']
+      end
+
+      it 'returns and caches a sorted union of local and remote file names' do
+        sync_context.expects(:local_files).once.returns(local_files_hash)
+        sync_context.expects(:remote_files).once.returns(remote_files_hash)
+
+        sync_context.send(:all_file_names).should == local_remote_union_array
+        sync_context.instance_variable_get(:@all_file_names).
+            should == local_remote_union_array
+        sync_context.send(:all_file_names).should == local_remote_union_array
+      end
+    end # describe '#all_file_names'
+
+    describe '#local_files' do
+      let(:local_file_class)  { Backup::Syncer::Cloud::Base::LocalFile }
+      let(:local_hashes_data) { "line1\nline2\nbad\xFFline\nline3" }
+
+      let(:local_file_a)  { stub(:relative_path => 'file_a') }
+      let(:local_file_b)  { stub(:relative_path => 'file_b') }
+      let(:local_file_c)  { stub(:relative_path => 'file_c') }
+      let(:local_files_hash) do
+        { 'file_a' => local_file_a,
+          'file_b' => local_file_b,
+          'file_c' => local_file_c }
+      end
+
+      it 'should return and caches a hash of LocalFile objects' do
+        sync_context.expects(:local_hashes).once.returns(local_hashes_data)
+
+        local_file_class.expects(:new).once.with('/dir/to/sync', "line1\n").
+            returns(local_file_a)
+        local_file_class.expects(:new).once.with('/dir/to/sync', "line2\n").
+            returns(local_file_b)
+        local_file_class.expects(:new).once.with('/dir/to/sync', "bad\xFFline\n").
+            returns(nil)
+        local_file_class.expects(:new).once.with('/dir/to/sync', "line3").
+            returns(local_file_c)
+
+        sync_context.send(:local_files).should == local_files_hash
+        sync_context.instance_variable_get(:@local_files).
+            should == local_files_hash
+        sync_context.send(:local_files).should == local_files_hash
+      end
+
+      # Note: don't use methods that validate encoding
+      it 'will raise an Exception if String#split is used',
+          :if => RUBY_VERSION >= '1.9' do
+        expect do
+          "line1\nbad\xFFline\nline3".split("\n")
+        end.to raise_error(ArgumentError, 'invalid byte sequence in UTF-8')
+      end
+    end # describe '#local_files'
+
+    describe '#local_hashes' do
+      it 'should collect file paths and MD5 checksums for @directory' do
+        Backup::Logger.expects(:message).with(
+          "\s\sGenerating checksums for '/dir/to/sync'"
+        )
+        sync_context.expects(:`).with(
+          "find '/dir/to/sync' -print0 | xargs -0 openssl md5 2> /dev/null"
+        ).returns('MD5(tmp/foo)= 0123456789abcdefghijklmnopqrstuv')
+
+        sync_context.send(:local_hashes).should ==
+          'MD5(tmp/foo)= 0123456789abcdefghijklmnopqrstuv'
+      end
+    end
+
+    describe '#remote_files' do
+      let(:repository_object) { mock }
+      let(:repository_files)  { mock }
+      let(:file_objects)      { mock }
+      let(:file_obj_a)        { stub(:key => 'file_a') }
+      let(:file_obj_b)        { stub(:key => 'file_b') }
+      let(:file_obj_c)        { stub(:key => 'dir/file_c') }
+      let(:remote_files_hash) do
+        { 'file_a'      => file_obj_a,
+          'file_b'      => file_obj_b,
+          'dir/file_c'  => file_obj_c }
+      end
+
+      before do
+        sync_context.instance_variable_set(:@bucket, repository_object)
+
+        repository_object.expects(:files).once.returns(repository_files)
+        repository_files.expects(:all).once.with(:prefix => 'backups/sync').
+            returns(file_objects)
+        file_objects.expects(:each).once.multiple_yields(
+          file_obj_a, file_obj_b, file_obj_c
+        )
+
+        # this is to avoid: unexpected invocation: #<Mock>.to_a()
+        # only 1.9.2 seems affected by this
+        if RUBY_VERSION == '1.9.2'
+          file_obj_a.stubs(:to_a)
+          file_obj_b.stubs(:to_a)
+          file_obj_c.stubs(:to_a)
+        end
+      end
+
+      context 'when it returns and caches a hash of repository file objects' do
+        it 'should remove the @remote_base from the path for the hash key' do
+          sync_context.send(:remote_files).should == remote_files_hash
+          sync_context.instance_variable_get(:@remote_files).
+              should == remote_files_hash
+          sync_context.send(:remote_files).should == remote_files_hash
+        end
+      end
+    end # describe '#remote_files'
+
+    describe '#sync_file' do
+      let(:local_file) do
+        stub(
+          :path => '/dir/to/sync/sync.file',
+          :md5 => '0123456789abcdefghijklmnopqrstuv')
+      end
+      let(:remote_file) do
+        stub(:path => 'backups/sync/sync.file')
+      end
+      let(:file) { mock }
+      let(:repository_object) { mock }
+      let(:repository_files)  { mock }
+
+      before do
+        sync_context.instance_variable_set(:@bucket, repository_object)
+        repository_object.stubs(:files).returns(repository_files)
+      end
+
+      context 'when the requested file to sync exists locally' do
+        before do
+          sync_context.stubs(:local_files).returns(
+            { 'sync.file' => local_file }
+          )
+          File.expects(:exist?).with('/dir/to/sync/sync.file').returns(true)
+        end
+
+        context 'when the MD5 checksum matches the remote file' do
+          before do
+            remote_file.stubs(:etag).returns('0123456789abcdefghijklmnopqrstuv')
+            sync_context.stubs(:remote_files).returns(
+              { 'sync.file' => remote_file }
+            )
+          end
+
+          it 'should skip the file' do
+            File.expects(:open).never
+            Backup::Syncer::Cloud::Base::MUTEX.expects(:synchronize).yields
+            Backup::Logger.expects(:message).with(
+              "\s\s[skipping] 'backups/sync/sync.file'"
+            )
+
+            sync_context.send(:sync_file, 'sync.file', :foo)
+          end
+        end
+
+        context 'when the MD5 checksum does not match the remote file' do
+          before do
+            remote_file.stubs(:etag).returns('vutsrqponmlkjihgfedcba9876543210')
+            sync_context.stubs(:remote_files).returns(
+              { 'sync.file' => remote_file }
+            )
+          end
+
+          it 'should upload the file' do
+            Backup::Syncer::Cloud::Base::MUTEX.expects(:synchronize).yields
+            Backup::Logger.expects(:message).with(
+              "\s\s[transferring] 'backups/sync/sync.file'"
+            )
+
+            File.expects(:open).with('/dir/to/sync/sync.file', 'r').yields(file)
+            repository_files.expects(:create).with(
+              :key  => 'backups/sync/sync.file',
+              :body => file
+            )
+
+            sync_context.send(:sync_file, 'sync.file', :foo)
+          end
+        end
+
+        context 'when the requested file does not exist on the remote' do
+          before do
+            sync_context.stubs(:remote_files).returns({})
+          end
+
+          it 'should upload the file' do
+            Backup::Syncer::Cloud::Base::MUTEX.expects(:synchronize).yields
+            Backup::Logger.expects(:message).with(
+              "\s\s[transferring] 'backups/sync/sync.file'"
+            )
+
+            File.expects(:open).with('/dir/to/sync/sync.file', 'r').yields(file)
+            repository_files.expects(:create).with(
+              :key  => 'backups/sync/sync.file',
+              :body => file
+            )
+
+            sync_context.send(:sync_file, 'sync.file', :foo)
+          end
+        end
+      end
+
+      context 'when the requested file does not exist locally' do
+        before do
+          sync_context.stubs(:remote_files).returns(
+            { 'sync.file' => remote_file }
+          )
+          sync_context.stubs(:local_files).returns({})
+        end
+
+        context 'when the `mirror` option is set to true' do
+          it 'should remove the file from the remote' do
+            Backup::Syncer::Cloud::Base::MUTEX.expects(:synchronize).yields
+            Backup::Logger.expects(:message).with(
+              "\s\s[removing] 'backups/sync/sync.file'"
+            )
+
+            remote_file.expects(:destroy)
+
+            sync_context.send(:sync_file, 'sync.file', true)
+          end
+        end
+
+        context 'when the `mirror` option is set to false' do
+          it 'should leave the file on the remote' do
+            Backup::Syncer::Cloud::Base::MUTEX.expects(:synchronize).yields
+            Backup::Logger.expects(:message).with(
+              "\s\s[leaving] 'backups/sync/sync.file'"
+            )
+
+            remote_file.expects(:destroy).never
+
+            sync_context.send(:sync_file, 'sync.file', false)
+          end
+        end
+      end
+    end # describe '#sync_file'
+  end # describe 'Cloud::Base::SyncContext'
+
+  describe 'Cloud::Base::LocalFile' do
+    let(:local_file_class) { Backup::Syncer::Cloud::Base::LocalFile }
+
+    describe '#new' do
+      describe 'wrapping #initialize and using #sanitize to validate objects' do
+        context 'when the path is valid UTF-8' do
+          let(:local_file) do
+            local_file_class.new(
+              'foo',
+              'MD5(foo)= 0123456789abcdefghijklmnopqrstuv'
+            )
+          end
+
+          it 'should return the new object' do
+            Backup::Logger.expects(:warn).never
+
+            local_file.should be_an_instance_of local_file_class
+          end
+        end
+
+        context 'when the path contains invalid UTF-8' do
+          let(:local_file) do
+            local_file_class.new(
+              "/bad/pa\xFFth",
+              "MD5(/bad/pa\xFFth/to/file)= 0123456789abcdefghijklmnopqrstuv"
+            )
+          end
+          it 'should return nil and log a warning' do
+            Backup::Logger.expects(:warn).with(
+              "\s\s[skipping] /bad/pa\xEF\xBF\xBDth/to/file\n" +
+              "\s\sPath Contains Invalid UTF-8 byte sequences"
+            )
+
+            local_file.should be_nil
+          end
+        end
+      end
+    end # describe '#new'
+
+    describe '#initialize' do
+      let(:local_file) do
+        local_file_class.new(:directory, :line)
+      end
+
+      before do
+        local_file_class.any_instance.expects(:sanitize).with(:directory).
+          returns('/dir/to/sync')
+        local_file_class.any_instance.expects(:sanitize).with(:line).
+          returns("MD5(/dir/to/sync/subdir/sync.file)= 0123456789abcdefghijklmnopqrstuv\n")
+      end
+
+      it 'should determine @path, @relative_path and @md5' do
+        local_file.path.should == '/dir/to/sync/subdir/sync.file'
+        local_file.relative_path.should == 'subdir/sync.file'
+        local_file.md5.should == '0123456789abcdefghijklmnopqrstuv'
+      end
+
+      it 'should return nil if the object is invalid' do
+        local_file_class.any_instance.expects(:invalid?).returns(true)
+        Backup::Logger.expects(:warn)
+        local_file.should be_nil
+      end
+    end # describe '#initialize'
+
+    describe '#sanitize' do
+      let(:local_file) do
+        local_file_class.new('foo', 'MD5(foo)= 0123456789abcdefghijklmnopqrstuv')
+      end
+
+      it 'should replace any invalid UTF-8 characters' do
+        local_file.send(:sanitize, "/path/to/d\xFFir/subdir/sync\xFFfile").
+          should == "/path/to/d\xEF\xBF\xBDir/subdir/sync\xEF\xBF\xBDfile"
+      end
+
+      it 'should flag the LocalFile object as invalid' do
+        local_file.send(:sanitize, "/path/to/d\xFFir/subdir/sync\xFFfile")
+        local_file.invalid?.should be_true
+      end
+    end # describe '#sanitize'
+  end # describe 'Cloud::Base::LocalFile'
+end