push-stream: NGINX push stream module

Installation

You can install this module in any RHEL-based distribution, including, but not limited to:

RedHat Enterprise Linux 7, 8, 9
CentOS 7, 8, 9
AlmaLinux 8, 9
Rocky Linux 8, 9
Amazon Linux 2 and Amazon Linux 2023

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install nginx-module-push-stream

Enable the module by adding the following at the top of /etc/nginx/nginx.conf:

load_module modules/ngx_http_push_stream_module.so;

This document describes nginx-module-push-stream v0.5.5 released on Dec 11 2021.

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.

Available on github at nginx_push_stream_module h1. Changelog Always take a look at CHANGELOG.textile to see what’s new.

h1. Contribute After you try this module and like it, feel free to give something back, and help in the maintenance of the project ;) :donate h1. Status This module is considered production ready. h1. Basic Configuration \<pre> # add the push_stream_shared_memory_size to your http context http { push_stream_shared_memory_size 32M; # define publisher and subscriber endpoints in your server context server { location /channels-stats { # activate channels statistics mode for this location push_stream_channels_statistics; # query string based channel id push_stream_channels_path \$arg_id; } location /pub { # activate publisher mode for this location push_stream_publisher admin; # query string based channel id push_stream_channels_path \$arg_id; } location \~ /sub/ { # activate subscriber mode for this location push_stream_subscriber; # positional channel path push_stream_channels_path \$1; } } } \</pre>

h1. Basic Usage You can feel the flavor right now at the command line. Try using more than one terminal and start playing http pubsub: \<pre> # Subs curl ~~s~~v —no-buffer ‘http://localhost/sub/my_channel_1’ curl ~~s~~v —no-buffer ‘http://localhost/sub/your_channel_1’ curl ~~s~~v —no-buffer ‘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_2’~~d ‘Goodbye!’ # Channels Stats for publisher curl ~~s~~v ‘http://localhost/pub?id=my_channel_1’ # All Channels Stats summarized curl ~~s~~v ‘http://localhost/channels-stats’ # All Channels Stats detailed curl ~~s~~v ‘http://localhost/channels-stats?id=ALL’ # Prefixed Channels Stats detailed 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’ \</pre>

h1. Some Examples ** Curl examples * Forever (hidden) iFrame * Event Source * WebSocket * Long Polling * JSONP * M-JPEG * Other examples

FAQ

Doubts?! Check the FAQ.

Bug report

To report a bug, please provide the following information when applicable

Which push stream module version is been used (commit sha1)?
Which nginx version is been used?
Nginx configuration in use
“nginx ~~V" command outuput # Core dump indicating a failure on the module code. Check here how to produce one. # Step by step description to reproduce the error. h1. Who is using the module? Do you use this module? Put your name on the list.

