documentation review

.gitignore

@@ -5,6 +5,9 @@ build/
 test/.bundle/
 test/tmp/
 misc/*.textile*
+misc/CHANGELOG.html
+misc/README.html
+misc/docs
 *.o
 misc/tools/publisher
 misc/tools/subscriber

CHANGELOG.textile

+h1(#changelog). Changelog
 
 * Adding event type feature to Event Source support
 * Adding tag and time available at message template, and make possible pass these values whithout set headers
@@ -8,7 +9,7 @@
 * Fixing memory leak in javascript
 * Fixing read messages in high throughput using keepalive on
 
-h3. Version 0.3.2
+h2. Version 0.3.2
 
 * Adding WebSocket support
 * Adding a default header template for EventSource to call _onopen_ callback quickly
@@ -18,7 +19,7 @@ h3. Version 0.3.2
 * Improvement on delete channel removing unnecessary loop
 * Fixing bug on delete channel with long polling subscribers
 
-h3. Version 0.3.1
+h2. Version 0.3.1
 
 * Adding _push_stream_longpolling_connection_ttl_ directive to be possible use different values for timeout of stream and long polling subscribers on the same location
 * Adding _push_stream_max_subscribers_per_channel_ directive to limit the number of subscribers per channel

docs/directives/channels_statistics.textile

+h1(#channels_statistic). Channel Statistics Configuration
+
+h2(#push_stream_channels_statistics). push_stream_channels_statistics <a name="push_stream_channels_statistics" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_channels_statistics_
+
+*context:* _location_
+
+*release version:* _0.2.0_
+
+Defines a location as a source of statistics. You can use this location to get statistics about a specific, group or all channels, in a resumed ou summarized way.
+To get statistics about all channels in a summarized way you have to make a GET in this location without specify a name in the push_stream_channel_id variable.
+To get statistics about all channels in a detailed way you have to specify "ALL" in the push_stream_channel_id.
+To get statistics about prefixed channels in a detailed way you have to specify "_prefix_*" in the push_stream_channel_id.
+To get statistics about a channel you have to specify the name in the push_stream_channel_id.
+
+You can get statistics in the formats plain, xml, yaml and json. The default is json, to change this behavior you can use *Accept* header parameter passing values like "text/plain", "application/xml", "application/yaml" and "application/json" respectivelly.
+
+<pre>
+  location /channels-stats {
+      push_stream_channels_statistics;
+      set $push_stream_channel_id             $arg_id;
+  }
+
+  # /channels-stats -> get statistics about all channels in a summarized way
+  # /channels-stats?id=ALL -> get statistics about all channels in a detailed way
+  # /channels-stats?id=channel_* -> get statistics about all channels which starts with 'channel_'
+  # /channels-stats?id=channel_id -> get statistics about a channel
+</pre>

docs/directives/main.textile

+h1(#main_configuration). Main Configuration
+
+h2(#push_stream_shared_memory_size). push_stream_shared_memory_size <a name="push_stream_shared_memory_size" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_shared_memory_size size_
+
+*default:* _32M_
+
+*context:* _http_
+
+The size of the memory chunk this module will use to store published messages, channels and other shared structures.
+When this memory is full any new request for publish a message or subscribe a channel will receive an 500 Internal Server Error response.
+
+
+h2(#push_stream_shared_memory_cleanup_objects_ttl). push_stream_shared_memory_cleanup_objects_ttl <a name="push_stream_shared_memory_cleanup_objects_ttl" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_shared_memory_cleanup_objects_ttl time_
+
+*default:* _30 seconds_
+
+*context:* _http_
+
+The length of time a message or a channel will stay on garbage collection area before it is completly discarded, freeing the shared memory. The minimum length is 30 seconds to ensure that no one is using these elements.
+This operation is very important to help Nginx recycle memory consumed to create messages and channels, so do not use a large time.
+
+
+h2(#push_stream_channel_deleted_message_text). push_stream_channel_deleted_message_text <a name="push_stream_channel_deleted_message_text" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_channel_deleted_message_text string_
+
+*default:* _Channel deleted_
+
+*context:* _http_
+
+*release version:* _0.2.5_
+
+The string used on channel deleted message sent to subscribers when the channel is deleted by a publisher.
+
+
+h2(#push_stream_ping_message_text). push_stream_ping_message_text <a name="push_stream_ping_message_text" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_ping_message_text string_
+
+*default:* _none_
+
+*context:* _http_
+
+*release version:* _0.2.5_
+
+The string used on ping message sent to subscribers.
+
+
+h2(#push_stream_message_ttl). push_stream_message_ttl <a name="push_stream_message_ttl" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_message_ttl time_
+
+*default:* _none_
+
+*context:* _http_
+
+The length of time a message may be queued before it is considered expired. If you do not want messages to expire, just not set this directive.
+
+
+h2(#push_stream_max_subscribers_per_channel). push_stream_max_subscribers_per_channel <a name="push_stream_max_subscribers_per_channel" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_max_subscribers_per_channel number_
+
+*default:* _none_
+
+*context:* _http_
+
+*release version:* _0.3.1_
+
+The maximum number of subscribers accepted per channel. If you do not want to limit number of subscribers access to channels, just not set this directive.
+
+
+h2(#push_stream_max_messages_stored_per_channel). push_stream_max_messages_stored_per_channel <a name="push_stream_max_messages_stored_per_channel" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_max_messages_stored_per_channel number_
+
+*default:* _none_
+
+*context:* _http_
+
+The maximum number of messages to store per channel. A channel's message buffer will retain at most this many most recent messages. If you do not want messages to be discarded by length, just not set this directive.
+
+
+h2(#push_stream_max_channel_id_length). push_stream_max_channel_id_length <a name="push_stream_max_channel_id_length" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_max_channel_id_length number_
+
+*default:* _none_
+
+*context:* _http_
+
+Maximum permissible channel id length (number of characters). Longer ids will receive an 400 Bad Request response. If you do not want to limit channel id length, just not set this directive.
+
+
+h2(#push_stream_max_number_of_channels). push_stream_max_number_of_channels <a name="push_stream_max_number_of_channels" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_max_number_of_channels number_
+
+*default:* _none_
+
+*context:* _http_
+
+The maximum number of concurrent channels on the server. If you do not want to limit the number of channels, just not set this directive.
+
+
+h2(#push_stream_max_number_of_broadcast_channels). push_stream_max_number_of_broadcast_channels <a name="push_stream_max_number_of_broadcast_channels" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_max_number_of_broadcast_channels number_
+
+*default:* _none_
+
+*context:* _http_
+
+The maximum number of concurrent broadcats channels on the server. If you do not want to limit the number of broadcast channels, just not set this directive.
+
+
+h2(#push_stream_broadcast_channel_prefix). push_stream_broadcast_channel_prefix <a name="push_stream_broadcast_channel_prefix" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_broadcast_channel_prefix string_
+
+*default:* _none_
+
+*context:* _http_
+
+The string prefix used to identify when a channel is a normal or broadcast channel, example: when you set this directive as "bd_", "bd_ch1" will be a broadcast channel

docs/directives/publishers.textile

+h1(#publishers_configuration). Publishers Configuration
+
+h2(#push_stream_publisher). push_stream_publisher <a name="push_stream_publisher" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_publisher [normal | admin]_
+
+*default:* _normal_
+
+*context:* _location_
+
+Defines a location as a message publisher. Requests to a publisher location are treated as messages to be sent to subscribers.
+This location supports three http methods:
+GET, make possible to get statistics about the channel
+POST, publish a message to the channel
+DELETE, remove any existent stored messages, disconnect any subscriber, and delete the channel. Available only if _admin_ value is used in this directive.
+
+<pre>
+  # normal publisher location
+  location /pub {
+      push_stream_publisher;
+      set $push_stream_channel_id             $arg_id;
+  }
+
+  # GET    /pub?id=channel_id -> get statistics about a channel
+  # POST   /pub?id=channel_id -> publish a message to the channel
+
+  # admin publisher location
+  location /pub_admin {
+      push_stream_publisher                   admin;
+      set $push_stream_channel_id             $arg_id;
+  }
+
+  # GET    /pub_admin?id=channel_id -> get statistics about a channel
+  # POST   /pub_admin?id=channel_id -> publish a message to the channel
+  # DELETE /pub_admin?id=channel_id -> delete the channel
+</pre>
+
+h2(#push_stream_store_messages). push_stream_store_messages <a name="push_stream_store_messages" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_store_messages on | off_
+
+*default:* _off_
+
+*context:* _location (push_stream_publisher)_
+
+Whether or not message queuing is enabled.
+If store messages is "on" is needed to set at least one of these two directives push_stream_message_ttl or push_stream_max_messages_stored_per_channel.
+
+h2(#push_stream_keepalive). push_stream_keepalive <a name="push_stream_keepalive" href="#">&nbsp;</a>
+
+*syntax:* _push_stream_keepalive on | off_
+
+*default:* _off_
+
+*context:* _location (push_stream_publisher, push_stream_channels_statistics)_
+
+*release version:* _0.2.4_
+
+Enable keepalive connections, on publisher or channels statistics locations.

docs/examples/event_source.textile

+h1(#event_source). Event Source <a name="event_source" href="#">&nbsp;</a>
+
+Using EventSource to receive the messages.
+*This example uses the PushStream class present in _misc/js/pushstream.js_ file, copy it to your server htdocs.*
+
+Configure your server like suggested bellow. You should complete this configuration with other directives according with target application.
+Create a html page with the content on **Client** part, access it from browser and try with the command *curl http://localhost/pub?id=ch1 -d =="Some Text"==* .
+
+*Server:*
+
+<pre>
+    location /pub {
+        # activate publisher (admin) mode for this location
+        push_stream_publisher admin;
+
+        # query string based channel id
+        set $push_stream_channel_id             $arg_id;
+    }
+
+    location ~ /ev/(.*) {
+        # activate subscriber mode for this location
+        push_stream_subscriber;
+
+        # activate event source support for this location
+        push_stream_eventsource_support on;
+
+        # positional channel path
+        set $push_stream_channels_path              $1;
+        # message template
+        push_stream_message_template                "'{\"id\":~id~,\"channel\":\"~channel~\",\"text\":\"~text~\"}'";
+
+        # ping frequency
+        push_stream_ping_message_interval           10s;
+    }
+</pre>
+
+*Client:*
+
+<pre>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+    <title>Event Source Example</title>
+</head>
+<body>
+    <p>Messages:</p>
+    <div id="messages" style="width:800px;height:300px;overflow:scroll;"></div>
+
+    <script src="/js/pushstream.js" type="text/javascript" language="javascript" charset="utf-8"></script>
+    <script type="text/javascript" language="javascript" charset="utf-8">
+    // <![CDATA[
+    function messageReceived(text, id, channel) {
+      document.getElementById('messages').innerHTML += id + ': ' + text + '<br>';
+    };
+
+    var pushstream = new PushStream({
+      host: window.location.hostname,
+      port: window.location.port,
+      modes: "eventsource"
+    });
+    pushstream.onmessage = messageReceived;
+    pushstream.addChannel('ch1');
+    pushstream.connect();
+    // ]]>
+    </script>
+</body>
+</html>
+</pre>
+
+h2(#using_channels_by_argument). Using Channels by argument
+
+By default pushstream.js send the desired channels to the server as part of the url.
+If needed you can change this behavior changing the javascript usage, like the example bellow, to not set the location as a regular expression.
+
+*Server:*
+
+<pre>
+    location /pub {
+        # activate publisher (admin) mode for this location
+        push_stream_publisher admin;
+
+        # query string based channel id
+        set $push_stream_channel_id             $arg_id;
+    }
+
+    location /ev {
+        # activate subscriber mode for this location
+        push_stream_subscriber;
+
+        # activate event source support for this location
+        push_stream_eventsource_support on;
+
+        # positional channel path
+        set $push_stream_channels_path              $arg_channels;
+        # message template
+        push_stream_message_template                "'{\"id\":~id~,\"channel\":\"~channel~\",\"text\":\"~text~\"}'";
+
+        # ping frequency
+        push_stream_ping_message_interval           10s;
+    }
+</pre>
+
+*Client:*
+
+<pre>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+    <title>Event Source Example</title>
+</head>
+<body>
+    <p>Messages:</p>
+    <div id="messages" style="width:800px;height:300px;overflow:scroll;"></div>
+
+    <script src="/js/pushstream.js" type="text/javascript" language="javascript" charset="utf-8"></script>
+    <script type="text/javascript" language="javascript" charset="utf-8">
+    // <![CDATA[
+    function messageReceived(text, id, channel) {
+      document.getElementById('messages').innerHTML += id + ': ' + text + '<br>';
+    };
+
+    var pushstream = new PushStream({
+      host: window.location.hostname,
+      port: window.location.port,
+      modes: "eventsource",
+      channelsByArgument: true,
+      channelsArgument: 'channels' //this is the default value, you have to change it to be the same value used on push_stream_channels_path variable
+    });
+    pushstream.onmessage = messageReceived;
+    pushstream.addChannel('ch1');
+    pushstream.connect();
+    // ]]>
+    </script>
+</body>
+</html>
+</pre>
+
+*Observations:*
+
+* _push_stream_message_template_ should be exactly like as the example to be used with PushStream class
+* WebSocket, EventSource and Forever iFrame may be combined setting _/ws_, _/sub_ and _/ev_ locations on same server and setting *modes: "websocket|eventsource|stream"* on client. With that if the browser supports Websocket or Event Source, it will use it, if not it will use iFrame, following the order on _modes_ attribute.

docs/examples/forever_iframe.textile

+h1(#forever_iframe). Forever Iframe <a name="forever_iframe" href="#">&nbsp;</a>
+
+Using an invisible iFrame on the page to receive the messages and pass them to main page.
+*This example uses the PushStream class present in _misc/js/pushstream.js_ file, copy it to your server htdocs.*
+
+Configure your server like suggested bellow. You should complete this configuration with other directives according with target application.
+Create a html page with the content on **Client** part, access it from browser and try with the command *curl http://localhost/pub?id=ch1 -d =="Some Text"==* .
+
+*Server:*
+
+<pre>
+    location /pub {
+        # activate publisher (admin) mode for this location
+        push_stream_publisher admin;
+
+        # query string based channel id
+        set $push_stream_channel_id             $arg_id;
+    }
+
+    location ~ /sub/(.*) {
+        # activate subscriber (streaming) mode for this location
+        push_stream_subscriber;
+
+        # positional channel path
+        set $push_stream_channels_path              $1;
+
+        # header to be sent when receiving new subscriber connection
+        push_stream_header_template                 "<html><head><meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta http-equiv=\"Cache-Control\" content=\"no-store\">\r\n<meta http-equiv=\"Cache-Control\" content=\"no-cache\">\r\n<meta http-equiv=\"Pragma\" content=\"no-cache\">\r\n<meta http-equiv=\"Expires\" content=\"Thu, 1 Jan 1970 00:00:00 GMT\">\r\n<script type=\"text/javascript\">\r\nwindow.onError = null;\r\ntry{ document.domain = (window.location.hostname.match(/^(\d{1,3}\.){3}\d{1,3}$/)) ? window.location.hostname : window.location.hostname.split('.').slice(-2).join('.');}catch(e){}\r\nparent.PushStream.register(this);\r\n</script>\r\n</head>\r\n<body>";
+        # message template
+        push_stream_message_template                "<script>p(~id~,'~channel~','~text~');</script>";
+        # footer to be sent when finishing subscriber connection
+        push_stream_footer_template                 "</body></html>";
+        # content-type
+        push_stream_content_type                    "text/html; charset=utf-8";
+        # ping frequency
+        push_stream_ping_message_interval           10s;
+    }
+
+</pre>
+
+*Client:*
+
+<pre>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+    <title>Forever iFrame Example</title>
+</head>
+<body>
+    <p>Messages:</p>
+    <div id="messages" style="width:800px;height:300px;overflow:scroll;"></div>
+
+    <script src="/js/pushstream.js" type="text/javascript" language="javascript" charset="utf-8"></script>
+    <script type="text/javascript" language="javascript" charset="utf-8">
+    // <![CDATA[
+    function messageReceived(text, id, channel) {
+      document.getElementById('messages').innerHTML += id + ': ' + text + '<br>';
+    };
+
+    var pushstream = new PushStream({
+      host: window.location.hostname,
+      port: window.location.port,
+      modes: "stream"
+    });
+    pushstream.onmessage = messageReceived;
+    pushstream.addChannel('ch1');
+    pushstream.connect();
+    // ]]>
+    </script>
+</body>
+</html>
+</pre>
+
+h2(#using_channels_by_argument). Using Channels by argument
+
+By default pushstream.js send the desired channels to the server as part of the url.
+If needed you can change this behavior changing the javascript usage, like the example bellow, to not set the location as a regular expression.
+
+*Server:*
+
+<pre>
+    location /pub {
+        # activate publisher (admin) mode for this location
+        push_stream_publisher admin;
+
+        # query string based channel id
+        set $push_stream_channel_id             $arg_id;
+    }
+
+    location /sub {
+        # activate subscriber (streaming) mode for this location
+        push_stream_subscriber;
+
+        # positional channel path
+        set $push_stream_channels_path              $arg_channels;
+
+        # header to be sent when receiving new subscriber connection
+        push_stream_header_template                 "<html><head><meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta http-equiv=\"Cache-Control\" content=\"no-store\">\r\n<meta http-equiv=\"Cache-Control\" content=\"no-cache\">\r\n<meta http-equiv=\"Pragma\" content=\"no-cache\">\r\n<meta http-equiv=\"Expires\" content=\"Thu, 1 Jan 1970 00:00:00 GMT\">\r\n<script type=\"text/javascript\">\r\nwindow.onError = null;\r\ntry{ document.domain = (window.location.hostname.match(/^(\d{1,3}\.){3}\d{1,3}$/)) ? window.location.hostname : window.location.hostname.split('.').slice(-2).join('.');}catch(e){}\r\nparent.PushStream.register(this);\r\n</script>\r\n</head>\r\n<body>";
+        # message template
+        push_stream_message_template                "<script>p(~id~,'~channel~','~text~');</script>";
+        # footer to be sent when finishing subscriber connection
+        push_stream_footer_template                 "</body></html>";
+        # content-type
+        push_stream_content_type                    "text/html; charset=utf-8";
+        # ping frequency
+        push_stream_ping_message_interval           10s;
+    }
+
+</pre>
+
+*Client:*
+
+<pre>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+    <title>Forever iFrame Example</title>
+</head>
+<body>
+    <p>Messages:</p>
+    <div id="messages" style="width:800px;height:300px;overflow:scroll;"></div>
+
+    <script src="/js/pushstream.js" type="text/javascript" language="javascript" charset="utf-8"></script>
+    <script type="text/javascript" language="javascript" charset="utf-8">
+    // <![CDATA[
+    function messageReceived(text, id, channel) {
+      document.getElementById('messages').innerHTML += id + ': ' + text + '<br>';
+    };
+
+    var pushstream = new PushStream({
+      host: window.location.hostname,
+      port: window.location.port,
+      modes: "stream",
+      channelsByArgument: true,
+      channelsArgument: 'channels' //this is the default value, you have to change it to be the same value used on push_stream_channels_path variable
+    });
+    pushstream.onmessage = messageReceived;
+    pushstream.addChannel('ch1');
+    pushstream.connect();
+    // ]]>
+    </script>
+</body>
+</html>
+</pre>
+
+*Observations:*
+
+* _push_stream_message_template_ should be exactly like as the example to be used with PushStream class
+* WebSocket, EventSource and Forever iFrame may be combined setting _/ws_, _/sub_ and _/ev_ locations on same server and setting *modes: "websocket|eventsource|stream"* on client. With that if the browser supports Websocket or Event Source, it will use it, if not it will use iFrame, following the order on _modes_ attribute.

docs/examples/websocket.textile

+h1(#websocket). WebSocket <a name="websocket" href="#">&nbsp;</a>
+
+Using WebSocket to receive the messages.
+*This example uses the PushStream class present in _misc/js/pushstream.js_ file, copy it to your server htdocs.*
+
+Configure your server like suggested bellow. You should complete this configuration with other directives according with target application.
+Create a html page with the content on **Client** part, access it from browser and try with the command *curl http://localhost/pub?id=ch1 -d =="Some Text"==* .
+
+*Server:*
+
+<pre>
+    location /pub {
+        # activate publisher (admin) mode for this location
+        push_stream_publisher admin;
+
+        # query string based channel id
+        set $push_stream_channel_id             $arg_id;
+    }
+
+    location ~ /ws/(.*) {
+        # activate websocket mode for this location
+        push_stream_websocket;
+
+        # positional channel path
+        set $push_stream_channels_path              $1;
+        # message template
+        push_stream_message_template                "'{\"id\":~id~,\"channel\":\"~channel~\",\"text\":\"~text~\"}'";
+
+        push_stream_websocket_allow_publish         on;
+
+        # ping frequency
+        push_stream_ping_message_interval           10s;
+    }
+</pre>
+
+*Client:*
+
+<pre>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+    <title>WebSocket Example</title>
+</head>
+<body>
+    <p>Messages:</p>
+    <div id="messages" style="width:800px;height:300px;overflow:scroll;"></div>
+
+    <script src="/js/pushstream.js" type="text/javascript" language="javascript" charset="utf-8"></script>
+    <script type="text/javascript" language="javascript" charset="utf-8">
+    // <![CDATA[
+    function messageReceived(text, id, channel) {
+      document.getElementById('messages').innerHTML += id + ': ' + text + '<br>';
+    };
+
+    var pushstream = new PushStream({
+      host: window.location.hostname,
+      port: window.location.port,
+      modes: "websocket"
+    });
+    pushstream.onmessage = messageReceived;
+    pushstream.addChannel('ch1');
+    pushstream.connect();
+    // ]]>
+    </script>
+</body>
+</html>
+</pre>
+
+h2(#using_channels_by_argument). Using Channels by argument
+
+By default pushstream.js send the desired channels to the server as part of the url.
+If needed you can change this behavior changing the javascript usage, like the example bellow, to not set the location as a regular expression.
+
+*Server:*
+
+<pre>
+    location /pub {
+        # activate publisher (admin) mode for this location
+        push_stream_publisher admin;
+
+        # query string based channel id
+        set $push_stream_channel_id             $arg_id;
+    }
+
+    location /ws {
+        # activate websocket mode for this location
+        push_stream_websocket;
+
+        # positional channel path
+        set $push_stream_channels_path              $arg_channels;
+        # message template
+        push_stream_message_template                "'{\"id\":~id~,\"channel\":\"~channel~\",\"text\":\"~text~\"}'";
+
+        push_stream_websocket_allow_publish         on;
+
+        # ping frequency
+        push_stream_ping_message_interval           10s;
+    }
+</pre>
+
+*Client:*
+
+<pre>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+    <title>WebSocket Example</title>
+</head>
+<body>
+    <p>Messages:</p>
+    <div id="messages" style="width:800px;height:300px;overflow:scroll;"></div>
+
+    <script src="/js/pushstream.js" type="text/javascript" language="javascript" charset="utf-8"></script>
+    <script type="text/javascript" language="javascript" charset="utf-8">
+    // <![CDATA[
+    function messageReceived(text, id, channel) {
+      document.getElementById('messages').innerHTML += id + ': ' + text + '<br>';
+    };
+
+    var pushstream = new PushStream({
+      host: window.location.hostname,
+      port: window.location.port,
+      modes: "websocket",
+      channelsByArgument: true,
+      channelsArgument: 'channels' //this is the default value, you have to change it to be the same value used on push_stream_channels_path variable
+    });
+    pushstream.onmessage = messageReceived;
+    pushstream.addChannel('ch1');
+    pushstream.connect();
+    // ]]>
+    </script>
+</body>
+</html>
+</pre>
+
+*Observations:*
+
+* _push_stream_message_template_ should be exactly like as the example to be used with PushStream class
+* WebSocket, EventSource and Forever iFrame may be combined setting _/ws_, _/sub_ and _/ev_ locations on same server and setting *modes: "websocket|eventsource|stream"* on client. With that if the browser supports Websocket or Event Source, it will use it, if not it will use iFrame, following the order on _modes_ attribute.
+

docs/server_tests.textile

+h1(#tests). Tests <a name="tests" href="#">&nbsp;</a>
+
+The tests for this module are written in Ruby, and are acceptance tests.
+To run them is needed to have an environment with:
+
+* Basic requirements
+** ruby >= 1.8.7
+** rubygems >= 1.6.2
+** rake >= 0.8.7
+* Required gems
+** POpen4 >= 0.1.4
+** em-http-request >= 0.2.14
+** json >= 1.4.3
+** ruby-debug >= 0.10.4
+** jasmine >= 1.0.2.1
+** nokogiri >= 1.5.0
+** jshint >= 0.1.1
+
+You can install these gems with bundler (bundler is required to be installed before, _gem install bundler_)
+
+<pre>
+cd test/
+bundle install --without docs
+</pre>
+
+or individually
+
+<pre>
+gem install POpen4 -v 0.1.4
+gem install em-http-request -v 0.2.14
+gem install json -v 1.4.3
+gem install ruby-debug -v 0.10.4
+gem install jasmine -v 1.0.2.1
+gem install nokogiri -v 1.5.0
+gem install jshint -v 0.1.1
+</pre>
+
+Then issue @rake tests@.
+This command run the tests using nginx *executable* located at _/usr/local/nginx/sbin/nginx_ with _1_ *worker* responding at *host* _localhost_ and *port* _9990_.
+To change this behavior use the commands bellow
+
+<pre>
+rake tests executable="../build/nginx-1.1.15/objs/nginx"  # to change default path for nginx executable
+rake tests host=my_machine                                # to change default hostname
+rake tests port=9889                                      # to change default port
+rake tests workers=2                                      # to change dafault number of workers used
+
+and can combine any of these parameters, like:
+
+rake tests port=9889 executable="../build/nginx-1.1.15/objs/nginx"
+</pre>

docs/variables.textile

+h1(#variables). Variables
+
+h2(#push_stream_channel_id). push_stream_channel_id <a name="push_stream_channel_id" href="#">&nbsp;</a>
+
+*values:* _channel id_
+
+*location:* _push_stream_publisher, push_stream_channels_statistics_
+
+A string to uniquely identify a communication channel. Must be present on location of the push_stream_publisher and push_stream_channels_statistics.
+
+<pre>
+set $push_channel_id $arg_id;
+#channel id is now the url query string parameter "id"
+#(/pub?id=channel_id_string or /channels-stats?id=channel_id_string)
+</pre>
+
+
+h2(#push_stream_channels_path). push_stream_channels_path <a name="push_stream_channels_path" href="#">&nbsp;</a>
+
+*values:* _set of channels id and backtrack desired messages_
+
+*location:* _push_stream_subscriber_
+
+A string representing a set of channels id and backtrack desired messages separated by slash, example _/channel1.b3/channel2.b5/channel3.b2_.
+The backtrack means the amount of old messages from each of the channels that will be delivered to the subscriber. On the example will be 3 messages from channel1, 5 from channel2 and 2 from channel3.
+Backtrack isn't needed, you can only sign channels without get old messages, or you can mix things.
+More accepted examples: _/channel1_ , _/channel1/channel2_ , _/channel1.b5/channel2_ , _/channel1/channel2.b6_ , ...
+Must be present on location of the push_stream_subscriber.
+
+<pre>
+location /sub/(.*) {
+  set $push_stream_channels_path $1;
+}
+#channels path is now part of url
+#(/sub/channel_id_string or /sub/channel_id_string.b2/other_channel)
+</pre>

include/ngx_http_push_stream_module_version.h

@@ -27,6 +27,6 @@
 #define NGX_HTTP_PUSH_STREAM_MODULE_VERSION_H_
 
 static const ngx_str_t  NGX_HTTP_PUSH_STREAM_TAG = ngx_string("0.3.2");
-static const ngx_str_t  NGX_HTTP_PUSH_STREAM_COMMIT = ngx_string("a1161e8eacdd207760b46975feed4ae268e3f06f");
+static const ngx_str_t  NGX_HTTP_PUSH_STREAM_COMMIT = ngx_string("01d608aaaa8e724a104b571461b66388d0dd5dc6");
 
 #endif /* NGX_HTTP_PUSH_STREAM_MODULE_VERSION_H_ */

