APIリファレンス

NetFUNNEL Node.js Agent関数と使用方法の完全なリファレンスです。

---

Netfunnelクラス

Node.js Agentのコアクラスです。ExpressまたはNuxtミドルウェアで使用してNetFUNNEL待機列制御を実行します。

initializeメソッド

目的: NetFUNNELエージェントを初期化します。

関数シグネチャ:

Netfunnel.initialize(config: NetfunnelConfig): void

パラメータ:

パラメータ	型	説明
config	NetfunnelConfig	NetFUNNEL初期化設定オブジェクト

例:

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

Netfunnel.initialize({
  clientId: '{{CLIENT_ID}}',
  secretKey: '{{SECRET_KEY}}'
});

注意: 初期化はサーバー起動時に1回だけ実行すれば十分です。Expressの場合はapp.tsで、Nuxtの場合はミドルウェアで実行します。

---

runメソッド

目的: NetFUNNEL待機列制御を実行します。

関数シグネチャ:

Netfunnel.run(req: IncomingMessage, res: ServerResponse): Promise<boolean>

パラメータ:

パラメータ	型	説明
req	IncomingMessage	Node.js HTTPリクエストオブジェクト
res	ServerResponse	Node.js HTTPレスポンスオブジェクト

戻り値: Promise<boolean>

• true: リクエストが正常に処理され、次のミドルウェアに進むことができます
• false: リクエストがブロックされたかリダイレクトされたため、次のミドルウェアに進みません

動作:

1. トリガールールマッチング: ユーザーがアクセスしたページのURLとトリガールールを比較
2. ルール一致時: NetFUNNELサーバーに進入リクエスト
3. 待機応答時: 自動的に待機室ページにリダイレクト (302)
4. 進入成功時: キーを発行し、リクエストを継続

例:

// Expressミドルウェアで使用
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();
  });
}

// Nuxtミドルウェアで使用
import { Netfunnel } from 'netfunnel-node-agent';
import { sendRedirect } from 'h3';

export default defineEventHandler(async event => {
  const allowed = await Netfunnel.run(event.node.req, event.node.res);
  
  if (!allowed) {
    const redirectUrl = (event.node.req as any)._nfRedirect || '/';
    return sendRedirect(event, redirectUrl);
  }
});

---

getVersionメソッド

目的: NetFUNNELエージェントバージョンを取得します。

関数シグネチャ:

Netfunnel.getVersion(): string

戻り値: string - エージェントバージョン文字列

例:

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

console.log('NetFUNNEL Version:', Netfunnel.getVersion());

---

動作フロー

正常フロー

1. ユーザーがページにアクセス
2. ミドルウェアでNetfunnel.run()を呼び出し
3. トリガールールマッチングを確認
4. ルール一致時、NetFUNNELサーバーに進入リクエスト
5. 進入許可時、キー発行およびリクエスト継続
6. run()メソッドがtrueを返す

待機フロー

1. ユーザーがページにアクセス
2. ミドルウェアでNetfunnel.run()を呼び出し
3. トリガールールマッチングを確認
4. ルール一致時、NetFUNNELサーバーに進入リクエスト
5. 待機応答を受信
6. 自動的に待機室ページにリダイレクト (302)
7. run()メソッドがfalseを返す

ブロックフロー

1. ユーザーがページにアクセス
2. ミドルウェアでNetfunnel.run()を呼び出し
3. トリガールールマッチングを確認
4. ルール一致時、NetFUNNELサーバーに進入リクエスト
5. ブロック応答を受信
6. ブロックページにリダイレクトまたはブロック処理
7. run()メソッドがfalseを返す

---

ベストプラクティス

集中型構成

// config/netfunnel.ts
import { Netfunnel } from 'netfunnel-node-agent';

export function initializeNetfunnel() {
  Netfunnel.initialize({
    clientId: process.env.NETFUNNEL_CLIENT_ID!,
    secretKey: process.env.NETFUNNEL_SECRET_KEY!
  });
}

環境別設定

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

Netfunnel.initialize({
  clientId: process.env.NETFUNNEL_CLIENT_ID!,
  secretKey: process.env.NETFUNNEL_SECRET_KEY!,
  printLog: process.env.NODE_ENV === 'development'
});

エラー処理

export function netfunnelMiddleware(req, res, next) {
  Netfunnel.run(req, res)
    .then(allowed => {
      if (!allowed) {
        return res.redirect(302, req._nfRedirect || '/');
      }
      next();
    })
    .catch(error => {
      console.error('NetFUNNEL error:', error);
      // エラー発生時にもサービス継続
      next();
    });
}

---

関連ドキュメント

• インストールと初期化: Express/Nuxtミドルウェア適用方法
• 初期化設定: すべての初期化パラメータ
• トラブルシューティング: 一般的な問題と解決方法