nginScript ドキュメント¶
セクション 1: 概要¶
nginScript はNGINXの可能性の進化の次のステージです。現在のところ設計と開発のきわめて早期の段階で、この機能の将来を方向付けるのに役立つフィードバックや示唆を歓迎します。
なぜ？¶
MNGINX is a powerful web server and layer-7 proxy, configured through directives which access functionality in NGINX modules (both built-in and third-party). 変数と条件ブロックにより複雑な設定を定義することができます。NGINXを使って多くのことができますが、最終的にNGINXチームとコミュニティによって構築されたモジュールの創造性と可能性によって天井にぶつかるでしょう。
nginScriptは他の誰もが思いもしないような解決策の構築や問題の解決法を使って、天上を突き破ることができるでしょう。
nginxScriptとは何か¶
nginScriptは二つの部分からなります:
- JavaScript言語の大きなサブセットを実装する独自のVM (仮想マシーン) とバイトコードコンパイラ。現在のJavaScript VMと違い、NGINX VMはNGINX環境のためのおあつらえ向きのものです。JSのスニペットを効率的に実行するためにとても低いスタートアップとティアダウン時間を持ちます。効率的および予測可能なメモリ消費のために、ガベージコレクターではなく短期のメモリプール構造を使用します。Finally, we’re planning a pre-emption capability so that blocking operations (such as an HTTP subrequest) can be suspended and resumed, which aligns perfectly with the event-driven NGINX architecture
- 設定の構文 はNGINX設定の中のJavaScriptのスニペットを埋め込むことができます。これらのスニペットは実行時に評価され、各HTTPトランザクションのコンテキスト内で、もっと強力な条件設定の設定することができ、リクエストおよび応答を編集し、各リクエストに対してNGINXの内部的な操作を正確に制御することができます。
nginScriptは何ではないか¶
nginScriptはアプリケーションサーバではありません。node.jsの代替物あるいは他のどのようなアプリケーションプラットフォームも作成するつもりはありません。nginScript is targeted very firmly at extending the NGINX configuration to give you more control over HTTP traffic.
nginScript は完全ではありませんが、ECMAscriptの標準準拠の実装です。It shares the same syntax and behaviour, but for efficiency and pragmatic reasons, we don’t plan to support the more esoteric parts of the JavaScript language and built-in objects that believe are not necessary for our use cases.
nginScript is not intended to replace or marginalize the excellent and highly-regarded Lua suite of modules for NGINX, or any of the other embedded languages for NGINX. We believe in choice, we believe there’s a gap and an opportunity for JavaScript as an alternative, and we welcome the broad community of extensions to NGINX. It’s community and choice that makes NGINX so strong.
nginxScriptへのEarly-Access¶
nginScriptは early-access プロジェクトとして利用可能です。それはアルファ品質の外部モジュールで、実装を開発およびフィードバックを組み込むに連れて、機能および設定の構文は変わるかも知れません。自身のリスクの下に使用してください。しかしフィードバックとアイデアは歓迎します。
セクション 2: nginScriptモジュールのインストール¶
インストールの説明:
# http://nginx.org/en/download.html からNGINXの最新ソースを取得します
$ wget http://nginx.org/download/nginx-1.9.4.tar.gz
$ tar -xzvf nginx-1.9.4.tar.gz
# nginScriptの開発ソースを取得します
$ hg clone http://hg.nginx.org/njs
# NGINXをビルドおよびインストールする
$ cd nginx-1.9.4
$ ./configure --add-module=../njs/nginx --prefix=/your/installation/directory
$ make
$ make install
NGINXおよびサードパーティモジュールのコンパイルについての詳細は、http://nginx.org/en/docs/configure.htmlを参照してください。
セクション 3: nginScriptを開始する¶
nginScriptのearly-access リリースでは、幾つかのことができます。
変数¶
js_setを使って変数を宣言することができます:
js_set $msg "
var m = 'Hello ';
m += 'world!';
m;
";
これらの変数はNGINX設定ディレクティブで使うことができます。変数が使用された時にJavaScriptコードが評価されます:
location /hello {
add_header Content-Type text/plain;
return 200 $msg;
}
コンテントの生成¶
js_run ディレクティブは content-generation ステージで評価されます。JavaScriptをnativelyに実行するために使われ、HTTP応答を生成します:
location /hello {
js_run "
var res;
res = $r.response;
res.contentType = 'text/plain';
res.status = 200;
res.sendHeader();
res.send( 'Hello, world!' );
res.finish();
";
}
リクエストオブジェクト¶
nginScript環境はリクエストオブジェクト、$rとして指定される、を提供します。このオブジェクトのプロパティを読み込みおよび設定をすることができ、リクエストにアクセスおよび修正するために提供するメソッドを使うことができます。
js_set $summary "
var a, s, h;
s = ‘Request summary\n\n';
s += 'Method: ' + $r.method + '\n';
s += 'HTTP version: ' + $r.httpVersion + '\n';
s += 'Host: ' + $r.headers.host + '\n';
s += 'Remote Address: ' + $r.remoteAddress + '\n';
s += 'URI: ' + $r.uri + '\n';
s += 'Headers:\n';
for (h in $r.headers) {
s += ' header \"' + h + '\" is \"' + $r.headers[h] + '\"\n';
}
s += 'Args:\n';
for (a in $r.args) {
s += ' arg \"' + a + '\" is \"' + $r.args[a] + '\"\n';
}
s;
";
応答オブジェクト¶
現在の $r リクエストオブジェクトから応答オブジェクトを取得することができ、変数の評価あるいはコンテントの生成の間に応答を生成することができます。
js_run "
var res;
res = $r.response;
res.contentType = 'text/plain';
res.status = 200;
res.sendHeader();
res.send( 'Hello, world!' );
res.finish();
";
Bringing it all together¶
以下の例は、リクエストのクエリ文字列からパラメータを取得し、応答を生成する方法を説明します。
location /fib {
js_run "
function f( n ) { return ( n < 2 ) ? 1: f( n-1 ) + f( n-2 ) ; }
var nn = $r.args['n'];
// nn++ is a hack to convert nn to an integer
var n = nn++;
var msg = 'Fibonacci( ' + n + ' ) = ' + f( n );
var res = $r.response;
res.contentType = 'text/plain';
res.status = 200;
res.sendHeader();
res.send( msg );
res.send( '\n' );
res.finish();
";
}
セクション 4: ドキュメント¶
構文および実行¶
変数が評価される時のJavaScript変数の構文 (および実行されるJSコード)
調整と設定¶
nJSのための調整あるいは設定
警告と制限¶
nginScript はJS言語のサブセットをサポートします。
Specific exclusions (e.g. no closures, no eval, etc)
JS/ECMAscript標準の完全な実装を作成することは私たちの目的ではありません。Implement sufficient functionality that users can create sophisticated rules in NGINX to control how requests and responses are processed.
もっと多くの例¶
共有できる完全な他の例はありますか？
フィードバック - して欲しいこと¶
フィードバックを共有する場所 nginx-devel@nginx.org。
What sort of feedback we’re interested in: suggestions for future features recommendations on architectural improvements
注意
これはnginScriptのearly-accessリリースです。コードは頻繁に変更されるため、現在のところコードの貢献あるいはパッチのレビューと受領できる状態ではありません。