listen 2.4.1 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 968f171fec1b3b5600ac4e789f5d01ec91c8acbf
-  data.tar.gz: 38a66c48a8ea7a1c1a56511349c3372f2dee13a3
+  metadata.gz: 042d2544c103c6d5dfbf379cfc2c9f3f6bf84f3e
+  data.tar.gz: dc1649706fbc543ea1cce0ef66f004f27f785152
 SHA512:
-  metadata.gz: b5ac8813595d071733abef351324858ffb0f2af05a6f25ee7e629ff3e8a5d9863b3c4b7988352790986b9d08e653a152b9c8cf1d7caba9745c319a344b017dca
-  data.tar.gz: 4e6b618a757f09d028dd48d057e597faf345fa65e258a54b5d7b4f6edc5fd0244b31e8b7979f65dc12f7b9ea2b188f40bdf55e57ca3831627d8ea78aecdc0105
+  metadata.gz: d97f0b9f72731fe5675324aee96cc6671efd538bec2207f3b3386c5fb98e3aab1f85251f36b8f8a12447a2932c7ae0dfb9220bb37e3fd369326280037ead5d87
+  data.tar.gz: 5facee3fb794d2c49670a783119d434c589da911b12dd4b32445808e8b8750e19513ba57045da4ce6e18c38817e3b31d26bd219bb8b7d402523bb0e66544adba

data/README.md

@@ -11,6 +11,7 @@ The Listen gem listens to file modifications and notifies you about the changes.
 * Detects file modification, addition and removal.
 * Allows supplying regexp-patterns to ignore paths for better results.
 * File content checksum comparison for modifications made under the same second (OS X only).
