Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 188 lines (157 sloc) 7.832 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 ]
c111014 @slact set default shm size to 32M
authored
61 default: 32M
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
c75c092 @slact added push_message_buffer_length setting
authored
78 push_message_buffer_length [ number ]
79 default: none
80 context: http, server, location
81 The exact number of messages to store per channel. Sets both
82 push_max_message_buffer_length and push_min_message_buffer_length to this
83 value.
84
7a0394b @slact changed min_messaged_recipients to a more useful push_delete_oldest_r…
authored
85 push_delete_oldest_received_message [ on | off ]
86 default: off
7ed20c1 @slact added push_min_message_recipients option
authored
87 context: http, server, location
7a0394b @slact changed min_messaged_recipients to a more useful push_delete_oldest_r…
authored
88 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
89 been received by a subscriber, it is deleted -- provided there are more than
90 push_min_message_buffer_length messages in the channel's message buffer.
91 Recommend avoiding this directive as it violates subscribers' assumptions of
92 GET request idempotence.
7ed20c1 @slact added push_min_message_recipients option
authored
93
94 push_message_timeout [ time ]
95 default: 1h
96 context: http, server, location
e171fe7 @slact readme improvements
authored
97 The length of time a message may be queued before it is considered expired.
98 If you do not want messages to expire, set this to 0. Applicable only if a
99 push_publisher is present in this or a child context.
e3f8b53 @slact readme bettered
authored
100
101 == Security ==
102
b26ed76 @slact push_authorized_channels_only documentation
authored
103 push_authorized_channels_only [ on | off ]
104 default: off
105 context: http, server, location
e3f8b53 @slact readme bettered
authored
106 Whether or not a subscriber may create a channel by making a request to a
e171fe7 @slact readme improvements
authored
107 push_subscriber location. If set to on, a publisher must send a POST or PUT
108 request before a subscriber can request messages on the channel. Otherwise,
109 all subscriber requests to nonexistent channels will get a 403 Forbidden
110 response.
0c4be3e @slact added push_channel_group setting
authored
111
112 push_channel_group [ string ]
113 default: (none)
114 context: server, location
e171fe7 @slact readme improvements
authored
115 Because settings are bound to locations and not individual channels,
0c4be3e @slact added push_channel_group setting
authored
116 it is useful to be able to have channels that can be reached only from some
117 locations and never others. That's where this setting comes in. Think of it
118 as a prefix string for the channel id.
119
0be70b6 @slact added push_max_channel_id_length config option
authored
120 push_max_channel_id_length [ number ]
121 default: 512
122 context: main, server, location
123 Maximum permissible channel id length (number of characters).
124 Longer ids will be truncated.
8122991 @slact document it better
authored
125
70d17c2 @slact push_max_channel_subscribers readme stuff
authored
126 push_max_channel_subscribers [ number ]
127 default: 0 (unlimited)
128 context: main, server, location
129 Maximum concurrent subscribers. Pretty self-explanatory.
130
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
131 --------------------------- Example Config -----------------------------------
132 http {
133 #maximum amount of memory the push module is allowed to use
134 #for buffering and stuff
02a0e11 @slact updated example slightly
authored
135 push_max_reserved_memory 12M; #default is 3M
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
136
e3f8b53 @slact readme bettered
authored
137 # internal publish endpoint (keep it private / protected)
138 location /publish {
e084077 @carsonbaker Updating README: (1) Fixing name bug in example nginx configuration. …
carsonbaker authored
139 set $push_channel_id $arg_channel; #/?channel=239aff3 or some-such
e3f8b53 @slact readme bettered
authored
140 push_publisher;
141
142 push_message_timeout 2h; # expire buffered messages after 2 hours
143 push_max_message_buffer_length 10; # store absolutely at most 10 messages
144 push_min_message_recipients 0; # minimum recipients before purge
145 }
146
147 # public long-polling endpoint
148 location /activity {
149 push_subscriber;
150
e084077 @carsonbaker Updating README: (1) Fixing name bug in example nginx configuration. …
carsonbaker authored
151 # how multiple subscriber requests to the same channel id are handled
152 # - last: only the most recent subscriber request is kept, 409 for others.
153 # - first: only the oldest subscriber request is kept, 409 for others.
154 # - broadcast: any number of subscriber requests may be long-polling.
155 push_subscriber_concurrency broadcast;
156 set $push_channel_id $arg_channel; #/?channel=239aff3 or some-such
e3f8b53 @slact readme bettered
authored
157 default_type text/plain;
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
158 }
159 }
7700e87 @slact pub/sub terminology for readme
authored
160
e7d3ccc @slact good enough
authored
161 ---------------------------- Operation ---------------------------------------
e171fe7 @slact readme improvements
authored
162 The following describes what is likely to be the most commonly desired setup:
163
164 Assuming the example config given above,
bc71bb7 @carsonbaker Fixing location in explanation of example. @slact, shouldn't line 153
carsonbaker authored
165 Clients will connect to http://example.com/activity?id=... and have the
166 response delayed until a message is POSTed to http://example.com/publish?id=...
e7d3ccc @slact good enough
authored
167 Messages can be sent to clients that have not yet connected, i.e. they are
168 queued.
6404eb2 @slact info
authored
169
e171fe7 @slact readme improvements
authored
170 Upon sending a request to a push_publisher location, the message, contained in
171 the publisher request body, will be sent to the channel identified by
172 $push_channel_id and to all presently connected channel subscribers. If there
173 are no subscribers waiting for a message at the time, the publisher will be
174 sent to with a with a 202 Accepted response. Otherwise, a 201 Created response
175 is sent. Additionally, the body of the publisher response will contain
176 information about the channel (number of current subscribers, message queue
177 length, etc).
97c3e49 @slact elaborate.
authored
178
e171fe7 @slact readme improvements
authored
179 If you intend to have the publisher be a server-side application, it's a damn
180 good idea to make sure the push_publisher location is not publicly accessible.
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
181
e171fe7 @slact readme improvements
authored
182 Traversal through a channel's message buffer by a subscriber requires proper
183 HTTP caching support from the subscriber client. Make sure it correctly sends
184 Last-Modified and Etag headers. (All modern web browsers do this.)
885051f @slact clarified the protocol, added a todo
authored
185
e171fe7 @slact readme improvements
authored
186 ----------------------- Protocol Spec --------------------------------------
187 This module is unconditionally (fully) compliant with the Basic HTTP Push
188 Relay Protocol, Rev. 2.21, found in the file protocol.txt.
Something went wrong with that request. Please try again.