Nginx Push Stream Module
A pure stream http push technology for your Nginx setup.
Comet made easy and really scalable.
Supports EventSource, WebSocket, Long Polling, and Forever Iframe. See some examples bellow.
This module is not distributed with the Nginx source. See the installation instructions.
Available on github at nginx_push_stream_module
Changelog
Always take a look at CHANGELOG.textile to see what’s new.
Contribute
After you try this module and like it, feel free to give something back, and help in the maintenance of the project ;)
Status
This module is considered production ready.
Basic Configuration
location /channels-stats { # activate channels statistics mode for this location push_stream_channels_statistics; # query string based channel id set $push_stream_channel_id $arg_id; } 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; }
Basic Usage
You can feel the flavor right now at the command line. Try using more than
one terminal and start playing http pubsub:
# Subs curl -s -v 'http://localhost/sub/my_channel_1' curl -s -v 'http://localhost/sub/your_channel_1' curl -s -v 'http://localhost/sub/your_channel_2' # Pubs curl -s -v -X POST 'http://localhost/pub?id=my_channel_1' -d 'Hello World!' curl -s -v -X POST 'http://localhost/pub?id=your_channel_1' -d 'Hi everybody!' curl -s -v -X POST 'http://localhost/pub?id=your_channel_2' -d 'Goodbye!' # Channels Stats for publisher (json format) curl -s -v 'http://localhost/pub?id=my_channel_1' # All Channels Stats summarized (json format) curl -s -v 'http://localhost/channels-stats' # All Channels Stats detailed (json format) curl -s -v 'http://localhost/channels-stats?id=ALL' # Prefixed Channels Stats detailed (json format) curl -s -v 'http://localhost/channels-stats?id=your_channel_*' # Channels Stats (json format) curl -s -v 'http://localhost/channels-stats?id=my_channel_1' # Delete Channels curl -s -v -X DELETE 'http://localhost/pub?id=my_channel_1'
Some Examples
Variables
Directives
(1) Defining locations, (2) Main configuration, (3) Subscribers configuration, (4) Publishers configuration, (5) Channels Statistics configuration, (6) WebSocket configuration
Installation
You may use build.sh
script inside the project:
# clone the project git clone http://github.com/wandenberg/nginx-push-stream-module.git NGINX_PUSH_STREAM_MODULE_PATH=$PWD/nginx-push-stream-module cd nginx-push-stream-module # build with 1.1.x, 1.0.x, 0.9.x, 0.8.x series ./build.sh master 1.1.15 cd build/nginx-1.1.15 # install and finish sudo make install # check sudo /usr/local/nginx/sbin/nginx -v nginx version: nginx/1.1.15 # test configuration sudo /usr/local/nginx/sbin/nginx -c $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf -t the configuration file $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf syntax is ok configuration file $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf test is successful # run sudo /usr/local/nginx/sbin/nginx -c $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf
Or you may do by yourself:
# clone the project git clone http://github.com/wandenberg/nginx-push-stream-module.git NGINX_PUSH_STREAM_MODULE_PATH=$PWD/nginx-push-stream-module # get desired nginx version (works with 1.1.x, 1.0.x, 0.9.x, 0.8.x series) wget http://nginx.org/download/nginx-1.1.15.tar.gz # unpack, configure and build tar xzvf nginx-1.1.15.tar.gz cd nginx-1.1.15 ./configure --add-module=../nginx-push-stream-module make # install and finish sudo make install # check sudo /usr/local/nginx/sbin/nginx -v nginx version: nginx/1.1.15 # test configuration sudo /usr/local/nginx/sbin/nginx -c $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf -t the configuration file $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf syntax is ok configuration file $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf test is successful # run sudo /usr/local/nginx/sbin/nginx -c $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf
Attention
This module controls everything needed to send the messages to subscribers.
So it disable Nginx’s chuncked filter to reduce memory consumption in streaming connections.
Memory usage
Just as information is listed below the minimum amount of memory used for each object:
- message on shared = 200 bytes
- channel on shared = 536 bytes
- subscriber
- on shared = 230 bytes
- on system = 7100 bytes
Tests
The server tests for this module are written in Ruby, and are acceptance tests, click here for more details.
Discussion
Nginx Push Stream Module Discussion Group