iodine 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 360dcbeabc106918078a92d3902fc8ef1a94323c933e028c99224a2ef3b5409a
-  data.tar.gz: 75425229c8fefd9429d0f8d0936186d13668eb7b3f7c8905e16e3d617cdd3390
+  metadata.gz: c633ef1f40df47f2edefcd78b2bd3fc2a896ab7a704b298f42765d605b375947
+  data.tar.gz: e810cccda11b73c2c4881fd90e4e0132efbf62c11857edee457381cb700c6302
 SHA512:
-  metadata.gz: 1f437aad47df8fc727bf360692597e31ad41e297d1ff7dfe46786b9d3d7a9c40ff334e3eeca8cec1927b2143d4509b2ce509eaf192d9d521f4113b0b68a1cec8
-  data.tar.gz: ca852958d4f264f907911f95fbd44288b8e6b525afdfc5708b51d2ea13b3d8e236c166544b19686151fdf2c73741b7353e2c2a90b28702275158f16bdf311eeb
+  metadata.gz: 1e376b5ca69fb98da82062508687cd2bdaf7bb55b2071559d23c2f5eb330cd7fc9f7856865a86cb382357106835027e5296a8f0c67113a0522dd1a6ac9323bbf
+  data.tar.gz: ecd04e8c645961e8df5e4bfa7e2666a71a81dfda1647fe7e43c27894abb9431010663821d36a99bca23727cb0077f6f00144e0cd563a2a34ba9426ab80bb24cb

data/CHANGELOG.md

@@ -6,6 +6,20 @@ Please notice that this change log contains changes for upcoming releases as wel
 
 ## Changes:
 
+#### Change log v.0.6.0
+
+I apologize to all my amazing early adopters for the rapid changes in the API for connection objects (SSE / WebSockets) and Pub/Sub. This was a result of an attempt to create a de-facto standard with other server authors. Hopefully the API in the 0.6.0 release will see the last of the changes.
+
+**API BREAKING CHANGE**: The API for persistent connections (SSE / WebSockets) was drastically changed in accordance with the Rack specification discussion that required each callback to accept a "client" object (replacing the `extend` approach). Please see the documentation.
+
+**API BREAKING CHANGE**: `Iodine.attach` was removed due to instability and issues regarding TLS/SSL and file system IO. I hope to fix these issues in a future release. For now the `Iodine.attach_fd` can be used for clear-text sockets and pipes.
+
+**API BREAKING CHANGE**: Pub/Sub API was changed, replacing the previously suggested pub/sub object with an updated `unsubscribe` method. This means there's no need for the client to map channel names to specific subscriptions (Iodine will perform this housekeeping task for the client).
+
+**Fix**: Iodine should now build correctly on FreeBSD. Credit to @adam12 (Adam Daniels) for detecting the issue.
+
+---
+
 #### Change log v.0.5.2
 
 **Fix**: fixed compilation issues on FreeBSD. Credit to @adam12 (Adam Daniels) for opening issue #35 and offering a patch.

data/README.md

