ngx_http_js_module モジュール
ngx_http_js_module
モジュールはnjs - JavaScript言語のサブセット、での場所と変数のハンドラを実装するために使われます。
ダウンロードとインストールの説明はここで利用可能です。
設定例
この例は、0.4.0以降で動作します。
http { js_import http.js; js_set $foo http.foo; js_set $summary http.summary; js_set $hash http.hash; resolver 10.0.0.1; server { listen 8000; location / { add_header X-Foo $foo; js_content http.baz; } location = /summary { return 200 $summary; } location = /hello { js_content http.hello; } # since 0.7.0 location = /fetch { js_content http.fetch; js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem; } # since 0.7.0 location = /crypto { add_header Hash $hash; return 200; } } }
The http.js
file:
function foo(r) { r.log("hello from foo() handler"); return "foo"; } function summary(r) { var a, s, h; s = "JS summary\n\n"; s += "Method: " + r.method + "\n"; s += "HTTP version: " + r.httpVersion + "\n"; s += "Host: " + r.headersIn.host + "\n"; s += "Remote Address: " + r.remoteAddress + "\n"; s += "URI: " + r.uri + "\n"; s += "Headers:\n"; for (h in r.headersIn) { s += " header '" + h + "' is '" + r.headersIn[h] + "'\n"; } s += "Args:\n"; for (a in r.args) { s += " arg '" + a + "' is '" + r.args[a] + "'\n"; } return s; } function baz(r) { r.status = 200; r.headersOut.foo = 1234; r.headersOut['Content-Type'] = "text/plain; charset=utf-8"; r.headersOut['Content-Length'] = 15; r.sendHeader(); r.send("nginx"); r.send("java"); r.send("script"); r.finish(); } function hello(r) { r.return(200, "Hello world!"); } // since 0.7.0 async function fetch(r) { let results = await Promise.all([ngx.fetch('https://nginx.org/'), ngx.fetch('https://nginx.org/en/')]); r.return(200, JSON.stringify(results, undefined, 4)); } // since 0.7.0 async function hash(r) { let hash = await crypto.subtle.digest('SHA-512', r.headersIn.host); r.setReturnValue(Buffer.from(hash).toString('hex')); } export default {foo, summary, baz, hello, fetch, hash};
ディレクティブ
構文: |
js_body_filter |
---|---|
デフォルト: | - |
コンテキスト: |
location , limit_except |
このディレクティブはバージョン0.5.2から導入されました。
応答ボディフィルタとしてnfs関数を設定します。フィルタ関数は、以下の引数を使って応答ボディの各データチャンクに対して呼ばれます:
r
- HTTPリクエストオブジェクト
data
-
着信データチャンク。
buffer_type
の値に応じて文字列またはバッファになります。デフォルトは文字列です。 flags
-
以下のプロパティを持つオブジェクト:
last
- boolean 値。データが最後のバッファの場合はtrue。
フィルタ関数は、r.sendBuffer()
を呼び出すことで、入力データチャンクの独自の変更バージョンを次のボディフィルタに渡すことができます。例えば、応答ボディの全ての小文字を変換するには:
function filter(r, data, flags) { r.sendBuffer(data.toLowerCase(), flags); }
フィルタリングを停止するには(次のデータチャンクはjs_body_filter
を呼ばずにクライアントに渡されます)、r.done()
を使えます。
フィルタ関数が応答ボディの長さを変更する場合、js_header_filter
の“Content-Length”応答ヘッダ(存在する場合)をクリアして、チャンク化転送エンコーディングを強制する必要があります。
js_body_filter
ハンドラはすぐに結果を返すため、同期操作のみをサポートします。従って、r.subrequest()やsetTimeout()のような非同期操作はサポートされません。
構文: |
js_content |
---|---|
デフォルト: | - |
コンテキスト: |
location , limit_except |
場所のコンテントハンドラとしてnjs関数を設定します。0.4.0以降、モジュール関数を参照できます。
構文: |
js_fetch_buffer_size |
---|---|
デフォルト: |
js_fetch_buffer_size 16k; |
コンテキスト: |
http , server , location |
このディレクティブはバージョン0.7.4から導入されました。
Fetch APIを使って読み書きするためのバッファのsize
を設定します。
構文: |
js_fetch_ciphers |
---|---|
デフォルト: |
js_fetch_ciphers HIGH:!aNULL:!MD5; |
コンテキスト: |
http , server , location |
このディレクティブはバージョン0.7.0から導入されました。
Fetch APIを使ったHTTPSリクエストのために有効にされたcipherを指定します。cipherはOpenSSLライブラリで理解される形式で指定されます。
全てのリストは"openssl ciphers
"コマンドを使ってみることができます。
構文: |
js_fetch_max_response_buffer_size |
---|---|
デフォルト: |
js_fetch_max_response_buffer_size 1m; |
コンテキスト: |
http , server , location |
このディレクティブはバージョン0.7.4から導入されました。
Fetch APIを使って受信された応答の最大size
を設定します。
構文: |
js_fetch_protocols
[ |
---|---|
デフォルト: |
js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2; |
コンテキスト: |
http , server , location |
このディレクティブはバージョン0.7.0から導入されました。
Fetch APIを使ったHTTPSリクエストのために指定されたプロトコルを有効にします。
構文: |
js_fetch_timeout |
---|---|
デフォルト: |
js_fetch_timeout 60s; |
コンテキスト: |
http , server , location |
このディレクティブはバージョン0.7.4から導入されました。
Fetch APIのための読み書きのためのタイムアウトを定義します。タイムアウトは二つの連続する読み込み/書き込み操作の間に設定され、応答全体の転送のためのものではありません。この時間の間に何もデータが転送されない場合、接続は閉じられます。
構文: |
js_fetch_trusted_certificate |
---|---|
デフォルト: | - |
コンテキスト: |
http , server , location |
このディレクティブはバージョン0.7.0から導入されました。
Fetch APIのHTTPS証明書をverifyするために使われるPEM形式の信頼されたCA証明書のfile
を指定します。
構文: |
js_fetch_verify |
---|---|
デフォルト: |
js_fetch_verify on; |
コンテキスト: |
http , server , location |
このディレクティブはバージョン0.7.4から導入されました。
Fetch APIの証明書の検証を有効または無効にします。
構文: |
js_fetch_verify_depth |
---|---|
デフォルト: |
js_fetch_verify_depth 100; |
コンテキスト: |
http , server , location |
このディレクティブはバージョン0.7.0から導入されました。
Fetch APIの連鎖証明書の検証の深さを設定します。
構文: |
js_header_filter |
---|---|
デフォルト: | - |
コンテキスト: |
location , limit_except |
このディレクティブはバージョン0.5.1から導入されました。
応答ヘッダフィルタとしてnfs関数を設定します。このディレクティブを使って応答ヘッダの任意のヘッダフィールドを変更できます。
js_header_filter
ハンドラはすぐに結果を返すため、同期操作のみをサポートします。従って、r.subrequest()やsetTimeout()のような非同期操作はサポートされません。
構文: |
js_import |
---|---|
デフォルト: | - |
コンテキスト: |
http |
このディレクティブはアb―ジョン0.4.0で導入されました。
njs内のlocationと変数を実装するモジュールをインポートします。export_name
は、モジュール関数にアクセスするための名前空間として使います。export_name
が指定されない場合、モジュール名が名前空間として使われます。
js_import http.js;
ここで、モジュール名http
はエクスポートにアクセスする時に名前空間として使われます。インポートされたモジュールがfoo()
をエクスポートする場合、http.foo
はそれを参照するために使われます。
いくつかのjs_import
ディレクティブを指定できます。
構文: |
js_include |
---|---|
デフォルト: | - |
コンテキスト: |
http |
njs内のlocationと変数のハンドラを実装するファイルを指定します:
nginx.conf: js_include http.js; location /version { js_content version; } http.js: function version(r) { r.return(200, njs.version); }
このディレクティブはバージョン0.4.0 で非推奨になり、0.7.1で削除されました。代わりにjs_import ディレクティブが使われるべきです。
構文: |
js_path
|
---|---|
デフォルト: | - |
コンテキスト: |
http |
このディレクティブはバージョン0.3.0から導入されました。
njsモジュールの追加のパスをせっていします。
構文: |
js_set
|
---|---|
デフォルト: | - |
コンテキスト: |
http |
特定の変数
のためにnjsfunction
を設定します。0.4.0以降、モジュール関数を参照できます。
この関数は、特定のリクエストで変数が初めて参照された時に呼び出されます。正確な瞬間は、変数が参照されるphase によって異なります。これは、変数の評価に関係のないロジックを実行するために使えます。例えば、変数がlog_formatディレクティブでのみ参照されている場合、そのハンドラはログフェーズまで実行されません。このハンドラはリクエストが解放される直前になんらかのクリーンアップを行うために使えます。
js_set
ハンドラはすぐに結果を返すため、同期操作のみをサポートします。従って、r.subrequest()やsetTimeout()のような非同期操作はサポートされません。
構文: |
js_var |
---|---|
デフォルト: | - |
コンテキスト: |
http |
このディレクティブはバージョン0.5.3から導入されました。
writable変数を宣言します。値には、テキスト、変数、およびそれらの組み合わせを含めることができます。setディレクティブで作成された変数とは異なり、変数はリダイレクト後に上書きされません。
リクエストの引数
各HTTP njsヘッダは1つの引数、リクエストオブジェクトを受け取ります。