+* Forwarding file events over TCP, [more info](#forwarding-file-events-over-tcp) below.
 * Tested on MRI Ruby environments (1.9+ only) via [Travis CI](https://travis-ci.org/guard/listen),
 
 Please note that:
@@ -192,6 +193,35 @@ Here are some things you could try to avoid forcing polling.
 
 If your application keeps using the polling-adapter and you can't figure out why, feel free to [open an issue](https://github.com/guard/listen/issues/new) (and be sure to [give all the details](https://github.com/guard/listen/blob/master/CONTRIBUTING.md)).
 
+## Forwarding file events over TCP
+
+Listen is capable of forwarding file events over the network using a messaging protocol. This can be useful for virtualized development environments when file events are unavailable, as is the case with [Vagrant](https://github.com/mitchellh/vagrant).
+
+To broadcast events over TCP, use the `forward_to` option with an address - just a port or a hostname/port combination:
+
+```ruby
+listener = Listen.to 'path/to/app', forward_to: '10.0.0.2:4000' do |modified, added, removed|
+  # After broadcasting the changes to any connected recipients,
+  # this block will still be called
+end
+listener.start
+sleep
+```
+
+To connect to a broadcasting listener as a recipient, specify its address using `Listen.on`:
+
+```ruby
+listener = Listen.on '10.0.0.2:4000' do |modified, added, removed|
+  # This block will be called
+end
+listener.start
+sleep
+```
+
+### Security considerations
+
+Since file events potentially expose sensitive information, care must be taken when specifying the broadcaster address. It is recommended to **always** specify a hostname and make sure it is as specific as possible to reduce any undesirable eavesdropping.
+
 ## Development
 
 * Documentation hosted at [RubyDoc](http://rubydoc.info/github/guard/listen/master/frames).

data/lib/listen.rb

@@ -1,5 +1,6 @@
 require 'celluloid'
 require 'listen/listener'
+require 'listen/tcp/listener'
 
 module Listen
   class << self
@@ -7,6 +8,8 @@ module Listen
 
     # Listens to file system modifications on a either single directory or multiple directories.
     #
+    # When :forward_to is specified, this listener will broadcast modifications over TCP.
+    #
     # @param (see Listen::Listener#new)
     #
     # @yield [modified, added, removed] the changed files
@@ -18,7 +21,12 @@ module Listen
     #
     def to(*args, &block)
       @stopping = false
-      Listener.new(*args, &block)
+      options = args.last.is_a?(Hash) ? args.last : {}
+      if target = options.delete(:forward_to)
+        TCP::Listener.new(target, :broadcaster, *args, &block)
+      else
+        Listener.new(*args, &block)
+      end
     end
 
     # Stop all listeners
@@ -26,5 +34,22 @@ module Listen
     def stop
       @stopping = true
     end
+
+    # Listens to file system modifications broadcast over TCP.
+    #
+    # @param [String/Fixnum] target to listen on (hostname:port or port)
+    #
+    # @yield [modified, added, removed] the changed files
+    # @yieldparam [Array<String>] modified the list of modified files
+    # @yieldparam [Array<String>] added the list of added files
+    # @yieldparam [Array<String>] removed the list of removed files
+    #
+    # @return [Listen::Listener] the listener
+    #
+    def on(target, *args, &block)
+      TCP::Listener.new(target, :recipient, *args, &block)
+    end
+
   end
+
 end

data/lib/listen/adapter.rb

@@ -3,6 +3,7 @@ require 'listen/adapter/bsd'
 require 'listen/adapter/darwin'
 require 'listen/adapter/linux'
 require 'listen/adapter/polling'
+require 'listen/adapter/tcp'
 require 'listen/adapter/windows'
 
 module Listen
@@ -11,6 +12,7 @@ module Listen
     POLLING_FALLBACK_MESSAGE = "Listen will be polling for changes. Learn more at https://github.com/guard/listen#polling-fallback."
 
     def self.select(options = {})
+      return TCP if options[:force_tcp]
       return Polling if options[:force_polling]
       return _usable_adapter_class if _usable_adapter_class
 

data/lib/listen/adapter/tcp.rb

@@ -0,0 +1,64 @@
+require 'celluloid/io'
+
+module Listen
+  module Adapter
+
+    # Adapter to receive file system modifications over TCP
+    class TCP < Base
+      include Celluloid::IO
+
+      finalizer :finalize
+
+      attr_reader :buffer, :socket
+
+      def self.usable?
+        true
+      end
+
+      # Initializes and starts a Celluloid::IO-powered TCP-recipient
+      def start
+        @socket = TCPSocket.new(listener.host, listener.port)
+        @buffer = String.new
+        run
+      end
+
+      # Cleans up buffer and socket
+      def finalize
+        @buffer = nil
+        if @socket
+          @socket.close
+          @socket = nil
+        end
+      end
+
+      # Number of bytes to receive at a time
+      RECEIVE_WINDOW = 1024
+
+      # Continuously receive and asynchronously handle data
+      def run
+        while data = @socket.recv(RECEIVE_WINDOW)
+          async.handle_data(data)
+        end
+      end
+
+      # Buffers incoming data and handles messages accordingly
+      def handle_data(data)
+        @buffer << data
+        while message = Listen::TCP::Message.from_buffer(@buffer)
+          handle_message(message)
+        end
+      end
+
+      # Handles incoming message by notifying of path changes
+      def handle_message(message)
+        message.object.each do |change, paths|
+          paths.each do |path|
+            _notify_change(path, change: change.to_sym)
+          end
+        end
+      end
+
+    end
+
+  end
+end

data/lib/listen/tcp/broadcaster.rb

@@ -0,0 +1,72 @@
+require 'celluloid/io'
+
+module Listen
+  module TCP
+    class Broadcaster
+      include Celluloid::IO
+
+      finalizer :finalize
+
+      attr_reader :server, :sockets
+
+      # Initializes a Celluloid::IO-powered TCP-broadcaster
+      #
+      # @param [String] host to broadcast on
+      # @param [String] port to broadcast on
+      #
+      # Note: Listens on all addresses when host is nil
+      #
+      def initialize(host, port)
+        @server = TCPServer.new(host, port)
+        @sockets = []
+      end
+
+      # Asynchronously start accepting connections
+      def start
+        async.run
+      end
+
+      # Cleans up sockets and server
+      def finalize
+        if @server
+          @sockets.clear
+          @server.close
+          @server = nil
+        end
+      end
+
+      # Broadcasts given payload to all connected sockets
+      def broadcast(payload)
+        @sockets.each do |socket|
+          unicast(socket, payload)
+        end
+      end
+
+      # Unicasts payload to given socket
+      #
+      # @return [Boolean] whether writing to socket was succesful
+      #
+      def unicast(socket, payload)
+        socket.write(payload)
+        true
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE
+        @sockets.delete(socket)
+        false
+      end
+
+      # Continuously accept and handle incoming connections
+      def run
+        while socket = @server.accept
+          handle_connection(socket)
+        end
+      end
+
+      # Handles incoming socket connection
+      def handle_connection(socket)
+        @sockets << socket
+      end
+
+    end
+
+  end
+end

data/lib/listen/tcp/listener.rb

@@ -0,0 +1,103 @@
+require 'listen/tcp/broadcaster'
+require 'listen/tcp/message'
+
+module Listen
+  module TCP
+    class Listener < Listen::Listener
+
+      DEFAULT_HOST = 'localhost'
+
+      attr_reader :host, :mode, :port
+
+      # Initializes a listener to broadcast or receive modifications over TCP
+      #
+      # @param [String/Fixnum] target to listen on (hostname:port or port)
+      # @param [Symbol] mode (either :broadcaster or :recipient)
+      #
+      # @param (see Listen::Listener#new)
+      #
+      def initialize(target, mode, *args, &block)
+        self.mode = mode
+        self.target = target
+
+        super *args, &block
+      end
+
+      def broadcaster?
+        @mode == :broadcaster
+      end
+
+      def recipient?
+        @mode == :recipient
+      end
+
+      # Initializes and starts TCP broadcaster
+      def start
+        super
+        if broadcaster?
+          supervisor.add(Broadcaster, as: :broadcaster, args: [host, port])
+          registry[:broadcaster].start
+        end
+      end
+
+      # Hook to broadcast changes over TCP
+      def block
+        if broadcaster?
+          Proc.new { |modified, added, removed|
+
+            # Honour paused and stopped states
+            next if @paused || @stopping
+
+            # Broadcast changes as a hash (see Listen::Adapter::TCP#handle_message)
+            message = Message.new(modified: modified, added: added, removed: removed)
+            registry[:broadcaster].async.broadcast(message.payload)
+
+            # Invoke the original callback block
+            @block.call(modified, added, removed) if @block
+          }
+        else
+          super
+        end
+      end
+
+      private
+
+      def _init_options(options = {})
+        options = super(options)
+        options[:force_tcp] = true if recipient?
+        options
+      end
+
+      # Sets listener mode
+      #
+      # @param [Symbol] mode (either :broadcaster or :recipient)
+      #
+      def mode=(mode)
+        unless [:broadcaster, :recipient].include? mode
+          raise ArgumentError, 'TCP::Listener requires mode to be either :broadcaster or :recipient'
+        end
+        @mode = mode
+      end
+
+      # Sets listener target
+      #
+      # @param [String/Fixnum] target to listen on (hostname:port or port)
+      #
+      def target=(target)
+        unless target
+          raise ArgumentError, 'TCP::Listener requires target to be given'
+        end
+
+        @host = DEFAULT_HOST if recipient?
+
+        if target.is_a? Fixnum
+          @port = target
+        else
+          @host, @port = target.split(':')
+          @port = @port.to_i
+        end
+      end
+
+    end
+  end
+end

data/lib/listen/tcp/message.rb

@@ -0,0 +1,52 @@
+require 'json'
+
+module Listen
+  module TCP
+    class Message
+
+      attr_reader :body, :object, :payload, :size
+
+      HEADER_SIZE    = 4
+      HEADER_FORMAT  = 'N'
+      PAYLOAD_FORMAT = "#{HEADER_FORMAT}a*"
+
+      # Initializes a new message
+      #
+      # @param [Object] object to initialize message with
+      #
+      def initialize(object = nil)
+        self.object = object if object
+      end
+
+      # Generates message size and payload for given object
+      def object=(obj)
+        @object = obj
+        @body = JSON.generate(@object)
+        @size = @body.bytesize
+        @payload = [@size, @body].pack(PAYLOAD_FORMAT)
+      end
+
+      # Extracts message size and loads object from given payload
+      def payload=(payload)
+        @payload = payload
+        @size, @body = @payload.unpack(PAYLOAD_FORMAT)
+        @object = JSON.parse(@body)
+      end
+
+      # Extracts a message from given buffer
+      def self.from_buffer(buffer)
+        if buffer.bytesize > HEADER_SIZE
+          size = buffer.unpack(HEADER_FORMAT).first
+          payload_size = HEADER_SIZE + size
+          if buffer.bytesize >= payload_size
+            payload = buffer.slice!(0...payload_size)
+            new.tap do |message|
+              message.payload = payload
+            end
+          end
+        end
+      end
+
+    end
+  end
+end

data/lib/listen/version.rb

@@ -1,3 +1,3 @@
 module Listen
-  VERSION = '2.4.1'
+  VERSION = '2.5.0'
 end

data/listen.gemspec

@@ -20,6 +20,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = ">= 1.9.3"
 
   s.add_dependency 'celluloid',  '>= 0.15.2'
+  s.add_dependency 'celluloid-io', '>= 0.15.0'
   s.add_dependency 'rb-fsevent', '>= 0.9.3'
   s.add_dependency 'rb-inotify', '>= 0.9'
 

data/spec/acceptance/tcp_spec.rb

@@ -0,0 +1,143 @@
+require 'spec_helper'
+
+describe Listen::TCP do
+
+  let(:port) { 4000 }
+
+  let(:broadcaster) { Listen.to(Dir.pwd, forward_to: port) }
+  let(:recipient)  { Listen.on(port) }
+  let(:callback) { ->(modified, added, removed) {
+    add_changes(:modified, modified)
+    add_changes(:added, added)
+    add_changes(:removed, removed)
+  } }
+  let(:paths) { Pathname.new(Dir.pwd) }
+
+  around { |example| fixtures { |path| example.run } }
+
+  before do
+    broadcaster.start
+  end
+
+  context 'when broadcaster' do
+    before do
+      broadcaster.block = callback
+    end
+
+    it 'still handles local changes' do
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: [],
+        added:    ['file.rb'],
+        removed:  []
+      )
+    end
+
+    it 'may be paused and unpaused' do
+      broadcaster.pause
+
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: [],
+        added:    [],
+        removed:  []
+      )
+
+      broadcaster.unpause
+
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: ['file.rb'],
+        added:    [],
+        removed:  []
+      )
+    end
+
+    it 'may be stopped and restarted' do
+      broadcaster.stop
+
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: [],
+        added:    [],
+        removed:  []
+      )
+
+      broadcaster.start
+
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: ['file.rb'],
+        added:    [],
+        removed:  []
+      )
+    end
+  end
+
+  context 'when recipient' do
+    before do
+      recipient.start
+      recipient.block = callback
+    end
+
+    it 'receives changes over TCP' do
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: [],
+        added:    ['file.rb'],
+        removed:  []
+      )
+    end
+
+    it 'may be paused and unpaused' do
+      recipient.pause
+
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: [],
+        added:    [],
+        removed:  []
+      )
+
+      recipient.unpause
+
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: ['file.rb'],
+        added:    [],
+        removed:  []
+      )
+    end
+
+    it 'may be stopped and restarted' do
+      recipient.stop
+
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: [],
+        added:    [],
+        removed:  []
+      )
+
+      recipient.start
+
+      expect(listen {
+        touch 'file.rb'
+      }).to eq(
+        modified: ['file.rb'],
+        added:    [],
+        removed:  []
+      )
+    end
+  end
+
+end

