iodine 0.7.41 → 0.7.45

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 03af29c680fee3cd7b70b4a9fbc0f370b42a763f83f4422cc0f1cae296b95f1c
-  data.tar.gz: b6e25d8cc33dd955989ae6c8f6bf18d45f84dad42887eff22f39c68aada56f02
+  metadata.gz: 33f22236ecbf1c2166c056476bbefb6ab80b709cdb6cc16c0ec144926cf3fdc0
+  data.tar.gz: 6b0c70cc71431eb3611d34af45c80f679c0177141843a5e03b1cdb6b242d4f19
 SHA512:
-  metadata.gz: b4eab8d5f7309dd8845d4f6c8052935dbd8145201c4820786ae000e895277883765c1dd628c1e053816b50a1d7c002180f6b4e0a5833e60d76277dab8ecf81b1
-  data.tar.gz: f90eb620cf2a9aaf7c943fe981e829f698cb1e8fc176ad8ad778df2c36c5eb026314522d428bee8058915e95f9ed3750ed078931193b81b0dec062e27eb569c2
+  metadata.gz: 3506324c77f3de50b9dda515922c3468bbb49c63cd58831d2f7711e02b28209ba7fb5d15e076e860092be4d783cf595fd69b2483bf7ee59b873040005468161f
+  data.tar.gz: 7c4b0ffb76c749c11f18d66faaad5494e6ab7c675b0d887721de3c7494a7b764886bb8b7b4f5fc369e606e0f3b2e30172818dae27faa4c3cfffa73d094012cf9

data/.github/ISSUE_TEMPLATE/bug_report.md

@@ -21,7 +21,7 @@ A clear and concise description of what the bug is.
 ### Rack App to Reproduce
 
 ```ruby
-APP = {|env| [200, {}, "Hello World"] }
+APP = proc {|env| [200, {}, ["Hello World"]] }
 run APP
 ```
 

data/.gitignore

@@ -10,6 +10,7 @@
 /old_stuff/
 *.bundle
 *.so
+*.gem
 
 .ruby-version
 .clang_complete

data/CHANGELOG.md

@@ -6,6 +6,30 @@ Please notice that this change log contains changes for upcoming releases as wel
 
 ## Changes:
 
