Node.js Agent

개요

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

최소 요구 사항

• Node.js 18 이상

에이전트 설치

라이브러리 주입

의존성 추가

아래 코드를 복사하여 package.json에 의존성을 추가해주세요. 정확한 주소는 콘솔의 에이전트탭에서 확인가능합니다.

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	콘솔에서 발급받은 클라이언트 아이디를 입력합니다.	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.1 이상

에이전트 적용

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

설정 옵션

• Logical Operator: 두 개 이상의 트리거 규칙을 생성할 때, 서로의 관계를 and 또는 or 연산자로 결정합니다.
• Validator: 트리거 규칙이 적용될 대상의 최상위 범위를 정의합니다. 현재는 URL만 제공하고 있습니다.
• Component: Validator에 의해 정의된 범위 내에서 더 세부적으로 규칙을 적용할 대상을 지정합니다. 이는 URL 전체 또는 경로(Path) 등이 될 수 있으며, 특정 페이지나 자원에 규칙을 적용하는 데 사용됩니다.
• 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이 트리거 규칙에 부합하는지 미리 확인하기 위하여 사전에 테스트할 수 있습니다.