큐 작업
요청 안에서 끝내기엔 너무 오래 걸리는 일이 있습니다. 이런 일은 큐에 넣고 바로 응답합니다. 무거운 부분은 백그라운드 process가 이어받아 처리합니다.
이럴 때 씁니다. 백업, 내보내기, 리포트 생성, 가져오기, 오래 걸리는 AI 작업.
이 페이지에서 쓰는 말
용어설명
process
signal 파일에 선언하는 internal입니다. 큐에 들어간 job이 이것의
exec을 실행합니다.job
process를 한 번 실행하도록 큐에 넣은 단위입니다. 인자와 재시도 상태를 담습니다.
replica
앱을 실행하는 서버 프로세스 하나입니다. 역할은
federation, batch, all 중 하나입니다.serverMode
어느 역할의 replica가 job을 실행할지 고르는 process 옵션입니다.
세 단계
- 엔드포인트가 사용자의 의도를 기록합니다. 상태를
waiting으로 저장하고 job을 큐에 넣은 뒤 바로 돌아옵니다. - 큐가 job을 보관합니다. 이 process를 실행하는 replica가 가져갈 때까지입니다.
- process가 느린 작업을 합니다. 요청 경로 밖에서 실행하며, 상태와 진행률을 문서에 기록합니다.
엔드포인트에서 큐에 넣기
엔드포인트는 짧게 둡니다. 상태를
waiting으로 바꾸고, process에게 나중에 실행해 달라고 요청한 뒤 돌아옵니다.엔드포인트는 호출을 service에 넘기기만 합니다:
apps/myapp/lib/report/report.signal.ts
service가 상태를 저장한 다음 job을 큐에 넣습니다:
apps/myapp/lib/report/report.service.ts
this.reportSignal.generateReport()는 실행이 아니라 등록입니다. job이 저장되면 바로 돌아오고, 인자는 process의.msg()순서를 따릅니다.signal<sig.Report>()로 주입합니다. 필드 이름은<refName>Signal, 여기서는reportSignal이어야 합니다.- 상태를 먼저 저장하고 큐에 넣습니다. job은 곧바로 시작될 수 있어서, 늦게 쓴
waiting이 process가 쓴running을 덮어쓸 수 있습니다.
job 옵션
등록 호출의 마지막 인자로 job 옵션을 넘깁니다:
delaynumber기본값 0
첫 실행까지 기다릴 시간(ms)입니다.
attemptsnumber기본값 1
첫 시도를 포함해 job이 실행될 수 있는 최대 횟수입니다.
backoffnumber | { type?, delay? }
재시도하기 전에 기다릴 시간(ms)입니다.
process에서 실행
느린 작업은 internal process가 맡습니다. 진행률을 갱신하고, 파일을 업로드하고, job을
done 또는 failed로 표시합니다.process는 signal 파일의 Internal 클래스에 선언합니다:
apps/myapp/lib/report/report.signal.ts
.msg()가 job에 실을 인자를 정합니다. 등록할 때 넘긴 값이 선언한 타입으로 복원되어 같은 순서로 들어옵니다.- job 자체는 마지막 인자로 옵니다.
exec(async function (reportId, job) {…})처럼 받고,job.id와job.attemptsMade를 담고 있습니다. process(Boolean)가exec의 반환 타입을 정합니다. 여기서는true를 돌려줍니다.
실제 작업은 service 메서드에 둡니다:
apps/myapp/lib/report/report.service.ts
- 단계마다 저장합니다.
running을 거쳐done또는failed로 끝나고, 그 사이에progress를 갱신합니다.
에러를 던져야 재시도됩니다.
exec이 에러를 던지고 attempts가 남아 있을 때만 job이 다시 실행됩니다. 이 예제는 catch해서 failed로 기록하므로 한 번에 끝납니다.replica 역할
Akan은 역할이 있는 replica를 실행합니다.
federation은 사용자 요청을 받고, batch는 백그라운드 작업을 맡습니다. 둘을 나누면 느린 job이 요청 서버의 자원을 다 쓰지 못합니다.역할
요청
기본 job
batch job
AKAN_REPLICA=<federation>,<batch>,<all>federation
✓
✓
사용자 요청을 받습니다.
batch
✓
✓
요청을 받지 않고 백그라운드 작업만 합니다.
all
✓
✓
✓
둘 다 합니다. 기본값
0,0,1이 이 replica 하나입니다.✓실행함실행 안 함
리포트 job을 요청 서버에서 빼려면 process에
serverMode를 선언합니다:apps/myapp/lib/report/report.signal.ts
- 그다음 batch replica를 띄웁니다.
AKAN_REPLICA=2,1,0은 federation replica 2개와 batch replica 1개입니다. - 실행할 replica가 있어야 합니다.
serverMode: "batch"인데2,0,0처럼 batch도 all도 없으면 job이 실행되지 않고 쌓입니다.
batch replica를 띄우는 것만으로는 작업이 옮겨 가지 않습니다.
serverMode를 선언하지 않은 process는 federation을 포함한 모든 역할에서 실행됩니다.요청 쪽: federation replica
사용자 요청
federation replica엔드포인트
job을 큐에 넣기
백그라운드 쪽: batch replica
batch replicaprocess
무거운 작업 실행
job 상태 갱신
사용자가 진행 상황 확인
꿀팁
job 상태는 항상 저장합니다. 이 네 가지면 화면이 무엇을 보여 줄지 정할 수 있습니다:
| 상태 | 쓰는 곳 | 뜻 |
|---|---|---|
| waiting | queueGenerateReport | job이 큐에서 차례를 기다립니다. |
| running | generateReport | process가 작업 중입니다. 도중에 progress를 갱신합니다. |
| done | generateReport | 결과(여기서는 file)가 준비됐습니다. |
| failed | generateReport | 작업이 실패했습니다. 원인은 errMsg에 남깁니다. |
- job은 멱등(idempotent)하게 만듭니다. 같은 job을 다시 실행해도 데이터가 깨지면 안 됩니다.
- 사용자에게 진행 상황을 보여 줘야 하면 진행률을 저장합니다.
progress필드 하나면 충분합니다. - 엔드포인트는 빨리 반환합니다. 느린 작업은 process에서 합니다.