Njs

nginx JavaScript module (njs) は、nginx に JavaScript のサポートを追加するモジュールで、nginx におけるリクエスト処理やレスポンス処理を柔軟にカスタマイズできるようにするための仕組みです。

このモジュールを使用すると、nginx の設定ファイル内で JavaScript を使用して処理を記述できるようになります。njs は nginx に最適化された軽量な JavaScript インタープリタであり、nginx のパフォーマンスを損なわないように設計されています。

主な特徴

JavaScriptによる拡張性 JavaScript を使用してリクエストやレスポンスの内容を操作したり、リクエストルーティングを柔軟にカスタマイズしたりできます。
軽量で高速 njs は V8 や SpiderMonkey のようなフル機能の JavaScript エンジンではなく、nginx に特化した軽量な実装です。そのため、パフォーマンスを重視する場面でも適しています。
nginx のモジュールとの連携 HTTP、Stream、TCP、UDPなどの nginx モジュールと統合して動作するため、幅広い用途に対応可能です。
シンプルなスクリプト JavaScript の構文を使用してスクリプトを記述するため、学習コストが低いです。

使える場面

リクエストのリダイレクトやリライト
レスポンスの内容を動的に変更
カスタム認証ロジック
APIゲートウェイとしての動的なルーティング
TCPやUDP通信のプロキシ処理

ダウンロードとインストール

パッケージマネージャーを使用したインストール

FreeBSDでは:

doas pkg install lang/njs
または
doas make -C /usr/ports/lang/njs all install clean

Ubuntuおよびその他のDebianベースのシステムでは:

sudo apt-get install nginx-module-njs

CentOSおよびその他のRHELベースのシステムでは:

sudo yum install nginx-module-njs

ソースからのビルド

最新のソースコードからビルドする場合:

git clone https://github.com/nginx/njs.git
cd njs
./configure
make
sudo make install

リファレンス

主要な機能

HTTP/HTTPSリクエストの処理
ストリーム（TCP/UDP）の処理
非同期プログラミング
JSONの処理
ファイルシステムの操作
クエリパラメータの処理

コア関数

ngx.log(level, message) - ログメッセージの出力
ngx.fetch(url, options) - HTTPリクエストの実行
ngx.sleep(delay) - 指定時間の待機
ngx.encode_uri(uri) - URIのエンコード
ngx.decode_uri(uri) - URIのデコード

JavaScriptエンジン

njsは独自のJavaScriptエンジンを使用しており、以下の特徴があります：

ECMAScript 5.1互換
一部のECMAScript 6+機能をサポート
メモリ効率を重視した設計
最小限の依存関係

例

基本的なHTTPハンドラ

function hello(r) {
    r.return(200, "Hello from njs!");
}

export default {hello}

JSONレスポンス

function api(r) {
    r.headersOut['Content-Type'] = 'application/json';
    r.return(200, JSON.stringify({
        status: "success",
        message: "API response"
    }));
}

export default {api}

セキュリティ

推奨プラクティス

入力の検証と無害化
適切な権限設定
セキュアなHTTPヘッダーの使用
エラー情報の適切な制限

一般的な脆弱性対策

XSS（クロスサイトスクリプティング）対策
CSRF（クロスサイトリクエストフォージェリ）対策
インジェクション攻撃対策

互換性

サポートされているnginxバージョン

nginx 1.20.0以降
nginx Plus R20以降

プラットフォーム互換性

Linux（主要なディストリビューション）
FreeBSD
macOS
Windows（制限付き）

コマンドラインインターフェース

njs CLIツール

;njs [options] [script]

オプション：

-v, --version - バージョン情報の表示
-p, --parse - スクリプトの構文解析
-c, --cmd - コマンドの実行

プリロードされたオブジェクトの理解

グローバルオブジェクト

console - ログ出力用オブジェクト
process - プロセス情報
require - モジュール読み込み

nginxオブジェクト

ngx - コア機能へのアクセス
r - リクエストオブジェクト

テスト済みOSとプラットフォーム

Linux

Ubuntu 18.04 LTS以降
CentOS 7以降
Debian 10以降

その他のプラットフォーム

FreeBSD 12以降
macOS 10.15以降
Windows Server 2016以降

ngx_http_js_module

HTTPリクエスト処理用のモジュールで、以下の機能を提供：

主な機能

HTTPリクエストの処理
レスポンスの生成
ヘッダーの操作
クッキーの処理

ngx_stream_js_module

TCPおよびUDPストリーム処理用のモジュールです：

主な機能

ストリーム接続の処理
プロキシ機能
ロードバランシング
セッション管理

TypeScript定義ファイルを使用したnjsコードの記述

セットアップ

npm install --save-dev @types/njs

使用例

import { NginxHTTPRequest, NginxHTTPResponse } from '@types/njs';

function handleRequest(r: NginxHTTPRequest): void {
    r.return(200, "TypeScript integration example");
}

設定例

以下は、リクエストヘッダーを変更する簡単な例です。

JavaScript スクリプトを記述

