documentation
NetFUNNEL
에이전트
서버 측 에이전트

Server Side Agent (SSA) v.1.0.0

서버로 들어오는 요청들 중 특정 페이지에 대해 NetFUNNEL 서버와 통신하여 대기열 서비스를 적용할 수 있는 서버 전용 에이전트입니다. 에이전트 적용 코드를 삽입함으로써 가상 대기실을 사용할 수 있습니다.

동작 원리

NetFUNNEL 서버 측 동적 에이전트는 크게 다음과 같은 동작 흐름을 가지고 있습니다.

SSA 동작 흐름도

  1. 룰 매칭에 필요한 설정 정보들을 요청합니다.
  2. 수신한 룰 설정 정보들을 가지고 서버로 들어오는 요청에 대해 일치하는 매칭을 찾습니다.
  3. 매칭이 된 경우 Netfunnel 서버에 진입 요청을 한 후 진입 여부에 대한 응답코드를 수신합니다.
  4. 수신한 응답 코드에 따라 대기실로 이동하거나 바로 진입 처리를 하여 실제 사용자의 Application Logic이 동작하도록 합니다.

대기실에서 진입 방식
대기실 페이지로 이동한 후에는 다음과 같이 동작합니다.

  1. Netfunnel서버에게 주기적으로 진입가능 여부를 요청하여 확인합니다.
  2. 진입이 가능하단 응답을 받으면 실제 요청한 페이지로 진입 처리합니다.

에이전트 적용 방법

Java

NF Console에 로그인 후 에이전트 탭 → 서버 측 에이전트 페이지로 이동 후 해당 가이드 문서에 나온 순서대로 적용합니다.
⭐️ springboot v3.0 이상을 사용하고 있다고 가정하에 설명합니다.

📁 다운로드 파일 목록

  • netfunnel-agent.zip
    • gson-2.9.1.jar
    • netfunnel-agent.jar

다운로드 된 파일을 프로젝트에 추가합니다. 프로젝트 libs 폴더 하위에 위치시킨 뒤 build.gradle을 수정합니다.
⭐️ Build Tool은 Gradle이라 가정하고 설명합니다.

dependencies {
    implementation files('libs/netfunnel-agent.jar', 'libs/gson-2.9.1.jar')
}

Interceptor 적용방법

Step 1. 서버의 요청을 먼저 수신하는 Interceptor에 아래와 같은 코드를 작성합니다.

import com.stclab.adapter.NfAdapter;
import com.stclab.adapter.NfAdapterImpl;
import com.stclab.adapter.NfTokenServletServiceImpl;
import com.stclab.adapter.config.NfAdapterConfig;
 
@Component
public class DemoInterceptor implements HandlerInterceptor {
 
 @Override
 public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
    NfAdapterConfig.nfServerUrl = "https://nf4-iphash-lb.stclab.com";
    NfAdapterConfig.nfSettingUrl = "https://nf4-iphash-lb.stclab.com/assets/nf-setting/1/nf-setting.json";
    NfAdapterConfig.nfVwrPageUrl = "https://nf4-iphash-lb.stclab.com/assets/vwr-page-url/1/index.html";
    NfAdapterConfig.requestUrl = request.getRequestURL().toString() + (request.getQueryString() != null ? "?" + request.getQueryString() : "");
    
    NfAdapterConfig.retryCount = 1;    // Optional, Default: 1, min: 0
    NfAdapterConfig.networkTimeout = 1000;    // Optional, Default: 1000, min: 0
    NfAdapterConfig.logLevel = Level.INFO;  
    
    NfAdapter nfAdapter = new NfAdapterImpl(new NfTokenServletServiceImpl(request, response));
 
    if (nfAdapter.run()) {
        log.info("Intercepter에서 통과");
        return true;
    } else {
        log.error("Intercepter에서 차단");
        return false;
    }
 }
}

Step 2. 생성한 interceptor를 WebMvcConfigurer 의 addInterceptors 메서드를 override해서 등록합니다.

@Configuration
@RequiredArgsConstructor
public class Webconfig implements WebMvcConfigurer {
 
    private final DemoInterceptor demoInterceptor;
 
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(demoInterceptor);
    }
}

Filter 적용방법

Step 1. 서버의 요청을 먼저 수신하는 Filter에 아래와 같은 코드를 작성합니다.

@Component
public class DemoFilter implements Filter {
 
    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain chain) throws IOException, ServletException {
 
        HttpServletRequest request = (HttpServletRequest) servletRequest;
        HttpServletResponse response = (HttpServletResponse) servletResponse;
 
        NfAdapterConfig.nfServerUrl = "https://nf4-iphash-lb.stclab.com";
        NfAdapterConfig.nfSettingUrl = "https://nf4-iphash-lb.stclab.com/assets/nf-setting/1/nf-setting.json";
        NfAdapterConfig.nfVwrPageUrl = "https://nf4-iphash-lb.stclab.com/assets/vwr-page-url/1/index.html";
        NfAdapterConfig.requestUrl = request.getRequestURL().toString() + (request.getQueryString() != null ? "?" + request.getQueryString() : "");
        
        NfAdapterConfig.logLevel = Level.INFO;
 
        NfAdapter nfAdapter = new NfAdapterImpl(new NfTokenServletServiceImpl(request, response));
 
        if (nfAdapter.run()) {
            chain.doFilter(servletRequest, servletResponse);
        }
    }
}

Step 2. 생성한 Filter를 빈에 등록합니다.

@Configuration
@RequiredArgsConstructor
public class FilterConfig {
    private final DemoFilter demoFilter;
 
    @Bean
    public FilterRegistrationBean<Filter> filterRegistrationBean() {
        return new FilterRegistrationBean<>(demoFilter);
    }
}

NfAdapterConfig 설정 정보

필드설명필수값 여부
nfServerUrlNF Console에서 확인한 Netfunnel 서버 주소를 지정합니다.True
nfSettingUrlNF Console에서 확인한 Setting.json 주소를 지정합니다.True
nfVwrPageUrlNF Console에서 확인한 Vwr Page 주소를 지정합니다.True
requestUrl서버로 들어오는 요청 URL을 설정합니다.True
retryCountAPI 요청이 실패했을 때 재시도하는 횟수를 설정합니다. 설정된 횟수만큼 API 요청이 실패하면 더 이상 요청을 재시도하지 않습니다.False
networkTimeoutAPI 요청을 기다리는 최대 시간을 밀리초(ms) 단위로 설정합니다. 설정된 시간 내에 API 응답이 도착하지 않으면 요청이 실패한 것으로 간주합니다. 0으로 설정할 경우 timeout 기능을 비활성화 합니다.False
logLevelAgent의 로그 레벨을 설정합니다.False
ℹ️

nfEumUrl 을 제외한 NfAdapterConfig의 Url 설정들은 필수값임으로 설정하지 않는 경우 모든 요청에 대해 bypass 처리가 됩니다.(nfServerUrl, nfSettingUrl 등)

클라이언트 측 에이전트MBUSTER 시작하기