HTTP Push Stream¶
説明¶
nginx-push-stream-module - NGINX構成のためのピュアstream http pushテクノロジ。
Comet made easy and really scalable.
github上のnginx-push-stream-moduleで利用可能です。
注意
このモジュールはNGIXのソースと一緒に配布されません。 インストレーションの説明を見てください。
変更ログ¶
最新については常に CHANGELOG.textileを見てください。
状態¶
このモジュールはプロダクションの準備ができています。
インストール
プロジェクト内で build.sh
スクリプトを使うかも知れません:
# clone the project
git clone http://github.com/wandenberg/nginx-push-stream-module.git
NGINX_PUSH_STREAM_MODULE_PATH=$PWD/nginx-push-stream-module
cd nginx-push-stream-module
# build with 1.0.x, 0.9.x, 0.8.x series
./build.sh master 1.0.5
cd build/nginx-1.0.5
# install and finish
sudo make install
# check
sudo /usr/local/nginx/sbin/nginx -v
nginx version: nginx/1.0.5
# 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
あるいは、自分自身で行うかも知れません:
# clone the project
git clone http://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.0.x, 0.9.x, 0.8.x series)
wget http://nginx.org/download/nginx-1.0.5.tar.gz
# unpack, configure and build
tar xzvf nginx-1.0.5.tar.gz
cd nginx-1.0.5
./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.0.5
# 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
基本設定¶
location /channels-stats {
# activate channels statistics mode for this location
push_stream_channels_statistics;
# query string based channel id
set $push_stream_channel_id $arg_id;
}
location /pub {
# activate publisher (admin) mode for this location
push_stream_publisher admin;
# query string based channel id
set $push_stream_channel_id $arg_id;
}
location ~ /sub/(.*) {
# activate subscriber (streaming) mode for this location
push_stream_subscriber;
# positional channel path
set $push_stream_channels_path $1;
}
基本的な使い方¶
You can feel the flavor right now at the command line. 一つ以上のターミナルを使ってhttp pubsubを開始します:
# 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!'
# Subs
curl -s -v 'http://localhost/sub/my_channel_1.b20'
curl -s -v 'http://localhost/sub/your_channel_1.b20'
curl -s -v 'http://localhost/sub/your_channel_2.b20'
# 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'
変数¶
push_stream_channel_id¶
値: | channel id |
---|---|
Location: | push_stream_publisher, push_stream_channels_statistics |
通信チャネルを独自に識別するための文字列。push_stream_publisher と push_stream_channels_statisticsのlocation上に存在しなければなりません。
set $push_channel_id $arg_id;
#channel id is now the url query string parameter "id"
#(/pub?id=channel_id_string or /channels-stats?id=channel_id_string)
push_stream_channels_path¶
値: | set of channels id and backtrack desired messages |
---|---|
Location: | push_stream_subscriber |
A string representing a set of channels id and backtrack desired messages separated by slash, example /channel1.b3/channel2.b5/channel3.b2. バックトラックは、購読者へ配送される各チャネルからの古い総メッセージを意味します。例えば /channel1.b3/channel2.b5/channel3.b2</c0>。例では、channel1からの3つのメッセージ、channel2からの5つのメッセージ、channel3からの2つのメッセージ。バックトラックは必須ではありません。古いメッセージを取得せずにchannelだけを署名、あるいはそれらを混ぜることができます。More accepted examples: /channel1 , /channel1/channel2 , /channel1.b5/channel2 , /channel1/channel2.b6 , … Must be present on location of the push_stream_subscriber.
location /sub/(.*) {
set $push_stream_channels_path $1;
}
#channels path is now part of url
#(/sub/channel_id_string or /sub/channel_id_string.b2/other_channel)
ディレクティブ¶
push_stream_channels_statistics¶
構文: | push_stream_channels_statistics |
---|---|
デフォルト: | 場所 |
release version: 0.2.0
統計のソースとしてのlocationを定義。You can use this location to get statistics about a specific, group or all channels, in a resumed ou summarized way. 全てのchannelの統計を要約して取得するにはpush_stream_channel_id 変数に名前を指定せずにlocationにGETします。全てのchannelの統計を詳細に取得するには push_stream_channel_id に"all"を指定しなければなりません。接頭辞のあるchannelの統計を詳細に取得するには push_stream_channel_idに"_prefix_*"を指定しなければなりません。あるchannelの統計を取得するには push_stream_channel_id に名前を指定しなければなりません。
統計を plain, xml, yaml および jsonの形式で取得することができます。デフォルトはjsonで、この挙動を変更するために、Accept ヘッダパラメータにそれぞれ "text/plain","application/xml", "application/yaml" および "application/json"の値を渡すことができます。
location /channels-stats {
push_stream_channels_statistics;
set $push_stream_channel_id $arg_id;
}
# /channels-stats -> get statistics about all channels in a summarized way
# /channels-stats?id=ALL -> get statistics about all channels in a detailed way
# /channels-stats?id=channel_* -> get statistics about all channels which starts with 'channel_'
# /channels-stats?id=channel_id -> get statistics about a channel
push_stream_publisher¶
構文: | push_stream_publisher [ normal | admin ] |
---|---|
デフォルト: | normal |
コンテキスト: | 場所 |
メッセージの発行者としてlocationを定義します。発行者のlocationへのリクエストは購読者へ送信されるメッセージとして扱われます。このlocationは3つのhttpメソッドをサポートします: GET, channelについての統計を取得することができます。POST, channelへのメッセージを発行します。DELETE, 既存の保持された全てのメッセージを削除、購読者の切断、およびchannelの削除をします。このディレクティブの中でadmin 値が使われた場合のみ利用可能です。
# normal publisher location
location /pub {
push_stream_publisher;
set $push_stream_channel_id $arg_id;
}
# GET /pub?id=channel_id -> get statistics about a channel
# POST /pub?id=channel_id -> publish a message to the channel
# admin publisher location
location /pub_admin {
push_stream_publisher admin;
set $push_stream_channel_id $arg_id;
}
# GET /pub_admin?id=channel_id -> get statistics about a channel
# POST /pub_admin?id=channel_id -> publish a message to the channel
# DELETE /pub_admin?id=channel_id -> delete the channel
push_stream_subscriber¶
構文: | push_stream_subscriber [ streaming | polling |
long-polling ] |
---|---|
デフォルト: | streaming |
コンテキスト: | 場所 |
購読者としてlocationを定義します。このlocationはchannelのメッセージキューへの購読者のインタフェースを表します。このlocationは発行されたメッセージを受け取るために GET http メソッドのみをサポートします。そして、pushモードを設定するための3つの可能な値を持ちます: streaming, polling, long-polling. デフォルト値はstreamingです。ポーリングおよび長時間のポーリングモードはpush_stream_subscriber ディレクティブ値を上書きするリクエストヘッダX-Nginx-PushStream-Modeによって設定することができます。
# streaming subscriber location
location /sub/(.*) {
push_stream_subscriber;
# positional channel path
set $push_stream_channels_path $1;
}
curl localhost/sub/ch1 -H 'X-Nginx-PushStream-Mode:polling' #polling request on a streaming location
curl localhost/sub/ch1 -H 'X-Nginx-PushStream-Mode:long-polling' #long-polling request on a streaming location
# polling subscriber location
location /sub/(.*) {
push_stream_subscriber polling;
# positional channel path
set $push_stream_channels_path $1;
}
curl localhost/sub/ch1 #polling request
curl localhost/sub/ch1 -H 'X-Nginx-PushStream-Mode:long-polling' #long-polling request on a polling location
# long polling subscriber location
location /sub/(.*) {
push_stream_subscriber long-polling;
# positional channel path
set $push_stream_channels_path $1;
}
curl localhost/sub/ch1 #long-polling request
curl localhost/sub/ch1 -H 'X-Nginx-PushStream-Mode:polling' #polling request on a logn-polling location
push_stream_channel_deleted_message_text¶
構文: | push_stream_channel_deleted_message_text string |
---|---|
デフォルト: | “Channel deleted” |
コンテキスト: | http |
リリースバージョン: 0.2.5
The string used on channel deleted message sent to subscribers when the channel is deleted by a publisher.
push_stream_ping_message_text¶
構文: | push_stream_ping_message_text string |
---|---|
デフォルト: | none |
コンテキスト: | http |
リリースバージョン: 0.2.5
購買者に送信されるpingメッセージに使用される文字列。
push_stream_message_ttl¶
構文: | push_stream_message_ttl time |
---|---|
デフォルト: | none |
コンテキスト: | http |
メッセージが期限切れだと見なされる前にキューされることができる時間の長さ。メッセージを期限切れにしたくない場合は、単にこのディレクティブを設定しないでください。
push_stream_max_subscribers_per_channel¶
構文: | push_stream_max_subscribers_per_channel number |
---|---|
デフォルト: | none |
コンテキスト: | http |
channelあたりに受け入れられる購買者の最大数。channelにアクセスする購買者の数を制限したくない場合は、単にこのディレクティブを設定しないでください。
push_stream_max_messages_stored_per_channel¶
構文: | push_stream_max_messages_stored_per_channel number |
---|---|
デフォルト: | none |
コンテキスト: | http |
channelあたりに格納するメッセージの最大数。A channel’s message buffer will retain at most this many most recent messages. 長さによってメッセージが破棄されたくなければ、単にこのディレクティブを設定しないでください。
push_stream_max_channel_id_length¶
構文: | push_stream_max_channel_id_length number |
---|---|
デフォルト: | none |
コンテキスト: | http |
channel idの最大許容長 (文字数)。コレより長いidは 400 Bad Request 応答を受け取るでしょう。channel idの長さを制限したくない場合は、単にこのディレクティブを設定しないでください。
push_stream_ping_message_interval¶
構文: | push_stream_ping_message_interval time |
---|---|
デフォルト: | none |
コンテキスト: | http |
keepaliveメッセージが購買者に送信される時間間隔。pingメッセージを送信したくない場合は、単にこのディレクティブを設定しないでください。
push_stream_subscriber_connection_ttl¶
構文: | push_stream_subscriber_connection_ttl time |
---|---|
デフォルト: | none |
コンテキスト: | http |
接続が期限切れで削除されるまでに購買者が接続し続ける時間の長さ。購買者を自動的に切断したくない場合は、単にこのディレクティブを設定しないでください。しかし、この操作はNGINXが購買者にメッセージを送信するために消費するメモリを再利用するため、リクエストをプールするために割り当てられ、とても重要です
push_stream_max_number_of_channels¶
構文: | push_stream_max_number_of_channels number |
---|---|
デフォルト: | none |
コンテキスト: | http |
サーバ上の同時接続channelの最大数。channelの数を制限したくない場合は、単にこのディレクティブを設定しないでください。
push_stream_max_number_of_broadcast_channels¶
構文: | push_stream_max_number_of_broadcast_channels number |
---|---|
デフォルト: | none |
コンテキスト: | http |
サーバ上の同時接続ブロードキャストchannelの最大数。ブロードキャストchannelの数を制限したくない場合は、単にこのディレクティブを設定しないでください。
push_stream_broadcast_channel_prefix¶
構文: | push_stream_broadcast_channel_prefix string |
---|---|
デフォルト: | none |
コンテキスト: | http |
channelが通常あるいはブロードキャストchannelの場合、識別に使われる接頭辞の文字列。例えば: このディレクティブを bd_
として設定した場合、bd_ch1
がブロードキャストchannelです。
push_stream_store_messages¶
構文: | push_stream_store_messages [ on | off ] |
---|---|
デフォルト: | off |
コンテキスト: | location (push_stream_publisher) |
メッセージキューが有効かどうか。If store messages is “on” is needed to set at least one of these two directives push_stream_message_ttl or push_stream_max_messages_stored_per_channel.
push_stream_authorized_channels_only¶
構文: | push_stream_authorized_channels_only [ on | off ] |
---|---|
デフォルト: | off |
コンテキスト: | location (push_stream_subscriber) |
購買者がpush_stream_subscriber locationへのリクエストをすることでchannelを生成することができるかどうか。onに設定された場合は、発行者は購買者がchannelにメッセージをリクエストすることができる前にPOSTリクエストを送信しなければなりません。そうでなければ、存在しないchannelへの全ての購買者のリクエストは403 Forbidden応答を取得するでしょう。This restriction is not applied to broadcast channels, but to subscribe to a broadcast channel is necessary to subscribe at least to one normal channel, and if this directive is set to on this channel has to be created before.
push_stream_header_template¶
構文: | push_stream_header_template string |
---|---|
デフォルト: | none |
コンテキスト: | location (push_stream_subscriber) |
購買者が活動状態の場合に購買者に送信されるだろうテキスト。
push_stream_message_template¶
構文: | push_stream_message_template string |
---|---|
デフォルト: | ~text~ |
コンテキスト: | location (push_stream_subscriber) |
購買者に送信される前にメッセージを整形するために使われるだろうテキストのテンプレート。テンプレートには任意の数の予約語を含めることができます: ~id~, ~text~, ~channel~ and ~event-id~。例えば: “<script>p(~id~,’~channel~’,’~text~’);</script>”
push_stream_content_type¶
構文: | push_stream_content_type string |
---|---|
デフォルト: | text/plain |
コンテキスト: | location (push_stream_subscriber) |
購買者への応答に使われるコンテントタイプ。a0>push_stream_header_template, push_stream_message_template および push_stream_footer_templateに準拠しなければなりません。
push_stream_broadcast_channel_max_qtd¶
構文: | push_stream_broadcast_channel_max_qtd number |
---|---|
デフォルト: | none |
コンテキスト: | location (push_stream_subscriber) |
購読者がリクエストに署名することができるブロードキャストchannelの最大数。このディレクティブは購読者が一つの通常channelと多くの存在しないブロードキャストchannelに署名する場合のある種の攻撃からサーバを守るために、push_stream_authorized_channels_onlyと連結して動作します。
push_stream_keepalive¶
構文: | push_stream_keepalive [ on | off ] |
---|---|
デフォルト: | off |
コンテキスト: | location (push_stream_publisher, push_stream_channels_statistics) |
リリースバージョン: 0.2.4
購読者あるいはchannelの統計location上のkeepalive接続を有効にします。
push_stream_eventsource_support¶
構文: | push_stream_eventsource_support [ on | off ] |
---|---|
デフォルト: | off |
コンテキスト: | location (push_stream_subscriber) |
リリースバージョン: 0.3.0
購読者のための Event Source サポートを有効にします。
注意¶
このモジュールはメッセージを購読者に送信するために必要な全てを制御します。つまり、ストリーミング接続でのメモリの消費を少なくするためのNGINXのチャンク フィルターを無効にします。
テスト¶
このモジュールのテストはRubyで書かれており、それらは受け入れテストです。それらの実行するには以下の環境が必要です:
* 基本的な要求
- ruby >= 1.8.7
- rubygems >= 1.6.2
- rake >= 0.8.7
* 必要なgem
- POpen4 >= 0.1.4
- em-http-request >= 0.2.14
- json >= 1.4.3
- ruby-debug >= 0.10.4
- jasmine >= 1.0.2.1
- nokogiri >= 1.5.0
これらのgemをbundler(bundlerは事前にインストールされる必要があります。gem install bundler)を使ってこれらのgemをインストールすることができます。
cd test/
bundle install --without docs
あるいは個別に
gem install POpen4 -v 0.1.4
gem install em-http-request -v 0.2.14
gem install json -v 1.4.3
gem install ruby-debug -v 0.10.4
gem install jasmine -v 1.0.2.1
gem install nokogiri -v 1.5.0
そして、rake tests
を発行します。このコマンドはhost localhost および port 9990で応答する1つの workerと/usr/local/nginx/sbin/nginxにあるnginxの executableを使ってテストを実行します。この挙動を返るには以下のコマンドを使用します
rake tests executable="../build/nginx-1.0.5/objs/nginx" # to change default path for nginx executable
rake tests host=my_machine # to change default hostname
rake tests port=9889 # to change default port
rake tests workers=2 # to change dafault number of workers used
これらのパラメータは以下のように組み合わせることができます:
rake tests port=9889 executable="../build/nginx-1.0.5/objs/nginx"
議論¶
NGINX Push Stream Module Discussion Group