QStash는 서버리스 환경을 위해 설계된 작업 스케줄러이자 메시지 큐 시스템입니다. 상태 관리를 걱정할 필요 없이 특정 간격으로 한 번 또는 반복 실행되는 자동화 워크플로우를 손쉽게 구축할 수 있어 개발자에게 매우 유용한 도구입니다.
QStash 콘솔에서 직접 요청을 만들어 보면서 사용법을 익힐 수 있습니다.
활용 사례
제가 만든 제품인 GPT Hotline은 사실상 WhatsApp 위에서 동작하는 ChatGPT입니다(동일한 기반 모델을 사용합니다). ChatGPT 앱을 사용하듯 전용 번호로 봇에게 메시지를 보낼 수 있습니다.
GPT Hotline은 단순 텍스트 대화 외에도 이미지 검색, 동영상 검색, 뉴스 같은 부가 기능을 제공합니다. 여기에 더해 사용자가 봇에게 메시지를 보내 지정한 시간에 알림을 받을 수 있는 리마인더 기능을 추가하고 싶었습니다.
즉, 봇에게 메시지를 보내면 지정한 시간에 해당 메시지를 다시 받아볼 수 있는 간단한 흐름입니다. 대략 다음과 같은 형태입니다:
예전에 서버리스 Redis 용도로 Upstash를 사용한 적이 있어 QStash의 존재는 어렴풋이 알고 있었는데, 이번이 자세히 배우기에 딱 좋은 기회라고 생각했습니다!
본격적으로 시작해 보기
구현하려는 전체적인 워크플로우는 다음과 같습니다.
사용자가 리마인더 메시지 전송 → QStash 작업 생성 → 지정된 시간에 QStash가 API 호출 → 사용자에게 메시지 발송
설명을 단순하게 하기 위해 이 글에서는 QStash 관련 코드만 다룹니다. GPT Hotline에는 봇의 기본 응답을 대체하는 "파워 커맨드" 기능이 있으며, 리마인더를 설정하는 명령어는 다음과 같은 형식입니다:
sudo reminder <TIME-INTERVAL> <MY-MESSAGE>예를 들어 다음과 같이 메시지를 보냈다고 가정해 보겠습니다:
sudo reminder 3h go for a walk"sudo reminder" 명령어가 리마인더 코드를 트리거하고, "3h"는 3시간 후에 "go for a walk"라는 리마인더 메시지를 받고 싶다는 의미입니다.
GPT Hotline은 Next.js로 만들어졌기 때문에 몇 가지 방법으로 QStash를 호출할 수 있습니다. 인증에 사용할 수 있는 verifySignature 함수도 제공되지만, 여기서는 간단하게 REST API 방식을 사용하겠습니다.
// 참고: QStash 문서에 CURL 명령어 예제도 있습니다.
const YOUR_API_URL = "https://api.example.com";
const MY_MESSAGE = "go for a walk";
const REMINDER_TIME = "3h";
const MESSENGER = "1800-MCDONALDS";
await fetch(`https://qstash.upstash.io/v1/publish/${YOUR_API_URL}`, {
headers: {
Authorization: `Bearer ${process.env.QSTASH_TOKEN}`,
"Upstash-Delay": REMINDER_TIME,
"Content-Type": "application/json",
},
method: "POST",
body: JSON.stringify({
message: MY_MESSAGE,
messenger: MESSENGER,
}),
});위 코드는 QStash로 전송할 수 있는 fetch 요청의 예시입니다. 실제 앱의 요청에서 값을 하드코딩하고 불필요한 필드를 제거했지만, 실제 구조를 잘 보여주는 예시입니다.
QStash는 메시지를 전송할 URL이 필요합니다. 여기서는 지정된 시간에 호출하고 싶은 우리 API URL이 해당됩니다.
Upstash-Delay 값은 메시지 발송 시점을 결정합니다. 초(s), 분(m), 시간(h), 일(d) 단위를 지원하며, 예를 들어 30m은 30분, 2d는 2일을 의미합니다. 한 번만 실행하는 것이 아니라 주기적으로 반복되는 작업을 설정하고 싶다면 cron 로직을 사용하는 Upstash-Cron 필드를 활용하면 됩니다.
또한 요청 본문에는 메시지와 함께 수신자 번호(messenger)를 담아 보내고, 환경 변수로 설정해 둔 QSTASH_TOKEN으로 인증을 진행합니다.
이게 전부입니다! 모든 것이 정상적으로 동작하면 리마인더가 설정되었다는 확인 응답을 받게 되고, QStash가 설정된 시간에 message와 messenger 값을 포함해 API를 호출하여 수신자에게 리마인더를 전달합니다.
마무리
사실 구현이 좀 복잡하지 않을까 걱정해서 이 기능을 미루고 있었는데, QStash 덕분에 딱 하루 저녁 만에 완성할 수 있었습니다!
여러분도 꼭 한번 사용해 보시길 추천합니다. 하루 500건의 메시지를 무료로 사용할 수 있는 넉넉한 프리 티어(Free Tier)를 제공하며, 애플리케이션이 성장한 이후에만 비용을 지불하면 되므로 시도해 볼 이유가 충분합니다.
감사합니다.
Bilal 드림
sudo reminder 1m Good Luck!