data/spec/lib/listen/adapter/tcp_spec.rb

@@ -0,0 +1,110 @@
+require 'spec_helper'
+
+describe Listen::Adapter::TCP do
+
+  let(:host) { '10.0.0.2' }
+  let(:port) { 4000 }
+
+  subject { described_class.new(listener) }
+  let(:registry) { double(Celluloid::Registry) }
+  let(:listener) { double(Listen::TCP::Listener, registry: registry, options: {}, host: host, port: port) }
+  let(:socket)   { double(described_class::TCPSocket, close: true, recv: nil) }
+
+  before do
+    described_class::TCPSocket.stub(:new).and_return socket
+  end
+
+  after do
+    subject.terminate
+  end
+
+  describe '.usable?' do
+    it 'always returns true' do
+      expect(described_class).to be_usable
+    end
+  end
+
+  describe '#start' do
+    it 'initializes and exposes a socket with listener host and port' do
+      expect(described_class::TCPSocket).to receive(:new).with listener.host, listener.port
+      subject.start
+      expect(subject.socket).to be socket
+    end
+
+    it 'initializes and exposes a string buffer' do
+      subject.start
+      expect(subject.buffer).to eq ''
+    end
+
+    it 'invokes run loop' do
+      expect(subject.wrapped_object).to receive(:run)
+      subject.start
+    end
+  end
+
+  describe '#finalize' do
+    it 'clears buffer' do
+      subject.start
+      subject.finalize
+      expect(subject.buffer).to be_nil
+    end
+
+    it 'closes socket' do
+      subject.start
+      expect(subject.socket).to receive(:close)
+      subject.finalize
+      expect(subject.socket).to be_nil
+    end
+  end
+
+  describe '#run' do
+    let(:async) { double('TCP-adapter async', handle_data: true) }
+
+    it 'handles data from socket' do
+      socket.stub(:recv).and_return 'foo', 'bar', nil
+      subject.stub(:async).and_return async
+
+      expect(async).to receive(:handle_data).with 'foo'
+      expect(async).to receive(:handle_data).with 'bar'
+
+      subject.start
+    end
+  end
+
+  describe '#handle_data' do
+    it 'buffers data' do
+      subject.start
+      subject.handle_data 'foo'
+      subject.handle_data 'bar'
+      expect(subject.buffer).to eq 'foobar'
+    end
+
+    it 'handles messages accordingly' do
+      message = Listen::TCP::Message.new
+
+      Listen::TCP::Message.stub(:from_buffer).and_return message, nil
+      expect(Listen::TCP::Message).to receive(:from_buffer).with 'foo'
+      expect(subject.wrapped_object).to receive(:handle_message).with message
+
+      subject.start
+      subject.handle_data 'foo'
+    end
+  end
+
+  describe '#handle_message' do
+    it 'notifies listener of path changes' do
+      message = Listen::TCP::Message.new(
+        'modified' => ['/foo', '/bar'],
+        'added'    => ['/baz'],
+        'removed'  => []
+      )
+
+      expect(subject.wrapped_object).to receive(:_notify_change).with '/foo', change: :modified
+      expect(subject.wrapped_object).to receive(:_notify_change).with '/bar', change: :modified
+      expect(subject.wrapped_object).to receive(:_notify_change).with '/baz', change: :added
+
+      subject.handle_message message
+    end
+  end
+
+end

