Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 174 lines (145 sloc) 7.28 kb
e171fe7 @slact readme improvements
authored
1 NGiNX HTTP push module - Turn NGiNX into an adept HTTP Push (Comet) server.
6404eb2 @slact info
authored
2
e171fe7 @slact readme improvements
authored
3 This module takes care of all the connection juggling, and exposes a simple
4 interface to broadcast messages to clients via plain old HTTP requests.
5 This makes it possible to write live-updating applications without having to
6 wait on idle connections via upstream proxies or making your code all
7 asynchronous and concurrent.
8122991 @slact document it better
authored
8
e171fe7 @slact readme improvements
authored
9 ---------------- Configuration Directives & Variables ------------------------
e3f8b53 @slact readme bettered
authored
10 Variables:
11 $push_channel_id
e171fe7 @slact readme improvements
authored
12 A token uniquely identifying a communication channel. Must be present in the
13 context of the push_subscriber and push_publisher directives.
e3f8b53 @slact readme bettered
authored
14 Example:
e171fe7 @slact readme improvements
authored
15 set $push_channel_id $arg_id;
16 #channel id is now the url query string parameter "id"
17 #(/foo/bar?id=channel_id_string)
e3f8b53 @slact readme bettered
authored
18
19 Directives:
20
21 ==Publisher/Subscriber==
22
23 push_subscriber [ long-poll | interval-poll ]
24 default: long-poll
e7d3ccc @slact good enough
authored
25 context: server, location
e3f8b53 @slact readme bettered
authored
26 Defines a server or location as a subscriber. This location represents a
27 subscriber's interface to a channel's message queue. The queue is traversed
28 automatically via caching information request headers (If-Modified-Since and
e171fe7 @slact readme improvements
authored
29 If-None-Match), beginning with the oldest available message. Requests for
30 upcoming messages are handled in accordance with the setting provided.
31 See the protocol documentation for a detailed description.
8122991 @slact document it better
authored
32
7700e87 @slact pub/sub terminology for readme
authored
33 push_subscriber_concurrency [ last | first | broadcast ]
059ebe0 @slact default subscriber concurrency setting is now "broadcast"
authored
34 default: broadcast
baaa275 @slact concurency setting stuff (not yet, but sort of)
authored
35 context: http, server, location
e171fe7 @slact readme improvements
authored
36 Controls how multiple subscriber requests to a channel (identified by
37 some common ID) are handled.
baaa275 @slact concurency setting stuff (not yet, but sort of)
authored
38 The values work as follows:
e171fe7 @slact readme improvements
authored
39 - broadcast: any number of concurrent subscriber requests may be held.
40 - last: only the most recent subscriber request is kept, all others get
41 a 409 Conflict response.
42 - first: only the oldest subscriber request is kept, all others get a
43 409 Conflict response.
44
45 push_publisher
46 default: none
47 context: server, location
48 Defines a server or location as a message publisher. Requests to a publisher
49 location are treated as messages to be sent to subscribers. See the protocol
50 documentation for a detailed description.
baaa275 @slact concurency setting stuff (not yet, but sort of)
authored
51
e3f8b53 @slact readme bettered
authored
52 == Message storage ==
53
54 push_store_messages [ on | off ]
55 default: on
56 context: http, server, location
57 Whether or not message queuing is enabled. "Off" is equivalent to the setting
58 push_channel_buffer_length 0;
59
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
60 push_max_reserved_memory [ size ]
e3f8b53 @slact readme bettered
authored
61 default: 16M
e7d3ccc @slact good enough
authored
62 context: http
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
63 The size of the memory chunk this module will use for all message queuing
e7d3ccc @slact good enough
authored
64 and buffering.
8122991 @slact document it better
authored
65
2878765 @slact split push_message_buffer_length into push_min_message_buffer_length …
authored
66 push_min_message_buffer_length [ number ]
e3f8b53 @slact readme bettered
authored
67 default: 1
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
68 context: http, server, location
2878765 @slact split push_message_buffer_length into push_min_message_buffer_length …
authored
69 The minimum number of messages to store per channel. A channel's message
e171fe7 @slact readme improvements
authored
70 buffer will retain at least this many most recent messages.
2878765 @slact split push_message_buffer_length into push_min_message_buffer_length …
authored
71
72 push_max_message_buffer_length [ number ]
e3f8b53 @slact readme bettered
authored
73 default: 10
2878765 @slact split push_message_buffer_length into push_min_message_buffer_length …
authored
74 context: http, server, location
5d839d3 @amir Updating README
amir authored
75 The maximum number of messages to store per channel. A channel's message
e171fe7 @slact readme improvements
authored
76 buffer will retain at most this many most recent messages.
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
77
7ed20c1 @slact added push_min_message_recipients option
authored
78 push_min_message_recipients [ number ]
79 default: 0
80 context: http, server, location
e171fe7 @slact readme improvements
authored
81 The number of times a message must be received before it is considered for
e3f8b53 @slact readme bettered
authored
82 deletion. Useful to guarantee message delivery. (This does NOT override the
e171fe7 @slact readme improvements
authored
83 push_max_message_buffer_length setting).
7ed20c1 @slact added push_min_message_recipients option
authored
84
85 push_message_timeout [ time ]
86 default: 1h
87 context: http, server, location
e171fe7 @slact readme improvements
authored
88 The length of time a message may be queued before it is considered expired.
89 If you do not want messages to expire, set this to 0. Applicable only if a
90 push_publisher is present in this or a child context.
e3f8b53 @slact readme bettered
authored
91
92 == Security ==
93
b26ed76 @slact push_authorized_channels_only documentation
authored
94 push_authorized_channels_only [ on | off ]
95 default: off
96 context: http, server, location
e3f8b53 @slact readme bettered
authored
97 Whether or not a subscriber may create a channel by making a request to a
e171fe7 @slact readme improvements
authored
98 push_subscriber location. If set to on, a publisher must send a POST or PUT
99 request before a subscriber can request messages on the channel. Otherwise,
100 all subscriber requests to nonexistent channels will get a 403 Forbidden
101 response.
0c4be3e @slact added push_channel_group setting
authored
102
103 push_channel_group [ string ]
104 default: (none)
105 context: server, location
e171fe7 @slact readme improvements
authored
106 Because settings are bound to locations and not individual channels,
0c4be3e @slact added push_channel_group setting
authored
107 it is useful to be able to have channels that can be reached only from some
108 locations and never others. That's where this setting comes in. Think of it
109 as a prefix string for the channel id.
110
0be70b6 @slact added push_max_channel_id_length config option
authored
111 push_max_channel_id_length [ number ]
112 default: 512
113 context: main, server, location
114 Maximum permissible channel id length (number of characters).
115 Longer ids will be truncated.
8122991 @slact document it better
authored
116
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
117 --------------------------- Example Config -----------------------------------
118 http {
119 #maximum amount of memory the push module is allowed to use
120 #for buffering and stuff
02a0e11 @slact updated example slightly
authored
121 push_max_reserved_memory 12M; #default is 3M
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
122
e3f8b53 @slact readme bettered
authored
123 # internal publish endpoint (keep it private / protected)
124 location /publish {
e084077 @carsonbaker Updating README: (1) Fixing name bug in example nginx configuration. …
carsonbaker authored
125 set $push_channel_id $arg_channel; #/?channel=239aff3 or some-such
e3f8b53 @slact readme bettered
authored
126 push_publisher;
127
128 push_message_timeout 2h; # expire buffered messages after 2 hours
129 push_max_message_buffer_length 10; # store absolutely at most 10 messages
130 push_min_message_recipients 0; # minimum recipients before purge
131 }
132
133 # public long-polling endpoint
134 location /activity {
135 push_subscriber;
136
e084077 @carsonbaker Updating README: (1) Fixing name bug in example nginx configuration. …
carsonbaker authored
137 # how multiple subscriber requests to the same channel id are handled
138 # - last: only the most recent subscriber request is kept, 409 for others.
139 # - first: only the oldest subscriber request is kept, 409 for others.
140 # - broadcast: any number of subscriber requests may be long-polling.
141 push_subscriber_concurrency broadcast;
142 set $push_channel_id $arg_channel; #/?channel=239aff3 or some-such
e3f8b53 @slact readme bettered
authored
143 default_type text/plain;
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
144 }
145 }
7700e87 @slact pub/sub terminology for readme
authored
146
e7d3ccc @slact good enough
authored
147 ---------------------------- Operation ---------------------------------------
e171fe7 @slact readme improvements
authored
148 The following describes what is likely to be the most commonly desired setup:
149
150 Assuming the example config given above,
bc71bb7 @carsonbaker Fixing location in explanation of example. @slact, shouldn't line 153
carsonbaker authored
151 Clients will connect to http://example.com/activity?id=... and have the
152 response delayed until a message is POSTed to http://example.com/publish?id=...
e7d3ccc @slact good enough
authored
153 Messages can be sent to clients that have not yet connected, i.e. they are
154 queued.
6404eb2 @slact info
authored
155
e171fe7 @slact readme improvements
authored
156 Upon sending a request to a push_publisher location, the message, contained in
157 the publisher request body, will be sent to the channel identified by
158 $push_channel_id and to all presently connected channel subscribers. If there
159 are no subscribers waiting for a message at the time, the publisher will be
160 sent to with a with a 202 Accepted response. Otherwise, a 201 Created response
161 is sent. Additionally, the body of the publisher response will contain
162 information about the channel (number of current subscribers, message queue
163 length, etc).
97c3e49 @slact elaborate.
authored
164
e171fe7 @slact readme improvements
authored
165 If you intend to have the publisher be a server-side application, it's a damn
166 good idea to make sure the push_publisher location is not publicly accessible.
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
167
e171fe7 @slact readme improvements
authored
168 Traversal through a channel's message buffer by a subscriber requires proper
169 HTTP caching support from the subscriber client. Make sure it correctly sends
170 Last-Modified and Etag headers. (All modern web browsers do this.)
885051f @slact clarified the protocol, added a todo
authored
171
e171fe7 @slact readme improvements
authored
172 ----------------------- Protocol Spec --------------------------------------
173 This module is unconditionally (fully) compliant with the Basic HTTP Push
174 Relay Protocol, Rev. 2.21, found in the file protocol.txt.
Something went wrong with that request. Please try again.