NGiNX HTTP push module - Turn NGiNX into an adept HTTP Push (Comet) server.
This module takes care of all the connection juggling, and exposes a simple
interface to broadcast messages to clients via plain old HTTP requests.
This makes it possible to write live-updating applications without having to
wait on idle connections via upstream proxies or making your code all
asynchronous and concurrent.
---------------- Configuration Directives & Variables ------------------------
Variables:
$push_channel_id
A token uniquely identifying a communication channel. Must be present in the
context of the push_subscriber and push_publisher directives.
Example:
set $push_channel_id $arg_id;
#channel id is now the url query string parameter "id"
#(/foo/bar?id=channel_id_string)
Directives:
==Publisher/Subscriber==
push_subscriber [ long-poll | interval-poll ]
default: long-poll
context: server, location
Defines a server or location as a subscriber. This location represents a
subscriber's interface to a channel's message queue. The queue is traversed
automatically via caching information request headers (If-Modified-Since and
If-None-Match), beginning with the oldest available message. Requests for
upcoming messages are handled in accordance with the setting provided.
See the protocol documentation for a detailed description.
push_subscriber_concurrency [ last | first | broadcast ]
default: broadcast
context: http, server, location
Controls how multiple subscriber requests to a channel (identified by
some common ID) are handled.
The values work as follows:
- broadcast: any number of concurrent subscriber requests may be held.
- last: only the most recent subscriber request is kept, all others get
a 409 Conflict response.
- first: only the oldest subscriber request is kept, all others get a
409 Conflict response.
push_publisher
default: none
context: server, location
Defines a server or location as a message publisher. Requests to a publisher
location are treated as messages to be sent to subscribers. See the protocol
documentation for a detailed description.
push_jsonp
default: none
context: server, location
Defines a server or location as a JSONP subscriber. This makes a subscriber
take into account a callback parameter usually given by "&callback=", and
convert publisher's posts to JSONP responses by wrapping with it.
== Message storage ==
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_max_reserved_memory [ size ]
default: 32M
context: http
The size of the memory chunk this module will use for all message queuing
and buffering.
push_min_message_buffer_length [ number ]
default: 1
context: http, server, location
The minimum number of messages to store per channel. A channel's message
buffer will retain at least this many most recent messages.
push_max_message_buffer_length [ number ]
default: 10
context: http, server, location
The maximum number of messages to store per channel. A channel's message
buffer will retain at most this many most recent messages.
push_message_buffer_length [ number ]
default: none
context: http, server, location
The exact number of messages to store per channel. Sets both
push_max_message_buffer_length and push_min_message_buffer_length to this
value.
push_delete_oldest_received_message [ on | off ]
default: off
context: http, server, location
When enabled, as soon as the oldest message in a channel's message queue has
been received by a subscriber, it is deleted -- provided there are more than
push_min_message_buffer_length messages in the channel's message buffer.
Recommend avoiding this directive as it violates subscribers' assumptions of
GET request idempotence.
push_message_timeout [ time ]
default: 1h
context: http, server, location
The length of time 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_publisher is present in this or a child context.
push_subscriber_timeout [ time ]
default: 0
context: http, server, location
The length of time a subscriber's long-polling connection can last before
it's timed out. If you don't want subscriber's connection to timeout, set
this to 0. Applicable only if a push_subscriber is present in this or a
child context.
push_channel_timeout [ time ]
default: 0
context: http, server, location
The length of time a channel will be removed after it has no subscriber and
no queued messages. If you want to remove a channel as soon as possible,
set this to 0. Applicable only if a push_publisher or push_subscriber is
present in this or a child context and push_subscriber_timeout is greater
than 0. This value should be greater than push_subscriber_timeout to make
sense.
== Security ==
push_authorized_channels_only [ on | off ]
default: off
context: http, server, location
Whether or not a subscriber may create a channel by making a request to a
push_subscriber location. If set to on, a publisher must send a POST or PUT
request before a subscriber can request messages on the channel. Otherwise,
all subscriber requests to nonexistent channels will get a 403 Forbidden
response.
push_channel_group [ string ]
default: (none)
context: server, location
Because settings are bound to locations and not individual channels,
it is useful to be able to have channels that can be reached only from some
locations and never others. That's where this setting comes in. Think of it
as a prefix string for the channel id.
push_max_channel_id_length [ number ]
default: 512
context: main, server, location
Maximum permissible channel id length (number of characters).
Longer ids will be truncated.
push_max_channel_subscribers [ number ]
default: 0 (unlimited)
context: main, server, location
Maximum concurrent subscribers. Pretty self-explanatory.
--------------------------- 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
# internal publish endpoint (keep it private / protected)
location /publish {
set $push_channel_id $arg_channel; #/?channel=239aff3 or some-such
push_publisher;
push_message_timeout 2h; # expire buffered messages after 2 hours
push_max_message_buffer_length 10; # store absolutely at most 10 messages
push_min_message_recipients 0; # minimum recipients before purge
}
# public long-polling endpoint
location /activity {
push_subscriber;
# how multiple subscriber requests to the same channel id are handled
# - last: only the most recent subscriber request is kept, 409 for others.
# - first: only the oldest subscriber request is kept, 409 for others.
# - broadcast: any number of subscriber requests may be long-polling.
push_subscriber_concurrency broadcast;
set $push_channel_id $arg_channel; #/?channel=239aff3 or some-such
default_type text/plain;
}
# public long-polling JSONP endpoint
location /jsonp {
push_subscriber;
push_subscriber_concurrency broadcast;
set $push_channel_id $arg_channel; #/?channel=239aff3 or some-such
# For cross-domain XHR, you'd need to use JSONP, and you'd not be allowed to
# read/write headers such as "If-Modified-Since" and "If-None-Match".
# In that case, you can pass them via GET parameters along with "callback".
# This endpoint will return something like below.
# e.g.) jsonp12345([{"foo": 1, "bar": 2, "baz": 3},"Wed, 16 Feb 2011 09:02:29 GMT","0"]);
push_jsonp;
set $push_jsonp_callback $arg_callback; #/?callback=jsonp12345
set $push_jsonp_if_modified_since $arg_since; #/?since=Wed,%2016%20Feb%202011%2009:01:06%20GMT
set $push_jsonp_if_none_match $arg_etag; #/?etag=1
default_type text/javascript;
charset utf-8;
}
}
---------------------------- Operation ---------------------------------------
The following describes what is likely to be the most commonly desired setup:
Assuming the example config given above,
Clients will connect to http://example.com/activity?id=... and have the
response delayed until a message is POSTed to http://example.com/publish?id=...
Messages can be sent to clients that have not yet connected, i.e. they are
queued.
Upon sending a request to a push_publisher location, the message, contained in
the publisher request body, will be sent to the channel identified by
$push_channel_id and to all presently connected channel subscribers. If there
are no subscribers waiting for a message at the time, the publisher will be
sent to with a with a 202 Accepted response. Otherwise, a 201 Created response
is sent. Additionally, the body of the publisher response will contain
information about the channel (number of current subscribers, message queue
length, etc).
If you intend to have the publisher be a server-side application, it's a damn
good idea to make sure the push_publisher location is not publicly accessible.
Traversal through a channel's message buffer by a subscriber requires proper
HTTP caching support from the subscriber client. Make sure it correctly sends
Last-Modified and Etag headers. (All modern web browsers do this.)
----------------------- Protocol Spec --------------------------------------
This module is unconditionally (fully) compliant with the Basic HTTP Push
Relay Protocol, Rev. 2.21, found in the file protocol.txt.