iodine 0.7.39 → 0.7.44

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad7a8dc81e2698056037086bfd6dd2f24ee975229a928092ac039ae9c44cb0d7
-  data.tar.gz: 84ff62b2c79efe4b0f5f1d796e27e6513bc8a29414fbd771404c814567d1138c
+  metadata.gz: a212aecebe63d7033c5c1e985d4e2f90588dc604c8aa6a25965735aeef79ec72
+  data.tar.gz: 299ef31e1f2209cb11c0c49f2d4851d8c779a2744ebc08f42fb430ffaf3d76cc
 SHA512:
-  metadata.gz: bc69044b0cac72fda7be13ffb6e039007282f07e6b2607ea23e0a97733250d1b883d5e9cee171c67095e4eebd623f04f4d9d08ee2067f5a42a923b6785e3b824
-  data.tar.gz: b182b80a365fabaa0b97ce312f4bd2033ed28ba5a07759674cd305486f7a43ae64704da76449a84379be1a844ffe2df9396a863f4e8df5a9883d796be9fc3a91
+  metadata.gz: a6f12dfcff4eced37d98f627be0cb6a9662c8bac98365a5080ea0c47f9c3ae3919e315836ec33989be098c52c826707e0f22fa746f95a3847b354d6d0efa4f79
+  data.tar.gz: 1b5541f8c952f6b61feeb183cc6d7587ca200b4295afec9c9e540c69699f065c03724b46b464c929cc0aa800b594a0cdb83ec7b9a1b57c7501ba5633cb270124

data/.travis.yml

@@ -1,4 +1,7 @@
 language: ruby
+arch:
+  - amd64
+  - arm64
 os:
   - linux
   # - osx
@@ -6,6 +9,7 @@ before_install:
   - gem install bundler -v 1.10.6
   - bundle install
 rvm:
+  - 2.7.1
   - 2.6.5
   - 2.5.7
   - 2.4.9
@@ -14,7 +18,7 @@ rvm:
 notifications:
   email: false
 sudo: required
-dist: trusty
+dist: xenial
 addons:
   apt:
     sources:
@@ -24,8 +28,5 @@ addons:
 script:
   - echo CFLAGS = $CFLAGS
   - echo cflags = $cflags
-  - bundle exec rake compile
+  - bundle exec rake install
   - env VERBOSE=1 bundle exec rspec --format documentation
-  - gem uninstall -x iodine
-  - rake build
-  - find pkg/iodine-*.gem -exec gem install -V {} +

data/CHANGELOG.md

@@ -6,6 +6,34 @@ Please notice that this change log contains changes for upcoming releases as wel
 
 ## Changes:
 
