Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A pure stream http push technology for your Nginx setup. Comet made easy and really scalable.
C Ruby JavaScript HTML Other

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
docs
include
misc
patchs
src
test
.gitignore
AUTHORS
CHANGELOG.textile
COPYING
LICENSE
README.textile
build.sh
config
pack.sh

README.textile

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

Directive (1) (2) (3) (4) (5) (6)
push_stream_channels_statistics   x   -   -   -   -   -
push_stream_publisher   x   -   -   -   -   -
push_stream_subscriber   x   -   -   -   -   -
push_stream_websocket   x   -   -   -   -   -
push_stream_shared_memory_size   -   x   -   -   -   -
push_stream_shared_memory_cleanup_objects_ttl   -   x   -   -   -   -
push_stream_channel_deleted_message_text   -   x   -   -   -   -
push_stream_ping_message_text   -   x   -   -   -   -
push_stream_message_ttl   -   x   -   -   -   -
push_stream_max_subscribers_per_channel   -   x   -   -   -   -
push_stream_max_messages_stored_per_channel   -   x   -   -   -   -
push_stream_max_channel_id_length   -   x   -   -   -   -
push_stream_max_number_of_channels   -   x   -   -   -   -
push_stream_max_number_of_broadcast_channels   -   x   -   -   -   -
push_stream_broadcast_channel_prefix   -   x   -   -   -   -
push_stream_authorized_channels_only   -   -   x   -   -   x
push_stream_header_template   -   -   x   -   -   x
push_stream_message_template   -   -   x   -   -   x
push_stream_footer_template   -   -   x   -   -   x
push_stream_content_type   -   -   x   -   -   -
push_stream_broadcast_channel_max_qtd   -   -   x   -   -   x
push_stream_eventsource_support   -   -   x   -   -   -
push_stream_ping_message_interval   -   -   x   -   -   x
push_stream_subscriber_connection_ttl   -   -   x   -   -   x
push_stream_longpolling_connection_ttl   -   -   x   -   -   -
push_stream_last_received_message_time   -   -   x   -   -   -
push_stream_last_received_message_tag   -   -   x   -   -   -
push_stream_user_agent   -   -   x   -   -   -
push_stream_padding_by_user_agent   -   -   x   -   -   -
push_stream_websocket_allow_publish   -   -   -   -   -   x
push_stream_store_messages   -   -   -   x   -   x
push_stream_keepalive   -   -   -   x   x   -

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

Contributors

People

Something went wrong with that request. Please try again.