face-faye 0.8.9

data/lib/faye/transport/transport.rb

@@ -0,0 +1,116 @@
+module Faye
+  class Transport
+
+    include Logging
+    include Publisher
+    include Timeouts
+
+    attr_accessor :cookies, :endpoint, :headers
+
+    def initialize(client, endpoint)
+      @client   = client
+      @endpoint = endpoint
+      @outbox   = []
+    end
+
+    def batching?
+      true
+    end
+
+    def close
+    end
+
+    def connection_type
+      self.class.connection_type
+    end
+
+    def send(message, timeout)
+      debug('Client ? sending message to ?: ?', @client.client_id, @endpoint, message)
+
+      return request([message], timeout) unless batching?
+
+      @outbox << message
+      @timeout = timeout
+
+      if message['channel'] == Channel::HANDSHAKE
+        return add_timeout(:publish, 0.01) { flush }
+      end
+
+      if message['channel'] == Channel::CONNECT
+        @connection_message = message
+      end
+
+      add_timeout(:publish, Engine::MAX_DELAY) { flush }
+    end
+
+    def flush
+      remove_timeout(:publish)
+
+      if @outbox.size > 1 and @connection_message
+        @connection_message['advice'] = {'timeout' => 0}
+      end
+
+      request(@outbox, @timeout)
+
+      @connection_message = nil
+      @outbox = []
+    end
+
+    def receive(responses)
+      debug('Client ? received from ?: ?', @client.client_id, @endpoint, responses)
+      responses.each { |response| @client.receive_message(response) }
+    end
+
+    def retry_block(message, timeout)
+      lambda do
+        EventMachine.add_timer(@client.retry) { request(message, timeout) }
+      end
+    end
+
+    @transports = []
+
+    class << self
+      attr_accessor :connection_type
+
+      def get(client, allowed, disabled, &callback)
+        endpoint = client.endpoint
+
+        select = lambda do |(conn_type, klass), resume|
+          conn_endpoint = client.endpoints[conn_type] || endpoint
+
+          if disabled.include?(conn_type)
+            next resume.call
+          end
+
+          unless allowed.include?(conn_type)
+            klass.usable?(client, conn_endpoint) { |u| }
+            next resume.call
+          end
+
+          klass.usable?(client, conn_endpoint) do |is_usable|
+            next resume.call unless is_usable
+            transport = klass.respond_to?(:create) ? klass.create(client, conn_endpoint) : klass.new(client, conn_endpoint)
+            callback.call(transport)
+          end
+        end
+
+        error = lambda do
+          raise "Could not find a usable connection type for #{ endpoint }"
+        end
+
+        Faye.async_each(@transports, select, error)
+      end
+
+      def register(type, klass)
+        @transports << [type, klass]
+        klass.connection_type = type
+      end
+    end
+
+    %w[local web_socket http].each do |type|
+      require File.join(ROOT, 'faye', 'transport', type)
+    end
+
+  end
+end
+

data/lib/faye/transport/web_socket.rb

@@ -0,0 +1,92 @@
+module Faye
+
+  class Transport::WebSocket < Transport
+    UNCONNECTED = 1
+    CONNECTING  = 2
+    CONNECTED   = 3
+
+    include EventMachine::Deferrable
+
+    def self.usable?(client, endpoint, &callback)
+      create(client, endpoint).usable?(&callback)
+    end
+
+    def self.create(client, endpoint)
+      sockets = client.transports[:websocket] ||= {}
+      sockets[endpoint] ||= new(client, endpoint)
+    end
+
+    def batching?
+      false
+    end
+
+    def usable?(&callback)
+      self.callback { callback.call(true) }
+      self.errback { callback.call(false) }
+      connect
+    end
+
+    def request(messages, timeout = nil)
+      return if messages.empty?
+      @messages ||= {}
+      messages.each { |message| @messages[message['id']] = message }
+      callback { |socket| socket.send(Faye.to_json(messages)) }
+      connect
+    end
+
+    def close
+      return unless @socket
+      @socket.onclose = @socket.onerror = nil
+      @socket.close
+      @socket = nil
+      set_deferred_status(:deferred)
+      @state = UNCONNECTED
+    end
+
+    def connect
+      @state ||= UNCONNECTED
+      return unless @state == UNCONNECTED
+
+      @state = CONNECTING
+
+      @socket = Faye::WebSocket::Client.new(@endpoint.gsub(/^http(s?):/, 'ws\1:'))
+
+      @socket.onopen = lambda do |*args|
+        @state = CONNECTED
+        @ever_connected = true
+        set_deferred_status(:succeeded, @socket)
+        trigger(:up)
+      end
+
+      @socket.onmessage = lambda do |event|
+        messages = MultiJson.load(event.data)
+        next if messages.nil?
+        messages = [messages].flatten
+        messages.each { |message| @messages.delete(message['id']) }
+        receive(messages)
+      end
+
+      @socket.onclose = @socket.onerror = lambda do |*args|
+        was_connected = (@state == CONNECTED)
+        set_deferred_status(:deferred)
+        @state = UNCONNECTED
+
+        close
+
+        next resend if was_connected
+        next set_deferred_status(:failed) unless @ever_connected
+
+        EventMachine.add_timer(@client.retry) { connect }
+        trigger(:down)
+      end
+    end
+
+    def resend
+      return unless @messages
+      request(@messages.values)
+    end
+  end
+
+  Transport.register 'websocket', Transport::WebSocket
+
+end

