Node.js 통합 가이드

NetFUNNEL Node.js 에이전트는 NetFUNNEL 서버와 통신하는 전용 클라이언트입니다.

---

1. 최소 요구 사항

• Node.js 18 이상

---

2. 에이전트 동작 흐름

대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.

대기 전

페이지 로드 → 에이전트 초기화 → 트리거 규칙 매치

대기 중

넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동

대기 후

서비스 페이지 진입 → 넷퍼넬 키 반납

---

3. 에이전트 설치

3.1 의존성 추가

아래 코드를 복사하여 package.json에 의존성을 추가해주세요.

package.json

{
  "dependencies": {
    "netfunnel-node-agent": "https://agent-lib.stclab.com/agents/was/nodejs/netfunnel-node-agent.tgz"
  }
}

3.2 패키지 설치

프로젝트 루트 경로에서 아래의 명령어를 사용하여 패키지를 설치합니다.

npm install

---

4. 미들웨어 적용

서버의 요청을 먼저 수신하는 미들웨어에 아래와 같은 코드를 작성합니다.

4.1 Nuxt 3

Nuxt 3에서는 defineEventHandler를 통해 NetFUNNEL 에이전트를 등록합니다. Netfunnel.run() 호출 후 allowed가 false이면 대기실 진입 후 리다이렉트 URL로 이동하며, 그렇지 않으면 라우팅 처리를 계속 진행합니다.

TypeScript

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: '*****'
  });

  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['_nfRedirect'] || '/';
    console.log(`Redirecting now to: ${redirectUrl}`);
    return sendRedirect(event, redirectUrl);
  }
});

JavaScript

server/middleware/netfunnelAgent.js

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

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

  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._nfRedirect || '/';
    console.log(`Redirecting now to: ${redirectUrl}`);
    return sendRedirect(event, redirectUrl);
  }
});

4.2 Express

Express에서는 전역 미들웨어로 NetFUNNEL을 적용합니다. Netfunnel.run()의 결과가 false이면 대기실 진입 후 리다이렉트되며, 그렇지 않으면 next()를 호출하여 다음 라우터로 진행합니다.

TypeScript

middleware/netfunnel-middleware.ts

import { Netfunnel } from 'netfunnel-node-agent';
import { Request, Response, NextFunction } from "express";

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

JavaScript

middleware/netfunnel-middleware.js

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();
  });
}

NetFUNNEL 미들웨어를 전역으로 등록하여, 모든 요청에 대해 대기열 제어를 적용합니다.

TypeScript

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: number = 3000;

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

app.use(netfunnelMiddleware);
app.use('/', router);

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

JavaScript

app.js

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.initialize({
  clientId : '{CLIENT_ID}',
  secretKey: '*****'
});

app.use(netfunnelMiddleware);
app.use('/', router);

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

---

5. Initialize 설정

필드	기본값	필수	설명	에이전트 버전
clientId string	N/A	O	콘솔에서 발급받은 클라이언트 아이디를 입력합니다.	4.0.1 이상
secretKey string	N/A	O	콘솔에서 발급받은 암호화 키를 입력합니다.	4.0.1 이상
serverUrl string	N/A	X	NetFUNNEL 서버의 URL입니다. CNAME을 사용하지 않고, clientId 기반의 URL 조합이 아닌 별도의 URL로 서버에 접근할 때 사용합니다. (기존 방식과의 호환성을 위해 지원됩니다.)	4.0.1 이상
settingUrl string	N/A	X	NetFUNNEL 환경설정 파일의 URL입니다. CNAME을 사용하지 않고, clientId 기반의 URL 조합이 아닌 별도의 URL로 설정 파일을 불러올 때 사용합니다. (기존 방식과의 호환성을 위해 지원됩니다.)	4.0.1 이상
vwrPageUrl string	N/A	X	NetFUNNEL VWR Page의 URL입니다. CNAME을 사용하지 않고, clientId 기반의 URL 조합이 아닌 별도의 URL로 대기실 페이지에 진입해야 할 때 지정합니다.	4.0.1 이상
returnKey boolean	true	X	사용자가 대기열을 통과해 페이지에 진입하면 즉시 다음 사용자가 입장할 수 있습니다. 옵션을 비활성화하면, 사용자가 페이지에 진입한 뒤에도 일정 시간동안 다음 사용자가 대기하게 됩니다. (타임아웃 설정은 콘솔의 세그먼트 설정 > 고급설정에서 가능합니다.)	4.0.1 이상
printLog boolean	false	X	디버그 로그 출력 여부를 설정합니다.	4.0.1 이상
goodBots array	N/A	X	선의의 봇(검색엔진 등)이 NetFUNNEL 진입 요청에서 제외되도록 설정합니다. 문자열의 배열로 값을 받습니다. 예시: `["Googlebot", "Bingbot"]`	4.0.1 이상
userId string	N/A	X	이 값을 입력하면 화이트리스트 및 영구 차단 사용자 구분에 ID가 사용됩니다. 콘솔의 반복 요청 차단 > 사용자 설정 > 접속자 관리에서 설정한 ID가 적용됩니다.	4.0.1 이상
vwrPageDomain string	N/A	X	CNAME 도메인만으로 VWR Page URL을 구성할 때 사용합니다. 예시: `https://vwr.example.com`	4.0.1 이상
cookieDomain string	N/A	X	발급되는 NetFUNNEL 쿠키의 도메인(Domain) 값을 직접 지정할 수 있습니다.	4.0.2 이상

---

6. 트리거 규칙 설정

info

대기열 제어 지점은 NetFUNNEL 콘솔의 세그먼트 트리거 규칙을 통해 설정할 수 있습니다. 사용자가 접속한 페이지의 URL과 트리거 규칙을 비교하여 일치하는 경우 대기열이 적용됩니다.

트리거 규칙 설정 방법은 트리거 규칙 설정 가이드를 참고하세요.