モジュール ngx_stream_js_module

ngx_stream_js_moduleモジュールは、JavaScript言語のサブセットであるnjsでハンドラを実装するために使用されます。

ダウンロードとインストールの手順はこちらにあります。

この例は0.4.0以降で動作します。

stream {
    js_import stream.js;

    js_set $bar stream.bar;
    js_set $req_line stream.req_line;

    server {
        listen 12345;

        js_preread stream.preread;
        return     $req_line;
    }

    server {
        listen 12346;

        js_access  stream.access;
        proxy_pass 127.0.0.1:8000;
        js_filter  stream.header_inject;
    }
}

http {
    server {
        listen 8000;
        location / {
            return 200 $http_foo\n;
        }
    }
}

stream.jsファイル

var line = '';

function bar(s) {
    var v = s.variables;
    s.log("hello from bar() handler!");
    return "bar-var" + v.remote_port + "; pid=" + v.pid;
}

function preread(s) {
    s.on('upload', function (data, flags) {
        var n = data.indexOf('\n');
        if (n != -1) {
            line = data.substr(0, n);
            s.done();
        }
    });
}

function req_line(s) {
    return line;
}

// Read HTTP request line.
// Collect bytes in 'req' until
// request line is read.
// Injects HTTP header into a client's request

var my_header =  'Foo: foo';
function header_inject(s) {
    var req = '';
    s.on('upload', function(data, flags) {
        req += data;
        var n = req.search('\n');
        if (n != -1) {
            var rest = req.substr(n + 1);
            req = req.substr(0, n + 1);
            s.send(req + my_header + '\r\n' + rest, flags);
            s.off('upload');
        }
    });
}

function access(s) {
    if (s.remoteAddress.match('^192.*')) {
        s.deny();
        return;
    }

    s.allow();
}

export default {bar, preread, req_line, header_inject, access};

アクセスフェーズで呼び出されるnjs関数を設定します。0.4.0以降、モジュール関数を参照できます。

この関数は、ストリームセッションが初めてアクセスフェーズに到達した時点で1回呼び出されます。関数は、以下の引数を使用して呼び出されます。

s

ストリームセッションオブジェクト

このフェーズでは、初期化を実行したり、s.allow()、s.decline()、s.done()のいずれかのメソッドが呼び出されるまで、受信データチャンクごとにs.on()メソッドを使用してコールバックを登録できます。これらのメソッドのいずれかが呼び出されるとすぐに、ストリームセッション処理は次のフェーズに切り替わり、現在のs.on()コールバックはすべて削除されます。

js_context_reuse 128;

QuickJSエンジンで再利用されるJSコンテキストの最大数を設定します。各コンテキストは単一のストリームセッションで使用されます。終了したコンテキストは、再利用可能なコンテキストのプールに入れられます。プールがいっぱいになっている場合、コンテキストは破棄されます。

js_engine njs;

njsスクリプトで使用されるJavaScriptエンジンを設定します。njsパラメータは、デフォルトでも使用されるnjsエンジンを設定します。qjsパラメータはQuickJSエンジンを設定します。

js_fetch_buffer_size 16k;

Fetch APIで読み書きに使用されるバッファのサイズを設定します。

js_fetch_ciphers HIGH:!aNULL:!MD5;

Fetch APIを使用したHTTPS接続で有効にする暗号を指定します。暗号は、OpenSSLライブラリで認識される形式で指定します。

完全なリストは、「openssl ciphers」コマンドを使用して表示できます。

js_fetch_max_response_buffer_size 1m;

Fetch APIで受信した応答の最大サイズを設定します。

js_fetch_protocols TLSv1 TLSv1.1 TLSv1.2;

Fetch APIを使用したHTTPS接続で指定されたプロトコルを有効にします。

js_fetch_timeout 60s;

Fetch APIの読み書きのタイムアウトを定義します。タイムアウトは、2つの連続した読み書き操作の間のみに設定され、応答全体には設定されません。この時間内にデータが送信されない場合、接続は閉じられます。

