여러 서비스가 함께 쓰는 대기열 클라이언트 설계하기

들어가며

안녕하세요. 노머스 프론트엔드 개발자 지수민입니다.

fromm 스토어는 상품 오픈이나 이벤트 신청처럼 특정 시간에 사용자가 몰릴 때, 사용자를 줄 세웠다 순서대로 입장시키는 대기열 시스템(Virtual Waiting Room, 이하 VWR)을 사용하고 있습니다. 대기열을 필요로 하는 서비스가 늘어나면서, 사내 GitHub Packages(npm)에 퍼블리시해 각 서비스에서 공통으로 설치해 쓰는 패키지(vwr-client2)로 개발하게 되었습니다.

이 글에서는 이 패키지를 만든 이유와 설계 방식을 공유드리겠습니다.

VWR Client의 주요 기능

VWR Client는 대기열 등록부터 폴링(상태 확인), 입장, 세션 종료까지의 흐름을 맡고 있습니다.

1. 대기열 등록: POST /register를 통해 대기열에 진입합니다.
2. 상태 폴링: POST /polling/{visitorId}로 순번을 확인하며 상태를 갱신합니다 (pending → waiting → entered).
3. 입장 및 이용: 순서가 되면 서비스를 이용합니다.
4. 세션 종료: 이용이 끝나면 폴링을 중단하고 POST /end를 호출해 자리를 반납합니다 (ended).

register                POST /register
   ▼
폴링 루프                POST /polling/{visitorId}
   pending → waiting → entered
   ▼
end()                   폴링 중단 → POST /end → ended

배경

기존 클라이언트와 한계

기존 클라이언트(vwr-client)도 지금과 같은 core → react 구조였습니다. core가 대기열 로직을 담당하고, react 패키지가 그 위에 훅을 제공하는 형태입니다.

하지만 VWR을 사용하는 곳이 늘어나면서 한계가 드러났습니다. 호출하는 화면마다 필요한 동작이 달랐는데, 기존 react 패키지의 함수만으로는 이를 대응하기 어려웠기 때문입니다. 결국 같은 React 서비스 안에서도 각자 core를 직접 이용해 커스텀 구현을 하게 되었고, core는 로직, react는 공통 훅 이라는 애초의 설계 목적대로 쓰이지 못했습니다.

새로 만든 이유

구조는 기존과 동일하게 core → react를 유지하되, 내용을 새로 구성한 이유는 다음과 같습니다.

• 백엔드 API 개편: VWR API 버전업으로 엔드포인트, 상태, 입장 방식이 달라져 프론트엔드도 동시 대응이 필요했습니다. 이번 기회에 호환 레이어 대신 클라이언트를 새로 만들기로 했습니다.
• 공통 패키지화: 프롬 서비스의 스토어와 채널이 모두 React로 개발되어 있어, 두 서비스가 공통으로 쓸 수 있는 패키지가 필요했습니다.
• 사용성 개선: 훅 하나로 어디서나 쉽게 쓸 수 있도록 만들어, 서비스마다 대기열 로직을 중복 구현하는 일을 없애고자 했습니다.

구조

패키지는 역할에 따라 둘로 분리했습니다.

패키지	역할
core	서버 API 호출 및 대기열 상태 관리 (프레임워크·라이브러리에 의존하지 않음, 런타임 의존성 0개)
react	core를 React에서 쉽게 쓰기 위한 어댑터 (VwrProvider, useVwr 제공)

core: 서버 API 호출과 상태 관리

core는 register, polling, end 요청과 상태 변화를 맡습니다. React나 DOM에 의존하지 않아, 나중에 다른 프레임워크나 라이브러리로 확장하더라도 core는 그대로 재사용하고 어댑터만 교체하면 됩니다.

// 사용 예시

const client = createVwrClient({baseUrl});
const session = client.register({roomId, view: 'counter'});
const unsubscribe = session.subscribe(state => render(state));
await session.end();