data/spec/lib/listen/adapter_spec.rb

@@ -10,6 +10,11 @@ describe Listen::Adapter do
   }
 
   describe ".select" do
+    it 'returns TCP adapter when requested' do
+      klass = Listen::Adapter.select(force_tcp: true)
+      expect(klass).to eq Listen::Adapter::TCP
+    end
+
     it "returns Polling adapter if forced" do
       klass = Listen::Adapter.select(force_polling: true)
       expect(klass).to eq Listen::Adapter::Polling

data/spec/lib/listen/tcp/broadcaster_spec.rb

@@ -0,0 +1,114 @@
+require 'spec_helper'
+
+describe Listen::TCP::Broadcaster do
+
+  let(:host) { '10.0.0.2' }
+  let(:port) { 4000 }
+
+  subject { described_class.new(host, port) }
+  let(:server)  { double(described_class::TCPServer, close: true, accept: nil) }
+  let(:socket)  { double(described_class::TCPSocket, write: true) }
+  let(:payload) { Listen::TCP::Message.new.payload }
+
+  before do
+    expect(described_class::TCPServer).to receive(:new).with(host, port).and_return server
+  end
+
+  after do
+    subject.terminate
+  end
+
+  describe '#initialize' do
+    it 'initializes and exposes a server' do
+      expect(subject.server).to be server
+    end
+
+    it 'initializes and exposes a list of sockets' do
+      expect(subject.sockets).to eq []
+    end
+  end
+
+  describe '#start' do
+    let(:async) { double('TCP-listener async') }
+
+    it 'invokes run loop asynchronously' do
+      subject.stub(:async).and_return async
+      expect(async).to receive(:run)
+      subject.start
+    end
+  end
+
+  describe '#finalize' do
+    it 'clears sockets' do
+      expect(subject.sockets).to receive(:clear)
+      subject.finalize
+    end
+
+    it 'closes server' do
+      expect(subject.server).to receive(:close)
+      subject.finalize
+      expect(subject.server).to be_nil
+    end
+  end
+
+  describe '#broadcast' do
+    it 'unicasts to connected sockets' do
+      subject.handle_connection socket
+      expect(subject.wrapped_object).to receive(:unicast).with socket, payload
+      subject.broadcast payload
+    end
+  end
+
+  describe '#unicast' do
+    before do
+      subject.handle_connection socket
+    end
+
+    context 'when succesful' do
+      it 'returns true and leaves socket untouched' do
+        expect(subject.unicast(socket, payload)).to be_true
+        expect(subject.sockets).to include socket
+      end
+    end
+
+    context 'on IO errors' do
+      it 'returns false and removes socket from list' do
+        socket.stub(:write).and_raise IOError
+        expect(subject.unicast(socket, payload)).to be_false
+        expect(subject.sockets).not_to include socket
+      end
+    end
+
+    context 'on connection reset by peer' do
+      it 'returns false and removes socket from list' do
+        socket.stub(:write).and_raise Errno::ECONNRESET
+        expect(subject.unicast(socket, payload)).to be_false
+        expect(subject.sockets).not_to include socket
+      end
+    end
+
+    context 'on broken pipe' do
+      it 'returns false and removes socket from list' do
+        socket.stub(:write).and_raise Errno::EPIPE
+        expect(subject.unicast(socket, payload)).to be_false
+        expect(subject.sockets).not_to include socket
+      end
+    end
+  end
+
+  describe '#run' do
+    it 'handles incoming connections' do
+      server.stub(:accept).and_return socket, nil
+      expect(subject.wrapped_object).to receive(:handle_connection).with socket
+      subject.run
+    end
+  end
+
+  describe '#handle_connection' do
+    it 'adds socket to list' do
+      subject.handle_connection socket
+      expect(subject.sockets).to include socket
+    end
+  end
+
+end

