Wikibooks

Njs

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

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

主な特徴

編集
  1. JavaScriptによる拡張性 JavaScript を使用してリクエストやレスポンスの内容を操作したり、リクエストルーティングを柔軟にカスタマイズしたりできます。
  2. 軽量で高速 njs は V8 や SpiderMonkey のようなフル機能の JavaScript エンジンではなく、nginx に特化した軽量な実装です。そのため、パフォーマンスを重視する場面でも適しています。
  3. nginx のモジュールとの連携 HTTP、Stream、TCP、UDPなどの nginx モジュールと統合して動作するため、幅広い用途に対応可能です。
  4. シンプルなスクリプト 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年)
  • エラーオブジェクトの実装
  • ファイルシステムアクセスメソッドの追加
  • インタラクティブシェルの追加
  • 関数クロージャーのサポート
  • 厳格モードの強制適用

外部リンク

編集
"https://ja.wikibooks.org/w/index.php?title=Njs&oldid=265867" より作成