Node.js Agent

概要

NetFUNNEL Node エージェントは、NetFUNNEL サーバーと通信する専用クライアントです。

最小要件

• Node.js 18 以上

エージェントのインストール

ライブラリの追加

依存関係の追加

以下のコードをコピーし、package.json に依存関係を追加してください。正確な URL はコンソールのエージェントタブで確認できます。

package.json

{
  "dependencies": {
    "netfunnel-node-agent": "{{AGENT_URL}}"
  }
}

パッケージのインストール

プロジェクトルートで以下のコマンドを実行してパッケージをインストールします。

npm install

ミドルウェアの適用

リクエストを最初に受け取るミドルウェアに、以下のようにコードを追加します。

Nuxt

Nuxt 3 では defineEventHandler で NetFUNNEL エージェントを登録します。Netfunnel.run() の後、allowed が false の場合は待機室進入後にリダイレクト URL へ遷移し、そうでなければルーティングを続行します。Express と異なり next() の呼び出しは不要です。

// server/middleware/netfunnelAgent.ts

import { sendRedirect } from 'h3';
import { Netfunnel } from 'netfunnel-node-agent';

export default defineEventHandler(async event => {
	Netfunnel.initialize({
        clientId : '{{CLIENT_ID}}',
        secretKey: '{{SECRET_KEY}}'
	});

	console.log('[APP] NetFUNNEL Version:', Netfunnel.getVersion());
	const allowed = await Netfunnel.run(event.node.req, event.node.res);

	if (!allowed) {
		const redirectUrl = (event.node.req as any)._nfRedirect || '/';
		console.log(`Redirecting now to: ${redirectUrl}`);
		return sendRedirect(event, redirectUrl);
	}
});

Express

Express では NetFUNNEL をグローバルミドルウェアとして適用します。Netfunnel.run() が false を返した場合は待機室進入後にリダイレクトされ、そうでなければ next() で次へ進みます。初期化は app.ts でサーバー起動時に 1 回行います。

// middleware/netfunnel-middleware.ts

import { Netfunnel } from 'netfunnel-node-agent';

export function netfunnelMiddleware(req, res, next) {
	Netfunnel.run(req, res).then(allowed => {
		if (!allowed) {
			return res.redirect(302, req._nfRedirect || '/');
		}
		next();
	});
}

// app.ts

import express from 'express';
import { router } from './routes.js';
import { netfunnelMiddleware } from './middleware/netfunnel-middleware.js';
import { Netfunnel } from 'netfunnel-node-agent';

const app  = express();
const PORT = 3000;

/* NetFUNNEL グローバル初期化 */
Netfunnel.initialize({
  clientId : '{{CLIENT_ID}}',
  secretKey: '{{SECRET_KEY}}'
});

app.use(netfunnelMiddleware);

app.use('/', router);

app.listen(PORT, () => {
  console.log(`[APP] listening on ${PORT} (NetFUNNEL ${Netfunnel.getVersion()})`);
});

NetFUNNEL ミドルウェアをグローバルに登録すると、すべてのリクエストに待機列制御が適用されます。

// routes.ts

import { Router } from 'express';
export const router = Router();

router.get('/', (_req, res) => res.send('Home'));
router.get('/page1', (_req, res) => res.send('Page 1'));
router.get('/page2', (_req, res) => res.send('Page 2'));
router.get('/page3', (_req, res) => res.send('Page 3'));

Initialize 設定

フィールド	型	既定値	必須	説明	エージェントバージョン
clientId	string	N/A	O	コンソールで発行されたクライアント ID を入力します。	4.0.1 以上
secretKey	string	N/A	O	コンソールで発行された秘密鍵を入力します。	4.0.1 以上
serverUrl	string	N/A	X	NetFUNNEL サーバーの URL。CNAME を使わず、clientId ベース以外の URL でサーバーにアクセスする場合に指定します。<br/>（従来方式との互換のためサポート。）	4.0.1 以上
settingUrl	string	N/A	X	NetFUNNEL 環境設定ファイルの URL。CNAME を使わず、clientId ベース以外の URL で設定を読み込む場合に指定します。<br/>（従来方式との互換のためサポート。）	4.0.1 以上
vwrPageUrl	string	N/A	X	NetFUNNEL VWR ページの URL。CNAME を使わず、clientId ベース以外の URL で待機室に遷移する場合に指定します。	4.0.1 以上
returnKey	boolean	true	X	ユーザーが待機列を通過してページに進入すると、次のユーザーがすぐに入場できます。<br/>無効にすると、進入後も一定時間は次のユーザーが待機します。<br/>（タイムアウト: コンソール > セグメント設定 > 詳細設定）	4.0.1 以上
printLog	boolean	false	X	デバッグログの出力の有無を設定します。	4.0.1 以上
goodBots	array	N/A	X	検索エンジンなどの善意のボットを NetFUNNEL 進入から除外します。文字列の配列で指定。<br/>例: ["Googlebot", "Bingbot"]	4.0.1 以上
userId	string	N/A	X	指定すると、ホワイトリスト・永久ブロックの識別にこの ID が使われます。コンソールの反復リクエストブロック > ユーザー設定 > 訪問者管理で設定した ID が適用されます。	4.0.1 以上
vwrPageDomain	string	N/A	X	CNAME ドメインのみで VWR ページ URL を構成する場合に指定します。<br/>例: https://vwr.example.com	4.0.1 以上
cookieDomain	string	N/A	X	発行する NetFUNNEL クッキーのドメインを直接指定できます。	4.0.1 以上

エージェントの適用

待機列の制御ポイントは、NetFUNNEL コンソールのセグメントトリガールールで設定できます。ユーザーがアクセスしたページの URL とトリガールールを比較し、一致した場合に待機列が適用されます。

設定オプション

• Logical Operator: トリガールールを 2 つ以上作る場合、and / or で関係を定義します。
• Validator: トリガールールの対象となる最上位の範囲を定義します（例: URL のみ）。
• Component: Validator で定義した範囲内で、より細かく対象を指定します（例: URL 全体、パス）。
• Negate: 設定した条件の逆を適用する場合に使用します。
• Match: ルールが適用される条件の種類を定義します（Equals、Exists など）。
• Value: ルール評価時に比較する値を指定します。Match と組み合わせて使用します。
• Aa: Value の比較で大文字・小文字を区別するかどうかを指定します。

Match オプション

• Exists: URL にその Component が存在するか確認します。（Component が Path のときのみ使用可能。）
• Equals: Component の値と Value が完全に一致するか確認します。
• Contains: Component の値に Value が含まれるか確認します。
• StartsWith: Component の値が Value で始まるか確認します。
• EndsWith: Component の値が Value で終わるか確認します。

トリガールールのテスト

待機列を適用したい URL がトリガールールに合うか、事前にテストできます。