Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 137 lines (115 sloc) 5.238 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
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
24 $push_id) becomes available. See protocol documentation for more info.
8122991 @slact document it better
authored
25
baaa275 @slact concurency setting stuff (not yet, but sort of)
authored
26 push_listener_concurrency
27
28 push_listener_concurrency [ last | first | broadcast ]
29 default: last
30 context: http, server, location
31 Controls how multiple listener requests to the same channel id are handled.
32 The values work as follows:
33 broadcast: any number of listener requests may be long-polling.
34 last: only the most recent listener request is kept, all others get a 409
35 Conflict response.
36 first: only the oldest listener request is kept, all others get a 409
37 Conflict response.
38
e7d3ccc @slact good enough
authored
39 push_message_timeout [ time ]
40 default: 1h
41 context: http, server, location
42 How long a message may be queued before it is considered expired. If you do
43 not want messages to expire, set this to 0. Applicable only if a push_sender
44 is present in this or a child context.
8122991 @slact document it better
authored
45
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
46 push_max_reserved_memory [ size ]
e7d3ccc @slact good enough
authored
47 default: 3M
48 context: http
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
49 The size of the memory chunk this module will use for all message queuing
e7d3ccc @slact good enough
authored
50 and buffering.
8122991 @slact document it better
authored
51
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
52 push_message_buffer_length [ number ]
53 default: 5
54 context: http, server, location
55 The maximum number of messages to store per channel. Old messages are removed
56 when a channel's message buffer length exceeds this setting. Set to 0 to
57 disable buffering.
58
59 The following directives are DEPRECATED. They will be respected,
60 but may not be around for very long.
61
62 push_queue_messages [ on | off ]
63 default: on
64 context: http, server, location
65 Whether or not message queuing is enabled. "Off" is equivalent to the setting
66 push_channel_buffer_length 0;
67
8122991 @slact document it better
authored
68 Variables:
69 $push_id
e7d3ccc @slact good enough
authored
70 The id associated with a push_listener or push_sender. Must be present next
71 to said directives.
72 Example:
73 set $push_id $arg_id #$push_id is now the url parameter "id"
8122991 @slact document it better
authored
74
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
75 --------------------------- Example Config -----------------------------------
76 http {
77 #maximum amount of memory the push module is allowed to use
78 #for buffering and stuff
79 push_buffer_size 12M; #default is 3M
80
81 #sender
82 server {
83 listen localhost:8089;
84 location / {
85 default_type text/plain;
86 set $push_id $arg_id; #/?id=239aff3 or somesuch
87 push_sender;
88 push_message_timeout 2h; #buffered messages expire after 2 hours
89 push_message_buffer_length 10; #store 10 messages.
90 }
91 }
92
93 #receiver
94 server {
95 listen 8088;
96 location / {
97 default_type text/plain;
98 set $push_id $arg_id; #/?id=239aff3 or somesuch
99 push_listener;
100 }
101 }
102 }
103
e7d3ccc @slact good enough
authored
104 ---------------------------- Operation ---------------------------------------
8122991 @slact document it better
authored
105 Assuming the example config given above:
6404eb2 @slact info
authored
106 Clients will connect to http://example.com:8088/?id=... and have the
107 response delayed until a message is POSTed to http://localhost:8089/?id=...
e7d3ccc @slact good enough
authored
108 Messages can be sent to clients that have not yet connected, i.e. they are
109 queued.
6404eb2 @slact info
authored
110
9ecf9ee @slact even less wrong, perhaps even almost sufficiently right
authored
111 Upon sending a request to a push_sender location, the server will respond with
97c3e49 @slact elaborate.
authored
112 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
113 push_listener with this id is presently connected), a 202 Accepted will be sent.
97c3e49 @slact elaborate.
authored
114
da14752 @slact slightly less wrong
authored
115 If you indend to have the push_sender be a server-side application,
116 it's a damn good idea to make sure the push_server location is not visible
97c3e49 @slact elaborate.
authored
117 publically, as it is intended for use only by your application.
885051f @slact clarified the protocol, added a todo
authored
118
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
119 Traversal through the message buffer by a listener requires proper caching
120 support. Make sure your client correctly send Last-Modified and ETag headers.
121
e7d3ccc @slact good enough
authored
122 ----------------------- "Protocol" spec --------------------------------------
22eb295 @slact renamed push_server and push_client to push_sender and push_listener, re...
authored
123 see http://wiki.github.com/slact/nginx_http_push_module/queuing-long-poll-relay-protocol
885051f @slact clarified the protocol, added a todo
authored
124
e7d3ccc @slact good enough
authored
125 ---------------------------- todo --------------------------------------------
d0e5c83 @slact todos
authored
126 - Add a directive apply to push_listeners regarding what to do when
127 multiple simultaneous requests with the same $push_id are received.
128 Options will be "unique", "broadcast", "fifo" and "filo".
129 - Add other mechanisms of server pushing. The list should include
130 "long-poll" (default), "interval-poll".
e7d3ccc @slact good enough
authored
131 - Add a push_accomodate_strangers setting (presently defaulting to on).
132 When set to off, requests with a previously-unseen $push_id
133 will be rejected.
134 - When POSTing to push_server, if Content-Type is "message/http", the
135 response sent to $push_id should be created from the body of the request.
885051f @slact clarified the protocol, added a todo
authored
136
Something went wrong with that request. Please try again.