세션은 상태 조회, 구독(subscribe), 종료(end) 인터페이스만 노출하므로 프레임워크나 라이브러리의 상태 관리 방식에 맞춰 쉽게 연결할 수 있습니다.

상태는 서버가 내려주는 값(pending, waiting, entered)에, 클라이언트가 화면을 그릴 때 필요한 상태값(disconnected, ended, failed)을 추가해 정의했습니다.

상태	의미
pending	등록이 대기열에 아직 반영되지 않음
waiting	대기 중 (순번 정보 포함)
entered	입장 가능
disconnected	일시 장애로 재시도 중
ended	end()로 정상 종료
failed	오류로 종료 (errorType으로 에러처리)

core의 4가지 동작 원칙:

1. 폴링 주기는 서버가 결정: 폴링 간격은 서버 응답의 pollInterval을 따릅니다.
2. 입장 후에도 폴링 유지: 폴링이 서버의 만료 시간(TTL)을 연장하는 역할도 하기 때문에, 입장한 뒤에도 폴링을 멈추지 않습니다. 세션을 끝낼 때는 폴링을 먼저 끊고 /end를 호출합니다.
3. 인스턴스당 단일 세션: 같은 roomId로 중복 등록을 방지합니다. /register는 재시도하지 않도록 설계했습니다.
4. 에러 케이스별 처리: 서버에서 내려주는 에러 케이스별로 처리합니다.

react: React 서비스 환경을 위한 어댑터

앱 루트에 VwrProvider를 선언하고 필요한 곳에서 useVwr 훅을 호출하는 구조로, 어디서든 같은 방식으로 대기열을 제어할 수 있도록 했습니다.

react 사용 방법

1. Provider 등록

import {VwrProvider} from '@knowmerce/vwr-client2-react';

<VwrProvider baseUrl="https://...">{children}</VwrProvider>

baseUrl은 필수이며 첫 렌더 기준으로 고정됩니다. Provider는 useState 초기화를 통해 클라이언트를 한 번만 생성하여 세션 중복 참여를 방지합니다.

2. 훅 호출 (roomId, view)

const {state, register, end, clear} = useVwr(roomId, {view: 'counter'});

• roomId: 대기열 방 ID (대기열이 없는 상품이면 undefined를 그대로 넘겨도 되고, 이때 state는 null)
• view: 대기 화면 유형 (counter 또는 progress)

view	대기 중(waiting) 상태 데이터	활용 예시
counter	aheadCount, totalWaiting	”내 앞에 N명” 등 대기 인원 표시
progress	loadingMetric (진행률)	인원 수 없이 로딩 바 표시

3. 상태에 따른 화면 분기

function PurchaseButton({roomId}: {roomId?: string}) {
    const {state, register, clear} = useVwr(roomId, {view: 'counter'});

    const onClick = () => register();

    useEffect(() => {
        if (state?.status === 'entered') goToOrder();
    }, [state?.status]);

    if (state?.status === 'waiting' && state.view === 'counter') {
        return <Waiting count={state.aheadCount} />;
    }
    if (state?.status === 'failed') {
        return <ErrorView onClose={clear} />;
    }
    return <button onClick={onClick}>구매하기</button>;
}

4. 이용 종료 시 end() 호출

end()는 폴링을 중단하고 서버에 자리를 반납합니다. 컴포넌트가 언마운트되어도 세션은 끝나지 않으므로, 주문 완료 시점이나 화면 이탈 시점에 직접 호출해야 합니다.

• register(): 기존 활성 세션 재사용
• end(): 참여 종료 및 상태를 null로 초기화
• clear(): failed 상태를 초기화

마치며

core는 비즈니스 로직에만 집중하고, react 패키지는 React 연동 역할만 하도록 분리하여 유지보수성과 확장성을 높였습니다. 공통 훅을 제공해 서비스마다 대기열 로직을 중복 구현하던 문제를 줄이고, 일관된 방식으로 연동할 수 있도록 했습니다.

실제 서비스 적용 과정에서 얻은 인사이트는 다음 글에서 이어서 공유하겠습니다.

감사합니다.