Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

138 lines (116 sloc) 5 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_id) becomes available. See protocol documentation for more info.
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_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_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_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
The id associated with a push_listener or push_sender. Must be present next
to said directives.
set $push_id $arg_id #$push_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_buffer_size 12M; #default is 3M
server {
listen localhost:8089;
location / {
default_type text/plain;
set $push_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.
server {
listen 8088;
location / {
default_type text/plain;
set $push_id $arg_id; #/?id=239aff3 or somesuch
---------------------------- 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 push_server, if Content-Type is "message/http", the
response sent to $push_id should be created from the body of the request.
Jump to Line
Something went wrong with that request. Please try again.