data/lib/faye/util/namespace.rb

@@ -0,0 +1,20 @@
+module Faye
+  class Namespace
+
+    extend Forwardable
+    def_delegator :@used, :delete, :release
+    def_delegator :@used, :has_key?, :exists?
+
+    def initialize
+      @used = {}
+    end
+
+    def generate
+      name = Engine.random
+      name = Engine.random while @used.has_key?(name)
+      @used[name] = name
+    end
+
+  end
+end
+

data/spec/browser.html

@@ -0,0 +1,45 @@
+<!doctype html>
+<html>
+  <head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8">
+    <title>Faye test suite</title>
+    <script type="text/javascript" src="../node_modules/jsclass/min/loader.js"></script>
+  </head>
+  <body>
+    <script type="text/javascript">
+
+      if (typeof TestSwarm === 'undefined')
+        TestSwarm = {
+          submit: function(result) {
+            if (window.console) console.log(Faye.toJSON(result));
+          },
+          heartbeat: function() {}
+        }
+
+      JS.cacheBust = true
+
+      JS.Packages(function() { with(this) {
+        file('../build/browser/faye-browser-min.js').provides('Faye')
+        autoload(/.*Spec/, {from: './javascript'})
+      }})
+
+      JS.require('Faye', 'JS.Test', 'JS.Range', function() {
+        JS.Test.Unit.Assertions.include({
+          assertYield: function(expected) {
+            var testcase = this
+            return function(actual) { testcase.assertEqual(expected, actual) }
+          }
+        })
+
+        JS.require( 'FayeSpec',
+                    'GrammarSpec',
+                    'ChannelSpec',
+                    'ClientSpec',
+                    'TransportSpec',
+                    JS.Test.method('autorun'))
+      })
+
+    </script>
+  </body>
+</html>
+

data/spec/encoding_helper.rb

@@ -0,0 +1,7 @@
+module EncodingHelper
+  def encode(string)
+    return string unless string.respond_to?(:force_encoding)
+    string.force_encoding("UTF-8")
+  end
+end
+

data/spec/install.sh

