Skip to content
Newer
Older
100644 153 lines (127 sloc) 5.63 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:
7700e87 @slact pub/sub terminology for readme
authored
12 push_publisher
e7d3ccc @slact good enough
authored
13 default: none
14 context: server, location
7700e87 @slact pub/sub terminology for readme
authored
15 Defines a server or location as the publisher. Requests from a publisher will be
16 treated as messages to send to subscribers.See protocol documentation
e7d3ccc @slact good enough
authored
17 for more info.
18
7700e87 @slact pub/sub terminology for readme
authored
19 push_subscriber
e7d3ccc @slact good enough
authored
20 default: none
21 context: server, location
7700e87 @slact pub/sub terminology for readme
authored
22 Defines a server or location as a subscriber. Requests from a subscriber will
23 not be responded to until a message for the subscriber (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
7700e87 @slact pub/sub terminology for readme
authored
27 push_subscriber_concurrency [ last | first | broadcast ]
baaa275 @slact concurency setting stuff (not yet, but sort of)
authored
28 default: last
29 context: http, server, location
7700e87 @slact pub/sub terminology for readme
authored
30 Controls how multiple subscriber requests to the same channel id are handled.
baaa275 @slact concurency setting stuff (not yet, but sort of)
authored
31 The values work as follows:
7700e87 @slact pub/sub terminology for readme
authored
32 broadcast: any number of subscriber requests may be long-polling.
33 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
34 Conflict response.
7700e87 @slact pub/sub terminology for readme
authored
35 first: only the oldest subscriber request is kept, all others get a 409
baaa275 @slact concurency setting stuff (not yet, but sort of)
authored
36 Conflict response.
37
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
38 push_max_reserved_memory [ size ]
9d093e0 @slact upped DEFAULT_SHM_SIZE from 3 to 12 megs
authored
39 default: 12M
e7d3ccc @slact good enough
authored
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
2878765 @slact split push_message_buffer_length into push_min_message_buffer_length …
authored
44 push_min_message_buffer_length [ number ]
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
45 default: 5
46 context: http, server, location
2878765 @slact split push_message_buffer_length into push_min_message_buffer_length …
authored
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 ]
59738d8 @slact lowered DEFAULT_MAX_MESSAGE_QUEUE_SIZE from 255 to 50
authored
51 default: 50
2878765 @slact split push_message_buffer_length into push_min_message_buffer_length …
authored
52 context: http, server, location
5d839d3 @amir Updating README
amir authored
53 The maximum number of messages to store per channel. A channel's message
54 buffer, will cointain at last this many most recent messages.
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
55
7ed20c1 @slact added push_min_message_recipients option
authored
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
7700e87 @slact pub/sub terminology for readme
authored
66 not want messages to expire, set this to 0. Applicable only if a push_publisher
7ed20c1 @slact added push_min_message_recipients option
authored
67 is present in this or a child context.
68
b26ed76 @slact push_authorized_channels_only documentation
authored
69 push_authorized_channels_only [ on | off ]
70 default: off
71 context: http, server, location
7700e87 @slact pub/sub terminology for readme
authored
72 Whether or not a subscriber may create a channel. If set to on, a publisher must
73 senda request to some channel (POST or PUT) before a subscriber. Otherwise,
74 all subscriber requests will get a 403 Forbidden response.
b26ed76 @slact push_authorized_channels_only documentation
authored
75
eb143fe @slact push_store_messages info
authored
76 push_store_messages [ on | off ]
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
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
eb143fe @slact push_store_messages info
authored
82 push_queue_messages [ on | off ] (DEPRECATED)
83 default: on
84 context: http, server, location
85 see push_store_messages
613e9aa @slact push_buffer_size deprecation note
authored
86
87 push_buffer_size [ size ] (DEPRECATED)
88 default: 3M
89 context: http
90 see push_max_reserved_memory
eb143fe @slact push_store_messages info
authored
91
8122991 @slact document it better
authored
92 Variables:
dca6db8 @slact renamed $push_id to $push_channel_id. still need to find a way to use…
authored
93 $push_channel_id
94 A token uniquely identifying a channel. Must be present in the context of
7700e87 @slact pub/sub terminology for readme
authored
95 the push_subscriber and push_publisher directives.
e7d3ccc @slact good enough
authored
96 Example:
dca6db8 @slact renamed $push_id to $push_channel_id. still need to find a way to use…
authored
97 set $push_channel_id $arg_id; #channel id is now the url parameter "id"
8122991 @slact document it better
authored
98
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
99 --------------------------- Example Config -----------------------------------
100 http {
101 #maximum amount of memory the push module is allowed to use
102 #for buffering and stuff
02a0e11 @slact updated example slightly
authored
103 push_max_reserved_memory 12M; #default is 3M
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
104
105 server {
7700e87 @slact pub/sub terminology for readme
authored
106 #publisher
7587b85 @slact example urls
authored
107 location /send {
dca6db8 @slact renamed $push_id to $push_channel_id. still need to find a way to use…
authored
108 set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
7700e87 @slact pub/sub terminology for readme
authored
109 push_publisher;
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
110 push_message_timeout 2h; #buffered messages expire after 2 hours
5d839d3 @amir Updating README
amir authored
111 push_max_message_buffer_length 10; #store 10 messages.
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
112 }
113
56aac76 @slact fancier, simpler example
authored
114 #receiver
7587b85 @slact example urls
authored
115 location /listen {
7700e87 @slact pub/sub terminology for readme
authored
116 push_subscriber;
117 push_subscriber_concurrency broadcast;
56aac76 @slact fancier, simpler example
authored
118 set $push_channel_id $arg_id; #/?id=239aff3 or somesuch
7700e87 @slact pub/sub terminology for readme
authored
119 default_type text/plain;
120
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
121 }
122 }
123 }
7700e87 @slact pub/sub terminology for readme
authored
124
e7d3ccc @slact good enough
authored
125 ---------------------------- Operation ---------------------------------------
8122991 @slact document it better
authored
126 Assuming the example config given above:
7587b85 @slact example urls
authored
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=...
e7d3ccc @slact good enough
authored
129 Messages can be sent to clients that have not yet connected, i.e. they are
130 queued.
6404eb2 @slact info
authored
131
7700e87 @slact pub/sub terminology for readme
authored
132 Upon sending a request to a push_publisher location, the server will respond with
97c3e49 @slact elaborate.
authored
133 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
134 push_subscriber with this id is presently connected), a 202 Accepted will be sent.
97c3e49 @slact elaborate.
authored
135
7700e87 @slact pub/sub terminology for readme
authored
136 If you indend to have the push_publisher be a server-side application,
da14752 @slact slightly less wrong
authored
137 it's a damn good idea to make sure the push_server location is not visible
97c3e49 @slact elaborate.
authored
138 publically, as it is intended for use only by your application.
885051f @slact clarified the protocol, added a todo
authored
139
7700e87 @slact pub/sub terminology for readme
authored
140 Traversal through the message buffer by a subscriber requires proper caching
fb152f9 @slact read!!
authored
141 support. Make sure your client correctly sends Last-Modified and ETag headers.
7828a9e @slact deprecated deprecation, rename message buffer size setting
authored
142
5c3be48 @slact updated protocol document
authored
143 ----------------------- Protocol spec --------------------------------------
144 see the file protocol.txt
885051f @slact clarified the protocol, added a todo
authored
145
e7d3ccc @slact good enough
authored
146 ---------------------------- todo --------------------------------------------
fb152f9 @slact read!!
authored
147 - Add other mechanisms of server pushing. The list should include
148 "long-poll" (default), "interval-poll".
7700e87 @slact pub/sub terminology for readme
authored
149 - When POSTing to a publisher location, if Content-Type is "message/http", the
dca6db8 @slact renamed $push_id to $push_channel_id. still need to find a way to use…
authored
150 response sent to $push_channel_id should be created from the body of the
151 request.
885051f @slact clarified the protocol, added a todo
authored
152
Something went wrong with that request. Please try again.