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 and 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 and Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-push-stream
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.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.6.0 released on May 09 2024.
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 ;)
Basic Configuration
# 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 (admin) mode for this location
push_stream_publisher admin;
# query string based channel id
push_stream_channels_path $arg_id;
}
location ~ /sub/(.*) {
# activate subscriber (streaming) mode for this location
push_stream_subscriber;
# positional channel path
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 --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_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
- 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.
Who is using the module?
Do you use this module? Put your name on the list.
Javascript Client
There is a javascript client implementation here, which is framework independent. Try and help improve it. ;)
Directives
(1) Defining locations, (2) Main configuration, (3) Subscribers configuration, (4) Publishers configuration, (5) Channels Statistics configuration, (6) WebSocket configuration
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
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
GitHub
You may find additional configuration tips and documentation for this module in the GitHub repository for nginx-module-push-stream.