iodine 0.4.19 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b93946ad1ced55f2345f08bb90b3147ba0f8c1262391e34121cfc94b1b43d43
-  data.tar.gz: a724632ed98f2aa7998465fba68b4d6115fccdae29c1442b8fcfcecccc0fcbd0
+  metadata.gz: ddc0f34881258b83f214f4809227c826c6bc8f1e259a29fecc0d583c2d6c9a69
+  data.tar.gz: 58686f504218966ed558172cca8176c05fde580c122d8d2dc8196253f31c8d14
 SHA512:
-  metadata.gz: 2455dd897c6628120810579c75c6c7c8f235a150ae0c500a60fabf99d99eda81083c39845790723a229c8ab6a4602e7ad16521122c6e4d68b026d6d36d716001
-  data.tar.gz: d2fa620f1b1510900c17048c4fd11276d04c218e0ab78775ac067afa041c65a0eac22ec30bbe218c4669d099c16058cf886d92ed2a08e02836a5195fad43139c
+  metadata.gz: 608097ab4f29ed39435098c4b2930379d164b4e6d76634032ea056efc8b7f55dad2092cc28ab4bdf4172630eb3c707f68eecfd31f0a43c5e3b6511d9268994f6
+  data.tar.gz: d36b60bc3a67815afa9b2be2c1a2a00a773264146d4ecb5f796e12ab7c143664e2dd3e66f535272ba1c74a6e381e27ff57752d7f88dc3ba4f0d40a7032a6bc19

data/.travis.yml

@@ -5,10 +5,9 @@ os:
 before_install:
   - gem install bundler -v 1.10.6
 rvm:
+  - 2.5.0
   - 2.4.0
   - 2.3.1
-  - 2.3.0
-  - 2.2.4
   - 2.2.2
 notifications:
   email: false

data/CHANGELOG.md

@@ -6,6 +6,28 @@ Please notice that this change log contains changes for upcoming releases as wel
 
 ## Changes:
 
+#### Change log v.0.5.0
+
+Changed... everything. At least all the internal bits and some of the API.
+
+Iodine 0.5.0 is a stability oriented release. It also supports the updated Rack specification draft for WebSocket and SSE connections (yes, iodine 0.5.0 brings about SSE support).
+
+Deprecated the `each` function family in favor of the more scalable pub/sub approach.
+
+Moved the HTTP network layer outside of the GIL, more robust pub/sub (using Unix Sockets instead of pipes), hot restart (in cluster mode) and more.
+
+Larger header support. The total headers length now defaults to 32Kb, but can be adjusted. A hard coded limit of 8Kb per header line is still enforced (to minimize network buffer).
+
+Improved concurrency and energy consumption (idling CPU cycles reduced).
+
+Higher overall memory consumption might be observed (some security and network features now perform data copying rather than allowing for direct data access).
+
+Improved automatic header completion for missing `Content-Length`, `Date` and `Last-Modified`.
+
+Support for the Unicorn style `before_fork` and `after_fork` DSL as well as the Puma style `on_worker_boot` DSL.
+
+Credit to Anatoly Nosov (@jomei) for fixing some typos in the documentation.
+
 ---
 
 #### Change log v.0.4.19

data/LIMITS.md

@@ -1,25 +1,35 @@
 # Iodine limits and settings
 
-I will, at some point, document these... here's a few things:
+I will, at some point, document these... here's the key points:
 
-## HTTP/1.x limits
-
-* HTTP Headers have a ~16Kb total size limit.
+## HTTP limits
 
 * Uploads are adjustable and limited to ~50Mib by default.
 
-* HTTP keep-alive is adjustable and set to ~5 seconds by default.
+* HTTP connection timeout (keep-alive) is adjustable and set to ~60 seconds by default.
+
+* HTTP total header size is adjustable and limited to ~32Kib by default.
+
+* HTTP header line length size is limited to a hard-coded limit of 8Kb.
+
+* HTTP headers count is limited to a hard-coded limit of 128 headers.
 
 ## Websocket
 
 * Incoming Websocket message size limits are adjustable and limited to ~250Kib by default.
 
