iodine 0.3.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: efa1a3d3d054e8668d5e7f79bf04e61d5f0b169b
-  data.tar.gz: fe096a9cc9f6e6a1196c3c3091228c6d3a72a539
+  metadata.gz: 9a37969c5d9707236f1d87fcc548a442908d01fd
+  data.tar.gz: 450f40d62e72cf9a575188ecd62509fc1429a771
 SHA512:
-  metadata.gz: 6a6d75ec543937ff9f660cf643b442bd8adc8f4c31deac8d9233570385a6ae38a8743c4f1360b7bf3215401019d254e1fbb31c9dc57a1a197ee3c56aad97a1a6
-  data.tar.gz: 980fa44bbba6a0ad6c43c5f8383482261540a6c602b52a98ad716d7bb51ff7635f8fd58aaeb0bfb60bdcbed74218fa98a9ea8edc3cb2122cb5ed1d88c104098e
+  metadata.gz: 6c3fb1a3627926510480b73a3468940c1e436c15e60c295c508003beeb8997120047a8d483df76e6bfdc0e295eb199e2222c5713c11b33da0ae97ef316e39560
+  data.tar.gz: 67291bdfbcf83e45f03aae739e17ff5b511746ef8e7aa4ba99622ecb5306d1a9c9558cef8867e93fd5469f00c031ed70a64355231f5b0f7baff0f4037c480d4e

data/CHANGELOG.md

@@ -8,6 +8,52 @@ Please notice that this change log contains changes for upcoming releases as wel
 
 ***
 
+#### Change log v.0.4.0
+
+**Braking change**: Some of the API was changed / updated, hopefully simplified.
+
+**DEPRECTAION / Braking change**: The `websocket#write_each` function is gone. Future (planned) support for a Pub/Sub API would have caused confusion and since it's barely used (probably only there as a benchmarking proof of concept) it was removed.
+
+**Update**: Now using `facil.io` v.0.5.0 The extended features include the following listed features.
+
+**Fixes**: This was such a big rewrite, I suspect half the fixes I want to list are things I broke during the rewrite... but there were plenty of fixes.
+
+**Feature**: Iodine now support native Websocket Pub/Sub, with [an example in the `examples` folder](./examples/redis.ru). i.e.:
+
+```ruby
+# Within a Websocket connection:
+subscribe "chat"
+publish "chat", "Iodine is here!"
+```
+
+**Feature**: Iodine's Pub/Sub API supports both direct client messages and server filtered messages. i.e.
+
+```ruby
+# Within a Websocket connection:
+subscribe("chat-server") {|msg| write "Notice: #{msg}" }
+# v.s
+subscribe("chat-client")
+
+publish "chat-server", "Iodine is here!"
+```
+
+**Feature**: Iodine's Pub/Sub API includes support for home made Pub/Sub Engines connecting Iodine to your Pub/Sub service of choice.
+
+**Feature**: Iodine's Pub/Sub support includes a Process Cluster engine (pub/sub to all Websockets sharing the process cluster) as well as a Single Process engine (pub/sub to all websockets supporting a single process).
+
+**Feature**: Iodine's Pub/Sub support includes a native Redis Pub/Sub engine. The parser is written from the ground up in C to keep the Iodine licensing as MIT. It's young, so keep your eyes pealed and submit any issues you encounter.
+
+**Feature + Breaking Change**: Iodine now support multiple HTTP servers at once. i.e.:
+
+```ruby
+# `Iodine::HTTP.listen` initializes an HTTP service in the C and system levels, so it can't be changed once initialized.
+Iodine::HTTP.listen port: 3000, app: my_app1
+Iodine::HTTP.listen port: 3000, app: my_app2, public: "./www"
+Iodine.start
+```
+
+***
+
 #### Change log v.0.3.6
 
 **Update**: Now using `facil.io` v.0.4.3. This fixes some delays in websocket packet flushing (latency), as well as other internal polishes. It also promises some possible future feature extensions that could add a major performance boost.

