Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

151 lines (127 sloc) 5.525 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_max_reserved_memory 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.