1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
h1(#nginx_push_stream_module). Nginx Push Stream Module
A pure stream http push technology for your Nginx setup.
"Comet":comet_ref made easy and *really scalable*.
Supports "EventSource":eventsource_ref, "WebSocket":websocket_ref, Long Polling, and Forever Iframe. See "some examples":examples bellow.
_This module is not distributed with the Nginx source. See "the installation instructions":installation._
Available on github at "nginx_push_stream_module":repository
h1(#changelog). Changelog
Always take a look at "CHANGELOG.textile":changelog to see what's new.
h1(#contribute). Contribute
After you try this module and like it, feel free to "give something back":donate, and help in the maintenance of the project ;)
!https://www.paypalobjects.com/WEBSCR-640-20110429-1/en_US/i/btn/btn_donate_LG.gif!:donate
h1(#status). Status
This module is considered production ready.
h1(#basic-configuration). Basic Configuration
<pre>
# add the push_stream_shared_memory_size to your http context
http {
push_stream_shared_memory_size 32M;
# define publisher and subscriber endpoints in your server context
server {
location /channels-stats {
# activate channels statistics mode for this location
push_stream_channels_statistics;
# query string based channel id
push_stream_channels_path $arg_id;
}
location /pub {
# activate publisher (admin) mode for this location
push_stream_publisher admin;
# query string based channel id
push_stream_channels_path $arg_id;
}
location ~ /sub/(.*) {
# activate subscriber (streaming) mode for this location
push_stream_subscriber;
# positional channel path
push_stream_channels_path $1;
}
}
}
</pre>
h1(#basic-usage). Basic Usage
You can feel the flavor right now at the command line. Try using more than
one terminal and start playing http pubsub:
<pre>
# Subs
curl -s -v --no-buffer 'http://localhost/sub/my_channel_1'
curl -s -v --no-buffer 'http://localhost/sub/your_channel_1'
curl -s -v --no-buffer 'http://localhost/sub/your_channel_2'
# Pubs
curl -s -v -X POST 'http://localhost/pub?id=my_channel_1' -d 'Hello World!'
curl -s -v -X POST 'http://localhost/pub?id=your_channel_1' -d 'Hi everybody!'
curl -s -v -X POST 'http://localhost/pub?id=your_channel_2' -d 'Goodbye!'
# Channels Stats for publisher (json format)
curl -s -v 'http://localhost/pub?id=my_channel_1'
# All Channels Stats summarized (json format)
curl -s -v 'http://localhost/channels-stats'
# All Channels Stats detailed (json format)
curl -s -v 'http://localhost/channels-stats?id=ALL'
# Prefixed Channels Stats detailed (json format)
curl -s -v 'http://localhost/channels-stats?id=your_channel_*'
# Channels Stats (json format)
curl -s -v 'http://localhost/channels-stats?id=my_channel_1'
# Delete Channels
curl -s -v -X DELETE 'http://localhost/pub?id=my_channel_1'
</pre>
h1(#examples). Some Examples <a name="examples" href="#"> </a>
* "Curl examples":curl
* "Forever (hidden) iFrame":forever_iframe
* "Event Source":event_source
* "WebSocket":websocket
* "Long Polling":long_polling
* "JSONP":jsonp
* "M-JPEG":m-jpeg
* "Other examples":wiki
h1(#FAQ). FAQ <a names="faq" href="#"> </a>
Doubts?! Check the "FAQ":wiki.
h1(#bug_report). Bug report <a name="bug_report" href="#"> </a>
To report a bug, please provide the following information when applicable
# Which push stream module version is been used (commit sha1)?
# Which nginx version is been used?
# Nginx configuration in use
# "nginx -V" command outuput
# Core dump indicating a failure on the module code. Check "here":nginx_debugging how to produce one.
# Step by step description to reproduce the error.
h1(#who). Who is using the module? <a names="faq" href="#"> </a>
Do you use this module? Put your name on the "list":wiki.
h1(#javascript_client). Javascript Client <a name="javascript_client" href="#"> </a>
There is a javascript client implementation "here":javascript_client, which is framework independent. Try and help improve it. ;)
h1(#directives). Directives
(1) Defining locations, (2) Main configuration, (3) Subscribers configuration, (4) Publishers configuration, (5) Channels Statistics configuration, (6) WebSocket configuration
(head). | Directive | (1) | (2) | (3) | (4) | (5) | (6) |
| "push_stream_channels_statistics":push_stream_channels_statistics | x | - | - | - | - | - |
| "push_stream_publisher":push_stream_publisher | x | - | - | - | - | - |
| "push_stream_subscriber":push_stream_subscriber | x | - | - | - | - | - |
| "push_stream_shared_memory_size":push_stream_shared_memory_size | - | x | - | - | - | - |
| "push_stream_channel_deleted_message_text":push_stream_channel_deleted_message_text | - | x | - | - | - | - |
| "push_stream_channel_inactivity_time":push_stream_channel_inactivity_time | - | x | - | - | - | - |
| "push_stream_ping_message_text":push_stream_ping_message_text | - | x | - | - | - | - |
| "push_stream_timeout_with_body":push_stream_timeout_with_body | - | x | - | - | - | - |
| "push_stream_message_ttl":push_stream_message_ttl | - | x | - | - | - | - |
| "push_stream_max_subscribers_per_channel":push_stream_max_subscribers_per_channel | - | x | - | - | - | - |
| "push_stream_max_messages_stored_per_channel":push_stream_max_messages_stored_per_channel | - | x | - | - | - | - |
| "push_stream_max_channel_id_length":push_stream_max_channel_id_length | - | x | - | - | - | - |
| "push_stream_max_number_of_channels":push_stream_max_number_of_channels | - | x | - | - | - | - |
| "push_stream_max_number_of_wildcard_channels":push_stream_max_number_of_wildcard_channels | - | x | - | - | - | - |
| "push_stream_wildcard_channel_prefix":push_stream_wildcard_channel_prefix | - | x | - | - | - | - |
| "push_stream_events_channel_id":push_stream_events_channel_id | - | x | - | - | - | - |
| "push_stream_channels_path":push_stream_channels_path | - | - | x | x | x | x |
| "push_stream_store_messages":push_stream_store_messages | - | - | - | x | - | x |
| "push_stream_channel_info_on_publish":push_stream_channel_info_on_publish | - | - | - | x | - | - |
| "push_stream_authorized_channels_only":push_stream_authorized_channels_only | - | - | x | - | - | x |
| "push_stream_header_template_file":push_stream_header_template_file | - | - | x | - | - | x |
| "push_stream_header_template":push_stream_header_template | - | - | x | - | - | x |
| "push_stream_message_template":push_stream_message_template | - | - | x | - | - | x |
| "push_stream_footer_template":push_stream_footer_template | - | - | x | - | - | x |
| "push_stream_wildcard_channel_max_qtd":push_stream_wildcard_channel_max_qtd | - | - | x | - | - | x |
| "push_stream_ping_message_interval":push_stream_ping_message_interval | - | - | x | - | - | x |
| "push_stream_subscriber_connection_ttl":push_stream_subscriber_connection_ttl | - | - | x | - | - | x |
| "push_stream_longpolling_connection_ttl":push_stream_longpolling_connection_ttl | - | - | x | - | - | - |
| "push_stream_websocket_allow_publish":push_stream_websocket_allow_publish | - | - | - | - | - | x |
| "push_stream_last_received_message_time":push_stream_last_received_message_time | - | - | x | - | - | - |
| "push_stream_last_received_message_tag":push_stream_last_received_message_tag | - | - | x | - | - | - |
| "push_stream_last_event_id":push_stream_last_event_id | - | - | x | - | - | - |
| "push_stream_user_agent":push_stream_user_agent | - | - | x | - | - | - |
| "push_stream_padding_by_user_agent":push_stream_padding_by_user_agent | - | - | x | - | - | - |
| "push_stream_allowed_origins":push_stream_allowed_origins | - | - | x | - | - | - |
| "push_stream_allow_connections_to_events_channel":push_stream_allow_connections_to_events_channel | - | - | x | - | - | x |
h1(#installation). Installation <a name="installation" href="#"> </a>
<pre>
# clone the project
git clone https://github.com/wandenberg/nginx-push-stream-module.git
NGINX_PUSH_STREAM_MODULE_PATH=$PWD/nginx-push-stream-module
# get desired nginx version (works with 1.2.0+)
wget http://nginx.org/download/nginx-1.2.0.tar.gz
# unpack, configure and build
tar xzvf nginx-1.2.0.tar.gz
cd nginx-1.2.0
./configure --add-module=../nginx-push-stream-module
make
# install and finish
sudo make install
# check
sudo /usr/local/nginx/sbin/nginx -v
nginx version: nginx/1.2.0
# test configuration
sudo /usr/local/nginx/sbin/nginx -c $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf -t
the configuration file $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf syntax is ok
configuration file $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf test is successful
# run
sudo /usr/local/nginx/sbin/nginx -c $NGINX_PUSH_STREAM_MODULE_PATH/misc/nginx.conf
</pre>
h1(#memory-usage). Memory usage
Just as information is listed below the minimum amount of memory used for each object:
* message on shared = 200 bytes
* channel on shared = 270 bytes
* subscriber
** on shared = 160 bytes
** on system = 6550 bytes
h1(#tests). Tests
The server tests for this module are written in Ruby, and are acceptance tests, click "here":tests for more details.
h1(#discussion). Discussion
Nginx Push Stream Module "Discussion Group":discussion
h1(#contributors). Contributors
"People":contributors
[discussion]https://groups.google.com/group/nginxpushstream
[donate]https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=4LP6P9A7BC37S
[eventsource_ref]http://dev.w3.org/html5/eventsource/
[websocket_ref]http://dev.w3.org/html5/websockets/
[comet_ref]http://en.wikipedia.org/wiki/Comet_%28programming%29
[installation]#installation
[examples]#examples
[javascript_client]docs/javascript_client.textile#javascript_client
[repository]https://github.com/wandenberg/nginx-push-stream-module
[contributors]https://github.com/wandenberg/nginx-push-stream-module/contributors
[changelog]CHANGELOG.textile
[curl]docs/examples/curl.textile#curl
[forever_iframe]docs/examples/forever_iframe.textile#forever_iframe
[event_source]docs/examples/event_source.textile#event_source
[websocket]docs/examples/websocket.textile#websocket
[long_polling]docs/examples/long_polling.textile#long_polling
[jsonp]docs/examples/long_polling.textile#jsonp
[m-jpeg]docs/examples/m_jpeg.textile#m_jpeg
[tests]docs/server_tests.textile
[push_stream_channels_statistics]docs/directives/channels_statistics.textile#push_stream_channels_statistics
[push_stream_publisher]docs/directives/publishers.textile#push_stream_publisher
[push_stream_subscriber]docs/directives/subscribers.textile#push_stream_subscriber
[push_stream_shared_memory_size]docs/directives/main.textile#push_stream_shared_memory_size
[push_stream_channel_deleted_message_text]docs/directives/main.textile#push_stream_channel_deleted_message_text
[push_stream_ping_message_text]docs/directives/main.textile#push_stream_ping_message_text
[push_stream_channel_inactivity_time]docs/directives/main.textile#push_stream_channel_inactivity_time
[push_stream_message_ttl]docs/directives/main.textile#push_stream_message_ttl
[push_stream_max_subscribers_per_channel]docs/directives/main.textile#push_stream_max_subscribers_per_channel
[push_stream_max_messages_stored_per_channel]docs/directives/main.textile#push_stream_max_messages_stored_per_channel
[push_stream_max_channel_id_length]docs/directives/main.textile#push_stream_max_channel_id_length
[push_stream_max_number_of_channels]docs/directives/main.textile#push_stream_max_number_of_channels
[push_stream_max_number_of_wildcard_channels]docs/directives/main.textile#push_stream_max_number_of_wildcard_channels
[push_stream_wildcard_channel_prefix]docs/directives/main.textile#push_stream_wildcard_channel_prefix
[push_stream_events_channel_id]docs/directives/main.textile#push_stream_events_channel_id
[push_stream_channels_path]docs/directives/subscribers.textile#push_stream_channels_path
[push_stream_authorized_channels_only]docs/directives/subscribers.textile#push_stream_authorized_channels_only
[push_stream_header_template_file]docs/directives/subscribers.textile#push_stream_header_template_file
[push_stream_header_template]docs/directives/subscribers.textile#push_stream_header_template
[push_stream_message_template]docs/directives/subscribers.textile#push_stream_message_template
[push_stream_footer_template]docs/directives/subscribers.textile#push_stream_footer_template
[push_stream_wildcard_channel_max_qtd]docs/directives/subscribers.textile#push_stream_wildcard_channel_max_qtd
[push_stream_ping_message_interval]docs/directives/subscribers.textile#push_stream_ping_message_interval
[push_stream_subscriber_connection_ttl]docs/directives/subscribers.textile#push_stream_subscriber_connection_ttl
[push_stream_longpolling_connection_ttl]docs/directives/subscribers.textile#push_stream_longpolling_connection_ttl
[push_stream_timeout_with_body]docs/directives/subscribers.textile#push_stream_timeout_with_body
[push_stream_last_received_message_time]docs/directives/subscribers.textile#push_stream_last_received_message_time
[push_stream_last_received_message_tag]docs/directives/subscribers.textile#push_stream_last_received_message_tag
[push_stream_last_event_id]docs/directives/subscribers.textile#push_stream_last_event_id
[push_stream_user_agent]docs/directives/subscribers.textile#push_stream_user_agent
[push_stream_padding_by_user_agent]docs/directives/subscribers.textile#push_stream_padding_by_user_agent
[push_stream_store_messages]docs/directives/publishers.textile#push_stream_store_messages
[push_stream_channel_info_on_publish]docs/directives/publishers.textile#push_stream_channel_info_on_publish
[push_stream_allowed_origins]docs/directives/subscribers.textile#push_stream_allowed_origins
[push_stream_websocket_allow_publish]docs/directives/subscribers.textile#push_stream_websocket_allow_publish
[push_stream_allow_connections_to_events_channel]docs/directives/subscribers.textile#push_stream_allow_connections_to_events_channel
[wiki]https://github.com/wandenberg/nginx-push-stream-module/wiki/_pages
[nginx_debugging]http://wiki.nginx.org/Debugging
|
