Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

148 lines (123 sloc) 5.471 kb
Nginx HTTP push module - Turn nginx into a long-polling message queuing
HTTP push server.
If you want a long-polling server but don't want to wait on idle connections
via upstream proxies or make your applications totally asynchronous, use
this module to have nginx accept and hold long-polling client connections.
Send responses to those clients by sending an HTTP request to a different
---------------- Configuration directives & variables ------------------------
default: none
context: server, location
Defines a server or location as the sender. Requests from a sender will be
treated as messages to send to listeners.See protocol documentation
for more info.
default: none
context: server, location
Defines a server or location as a listener. Requests from a listener will
not be responded to until a message for the listener (identified by
$push_channel_id) becomes available. See protocol documentation for more
push_listener_concurrency [ last | first | broadcast ]
default: last
context: http, server, location
Controls how multiple listener requests to the same channel id are handled.
The values work as follows:
broadcast: any number of listener requests may be long-polling.
last: only the most recent listener request is kept, all others get a 409
Conflict response.
first: only the oldest listener request is kept, all others get a 409
Conflict response.
push_max_reserved_memory [ size ]
default: 3M
context: http
The size of the memory chunk this module will use for all message queuing
and buffering.
push_message_buffer_length [ number ]
default: 5
context: http, server, location
The maximum number of messages to store per channel. Old messages are removed
when a channel's message buffer length exceeds this setting. Set to 0 to
disable buffering.
push_min_message_recipients [ number ]
default: 0
context: http, server, location
How many times a message must be received before it is considered for
deletion. Useful to guarantee message delivery.
push_message_timeout [ time ]
default: 1h
context: http, server, location
How long a message may be queued before it is considered expired. If you do
not want messages to expire, set this to 0. Applicable only if a push_sender
is present in this or a child context.
push_authorized_channels_only [ on | off ]
default: off
context: http, server, location
Whether or not a listener may create a channel. If set to on, a sender must
senda request to some channel (POST or PUT) before a listener. Otherwise,
all listener requests will get a 403 Forbidden response.
push_store_messages [ on | off ]
default: on
context: http, server, location
Whether or not message queuing is enabled. "Off" is equivalent to the setting
push_channel_buffer_length 0;
push_queue_messages [ on | off ] (DEPRECATED)
default: on
context: http, server, location
see push_store_messages
push_buffer_size [ size ] (DEPRECATED)
default: 3M
context: http
see push_max_reserved_memory
A token uniquely identifying a channel. Must be present in the context of
the push_listener and push_sender directives.
set $push_channel_id $arg_id; #channel id is now the url parameter "id"
--------------------------- Example Config -----------------------------------
http {
#maximum amount of memory the push module is allowed to use
#for buffering and stuff
push_max_reserved_memory 12M; #default is 3M
server {
location / {
set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
push_message_timeout 2h; #buffered messages expire after 2 hours
push_message_buffer_length 10; #store 10 messages.
location / {
push_listener_concurrency broadcast;
set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
default_type text/plain;
---------------------------- Operation ---------------------------------------
Assuming the example config given above:
Clients will connect to and have the
response delayed until a message is POSTed to http://localhost:8089/?id=...
Messages can be sent to clients that have not yet connected, i.e. they are
Upon sending a request to a push_sender location, the server will respond with
a 201 Created if the message has been sent. If it must be queued up (i.e. the
push_listener with this id is presently connected), a 202 Accepted will be sent.
If you indend to have the push_sender be a server-side application,
it's a damn good idea to make sure the push_server location is not visible
publically, as it is intended for use only by your application.
Traversal through the message buffer by a listener requires proper caching
support. Make sure your client correctly sends Last-Modified and ETag headers.
----------------------- Protocol spec --------------------------------------
see the file protocol.txt
---------------------------- todo --------------------------------------------
- Add other mechanisms of server pushing. The list should include
"long-poll" (default), "interval-poll".
- When POSTing to a sender location, if Content-Type is "message/http", the
response sent to $push_channel_id should be created from the body of the
Jump to Line
Something went wrong with that request. Please try again.