data/spec/lib/listen/tcp/listener_spec.rb

@@ -0,0 +1,142 @@
+require 'spec_helper'
+
+describe Listen::TCP::Listener do
+
+  let(:host) { '10.0.0.2' }
+  let(:port) { 4000 }
+
+  subject { described_class.new("#{host}:#{port}", :recipient, options) }
+  let(:options) { {} }
+  let(:registry) { double(Celluloid::Registry, :[]= => true) }
+  let(:supervisor) { double(Celluloid::SupervisionGroup, add: true, pool: true) }
+  let(:record) { double(Listen::Record, terminate: true, build: true) }
+  let(:silencer) { double(Listen::Silencer, terminate: true) }
+  let(:adapter) { double(Listen::Adapter::Base) }
+  let(:broadcaster) { double(Listen::TCP::Broadcaster) }
+  let(:change_pool) { double(Listen::Change, terminate: true) }
+  let(:change_pool_async) { double('ChangePoolAsync') }
+  before {
+    Celluloid::Registry.stub(:new) { registry }
+    Celluloid::SupervisionGroup.stub(:run!) { supervisor }
+    registry.stub(:[]).with(:silencer) { silencer }
+    registry.stub(:[]).with(:adapter) { adapter }
+    registry.stub(:[]).with(:record) { record }
+    registry.stub(:[]).with(:change_pool) { change_pool }
+    registry.stub(:[]).with(:broadcaster) { broadcaster }
+  }
+
+  describe '#initialize' do
+    its(:mode) { should be :recipient }
+    its(:host) { should eq host }
+    its(:port) { should eq port }
+
+    it 'raises on invalid mode' do
+      expect do
+        described_class.new(port, :foo)
+      end.to raise_error ArgumentError
+    end
+
+    it 'raises on omitted target' do
+      expect do
+        described_class.new(nil, :recipient)
+      end.to raise_error ArgumentError
+    end
+  end
+
+  context 'when broadcaster' do
+    subject { described_class.new(port, :broadcaster) }
+
+    it { should be_a_broadcaster }
+    it { should_not be_a_recipient }
+
+    it 'does not force TCP adapter through options' do
+      expect(subject.options).not_to include(force_tcp: true)
+    end
+
+    context 'when host is omitted' do
+      its(:host) { should be_nil }
+    end
+
+    describe '#start' do
+      before do
+        adapter.stub_chain(:async, :start)
+        broadcaster.stub(:start)
+      end
+
+      it 'registers broadcaster' do
+        expect(supervisor).to receive(:add).with(Listen::TCP::Broadcaster, as: :broadcaster, args: [nil, port])
+        subject.start
+      end
+
+      it 'starts broadcaster' do
+        expect(broadcaster).to receive(:start)
+        subject.start
+      end
+    end
+
+    describe '#block' do
+      let(:async) { double('TCP broadcaster async', broadcast: true) }
+      let(:callback) { double(call: true) }
+      let(:changes) { {
+        modified: ['/foo'],
+        added: [],
+        removed: []
+      }}
+
+      before do
+        broadcaster.stub(:async).and_return async
+      end
+
+      after do
+        subject.block.call changes.values
+      end
+
+      context 'when paused' do
+        it 'honours paused state and does nothing' do
+          subject.pause
+          expect(broadcaster).not_to receive(:async)
+          expect(callback).not_to receive(:call)
+        end
+      end
+
+      context 'when stopped' do
+        let(:thread) { double(join: true) }
+        before do
+          subject.stub(:thread) { thread }
+        end
+
+        it 'honours stopped state and does nothing' do
+          subject.stop
+          expect(broadcaster).not_to receive(:async)
+          expect(callback).not_to receive(:call)
+        end
+      end
+
+      it 'broadcasts changes asynchronously' do
+        message = Listen::TCP::Message.new changes
+        expect(async).to receive(:broadcast).with message.payload
+      end
+
+      it 'invokes original callback block' do
+        subject.block = callback
+        expect(callback).to receive(:call).with *changes.values
+      end
+    end
+  end
+
+  context 'when recipient' do
+    subject { described_class.new(port, :recipient) }
+
+    it 'forces TCP adapter through options' do
+      expect(subject.options).to include(force_tcp: true)
+    end
+
+    it { should_not be_a_broadcaster }
+    it { should be_a_recipient }
+
+    context 'when host is omitted' do
+      its(:host) { should eq described_class::DEFAULT_HOST }
+    end
+  end
+
+end

