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_publisherpush_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_shared_memory_size

構文:push_stream_shared_memory_size size
デフォルト:32M
コンテキスト:http

このモジュールが発行したメッセージ、channelおよび他の共有構造を格納するために使われるメモリーチャンクのサイズ。このメモリが一杯になると、メッセージの発行あるいはchannelの購読のためのどのような新しいリクエストも500 Internal Server Errorメッセージを受け取るでしょう。

push_stream_shared_memory_cleanup_objects_ttl

構文:push_stream_shared_memory_cleanup_objects_ttl time
デフォルト:30 seconds
コンテキスト:http

The length of time a message or a channel will stay on garbage collection area before it is completly discarded, freeing the shared memory. 誰もこれらの要素を使わないようにするための最小の長さは30秒です。この操作はNGINXがメッセージやchannelを生成するために消費するメモリを再利用するためにとても重要です。そのため長い時間を使わないでください。

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

貢献

People