iodine 0.7.59 → 0.8.0

data/SPEC-WebSocket-Draft.md

@@ -1,239 +0,0 @@
-### Draft State
-
-This draft is also implemented by [the Agoo server](https://github.com/ohler55/agoo) according to the specifications stated in [Rack PR#1272](https://github.com/rack/rack/pull/1272).
-
----
-## Purpose
-
-This document details a Rack specification extension for WebSocket / EventSource servers.
-
-The purpose of this specification is:
-
-1. To improve application safety by phasing out the use of `hijack` and replacing it with the use of application object callbacks.
-
-    This should make it easer for applications to accept WebSocket and EventSource (SSE) connections without exposing themselves to risks and errors related to IO / network logic (such as slow client attacks, buffer flooding, etc').
-
-2. To improve separation of concerns between servers and applications, moving the IO / network logic related to WebSocket and EventSource (SSE) back to the server.
-
-    Simply put, when using a server that support this extension, the application / framework doesn’t need to have any knowledge about networking, transport protocols, IO streams, polling, etc'.
-
-## Rack WebSockets / EventSource
-
-Servers that publish WebSocket and/or EventSource (SSE) support using the `env['rack.upgrade?']` value **MUST** follow the requirements set in this document.
-
-This document reserves the Rack `env` Hash keys of `rack.upgrade?` and `rack.upgrade`.
-
-A conforming server **MUST** set `env['rack.upgrade?']` to `:websocket` for incoming WebSocket connections and `:sse` for incoming EventSource (SSE) connections. 
-
-If a connection is not "upgradeable", a conforming server **SHOULD** set `env['rack.upgrade?']` to either `nil` or `false`. Setting the `env['rack.upgrade?']` to either `false` or `nil` should make it easier for applications to test for server support during a normal HTTP request.
-
-If the connection is upgradeable and a client application set a value for `env['rack.upgrade']`:
-
-* the server **MUST** use that value as a WebSocket / EventSource Callback Object unless the response status code `>= 300` (redirection / error status code).
-
-* The response `body` **MUST NOT** be sent when switching to a Callback Object.
-
-If a connection is **NOT** upgradeable and a client application set a value for `env['rack.upgrade']`:
-
-* The server **SHOULD** ignore the Callback Object and process the response as if it did not exist.
-
-* A server **MAY** use the Callback Object to allow a client to "hijack" the data stream as raw data stream. Such behavior **MUST** be documented.
-
-### The WebSocket / EventSource Callback Object
-
-WebSocket and EventSource connection upgrade and handling is performed using a Callback Object.
-
-The Callback Object could be a any object which implements any (of none) of the following callbacks:
-
-* `on_open(client)` **MUST** be called once the connection had been established and/or the Callback Object had been linked to the `client` object.
-
-* `on_message(client, data)` **MUST** be called when incoming WebSocket data is received.
-
-    This callback is ignored for EventSource connections.
-
-    `data` **MUST** be a String with an encoding of UTF-8 for text messages and `binary` encoding for non-text messages (as specified by the WebSocket Protocol).
-
-    The *callback object* **MUST** assume that the `data` String will be a **recyclable buffer** and that it's content will be corrupted the moment the `on_message` callback returns.
-
-    Servers **MAY**, optionally, implement a **recyclable buffer** for the `on_message` callback. However, this is optional, is *not* required and might result in issues in cases where the client code is less than pristine.
-
-* `on_drained(client)` **MAY** be called when the `client.write` buffer becomes empty. **If** `client.pending` ever returns a non-zero value (see later on), the `on_drained` callback **MUST** be called once the write buffer becomes empty.
-
-* `on_shutdown(client)` **MAY** be called during the server's graceful shutdown process, _before_ the connection is closed and in addition to the `on_close` function (which is called _after_ the connection is closed.
-
-* `on_close(client)` **MUST** be called _after_ the connection was closed for whatever reason (socket errors, parsing errors, timeouts, client disconnection, `client.close` being called, etc') or the Callback Object was replaced by another Callback Object.
-
-
-The server **MUST** provide the Callback Object with a `client` object, that supports the following methods (this approach promises applications could be server agnostic):
-
-* `env` **MUST** return the Rack `env` hash related to the originating HTTP request. Some changes to the `env` hash (such as removal of the IO hijacking support) **MAY** be implemented by the server.
-
-* `write(data)` **MUST** schedule **all** the data to be sent. `data` **MUST** be a String. Servers **MAY** silently convert non-String objects to JSON if an application attempts to `write` a non-String value, otherwise servers **SHOULD** throw an exception.
-
-    A call to `write` only promises that the data is scheduled to be sent. Implementation details may differ across servers.
-
-    `write` shall return `true` on success and `false` if the connection is closed.
-
-    For WebSocket connections only (irrelevant for EventSource connections):
-
-    * If `data` is UTF-8 encoded, the data will be sent as text.
-
-    * If `data` is binary encoded it will be sent as non-text (as specified by the WebSocket Protocol).
-
-    A server **SHOULD** document its concurrency model, allowing developers to know whether `write` will block or not, whether buffered IO is implemented, etc'.
-
-    For example, evented servers are encouraged to avoid blocking and return immediately, deferring the actual `write` operation for later. However, (process/thread/fiber) per-connection based servers **MAY** choose to return only after all the data was sent. Documenting these differences will allows applications to choose the model that best fits their needs and environments.
-
-* `close` closes the connection once all the data scheduled using `write` was sent. If `close` is called while there is still data to be sent, `close` **SHOULD** return immediately and only take effect once the data was sent.
-
-    `close` shall always return `nil`.
-
-* `open?` **MUST** return `false` **if** the connection was never open, is known to be closed or marked to be closed. Otherwise `true` **MUST** be returned.
-
-* `pending` **MUST** return -1 if the connection is closed. Otherwise, `pending` **SHOULD** return the number of pending writes (messages in the `write` queue\*) that need to be processed before the next time the `on_drained` callback is called.
-
-    Servers **MAY** choose to always return the value `0` **ONLY IF** they never call the `on_drained` callback and the connection is open.
-
-    Servers that return a positive number **MUST** call the `on_drained` callback when a call to `pending` would return the value `0`.
-
-    \*Servers that divide large messages into a number of smaller messages (implement message fragmentation) **MAY** count each fragment separately, as if the fragmentation was performed by the user and `write` was called more than once per message.
-
-* `pubsub?` **MUST** return `false` **unless** the pub/sub extension is supported.
-
-   Pub/Sub patterns are idiomatic for WebSockets and EventSource connections but their API is out of scope for this extension.
-
-* `class` **MUST** return the client's Class, allowing it be extended with additional features (such as Pub/Sub, etc').
-
-    **Note**: Ruby adds this method automatically to every class, no need to do a thing.
-
-The server **MAY** support the following (optional) methods for the `client` object:
-
-* `handler` if implemented, **MUST** return the callback object linked to the `client` object.
-
-* `handler=` if implemented, **MUST** set a new Callback Object for `client`.
-
-    This allows applications to switch from one callback object to another (i.e., in case of credential upgrades).
-
-    Once a new Callback Object was set, the server **MUST** call the old handler's `on_close` callback and **afterwards** call the new handler's `on_open` callback.
-
-    It is **RECOMMENDED** (but not required) that this also updates the value for `env['rack.upgrade']`.
-
-* `timeout` / `timeout=` allows applications to get / set connection timeouts dynamically and separately for each connection. Servers **SHOULD** provide a global setting for the default connection timeout. It is **RECOMMENDED** (but not required) that a global / default timeout setting be available from the command line (CLI).
-
-* `protocol` if implemented, **MUST** return the same value that was originally set by `env['rack.upgrade?']`.
-
-
-WebSocket `ping` / `pong`, timeouts and network considerations **SHOULD** be implemented by the server. It is **RECOMMENDED** (but not required) that the server send `ping`s to prevent connection timeouts and to detect network failure. Clients **SHOULD** also consider sending `ping`s to detect network errors (dropped connections).
-
-Server settings **MAY** be provided to allow for customization and adaptation for different network environments or WebSocket extensions. It is **RECOMMENDED** that any settings be available as command line arguments and **not** incorporated into the application's logic.
-
----
-
-## Implementation Examples
-
-### Server-Client Upgrade to WebSockets / EventSource
-
-* **Server**:
-
-    When a regular HTTP request arrives (non-upgradeable), the server will set the `env['rack.upgrade?']` flag to `false`, indicating that: 1. this specific request is NOT upgradable; and 2. the server supports this specification for either WebSocket and/or EventSource connections.
-
-    When a WebSocket upgrade request arrives, the server will set the `env['rack.upgrade?']` flag to `:websocket`, indicating that: 1. this specific request is upgradable; and 2. the server supports this specification for WebSocket connections.
-
-    When an EventSource request arrives, the server will set the `env['rack.upgrade?']` flag to `:sse`, indicating that: 1. this specific request is an EventSource request; and 2. the server supports this specification for EventSource connections.
-
-* **Client**:
-
-    If a client decides to upgrade a request, they will place an appropriate Callback Object in the `env['rack.upgrade']` Hash key.
-
-* **Server**:
-
-    1. If the application's response status indicates an error or a redirection (status code `>= 300`), the server shall ignore the Callback Object and/or remove it from the `env` Hash, ignoring the rest of the steps that follow.
-
-    2. The server will review the `env` Hash *before* sending the response. If the `env['rack.upgrade']` was set, the server will perform the upgrade.
-
-    3. The server will send the correct response status and headers, as well as any headers present in the response object. The server will also perform any required housekeeping, such as closing the response body, if it exists.
-
-         The response status provided by the response object shall be ignored and the correct response status shall be set by the server.
-
-    4. Once the upgrade had completed, the server will call the `on_open` callback.
-
-        No other callbacks shall be called until the `on_open` callback had returned.
-
-        WebSocket messages shall be handled by the `on_message` callback in the same order in which they arrive and the `on_message` **SHOULD NOT** be executed concurrently for the same connection.
-
-        The `on_close` callback **MUST NOT** be called while any other callback is running (`on_open`, `on_message`, `on_drained`, etc').
-
-        The `on_drained` callback **MAY** be called concurrently with the `on_message` callback, allowing data to be sent even while incoming data is being processed. Multi-threading considerations apply.
-
-## Example Usage
-
-The following is an example WebSocket echo server implemented using this specification:
-
-```ruby
-module WSConnection
-    def on_open(client)
-        puts "WebSocket connection established (#{client.object_id})."
-    end
-    def on_message(client, data)
-        client.write data # echo the data back
-        puts "on_drained MUST be implemented if #{ pending } != 0."
-    end
-    def on_drained(client)
-        puts "If this line prints out, on_drained is supported by the server."
-    end
-    def on_shutdown(client)
-        client.write "The server is going away. Goodbye."
-    end
-    def on_close(client)
-        puts "WebSocket connection closed (#{client.object_id})."
-    end
-    extend self
-end
-
-module App
-   def self.call(env)
-       if(env['rack.upgrade?'.freeze] == :websocket)
-           env['rack.upgrade'.freeze] = WSConnection
-           return [0, {}, []]
-       end
-       return [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Hello World!"]]
-   end
-end
-
-run App
-```
-
-The following example uses Push notifications for both WebSocket and SSE connections. The Pub/Sub API is subject to a separate Pub/Sub API extension and isn't part of this specification (it is, however, supported by iodine):
-
-```ruby
-module Chat
-    def on_open(client)
-        client.class.prepend MyPubSubModule unless client.pubsub?
-        client.subscribe "chat"
-        client.publish "chat", "#{env[:nickname]} joined the chat."
-    end
-    def on_message(client, data)
-        client.publish "chat", "#{env[:nickname]}: #{data}"
-    end
-    def on_close(client)
-        client.publish "chat", "#{env[:nickname]}: left the chat."
-    end
-    extend self
-end
-
-module App
-   def self.call(env)
-       if(env['rack.upgrade?'.freeze])
-           nickname = env['PATH_INFO'][1..-1]
-           nickname = "Someone" if nickname == "".freeze
-           env[:nickname] = nickname
-           return [0, {}, []]
-       end
-       return [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Hello World!"]]
-   end
-end
-
-run App
-```
-
-Note that SSE connections will only be able to receive messages (the `on_message` callback is never called).

data/bin/console

@@ -1,22 +0,0 @@
-#!/usr/bin/env ruby
-
-# this will compile Iodine and start a Ruby console with the Iodine gem loaded.
-
-Dir.chdir(File.expand_path(File.join('..', '..'), __FILE__))
-puts `rake clean`
-puts `rake compile`
-
-require 'benchmark'
-$LOAD_PATH.unshift File.expand_path(File.join('..', '..', 'lib'), __FILE__ )
-require "bundler/setup"
-require "iodine"
-
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
-IRB.start

data/bin/info.md

@@ -1,353 +0,0 @@
-# Ruby's Rack Push: Decoupling the real-time web application from the web
-
-![](https://bowild.files.wordpress.com/2018/05/6865783407_84f470ec02_o.jpg)
-
-Something exciting is coming.
-
-Everyone is talking about WebSockets and their older cousin EventSource / Server Sent Events (SSE). Faye and ActionCable are all the rage and real-time updates are becoming easier than ever.
-
-But it's all a mess. It's hard to set up, it's hard to maintain. The performance is meh. In short, the existing design is expensive - it's expensive in developer hours and it's expensive in hardware costs.
-
-However, [a new PR in the Rack repository](https://github.com/rack/rack/pull/1272) promises to change all that in the near future.
-
-This PR is a huge step towards simplifying our code base, improving real-time performance and lowering the overall cost of real-time web applications. 
-
-In a sentence, it's an important step towards [decoupling](https://softwareengineering.stackexchange.com/a/244478/224017) the web application from the web.
-
-Remember, Rack is the interface Ruby frameworks (such and Rails and Sinatra) and web applications use to communicate with the Ruby application servers. It's everywhere. So this is a big deal.
-
-## The Problem in a Nutshell
-
-The problem with the current standard approach, in a nutshell, is that each real-time application process has to run two servers in order to support real-time functionality.
-
-The two servers might be listening on the same port, they might be hidden away in some gem, but at the end of the day, two different IO event handling units have to run side by side.
-
-"Why?" you might ask. Well, since you asked, I'll tell you (if you didn't ask, skip to the solution).
-
-### The story of the temporary `hijack`
-
-This is the story of a quick temporary solution coming up on it's 5th year as the only "standard" Rack solution available.
-
-At some point in our history, the Rack specification needed a way to support long polling and other HTTP techniques. Specifically, Rails 4.0 needed something for their "live stream" feature.
-
-For this purpose, [the Rack team came up with the `hijack` API approach](https://github.com/rack/rack/pull/481#issue-9702395).
-
-This approach allowed for a quick fix to a pressing need. was meant to be temporary, something quick until Rack 2.0 was released (5 years later, the Rack protocol is still at version 1.3).
-
-The `hijack` API offers applications complete control of the socket. Just hijack the socket away from the server and voilá, instant long polling / SSE support... sort of.
-
-That's where things started to get messy.
-
-To handle the (now "free") socket, a lot of network logic had to be copied from the server layer to the application layer (buffering `write` calls, handling incoming data, protocol management, timeout handling, etc').
-
-This is an obvious violation of the "**S**" in S.O.L.I.D (single responsibility), as it adds IO handling responsibilities to the application / framework.
-
-It also violates the DRY principle, since the IO handling logic is now duplicated (once within the server and once within the application / framework).
-
-Additionally, this approach has issues with HTTP/2 connections, since the network protocol and the application are now entangled.
-
-### The obvious `hijack` price
-
-The `hijack` approach has many costs, some hidden, some more obvious.
-
-The most easily observed price is memory, performance and developer hours.
-
-Due to code duplication and extra work, the memory consumption for `hijack` based solutions is higher and their performance is slower (more system calls, more context switches, etc').
-
-Using `require 'faye'` will add WebSockets to your application, but it will take almost 9Mb just to load the gem (this is before any actual work was performed).
-
-On the other hand, using the `agoo` or `iodine` HTTP servers will add both WebScokets and SSE to your application without any extra memory consumption.
-
-To be more specific, using `iodine` will consume about 2Mb of memory, marginally less than Puma, while providing both HTTP and real-time capabilities.
-
-### The hidden `hijack` price
-
-A more subtle price is higher hardware costs and a lower clients-per-machine ratio when using `hijack`.
-
-Why?
-
-Besides the degraded performance, the `hijack` approach allows some HTTP servers to lean on the `select` system call, (Puma used `select` last time I took a look).
-
-This system call [breaks down at around the 1024 open file limit](http://man7.org/linux/man-pages/man2/select.2.html#BUGS), possibly limiting each process to 1024 open connections.
-
-When a connection is hijacked, the sockets don't close as fast as the web server expects, eventually leading to breakage and possible crashes if the 1024 open file limit is exceeded.
-
-## The Solution - Callbacks and Events 
-
-[The new proposed Rack Push PR](https://github.com/rack/rack/pull/1272) offers a wonderful effective way to implement WebSockets and SSE while allowing an application to remain totally server agnostic.
-
-This new proposal leaves the responsibility for the network / IO handling with the server, simplifying the application's code base and decoupling it from the network protocol.
-
-By using a callback object, the application is notified of any events. Leaving the application free to focus on the data rather than the network layer.
-
-The callback object doesn't even need to know anything about the server running the application or the underlying protocol.
-
-~~The callback object is automatically linked to the correct API using Ruby's `extend` approach, allowing the application to remain totally server agnostic.~~ **EDIT**: the PR was updated, replacing the `extend` approach with an extra `client` object.
-
-### How it works
-
-Every Rack server uses a Hash type object to communicate with a Rack application.
-
-This is how Rails is built, this is how Sinatra is built and this is how every Rack application / framework is built. It's in [the current Rack specification](https://github.com/rack/rack/blob/master/SPEC).
-
-A simple Hello world using Rack would look like this (placed in a file called `config.ru`):
-
-```ruby
-# normal HTTP response
-RESPONSE = [200, { 'Content-Type' => 'text/html',
-          'Content-Length' => '12' }, [ 'Hello World!' ] ]
-# note the `env` variable
-APP = Proc.new {|env| RESPONSE }
-# The Rack DSL used to run the application
-run APP
-```
-
-This new proposal introduces the `env['rack.upgrade?']` variable.
-
-Normally, this variable is set to `nil` (or missing from the `env` Hash).
-
-However, for WebSocket connection, the `env['rack.upgrade?']` variable is set to `:websocket` and for EventSource (SSE) connections the variable is set to `:sse`.
-
-To set a callback object, the `env['rack.upgrade']` is introduced (notice the *missing* question mark).
-
-Now the design might look like this:
-
-```ruby
-# Place in config.ru
-RESPONSE = [200, { 'Content-Type' => 'text/html',
-          'Content-Length' => '12' }, [ 'Hello World!' ] ]
-# an example Callback class
-class MyCallbacks
-  def on_open client
-    puts "* Push connection opened."
-  end
-  def on_message client, data
-    puts "* Incoming data: #{data}"
-    client.write "Roger that, \"#{data}\""
-  end
-  def on_close client
-    puts "* Push connection closed."
-  end
-end
-# note the `env` variable
-APP = Proc.new do |env|
-  if(env['rack.upgrade?'])
-    env['rack.upgrade'] = MyCallbacks.new
-    [200, {}, []]
-  else
-    RESPONSE
-  end
-end
-# The Rack DSL used to run the application
-run APP
-```
-
-Run this application with the Agoo or Iodine servers and let the magic sparkle.
-
-For example, using Iodine:
-
-```bash
-# install iodine, version 0.6.0 and up
-gem install iodine
-# start in single threaded mode
-iodine -t 1
-```
-
-Now open the browser, visit [localhost:3000](http://localhost:3000) and open the browser console to test some JavaScript.
-
-First try an EventSource (SSE) connection (run in browser console):
-
-```js
-// An SSE example 
-var source = new EventSource("/");
-source.onmessage = function(msg) {
-  console.log(msg.id);
-  console.log(msg.data);
-};
-```
-
-Sweet! nothing happened just yet (we aren't sending notifications), but we have an open SSE connection!
-
-What about WebSockets (run in browser console):
-
-```js
-// A WebSocket example 
-ws = new WebSocket("ws://localhost:3000/");
-ws.onmessage = function(e) { console.log(e.data); };
-ws.onclose = function(e) { console.log("closed"); };
-ws.onopen = function(e) { e.target.send("Hi!"); };
-
-```
-
-Wow! Did you look at the Ruby console - we have working WebSockets, it's that easy.
-
-And this same example will run perfectly using the Agoo server as well (both Agoo and Iodine already support the Rack Push proposal).
-
-Try it:
-
-```bash
-# install the agoo server, version 2.1.0 and up
-gem install agoo
-# start it up
-rackup -s agoo -p 3000
-```
-
-Notice, no gems, no extra code, no huge memory consumption, just the Ruby server and raw Rack (I didn't even use a framework just yet).
-
-### The amazing push
-
-So far, it's so simple, it's hard to notice how powerful this is.
-
-Consider implementing a stock ticker, or in this case, a timer:
-
-```ruby
-# Place in config.ru
-RESPONSE = [200, { 'Content-Type' => 'text/html',
-          'Content-Length' => '12' }, [ 'Hello World!' ] ]
-
-# A global live connection storage
-module LiveList
-  @list = []
-  @lock = Mutex.new
-  def <<(connection)
-    @lock.synchronize { @list << connection }
-  end
-  def >>(connection)
-    @lock.synchronize { @list.delete connection }
-  end
-  def any?
-    # remove connection to the "live list"
-    @lock.synchronize { @list.any? }
-  end
-  # this will send a message to all the connections that share the same process.
-  # (in cluster mode we get partial broadcasting only and this doesn't scale)
-  def broadcast(data)
-    # copy the list so we don't perform long operations in the critical section
-    tmp = nil # place tmp in this part of the scope
-    @lock.synchronize do
-      tmp = @list.dup # copy list into tmp
-    end
-    # iterate list outside of critical section
-    tmp.each {|c| c.write data }
-  end
-  extend self
-end
-
-# Broadcast the time very second... but...
-# Threads will BREAK in cluster mode.
-@thread = Thread.new do
-  while(LiveList.any?) do
-    sleep(1)
-    LiveList.broadcast "The time is: #{Time.now}"
-  end
-end
-
-# an example static Callback module
-module MyCallbacks
-  def on_open client
-    # add connection to the "live list"
-    LiveList << client
-  end
-  def on_message(client, data)
-    # Just an example broadcast
-    LiveList.broadcast "Special Announcement: #{data}"
-  end
-  def on_close client
-    # remove connection to the "live list"
-    LiveList >> client
-  end
-  extend self
-end
-
-# The Rack application
-APP = Proc.new do |env|
-  if(env['rack.upgrade?'])
-    env['rack.upgrade'] = MyCallbacks
-    [200, {}, []]
-  else
-    RESPONSE
-  end
-end
-# The Rack DSL used to run the application
-run APP
-```
-
-Run the iodine server in single process mode: `iodine -w 1` and the little timer is ticking.
-
-Honestly, I don't love the code I just wrote for the previous example. It's a little long, it's slightly iffy and we can't use iodine's cluster mode.
-
-For my next example, I'll author a chat room in 32 lines (including comments).
-
-I will use Iodine's pub/sub extension API to avoid the LiveList module and the timer thread. I don't want a timer, so I'll skip the [`Iodine.run_every` method](https://www.rubydoc.info/github/boazsegev/iodine/master/Iodine#run_every-class_method).
-
-Also, I'll limit the interaction to WebSocket clients. Why? to show I can.
-
-This will better demonstrate the power offered by the new `env['rack.upgrade']` approach and it will also work in cluster mode.
-
-Sadly, this means that the example won't run on Agoo for now.
-
-```ruby
-# Place in config.ru
-RESPONSE = [200, { 'Content-Type' => 'text/html',
-          'Content-Length' => '12' }, [ 'Hello World!' ] ]
-CHAT = "chat".freeze
-# a Callback class
-class MyCallbacks
-  def initialize env
-     @name = env["PATH_INFO"][1..-1]
-     @name = "unknown" if(@name.length == 0)
-  end
-  def on_open client
-    client.subscribe CHAT
-    client.publish CHAT, "#{@name} joined the chat."
-  end
-  def on_message client, data
-    client.publish CHAT, "#{@name}: #{data}"
-  end
-  def on_close client
-    client.publish CHAT, "#{@name} left the chat."
-  end
-end
-# The actual Rack application
-APP = Proc.new do |env|
-  if(env['rack.upgrade?'] == :websocket)
-    env['rack.upgrade'] = MyCallbacks.new(env)
-    [200, {}, []]
-  else
-    RESPONSE
-  end
-end
-# The Rack DSL used to run the application
-run APP
-```
-
-Start the application from the command line (in terminal):
-
-```bash
-iodine
-```
-
-Now try (in the browser console):
-
-```js
-ws = new WebSocket("ws://localhost:3000/Mitchel");
-ws.onmessage = function(e) { console.log(e.data); };
-ws.onclose = function(e) { console.log("Closed"); };
-ws.onopen = function(e) { e.target.send("Yo!"); };
-```
-
-**EDIT**: Agoo 2.1.0 now implements pub/sub extensions, albeit, using slightly different semantics. I did my best so the same code would work on both servers.
-
-### Why didn't anyone think of this sooner?
-
-Actually, this isn't a completely new idea.
-
-Evens as the `hijack` API itself was suggested, [an alternative approach was suggested](https://github.com/rack/rack/pull/481#issuecomment-11916942).
-
-Another proposal was attempted [a few years ago](https://github.com/rack/rack/issues/1093).
-
-But it seems things are finally going to change, as two high performance server, [agoo](https://github.com/ohler55/agoo) and [iodine](https://github.com/boazsegev/iodine) already support this new approach.
-
-Things look promising.
-
-**UPDATE**: code examples were updated to reflect changes in theRack specification's PR.