-## Pub/Sub
+## EventSource / SSE
 
-* Channel names are binary safe, but limited to 1024 characters (even though Redis doesn't seem to limit channel name length).
+* Iodine will automatically attempt to send a `ping` event instead of disconnecting the connection. The ping interval is the same as the HTTP connection timeout interval.
 
-    Iodine uses a [trie](https://en.wikipedia.org/wiki/Trie) to match channel names. A trie offers binary exact matching with a fast lookup (unlike hash lookups, this offers zero name collision risk). However, it also means that channel names are memory **expensive**.
+## Pub/Sub
+
+* Channel names are binary safe and unlimited in length. However, name lengths effect performance.
 
-    As a side effect, sequencial channel names have an advantage over random channel names.
+    **Do NOT allow clients to dictate the channel name**, as they might use extremely long names and cause resource starvation.
 
 * Pub/sub is limited to the process cluster. To use pub/sub with an external service (such as Redis) an "Engine" is required (see YARD documentation).
+
+* Pub/sub pattern matching supports only the Redis pattern matching approach. This makes patterns significantly more expensive and exact matches simpler and faster.
+
+    It's recommended to prefer exact channel/stream name matching when possible.

data/README.md

@@ -1,22 +1,22 @@
-# iodine - HTTP / Websocket Server with Pub/Sub support, optimized for Ruby MRI on Linux / BSD
-[![Logo](https://github.com/boazsegev/iodine/raw/master/logo.png)](https://github.com/boazsegev/iodine)
-
+# iodine - a fast HTTP / Websocket Server with native Pub/Sub support for the new web
+[![Gem](https://img.shields.io/gem/dt/iodine.svg)](https://rubygems.org/gems/iodine)
 [![Build Status](https://travis-ci.org/boazsegev/iodine.svg?branch=master)](https://travis-ci.org/boazsegev/iodine)
 [![Gem Version](https://badge.fury.io/rb/iodine.svg)](https://badge.fury.io/rb/iodine)
 [![Inline docs](http://inch-ci.org/github/boazsegev/iodine.svg?branch=master)](http://www.rubydoc.info/github/boazsegev/iodine/master/frames)
 [![GitHub](https://img.shields.io/badge/GitHub-Open%20Source-blue.svg)](https://github.com/boazsegev/iodine)
 
-***Notice*: iodine's core library, [facil.io](https://github.com/boazsegev/facil.io) is being re-vamped with many updates and changes. This is a time to ask - what features are important for you? [let me know here](https://github.com/boazsegev/facil.io/issues/24)**.
+[![Logo](https://github.com/boazsegev/iodine/raw/master/logo.png)](https://github.com/boazsegev/iodine)
 
-**The development branch is the `v.0.5-rewrite` branch.**
+**Notice: *iodine's core library, [facil.io](https://github.com/boazsegev/facil.io) is being re-vamped with many updates and changes. This is a time to ask - what features are important for you? [let me know here](https://github.com/boazsegev/facil.io/issues/24)***.
 
 Iodine is a fast concurrent web server for real-time Ruby applications, with native support for:
 
-* Websockets;
+* Websockets and EventSource (SSE);
 * Pub/Sub (with optional Redis Pub/Sub scaling);
 * Static file service (with automatic `gzip` support for pre-compressed versions);
 * HTTP/1.1 keep-alive and pipelining;
 * Asynchronous event scheduling and timers;
+* Hot Restart (using the USR1 signal);
 * Client connectivity (attach client sockets to make them evented);
 * Custom protocol authoring;
 * and more!
@@ -93,6 +93,8 @@ bundler exec iodine -p $PORT -t 16 -w 4 -www /my/public/folder -v
 
 Ruby can leverage static file support (if enabled) by using the `X-Sendfile` header in the Ruby application response.
 
+To enable iodine's native X-Sendfile support, a static file service (a public folder) needs to be assigned (this informs iodine that static files aren't sent using a different layer, such as nginx).
+
 This allows Ruby to send very large files using a very small memory footprint, as well as (when possible) leveraging the `sendfile` system call.
 
 i.e. (example `config.ru` for iodine):
@@ -115,7 +117,7 @@ end
 run app
 ```
 
-Go to [localhost:3000/source](http://localhost:3000/source) to download the `config.ru` file using the `X-Sendfile` extension.
+Go to [localhost:3000/source](http://localhost:3000/source) to experience the `X-Sendfile` extension at work.
 
 #### Pre-Compressed assets / files
 
@@ -131,47 +133,61 @@ When a browser that supports compressed encoding (which is most browsers) reques
 
 It's as easy as that. No extra code required.
 
-### Special HTTP `Upgrade` support
+### Special HTTP `Upgrade` and SSE support
+
+Iodine's HTTP server implements the [WebSocket/SSE Rack Specification Draft](SPEC-Websocket-Draft.md), supporting native WebSocket/SSE connections using Rack's `env` Hash.
+
+This promotes separation of concerns, where iodine handles all the Network related logic and the application can focus on the API and data it provides.
 
-Iodine's HTTP server includes special support for the Upgrade directive using Rack's `env` Hash, allowing the application to focus on services and data while iodine takes care of the network layer.
+Upgrading an HTTP connection can be performed either using iodine's native WebSocket / EventSource (SSE) support with `env['rack.upgrade?']` or by implementing your own protocol directly over the TCP/IP layer - be it a WebSocket flavor or something completely different - using `env['upgrade.tcp']`.
 
-Upgrading an HTTP connection can be performed either using iodine's Websocket Protocol support with `env['upgrade.websocket']` or by implementing your own protocol directly over the TCP/IP layer - be it a websocket flavor or something completely different - using `env['upgrade.tcp']`.
+#### EventSource / SSE
 
-#### Websockets
+Iodine treats EventSource / SSE connections as if they were a half-duplex WebSocket connection, using the exact same API and callbacks as WebSockets.
 
-When an HTTP Upgrade request is received, iodine will set the Rack Hash's upgrade property to `true`, so that: `env[upgrade.websocket?] == true`
+When an EventSource / SSE request is received, iodine will set the Rack Hash's upgrade property to `:sse`, so that: `env[rack.upgrade?] == :sse`.
 
-To "upgrade" the HTTP request to the Websockets protocol, simply provide iodine with a Websocket Callback Object instance or class: `env['upgrade.websocket'] = MyWebsocketClass` or `env['upgrade.websocket'] = MyWebsocketClass.new(args)`
+The rest is detailed in the WebSocket support section.
 
-Iodine will adopt the object, providing it with network functionality (methods such as `write`, `each`, `defer` and `close` will become available) and invoke it's callbacks on network events.
+#### WebSockets
 
-Here is a simple chatroom example we can run in the terminal (`irb`) or easily paste into a `config.ru` file:
+When a WebSocket connection request is received, iodine will set the Rack Hash's upgrade property to `:websocket`, so that: `env[rack.upgrade?] == :websocket`
+
+To "upgrade" the HTTP request to the WebSockets protocol (or SSE), simply provide iodine with a WebSocket Callback Object instance or class: `env['rack.upgrade'] = MyWebsocketClass` or `env['rack.upgrade'] = MyWebsocketClass.new(args)`
+
+Iodine will adopt the object, providing it with network functionality (methods such as `write`, `defer` and `close` will become available) and invoke it's callbacks on network events.
+
+Here is a simple chat-room example we can run in the terminal (`irb`) or easily paste into a `config.ru` file:
 
 ```ruby
 require 'iodine'
 class WebsocketChat
   def on_open
     # Pub/Sub directly to the client (or use a block to process the messages)
-    subscribe channel: :chat
+    subscribe :chat
     # Writing directly to the socket
     write "You're now in the chatroom."
   end
   def on_message data
     # Strings and symbol channel names are equivalent.
-    publish channel: "chat", message: data
+    publish "chat", data
   end
 end
 Iodine::Rack.app= Proc.new do |env|
-  if env['upgrade.websocket?'.freeze] && env["HTTP_UPGRADE".freeze] =~ /websocket/i.freeze
-    env['upgrade.websocket'.freeze] = WebsocketChat # or: WebsocketChat.new
+  if env['rack.upgrade?'.freeze] == :websocket 
+    env['rack.upgrade'.freeze] = WebsocketChat # or: WebsocketChat.new
+    [0,{}, []] # It's possible to set cookies for the response.
+  elsif env['rack.upgrade?'.freeze] == :sse
+    puts "SSE connections can only receive data from the server, the can't write." 
+    env['rack.upgrade'.freeze] = WebsocketChat # or: WebsocketChat.new
     [0,{}, []] # It's possible to set cookies for the response.
   else
-    [200, {"Content-Length" => "12"}, ["Welcome Home"] ]
+    [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Welcome Home"] ]
   end
 end
 # Pus/Sub can be server oriented as well as connection bound
 root_pid = Process.pid
-Iodine.subscribe(channel: :chat) {|ch, msg| puts msg if Process.pid == root_pid }
+Iodine.subscribe(:chat) {|ch, msg| puts msg if Process.pid == root_pid }
 # By default, Pub/Sub performs in process cluster mode.
 Iodine.processes = 4
 # static file serving can be set manually as well as using the command line:
@@ -208,19 +224,11 @@ if(Iodine.default_pubsub.is_a? Iodine::PubSub::RedisEngine)
 end
 ```
 
-**Details and Limitations:**
-
-* Iodine does not use a Hash table for the Pub/Sub channels, it uses a [4 bit trie](https://en.wikipedia.org/wiki/Trie).
-
-    The cost is higher memory consumption per channel and a limitation of 1024 bytes per channel name (shorter names are better).
-
-    The bonus is high lookup times, zero chance of channel conflicts and an optimized preference for shared prefix channels (i.e. "user:1", "user:2"...).
-
-    Another added bonus is pattern publishing (is addition to pattern subscriptions) which isn't available when using Redis (since Redis doesn't support this feature).
+**Pub/Sub Details and Limitations:**
 
 * Iodine's Redis client does *not* support multiple databases. This is both because [database scoping is ignored by Redis during pub/sub](https://redis.io/topics/pubsub#database-amp-scoping) and because [Redis Cluster doesn't support multiple databases](https://redis.io/topics/cluster-spec). This indicated that multiple database support just isn't worth the extra effort.
 
-* The iodine Redis client will use two Redis connections per process (one for subscriptions and the other for publishing and commands). Both connections will be automatically re-established if timeouts or errors occur.
+* The iodine Redis client will use a single Redis connection per process (for publishing data) and an extra Redis connection for subscriptions (owned by the master process). Connections will be automatically re-established if timeouts or errors occur.
 
 #### TCP/IP (raw) sockets
 
@@ -241,7 +249,7 @@ Iodine::Rack.app = Proc.new do |env|
     # to upgrade AFTER a response, set a valid response status code.
     [1000,{}, []]
   else
-    [200, {"Content-Length" => "12"}, ["Welcome Home"] ]
+    [200, {"Content-Length" => "12", "Content-Type" => "text/plain"}, ["Welcome Home"] ]
   end
 end
 Iodine.start
@@ -251,63 +259,38 @@ Iodine.start
 
 This design has a number of benefits, some of them related to better IO handling, resource optimization (no need for two IO polling systems), etc. This also allows us to use middleware without interfering with connection upgrades and provides backwards compatibility.
 
-Iodine::Rack imposes a few restrictions for performance and security reasons, such as that the headers (both sending and receiving) must be less than 8Kb in size. These restrictions shouldn't be an issue and are similar to limitations imposed by Apache.
+Iodine::Rack imposes a few restrictions for performance and security reasons, such as limitimg each header line to 4Kb. These restrictions shouldn't be an issue and are similar to limitations imposed by Apache or Nginx.
 
 Of course, if you still want to use Rack's `hijack` API, iodine will support you - but be aware that you will need to implement your own reactor and thread pool for any sockets you hijack, as well as a socket buffer for non-blocking `write` operations (why do that when you can write a protocol object and have the main reactor manage the socket?).
 
-### Performance oriented design - but safety first
-
-Iodine is an evened server, similar in it's architecture to `nginx` and `puma`. It's different than the simple "thread-per-client" design that is often taught when we begin to learn about network programming.
-
-By leveraging `epoll` (on Linux) and `kqueue` (on BSD), iodine can listen to multiple network events on multiple sockets using a single thread.
-
-All these events go into a task queue, together with the application events and any user generated tasks, such as ones scheduled by [`Iodine.run`](http://www.rubydoc.info/github/boazsegev/iodine/Iodine#run-class_method).
-
-In pseudo-code, this might look like this
-
-```ruby
-QUEUE = Queue.new
-
-def server_cycle
-    if(QUEUE.empty?)
-      QUEUE << get_next_32_socket_events # these events schedule the proper user code to run
-    end
-    QUEUE << server_cycle
-end
+### How does it compare to other servers?
 
-def run_server
-      while ((event = QUEUE.pop))
-            event.shift.call(*event)
-      end
-end
-```
+Personally, after looking around, the only comparable servers are Puma and Passenger (both offer multi-threaded and multi-process concurrency), which iodine significantly outperformed on my tests (I didn't test Passenger's enterprise version). Another upcoming server is the Agoo server (which has a very high performance).
 
-In pure Ruby (without using C extensions or Java), it's possible to do the same by using `select`... and although `select` has some issues, it works well for lighter loads.
+When benchmarking with `wrk`, on the same local machine with similar settings (4 workers, 16 threads each, 200 concurrent connections), iodine performed better than Puma (I don't have Passenger enterprise, so I couldn't compare against it). 
 
-The server events are fairly fast and fragmented (longer code is fragmented across multiple events), so one thread is enough to run the server including it's static file service and everything... 
+* Iodine performed at 69,885.30 req/sec, consuming ~77.8Mb of memory.
 
-...but single threaded mode should probably be avoided.
+* Puma performed at 48,994.59 req/sec, consuming ~79.6Mb of memory.
 
-The thread pool is there to help slow user code.
 
-It's very common that the application's code will run slower and require external resources (i.e., databases, a custom pub/sub service, etc'). This slow code could "starve" the server, which is patiently waiting to run it's tasks on the same thread.
+When benchmarking with `wrk` and using striped down settings (single worker, single thread, 200 concurrent connections), iodine was faster than Puma.
 
-The slower your application code, the more threads you will need to keep the server running in a responsive manner (note that responsiveness and speed aren't always the same).
+* Iodine performed at 56,648.86 req/sec, consuming ~27.4Mb of memory.
 
-### How does it compare to other servers?
+* Puma performed at 16,547.31 req/sec, consuming ~23.4Mb of memory.
 
-Personally, after looking around, the only comparable servers are Puma and Passenger, which iodine significantly outperformed on my tests (I didn't test Passenger's enterprise version).
+When benchmarking using a VM (crossing machine boundaries, single thread, single worker, 200 concurrent connections), iodine significantly outperformed Puma.
 
-Since the HTTP and Websocket parsers are written in C (with no RegExp), they're fairly fast.
+* Iodine performed at 18,444.31 req/sec, consuming ~25.6Mb of memory.
 
-Also, iodine's core and parsers are running outside of Ruby's global lock, meaning that they enjoy true concurrency before entering the Ruby layer (your application) - this offers iodine a big advantage over other Ruby servers.
+* Puma performed at 2,521.56 req/sec, consuming ~27.5Mb of memory.
 
-Another assumption iodine makes is that it is behind a load balancer / proxy (which is the normal way Ruby applications are deployed) - this allows iodine to disregard some header validity checks (we're not checking for invalid characters) and focus it's resources on other security and performance concerns.
 
-I recommend benchmarking the performance for yourself using `wrk` or `ab`:
+I have doubts about my own benchmarks and I recommend benchmarking the performance for yourself using `wrk` or `ab`:
 
 ```bash
-$ wrk -c200 -d4 -t12 http://localhost:3000/
+$ wrk -c200 -d4 -t2 http://localhost:3000/
 # or
 $ ab -n 100000 -c 200 -k http://127.0.0.1:3000/
 ```
@@ -334,18 +317,50 @@ $ RACK_ENV=production puma -p 3000 -t 16 -w 4
 # Review the `iodine -?` help for more command line options.
 ```
 
+### Performance oriented design - but safety first
 
-When benchmarking with `wrk`, iodine performed significantly better, (~62K req/sec vs. ~44K req/sec) while keeping a lower memory foot print (~60Mb vs. ~111Mb).
+Iodine is an evened server, similar in it's architecture to `nginx` and `puma`. It's different than the simple "thread-per-client" design that is often taught when we begin to learn about network programming.
 
-When benchmarking with `ab`, I got different results, where iodine still performed significantly better, (~72K req/sec vs. ~36K req/sec and ~61Mb vs. ~81.6Mb). I suspect the difference between the two benchmarks has to do with system calls to `write` and possible packet fragmentation, but I have no real proof.
+By leveraging `epoll` (on Linux) and `kqueue` (on BSD), iodine can listen to multiple network events on multiple sockets using a single thread.
+
+All these events go into a task queue, together with the application events and any user generated tasks, such as ones scheduled by [`Iodine.run`](http://www.rubydoc.info/github/boazsegev/iodine/Iodine#run-class_method).
 
-Remember to compare the memory footprint after running some requests - it's not just speed that C is helping with, it's also memory management and object pooling (i.e., iodine uses a buffer packet pool management).
+In pseudo-code, this might look like this
+
+```ruby
+QUEUE = Queue.new
+
+def server_cycle
+    if(QUEUE.empty?)
+      QUEUE << get_next_32_socket_events # these events schedule the proper user code to run
+    end
+    QUEUE << server_cycle
+end
+
+def run_server
+      while ((event = QUEUE.pop))
+            event.shift.call(*event)
+      end
+end
+```
+
+In pure Ruby (without using C extensions or Java), it's possible to do the same by using `select`... and although `select` has some issues, it works well for lighter loads.
+
+The server events are fairly fast and fragmented (longer code is fragmented across multiple events), so one thread is enough to run the server including it's static file service and everything... 
+
+...but single threaded mode should probably be avoided.
+
+The thread pool is there to help slow user code.
+
+It's very common that the application's code will run slower and require external resources (i.e., databases, a custom pub/sub service, etc'). This slow code could "starve" the server, which is patiently waiting to run it's tasks on the same thread.
+
+The slower your application code, the more threads you will need to keep the server running in a responsive manner (note that responsiveness and speed aren't always the same).
 
-## Can I try before I buy?
+## Free, as in freedom (BYO beer)
 
-Well, it is **free** and **open source**, no need to buy.. and of course you can try it out.
+Iodine is **free** and **open source**, so why not take it out for a spin?
 
-It's installable just like any other gem on MRI, run:
+It's installable just like any other gem on Ruby MRI, run:
 
 ```
 $ gem install iodine

data/SPEC-PubSub-Draft.md

@@ -0,0 +1,113 @@
+# Ruby Pub/Sub API Specification Draft
+
+## Purpose
+
+The pub/sub design is idiomatic to WebSocket and EventSource approaches as well as other reactive programming techniques.
+
+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)\*.
+
+Simply put, applications will not have to worry about the chosen pub/sub implementation or about inter-process communication.
+
+This should simplify the idiomatic `subscribe` / `publish` approach to real-time data pushing.
+
+\* 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.
+
+## Pub/Sub handling
+
+Conforming Pub/Sub implementations **MUST** extend the WebSocket and SSE callback objects to implement the following pub/sub related methods (this requires that either the Pub/Sub implementation has knowledge about the Server OR that the Server has knowledge about the Pub/Sub implementation):
+
+* `subscribe(to, opt = {}) { |from, message| optional_block }` where `opt` is a Hash object that supports the following possible keys (undefined keys *SHOULD* be ignored):
+
+    * `:match` indicates a matching algorithm should be applied. Possible 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 should support some or all of these common pattern resolution schemes.
+    
+    * `:handler` is an alternative to the optional block. It should accept Proc like opbjects (objects that answer to `call(from, msg)`).
+
+    * 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) should be sent directly to the WebSocket / EventSource client.
+
+    * `:as` accepts either `:text` or `:binary` Symbol objects.
+
+        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.
+
+        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 `subscribe` method is called within a WebSocket / SSE Callback object, the subscription must be associated with the Callback object and closed automatically when the connection is closed.
+
+    If the `subscribe` method isn't called from within a connection, it should be considered a global (non connection related) subscription and a `block` or `:handler` **MUST** be provided. 
+    
+    The `subscribe` method must return a subscription object if a subscription was scheduled (not necessarily performed). If it's already known that the subscription would fail, the method should return `nil`.
+
+    The subscription object **MUST** support the method `close` (that will close the subscription).
+
+    The subscription object **MAY** support the method `to_s` (that will return a String representing the stream / channel / pattern).
+
+    The subscription object **MUST** support the method `==(str)` where `str` is a String object (that will return true if the subscription matches the String.
+
+    A global variation for this method (allowing global subscriptions to be created) MUST be defined as `Rack::PubSub.subscribe`.
+
+* `publish(to, message, engine = nil)` (preferably supporting named arguments) where:
+
+    * `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).
+
+    * `message` a String with containing the data to be published.
+
+    * `engine` (optional) routed the publish method to the specified Pub/Sub Engine (see later on). If none is specified, the default engine should be used.
+
+    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) should be defined as `Rack::PubSub.publish`.
+
+Implementations **MUST** implement the following methods:
+
+* `Rack::PubSub.register(engine)` where `engine` is a PubSubEngine object as described in this specification.
+
+    When a pub/sub engine is registered, the implementation **MUST** inform the engine of any existing or future subscriptions.
+
+    The implementation **MUST** call the engine's `subscribe` callback for each existing (and future) subscription.
+
+* `Rack::PubSub.deregister(engine)` where `engine` is a PubSubEngine object as described in this specification.
+
+    Removes an engine from the pub/sub registration. The opposit of 
+
+* `Rack::PubSub.default_engine = 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.
+
+* `Rack::PubSub.default_engine` returns the current default pub/sub engine, where the engine is a PubSubEngine object as described in this specification.
+
+* `Rack::PubSub.reset(engine)` where `engine` is a PubSubEngine object as described in this specification.
+
+    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 `pubsub_default` engine is the server itself or a server's module).
+
+However, servers **MUST** support external pub/sub "engines" as described above, using PubSubEngine objects.
+
+PubSubEngine objects **MUST** implement the following methods:
+
+* `subscribe(channel, as=nil)` this method performs the subscription to the specified channel.
+
+    If `as` 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.
+
+    The method must return `true` if a subscription was scheduled (or performed) or `false` if the subscription is known to fail.
+
+    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.
+
+* `unsubscribe(channel, as=nil)` this method performs closes the subscription to the specified channel.
+
+    The method's semantics are similar to `subscribe`.
+
+    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 object.
+
+    This method will be called by the server when a message is published using the engine.
+
+    The engine **MUST** assume that the method might called directly by an application.
+
+When a PubSubEngine object receives a published message, it should call:
+
+```ruby
+Rack::PubSub.publish channel: channel, message: message, engine: false
+```