Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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