data/spec/lib/listen/tcp/message_spec.rb

@@ -0,0 +1,104 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe Listen::TCP::Message do
+
+  let(:object)  { [1, 2, {'foo' => 'bar'}] }
+  let(:body)    { '[1,2,{"foo":"bar"}]' }
+  let(:size)    { 19 }
+  let(:payload) { "\x00\x00\x00\x13[1,2,{\"foo\":\"bar\"}]" }
+
+  describe '#initialize' do
+    it 'initializes with an object' do
+      message = described_class.new(object)
+      expect(message.object).to be object
+    end
+  end
+
+  describe '#object=' do
+    before do
+      subject.object = object
+    end
+
+    its(:object)  { should be object }
+    its(:body)    { should eq body }
+    its(:size)    { should eq size }
+    its(:payload) { should eq payload }
+  end
+
+  describe '#payload=' do
+    before do
+      subject.payload = payload
+    end
+
+    its(:object)  { should eq object }
+    its(:body)    { should eq body }
+    its(:size)    { should eq size }
+    its(:payload) { should be payload }
+  end
+
+  describe '.from_buffer' do
+
+    context 'when buffer is empty' do
+      it 'returns nil and leaves buffer intact' do
+        buffer = ''
+        message = described_class.from_buffer buffer
+        expect(message).to be_nil
+        expect(buffer).to eq ''
+      end
+    end
+
+    context 'when buffer has data' do
+
+      context 'with a partial packet' do
+        it 'returns nil and leaves remaining data intact' do
+          buffer = payload[0..4]
+          message = described_class.from_buffer buffer
+          expect(message).to be_nil
+          expect(buffer).to eq payload[0..4]
+        end
+      end
+
+      context 'with a full packet' do
+        it 'extracts message from buffer and depletes buffer' do
+          buffer = payload.dup
+          message = described_class.from_buffer buffer
+          expect(message).to be_a described_class
+          expect(message.object).to eq object
+          expect(buffer).to eq ''
+        end
+      end
+
+      context 'with a full and a partial packet' do
+        it 'extracts message from buffer and leaves remaining data intact' do
+          buffer = payload + payload[0..10]
+          message = described_class.from_buffer buffer
+          expect(message).to be_a described_class
+          expect(message.object).to eq object
+          expect(buffer).to eq payload[0..10]
+        end
+      end
+
+      context 'with two full packets' do
+        it 'extracts both messages from buffer and depletes buffer' do
+          buffer = payload + payload
+
+          message1 = described_class.from_buffer buffer
+          expect(message1).to be_a described_class
+          expect(message1.object).to eq object
+
+          message2 = described_class.from_buffer buffer
+          expect(message2).to be_a described_class
+          expect(message2.object).to eq object
+
+          expect(message1).not_to be message2
+          expect(buffer).to eq ''
+        end
+      end
+
+    end
+
+  end
+
+end

