Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

151 lines (127 sloc) 5.517 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
location.
---------------- Configuration directives & variables ------------------------
directives:
push_sender
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.
push_listener
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
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_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
Variables:
$push_channel_id
A token uniquely identifying a channel. Must be present in the context of
the push_listener and push_sender directives.
Example:
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_buffer_size 12M; #default is 3M
#sender
server {
listen localhost:8089;
location / {
default_type text/plain;
set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
push_sender;
push_message_timeout 2h; #buffered messages expire after 2 hours
push_message_buffer_length 10; #store 10 messages.
}
}
#receiver
server {
listen 8088;
location / {
default_type text/plain;
set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
push_listener;
}
}
}
---------------------------- Operation ---------------------------------------
Assuming the example config given above:
Clients will connect to http://example.com:8088/?id=... 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
queued.
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
request.
Jump to Line
Something went wrong with that request. Please try again.