Skip to content

HTTPS clone URL

Subversion checkout URL

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