/etc/nginx/conf.d/script.js

function modifyHeaders(r) {
    r.headersOut['X-Custom-Header'] = 'Hello from njs';
    r.return(200, 'Header modified');
}

nginx 設定ファイルを編集

/etc/nginx/nginx.conf

http {
    js_include /etc/nginx/conf.d/script.js;
    server {
        listen 8080;

        location / {
            js_content modifyHeaders;
        }
    }
}

nginx をリロード

sudo nginx -s reload

HTTPとStreamモジュールでの使用

HTTP モジュールでは、リクエストやレスポンスを操作するための js_content や js_set ディレクティブを使用します。
Stream モジュールでは、TCP や UDP 接続を処理するための js_preread や js_filter ディレクティブを使用します。

Node.jsモジュールのnjsでの使用

制限事項

一部のNode.jsモジュールのみサポート
ネイティブモジュールは非サポート
特定のAPIの制限

互換性のあるモジュール

純JavaScript実装のモジュール
最小限の依存関係を持つモジュール
njsの制限に適合するモジュール

まとめ

nginx JavaScript module (njs) は、nginx の高性能を維持しつつ、柔軟なカスタマイズを可能にする軽量なツールです。特に動的なリクエスト処理やカスタムロジックが必要な場面で便利です。ただし、複雑なスクリプトを実行する場合にはその制限を考慮し、設計を工夫する必要があります。

附録

変更履歴

2024年12月のnjs 0.8.8から2016年のnjs 0.1.xまでの主な変更点を要約します：

njs 0.8.8 (2024年12月)

QuickJSエンジン用の共有ディクショナリを実装
プロセスオブジェクトとkill()メソッドを実装
各種バグ修正

njs 0.8.7 (2024年10月)

fs.readlinkSync()の実装
メモリ使用量の最適化
バッファ関連のバグ修正

njs 0.8.6 (2024年10月)

QuickJSエンジンの導入
HTTPモジュールでキャプチャグループ変数のサポート
バッファモジュールの追加

njs 0.8.5 (2024年6月)

UTF-8エンコーディングの改善
共有ディクショナリのタイムアウト機能追加
ヘッダー処理の修正

njs 0.8.4 (2024年4月)

サーバーヘッダーの設定機能追加
CLIでのQuickJSエンジンサポート
Base64処理の改善

njs 0.8.3 (2024年2月)

ヘッダー処理の改善
日付処理やパース処理など、複数のバグ修正

njs 0.8.0 (2023年7月)

js_includeディレクティブの非推奨化
共有ディクショナリ機能の導入
nginxのグローバルプロパティの拡張

njs 0.7.12 (2023年4月)

Fetch APIのHeaders()コンストラクタの修正
crypto.Hash.copy()メソッドの追加
zlibモジュールの追加

njs 0.7.11 (2023年3月)

XMLノードAPIの追加でXML文書の編集が可能に
セキュリティ上の理由でXML_PARSE_DTDVALIDを無効化
文字列処理などの複数のバグ修正

njs 0.7.10 (2023年2月)

Fetch APIにRequest、Response、Headersコンストラクタを追加
XMLモジュールの追加
WebCrypto APIの機能拡張（JWKフォーマットのサポートなど）

njs 0.7.9 - 0.7.7 (2022年8月-11月)

js_preload_objectディレクティブの追加
非同期コールバックのサポート改善
nginxの設定コンテキストでのjsディレクティブの拡張

njs 0.7.6以前 (2022年7月以前)

Promise関連機能の実装
async/await機能の実装
WebCrypto APIの実装
テンプレートリテラルのサポート
アロー関数のサポート

njs 0.6.x シリーズ (2021年)

letとconstの宣言サポート
RegExpの機能強化
Promise関連メソッドの追加（Promise.all()など）
AggregateErrorの実装
テンプレートリテラルのサポート

njs 0.5.x シリーズ (2020-2021年)

グローバルngxオブジェクトの導入
Fetch APIの初期実装
js_header_filterディレクティブの追加
Bufferオブジェクトのサポート
TypeScript定義の追加

njs 0.4.x シリーズ (2020年)

クエリ文字列モジュールの追加
TextDecoderとTextEncoderの実装
マルチ値ヘッダーのサポート
fs（ファイルシステム）モジュールの拡張
レスポンスヘッダー処理の改善

njs 0.3.x シリーズ (2019年)

ES6モジュールの初期サポート
アロー関数のサポート
Object関連メソッドの拡張
プロパティgetter/setterのサポート
processグローバルオブジェクトの追加

njs 0.2.x シリーズ (2018年)

argumentsオブジェクトのサポート
JSONオブジェクトの実装
タイムアウト機能の追加
暗号化関連機能の追加
HTTPサブリクエスト機能の追加

njs 0.1.x シリーズ (2016-2017年)

エラーオブジェクトの実装
ファイルシステムアクセスメソッドの追加
インタラクティブシェルの追加
関数クロージャーのサポート
厳格モードの強制適用

外部リンク

[nginx JavaScript module]