+#### 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.
+
+**Fix**: CLI argument parsing is now only active when using the iodine CLI (or if defining `IODINE_PARSE_CLI` before requiring `iodine`). Credit to Aldis Berjoza (@graudeejs) for exposing issue #96.
+
+#### Change log v.0.7.40 (2020-05-23)
+
+**Fix**: fixed TLS logging and performance issues exposed by Franck Gille (@fgi) in issue #93.
+
 #### Change log v.0.7.39 (2020-05-18)
 
 **Security**: a request smuggling attack vector and Transfer Encoding attack vector in the HTTP/1.1 parser were exposed by Sam Sanoop from [the Snyk Security team (snyk.io)](https://snyk.io). The parser was updated to deal with these potential issues.

data/README.md

@@ -19,14 +19,15 @@ Iodine includes native support for:
 * Pub/Sub (with optional Redis Pub/Sub scaling);
 * Fast(!) builtin Mustache template engine.
 * Static file service (with automatic `gzip` support for pre-compressed assets);
+* Optimized Logging to `stderr`.
 * Asynchronous event scheduling and timers;
 * HTTP/1.1 keep-alive and pipelining;
+* Heap Fragmentation Protection.
 * TLS 1.2 and above (Requires OpenSSL >= 1.1.0);
 * TCP/IP server and client connectivity;
 * Unix Socket server and client connectivity;
-* Hot Restart (using the USR1 signal);
+* Hot Restart (using the USR1 signal and without hot deployment);
 * Custom protocol authoring;
-* Optimized Logging to `stderr`.
 * [Sequel](https://github.com/jeremyevans/sequel) and ActiveRecord forking protection.
 * and more!
 
@@ -48,6 +49,10 @@ With `Iodine.listen service: :http` it's possible to run multiple HTTP applicati
 
 Iodine also supports native process cluster Pub/Sub and a native RedisEngine to easily scale iodine's Pub/Sub horizontally.
 
+### Known Issues and Reporting Issues
+
+See the [GitHub Open Issues](https://github.com/boazsegev/iodine/issues) list for known issues and to report new issues.
+
 ### Installing and Running Iodine
 
 Install iodine on any Linux / BSD / macOS system using:
@@ -70,6 +75,8 @@ bundler exec iodine
 
 #### Installing with SSL/TLS
 
+**Note**: iodine has known issues with the TLS/SSL support. TLS/SSL should **NOT** be used in production (see issues #95 and #94).
+
 Make sure to update OpenSSL to the latest version **before installing Ruby** (`rbenv` should do this automatically).
 
 To avoid name resolution conflicts, iodine will bind to the same OpenSSL version Ruby is bound to. To use SSL/TLS this should be OpenSSL >= 1.1.0 or LibreSSL >= 2.7.4.
@@ -87,9 +94,7 @@ Confirmed OpenSSL to be version 1.1.0 or above (OpenSSL 1.1.0j  20 Nov 2018)...
 ...
 ```
 
-**KNOWN ISSUE:**
-
-The installation script tests for OpenSSL 1.1.0 and above. However, this testing approach sometimes provides false positives. If TLS isn't required, install with `NO_SSL=1`. i.e.:
+The installation script tests for OpenSSL 1.1.0 and above. However, this testing approach sometimes provides false positives. **If TLS isn't required, install with `NO_SSL=1`**. i.e.:
 
 ```bash
 NO_SSL=1 bundler exec iodine
@@ -110,17 +115,19 @@ On Rails:
     if(defined?(Iodine))
       Iodine.threads = ENV.fetch("RAILS_MAX_THREADS", 5).to_i if Iodine.threads.zero?
       Iodine.workers = ENV.fetch("WEB_CONCURRENCY", 2).to_i if Iodine.workers.zero?
-      Iodine::DEFAULT_SETTINGS[:port] = ENV.fetch("PORT") if ENV.fetch("PORT")
+      Iodine::DEFAULT_SETTINGS[:port] ||= ENV.fetch("PORT") if ENV.fetch("PORT")
     end
     ```
 
 When using native WebSockets with Rails, middle-ware is probably the best approach. A guide for this approach will, hopefully, get published in the future.
 
+**Note**: command-line instructions (CLI) should be the preferred way for configuring iodine, allowing for code-less configuration updates.
+
 ### Optimizing Iodine's Concurrency
 
 To get the most out of iodine, consider the amount of CPU cores available and the concurrency level the application requires.
 
-Iodine will calculate, when possible, a good enough default concurrency model. See if this works for your application or customize according to the application's needs.
+Iodine will calculate, when possible, a good enough default concurrency model for fast applications. See if this works for your application or customize according to the application's needs.
 
 Command line arguments allow easy access to different options, including concurrency levels. i.e., to set up 16 threads and 4 processes:
 
@@ -136,13 +143,19 @@ export WORKERS=-1 # negative values are fractions of CPU cores.
 bundler exec iodine -p $PORT
 ```
 
+Negative values are evaluated as "CPU Cores / abs(Value)". i.e., on an 8 core CPU machine, this will produce 4 worker processes with 2 threads per worker:
+
+```bash
+bundler exec iodine -p $PORT -t 2 -w -2
+```
+
 ### Heap Fragmentation Protection
 
 Iodine includes a fast, network oriented, custom memory allocator, optimizing away some of the work usually placed on the Ruby Garbage Collector (GC).
 
 This approach helps to minimize heap fragmentation for long running processes, by grouping many short-lived objects into a common memory space.
 
-It's still recommended to consider [jemalloc](http://jemalloc.net) or other allocators that also help mitigate heap fragmentation issues.
+It is still recommended to consider [jemalloc](http://jemalloc.net) or other allocators that also help mitigate heap fragmentation issues.
 
 ### Static file serving support
 
@@ -435,11 +448,11 @@ Iodine.connect url: "wss://echo.websocket.org", handler: EchoClient.new, ping: 4
 Iodine.start
 ```
 
-### TLS 1.2 support
+### TLS >= 1.2 support
 
 >  Requires OpenSSL >= `1.1.0`. On Heroku, requires `heroku-18`.
 
-Iodine supports secure connections fore TLS version 1.2 and up (depending on the OpenSSL version).
+Iodine supports secure connections fore TLS version 1.2 **and up** (depending on the OpenSSL version).
 
 A self signed certificate is available using the `-tls` flag from the command-line.
 
@@ -480,31 +493,11 @@ run APP
 
 ### How does it compare to other servers?
 
-The honest answer is "I don't know". I recommend that you perform your own tests.
-
-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.
+In my tests, pitching Iodine against Puma, Iodine was anywhere between x1.5 and more than x10 faster than Puma (depending on use-case and settings).
 
-Also, performing benchmarks on a single machine isn't very reliable... but it's all I've got.
+Such a big difference is suspect and I recommend that you test it yourself - even better if you test performance using your own application and a number of possible different settings (how many threads per CPU core? how many worker processes? middleware vs. server request logging, etc').
 
-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.
-
-* 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 23,559.56 req/sec, consuming ~88.8Mb 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), I calculated Iodine to be x7.3 faster:
-
-* Iodine performed at 18,444.31 req/sec, consuming ~25.6Mb of memory.
-
-* Puma performed at 2,521.56 req/sec, consuming ~27.5Mb of memory.
-
-I have doubts about my own benchmarks and I recommend benchmarking the performance for yourself using `wrk` or `ab`:
+I recommend benchmarking the performance for yourself using `wrk` or `ab`:
 
 ```bash
 $ wrk -c200 -d4 -t2 http://localhost:3000/
@@ -512,7 +505,7 @@ $ wrk -c200 -d4 -t2 http://localhost:3000/
 $ ab -n 100000 -c 200 -k http://127.0.0.1:3000/
 ```
 
-Create a simple `config.ru` file with a hello world app:
+The best application to use for benchmarking is your actual application. Or, you could create a simple `config.ru` file with a __hello world__ app:
 
 ```ruby
 App = Proc.new do |env|
@@ -525,17 +518,21 @@ end
 run App
 ```
 
-Then start comparing servers. Here are the settings I used to compare iodine and Puma (4 processes, 16 threads):
+Then start comparing servers. Here are the settings I used to compare iodine and Puma (4 processes, 4 threads):
 
 ```bash
-$ RACK_ENV=production iodine -p 3000 -t 16 -w 4
+$ RACK_ENV=production iodine -p 3000 -t 4 -w 4
 # vs.
-$ RACK_ENV=production puma -p 3000 -t 16 -w 4
+$ RACK_ENV=production puma -p 3000 -t 4 -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.
 
+It is worth noting that iodine can also speed up logging by replacing the logging middleware with `iodine -v`. This approach uses less memory and improves performance at the expense of fuzzy timing and some string caching.
+
+On my machine, testing with the logging functionality enabled, iodine was more then 10 times faster than puma (60.9K req/sec vs. 5.3K req/sec)
+
 ### A few notes
 
 Iodine's upgrade / callback 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.
@@ -579,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
 ```