vagrant-mirror 0.1.0.alpha

data/.gitignore

@@ -0,0 +1,17 @@
+# rcov generated
+coverage
+coverage.data
+
+# rdoc generated
+rdoc
+
+# yard generated
+doc
+.yardoc
+
+# bundler
+.bundle
+
+# jeweler generated
+pkgtmp/
+tmp/

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 1.9.3

data/CONTRIBUTING.md

@@ -0,0 +1,43 @@
+We love pull requests. Here's a quick guide:
+
+1. Fork the repo, and make your changes.
+
+2. Once you're ready to submit, rebase your branch against our master branch to
+maintain a clean history and ensure you're up to date with all the most recent
+changes.
+
+3. Run the tests. We only take pull requests with passing tests, and it's great
+to know that you have a clean slate: `bundle && rake`
+
+4. Add a test for your change. Only refactoring and documentation changes
+require no new tests. If you are adding functionality or fixing a bug, we need
+a test!
+
+5. Make the test pass.
+
+6. Push to your fork and submit a pull request.
+
+
+At this point you're waiting on us. We like to at least comment on, if not
+accept, pull requests within three business days (and, typically, one business
+day). We may suggest some changes or improvements or alternatives. Your pull request
+will be built by [Travis](https://travis-ci.org/ingenerator/vagrant-mirror) first - 
+if the build fails please fix that first.
+
+Some things that will increase the chance that your pull request is accepted,
+taken straight from the Ruby on Rails guide:
+
+* Include tests that fail without your code, and pass with it
+* Update the documentation, the surrounding one, examples elsewhere, guides,
+  whatever is affected by your contribution
+
+Syntax:
+
+* Two spaces, no tabs.
+* No trailing whitespace. Blank lines should not have any space.
+* Prefer &&/|| over and/or.
+* MyClass.my_method(my_arg) not my_method( my_arg ) or my_method my_arg.
+* a = b and not a=b.
+* Follow the conventions you see used in the source already.
+
+And in case we didn't emphasize it enough: we love tests!

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+# Dependencies specified in the gemspec
+gemspec
+
+group :development do
+  gem 'rb-inotify', :require => false
+  gem 'rb-fsevent', :require => false
+  gem 'rb-fchange', :require => false
+  gem 'wdm',        :require => false, :platforms => [:mswin, :mingw]
+end

data/Gemfile.lock

@@ -0,0 +1,85 @@
+PATH
+  remote: .
+  specs:
+    vagrant-mirror (0.0.1)
+      listen
+      vagrant (~> 1.0.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    archive-tar-minitar (0.5.2)
+    childprocess (0.3.9)
+      ffi (~> 1.0, >= 1.0.11)
+    coderay (1.0.8)
+    diff-lcs (1.1.3)
+    erubis (2.7.0)
+    ffi (1.2.0)
+    ffi (1.2.0-x86-mingw32)
+    guard (1.6.1)
+      listen (>= 0.6.0)
+      lumberjack (>= 1.0.2)
+      pry (>= 0.9.10)
+      thor (>= 0.14.6)
+    guard-rspec (2.3.3)
+      guard (>= 1.1)
+      rspec (~> 2.11)
+    i18n (0.6.4)
+    json (1.7.7)
+    listen (0.7.0)
+    log4r (1.1.10)
+    lumberjack (1.0.2)
+    method_source (0.8.1)
+    net-scp (1.0.4)
+      net-ssh (>= 1.99.1)
+    net-ssh (2.2.2)
+    pry (0.9.10)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.3.1)
+    pry (0.9.10-x86-mingw32)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.3.1)
+      win32console (~> 1.3)
+    rake (10.0.3)
+    rb-fchange (0.0.6)
+      ffi
+    rb-fsevent (0.9.3)
+    rb-inotify (0.8.8)
+      ffi (>= 0.5.0)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.1)
+    slop (3.3.3)
+    thor (0.16.0)
+    vagrant (1.0.7)
+      archive-tar-minitar (= 0.5.2)
+      childprocess (~> 0.3.1)
+      erubis (~> 2.7.0)
+      i18n (~> 0.6.0)
+      json (>= 1.5.1, < 1.8.0)
+      log4r (~> 1.1.9)
+      net-scp (~> 1.0.4)
+      net-ssh (~> 2.2.2)
+    wdm (0.1.0)
+    win32console (1.3.2-x86-mingw32)
+
+PLATFORMS
+  x86-mingw32
+
+DEPENDENCIES
+  guard
+  guard-rspec
+  rake
+  rb-fchange
+  rb-fsevent
+  rb-inotify
+  rspec
+  vagrant-mirror!
+  wdm