test/Gemfile.lock

@@ -17,7 +17,7 @@ GEM
       eventmachine (>= 0.12.9)
     eventmachine (0.12.10)
     ffi (1.0.9)
-    github-markup (0.5.3)
+    github-markup (0.7.1)
     jasmine (1.0.2.1)
       json_pure (>= 1.4.3)
       rack (>= 1.1)

test/Rakefile

@@ -8,11 +8,13 @@ namespace :docs do
     require 'github/markup'
     template = ERB.new File.read("#{base_dir}/misc/github_template.html.erb")
 
-    Dir.glob("#{base_dir}/*.textile").each do |file|
+    Dir.glob("#{base_dir}/**/*.textile").each do |file|
       filename = File.basename(file)
       content = GitHub::Markup.render(file, File.read(file))
       rendered = template.result(binding)
-      output = "#{base_dir}/misc/#{filename}"
+      output = file.gsub(base_dir, "#{base_dir}/misc").gsub(".textile", ".html")
+      output_dir = File.dirname(output)
+      FileUtils.mkdir_p(output_dir) unless File.exists?(output_dir)
       File.open(output, 'w') {|f| f.write(rendered) }
       puts "Preview rendered to #{output}"
     end
@@ -22,17 +24,19 @@ namespace :docs do
   task :convert_to_wiki do
     require 'redcloth'
     require 'nokogiri'
