Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 148 lines (123 sloc) 5.471 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 ------------------------
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
dca6db8 @slact renamed $push_id to $push_channel_id. still need to find a way to use…
authored
24 $push_channel_id) becomes available. See protocol documentation for more
25 info.
8122991 @slact document it better
authored
26
baaa275 @slact concurency setting stuff (not yet, but sort of)
authored
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
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
38 push_max_reserved_memory [ size ]
e7d3ccc @slact good enough
authored
39 default: 3M
40 context: http
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
41 The size of the memory chunk this module will use for all message queuing
e7d3ccc @slact good enough
authored
42 and buffering.
8122991 @slact document it better
authored
43
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
44 push_message_buffer_length [ number ]
45 default: 5
46 context: http, server, location
47 The maximum number of messages to store per channel. Old messages are removed
48 when a channel's message buffer length exceeds this setting. Set to 0 to
49 disable buffering.
50
7ed20c1 @slact added push_min_message_recipients option
authored
51 push_min_message_recipients [ number ]
52 default: 0
53 context: http, server, location
54 How many times a message must be received before it is considered for
55 deletion. Useful to guarantee message delivery.
56
57 push_message_timeout [ time ]
58 default: 1h
59 context: http, server, location
60 How long a message may be queued before it is considered expired. If you do
61 not want messages to expire, set this to 0. Applicable only if a push_sender
62 is present in this or a child context.
63
b26ed76 @slact push_authorized_channels_only documentation
authored
64 push_authorized_channels_only [ on | off ]
65 default: off
66 context: http, server, location
67 Whether or not a listener may create a channel. If set to on, a sender must
68 senda request to some channel (POST or PUT) before a listener. Otherwise,
69 all listener requests will get a 403 Forbidden response.
70
eb143fe @slact push_store_messages info
authored
71 push_store_messages [ on | off ]
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
72 default: on
73 context: http, server, location
74 Whether or not message queuing is enabled. "Off" is equivalent to the setting
75 push_channel_buffer_length 0;
76
eb143fe @slact push_store_messages info
authored
77 push_queue_messages [ on | off ] (DEPRECATED)
78 default: on
79 context: http, server, location
80 see push_store_messages
613e9aa @slact push_buffer_size deprecation note
authored
81
82 push_buffer_size [ size ] (DEPRECATED)
83 default: 3M
84 context: http
85 see push_max_reserved_memory
eb143fe @slact push_store_messages info
authored
86
8122991 @slact document it better
authored
87 Variables:
dca6db8 @slact renamed $push_id to $push_channel_id. still need to find a way to use…
authored
88 $push_channel_id
89 A token uniquely identifying a channel. Must be present in the context of
90 the push_listener and push_sender directives.
e7d3ccc @slact good enough
authored
91 Example:
dca6db8 @slact renamed $push_id to $push_channel_id. still need to find a way to use…
authored
92 set $push_channel_id $arg_id; #channel id is now the url parameter "id"
8122991 @slact document it better
authored
93
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
94 --------------------------- Example Config -----------------------------------
95 http {
96 #maximum amount of memory the push module is allowed to use
97 #for buffering and stuff
02a0e11 @slact updated example slightly
authored
98 push_max_reserved_memory 12M; #default is 3M
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
99
100 server {
56aac76 @slact fancier, simpler example
authored
101 #sender
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
102 location / {
dca6db8 @slact renamed $push_id to $push_channel_id. still need to find a way to use…
authored
103 set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
104 push_sender;
105 push_message_timeout 2h; #buffered messages expire after 2 hours
56aac76 @slact fancier, simpler example
authored
106 push_message_buffer_length 10; #store 10 messages.
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
107 }
108
56aac76 @slact fancier, simpler example
authored
109 #receiver
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
110 location / {
111 push_listener;
56aac76 @slact fancier, simpler example
authored
112 push_listener_concurrency broadcast;
113 set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
114 default_type text/plain;
115
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
116 }
117 }
118 }
119
e7d3ccc @slact good enough
authored
120 ---------------------------- Operation ---------------------------------------
8122991 @slact document it better
authored
121 Assuming the example config given above:
6404eb2 @slact info
authored
122 Clients will connect to http://example.com:8088/?id=... and have the
123 response delayed until a message is POSTed to http://localhost:8089/?id=...
e7d3ccc @slact good enough
authored
124 Messages can be sent to clients that have not yet connected, i.e. they are
125 queued.
6404eb2 @slact info
authored
126
9ecf9ee @slact even less wrong, perhaps even almost sufficiently right
authored
127 Upon sending a request to a push_sender location, the server will respond with
97c3e49 @slact elaborate.
authored
128 a 201 Created if the message has been sent. If it must be queued up (i.e. the
9ecf9ee @slact even less wrong, perhaps even almost sufficiently right
authored
129 push_listener with this id is presently connected), a 202 Accepted will be sent.
97c3e49 @slact elaborate.
authored
130
da14752 @slact slightly less wrong
authored
131 If you indend to have the push_sender be a server-side application,
132 it's a damn good idea to make sure the push_server location is not visible
97c3e49 @slact elaborate.
authored
133 publically, as it is intended for use only by your application.
885051f @slact clarified the protocol, added a todo
authored
134
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
135 Traversal through the message buffer by a listener requires proper caching
fb152f9 @slact read!!
authored
136 support. Make sure your client correctly sends Last-Modified and ETag headers.
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
137
5c3be48 @slact updated protocol document
authored
138 ----------------------- Protocol spec --------------------------------------
139 see the file protocol.txt
885051f @slact clarified the protocol, added a todo
authored
140
e7d3ccc @slact good enough
authored
141 ---------------------------- todo --------------------------------------------
fb152f9 @slact read!!
authored
142 - Add other mechanisms of server pushing. The list should include
143 "long-poll" (default), "interval-poll".
dca6db8 @slact renamed $push_id to $push_channel_id. still need to find a way to use…
authored
144 - When POSTing to a sender location, if Content-Type is "message/http", the
145 response sent to $push_channel_id should be created from the body of the
146 request.
885051f @slact clarified the protocol, added a todo
authored
147
Something went wrong with that request. Please try again.