data/Guardfile

@@ -0,0 +1,5 @@
+guard 'rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/vagrant-mirror/(.+)\.rb$})     { |m| "spec/vagrant-mirror/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 inGenerator Ltd, a company registered in Scotland no. SC435161
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,153 @@
+# Vagrant::Mirror
+
+[![Build Status](https://travis-ci.org/ingenerator/vagrant-mirror.png)](https://travis-ci.org/ingenerator/vagrant-mirror)
+
+**This plugin is for the 1.0.x series of Vagrant and has not been updated to work with 1.1 and
+above. We plan to update it eventually, if you want it faster than that then contributions are
+welcome!**
+
+A vagrant plugin that mirrors a folder from host to guest, designed to get around the performance
+issues of virtualbox shared folders and the headaches of NFS or Samba shares with a windows host and
+linux guest. Tested with Windows XP and Vista hosts and Ubuntu 12.04 guest. However, it uses the
+[listen](https://rubygems.org/gems/listen) gem from guard so it should be fully cross-platform. Your
+guest will need to have rsync installed.
+
+Vagrant-mirror runs on top of existing virtualbox shared folders, using rsync to mirror from the
+shared folder to a local instance folder. This seems to be best for performance and limits the
+number of dependencies.
+
+## Installation
+
+The best option is to install the gem (note you will need to run `vagrant gem vagrant-mirror` if
+using the bundled Vagrant package as this runs in isolation from your global ruby installation).
+
+You also need to install the correct filesystem driver for your host operating system:
+
+* For Windows - [WDM](https://github.com/Maher4Ever/wdm)
+* For Linux - [rb-inotify](https://github.com/nex3/rb-inotify)
+* For OS X - [rb-fsevent](https://github.com/thibaudgg/rb-fsevent)
+
+Unfortunately there is currently no way to specify these as platform-specific dependencies in the
+gemfile.
+
+You can then add to your Vagrantfile like so:
+
+```ruby
+    require 'vagrant-mirror'
+
+    Vagrant::Config.run do | config |
+      #.....
+    end
+```
+
+Alternatively, add this repository alongside the Vagrantfile and require the library manually.
+
+## Basic usage
+
+Include paths to mirror in your Vagrantfile like so:
+
+```ruby
+    # To mirror the vagrant root path
+    config.mirror.vagrant_root "/guest/path"
+
+    # To mirror any arbitrary path
+    config.vm.share_folder "foo", "guest/share/path", "host/path"
+    config.mirror.folder "foo", "/guest/mirror/path"
+```
+
+When you run `vagrant up` or `vagrant resume`, vagrant-mirror will:
+
+* Ensure that your guest has any shared folders required for the pair
+* Create any local symlinks required
+* Run rsync on the guest to copy from the virtualbox shared folder to the local guest path
+* Register with the local host filesystem for updates using using [listen](https://rubygems.org/gems/listen)
+
+When changes are detected on the host, they will be notified by the listen gem. Once a change is
+detected, the host will trigger the guest to run rsync on the changed path to update the locally
+stored file.
+
+If you want to force a full resync, you can run `vagrant mirror-sync`.
+
+If for some reason the mirror crashes you can just run `vagrant-mirror monitor` on the host to bring
+it back up.
+
+## Advanced usage
+
+### Mixing mirrored and shared files
+
+Perhaps there are a few files or directories on the guest that you do want to appear on the host
+too? Vagrant-mirror can create symbolic links for these from your mirror back to the virtualbox
+shared folder. For example, perhaps you want the 'log' directory to work as though it were just on
+the virtualbox shared folder?
+
+```ruby
+    # To mirror the vagrant root path - the options hash is also available when sharing any folder
+    config.mirror.vagrant_root "/guest/path", {
+      :symlinks => [ "/log"]
+    }
+```
+
+This will exclude the "/log" folder from rsync and symlink it directly to the shared folder.
+
+### Excluding paths
+
+Perhaps there are paths you don't require on your virtual machine. For example, syncing your docs
+folder might waste performance. You can easily add paths that should be excluded from mirroring:
+
+```ruby
+    # To mirror the vagrant root path - the options hash is also available when sharing any folder
+    config.mirror.vagrant_root "/guest/path", {
+      :exclude => [ "/docs"]
+    }
+```
+
+You can use any valid rsync exclude patterns for this option. All paths should be specified relative
+to the directory being mirrored.
+
+### Propogating deletes
+
+By default, vagrant mirror transfers new files and folders but does not propogate deletes. This can
+lead to unwanted behaviour, in particular if your application on the guest indexes or autoloads all
+the files it finds. You can enable deletions with the following:
+
+```ruby
+    # To mirror the vagrant root path - the options hash is also available when sharing any folder
+    config.mirror.vagrant_root "/guest/path", {
+      :delete => true
+    }
+```
+
+You should ensure that your "exclude" configuration includes all the paths that may be present on
+the guest (build directories, cache, assets) as otherwise they will be deleted.
+
+### Notifications
+
+The time between updates is generally pretty fast, but it is nonzero. If you're working in fast
+cycles it can be that you rerun a command on the guest before your updated files have been
+transferred, which may be confusing. Avoid this by having vagrant-mirror issue a system beep whenever
+transfers complete.
+
+```ruby
+    # To mirror the vagrant root path - the options hash is also available when sharing any folder
+    config.mirror.vagrant_root "/guest/path", {
+      :beep => true
+    }
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`) with specs
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## Acknowledgements
+
+The [vagrant-notify](https://github.com/fgrehm/vagrant-notify/) plugin was very useful in working
+out how to structure this plugin.
+
+## Copyright
+
+Copyright (c) 2013 inGenerator Ltd. See LICENSE.txt for
+further details.

data/Rakefile

@@ -0,0 +1,29 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+
+desc "Open an irb session preloaded with vagrant-mirror"
+task :console do
+  sh "irb -rubygems -I lib -r vagrant-mirror"
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "spec/**/*_spec.rb"
+end
+
+# From the vagrant-notify gem
+desc 'Outpus some information about Vagrant middleware stack useful for development (use ACTION=action_name to filter out actions)'
+task 'vagrant-stack' do
+  require 'vagrant'
+  Vagrant.actions.to_hash.each do |action, stack|
+    next unless !ENV['ACTION'] || ENV['ACTION'] == action.to_s
+
+    puts action
+    stack.send(:stack).each do |middleware|
+      puts "  #{middleware[0]}"
+      puts "    -> #{middleware[1].inspect}" unless middleware[1].empty?
+    end
+  end
+end
+
+task :default => :spec

data/lib/vagrant-mirror/command.rb

@@ -0,0 +1,71 @@
+require 'optparse'
+
+# Command line tasks to run a full synchronisation of the mirrored folders,
+# or to restart the live mirror (for example, if it fails). Folder mirroring
+# will also be started with vagrant up and vagrant resume
+module Vagrant
+  module Mirror
+    class Command < Vagrant::Command::Base
+
+      # Initializes the command and parses the subcommands from argv
+      def initialize(argv, env)
+        super
+        @main_args, @sub_command, @sub_args = split_main_and_subcommand(argv)
+      end
+
+      # Run the command - valid commands are:
+      # - vagrant mirror sync
+      # - vagrant mirror monitor
+      def execute
+
+        if @main_args.include?("-h") || @main_args.include?("--help")
+          # Print the help for all the box commands.
+          return help
+        end
+
+        # Currently we can only work with a single VM environment
+        raise Errors::SingleVMEnvironmentRequired if @env.multivm?
+
+        # Run the appropriate subcommand
+        case @sub_command
+          when 'sync'
+            return execute_sync
+          when 'monitor'
+            return execute_monitor
+          when nil
+            return execute_monitor
+          else
+            return help
+        end
+      end
+
+      protected
+
+      # Execute the Sync middleware on the primary vm
+      def execute_sync
+        @env.primary_vm.run_action(Vagrant::Mirror::Middleware::Sync)
+      end
+
+      # Execute the Mirror middleware on the primary vm
+      def execute_monitor
+        @env.primary_vm.run_action(Vagrant::Mirror::Middleware::Mirror)
+      end
+
+      # Output help documentation
+      def help
+        opts = OptionParser.new do |opts|
+          opts.banner = "Usage: vagrant mirror <command> [<args>]"
+          opts.separator ""
+          opts.separator "Available subcommands:"
+          opts.separator "     sync     One-off synchronisation of all mirrored files"
+          opts.separator "     monitor  Monitor and mirror changes on host and guest"
+          opts.separator ""
+          opts.separator "For help on any individual command run `vagrant mirror COMMAND -h`"
+        end
+
+        @env.ui.info(opts.help, :prefix => false)
+      end
+
+    end
+  end
+end

data/lib/vagrant-mirror/config.rb

@@ -0,0 +1,73 @@
+# Holds configuration for the vagrant-mirror plugin
+#
+# @author Andrew Coulton < andrew@ingerator.com >
+module Vagrant
+  module Mirror
+    class Config < Vagrant::Config::Base
+
+      # @return [Array] An array of hashes holding the details of folders to monitor
+      attr_reader   :folders
+
+      def initialize
+        @folders = []
+      end
+
+      # Validates the provided configuration
+      # @param [Vagrant::Environment] Vagrant environment instance
+      # @param [Vagrant::Config::ErrorRecorder] Stack of errors in configuration
+      def validate(env, errors)
+        folders.each do | folder |
+          errors.add("vagrant-mirror cannot mirror an empty or nil host path") if (folder[:name].nil? || folder[:name].empty?)
+          errors.add("vagrant-mirror cannot mirror an empty or nil guest path") if (folder[:guest_path].nil? || folder[:guest_path].empty?)
+          valid_opts = [:name, :guest_path, :delete, :beep, :exclude, :symlinks]
+          folder.each do | option, value |
+            errors.add("vagrant-mirror does not understand the option #{option}") unless valid_opts.include?(option)
+          end
+        end
+      end
+
+      # Shortcut to mirror the Vagrant root folder (where the Vagrantfile is stored) to a path on the guest
+      # @param [String] Path on the guest to mirror to
+      # @param [Hash]   Command options - see README.md for details
+      def vagrant_root(guest_path, options = {} )
+        folder('v-root', guest_path, options)
+      end
+
+      # Mirror a folder between the host and the guest
+      # @param [String] Name of the shared folder to mirror as passed to the vagrant shared folder config
+      # @param [String] Path on the guest to mirror to
+      # @param [Hash]   Command options - see README.md for details
+      def folder(share_name, guest_path, options = {} )
+        # Add the default options
+        folder = {
+          :delete   => false,
+          :beep     => false,
+          :exclude  => [],
+          :symlinks => []
+        }.merge(options)
+
+        # If there are any symlinks, they need to be added to the rsync excludes
+        folder[:symlinks].each do | link_path |
+          folder[:exclude] << link_path
+        end
+
+        # Add the names to the hash
+        folder[:name] = share_name
+        folder[:guest_path] = guest_path
+
+        # Store the folder details
+        @folders << folder
+      end
+
+      # Custom merge method since some keys here are merged differently.
+      # @param [Vagrant::Mirror::Config] Configuration to merge with this one
+      # @return [Vagrant::Mirror::Config] A new config instance with the merged configuration
+      def merge(other)
+        result = super
+        result.instance_variable_set(:@folders, @folders + other.folders)
+        result
+      end
+
+    end
+  end
+end

data/lib/vagrant-mirror/errors.rb

@@ -0,0 +1,42 @@
+module Vagrant
+  module Mirror
+    module Errors
+      class SingleVMEnvironmentRequired < Vagrant::Errors::VagrantError
+        status_code(99)
+
+        def initialize()
+          message = "Vagrant-mirror currently only supports a single VM environment"
+          super
+        end
+      end
+
+      class Error < Vagrant::Errors::VagrantError
+        status_code(100)
+
+        def initialize(msg)
+          message = msg
+          super
+        end
+      end
+
+      class MultipleFoldersNotSupported < Vagrant::Errors::VagrantError
+        status_code(101)
+
+        def initialize(msg)
+          message = msg
+          super
+        end
+      end
+
+      class SharedFolderNotMapped < Vagrant::Errors::VagrantError
+        status_code(102)
+
+        def initialize(msg)
+          message = msg
+          super
+        end
+      end
+
+    end
+  end
+end

data/lib/vagrant-mirror/listener/host.rb

@@ -0,0 +1,42 @@
+# Uses Guard to listen for changes on the host filesystem, which it queues
+# for review and transfer to the guest.
+#
+# @author Andrew Coulton < andrew@ingenerator.com >
+
+require 'listen'
+
+module Vagrant
+  module Mirror
+    module Listener
+      class Host
+
+        def initialize(path, queue)
+          @path = path
+          @queue = queue
+        end
+
+        # Makes a blocking call to Guard to listen on the configured path
+        def listen!
+          Listen.to(@path, :relative_paths => true) do | modified, added, removed |
+            @queue << {
+              :source   => :host,
+              :added    => added,
+              :modified => modified,
+              :removed  => removed
+            }
+          end
+        end
+
+        # Runs listen! in a separate thread and returns the thread handle
+        #
+        # @return [Thread] The listener thread
+        def listen
+          Thread.new do
+            listen!
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/vagrant-mirror/middleware/base.rb

@@ -0,0 +1,65 @@
+# Base middleware with common functionality.
+#
+# @author Andrew Coulton < andrew@ingerator.com >
+module Vagrant
+  module Mirror
+    module Middleware
+      class Base
+
+        # Creates an instance
+        #
+        # @param [Object] The next middleware in the chain
+        # @param [Vagrant::Action::Environment] The environment
+        def initialize(app, env)
+          @app = app
+          @env = env
+        end
+
+        # Executes the middleware and then continues to the next middleware in the
+        # stack
+        #
+        # @param [Vagrant::Action::Environment] The environment
+        def call(env)
+          mirrors = env[:vm].config.mirror.folders
+          if !mirrors.empty?
+            execute(mirrors, env)
+          else
+            env[:ui].info("No vagrant-mirror mirrored folders configured for this box")
+          end
+          @app.call(env)
+        end
+
+        protected
+
+        # Iterates over a set of mirror configs, fetching the paths for the shared folder pair from
+        # on the guest and host and passing them together with the folder config to the passed block
+        #
+        # @param [Hash] The folder pair
+        def each_mirror(mirrors)
+          shared_folders = @env[:vm].config.vm.shared_folders
+
+          if (mirrors.count > 1)
+            raise Vagrant::Mirror::Errors::MultipleFoldersNotSupported.new("Sorry, vagrant-mirror doesn't support multiple base folders yet")
+          end
+
+          mirrors.each do | folder |
+            # Locate the shared folder pairing in the config
+            shared_folder = shared_folders[folder[:name]]
+
+            if shared_folder.nil?
+              raise Vagrant::Mirror::Errors::SharedFolderNotMapped.new("The folder #{folder[:name]} was not a valid Vagrant shared folder name")
+            end
+
+            # Pull out the guest and host path
+            guest_path = shared_folder[:guestpath]
+            host_path = File.expand_path(shared_folder[:hostpath], @env[:root_path])
+
+            # Yield for the parent
+            yield host_path, guest_path, folder
+          end
+        end
+
+      end
+    end
+  end
+end