Node.js 통합 가이드

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

1. 최소 요구 사항

Node.js 18 이상

2. 에이전트 동작 흐름

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

대기 전: 페이지 로드 → 에이전트 초기화 → 트리거 규칙 매치
대기 중: 넷퍼넬 서버 요청 → 넷퍼넬 키 발급 → 대기실 페이지로 이동
대기 후: 서비스 페이지 진입 → 넷퍼넬 키 반납

3. 에이전트 설치

3.1 의존성 추가

아래 코드를 복사하여 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
JavaScript

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

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
JavaScript

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

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
JavaScript

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

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

6. 트리거 규칙 설정

트리거 규칙 설정 방법은 트리거 룰 문서를 참고하세요.