Fetch APIでHTTPS証明書を検証するために使用される、PEM形式の信頼できるCA証明書を含むファイルを指定します。

js_fetch_verify on;

Fetch APIでHTTPSサーバー証明書の検証を有効または無効にします。

js_fetch_verify_depth 100;

Fetch APIでHTTPSサーバー証明書チェーンの検証深度を設定します。

データフィルタを設定します。0.4.0以降、モジュール関数を参照できます。フィルタ関数は、ストリームセッションがコンテンツフェーズに到達した時点で1回呼び出されます。

フィルタ関数は、以下の引数を使用して呼び出されます。

s

ストリームセッションオブジェクト

このフェーズでは、初期化を実行したり、受信データチャンクごとにs.on()メソッドを使用してコールバックを登録できます。s.off()メソッドを使用してコールバックの登録を解除し、フィルタリングを停止できます。

js_filterハンドラは結果をすぐに返すため、同期操作のみをサポートしています。そのため、ngx.fetch()やsetTimeout()などの非同期操作はサポートされていません。

ロケーションと変数ハンドラを実装するモジュールをインポートします。export_nameは、モジュール関数にアクセスするための名前空間として使用されます。export_nameを指定しない場合、モジュール名が名前空間として使用されます。

js_import stream.js;

ここでは、エクスポートにアクセスする際にstreamというモジュール名が名前空間として使用されます。インポートされたモジュールがfoo()をエクスポートする場合、stream.fooを使用して参照します。

複数のjs_importディレクティブを指定できます。

0.7.7以降、このディレクティブはserverレベルで指定できます。

njsでサーバーと変数ハンドラを実装するファイルを指定します。

nginx.conf:
js_include stream.js;
js_set     $js_addr address;
server {
    listen 127.0.0.1:12345;
    return $js_addr;
}

stream.js:
function address(s) {
    return s.remoteAddress;
}

このディレクティブはバージョン0.4.0で非推奨となり、バージョン0.7.1で削除されました。js_importディレクティブを使用してください。

njsモジュールの追加パスを設定します。

0.7.7以降、このディレクティブはserverレベルで指定できます。

定期的な間隔で実行されるコンテンツハンドラを指定します。ハンドラは、最初の引数としてセッションオブジェクトを受信し、ngxなどのグローバルオブジェクトにもアクセスできます。

オプションのintervalパラメータは、2回連続した実行の間隔を設定します。デフォルトは5秒です。

オプションのjitterパラメータは、ロケーションコンテンツハンドラがランダムに遅延する時間を設定します。デフォルトでは遅延はありません。

デフォルトでは、js_handlerはワーカープロセス0で実行されます。オプションのworker_affinityパラメータを使用すると、ロケーションコンテンツハンドラを実行する特定のワーカープロセスを指定できます。各ワーカープロセスのセットは、許可されたワーカープロセスのビットマスクで表されます。allマスクを使用すると、すべてのワーカープロセスでハンドラを実行できます。

例

example.conf:

location @periodics {
    # to be run at 1 minute intervals in worker process 0
    js_periodic main.handler interval=60s;

    # to be run at 1 minute intervals in all worker processes
    js_periodic main.handler interval=60s worker_affinity=all;

    # to be run at 1 minute intervals in worker processes 1 and 3
    js_periodic main.handler interval=60s worker_affinity=0101;

    resolver 10.0.0.1;
    js_fetch_trusted_certificate /path/to/ISRG_Root_X1.pem;
}

example.js:

async function handler(s) {
    let reply = await ngx.fetch('https://nginx.dokyumento.jp/en/docs/njs/');
    let body = await reply.text();

    ngx.log(ngx.INFO, body);
}

設定時に不変オブジェクトをプリロードします。nameは、njsコードでオブジェクトが使用できるグローバル変数の名前として使用されます。nameを指定しない場合、ファイル名が代わりに使用されます。

js_preload_object map.json;

ここでは、プリロードされたオブジェクトにアクセスする際にmapが名前として使用されます。