+#### Change log v.0.7.45 (2021-11-26)
+
+**Security**: Fixes a number of issues with the HTTP parser that could have been leveraged in potential exploit attempts such as request smuggling. Credit to @dcepelik (David Čepelík).
+
+**Compatibility**: This release adds experimental Windows support (I don't have Windows, nor Intel, I cannot test this). Credit for a lot of work by @janbiedermann (Jan Biedermann).
+
+#### Change log v.0.7.44 (2021-02-28)
+
+**Fix**: Fixes issue #103 where an empty String response would result in the word "null" being returned (no String object was created, which routed the NULL object to facil.io's JSON interpreter). Credit to @waghanza (Marwan Rabbâa) for exposing the issue.
+
+**Fix**: Fixes a possible edge case race condition where the GC might free a channel name's String object before it's passed on to the user's callback.
+
+**Fix**: Fixes a typo in the CLI documentation.
+
+#### Change log v.0.7.43 (2020-11-03)
+
+**Fix**: Fixes an issue where the GVL state in user-spawned threads is inaccurate. This issue only occurs if spawning a new thread and calling certain Iodine methods from a user thread.
+
+**Fix**: validate that data passed by the user to `write` is a String object and print warnings / raise exceptions if t isn't. Credit to Vamsi Ambati for asking a question that exposed this issue.
+
+#### Change log v.0.7.42 (2020-08-02)
+
+**Fix**: Implement fix suggested by @Shelvak (Néstor Coppi) in issue #98.
+
 #### Change log v.0.7.41 (2020-07-24)
 
 **Fix**: Hot Restart failed because listening sockets were cleared away. Credit to Néstor Coppi (@Shelvak) for exposing issue #97.

data/README.md

@@ -576,8 +576,8 @@ Iodine is written in C and allows some compile-time customizations, such as:
 These options can be used, for example, like so:
 
 ```bash
-$ CFLAGS="-DFIO_FORCE_MALLOC=1 -DHTTP_MAX_HEADER_COUNT=64" \
-  gem install iodine
+  gem install iodine -- \
+      --with-cflags=\"-DHTTP_MAX_HEADER_LENGTH=48000 -DFIO_FORCE_MALLOC=1 -DHTTP_MAX_HEADER_COUNT=64\"
 ```
 
 More possible compile time options can be found in the [facil.io documentation](http://facil.io).

data/SPEC-PubSub-Draft.md

@@ -1,66 +1,106 @@
-# Ruby Pub/Sub API Specification Draft
+# Ruby pub/sub API Specification Draft
+
+### Draft State
+
+This draft is under discussion and will be implemented by iodine starting with the 0.8.x versions.
+
+---
 
 ## Purpose
 
-The pub/sub design is idiomatic to WebSocket and EventSource approaches as well as other reactive programming techniques.
+This document details a Rack specification extension for publish/subscribe (pub/sub) modules that can extend WebSocket / EventSource Rack servers.
 
-The purpose of this specification is to offer a recommendation for pub/sub design that will allow applications to be implementation agnostic (not care which pub/sub extension is used)\*.
+The purpose of this specification is:
 
-Simply put, applications will not have to worry about the chosen pub/sub implementation or about inter-process communication.
+1. To keep separation of concerns by avoiding inter-process-communication logic (IPC) in the application code base.
 
-This should simplify the idiomatic `subscribe` / `publish` approach to real-time data pushing.
+   This is important since IPC is often implemented using pipes / sockets, which could introduce network and IO concerns into the application code.
 
-\* The pub/sub extension could be implemented by any external library as long as the API conforms to the specification. The extension will have to manage the fact that some servers `fork` and manage inter-process communication for pub/sub propagation (or limit it's support to specific servers). Also, servers that opt to implement the pub/sub layer, could perform optimizations related to connection handling and pub/sub lifetimes.
+2. To specify a common publish/subscribe (pub/sub) API for servers and pub/sub modules, allowing applications to easily switch between conforming implementations and servers.
 
-## Pub/Sub handling
+    Since pub/sub design is idiomatic to WebSocket and EventSource approaches, as well as other reactive programming techniques, it is better if applications aren't locked in to a specific server / implementation.
 
-Conforming Pub/Sub implementations **MUST** implement the following pub/sub related methods within the WebSocket/SSE `client` object (as defined in the Rack WebSockets / EventSource specification draft):
+3. To provide common considerations and guidelines for pub/sub implementors to consider when implementing their pub/sub modules.
 
-* `subscribe(to, opt = {}) { |from, message| optional_block }` where `to` is a named *channel* and `opt` is a Hash object that *SHOULD* support the following possible keys (unsupported keys *MUST* be ignored):
+    Some concerns are common for pub/sub implementors, such as integrating third party message brokers (Redis, RabbitMQ, Cassandra)
 
-    * `:match` indicates a matching algorithm should be applied to the `to` variable (`to` is a pattern).
-    
-        Possible (suggested) values should include [`:redis`](https://github.com/antirez/redis/blob/398b2084af067ae4d669e0ce5a63d3bc89c639d3/src/util.c#L46-L167), [`:nats`](https://nats.io/documentation/faq/#wildcards) or [`:rabbitmq`](https://www.rabbitmq.com/tutorials/tutorial-five-ruby.html). Pub/Sub implementations *MAY* support none, some or all of these common pattern resolution schemes.
-    
-    * `:handler` is an alternative to the optional block. It should accept Proc like objects (objects that answer to `.call(from, msg)`).
+## Pub/Sub Instance Methods
+
+Conforming pub/sub implementations **MUST** implement the following pub/sub instance methods:
+
+* `pubsub?` **MUST** return the pub/sub API version as an integer number. Currently, set to `0` (development version).
 
-    * If an optional `block` (or `:handler`) is provided, if will be called when a publication was received. Otherwise, the message alone (**not** the channel data) **MUST** be sent directly to the WebSocket / EventSource client.
+* `subscribe(to, is_pattern = false) { |from, message| optional_block }` where:
 
-    * `:as` accepts either `:text` or `:binary` Symbol objects.
+    * `to` is a named **channel** (or **pattern**).
 
-        This option is only valid if the optional `block` is missing and the connection is a WebSocket connection. Note that SSE connections are limited to text data by design.
+        The implementation **MAY** support pattern matching for named channels (`to`). The pattern matching algorithm used, if any, **SHOULD** be documented.
 
-        This will dictate the encoding for outgoing WebSocket message when publications are directly sent to the client (as a text message or a binary blob). `:text` will be the default value for a missing `:as` option.
+        If the implementation does **NOT** support pattern matching and `is_pattern` is truthful, the implementation **MUST** raise and exception.
 
-        Servers *MAY* ignore this value if they set the message type (text/binary) based on UTF-8 validation.
+        `to` **SHOULD** be a String, but implementations **MAY** support Symbols as aliases to Strings (in which case `:my_channel` is the same `'my_channel'`).
 
-    If a subscription to `to` already exists, it should be *replaced* by the new subscription (the old subscription should be canceled / unsubscribed).
+    * `block` is optional and accepts (if provided) two arguments (`from` which is equal to `to` and `message` which contains the data's content).
 
-    When the `subscribe` method is called within a WebSocket / SSE Callback object, the subscription must be closed automatically when the connection is closed.
+        `block` (if provided) **MUST** be called when a publication was received by the named channel.
+
+        If no `block` is provided:
+
+        * If the pub/sub instance is an extended WebSocket / EventSource (SSE) `client` object (see the WebSocket / EventSource extension draft) data should be directly sent to the `client`.
+
+        * If the pub/sub isn't linked with a `client` / connection, an exception **MUST** be raised.
+
+    If a subscription to `to` already exists for the same pub/sub instance, it should be *replaced* by the new subscription (the old subscription should be canceled / unsubscribed).
+
+    If the pub/sub instance is an extended WebSocket / EventSource (SSE) `client` object (see the WebSocket / EventSource extension draft), the subscription **MUST** be closed automatically when the connection is closed (when `on_close` is called).
+
+    Otherwise, the subscription **MUST** be closed automatically when the pub/sub object goes out of scope and is garbage collected (if this ever happens).
     
     The `subscribe` method **MUST** return `nil` on a known failure (i.e., when the connection is already closed), or any truthful value on success.
 
-    A global variation for this method (allowing global subscriptions to be created) **SHOULD** be made available as `Rack::PubSub.subscribe`.
+* `unsubscribe(from, is_pattern = false)` should cancel a subscription to the `from` named channel / pattern.
+
+* `publish(to, message, engine = nil)` where:
 
-    When the `subscribe` method isn't called from within a connection, it should be considered a global (non connection related) subscription and an exception should be raised if a `block` or `:handler` isn't provided by the user.
+    * `to` is a named channel, same as detailed in `subscribe`.
 
-* `unsubscribe(from)` should cancel a subscription to the `from` named channel / pattern.
+        Implementations **MAY** support pattern based publishing. This **SHOULD** be documented as well as how patterns are detected (as opposed to named channels). Note that pattern publishing isn't supported by common backends (such as Redis) and introduces complex privacy and security concerns.
 
-* `publish(to, message, engine = nil)` (preferably supporting named arguments) where:
+    * `message` a String containing the data to be published.
 
-    * `to` a String that identifies the channel / stream / subject for the publication ("channel" is the semantic used by Redis, it is similar to "subject" or "stream" in other pub/sub systems).
+        If `message` is NOT a String, the implementation **MAY** convert the data silently to JSON. Otherwise, the implementation **MUST** raise an exception.
 
-    * `message` a String with containing the data to be published.
+        `message` encoding (binary / UTZ-8) **MAY** be altered during publication, but any change **MUST** result in valid encoding.
 
-    * `engine` routes the publish method to the specified Pub/Sub Engine (see later on). If none is specified, the default engine should be used. If `false` is specified, the message should be forwarded to all subscribed clients.
+    * `engine` routes the publish method to the specified pub/sub Engine (see later on). If none is specified, the default engine should be used. If `false` is specified, the message **MUST** be forwarded to all subscribed clients on the **same process**.
 
-    The `publish` method must return `true` if a publication was scheduled (not necessarily performed). If it's already known that the publication would fail, the method should return `false`.
+    The `publish` method **MUST** return `true` if a publication was scheduled (not necessarily performed). If it's already known that the publication would fail, the method should return `false`.
 
     An implementation **MUST** call the relevant PubSubEngine's `publish` method after performing any internal book keeping logic. If `engine` is `nil`, the default PubSubEngine should be called. If `engine` is `false`, the implementation **MUST** forward the published message to the actual clients (if any).
 
     A global alias for this method (allowing it to be accessed from outside active connections) **MAY** be defined as `Rack::PubSub.publish`.
 
-Implementations **MUST** implement the following methods in one of their public classes / modules (iodine implements these under `Iodine::PubSub`):
+## Integrating a Pub/Sub module into a WebSocket / EventSource (SSE) `client` object
+
+A conforming pub/sub module **MUST** be designed so that it can be integrated into WebSocket / EventSource (SSE) `client` objects be `include`-ing their class.
+
+This **MUST** result in a behavior where subscriptions are destroyed / canceled once the `client` object state changes to "closed" - i.e., either when the `on_close` callback is called, or the first time the method `client.open?` returns `false`.
+
+The idiomatic way to add a pub/sub module to a `client`'s class is:
+
+```ruby
+client.class.prepend MyPubSubModule unless client.pubsub?
+```
+
+The pub/sub module **MUST** expect and support this behavior.
+
+**Note**: the use of `prepend` (rather than `include`) is chosen so that it's possible to override the `client`'s instance method of `pubsub?`.
+
+## Connecting to External Backends (pub/sub Engines)
+
+It is common for scaling applications to require an external message broker backend such as Redis, RabbitMQ, etc'. The following requirements set a common interface for such "engine" implementation and integration.
+
+Pub/sub implementations **MUST** implement the following module / class methods in one of their public classes / modules (iodine implements these under `Iodine::PubSub`):
 
 * `attach(engine)` where `engine` is a `PubSubEngine` object, as described in this specification.
 
@@ -72,9 +112,9 @@ Implementations **MUST** implement the following methods in one of their public
 
 * `detach(engine)` where `engine` is a PubSubEngine object as described in this specification.
 
-    Removes an engine from the pub/sub system. The opposite of `attach`.
+    The implementation **MUST** remove the engine from the attached engine list. The opposite of `attach`.
 
-* `default = engine` sets a default pub/sub engine, where `engine` is a PubSubEngine object as described in this specification.
+* `default=(engine)` sets a default pub/sub engine, where `engine` is a PubSubEngine object as described in this specification.
 
     Implementations **MUST** forward any `publish` method calls to the default pub/sub engine, unless an `engine` is specified in arguments passes to the `publish` method.
 
@@ -84,34 +124,36 @@ Implementations **MUST** implement the following methods in one of their public
 
     Implementations **MUST** behave as if the engine was newly registered and (re)inform the engine of any existing subscriptions by calling engine's `subscribe` callback for each existing subscription.
 
-Implementations **MAY** implement pub/sub internally (in which case the `default` engine is the server itself or a server's module).
+A `PubSubEngine` instance object **MUST** implement the following methods:
 
-However, servers **MUST** support external pub/sub "engines" as described above, using PubSubEngine objects.
+* `subscribe(to, is_pattern = false)` this method informs the engine that a subscription to the specified channel / pattern exists for the calling the process. It **MUST ONLY** be called **once** for all existing and future subscriptions to that channel within the process.
 
-`PubSubEngine` objects **MUST** implement the following methods:
+    The method **MUST** return `true` if a subscription was scheduled (or performed) or `false` if the subscription is known to fail.
 
-* `subscribe(channel, match=nil)` this method performs the subscription to the specified channel.
+    This method will be called by the pub/sub implementation (for each registered engine). The engine **MAY** assume that the method would never be called directly by an application / client.
 
-    If `match` is a Symbol that the engine recognizes (i.e., `:redis`, `:nats`, etc'), the engine should behave accordingly. i.e., the value `:redis` on a Redis engine will invoke the PSUBSCRIBE Redis command.
+    This method **MUST NOT** raise an exception.
 
-    The method must return `true` if a subscription was scheduled (or performed) or `false` if the subscription is known to fail.
+* `unsubscribe(from, is_pattern = false)` this method informs an engine that there are no more subscriptions to the named channel / pattern for the calling process.
 
-    This method will be called by the server (for each registered engine). The engine may assume that the method would never be called directly by an application.
+    The method's semantics are similar to `subscribe` only is performs the opposite action.
 
-* `unsubscribe(channel, match=nil)` this method performs closes the subscription to the specified channel.
+    This method **MUST NOT** raise an exception.
 
-    The method's semantics are similar to `subscribe`.
+    This method will be called by the pub/sub implementation (for each registered engine). The engine **MAY** assume that the method would never be called directly by an application / client.
 
-    This method will be called by the server (for each registered engine). The engine may assume that the method would never be called directly by an application.
-
-* `publish(channel, message)` where both `channel` and `message` are String objects.
+* `publish(channel, message)` where both `channel` is either a Symbol or a String (both being equivalent) and `message` **MUST** be a String.
 
     This method will be called by the server when a message is published using the engine.
 
-    The engine **MUST** assume that the method might get called directly by an application.
+    This method will be called by the pub/sub implementation (for each registered engine).
+
+    The engine **MUST** assume that the method **MAY** be called directly by an application / client.
+
+In order for a PubSubEngine instance object to publish messages to all subscribed clients on a particular process, it **SHOULD** call the implementation's global `publish` method with the engine set to `false`.
 
-When a PubSubEngine object receives a published message, it *should* call:
+i.e., if the implementation's global `publish` method is in a class called `Iodine`:
 
 ```ruby
-Foo::PubSub.publish channel, message, false
+Iodine.publish channel, message, false
 ```

data/SPEC-WebSocket-Draft.md

@@ -5,62 +5,72 @@ This draft is also implemented by [the Agoo server](https://github.com/ohler55/a
 ---
 ## Purpose
 
-This document details WebSocket / EventSource connection support for Rack servers.
+This document details a Rack specification extension for WebSocket / EventSource servers.
 
-The purpose of these specifications is:
+The purpose of this specification is:
 
-1. To allow separation of concerns between the transport layer and the application, thereby allowing the application to be server agnostic.
+1. To improve application safety by phasing out the use of `hijack` and replacing it with the use of application object callbacks.
 
-    Simply put, when choosing between conforming servers, the application doesn’t need to have any knowledge about the chosen server.
+    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 support “native" (server-side) WebSocket and EventSource (SSE) connections and using application side callbacks.
+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, to make it easy for applications to accept WebSocket and EventSource (SSE) connections from WebSocket and EventSource clients (commonly browsers) while abstracting away any transport layer details.
-
-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).
+    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.
+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.
+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']`:
 
-If a connection is not "upgradable", a conforming server SHOULD set `env['rack.upgrade?']` to either `nil` or `false`. 
+* The server **SHOULD** ignore the Callback Object and process the response as if it did not exist.
 
-The historical use of `upgrade.websocket?` and `upgrade.websocket` (iodine 0.4.x) will be gradually deprecated.
+* 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 the following callbacks:
+The Callback Object could be a any object which implements any (of none) of the following callbacks:
 
-* `on_open(client)` WILL be called once the connection had been established.
+* `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)` WILL be called when incoming WebSocket data is received.
+* `on_message(client, data)` **MUST** be called when incoming WebSocket data is received.
 
     This callback is ignored for EventSource connections.
 
-    `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).
+    `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 and it is *not* required.
+    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 the `client.write` buffer becomes empty. **If** `client.pending` returns a non-zero value, the `on_drained` callback **MUST** be called once the write buffer becomes empty.
+* `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').
+* `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):
 
-* `write(data)` will schedule the data to be sent. `data` **MUST** be a String.
+* `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.
 
-    A call to `write` only promises that the data is scheduled to be sent. Servers are encouraged to avoid blocking and return immediately, deferring the actual `write` operation for later.
+* `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.
 
@@ -70,27 +80,52 @@ The server **MUST** provide the Callback Object with a `client` object, that sup
 
     * If `data` is binary encoded it will be sent as non-text (as specified by the WebSocket Protocol).
 
-    A server **SHOULD** document whether `write` will block. 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.
+    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 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.
+* `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?` returns `true` if the connection isn't known to have been closed and `false` if the connection is known to be closed or marked to be closed.
+* `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` if they never call the `on_drained` callback and the connection is open.
+    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.
 
-    Servers that return a positive number MUST call the `on_drained` callback when a call to `pending` would return the value `0`.
+* `class` **MUST** return the client's Class, allowing it be extended with additional features (such as Pub/Sub, etc').
 
-    \*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.
+    **Note**: Ruby adds this method automatically to every class, no need to do a thing.
 
-* `env` returns 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.
+The server **MAY** support the following (optional) methods for the `client` object:
 
-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.
+* `handler` if implemented, **MUST** return the callback object linked to the `client` 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.
+* `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.
 
 ---
 
@@ -100,62 +135,65 @@ Server settings **MAY** (not required) be provided to allow for customization an
 
 * **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.
+    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**:
 
-    When a client decides to upgrade a request, they will place an appropriate Callback Object in the `env['rack.upgrade']` Hash key.
+    If a client decides to upgrade a request, they will place an appropriate Callback Object in the `env['rack.upgrade']` Hash key.
 
 * **Server**:
 
-    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.
+    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 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.
+    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.
 
-         The response status provided by the response object shall be ignored and the correct response status shall be set by the server.
+    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.
 
-         If the application's response status indicates an error or a redirection (status code >= 300), the server shall ignore the Callback Object.
+         The response status provided by the response object shall be ignored and the correct response status shall be set by the server.
 
-    3. Once the upgrade had completed, the server will call the `on_open` callback.
+    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` will **not** be executed concurrently for the same connection.
+        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 will **not** be called while any other callback is running (`on_open`, `on_message`, `on_drained`, etc').
+        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 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.
+        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
-class WSConnection
+module WSConnection
     def on_open(client)
-        puts "WebSocket connection established."
+        puts "WebSocket connection established (#{client.object_id})."
     end
     def on_message(client, data)
-        client.write data
+        client.write data # echo the data back
         puts "on_drained MUST be implemented if #{ pending } != 0."
     end
     def on_drained(client)
-        puts "Yap,on_drained is implemented."
+        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."
+        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.new
+           env['rack.upgrade'.freeze] = WSConnection
            return [0, {}, []]
        end
        return [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Hello World!"]]
@@ -165,23 +203,22 @@ end
 run App
 ```
 
-The following example uses Push notifications for both WebSocket and SSE connections. The Pub/Sub API isn't part of this specification but it is supported by iodine:
+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
-class Chat
-    def initialize(nickname)
-        @nickname = nickname
-    end
+module Chat
     def on_open(client)
+        client.class.prepend MyPubSubModule unless client.pubsub?
         client.subscribe "chat"
-        client.publish "chat", "#{@nickname} joined the chat."
+        client.publish "chat", "#{env[:nickname]} joined the chat."
     end
     def on_message(client, data)
-        client.publish "chat", "#{@nickname}: #{data}"
+        client.publish "chat", "#{env[:nickname]}: #{data}"
     end
     def on_close(client)
-        client.publish "chat", "#{@nickname}: left the chat."
+        client.publish "chat", "#{env[:nickname]}: left the chat."
     end
+    extend self
 end
 
 module App
@@ -189,7 +226,7 @@ module App
        if(env['rack.upgrade?'.freeze])
            nickname = env['PATH_INFO'][1..-1]
            nickname = "Someone" if nickname == "".freeze
-           env['rack.upgrade'.freeze] = Chat.new(nickname)
+           env[:nickname] = nickname
            return [0, {}, []]
        end
        return [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Hello World!"]]