본문으로 건너뛰기
버전: 4.6.1-saas

API 참조

NetFUNNEL Node.js Agent 함수 및 사용법에 대한 완전한 참조입니다.

Netfunnel 클래스​

Node.js Agent의 핵심 클래스입니다. Express 또는 Nuxt 미들웨어에서 사용하여 NetFUNNEL 대기열 제어를 수행합니다.

initialize 메서드​

목적: NetFUNNEL 에이전트를 초기화합니다.

함수 시그니처:

Netfunnel.initialize(config: NetfunnelConfig): void

매개변수:

매개변수유형설명
configNetfunnelConfigNetFUNNEL 초기화 설정 객체

예제:

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

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

참고: 초기화는 서버 시작 시 한 번만 수행하면 됩니다. Express의 경우 app.ts에서, Nuxt의 경우 미들웨어에서 수행합니다.

run 메서드​

목적: NetFUNNEL 대기열 제어를 실행합니다.

함수 시그니처:

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

매개변수:

매개변수유형설명
reqIncomingMessageNode.js HTTP 요청 객체
resServerResponseNode.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();
    });
}

관련 문서​