複数のjs_preload_objectディレクティブを指定できます。

prereadフェーズで呼び出されるnjs関数を設定します。0.4.0以降、モジュール関数を参照できます。

この関数は、ストリームセッションが初めてprereadフェーズに到達した時点で1回呼び出されます。関数は、以下の引数を使用して呼び出されます。

s

ストリームセッションオブジェクト

このフェーズでは、初期化を実行したり、s.allow()、s.decline()、s.done()のいずれかのメソッドが呼び出されるまで、受信データチャンクごとにs.on()メソッドを使用してコールバックを登録できます。これらのメソッドのいずれかが呼び出されると、ストリームセッションは次のフェーズに切り替わり、現在のs.on()コールバックはすべて削除されます。

js_prereadハンドラは結果をすぐに返すため、同期コールバックのみをサポートしています。そのため、ngx.fetch()やsetTimeout()などの非同期コールバックはサポートされていません。ただし、prereadフェーズでは、s.on()コールバックで非同期操作がサポートされています。詳細についてはこの例を参照してください。

指定された変数に対してnjs関数を設定します。0.4.0以降、モジュール関数を参照できます。

この関数は、特定のリクエストに対して変数が初めて参照されたときに呼び出されます。正確なタイミングは、変数が参照されるフェーズによって異なります。これは、変数の評価とは関係のないロジックを実行するために使用できます。たとえば、変数がlog_formatディレクティブでのみ参照される場合、そのハンドラはログフェーズまで実行されません。このハンドラを使用して、リクエストが解放される直前にクリーンアップを実行できます。

0.8.6以降、オプションの引数nocacheが指定されている場合、ハンドラは参照されるたびに呼び出されます。rewriteモジュールの現在の制限により、setディレクティブでnocache変数が参照される場合、そのハンドラは常に固定長の値を返す必要があります。

js_setハンドラは結果をすぐに返すため、同期コールバックのみをサポートしています。そのため、ngx.fetch()やsetTimeout()などの非同期コールバックはサポートされていません。

0.7.7以降、このディレクティブはserverレベルで指定できます。

ワーカープロセス間で共有されるキーバリューディクショナリを保持する共有メモリゾーンの名前とサイズを設定します。

デフォルトでは、共有ディクショナリはキーとして文字列、値として文字列を使用します。オプションのtypeパラメータを使用すると、値の型を数値に再定義できます。

オプションのtimeoutパラメータは、すべての共有ディクショナリエントリがゾーンから削除されるまでの時間をミリ秒単位で設定します。一部のエントリに異なる削除時間が必要な場合は、add、incr、setメソッドのtimeout引数を使用して設定できます(0.8.5)。

オプションのevictパラメータは、ゾーンストレージが不足している場合に、最も古いキーバリューペアを削除します。

例

example.conf:
    # Creates a 1Mb dictionary with string values,
    # removes key-value pairs after 60 seconds of inactivity:
    js_shared_dict_zone zone=foo:1M timeout=60s;

    # Creates a 512Kb dictionary with string values,
    # forcibly removes oldest key-value pairs when the zone is exhausted:
    js_shared_dict_zone zone=bar:512K timeout=30s evict;

    # Creates a 32Kb permanent dictionary with number values:
    js_shared_dict_zone zone=num:32k type=number;

example.js:
    function get(r) {
        r.return(200, ngx.shared.foo.get(r.args.key));
    }

    function set(r) {
        r.return(200, ngx.shared.foo.set(r.args.key, r.args.value));
    }

    function del(r) {
        r.return(200, ngx.shared.bar.delete(r.args.key));
    }

    function increment(r) {
        r.return(200, ngx.shared.num.incr(r.args.key, 2));
    }

書き込み可能な変数を宣言します。値には、テキスト、変数、およびそれらを組み合わせたものを指定できます。

0.7.7以降、このディレクティブはserverレベルで指定できます。

各ストリームnjsハンドラは、ストリームセッションオブジェクトを1つの引数として受け取ります。