data/spec/lib/listen_spec.rb

@@ -7,6 +7,13 @@ describe Listen do
       described_class.to('/path')
     end
 
+    context 'when using :forward_to option' do
+      it 'initializes TCP-listener in broadcast-mode' do
+        expect(Listen::TCP::Listener).to receive(:new).with(4000, :broadcaster, '/path', {})
+        described_class.to('/path', forward_to: 4000)
+      end
+    end
+
     it "sets stopping at false" do
       allow(Listen::Listener).to receive(:new)
       Listen.to('/path')
@@ -20,4 +27,11 @@ describe Listen do
       expect(Listen.stopping).to be_true
     end
   end
+
+  describe '.on' do
+    it 'initializes TCP-listener in recipient-mode' do
+      expect(Listen::TCP::Listener).to receive(:new).with(4000, :recipient, '/path')
+      described_class.on(4000, '/path')
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: listen
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.5.0
 platform: ruby
 authors:
 - Thibaud Guillaume-Gentil
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-07 00:00:00.000000000 Z
+date: 2014-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: celluloid
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 0.15.2
+- !ruby/object:Gem::Dependency
+  name: celluloid-io
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.15.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.15.0
 - !ruby/object:Gem::Dependency
   name: rb-fsevent
   requirement: !ruby/object:Gem::Requirement
