Discord Interaction을 도메인 상태 머신에 붙이는 법: 중복·역순 이벤트 대응 설계

외부 플랫폼 연동의 어려움은 API 호출보다 상태 정합성에 있다. 특히 Discord Interaction은 이벤트 중심이기 때문에 서비스 도메인 상태와 연결하는 순간 복잡도가 급격히 올라간다.

이 글은 Interaction 이벤트를 운영 가능한 상태 모델로 연결한 방식에 대한 정리다.

문제 정의

• 외부 이벤트 순서와 내부 상태 전이 순서가 다를 수 있음
• 실패/재시도 시 동일 이벤트가 여러 번 들어올 수 있음
• 이벤트 처리와 후속 동작이 강결합되면 장애 전파가 커짐

핵심 선택

이벤트 수신과 도메인 처리를 분리했다.

• interaction -> handler -> service state/session -> downstream actions

핵심은 핸들러가 모든 걸 처리하지 않게 만드는 것이다. 핸들러는 입력 정규화와 검증만 맡고, 상태 전이는 도메인 레이어가 책임진다.

플랫폼 제약과 도메인 모델 연결

Discord Interaction은 빠른 초기 응답이 필요하기 때문에, 도메인 계산을 끝내고 응답하면 늦는다.

그래서 경로를 두 개로 나눴다.

• Fast path: 검증 후 즉시 ACK
• Async path: 상태 계산/후속 메시지

이 구조가 없으면 타임아웃과 상태 꼬임이 동시에 발생한다.

상태 전이 예시

• RECEIVED -> ACKED -> PROCESSING -> COMPLETED
• 실패 시 PROCESSING -> FAILED_RETRYABLE or FAILED_FINAL

각 전이에는 event_id, source, version 메타데이터를 같이 저장했다. 이렇게 해야 재시도와 중복 처리 기준을 코드로 고정할 수 있다.

운영 관점에서 얻은 이점

• 이벤트 재처리 기준이 명확해짐
• 실패 시 재시도 범위를 최소화 가능
• 플랫폼 확장(Discord 외 채널) 시 재사용 가능

운영 체크리스트

• interaction ID 기반 멱등 처리
• ACK 경로와 도메인 처리 경로 분리
• 상태 전이 실패와 메시지 전송 실패를 분리 기록
• 재시도 가능한 실패와 불가능한 실패 코드를 구분

이 네 가지를 지키면 외부 플랫폼 이벤트를 내부 도메인 규칙으로 안정적으로 흡수할 수 있다.

참고 및 인용

참고: Discord Interaction API는 응답 타이밍과 후속 메시지 흐름을 명시적으로 규정한다. Receiving and Responding

참고: 상태 머신 모델링은 이벤트 순서 역전/중복 처리 같은 비동기 문제를 구조적으로 분리하는 데 유효하다. State Machine