Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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