iodine 0.4.19 → 0.5.0

data/SPEC-Websocket-Draft.md

@@ -1,223 +1,207 @@
-### Draft Inactivity Notice
+### Draft State
 
-This proposed draft is only implemented by Iodine and hadn't seen external activity in a while.
-
-Even though a number of other development teams (such as the teams for the Puma and Passenger server) mentioned that they plan to implements this draft, Iodine seems to be the only server currently implementing this draft and it is unlikely that this initiative will grow to become a community convention.
-
-I still believe it's important to separate the Websocket server from the Websocket API used by application developers and frameworks, much like Rack did for HTTP. I hope that in the future a community convention for this separation of concerns can be achieved.
+I am currently discussing a variation of this draft to be implemented by [the Agoo server](https://github.com/ohler55/agoo).
 
 ---
-## Rack Websockets
-
-This is the proposed Websocket support extension for Rack servers.
-
-Servers that publish Websocket support using the `env['upgrade.websocket?']` value are assume by users to follow the requirements set in this document and thus should follow the requirements set in herein.
-
-This document reserves the Rack `env` Hash keys of `upgrade.websocket?` and `upgrade.websocket`.
-
-## The Websocket Callback Object
-
-Websocket connection upgrade and handling is performed using a Websocket Callback Object.
-
-The Websocket Callback Object should be a class (or an instance of such class) who's instances implement any of the following callbacks:
+## Purpose
 
-* `on_open()` WILL be called once the upgrade had completed.
+This document details WebSocket / EventSource connection support for Rack servers.
 
-* `on_message(data)` (REQUIRED) WILL be called when incoming Websocket data is received. `data` will 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 purpose of these specifications is:
 
-    The *client* **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 and it is *not* required.
-
-* `on_ready()` **MAY** be called when the state of the out-going socket buffer changes from full to not full (data can be sent to the socket). **If** `has_pending?` returns `true`, the `on_ready` callback **MUST** be called once the buffer state changes.
-
-* `on_shutdown()` 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.
+1. To allow separation of concerns between the transport layer and the application, thereby allowing the application to be server agnostic.
 
-* `on_close()` WILL be called _after_ the connection was closed for whatever reason (socket errors, parsing errors, timeouts, client disconnection, `close` being called, etc').
+    Simply put, when choosing between conforming servers, the application doesn’t need to have any knowledge about the chosen server.
 
-* `on_open`, `on_ready`, `on_shutdown` and `on_close` shouldn't expect any arguments (`arity == 0`).
+2. To Support “native" (server-side) WebSocket and EventSource (SSE) connections and using application side callbacks.
 
-The following method names are reserved for the network implementation: `write`, `close` and `has_pending?`.
+    Simply put, to make it easy for applications to accept WebSocket and EventSource (SSE) connections from WebSocket and EventSource clients (commonly browsers).
 
-The server **MUST** extend the Websocket Callback Object's *class* using `extend`, so that the Websocket Callback Object inherits the following methods:
+3. Allow applications to use WebSocket and EventSource (SSE) on HTTP/2 servers. Note: current `hijack` practices will break network connections when attempting to implement EventSource (SSE).
 
-* `write(data)` will attempt to send the data through the websocket connection. `data` **MUST** be a String. 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).
+## Rack WebSockets / EventSource
 
-    `write` has the same delivery promise as `Socket#write` (a successful `write` does **not** mean any of the data will reach the other side).
-
-    `write` shall return `true` on success and `false` if the websocket is closed.
+Servers that publish WebSocket and/or EventSource (SSE) support using the `env['rack.upgrade?']` value MUST follow the requirements set in this document.
 
-    A server **SHOULD** document whether `write` will block or return immediately. It is **RECOMMENDED** that servers implement buffered IO, allowing `write` to return immediately when resources allow and block (or, possibly, disconnect) when the IO buffer is full.
+This document reserves the Rack `env` Hash keys of `rack.upgrade?` and `rack.upgrade`.
 
-* `close` closes the connection once all the data in the outgoing queue was sent. If `close` is called while there is still data to be sent, `close` will only take effect once the data was sent.
+The historical use of `upgrade.websocket?` and `upgrade.websocket` (iodine 0.4.x) will be gradually deprecated.
 
-    `close` shall always return `nil`.
+### The WebSocket / EventSource Callback Object
 
-* `has_pending?` queries the state of the server's buffer for the specific connection (i.e., if the server has any data it is waiting to send through the socket).
+WebSocket and EventSource connection upgrade and handling is performed using a Callback Object.
 
-    `has_pending?`, shall return `true` **if** the server has data waiting to be written to the socket **and** the server promises to call the `on_ready` callback once the buffer is empty and the socket is writable. Otherwise (i.e., if the server doesn't support the `on_ready` callback), `has_pending?` shall return `false`.
+The Callback Object should be a class (or an instance of such class) where **instances** implement any of the following callbacks:
 
-    To clarify: **implementing `has_pending?` is semi-optional**, meaning that a server may choose to always return `false`, no matter the actual state of the socket's buffer.
+* `on_open()` WILL be called once the connection had been established.
 
-The following keywords (both as method names and instance variable names) are reserved for the internal server implementation: `_server_ws` and `conn_id`.
+* `on_message(data)` WILL be called when incoming WebSocket data is received.
 
-* The `_server_ws` object is private and shouldn't be accessed by the client.
+    This callback is ignored for EventSource connections.
 
-* The `conn_id` object may be used as a connection ID for any functionality not specified herein.
+    `data` will 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).
 
-Connection `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 detect network failure.
+    The *client* **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.
 
-Server settings **MAY** (not required) 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.
+    Servers **MAY**, optionally, implement a **recyclable buffer** for the `on_message` callback. However, this is optional and it is *not* required.
 
-The requirement that the server extends the class of the Websocket Callback Object (instead of the client application doing so explicitly) is designed to allow the client application to be more server agnostic.
+* `on_drained()` **MAY** be called when the the `write` buffer becomes empty. **If** `pending` returns a non-zero value, the `on_drained` callback **MUST** be called once the write buffer becomes empty.
 
-## Upgrading
+* `on_shutdown()` **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.
 
-* **Server**: When an upgrade request is received, the server will set the `env['upgrade.websocket?']` flag to `true`, indicating that: 1. this specific request is upgradable; and 2. this server supports this specification.
+* `on_close()` **MUST** be called _after_ the connection was closed for whatever reason (socket errors, parsing errors, timeouts, client disconnection, `close` being called, etc').
 
-* **Client**: When a client decides to upgrade a request, they will place a Websocket Callback Object (either a class or an instance) in the `env['upgrade.websocket']` Hash key.
+* `on_open`, `on_drained`, `on_shutdown` and `on_close` shouldn't expect any arguments (`arity == 0`).
 
-* **Server**: The server will review the `env` Hash *before* sending the response. If the `env['upgrade.websocket']` was set, the server will perform the upgrade.
+The following method names are reserved for the network implementation: `write`, `close`, `open?` and `pending`.
 
- * **Server**: 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 exists.
+The server **MUST** extend the Callback Object's *class* using `extend`, so the Callback Object **inherits** the following methods (this approach promises applications could be server agnostic\*):
 
-     The response status provided by the response object shall be ignored and the correct response status shall be set by the server.
+* `write(data)` will attempt to send the data through the connection. `data` **MUST** be a String.
 
-* **Server**: Once the upgrade had completed, The server will add the required websocket/network functions to the callback handler or it's class (as aforementioned). If the callback handler is a Class object, the server will create a new instance of that class.
+    `write` has the same delivery promise as `Socket#write` (a successful `write` does **not** mean any of the data will reach the other side).
 
-* **Server**: The server will call the `on_open` callback.
+    `write` shall return `true` on success and `false` if the connection is closed.
 
-    No other callbacks shall be called until the `on_open` callback had returned.
+    For WebSocket connections only (irrelevant for EventSource connections):
 
-    Websocket messages shall be handled by the `on_message` callback in the same order in which they arrive and the `on_message` will **not** be executed concurrently for the same connection.
+    * If `data` is UTF-8 encoded, the data will be sent as text.
 
-    The `on_close` callback will **not** be called while `on_message` or `on_open` callbacks are running.
+    * If `data` is binary encoded it will be sent as non-text (as specified by the WebSocket Protocol).
 
-    The `on_ready` callback might be called concurrently with the `on_message` callback, allowing data to be sent even while other data is being processed. Multi-threading considerations may apply.
+    A server **SHOULD** document whether `write` will block or return immediately. It is **RECOMMENDED** that servers implement buffered IO, allowing `write` to return immediately when resources allow and block (or, possibly, disconnect) when the IO buffer is full.
 
----
+* `close` closes the connection once all the data in the outgoing queue was sent. If `close` is called while there is still data to be sent, `close` will only take effect once the data was sent.
 
-## Iodine's Collection Extension to the Rack Websockets
+    `close` shall always return `nil`.
 
-The biggest benefit from Iodine's Collection Extension is that it allows the creation of pub/sub plugins and other similar extensions that require access to all the connected Websockets - no need for the plugin to ask "where's the list" or "add this code to `on_open`" or anything at all, truly "plug and play".
+* `open?` returns the state of the connection. Servers **MUST** set the method to return `true` if the connection is open and `false` if the connection is closed or marked to be closed.
 
-This extension should be easy enough to implement using a loop or an array within each process context. These methods do **not** cross process boundaries and they are meant to help implement more advanced features (they aren't a feature as much as an "access point").
+* `pending` **MUST** return -1 if the connection is closed or the number of pending writes (calls to `write`) that need to be processed before the next time the `on_drained` callback is called\*.
 
-Internally, this extension also allows iodine to manage connection memory and resource allocation while relieving developers from rewriting the same workflow of connection storing (`on_open do ALL_WS << self; end `) and management. Knowing that the user doesn't keep Websocket object references, allows Iodine to safely optimize it's memory use.
+    Servers **MAY** choose to always return the value `0` if they never call the `on_drained` callback and the connection is open.
 
-* `Iodine::Websocket.each` (class method) will run a block of code for each connected Websocket Callback Object **belonging to the current process**. This can be called from outside of a Websocket Callback Object as well.
+    Servers that return a positive number MUST call the `on_drained` callback when a call to `pending` would return the value `0`.
 
-    ```ruby
-    Iodine::Websocket.each {|ws| ws.write "You're connected to PID #{Process.pid}" }
-    ```
+    \*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.
 
-* `Iodine::Websocket.defer(conn_id)` Schedules a block of code to run for the specified connection at a later time, (*if* the connection is open) while preventing concurrent code from running for the same connection object.
+The following keyword(s) (both as method names and instance variable names) is reserved for the internal server implementations: `_sock`, `_cid`.
 
-    ```ruby
-    Iodine::Websocket.defer(self.conn_id) {|ws| ws.write "still open" }
-    ```
+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 detect network failure.
 
-* `#defer` (instance method) Schedules a block of code to run for the specified connection at a later time, (*if* the connection is still open) while preventing concurrent code from running for the same connection object.
+Server settings **MAY** (not required) 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.
 
-    ```ruby
-    defer { write "still open" }
-    ```
+\* The requirement that the server extends the class of the Callback Object (instead of the client application doing so explicitly) is designed to allow the client application to be server agnostic
 
-* `Iodine::Websocket.count` (instance method) Returns the number of active websocket connections (including connections that are in the process of closing down) **belonging to the current process**.
+To clarify, an implicit `extend` doesn't require a namespace, while an explicit `extend` does. By avoiding the requirement to explicitly extend the callback object, the application can be namespace agnostic.
 
-    ```ruby
-    write "#{Iodine::Websocket.count} clients sharing this process"
-    ```
+---
 
-## Iodine's Pub/Sub Extension to the Rack Websockets
+## Implementation Examples
 
-This extension separates the websocket Pub/Sub semantics from the Pub/Sub engine (i.e. Redis, MongoDB, etc'). This allows the Pub/Sub pattern to integrate with the Websocket API without the need for servers or applications to implement the Pub/Sub features.
+### Server-Client Upgrade to WebSockets / EventSource
 
-This allows Pub/Sub "engines" to seamlessly integrate with a server and offer Pub/Sub functionality for the specified environment, without the need for applications or servers to know anything about the Pub/Sub details or the environment.
+* **Server**:
 
-For example, Iodine includes three Pub/Sub engines `Iodine::PubSub::CLUSTER` (the default, for single machine multi-process pub/sub), `Iodine::PubSub::SINGLE_PROCESS` (a single process pub/sub) and `Iodine::PubSub::RedisEngine` (for horizontal scaling across machine boundaries, using Redis pub/sub)...
+    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.
 
-...but it would be easy enough to write a gem that will add another engine for MongoDB Pub/Sub and that engine would be server agnostic.
+    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.
 
-If the Collection Extension is implemented, than this extension should be relatively easy to implement by the server.
+* **Client**:
 
-I don't personally believe this has a chance of being adopted by other server implementors, but it's a very powerful tool that Iodine supports.
+    When a client decides to upgrade a request, they will place an appropriate Callback Object (either a class or an instance) in the `env['rack.upgrade']` Hash key.
 
-The Websocket module (i.e. `Iodine::Websocket`) includes the following singleton methods:
+* **Server**:
 
- * `Iodine::Websocket.default_pubsub=` sets the default Pub/Sub engine.
+    1. The server will review the `env` Hash *before* sending the response. If the `env['rack.upgrade']` was set, the server will perform the upgrade.
 
- * `Iodine::Websocket.default_pubsub` gets the default Pub/Sub engine.
+        **If the callback handler is a Class object, the server will create a new instance of that class**.
 
-Websocket Callback Objects inherit the following functions:
+    2. 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.
 
- * `#subscribe` (instance method) Subscribes to a channel using a specific "engine" (or the default engine). *Returns a subscription object (success) or `nil` (error)*. Doesn't promise actual subscription, only that the subscription request was scheduled to be sent.
+         The response status provided by the response object shall be ignored and the correct response status shall be set by the server.
 
-    Messages from the subscription are sent directly to the client unless an optional block is provided.
+         If the application's response status indicates an error or a redirection (status code >= 300), the server shall ignore the Callback Object.
 
-    If an optional block is provided, it should accept the channel and message couplet (i.e. `{|channel, message| } `) and call the websocket `write` manually.
+    3. Once the upgrade had completed and the server extended the Callback Object, it will call the `on_open` callback.
 
-    All subscriptions (including server side subscriptions) MUST be automatically canceled **by the server** when the websocket closes.
+        No other callbacks shall be called until the `on_open` callback had returned.
 
- * `#subscription?` (instance method) locates an existing subscription, if any. *Returns a subscription object (success) or `nil` (error)*.
+        WebSocket messages shall be handled by the `on_message` callback in the same order in which they arrive and the `on_message` will **not** be executed concurrently for the same connection.
 
- * `#unsubscribe` (instance method) cancel / stop a subscription. Safely ignores `nil` subscription objects. Returns `nil`. Performance promise is similar to `subscribe` - the event was scheduled.
+        The `on_close` callback will **not** be called while any other callback is running (`on_open`, `on_message`, `on_drained`, etc').
 
-    Notice: there's no need to call this function during the `on_close` callback, since the server will cancel all subscriptions automatically.
+        The `on_drained` callback might be called concurrently with the `on_message` callback, allowing data to be sent even while other data is being processed. Multi-threading considerations may apply.
 
- * `#publish` (instance method) publishes a message to engine's specified channel. Returns `true` on success or `false` on failure (i.e., engine error). Doesn't promise actual publishing, only that the message was scheduled to be published.
+## Example Usage
 
-For example:
+The following is an example WebSocket echo server implemented using this specification:
 
 ```ruby
-# client side subscription
-s = subscribe(channel: "channel 1") # => subscription ID?
-# client side unsubscribe
-unsubscribe(s)
-
-# client side subscription forcing binary encoding for Websocket protocol.
-subscribe(channel: "channel 1", encoding: :binary) # => subscription ID?
-
-# client side pattern subscription without saving reference
-subscribe(pattern: "channel [0-9]") # => subscription ID?
-# client side unsubscribe
-unsubscribe( subscription?(pattern: "channel [0-9]"))
-
-# server side anonymous block subscription
-s = subscribe(channel: "channel ✨") do |channel, message|
-    puts message
+class WSConnection
+    def on_open
+        puts "WebSocket connection established."
+    end
+    def on_message(data)
+        write data
+        puts "on_drained MUST be implemented if #{ pending } != 0."
+    end
+    def on_drained
+        puts "Yap,on_drained is implemented."
+    end
+    def on_shutdown
+        write "The server is going away. Goodbye."
+    end
+    def on_close
+        puts "WebSocket connection closed."
+    end
 end
-# server side unsubscribe
-unsubscribe(s)
-
-# server side persistent block subscription without saving reference
-block = proc {|channel, message| puts message }
-subscribe({pattern: "*"}, &block)
-# server side unsubscribe
-unsubscribe subscription?({pattern: "*"}, &block)
-
-# server side anonymous block subscription requires reference...
-subscribe(pattern: "channel 5", force: text) do |channel, message|
-    puts message
-end
-# It's impossible to locate an anonymous block subscriptions!
-subscription? (pattern: "channel 5", force: text) do |channel, message|
-    puts message
+
+module App
+   def self.call(env)
+       if(env['rack.upgrade?'.freeze] == :websocket)
+           env['rack.upgrade'.freeze] = WSConnection.new
+           return [0, {}, []]
+       end
+       return [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Hello World!"]]
+   end
 end
-#  => nil # ! can't locate
 
+run App
 ```
 
-Servers supporting this extension aren't required to implement any Pub/Sub engines, but they MUST implement a **bridge** between the server and Pub/Sub Engines that follows the following semantics:
-
-Engines MUST inherit from a server specific Engine class and implement the following three methods that will be called by the server when required (servers might implement an internal distribution layer and call these functions at their discretion):
-
-* `subscribe(channel, is_pattern)`: Subscribes to the channel. The `is_pattern` flag sets the type of subscription. Returns `true` / `false`.
+The following is uses Push notifications for both WebSocket and SSE connections. The Pub/Sub API isn't part of this specification:
 
-* `unsubscribe(channel, is_pattern)`: Unsubscribes from the channel. The `is_pattern` flag sets the type of subscription. Returns `true` / `false`.
+```ruby
+class Chat
+    def initialize(nickname)
+        @nickname = nickname
+    end
+    def on_open
+        subscribe "chat"
+        publish "chat", "#{@nickname} joined the chat."
+    end
+    def on_message(data)
+        publish "chat", "#{@nickname}: #{data}"
+    end
+    def on_close
+        publish "chat", "#{@nickname}: left the chat."
+    end
+end
 
-* `publish(channel, msg, is_pattern)`: Publishes to the channel (or all channels matching the pattern). Returns `true` / `false` (some engines, such as Redis, might not support pattern publishing, they should simply return `false`).
+module App
+   def self.call(env)
+       if(env['rack.upgrade?'.freeze])
+           nickname = env['PATH_INFO'][1..-1]
+           nickname = "Someone" if nickname == "".freeze
+           env['rack.upgrade'.freeze] = Chat.new(nickname)
+           return [0, {}, []]
+       end
+       return [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Hello World!"]]
+   end
+end
 
-Engines inherit the following message from the server's Engine class and call it when messages were received:
+run App
+```
 
-* `distribute(channel, message, is_pattern = nil)`: If `channel` is a channel pattern rather than a channel name, the `is_pattern` should be set to `true` by the Engine. Engines that don't support pattern publishing, can simply ignore this flag.
+Note that SSE connections will only be able to receive messages (the `on_message` callback is never called).

data/bin/http-hello

@@ -19,7 +19,6 @@ Iodine::Rack.public = '~/Documents/Scratch'
 count = 2
 Iodine::Rack.app = proc { |_env| [200, { 'Content-Length'.freeze => '12'.freeze }, ['He11o World!'.freeze]] }
 puts Iodine::Rack.address
-Iodine::HTTP.listen app: Iodine::Rack.app, port: "3030", public: '~/Documents/Scratch'
 Iodine.start
 
 # puts env.to_a.map { |pair| pair.join(': ') } .join("\n").to_s;

data/bin/raw-rbhttp

@@ -18,7 +18,7 @@ class HttpProtocol
   @timeout = 10
   # `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_data
+  def on_message _
     # 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!"
   end

data/bin/raw_broadcast

@@ -42,20 +42,18 @@ class EchoProtocol
     puts "We have 1 timer, and #{Iodine.count} connections."
   end
 
+  def on_open
+    subscribe(channel: :chat) {|ch, msg|  write msg }
+    subscribe channel: :quite
+  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(buffer)
     # writing will never block and will use a buffer written in C when needed.
-    write buffer
-    puts buffer.dump
-    # close will be performed only once all the data in the write buffer
-    # was sent. use `force_close` to close early.
-    close if buffer =~ /^bye[\r\n]/i
-    upgrade ShoooProtocol if buffer =~ /^shoo[\r\n]/i
-    # use buffer.dup to save the data from being recycled once we return.
-    data = "Someone said: #{buffer}"
-    # run asynchronous tasks with ease
-    each { |c| puts c; c.write data }
+    publish channel: :chat, message: "Someone said: #{buffer}"
+    switch_protocol ShoooProtocol if buffer =~ /^shoo[\r\n]/i
+    write "You speak!\n" if unsubscribe(subscribed?(channel: :quite))
   end
 end
 

data/bin/updated api

@@ -35,8 +35,8 @@ class WSEcho
     puts "I'm shutting down #{self}"
   end
 
-  def on_ready
-    puts "on_ready called for #{self}"
+  def on_drained
+    puts "on_drained called for #{self}"
   end
 
   def on_message(data)

data/bin/ws-broadcast

@@ -25,6 +25,7 @@ class WSEcho
 
   def on_open
     puts 'We have a websocket connection'
+    subscribe channel: :all
   end
 
   def on_close
@@ -37,10 +38,7 @@ class WSEcho
 
   def on_message(data)
     puts "got message: #{data}"
-    write data
-    data_cp = "Broadcast: #{data}"
-    # puts "broadcasting #{data_cp.bytesize} bytes"
-    each { |h| h.write data_cp }
+    publish channe: :all, message: data
   end
 
   def self.pr_raise

data/bin/ws-echo

@@ -38,8 +38,8 @@ class WSEcho
     puts "I'm shutting down #{self}"
   end
 
-  def on_ready
-    puts "on_ready called for #{self}"
+  def on_drained
+    puts "on_drained called for #{self}"
   end
 
   def on_message(data)

data/examples/config.ru

@@ -1,12 +1,12 @@
-# This is a Websocket echo application.
+# This is a WebSocket / SSE notification broadcasting application.
 #
-# Running this application from the command line is eacy with:
+# Running this application from the command line is easy with:
 #
-#      iodine hello.ru
+#      iodine
 #
 # Or, in single thread and single process:
 #
-#      iodine -t 1 -w 1 hello.ru
+#      iodine -t 1 -w 1
 #
 # Benchmark with `ab` or `wrk` (a 5 seconds benchmark with 2000 concurrent clients):
 #
@@ -18,16 +18,16 @@
 module MyHTTPRouter
   # This is the HTTP response object according to the Rack specification.
   HTTP_RESPONSE = [200, { 'Content-Type' => 'text/html',
-          'Content-Length' => '32' },
-   ['Please connect using websockets.']]
+          'Content-Length' => '77' },
+   ['Please connect using WebSockets or SSE (send messages only using WebSockets).']]
 
-   WS_RESPONSE = [0, {}, []].freeze
+  WS_RESPONSE = [0, {}, []].freeze
 
    # this is function will be called by the Rack server (iodine) for every request.
    def self.call env
-     # check if this is an upgrade request.
-     if(env['upgrade.websocket?'.freeze])
-       env['upgrade.websocket'.freeze] = WebsocketEcho
+     # check if this is an upgrade request (WebsSocket / SSE).
+     if(env['rack.upgrade?'.freeze])
+       env['rack.upgrade'.freeze] = BroadcastClient
        return WS_RESPONSE
      end
      # simply return the RESPONSE object, no matter what request was received.
@@ -36,10 +36,10 @@ module MyHTTPRouter
 end
 
 # A simple Websocket Callback Object.
-class WebsocketEcho
+class BroadcastClient
   # seng a message to new clients.
   def on_open
-    write "Echo service initiated."
+    subscribe :broadcast
   end
   # send a message, letting the client know the server is suggunt down.
   def on_shutdown
@@ -47,7 +47,7 @@ class WebsocketEcho
   end
   # perform the echo
   def on_message data
-    write data
+    publish :broadcast, data
   end
 end