-    file = "#{base_dir}/README.textile"
-    puts file
-    filename = File.basename(file)
-    readme = File.read(file)
-
-    File.open("#{base_dir}/misc/#{filename}.html", 'w') {|f| f.write(RedCloth.new(readme).to_html) }
+    Dir.glob("#{base_dir}/**/*.textile").each do |file|
+      filename = File.basename(file)
+      content = File.read(file)
 
-    output = "#{base_dir}/misc/#{filename}.wiki"
+      output      = file.gsub(base_dir, "#{base_dir}/misc").gsub(".textile", ".html")
+      output_wiki = file.gsub(base_dir, "#{base_dir}/misc").gsub(".textile", ".wiki")
+      output_dir  = File.dirname(output)
+      FileUtils.mkdir_p(output_dir) unless File.exists?(output_dir)
 
-    File.open(output, 'w') {|f| f.write(convert_to_wiki_syntax(readme)) }
-    puts "Preview rendered to #{output}"
+      File.open(output, 'w') {|f| f.write(RedCloth.new(content).to_html) }
+      File.open(output_wiki, 'w') {|f| f.write(convert_to_wiki_syntax(content)) }
+      puts "Wiki converted to #{output_wiki}"
+    end
   end
 
   def convert_to_wiki_syntax(text)