@@ -21,33 +21,17 @@ Iodine is a fast concurrent web server for real-time Ruby applications, with nat
 
 Iodine is an **evented** framework with a simple API that builds off the low level [C code library facil.io](https://github.com/boazsegev/facil.io) with support for **epoll** and **kqueue** - this means that:
 
-* Iodine can handle **thousands of concurrent connections** (tested with more then 20K connections)!
+* Iodine can handle **thousands of concurrent connections** (tested with more then 20K connections on Linux)!
 
-* Iodine supports only **Linux/Unix** based systems (i.e. macOS, Ubuntu, FreeBSD etc'), which are ideal for evented IO (while Windows and Solaris are better at IO *completion* events, which are totally different). Currently, macOS support is limited to 10.12 or higher (see [issue #32](https://github.com/boazsegev/iodine/issues/32))
+* Iodine supports only **Linux/Unix** based systems (i.e. macOS, Ubuntu, FreeBSD etc'), which are ideal for evented IO (while Windows and Solaris are better at IO *completion* events, which are totally different).
 
 Iodine is a C extension for Ruby, developed and optimized for Ruby MRI 2.2.2 and up... it should support the whole Ruby 2.0 MRI family, but Rack requires Ruby 2.2.2, and so iodine matches this requirement.
 
----
-
-## Important Note about API Changes and Standardization 
-
-I am very thankful to the many early adopters of iodine using the WebSocket and Pub/Sub API.
-
-Please note that Iodine 0.5.0's API is a temporary API that was part of an attempt to come up with a de facto Rack standard for WebSocket / SSE connectivity.
-
-Sadly, this standard isn't progressing as well as I had hoped. More API changes were requested and it seems that the PR with the finalized API is still being considered ([please vote for the PR!](https://github.com/rack/rack/pull/1272)).
-
-I'm working on Iodine 0.6.0 with the requested updates to the API, along with an updated Pub/Sub API that should fit better with existing pub/sub approaches such ActionCable.
-
-It's my sincere hope that the upcoming API changes in 0.6.0 will be the last and that this will signal the API's maturity as well as general acceptance.
-
----
-
-## Iodine::Rack == fast & powerful HTTP + Websockets server with native Pub/Sub
+## Iodine - a fast & powerful HTTP + Websockets server with native Pub/Sub
 
 Iodine includes a light and fast HTTP and Websocket server written in C that was written according to the [Rack interface specifications](http://www.rubydoc.info/github/rack/rack/master/file/SPEC) and the [Websocket draft extension](./SPEC-Websocket-Draft.md).
 
-With `Iodine.listen2http` it's possible to run multiple HTTP applications in addition to (or instead of) the default `Iodine::Rack` HTTP service.
+With `Iodine.listen2http` it's possible to run multiple HTTP applications (please remember not to set more than a single application on a single TCP/IP port). 
 
 Iodine also supports native process cluster Pub/Sub and a native RedisEngine to easily scale iodine's Pub/Sub horizontally.
 
@@ -56,7 +40,7 @@ Iodine also supports native process cluster Pub/Sub and a native RedisEngine to
 Using the iodine server is easy, simply add iodine as a gem to your Rack application:
 
 ```ruby
-gem 'iodine', '~>0.4'
+gem 'iodine', '~>0.6'
 ```
 
 Iodine will calculate, when possible, a good enough default concurrency model for lightweight applications... this might not fit your application if you use heavier database access or other blocking calls.
@@ -90,11 +74,10 @@ Or by adding a single line to the application. i.e. (a `config.ru` example):
 ```ruby
 require 'iodine'
 # static file service
-Iodine::Rack.public = '/my/public/folder'
-# application
-out = [404, {"Content-Length" => "10"}, ["Not Found."]].freeze
-app = Proc.new { out }
-run app
+Iodine.listen2http public: '/my/public/folder'
+# for static file service, we only need a single thread per worker.
+Iodine.threads = 1
+Iodine.start
 ```
 
 To enable logging from the command line, use the `-v` (verbose) option:
@@ -117,7 +100,7 @@ i.e. (example `config.ru` for iodine):
 app = proc do |env|
   request = Rack::Request.new(env)
   if request.path_info == '/source'.freeze
-    [200, { 'X-Sendfile' => File.expand_path(__FILE__) }, []]
+    [200, { 'X-Sendfile' => File.expand_path(__FILE__), 'Content-Type' => 'text/plain'}, []]
   elsif request.path_info == '/file'.freeze
     [200, { 'X-Header' => 'This was a Rack::Sendfile response sent as text.' }, File.open(__FILE__)]
   else
@@ -175,25 +158,26 @@ Here is a simple chat-room example we can run in the terminal (`irb`) or easily
 
 ```ruby
 require 'iodine'
-class WebsocketChat
-  def on_open
+module WebsocketChat
+  def on_open client
     # Pub/Sub directly to the client (or use a block to process the messages)
-    subscribe :chat
+    client.subscribe :chat
     # Writing directly to the socket
-    write "You're now in the chatroom."
+    client.write "You're now in the chatroom."
   end
-  def on_message data
+  def on_message client, data
     # Strings and symbol channel names are equivalent.
-    publish "chat", data
+    client.publish "chat", data
   end
+  extend self
 end
-Iodine::Rack.app= Proc.new do |env|
+APP = Proc.new do |env|
   if env['rack.upgrade?'.freeze] == :websocket 
-    env['rack.upgrade'.freeze] = WebsocketChat # or: WebsocketChat.new
+    env['rack.upgrade'.freeze] = WebsocketChat 
     [0,{}, []] # It's possible to set cookies for the response.
   elsif env['rack.upgrade?'.freeze] == :sse
     puts "SSE connections can only receive data from the server, the can't write." 
-    env['rack.upgrade'.freeze] = WebsocketChat # or: WebsocketChat.new
+    env['rack.upgrade'.freeze] = WebsocketChat
     [0,{}, []] # It's possible to set cookies for the response.
   else
     [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Welcome Home"] ]
@@ -203,11 +187,12 @@ end
 root_pid = Process.pid
 Iodine.subscribe(:chat) {|ch, msg| puts msg if Process.pid == root_pid }
 # By default, Pub/Sub performs in process cluster mode.
-Iodine.processes = 4
-# static file serving can be set manually as well as using the command line:
-Iodine::Rack.public = "www/public"
-#
+Iodine.workers = 4
+# # in irb:
+Iodine.listen2http public: "www/public", app: APP
 Iodine.start
+# # or in config.ru
+run APP
 ```
 
 #### Native Pub/Sub with *optional* Redis scaling
@@ -217,24 +202,21 @@ Iodine's core, `facil.io` offers a native Pub/Sub implementation. The implementa
 Here's an example that adds horizontal scaling to the chat application in the previous example, so that Pub/Sub messages are published across many machines at once:
 
 ```ruby
-require 'uri'
 # initialize the Redis engine for each iodine process.
 if ENV["REDIS_URL"]
-  uri = URI(ENV["REDIS_URL"])
-  Iodine.default_pubsub = Iodine::PubSub::RedisEngine.new(uri.host, uri.port, 0, uri.password)
+  Iodine::PubSub.default = Iodine::PubSub::Redis.new(ENV["REDIS_URL"])
 else
   puts "* No Redis, it's okay, pub/sub will still run on the whole process cluster."
 end
-
-# ... the rest of the application remain unchanged.
+# ... the rest of the application remains unchanged.
 ```
 
 The new Redis client can also be used for asynchronous Redis command execution. i.e.:
 
 ```ruby
-if(Iodine.default_pubsub.is_a? Iodine::PubSub::RedisEngine)
+if(Iodine.default.is_a? Iodine::PubSub::Redis)
   # Ask Redis about all it's client connections and print out the reply.
-  Iodine.default_pubsub.send("CLIENT LIST") { |reply| puts reply }
+  Iodine.default.cmd("CLIENT LIST") { |reply| puts reply }
 end
 ```
 
@@ -246,55 +228,62 @@ end
 
 #### TCP/IP (raw) sockets
 
-Upgrading to a custom protocol (i.e., in order to implement your own Websocket protocol with special extensions) is performed almost the same way, using `env['upgrade.tcp']`. In the following (terminal) example, we'll use an echo server without direct socket echo:
+Upgrading to a custom protocol (i.e., in order to implement your own Websocket protocol with special extensions) is available when neither WebSockets nor SSE connection upgrades were requested. In the following (terminal) example, we'll use an echo server without direct socket echo:
 
 ```ruby
 require 'iodine'
 class MyProtocol
-  def on_message data
-    # regular socket echo - NOT websockets - notice the upgrade code
-    write data
+  def on_message client, data
+    # regular socket echo - NOT websockets
+    client.write data
   end
 end
-Iodine::Rack.app = Proc.new do |env|
-  if env['upgrade.tcp?'.freeze] && env["HTTP_UPGRADE".freeze] =~ /echo/i.freeze
-    env['upgrade.tcp'.freeze] = MyProtocol
-    # no HTTP response will be sent when the status code is 0 (or less).
-    # to upgrade AFTER a response, set a valid response status code.
-    [1000,{}, []]
+APP = Proc.new do |env|
+  if env["HTTP_UPGRADE".freeze] =~ /echo/i.freeze
+    env['upgrade.tcp'.freeze] = MyProtocol.new
+    # an HTTP response will be sent before changing protocols.
+    [101, { "Upgrade" => "echo" }, []]
   else
     [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Welcome Home"] ]
   end
 end
+# # in irb:
+Iodine.listen2http public: "www/public", app: APP
+Iodine.threads = 1
 Iodine.start
+# # or in config.ru
+run APP
 ```
 
 #### A few notes
 
 This design has a number of benefits, some of them related to better IO handling, resource optimization (no need for two IO polling systems), etc. This also allows us to use middleware without interfering with connection upgrades and provides backwards compatibility.
 
-Iodine::Rack imposes a few restrictions for performance and security reasons, such as limitimg each header line to 4Kb. These restrictions shouldn't be an issue and are similar to limitations imposed by Apache or Nginx.
+Iodine's HTTP server imposes a few restrictions for performance and security reasons, such as limiting each header line to 8Kb. These restrictions shouldn't be an issue and are similar to limitations imposed by Apache or Nginx.
 
-Of course, if you still want to use Rack's `hijack` API, iodine will support you - but be aware that you will need to implement your own reactor and thread pool for any sockets you hijack, as well as a socket buffer for non-blocking `write` operations (why do that when you can write a protocol object and have the main reactor manage the socket?).
+If you still want to use Rack's `hijack` API, iodine will support you - but be aware that you will need to implement your own reactor and thread pool for any sockets you hijack, as well as a socket buffer for non-blocking `write` operations (why do that when you can write a protocol object and have the main reactor manage the socket?).
 
 ### How does it compare to other servers?
 
-Personally, after looking around, the only comparable servers are Puma and Passenger (both offer multi-threaded and multi-process concurrency), which iodine significantly outperformed on my tests (I didn't test Passenger's enterprise version). Another upcoming server is the Agoo server (which has a very high performance).
+The honest answer is "I don't know". I recommend that you perform your own tests.
 
-When benchmarking with `wrk`, on the same local machine with similar settings (4 workers, 16 threads each, 200 concurrent connections), iodine performed better than Puma (I don't have Passenger enterprise, so I couldn't compare against it). 
+In my tests, pitching Iodine against Puma, Iodine was anywhere between x1.5 and x7 faster than Puma (depending on use-case). such a big difference is suspect and I recommend that you test it yourself.
 
-* Iodine performed at 69,885.30 req/sec, consuming ~77.8Mb of memory.
+Also, performing benchmarks on a single machine isn't very reliable... but it's all I've got.
 
-* Puma performed at 48,994.59 req/sec, consuming ~79.6Mb of memory.
+When benchmarking with `wrk`, on the same local machine with similar settings for both Puma and Iodine (4 workers, 16 threads each, 200 concurrent connections), I calculated Iodine to be x1.52 faster::
 
+* Iodine performed at 74,786.27 req/sec, consuming ~68.4Mb of memory.
 
-When benchmarking with `wrk` and using striped down settings (single worker, single thread, 200 concurrent connections), iodine was faster than Puma.
+* Puma performed at 48,994.59 req/sec, consuming ~79.6Mb of memory.
+
+When benchmarking using a VM (crossing machine boundaries, 16 threads, 4 workers, 200 concurrent connections), I calculated Iodine to be x2.3 faster:
 
-* Iodine performed at 56,648.86 req/sec, consuming ~27.4Mb of memory.
+* Iodine performed at 23,559.56 req/sec, consuming ~88.8Mb of memory.
 
-* Puma performed at 16,547.31 req/sec, consuming ~23.4Mb of memory.
+* Puma performed at 9,935.31 req/sec, consuming ~84.0Mb of memory.
 
-When benchmarking using a VM (crossing machine boundaries, single thread, single worker, 200 concurrent connections), iodine significantly outperformed Puma.
+When benchmarking using a VM (crossing machine boundaries, single thread, single worker, 200 concurrent connections), I calculated Iodine to be x7.3 faster:
 
 * Iodine performed at 18,444.31 req/sec, consuming ~25.6Mb of memory.
 
@@ -331,6 +320,8 @@ $ RACK_ENV=production puma -p 3000 -t 16 -w 4
 # Review the `iodine -?` help for more command line options.
 ```
 
+It's recommended that the servers (Iodine/Puma) and the client (`wrk`/`ab`) run on separate machines.
+
 ### Performance oriented design - but safety first
 
 Iodine is an evened server, similar in it's architecture to `nginx` and `puma`. It's different than the simple "thread-per-client" design that is often taught when we begin to learn about network programming.
@@ -424,11 +415,11 @@ Iodine.start
 
 ## Why not EventMachine?
 
-You can go ahead and use EventMachine if you like. They're doing amazing work on that one and it's been used a lot in Ruby-land... really, tons of good developers and people on that project, I'm sure...
+You can go ahead and use EventMachine if you like. They're doing amazing work on that one and it's been used a lot in Ruby-land... really, tons of good developers and people on that project.
 
-But me, I prefer to make sure my development software runs the exact same code as my production software. So here we are.
+EventMachine also offers some really great optimization features and it was vastly improved upon in the last few years (When I started Iodine, it was far more annoying to work with).
 
-Also, I don't really understand all the minute details of EventMachine's API, it kept crashing my system every time I reached 1K-2K active connections... I'm sure I just don't know how to use EventMachine, but that's just that.
+But there's a distinct approach difference for me. EventMachine attempts to give the developer access to the network layer while Iodine attempts to abstract the network layer away.
 
 Besides, you're here - why not take iodine out for a spin and see for yourself?
 
@@ -438,42 +429,14 @@ Yes, please, here are some thoughts:
 
 * I'm really not good at writing automated tests and benchmarks, any help would be appreciated. I keep testing manually and that's less then ideal (and it's mistake prone).
 
-* If we can write a Java wrapper for [the `facil.io` C framework](https://github.com/boazsegev/facil.io), it would be nice... but it could be as big a project as the whole gem, as a lot of minor details are implemented within the bridge between these two languages.
-
 * PRs or issues related to [the `facil.io` C framework](https://github.com/boazsegev/facil.io) should be placed in [the `facil.io` repository](https://github.com/boazsegev/facil.io).
 
 * Bug reports and pull requests are welcome on GitHub at https://github.com/boazsegev/iodine.
 
+* If we can write a Java wrapper for [the `facil.io` C framework](https://github.com/boazsegev/facil.io), it would be nice... but it could be as big a project as the whole gem, as a lot of minor details are implemented within the bridge between these two languages.
+
 * If you love the project or thought the code was nice, maybe helped you in your own project, drop me a line. I'd love to know.
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-
----
-
-## "I'm also writing a Ruby extension in C"
-
-Really?! That's great!
-
-We could all use some more documentation around the subject and having an eco-system for extension tidbits would be nice.
-
-Here's a few things you can use from this project and they seem to be handy to have (and easy to port):
-
-* Iodine is using a [Registry](https://github.com/boazsegev/iodine/blob/0.2.0/ext/core/rb-registry.h) to keep dynamic Ruby objects that are owned by C-land from being collected by the garbage collector in Ruby-land...
-
-    Some people use global Ruby arrays, adding and removing Ruby objects to the array, but that sounds like a performance hog to me.
-
-    This one is a simple binary tree with a Ruby GC callback. Remember to initialize the Registry (`Registry.init(owner)`) so it's "owned" by some Ruby-land object, this allows it to bridge the two worlds for the GC's mark and sweep.
-
-    I'm attaching it to one of iodine's library classes, just in-case someone adopts my code and decides the registry should be owned by the global Object class.
-
-* I was using a POSIX thread pool library ([`defer.h`](https://github.com/boazsegev/facil.io/blob/master/lib/facil/core/defer.c)) until I realized how many issues Ruby has with non-Ruby threads... So now there's a Ruby-thread patch for this library at ([`rb-defer.c`](https://github.com/boazsegev/iodine/blob/master/ext/iodine/rb-defer.c)).
-
-    Notice that all the new threads are free from the GVL - this allows true concurrency... but, you can't make Ruby API calls in that state.
-
-    To perform Ruby API calls you need to re-enter the global lock (GVL), albeit temporarily, using `rb_thread_call_with_gvl` and `rv_protect` (gotta watch out from Ruby `longjmp` exceptions).
-
-* Since I needed to call Ruby methods while multi-threading and running outside the GVL, I wrote [`RubyCaller`](https://github.com/boazsegev/iodine/blob/0.2.0/ext/core/rb-call.h) which let's me call an object's method and wraps all the `rb_thread_call_with_gvl` and `rb_protect` details in a secret hidden place I never have to see again. It also keeps track of the thread's state, so if we're already within the GVL, we won't enter it "twice" (which could crash Ruby sporadically).
-
-These are nice code snippets that can be easily used in other extensions. They're easy enough to write, I guess, but I already did the legwork, so enjoy.

data/bin/raw-rbhttp

@@ -14,20 +14,25 @@ $LOAD_PATH.unshift File.expand_path(File.join('..', '..', 'lib'), __FILE__)
 require 'bundler/setup'
 require 'iodine'
 
-class HttpProtocol
-  @timeout = 10
+module HttpProtocol
+	def self.on_open client
+		client.timeout = 10
+	end
   # `on_message` is an optional alternative to the `on_data` callback.
   # `on_message` has a 1Kb buffer that recycles itself for memory optimization.
-  def on_message _
+  def self.on_message client, _
     # writing will never block and will use a buffer written in C when needed.
-    write "HTTP/1.1 200 OK\r\nConnection: keep-alive\r\nKeep-Alive: timeout=1\r\nContent-Length: 12\r\n\r\nHello World!"
+    client.write "HTTP/1.1 200 OK\r\nConnection: keep-alive\r\nKeep-Alive: timeout=1\r\nContent-Length: 12\r\n\r\nHello World!"
+  end
+  def self.call
+  	self
   end
 end
 
 puts "thread #{Iodine.threads}"
 # Listen
-Iodine.listen '3000', HttpProtocol
-Iodine.threads = 8
-Iodine.processes = 1
+Iodine.listen port: '3000', handler: HttpProtocol
+Iodine.threads = 4
+Iodine.workers = 1
 puts "now, thread #{Iodine.threads}"
 Iodine.start

data/examples/config.ru

@@ -36,19 +36,20 @@ module MyHTTPRouter
 end
 
 # A simple Websocket Callback Object.
-class BroadcastClient
+module BroadcastClient
   # seng a message to new clients.
-  def on_open
-    subscribe :broadcast
+  def on_open client
+    client.subscribe :broadcast
   end
   # send a message, letting the client know the server is suggunt down.
-  def on_shutdown
-    write "Server shutting down. Goodbye."
+  def on_shutdown client
+    client.write "Server shutting down. Goodbye."
   end
   # perform the echo
-  def on_message data
-    publish :broadcast, data
+  def on_message client, data
+    client.publish :broadcast, data
   end
+  extend self
 end
 
 # this function call links our HelloWorld application with Rack

data/examples/echo.ru

@@ -39,19 +39,20 @@ module MyHTTPRouter
 end
 
 # A simple Websocket Callback Object.
-class WebsocketEcho
+module WebsocketEcho
   # seng a message to new clients.
-  def on_open
-    write "Welcome to our echo service!"
+  def on_open client
+    client.write "Welcome to our echo service!"
   end
   # send a message, letting the client know the server is suggunt down.
-  def on_shutdown
-    write "Server shutting down. Goodbye."
+  def on_shutdown client
+    client.write "Server shutting down. Goodbye."
   end
   # perform the echo
-  def on_message data
-    write data
+  def on_message client, data
+    client.write data
   end
+  extend self
 end
 
 # this function call links our HelloWorld application with Rack

data/examples/info.md

@@ -82,7 +82,7 @@ By using a callback object, the application is notified of any events. Leaving t
 
 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.
+~~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
 
@@ -108,7 +108,7 @@ 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).
+To set a callback object, the `env['rack.upgrade']` is introduced (notice the *missing* question mark).
 
 Now the design might look like this:
 
@@ -116,15 +116,16 @@ Now the design might look like this:
 # Place in config.ru
 RESPONSE = [200, { 'Content-Type' => 'text/html',
           'Content-Length' => '12' }, [ 'Hello World!' ] ]
-# a Callback class
+# an example Callback class
 class MyCallbacks
-  def on_open
+  def on_open client
     puts "* Push connection opened."
   end
-  def on_message data
+  def on_message client, data
     puts "* Incoming data: #{data}"
+    client.write "Roger that, \"#{data}\""
   end
-  def on_close
+  def on_close client
     puts "* Push connection closed."
   end
 end
@@ -146,7 +147,7 @@ Run this application with the Agoo or Iodine servers and let the magic sparkle.
 For example, using Iodine:
 
 ```bash
-# install iodine
+# install iodine, version 0.6.0 and up
 gem install iodine
 # start in single threaded mode
 iodine -t 1
@@ -185,7 +186,7 @@ And this same example will run perfectly using the Agoo server as well (both Ago
 Try it:
 
 ```bash
-# install the agoo server 
+# install the agoo server, version 2.1.0 and up
 gem install agoo
 # start it up
 rackup -s agoo -p 3000
@@ -204,14 +205,14 @@ Consider implementing a stock ticker, or in this case, a timer:
 RESPONSE = [200, { 'Content-Type' => 'text/html',
           'Content-Length' => '12' }, [ 'Hello World!' ] ]
 
-# A live connection storage
+# A global live connection storage
 module LiveList
   @list = []
   @lock = Mutex.new
-  def self.<<(connection)
+  def <<(connection)
     @lock.synchronize { @list << connection }
   end
-  def self.>>(connection)
+  def >>(connection)
     @lock.synchronize { @list.delete connection }
   end
   def any?
@@ -220,17 +221,16 @@ module LiveList
   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 self.broadcast(data)
+  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
-      @list.each do |c|
-        begin
-          c.write data
-        rescue IOError => _e
-          # An IOError can occur if the connection was closed during the loop.
-        end
-      end
+      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...
@@ -242,26 +242,27 @@ end
   end
 end
 
-# a Callback class
-class MyCallbacks
-  def on_open
+# an example static Callback module
+module MyCallbacks
+  def on_open client
     # add connection to the "live list"
-    LiveList << self
+    LiveList << client
   end
-  def on_message(data)
+  def on_message(client, data)
     # Just an example broadcast
     LiveList.broadcast "Special Announcement: #{data}"
   end
-  def on_close
+  def on_close client
     # remove connection to the "live list"
-    LiveList >> self
+    LiveList >> client
   end
+  extend self
 end
 
 # The Rack application
 APP = Proc.new do |env|
   if(env['rack.upgrade?'])
-    env['rack.upgrade'] = MyCallbacks.new
+    env['rack.upgrade'] = MyCallbacks
     [200, {}, []]
   else
     RESPONSE
@@ -277,7 +278,7 @@ Honestly, I don't love the code I just wrote for the previous example. It's a li
 
 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 need a timer, so I'll skip the [`Iodine.run_every` method](https://www.rubydoc.info/github/boazsegev/iodine/master/Iodine#run_every-class_method)).
+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.
 
@@ -289,21 +290,22 @@ Sadly, this means that the example won't run on Agoo for now.
 # 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
-    subscribe :chat
-    publish :chat, "#{@name} joined the chat."
+  def on_open client
+    client.subscribe CHAT
+    client.publish CHAT, "#{@name} joined the chat."
   end
-  def on_message data
-    publish :chat, "#{@name}: #{data}"
+  def on_message client, data
+    client.publish CHAT, "#{@name}: #{data}"
   end
-  def on_close
-    publish :chat, "#{@name} left the chat."
+  def on_close client
+    client.publish CHAT, "#{@name} left the chat."
   end
 end
 # The actual Rack application
@@ -334,6 +336,8 @@ 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.
@@ -345,3 +349,5 @@ Another proposal was attempted [a few years ago](https://github.com/rack/rack/is
 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.