@@ -0,0 +1,78 @@
+# This script installs all the necessary software to run the Ruby and
+# Node versions of Faye, as well as the load testing tools AB and Tsung.
+
+# Tested on Ubuntu 10.04 LTS 64-bit EC2 image:
+# http://uec-images.ubuntu.com/releases/10.04/release/
+
+FAYE_BRANCH=master
+NODE_VERSION=0.4.10
+PHANTOM_VERSION=1.2
+REDIS_VERSION=2.2.12
+RUBY_VERSION=1.9.2
+TSUNG_VERSION=1.3.3
+
+sudo apt-get update
+sudo apt-get install build-essential g++ git-core curl wget \
+                     openssl libcurl4-openssl-dev libreadline-dev \
+                     apache2-utils erlang gnuplot \
+                     libqt4-dev qt4-qmake xvfb
+
+# Install RVM and Ruby
+bash < <(curl -s https://rvm.beginrescueend.com/install/rvm)
+echo "source \"\$HOME/.rvm/scripts/rvm\"" | tee -a ~/.bashrc
+source ~/.rvm/scripts/rvm
+rvm install $RUBY_VERSION
+rvm --default use $RUBY_VERSION
+echo "install: --no-rdoc --no-ri
+update: --no-rdoc --no-ri" | tee ~/.gemrc
+gem install rake bundler
+
+# Install nvm and Node
+cd ~
+git clone git://github.com/creationix/nvm.git ~/.nvm
+. ~/.nvm/nvm.sh
+echo ". ~/.nvm/nvm.sh" | tee -a ~/.bashrc
+nvm install v$NODE_VERSION
+nvm use v$NODE_VERSION
+
+# Install Redis from source
+cd /usr/src
+sudo wget http://redis.googlecode.com/files/redis-$REDIS_VERSION.tar.gz
+sudo tar zxvf redis-$REDIS_VERSION.tar.gz
+cd redis-$REDIS_VERSION
+sudo make
+sudo ln -s /usr/src/redis-$REDIS_VERSION/src/redis-server /usr/bin/redis-server
+sudo ln -s /usr/src/redis-$REDIS_VERSION/src/redis-cli    /usr/bin/redis-cli
+
+# Install PhantomJS
+cd /usr/src
+sudo git clone git://github.com/ariya/phantomjs.git
+cd phantomjs
+sudo git checkout $PHANTOM_VERSION
+sudo qmake-qt4
+sudo make
+sudo ln -s /usr/src/phantomjs/bin/phantomjs /usr/bin/phantomjs
+echo "To use phantomjs, run DISPLAY=:1 Xvfb :1 -screen 0 1024x768x16"
+
+# Install Tsung and required Perl modules
+cd /usr/src
+sudo wget http://tsung.erlang-projects.org/dist/tsung-$TSUNG_VERSION.tar.gz
+sudo tar zxvf tsung-$TSUNG_VERSION.tar.gz
+cd tsung-$TSUNG_VERSION
+sudo ./configure
+sudo make
+sudo make install
+sudo ln -s /usr/lib/tsung/bin/tsung_stats.pl /usr/bin/tsung-stats
+echo "To use tsung-stats you need to 'install Template' from CPAN"
+sudo perl -MCPAN -eshell
+
+# Check out and build Faye project
+cd ~
+git clone git://github.com/faye/faye.git
+cd faye
+git checkout $FAYE_BRANCH
+git submodule update --init --recursive
+bundle install
+npm install redis
+cd vendor/js.class && jake
+cd ../.. && jake

data/spec/javascript/channel_spec.js

@@ -0,0 +1,15 @@
+JS.ENV.ChannelSpec = JS.Test.describe("Channel", function() { with(this) {
+  describe("expand", function() { with(this) {
+    it("returns all patterns that match a channel", function() { with(this) {
+
+      assertEqual( ["/**", "/foo", "/*"],
+                   Faye.Channel.expand("/foo") )
+
+      assertEqual( ["/**", "/foo/bar", "/foo/*", "/foo/**"],
+                   Faye.Channel.expand("/foo/bar") )
+
+      assertEqual( ["/**", "/foo/bar/qux", "/foo/bar/*", "/foo/**", "/foo/bar/**"],
+                   Faye.Channel.expand("/foo/bar/qux") )
+    }})
+  }})
+}})

data/spec/javascript/client_spec.js

@@ -0,0 +1,729 @@
+JS.ENV.ClientSpec = JS.Test.describe("Client", function() { with(this) {
+  before(function() { with(this) {
+    this.transport = {connectionType: "fake", send: function() {}}
+    Faye.extend(transport, Faye.Publisher)
+    stub(Faye.Transport, "get").yields([transport])
+  }})
+
+  before(function() { with(this) {
+    stub("setTimeout")
+  }})
+
+  define("stubResponse", function(response) { with(this) {
+    stub(transport, "send", function(message) {
+      response.id = message.id
+      client.receiveMessage(response)
+    })
+  }})
+
+  define("createClient", function() { with(this) {
+    this.client = new Faye.Client("http://localhost/")
+  }})
+
+  define("createConnectedClient", function() { with(this) {
+    createClient()
+    stubResponse({channel:    "/meta/handshake",
+                  successful: true,
+                  version:    "1.0",
+                  supportedConnectionTypes: ["websocket"],
+                  clientId:   "fakeid" })
+
+    client.handshake()
+  }})
+
+  define("subscribe", function(client, channel, callback) { with(this) {
+    stubResponse({channel:      "/meta/subscribe",
+                  successful:   true,
+                  clientId:     "fakeid",
+                  subscription: channel })
+
+    this.subsCalled = 0
+    callback = callback || function() { subsCalled += 1 }
+    client.subscribe(channel, callback)
+  }})
+
+  describe("initialize", function() { with(this) {
+    it("puts the client in the UNCONNECTED state", function() { with(this) {
+      stub(Faye.Transport, "get")
+      var client = new Faye.Client("http://localhost/")
+      assertEqual( "UNCONNECTED", client.getState() )
+    }})
+  }})
+
+  describe("handshake", function() { with(this) {
+    before(function() { this.createClient() })
+
+   it("creates a transport the server must support", function() { with(this) {
+      expect(Faye.Transport, "get").given(instanceOf(Faye.Client),
+                                          ["long-polling", "callback-polling", "in-process"],
+                                          [])
+                                   .yielding([transport])
+      client.handshake()
+    }})
+
+   it("sends a handshake message to the server", function() { with(this) {
+      expect(transport, "send").given({
+        channel:  "/meta/handshake",
+        version:  "1.0",
+        supportedConnectionTypes: ["fake"],
+        id:       instanceOf("string")
+      }, 60)
+      client.handshake()
+    }})
+
+    it("puts the client in the CONNECTING state", function() { with(this) {
+      stub(transport, "send")
+      client.handshake()
+      assertEqual( "CONNECTING", client.getState() )
+    }})
+
+    describe("with an outgoing extension installed", function() { with(this) {
+      before(function() { with(this) {
+        var extension = {
+          outgoing: function(message, callback) {
+            message.ext = {auth: "password"}
+            callback(message)
+          }
+        }
+        client.addExtension(extension)
+      }})
+
+      it("passes the handshake message through the extension", function() { with(this) {
+        expect(transport, "send").given({
+          channel:  "/meta/handshake",
+          version:  "1.0",
+          supportedConnectionTypes: ["fake"],
+          id:       instanceOf("string"),
+          ext:      {auth: "password"}
+        }, 60)
+        client.handshake()
+      }})
+    }})
+
+    describe("on successful response", function() { with(this) {
+      before(function() { with(this) {
+        stubResponse({channel:    "/meta/handshake",
+                      successful: true,
+                      version:    "1.0",
+                      supportedConnectionTypes: ["long-polling", "websocket"],
+                      clientId:   "fakeid" })
+      }})
+
+      it("stores the clientId", function() { with(this) {
+        client.handshake()
+        assertEqual( "fakeid", client.getClientId() )
+      }})
+
+      it("puts the client in the CONNECTED state", function() { with(this) {
+        client.handshake()
+        assertEqual( "CONNECTED", client.getState() )
+      }})
+
+      it("registers any pre-existing subscriptions", function() { with(this) {
+        expect(client, "subscribe").given([], true)
+        client.handshake()
+      }})
+
+      it("selects a new transport based on what the server supports", function() { with(this) {
+        expect(Faye.Transport, "get").given(instanceOf(Faye.Client), ["long-polling", "websocket"], [])
+                                     .yielding([transport])
+        client.handshake()
+      }})
+
+      describe("with websocket disabled", function() { with(this) {
+        before(function() { this.client.disable('websocket') })
+
+        it("selects a new transport, excluding websocket", function() { with(this) {
+          expect(Faye.Transport, "get").given(instanceOf(Faye.Client),
+                                              ["long-polling", "websocket"],
+                                              ["websocket"])
+                                       .yielding([transport])
+          client.handshake()
+        }})
+      }})
+    }})
+
+    describe("on unsuccessful response", function() { with(this) {
+      before(function() { with(this) {
+        stubResponse({channel:    "/meta/handshake",
+                      successful: false,
+                      version:    "1.0",
+                      supportedConnectionTypes: ["websocket"] })
+      }})
+
+      it("schedules a retry", function() { with(this) {
+        expect("setTimeout")
+        client.handshake()
+      }})
+
+      it("puts the client in the UNCONNECTED state", function() { with(this) {
+        stub("setTimeout")
+        client.handshake()
+        assertEqual( "UNCONNECTED", client.getState() )
+      }})
+    }})
+
+    describe("with existing subscriptions after a server restart", function() { with(this) {
+      before(function() { with(this) {
+        createConnectedClient()
+
+        this.message = null
+        subscribe(client, "/messages/foo", function(m) { message = m })
+
+        client.receiveMessage({advice: {reconnect: "handshake"}})
+
+        stubResponse({channel:      "/meta/handshake",
+                      successful:   true,
+                      version:      "1.0",
+                      supportedConnectionTypes: ["websocket"],
+                      clientId:     "reconnectid",
+                      subscription: "/messages/foo" })  // tacked on to trigger subscribe() callback
+      }})
+
+      it("resends the subscriptions to the server", function() { with(this) {
+        expect(transport, "send").given({
+          channel:      "/meta/subscribe",
+          clientId:     "reconnectid",
+          subscription: "/messages/foo",
+          id:           instanceOf("string")
+        }, 60)
+        client.handshake()
+      }})
+
+      it("retains the listeners for the subscriptions", function() { with(this) {
+        client.handshake()
+        client.receiveMessage({channel: "/messages/foo", "data": "ok"})
+        assertEqual( "ok", message )
+      }})
+    }})
+
+    describe("with a connected client", function() { with(this) {
+      before(function() { this.createConnectedClient() })
+
+      it("does not send a handshake message to the server", function() { with(this) {
+        expect(transport, "send").given({
+          channel:  "/meta/handshake",
+          version:  "1.0",
+          supportedConnectionTypes: ["fake"],
+          id:       instanceOf("string")
+        }, 60)
+        .exactly(0)
+
+        client.handshake()
+      }})
+    }})
+  }})
+
+  describe("connect", function() { with(this) {
+    describe("with an unconnected client", function() { with(this) {
+      before(function() { with(this) {
+        stubResponse({channel:    "/meta/handshake",
+                      successful: true,
+                      version:    "1.0",
+                      supportedConnectionTypes: ["websocket"],
+                      clientId:   "handshakeid" })
+
+        createClient()
+      }})
+
+      it("handshakes before connecting", function() { with(this) {
+        expect(transport, "send").given({
+          channel:        "/meta/connect",
+          clientId:       "handshakeid",
+          connectionType: "fake",
+          id:             instanceOf("string")
+        }, 60)
+        client.connect()
+      }})
+    }})
+
+    describe("with a connected client", function() { with(this) {
+      before(function() { this.createConnectedClient() })
+
+      it("sends a connect message to the server", function() { with(this) {
+        expect(transport, "send").given({
+          channel:        "/meta/connect",
+          clientId:       "fakeid",
+          connectionType: "fake",
+          id:             instanceOf("string")
+        }, 60)
+        client.connect()
+      }})
+
+      it("only opens one connect request at a time", function() { with(this) {
+        expect(transport, "send").given({
+          channel:        "/meta/connect",
+          clientId:       "fakeid",
+          connectionType: "fake",
+          id:             instanceOf("string")
+        }, 60)
+        .exactly(1)
+
+        client.connect()
+        client.connect()
+      }})
+    }})
+  }})
+
+  describe("disconnect", function() { with(this) {
+    before(function() { this.createConnectedClient() })
+
+    it("sends a disconnect message to the server", function() { with(this) {
+      expect(transport, "send").given({
+        channel:  "/meta/disconnect",
+        clientId: "fakeid",
+        id:       instanceOf("string")
+      }, 60)
+      client.disconnect()
+    }})
+
+    it("puts the client in the DISCONNECTED state", function() { with(this) {
+      stub(transport, "close")
+      client.disconnect()
+      assertEqual( "DISCONNECTED", client.getState() )
+    }})
+
+    describe("on successful response", function() { with(this) {
+      before(function() { with(this) {
+        stubResponse({channel:      "/meta/disconnect",
+                      successful:   true,
+                      clientId:     "fakeid" })
+      }})
+
+      it("closes the transport", function() { with(this) {
+        expect(transport, "close")
+        client.disconnect()
+      }})
+    }})
+  }})
+
+  describe("subscribe", function() { with(this) {
+    before(function() { with(this) {
+      createConnectedClient()
+      this.subscribeMessage = {
+          channel:      "/meta/subscribe",
+          clientId:     "fakeid",
+          subscription: "/foo",
+          id:           instanceOf("string")
+        }
+    }})
+
+    describe("with no prior subscriptions", function() { with(this) {
+      it("sends a subscribe message to the server", function() { with(this) {
+        expect(transport, "send").given(subscribeMessage, 60)
+        client.subscribe("/foo")
+      }})
+
+      // The Bayeux spec says the server should accept a list of subscriptions
+      // in one message but the cometD server doesn't actually support this
+      describe("with an array of subscriptions", function() { with(this) {
+        it("sends multiple subscribe messages", function() { with(this) {
+          expect(transport, "send").given({
+            channel:      "/meta/subscribe",
+            clientId:     "fakeid",
+            subscription: "/foo",
+            id:           instanceOf("string")
+          }, 60)
+          expect(transport, "send").given({
+            channel:      "/meta/subscribe",
+            clientId:     "fakeid",
+            subscription: "/bar",
+            id:           instanceOf("string")
+          }, 60)
+          client.subscribe(["/foo", "/bar"])
+        }})
+
+        it("returns an array of subscriptions", function() { with(this) {
+          stub(transport, "send")
+          var subs = client.subscribe(["/foo", "/bar"])
+          assertEqual( 2, subs.length )
+          assertKindOf( Faye.Subscription, subs[0] )
+        }})
+      }})
+
+      describe("on successful response", function() { with(this) {
+        before(function() { with(this) {
+          stubResponse({channel:      "/meta/subscribe",
+                        successful:   true,
+                        clientId:     "fakeid",
+                        subscription: "/foo/*" })
+        }})
+
+        it("sets up a listener for the subscribed channel", function() { with(this) {
+          var message
+          client.subscribe("/foo/*", function(m) { message = m })
+          client.receiveMessage({channel: "/foo/bar", data: "hi"})
+          assertEqual( "hi", message )
+        }})
+
+        it("does not call the listener for non-matching channels", function() { with(this) {
+          var message
+          client.subscribe("/foo/*", function(m) { message = m })
+          client.receiveMessage({channel: "/bar", data: "hi"})
+          assertEqual( undefined, message )
+        }})
+
+        it("activates the subscription", function() { with(this) {
+          var active = false
+          client.subscribe("/foo/*").callback(function() { active = true })
+          assert( active )
+        }})
+
+        describe("with an incoming extension installed", function() { with(this) {
+          before(function() { with(this) {
+            var extension = {
+              incoming: function(message, callback) {
+                if (message.data) message.data.changed = true
+                callback(message)
+              }
+            }
+            client.addExtension(extension)
+            this.message = null
+            client.subscribe("/foo/*", function(m) { message = m })
+          }})
+
+          it("passes delivered messages through the extension", function() { with(this) {
+            client.receiveMessage({channel: "/foo/bar", data: {hello: "there"}})
+            assertEqual( {hello: "there", changed: true}, message )
+          }})
+        }})
+
+        describe("with an outgoing extension installed", function() { with(this) {
+          before(function() { with(this) {
+            var extension = {
+              outgoing: function(message, callback) {
+                if (message.data) message.data.changed = true
+                callback(message)
+              }
+            }
+            client.addExtension(extension)
+            this.message = null
+            client.subscribe("/foo/*", function(m) { message = m })
+          }})
+
+          it("leaves messages unchanged", function() { with(this) {
+            client.receiveMessage({channel: "/foo/bar", data: {hello: "there"}})
+            assertEqual( {hello: "there"}, message )
+          }})
+        }})
+
+        describe("with an incoming extension that invalidates the response", function() { with(this) {
+          before(function() { with(this) {
+            var extension = {
+              incoming: function(message, callback) {
+                if (message.channel === "/meta/subscribe") message.successful = false
+                callback(message)
+              }
+            }
+            client.addExtension(extension)
+          }})
+
+          it("does not set up a listener for the subscribed channel", function() { with(this) {
+            var message
+            client.subscribe("/foo/*", function(m) { message = m })
+            client.receiveMessage({channel: "/foo/bar", data: "hi"})
+            assertEqual( undefined, message )
+          }})
+
+          it("does not activate the subscription", function() { with(this) {
+            var active = false
+            client.subscribe("/foo/*").callback(function() { active = true })
+            assert( !active )
+          }})
+        }})
+      }})
+
+      describe("on unsuccessful response", function() { with(this) {
+        before(function() { with(this) {
+          stubResponse({channel:      "/meta/subscribe",
+                        successful:   false,
+                        error:        "403:/meta/foo:Forbidden channel",
+                        clientId:     "fakeid",
+                        subscription: "/meta/foo" })
+        }})
+
+        it("does not set up a listener for the subscribed channel", function() { with(this) {
+          var message
+          client.subscribe("/meta/foo", function(m) { message = m })
+          client.receiveMessage({channel: "/meta/foo", data: "hi"})
+          assertEqual( undefined, message )
+        }})
+
+        it("does not activate the subscription", function() { with(this) {
+          var active = false
+          client.subscribe("/meta/foo").callback(function() { active = true })
+          assert( !active )
+        }})
+
+        it("reports the error through an errback", function() { with(this) {
+          var error = null
+          client.subscribe("/meta/foo").errback(function(e) { error = e })
+          assertEqual( objectIncluding({code: 403, params: ["/meta/foo"], message: "Forbidden channel"}), error )
+        }})
+      }})
+    }})
+
+    describe("with an existing subscription", function() { with(this) {
+      before(function() { with(this) {
+        subscribe(client, "/foo/*")
+      }})
+
+      it("does not send another subscribe message to the server", function() { with(this) {
+        expect(transport, "send").given(subscribeMessage, 60).exactly(0)
+        client.subscribe("/foo/*")
+      }})
+
+      it("sets up another listener on the channel", function() { with(this) {
+        client.subscribe("/foo/*", function() { subsCalled += 1 })
+        client.receiveMessage({channel: "/foo/bar", data: "hi"})
+        assertEqual( 2, subsCalled )
+      }})
+
+      it("activates the subscription", function() { with(this) {
+        var active = false
+        client.subscribe("/foo/*").callback(function() { active = true })
+        assert( active )
+      }})
+    }})
+  }})
+
+  describe("unsubscribe", function() { with(this) {
+    before(function() { with(this) {
+      createConnectedClient()
+      this.unsubscribeMessage = {
+          channel:      "/meta/unsubscribe",
+          clientId:     "fakeid",
+          subscription: "/foo/*",
+          id:           instanceOf("string")
+        }
+    }})
+
+    describe("with no subscriptions", function() { with(this) {
+      it("does not send an unsubscribe message to the server", function() { with(this) {
+        expect(transport, "send").given(unsubscribeMessage, 60).exactly(0)
+        client.unsubscribe("/foo/*")
+      }})
+    }})
+
+    describe("with a single subscription", function() { with(this) {
+      before(function() { with(this) {
+        this.message  = null
+        this.listener = function(m) { message = m }
+        subscribe(client, "/foo/*", listener)
+      }})
+
+      it("sends an unsubscribe message to the server", function() { with(this) {
+        expect(transport, "send").given(unsubscribeMessage, 60)
+        client.unsubscribe("/foo/*")
+      }})
+
+      it("removes the listener from the channel", function() { with(this) {
+        client.receiveMessage({channel: "/foo/bar", data: "first"})
+        client.unsubscribe("/foo/*", listener)
+        client.receiveMessage({channel: "/foo/bar", data: "second"})
+        assertEqual( "first", message )
+      }})
+    }})
+
+    describe("with multiple subscriptions to the same channel", function() { with(this) {
+      before(function() { with(this) {
+        this.messages = []
+        this.hey = function(m) { messages.push("hey " + m.text) }
+        this.bye = function(m) { messages.push("bye " + m.text) }
+        subscribe(client, "/foo/*", hey)
+        subscribe(client, "/foo/*", bye)
+      }})
+
+      it("removes one of the listeners from the channel", function() { with(this) {
+        client.receiveMessage({channel: "/foo/bar", data: {text: "you"}})
+        client.unsubscribe("/foo/*", hey)
+        client.receiveMessage({channel: "/foo/bar", data: {text: "you"}})
+        assertEqual( ["hey you", "bye you", "bye you"], messages)
+      }})
+
+      it("does not send an unsubscribe message if one listener is removed", function() { with(this) {
+        expect(transport, "send").given(unsubscribeMessage, 60).exactly(0)
+        client.unsubscribe("/foo/*", bye)
+      }})
+
+      it("sends an unsubscribe message if each listener is removed", function() { with(this) {
+        expect(transport, "send").given(unsubscribeMessage, 60)
+        client.unsubscribe("/foo/*", bye)
+        client.unsubscribe("/foo/*", hey)
+      }})
+
+      it("sends an unsubscribe message if all listeners are removed", function() { with(this) {
+        expect(transport, "send").given(unsubscribeMessage, 60)
+        client.unsubscribe("/foo/*")
+      }})
+    }})
+
+    describe("with multiple subscriptions to different channels", function() { with(this) {
+      before(function() { with(this) {
+        subscribe(client, "/foo")
+        subscribe(client, "/bar")
+      }})
+
+      it("sends multiple unsubscribe messages if given an array", function() { with(this) {
+        expect(transport, "send").given({
+          channel:      "/meta/unsubscribe",
+          clientId:     "fakeid",
+          subscription: "/foo",
+          id:           instanceOf("string")
+        }, 60)
+        expect(transport, "send").given({
+          channel:      "/meta/unsubscribe",
+          clientId:     "fakeid",
+          subscription: "/bar",
+          id:           instanceOf("string")
+        }, 60)
+        client.unsubscribe(["/foo", "/bar"])
+      }})
+    }})
+  }})
+
+  describe("publish", function() { with(this) {
+    before(function() { this.createConnectedClient() })
+
+    it("sends the message to the server with an ID", function() { with(this) {
+      expect(transport, "send").given({
+        channel:  "/messages/foo",
+        clientId: "fakeid",
+        data:     {hello: "world"},
+        id:       instanceOf("string")
+      }, 60)
+      client.publish("/messages/foo", {hello: "world"})
+    }})
+
+    describe("on publish failure", function() { with(this) {
+      before(function() { with(this) {
+        stubResponse({channel:    "/messages/foo",
+                      error:      "407:/messages/foo:Failed to publish",
+                      successful: false,
+                      clientId:   "fakeid" })
+      }})
+
+      it("should not be published", function() { with(this) {
+        var published = false
+        client.publish("/messages/foo", {text: "hi"}).callback(function() { published = true })
+        assert( !published )
+      }})
+
+      it("reports the error through an errback", function() { with(this) {
+        var error = null
+        client.publish("/messages/foo", {text: "hi"}).errback(function(e) { error = e })
+        assertEqual( 407, error.code )
+        assertEqual( ["/messages/foo"], error.params )
+        assertEqual( "Failed to publish", error.message )
+      }})
+    }})
+
+    describe("on receipt of the published message", function() { with(this) {
+      before(function() { with(this) {
+        stubResponse({channel:    "/messages/foo",
+                      data:       {text: "hi"},
+                      clientId:   "fakeid" })
+      }})
+
+      it("does not trigger the callbacks", function() { with(this) {
+        var published = false
+        var publication = client.publish("/messages/foo", {text: "hi"})
+        publication.callback(function() { published = true })
+        publication.errback(function() { published = true })
+        assert( !published )
+      }})
+    }})
+
+    describe("with an outgoing extension installed", function() { with(this) {
+      before(function() { with(this) {
+        var extension = {
+          outgoing: function(message, callback) {
+            message.ext = {auth: "password"}
+            callback(message)
+          }
+        }
+        client.addExtension(extension)
+      }})
+
+      it("passes messages through the extension", function() { with(this) {
+        expect(transport, "send").given({
+          channel:  "/messages/foo",
+          clientId: "fakeid",
+          data:     {hello: "world"},
+          id:       instanceOf("string"),
+          ext:      {auth: "password"}
+        }, 60)
+        client.publish("/messages/foo", {hello: "world"})
+      }})
+    }})
+
+    describe("with an incoming extension installed", function() { with(this) {
+      before(function() { with(this) {
+        var extension = {
+          incoming: function(message, callback) {
+            message.ext = {auth: "password"}
+            callback(message)
+          }
+        }
+        client.addExtension(extension)
+      }})
+
+      it("leaves the message unchanged", function() { with(this) {
+        expect(transport, "send").given({
+          channel:  "/messages/foo",
+          clientId: "fakeid",
+          data:     {hello: "world"},
+          id:       instanceOf("string")
+        }, 60)
+        client.publish("/messages/foo", {hello: "world"})
+      }})
+    }})
+  }})
+
+  describe("network notifications", function() { with(this) {
+    before(function() { with(this) {
+      createClient()
+      client.handshake()
+    }})
+
+    describe("in the default state", function() { with(this) {
+      it("broadcasts a down notification", function() { with(this) {
+        expect(client, "trigger").given("transport:down")
+        transport.trigger("down")
+      }})
+
+      it("broadcasts an up notification", function() { with(this) {
+        expect(client, "trigger").given("transport:up")
+        transport.trigger("up")
+      }})
+    }})
+
+    describe("when the transport is up", function() { with(this) {
+      before(function() { this.transport.trigger("up") })
+
+      it("broadcasts a down notification", function() { with(this) {
+        expect(client, "trigger").given("transport:down")
+        transport.trigger("down")
+      }})
+
+      it("does not broadcast an up notification", function() { with(this) {
+        expect(client, "trigger").exactly(0)
+        transport.trigger("up")
+      }})
+    }})
+
+    describe("when the transport is down", function() { with(this) {
+      before(function() { this.transport.trigger("down") })
+
+      it("does not broadcast a down notification", function() { with(this) {
+        expect(client, "trigger").exactly(0)
+        transport.trigger("down")
+      }})
+
+      it("broadcasts an up notification", function() { with(this) {
+        expect(client, "trigger").given("transport:up")
+        transport.trigger("up")
+      }})
+    }})
+  }})
+}})