@@ -133,6 +147,7 @@ files:
 - lib/listen/adapter/darwin.rb
 - lib/listen/adapter/linux.rb
 - lib/listen/adapter/polling.rb
+- lib/listen/adapter/tcp.rb
 - lib/listen/adapter/windows.rb
 - lib/listen/change.rb
 - lib/listen/directory.rb
@@ -140,14 +155,19 @@ files:
 - lib/listen/listener.rb
 - lib/listen/record.rb
 - lib/listen/silencer.rb
+- lib/listen/tcp/broadcaster.rb
+- lib/listen/tcp/listener.rb
+- lib/listen/tcp/message.rb
 - lib/listen/version.rb
 - listen.gemspec
 - spec/acceptance/listen_spec.rb
+- spec/acceptance/tcp_spec.rb
 - spec/lib/listen/adapter/base_spec.rb
 - spec/lib/listen/adapter/bsd_spec.rb
 - spec/lib/listen/adapter/darwin_spec.rb
 - spec/lib/listen/adapter/linux_spec.rb
 - spec/lib/listen/adapter/polling_spec.rb
+- spec/lib/listen/adapter/tcp_spec.rb
 - spec/lib/listen/adapter/windows_spec.rb
 - spec/lib/listen/adapter_spec.rb
 - spec/lib/listen/change_spec.rb
@@ -156,6 +176,9 @@ files:
 - spec/lib/listen/listener_spec.rb
 - spec/lib/listen/record_spec.rb
 - spec/lib/listen/silencer_spec.rb
+- spec/lib/listen/tcp/broadcaster_spec.rb
+- spec/lib/listen/tcp/listener_spec.rb
+- spec/lib/listen/tcp/message_spec.rb
 - spec/lib/listen_spec.rb
 - spec/spec_helper.rb
 - spec/support/acceptance_helper.rb
@@ -187,11 +210,13 @@ specification_version: 4
 summary: Listen to file modifications
 test_files:
 - spec/acceptance/listen_spec.rb
+- spec/acceptance/tcp_spec.rb
 - spec/lib/listen/adapter/base_spec.rb
 - spec/lib/listen/adapter/bsd_spec.rb
 - spec/lib/listen/adapter/darwin_spec.rb
 - spec/lib/listen/adapter/linux_spec.rb
 - spec/lib/listen/adapter/polling_spec.rb
+- spec/lib/listen/adapter/tcp_spec.rb
 - spec/lib/listen/adapter/windows_spec.rb
 - spec/lib/listen/adapter_spec.rb
 - spec/lib/listen/change_spec.rb
@@ -200,6 +225,9 @@ test_files:
 - spec/lib/listen/listener_spec.rb
 - spec/lib/listen/record_spec.rb
 - spec/lib/listen/silencer_spec.rb
+- spec/lib/listen/tcp/broadcaster_spec.rb
+- spec/lib/listen/tcp/listener_spec.rb
+- spec/lib/listen/tcp/message_spec.rb
 - spec/lib/listen_spec.rb
 - spec/spec_helper.rb
 - spec/support/acceptance_helper.rb