Skip to content
This repository
Newer
Older
100644 153 lines (127 sloc) 5.683 kb
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
1 Nginx HTTP push module - Turn nginx into a long-polling message queuing
2 HTTP push server.
6404eb24 »
2009-08-10 info
3
e7d3ccc6 »
2009-08-27 good enough
4 If you want a long-polling server but don't want to wait on idle connections
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
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.
81229917 »
2009-08-25 document it better
9
e7d3ccc6 »
2009-08-27 good enough
10 ---------------- Configuration directives & variables ------------------------
11 directives:
12 push_sender
13 default: none
14 context: server, location
15 Defines a server or location as the sender. Requests from a sender will be
16 treated as messages to send to listeners.See protocol documentation
17 for more info.
18
19 push_listener
20 default: none
21 context: server, location
22 Defines a server or location as a listener. Requests from a listener will
23 not be responded to until a message for the listener (identified by
dca6db82 »
2009-10-08 renamed $push_id to $push_channel_id. still need to find a way to use…
24 $push_channel_id) becomes available. See protocol documentation for more
25 info.
81229917 »
2009-08-25 document it better
26
baaa2755 »
2009-10-08 concurency setting stuff (not yet, but sort of)
27 push_listener_concurrency [ last | first | broadcast ]
28 default: last
29 context: http, server, location
30 Controls how multiple listener requests to the same channel id are handled.
31 The values work as follows:
32 broadcast: any number of listener requests may be long-polling.
33 last: only the most recent listener request is kept, all others get a 409
34 Conflict response.
35 first: only the oldest listener request is kept, all others get a 409
36 Conflict response.
37
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
38 push_max_reserved_memory [ size ]
e7d3ccc6 »
2009-08-27 good enough
39 default: 3M
40 context: http
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
41 The size of the memory chunk this module will use for all message queuing
e7d3ccc6 »
2009-08-27 good enough
42 and buffering.
81229917 »
2009-08-25 document it better
43
28787656 »
2009-10-16 split push_message_buffer_length into push_min_message_buffer_length …
44 push_min_message_buffer_length [ number ]
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
45 default: 5
46 context: http, server, location
28787656 »
2009-10-16 split push_message_buffer_length into push_min_message_buffer_length …
47 The minimum number of messages to store per channel. A channel's message
48 buffer, will cointain at least this many most recent messages.
49
50 push_max_message_buffer_length [ number ]
51 default: 255
52 context: http, server, location
53 The minimum number of messages to store per channel. A channel's message
54 buffer, will cointain at least this many most recent messages.
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
55
7ed20c17 »
2009-10-16 added push_min_message_recipients option
56 push_min_message_recipients [ number ]
57 default: 0
58 context: http, server, location
59 How many times a message must be received before it is considered for
60 deletion. Useful to guarantee message delivery.
61
62 push_message_timeout [ time ]
63 default: 1h
64 context: http, server, location
65 How long a message may be queued before it is considered expired. If you do
66 not want messages to expire, set this to 0. Applicable only if a push_sender
67 is present in this or a child context.
68
b26ed76d »
2009-10-08 push_authorized_channels_only documentation
69 push_authorized_channels_only [ on | off ]
70 default: off
71 context: http, server, location
72 Whether or not a listener may create a channel. If set to on, a sender must
73 senda request to some channel (POST or PUT) before a listener. Otherwise,
74 all listener requests will get a 403 Forbidden response.
75
eb143fe5 »
2009-10-08 push_store_messages info
76 push_store_messages [ on | off ]
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
77 default: on
78 context: http, server, location
79 Whether or not message queuing is enabled. "Off" is equivalent to the setting
80 push_channel_buffer_length 0;
81
eb143fe5 »
2009-10-08 push_store_messages info
82 push_queue_messages [ on | off ] (DEPRECATED)
83 default: on
84 context: http, server, location
85 see push_store_messages
613e9aa3 »
2009-10-16 push_buffer_size deprecation note
86
87 push_buffer_size [ size ] (DEPRECATED)
88 default: 3M
89 context: http
90 see push_max_reserved_memory
eb143fe5 »
2009-10-08 push_store_messages info
91
81229917 »
2009-08-25 document it better
92 Variables:
dca6db82 »
2009-10-08 renamed $push_id to $push_channel_id. still need to find a way to use…
93 $push_channel_id
94 A token uniquely identifying a channel. Must be present in the context of
95 the push_listener and push_sender directives.
e7d3ccc6 »
2009-08-27 good enough
96 Example:
dca6db82 »
2009-10-08 renamed $push_id to $push_channel_id. still need to find a way to use…
97 set $push_channel_id $arg_id; #channel id is now the url parameter "id"
81229917 »
2009-08-25 document it better
98
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
99 --------------------------- Example Config -----------------------------------
100 http {
101 #maximum amount of memory the push module is allowed to use
102 #for buffering and stuff
02a0e11d »
2009-10-16 updated example slightly
103 push_max_reserved_memory 12M; #default is 3M
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
104
105 server {
56aac765 »
2009-10-16 fancier, simpler example
106 #sender
7587b85a »
2009-10-16 example urls
107 location /send {
dca6db82 »
2009-10-08 renamed $push_id to $push_channel_id. still need to find a way to use…
108 set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
109 push_sender;
110 push_message_timeout 2h; #buffered messages expire after 2 hours
56aac765 »
2009-10-16 fancier, simpler example
111 push_message_buffer_length 10; #store 10 messages.
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
112 }
113
56aac765 »
2009-10-16 fancier, simpler example
114 #receiver
7587b85a »
2009-10-16 example urls
115 location /listen {
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
116 push_listener;
56aac765 »
2009-10-16 fancier, simpler example
117 push_listener_concurrency broadcast;
118 set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
119 default_type text/plain;
120
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
121 }
122 }
123 }
124
e7d3ccc6 »
2009-08-27 good enough
125 ---------------------------- Operation ---------------------------------------
81229917 »
2009-08-25 document it better
126 Assuming the example config given above:
7587b85a »
2009-10-16 example urls
127 Clients will connect to http://example.com/listen?id=... and have the
128 response delayed until a message is POSTed to http://example.com/send?id=...
e7d3ccc6 »
2009-08-27 good enough
129 Messages can be sent to clients that have not yet connected, i.e. they are
130 queued.
6404eb24 »
2009-08-10 info
131
9ecf9eee »
2009-08-26 even less wrong, perhaps even almost sufficiently right
132 Upon sending a request to a push_sender location, the server will respond with
97c3e493 »
2009-08-10 elaborate.
133 a 201 Created if the message has been sent. If it must be queued up (i.e. the
9ecf9eee »
2009-08-26 even less wrong, perhaps even almost sufficiently right
134 push_listener with this id is presently connected), a 202 Accepted will be sent.
97c3e493 »
2009-08-10 elaborate.
135
da147525 »
2009-08-26 slightly less wrong
136 If you indend to have the push_sender be a server-side application,
137 it's a damn good idea to make sure the push_server location is not visible
97c3e493 »
2009-08-10 elaborate.
138 publically, as it is intended for use only by your application.
885051f4 »
2009-08-12 clarified the protocol, added a todo
139
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
140 Traversal through the message buffer by a listener requires proper caching
fb152f98 »
2009-10-08 read!!
141 support. Make sure your client correctly sends Last-Modified and ETag headers.
7828a9ea »
2009-10-08 deprecated deprecation, rename message buffer size setting
142
5c3be480 »
2009-10-08 updated protocol document
143 ----------------------- Protocol spec --------------------------------------
144 see the file protocol.txt
885051f4 »
2009-08-12 clarified the protocol, added a todo
145
e7d3ccc6 »
2009-08-27 good enough
146 ---------------------------- todo --------------------------------------------
fb152f98 »
2009-10-08 read!!
147 - Add other mechanisms of server pushing. The list should include
148 "long-poll" (default), "interval-poll".
dca6db82 »
2009-10-08 renamed $push_id to $push_channel_id. still need to find a way to use…
149 - When POSTing to a sender location, if Content-Type is "message/http", the
150 response sent to $push_channel_id should be created from the body of the
151 request.
885051f4 »
2009-08-12 clarified the protocol, added a todo
152
Something went wrong with that request. Please try again.