data/LIMITS.md

@@ -0,0 +1,25 @@
+# Iodine limits and settings
+
+I will, at some point, document these... here's a few things:
+
+## HTTP/1.x limits
+
+* HTTP Headers have a ~16Kb total size limit.
+
+* Uploads are adjustable and limited to ~50Mib by default.
+
+* HTTP keep-alive is adjustable and set to ~5 seconds by default.
+
+## Websocket
+
+* Incoming Websocket message size limits are adjustable and limited to ~250Kib by default.
+
+## Pub/Sub
+
+* Channel names are binary safe, but limited to 1024 characters (even though Redis doesn't seem to limit channel name length).
+
+    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**.
+
+    As a side effect, sequencial channel names have an advantage over random channel names.
+
+* 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).

data/README.md

@@ -6,7 +6,7 @@
 [![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)
 
-Iodine is a fast concurrent web server for real-time Ruby applications, with native support for Websockets, static file service and HTTP/1.1.
+Iodine is a fast concurrent web server for real-time Ruby applications, with native support for Websockets, Pub/Sub, static file service, HTTP/1.1 and Redis Pub/Sub scaling (2 connections per Iodine process).
 
 Iodine also supports custom protocol authoring, making Object Oriented **Network Services** easy to write.
 
@@ -22,52 +22,41 @@ Iodine is an **evented** framework with a simple API that builds off the low lev
 
 Iodine is a C extension for Ruby, developed for Ruby MRI 2.2.2 and up... it should support the whole Ruby 2.0 MRI family, but Rack requires Ruby 2.2.2, and so Iodine matches this requirement.
 
-## Iodine::Rack - an HTTP and Websockets server
+## Iodine::Rack == a fast and powerful HTTP + Websockets server with native Pub/Sub
 
 Iodine includes a light and fast HTTP and Websocket server written in C that was written according to the [Rack interface specifications](http://www.rubydoc.info/github/rack/rack/master/file/SPEC) and the [Websocket draft extension](./SPEC-Websocket-Draft.md).
 
+With `Iodine.listen2http` it's possible to run multiple HTTP applications in addition to (or instead of) the default `Iodine::Rack` HTTP service.
+
+Iodine also supports native process cluster Pub/Sub and a native RedisEngins to easily scale Iodine's Pub/Sub horizontally.
+
 ### Running the web server
 
 Using the Iodine server is easy, simply add Iodine as a gem to your Rack application:
 
 ```ruby
-gem 'iodine', '>=0.3'
+gem 'iodine', '~>0.4'
 ```
 
-Iodine will calculate, when possible, a good enough default concurrency model for fast applications... this might not fit your application if you use database access or other blocking calls.
+Iodine will calculate, when possible, a good enough default concurrency model for lightweight applications... this might not fit your application if you use heavier database access or other blocking calls.
 
 To get the most out of Iodine, consider the amount of CPU cores available and the concurrency level the application requires.
 
-Puma's model of 16 threads and 4 processes is easily adopted and proved to provide a good enough balance for most use-cases. Use:
+The common model of 16 threads and 4 processes can be easily adopted:
 
 ```bash
 bundler exec iodine -p $PORT -t 16 -w 4
 ```
 
-It should be noted that automatic process scaling will cause issues with Websocket broadcast (`each`) support, since the `Websocket#each` method will be limited to the calling process (other clients might be connected to a different process).
-
-It is recommended that you consider using Redis to scale Websocket "events" across processes / machines.  
-Look into [plezi.io](http://www.plezi.io) for automatic Websocket scaling with Redis and Iodine.
-
-### Writing data to the network layer
-
-Iodine allows Ruby to write strings to the network layer. This includes HTTP and Websocket responses.
-
-Iodine will handle an internal buffer (~4 to ~16 Mb, version depending) so that `write` can return immediately (non-blocking).
-
-However, when the buffer is full, `write` will block until enough space in the buffer becomes available. Sending up to 16Kb of data (a single buffer "packet") is optimal. Sending a larger response might effect concurrency. Best Websocket response length is ~1Kb (1 TCP / IP packet) and allows for faster transmissions.
-
-When using the Iodine's web server (`Iodine::Rack`), the static file service offered by Iodine streams files (instead of using the buffer). Every file response will require up to 2 buffer "packets" (~32Kb), one for the header and the other for file streaming.
-
-This means that even a Gigabyte long response will use ~32Kb of memory, as long as it uses the static file service or the `X-Sendfile` extension (Iodine's static file service can be invoked by the Ruby application using the `X-Sendfile` header).
-
 ### Static file serving support
 
-Iodine supports static file serving that allows the server to serve static files directly, with no Ruby layer (all from C-land).
+Iodine supports an internal static file service that bypasses the Ruby layer  and serves static files directly from "C-land".
 
-This means that Iodine won't lock Ruby's GVL when sending static files. The files will be sent directly, allowing for true native concurrency. Since the Ruby layer is unaware of these requests, logging can be performed by turning iodine's logger on.
+This means that Iodine won't lock Ruby's GVL when sending static files. The files will be sent directly, allowing for true native concurrency.
 
-To setup native static file service, setup the public folder's address **before** starting the server.
+Since the Ruby layer is unaware of these requests, logging can be performed by turning iodine's logger on.
+
+To use native static file service, setup the public folder's address **before** starting the server.
 
 This can be done when starting the server from the command line:
 
@@ -133,23 +122,38 @@ To "upgrade" the HTTP request to the Websockets protocol, simply provide Iodine
 
 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.
 
-Here is a simple example we can run in the terminal (`irb`) or easily paste into a `config.ru` file:
+Here is a simple chatroom example we can run in the terminal (`irb`) or easily paste into a `config.ru` file:
 
 ```ruby
 require 'iodine'
 class WebsocketEcho
+  def on_open
+    # Pub/Sub directly to the client (or use a block to process the messages)
+    subscribe channel: :chat
+    # Writing directly to the socket
+    write "You're now in the chatroom."
+  end
   def on_message data
-    write data
+    # Strings and symbol channel names are equivalent.
+    publish channel: "chat", message: data
   end
 end
 Iodine::Rack.app= Proc.new do |env|
   if env['upgrade.websocket?'.freeze] && env["HTTP_UPGRADE".freeze] =~ /websocket/i.freeze
-    env['iodine.websocket'.freeze] = WebsocketEcho # or: WebsocketEcho.new
-    [100,{}, []] # It's possible to set cookies for the response.
+    env['upgrade.websocket'.freeze] = WebsocketEcho # or: WebsocketEcho.new
+    [0,{}, []] # It's possible to set cookies for the response.
   else
     [200, {"Content-Length" => "12"}, ["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 }
+# By default, Pub/Sub performs in process cluster mode.
+Iodine.processes = 4
+# static file serving can be set manually as well as using the command line:
+Iodine::Rack.public = "www/public"
+#
 Iodine.start
 ```
 
@@ -180,49 +184,10 @@ Iodine.start
 
 #### A few notes
 
-This design has a number of benefits, some of them related to better IO handling, resource optimization (no need for two IO polling systems), etc. This also allows us to use middleware without interfering with connection upgrades and provides  backwards compatibility.
+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.
 
-Here's a small HTTP and Websocket broadcast server with Iodine::Rack, which can be used directly from `irb`:
-
-```ruby
-require 'iodine'
-
-# Our server controller and websockets handler
-class My_Broadcast
-
-  # handle HTTP requests (a class callback, emulating a Proc)
-  def self.call env
-    if env["HTTP_UPGRADE".freeze] =~ /websocket/i.freeze
-      env['upgrade.websocket'.freeze] = self.new(env)
-      [0,{}, []]
-    end
-    [200, {"Content-Length" => "12".freeze}, ["Hello World!".freeze]]
-  end
-
-  def initialize env
-    @env = env # allows us to access the HTTP request data during the Websocket session
-  end
-
-  # handles websocket data (an instance  callback)
-  def on_message data
-    # data is the direct buffer and will be recycled once we leave this scope.
-    # we'll copy it to prevent corruption when broadcasting the data asynchronously.
-    data_copy = data.dup
-    # We'll broadcast the data asynchronously to all open websocket connections.
-    each {|ws| ws.write data_copy } # (limited to current process)
-    close if data =~ /^bye[\r\n]/i
-  end
-end
-
-# static file serving is as easy as (also supports simple byte serving):
-Iodine::Rack.public = "www/public"
-
-# start the server while setting the app at the same time
-Iodine::Rack.run My_Broadcast
-```
-
 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
@@ -295,11 +260,13 @@ Then start comparing servers. Here are the settings I used to compare Iodine and
 $ RACK_ENV=production iodine -p 3000 -t 16 -w 4
 # vs.
 $ RACK_ENV=production puma -p 3000 -t 16 -w 4
+# Review the `iodine -?` help for more command line options.
 ```
 
-Iodine performed almost twice as well, (~90K req/sec vs. ~44K req/sec) while keeping a memory foot print that was more then 20% lower (~65Mb vs. ~85Mb).
 
-Review the `iodine -?` help for more data.
+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).
+
+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`, but I have no real proof.
 
 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).
 
@@ -355,21 +322,13 @@ Iodine.start
 
 ```
 
-## I loved Iodine 0.1.x - is this an upgrade?
-
-This is **not** an upgrade, this is a **full rewrite**.
-
-Iodine 0.1.x was written in Ruby and had tons of bells and whistles and a somewhat different API. It also inherited the `IO.select` limit of 1024 concurrent connections.
-
-Iodine 0.2.x is written in C, doesn't have as many bells and whistles (i.e., no Websocket Client) and has a stripped down API (simpler to learn). The connection limit is calculated on startup, according to the system's limits. Connection overflows are terminated with an optional busy message, so the system won't crash.
-
 ## Why not EventMachine?
 
 You can go ahead and use EventMachine if you like. They're doing amazing work on that one and it's been used a lot in Ruby-land... really, tons of good developers and people on that project, I'm sure...
 
 But me, I prefer to make sure my development software runs the exact same code as my production software. So here we are.
 
-Also, I don't really understand all the minute details of EventMachine's API, it kept crashing my system every time I reached ~1024 active connections... I'm sure I just don't know how to use EventMachine, but that's just that.
+Also, I don't really understand all the minute details of EventMachine's API, it kept crashing my system every time I reached 1K-2K active connections... I'm sure I just don't know how to use EventMachine, but that's just that.
 
 Besides, you're here - why not take Iodine out for a spin and see for yourself?
 

data/SPEC-Websocket-Draft.md

@@ -1,8 +1,10 @@
 ### Draft Inactivity Notice
 
-This proposed draft is only implemented by Iodine and hadn't seen external activity in the last four months. It is unlikely that this initiative will grow to become a community convention.
+This proposed draft is only implemented by Iodine and hadn't seen external activity in a while.
 
-I still believe it's important to separate the Websocket server from the Websocket application (much like Rack did for HTTP).n I hope that in the future a community convention for this separation of concerns can be achieved.
+Even though a number of other development teams (such as the teams for the Puma and Passenger server) mentioned that they plan to implements this draft, Iodine seems to be the only server currently implementing this draft and it is unlikely that this initiative will grow to become a community convention.
+
+I still believe it's important to separate the Websocket server from the Websocket API used by application developers and frameworks, much like Rack did for HTTP. I hope that in the future a community convention for this separation of concerns can be achieved.
 
 ---
 ## Rack Websockets
@@ -67,13 +69,13 @@ Server settings **MAY** (not required) be provided to allow for customization an
 
 ## Upgrading
 
-* **Server**: When an upgrade request is received, the server will set the `env['upgrade.websocket?']` flag to `true`, indicating that: 1. this specific request is upgradable; and 2. this server supports specification.
+* **Server**: When an upgrade request is received, the server will set the `env['upgrade.websocket?']` flag to `true`, indicating that: 1. this specific request is upgradable; and 2. this server supports this specification.
 
 * **Client**: When a client decides to upgrade a request, they will place a Websocket Callback Object (either a class or an instance) in the `env['upgrade.websocket']` Hash key.
 
 * **Server**: The server will review the `env` Hash *before* sending the response. If the `env['upgrade.websocket']` was set, the server will perform the upgrade.
 
- * **Server**: The server will send the correct response status and headers, as will as any headers present in the response. The server will also perform any required housekeeping, such as closing the response body, if exists.
+ * **Server**: The server will send the correct response status and headers, as well as any headers present in the response object. The server will also perform any required housekeeping, such as closing the response body, if exists.
 
      The response status provided by the response object shall be ignored and the correct response status shall be set by the server.
 
@@ -88,3 +90,126 @@ Server settings **MAY** (not required) be provided to allow for customization an
     The `on_close` callback will **not** be called while `on_message` or `on_open` callbacks are running.
 
     The `on_ready` callback might be called concurrently with the `on_message` callback, allowing data to be sent even while other data is being processed. Multi-threading considerations may apply.
+
+---
+
+## Iodine's Collection Extension to the Rack Websockets
+
+The biggest benefit from Iodine's Collection Extension is that it allows the creation of pub/sub plugins and other similar extensions that require access to all the connected Websockets - no nee for the plugin to ask "where's the list" or "add this code to `on_open`" or anything at all, truly "plug and play".
+
+This extension should be easy enough to implement using a loop or an array within each process context. These methods do **not** cross process boundaries and they are meant to help implement more advanced features (they aren't a feature as much as an "access point").
+
+Internally, this extension also allows iodine to manage connection memory and resource allocation while relieving developers from rewriting the same workflow of connection storing (`on_open do ALL_WS << self; end `) and management. Knowing that the user doesn't keep Websocket object references, allows Iodine to safely optimize it's memory use.
+
+* `Iodine::Websocket.each` (class method) will run a block of code for each connected Websocket Callback Object **belonging to the current process**. This can be called from outside of a Websocket Callback Object as well.
+
+    ```ruby
+    Iodine::Websocket.each {|ws| ws.write "You're connected to PID #{Process.pid}" }
+    ```
+
+* `Iodine::Websocket.defer(conn_id)` Schedules a block of code to run for the specified connection at a later time, (*if* the connection is open) while preventing concurrent code from running for the same connection object.
+
+    ```ruby
+    Iodine::Websocket.defer(self.conn_id) {|ws| ws.write "still open" }
+    ```
+
+* `#defer` (instance method) Schedules a block of code to run for the specified connection at a later time, (*if* the connection is still open) while preventing concurrent code from running for the same connection object.
+
+    ```ruby
+    defer { write "still open" }
+    ```
+
+* `Iodine::Websocket.count` (instance method) Returns the number of active websocket connections (including connections that are in the process of closing down) **belonging to the current process**.
+
+    ```ruby
+    write "#{Iodine::Websocket.count} clients sharing this process"
+    ```
+
+## Iodine's Pub/Sub Extension to the Rack Websockets
+
+This extension separates the websocket Pub/Sub semantics from the Pub/Sub engine (i.e. Redis, MongoDB, etc') or the Server. If the Collection Extension is implemented, than this isn't necessarily a big step forward (the big step forward is what can be done with is).
+
+I don't personally believe this has a chance of being adopted by other server implementors, but it's a very powerful tool that Iodine supports.
+
+Including these semantics, in the form of the described API, allows servers and Pub/Sub engines to be optimized in different ways without distracting the application (or framework implementor with environmental details.
+
+For example, Iodine includes two default Pub/Sub engines `Iodine::PubSub::Engine::CLUSTER` (the default) and `Iodine::PubSub::Engine::SINGLE_PROCESS` that implement a localized Pub/Sub engine within a process cluster.
+
+ The Websocket module (i.e. `Iodine::Websocket`) includes the following singleton methods:
+
+ * `Iodine::Websocket.default_pubsub=` sets the default Pub/Sub engine.
+
+ * `Iodine::Websocket.default_pubsub` gets the default Pub/Sub engine.
+
+Websocket Callback Objects inherit the following functions:
+
+ * `#subscribe` (instance method) Subscribes to a channel using a specific "engine" (or the default engine). *Returns a subscription object (success) or `nil` (error)*. Doesn't promise actual subscription, only that the subscription request was scheduled to be sent.
+
+    Messages from the subscription are sent directly to the client unless an optional block is provided.
+
+    If an optional block is provided, it should accept the channel and message couplet (i.e. `{|channel, message| } `) and call the websocket `write` manually.
+
+    All subscriptions (including server side subscriptions) MUST be automatically canceled **by the server** when the websocket closes.
+
+ * `#subscription?` (instance method) locates an existing subscription, if any. *Returns a subscription object (success) or `nil` (error)*.
+
+ * `#unsubscribe` (instance method) cancel / stop a subscription. Safely ignores `nil` subscription objects. Returns `nil`. Performance promise is similar to `subscribe` - the event was scheduled.
+
+    Notice: there's no need to call this function during the `on_close` callback, since the server will cancel all subscriptions automatically.
+
+ * `#publish` (instance method) publishes a message to engine's specified channel. Returns `true` on success or `false` on failure (i.e., engine error). Doesn't promise actual publishing, only that the message was scheduled to be published.
+
+For example:
+
+```ruby
+# client side subscription
+s = subscribe(channel: "channel 1") # => subscription ID?
+# client side unsubscribe
+unsubscribe(s)
+
+# client side subscription forcing binary encoding for Websocket protocol.
+subscribe(channel: "channel 1", encoding: :binary) # => subscription ID?
+
+# client side pattern subscription without saving reference
+subscribe(pattern: "channel [0-9]") # => subscription ID?
+# client side unsubscribe
+unsubscribe( subscription?(pattern: "channel [0-9]"))
+
+# server side anonymous block subscription
+s = subscribe(channel: "channel ✨") do |channel, message|
+    puts message
+end
+# server side unsubscribe
+unsubscribe(s)
+
+# server side persistent block subscription without saving reference
+block = proc {|channel, message| puts message }
+subscribe({pattern: "*"}, &block)
+# server side unsubscribe
+unsubscribe subscription?({pattern: "*"}, &block)
+
+# server side anonymous block subscription requires reference...
+subscribe(pattern: "channel 5", force: text) do |channel, message|
+    puts message
+end
+# It's impossible to locate an anonymous block subscriptions!
+subscription? (pattern: "channel 5", force: text) do |channel, message|
+    puts message
+end
+#  => nil # ! can't locate
+
+```
+
+Servers supporting this extension aren't required to implement any Pub/Sub engines, but they MUST implement a **bridge** between the server and Pub/Sub Engines that follows the following semantics:
+
+Engines MUST inherit from a server specific Engine class and implement the following three methods that will be called by the server when required (servers might implement an internal distribution layer and call these functions at their discretion):
+
+* `subscribe(channel, is_pattern)`: Subscribes to the channel. The `is_pattern` flag sets the type of subscription. Returns `true` / `false`.
+
+* `unsubscribe(channel, is_pattern)`: Unsubscribes from the channel. The `is_pattern` flag sets the type of subscription. Returns `true` / `false`.
+
+* `publish(channel, msg, is_pattern)`: Publishes to the channel (or all channels matching the pattern). Returns `true` / `false` (some engines, such as Redis, might not support pattern publishing, they should simply return `false`).
+
+Engines inherit the following message from the server's Engine class and call it when messages were received:
+
+* `distribute(channel, message, is_pattern = nil)`: If `channel` is a channel pattern rather than a channel name, the `is_pattern` should be set to `true` by the Engine. Engines that don't support pattern publishing, can simply ignore this flag.