コンテンツにスキップ
|
Kong Gateway
3.7.x
report-issue問題を報告する
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

JavaScript でプラグインを書く

JavaScript言語の Kong Gatewayサポートは、JavaScript PDKによって提供されます。ライブラリはKong GatewayのJavaScriptバインディングのランタイムを提供するプラグインサーバーを提供します。

TypeScriptは以下の方法でもサポートされています。

  • TypeScriptでプラグインを開発する場合、PDKには、型チェックを可能にするPDK関数の型定義が含まれています。
  • TypeScriptで記述されたプラグインは、 Kong Gatewayに直接ロードしてトランスパイルできます。

インストール

JavaScript PDKは、npmを使用してインストールできます。プラグインサーバーバイナリをインストールするには、次のコマンドを実行します。

npm install kong-pdk -g

開発

有効なJavaScriptプラグインの実装では、通常、次のオブジェクトをエクスポートします。

module.exports = {
  Plugin: KongPlugin,
  Schema: [
    { message: { type: "string" } },
  ],
  Version: '0.1.0',
  Priority: 0,
}
  • Plugin属性は、このプラグインを実装するクラスを定義します。
  • Schemaは、プラグインの構成スキーマを定義します。
  • VersionとPriorityの変数には、バージョン番号と実行の優先順位が設定されます。

注 : このリポジトリには、JavaScript でビルドしたプラグインの例が含まれています。

フェーズハンドラー

実行するカスタムロジックを実装できます。 リクエスト処理ライフサイクルのさまざまなポイント。アクセスフェーズの カスタム JavaScript コードを実行するには、 accessという名前の関数を定義します。

class KongPlugin {
  constructor(config) {
    this.config = config
  }
  async access(kong) {
    // ...
  }
}

同じ関数シグネチャを使用して、以下のフェーズ中にカスタムロジックを実装できます。

  • certificate
  • rewrite
  • access
  • response
  • preread
  • log

responseハンドラが存在すると、プロキシでのバッファリングモードが自動的に有効になります。

PDK機能

Kong は、ネットワークベースのプロセス間通信を通じて PDK と対話します。 各関数はPromiseインスタンスを 返します。読みやすさを向上させるために、フェーズ ハンドラーでasync / awaitキーワードを使用できます。

class KongPlugin {
  constructor(config) {
    this.config = config
  }
  async access(kong) {
    let host = await kong.request.getHeader("host")
    // do something to host
  }
}

あるいは、thenメソッドを使用してプロミスを解決します。

class KongPlugin {
  constructor(config) {
    this.config = config
  }
  async access(kong) {
    kong.request.getHeader("host")
      .then((host) => {
        // do something to host
      })
  }
}

プラグインの依存関係

プラグインサーバーを使用する場合、プラグインのソースコードを格納するディレクトリにnode_modulesディレクトリも含まれている限り、プラグインに追加の依存関係を設定できます。

プラグインが/usr/local/kong/js-pluginsに保存されていると仮定すると、追加の依存関係は /usr/local/kong/js-plugins/package.jsonで定義されます。

開発者は、これらの依存関係をローカルに/usr/local/kong/js-plugins/node_modulesにインストールするために、 /usr/local/kong/js-pluginsの下で npm installを実行する必要もあります。

Node.jsバージョンとアーキテクチャでプラグインサーバーを実行するものは、プラグインディレクトリで npm installを実行するものと一致する必要があります。

TypeScriptプラグインを実行する場合、kong-pdkは package.jsonの依存関係として定義する必要があります。

{
  "name": "ts_hello",
  "version": "0.1.0",
  "description": "hello TS plugin from kong",
  "main": "ts_hello.ts",
  "dependencies": {
    "kong-pdk": "^0.5.5"
  }
}

次に、TypeScriptファイルにkong-pdkをインポートします。

import kong from "kong-pdk/kong";

テスト

JavaScript PDK は、 jestを使用してプラグイン コードをテストするためのモック フレームワークを提供します。

jestを開発依存関係としてインストールしてから、package.jsonにtestスクリプトを追加します。

npm install jest --save-dev

この package.json には、次のような情報が含まれています。

{
  "scripts": {
    "test": "jest"
  },
  "devDependencies": {
    "jest": "^26.6.3",
    "kong-pdk": "^0.3.2"
  }
}

次のようにして、npmでテストを実行します。

npm test

このリポジトリには jestを使用してテストを記述する例が含まれています。

構成例

必要な依存関係をインストールして、システムを準備します。Debian/Ubuntuベースのシステムの場合。

apt update
apt install -y nodejs npm
npm install -g kong-pdk

プラグインコードとpackage.jsonファイルを/usr/local/kong/js-pluginsにコピーして、次を実行します。

cd /usr/local/kong/js-plugins/ 
npm install

kong.conf構成ファイルを使用してプラグインを読み込むには、既存のKong Gatewayプロパティをプラグインの側面にマッピングする必要があります。kong.conf 内でプラグインをロードする例を次に示します。

pluginserver_names = js

pluginserver_js_start_cmd = /usr/local/bin/kong-js-pluginserver -v --plugins-directory /usr/local/kong/js-plugins
pluginserver_js_query_cmd = /usr/local/bin/kong-js-pluginserver --plugins-directory /usr/local/kong/js-plugins --dump-all-plugins

pluginserver_js_socket = /usr/local/kong/js_pluginserver.sock

その他の情報