h1. Javascript Client There is a javascript client implementation here, which is framework independent. Try and help improve it. ;) h1. Directives Defining locations, Main configuration, Subscribers configuration, Publishers configuration, Channels Statistics configuration, WebSocket configuration . | Directive | | | | | | | | push_stream_channels_statistics | x | ~~ | - | - | - | - | |”push_stream_publisher“:push_stream_publisher | x | - | - | - | - | - | |”push_stream_subscriber“:push_stream_subscriber | x | - | - | - | - | - | |”push_stream_shared_memory_size“:push_stream_shared_memory_size | - | x | - | - | - | - | |”push_stream_channel_deleted_message_text“:push_stream_channel_deleted_message_text | - | x | - | - | - | - | |”push_stream_channel_inactivity_time“:push_stream_channel_inactivity_time | - | x | - | - | - | - | |”push_stream_ping_message_text“:push_stream_ping_message_text | - | x | - | - | - | - | |”push_stream_timeout_with_body“:push_stream_timeout_with_body | - | x | - | - | - | - | |”push_stream_message_ttl“:push_stream_message_ttl | - | x | - | - | - | - | |”push_stream_max_subscribers_per_channel“:push_stream_max_subscribers_per_channel | - | x | - | - | - | - | |”push_stream_max_messages_stored_per_channel“:push_stream_max_messages_stored_per_channel | - | x | - | - | - | - | |”push_stream_max_channel_id_length“:push_stream_max_channel_id_length | - | x | - | - | - | - | |”push_stream_max_number_of_channels“:push_stream_max_number_of_channels | - | x | - | - | - | - | |”push_stream_max_number_of_wildcard_channels“:push_stream_max_number_of_wildcard_channels | - | x | - | - | - | - | |”push_stream_wildcard_channel_prefix“:push_stream_wildcard_channel_prefix | - | x | - | - | - | - | |”push_stream_events_channel_id“:push_stream_events_channel_id | - | x | - | - | - | - | |”push_stream_channels_path“:push_stream_channels_path | - | - | x | x | x | x | |”push_stream_store_messages“:push_stream_store_messages | - | - | - | x | - | x | |”push_stream_channel_info_on_publish“:push_stream_channel_info_on_publish | - | - | - | x | - | - | |”push_stream_authorized_channels_only“:push_stream_authorized_channels_only | - | - | x | - | - | x | |”push_stream_header_template_file“:push_stream_header_template_file | - | - | x | - | - | x | |”push_stream_header_template“:push_stream_header_template | - | - | x | - | - | x | |”push_stream_message_template“:push_stream_message_template | - | - | x | - | - | x | |”push_stream_footer_template“:push_stream_footer_template | - | - | x | - | - | x | |”push_stream_wildcard_channel_max_qtd“:push_stream_wildcard_channel_max_qtd | - | - | x | - | - | x | |”push_stream_ping_message_interval“:push_stream_ping_message_interval | - | - | x | - | - | x | |”push_stream_subscriber_connection_ttl“:push_stream_subscriber_connection_ttl | - | - | x | - | - | x | |”push_stream_longpolling_connection_ttl“:push_stream_longpolling_connection_ttl | - | - | x | - | - | - | |”push_stream_websocket_allow_publish“:push_stream_websocket_allow_publish | - | - | - | - | - | x | |”push_stream_last_received_message_time“:push_stream_last_received_message_time | - | - | x | - | - | - | |”push_stream_last_received_message_tag“:push_stream_last_received_message_tag | - | - | x | - | - | - | |”push_stream_last_event_id“:push_stream_last_event_id | - | - | x | - | - | - | |”push_stream_user_agent“:push_stream_user_agent | - | - | x | - | - | - | |”push_stream_padding_by_user_agent“:push_stream_padding_by_user_agent | - | - | x | - | - | - | |”push_stream_allowed_origins“:push_stream_allowed_origins | - | - | x | - | - | - | |”push_stream_allow_connections_to_events_channel“:push_stream_allow_connections_to_events_channel | - | - | x | - | - | x | h1(#installation). Installation \<pre> # clone the project git clone https://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.2.0+) wget http://nginx.org/download/nginx-1.2.0.tar.gz # unpack, configure and build tar xzvf nginx-1.2.0.tar.gz cd nginx-1.2.0 ./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.2.0 # 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 \</pre> h1(#memory-usage). 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 = 270 bytes * subscriber * on shared = 160 bytes * on system = 6550 bytes h1(#tests). Tests The server tests for this module are written in Ruby, and are acceptance tests, click”here“:tests for more details. h1(#discussion). Discussion Nginx Push Stream Module”Discussion Group“:discussion h1(#contributors). Contributors ”People":contributors

[discussion]https://groups.google.com/group/nginxpushstream [donate]https://www.paypal.com/cgi-bin/webscr?cmd=s-xclick&hosted_button_id=4LP6P9A7BC37S http://dev.w3.org/html5/eventsource/ http://dev.w3.org/html5/websockets/ http://en.wikipedia.org/wiki/Comet28programming29 [installation]#installation [examples]#examples [javascript_client]docs/javascript_client.textile#javascript_client [repository]https://github.com/wandenberg/nginx-push-stream-module [contributors]https://github.com/wandenberg/nginx-push-stream-module/contributors [changelog]CHANGELOG.textile [curl]docs/examples/curl.textile#curl [forever_iframe]docs/examples/forever_iframe.textile#forever_iframe [event_source]docs/examples/event_source.textile#event_source [websocket]docs/examples/websocket.textile#websocket [long_polling]docs/examples/long_polling.textile#long_polling [jsonp]docs/examples/long_polling.textile#jsonp [m-jpeg]docs/examples/m_jpeg.textile#m_jpeg [tests]docs/server_tests.textile [push_stream_channels_statistics]docs/directives/channels_statistics.textile#push_stream_channels_statistics [push_stream_publisher]docs/directives/publishers.textile#push_stream_publisher [push_stream_subscriber]docs/directives/subscribers.textile#push_stream_subscriber [push_stream_shared_memory_size]docs/directives/main.textile#push_stream_shared_memory_size [push_stream_channel_deleted_message_text]docs/directives/main.textile#push_stream_channel_deleted_message_text [push_stream_ping_message_text]docs/directives/main.textile#push_stream_ping_message_text [push_stream_channel_inactivity_time]docs/directives/main.textile#push_stream_channel_inactivity_time [push_stream_message_ttl]docs/directives/main.textile#push_stream_message_ttl [push_stream_max_subscribers_per_channel]docs/directives/main.textile#push_stream_max_subscribers_per_channel [push_stream_max_messages_stored_per_channel]docs/directives/main.textile#push_stream_max_messages_stored_per_channel [push_stream_max_channel_id_length]docs/directives/main.textile#push_stream_max_channel_id_length [push_stream_max_number_of_channels]docs/directives/main.textile#push_stream_max_number_of_channels [push_stream_max_number_of_wildcard_channels]docs/directives/main.textile#push_stream_max_number_of_wildcard_channels [push_stream_wildcard_channel_prefix]docs/directives/main.textile#push_stream_wildcard_channel_prefix [push_stream_events_channel_id]docs/directives/main.textile#push_stream_events_channel_id [push_stream_channels_path]docs/directives/subscribers.textile#push_stream_channels_path [push_stream_authorized_channels_only]docs/directives/subscribers.textile#push_stream_authorized_channels_only [push_stream_header_template_file]docs/directives/subscribers.textile#push_stream_header_template_file [push_stream_header_template]docs/directives/subscribers.textile#push_stream_header_template [push_stream_message_template]docs/directives/subscribers.textile#push_stream_message_template [push_stream_footer_template]docs/directives/subscribers.textile#push_stream_footer_template [push_stream_wildcard_channel_max_qtd]docs/directives/subscribers.textile#push_stream_wildcard_channel_max_qtd [push_stream_ping_message_interval]docs/directives/subscribers.textile#push_stream_ping_message_interval [push_stream_subscriber_connection_ttl]docs/directives/subscribers.textile#push_stream_subscriber_connection_ttl [push_stream_longpolling_connection_ttl]docs/directives/subscribers.textile#push_stream_longpolling_connection_ttl [push_stream_timeout_with_body]docs/directives/subscribers.textile#push_stream_timeout_with_body [push_stream_last_received_message_time]docs/directives/subscribers.textile#push_stream_last_received_message_time [push_stream_last_received_message_tag]docs/directives/subscribers.textile#push_stream_last_received_message_tag [push_stream_last_event_id]docs/directives/subscribers.textile#push_stream_last_event_id [push_stream_user_agent]docs/directives/subscribers.textile#push_stream_user_agent [push_stream_padding_by_user_agent]docs/directives/subscribers.textile#push_stream_padding_by_user_agent [push_stream_store_messages]docs/directives/publishers.textile#push_stream_store_messages [push_stream_channel_info_on_publish]docs/directives/publishers.textile#push_stream_channel_info_on_publish [push_stream_allowed_origins]docs/directives/subscribers.textile#push_stream_allowed_origins [push_stream_websocket_allow_publish]docs/directives/subscribers.textile#push_stream_websocket_allow_publish [push_stream_allow_connections_to_events_channel]docs/directives/subscribers.textile#push_stream_allow_connections_to_events_channel [wiki]https://github.com/wandenberg/nginx-push-stream-module/wiki/_pages [nginx_debugging]http://wiki.nginx.org/Debugging

GitHub

You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-push-stream.