[landing] watch: 웹훅 수신/원장 폴링으로 자동 처리하는 로컬 워커 데몬 (axmini 용)

[younjihoon]

목표

사람이 명령을 치지 않아도, 문서가 랜딩되면 로컬 머신이 알아서 render → enrich → 업로드까지 끝내는 데몬. Sweetspot 은 axmini 에서 이걸 돌리고, business 서버 워커도 같은 루프를 돈다.

동작

cloudbtl watch --enricher clip,color,yolo-world [--listen :8787] [--poll 60s] [--only-skipped]

• 웹훅 모드: --listen 으로 HTTP 리스너를 열고 document.landed / extraction.skipped / extraction.completed 를 받는다. 서명 검증(X-Cloudbtl-Signature, t 허용 오차 5분) 필수, 배달 id 로 멱등 처리. 외부 노출은 터널(cloudflared 등) 사용자 몫; cloudbtl webhooks add --url … 로 등록까지 도와준다.
• 폴링 모드: 웹훅을 못 받는 환경용. 주기적으로 대상 문서 목록을 받아 descriptors/summary 에 자기 producer 가 없는 것만 처리. 서버 의존: 스코프 안 문서 목록을 batch/metadata/기간으로 필터하는 list API 가 아직 없음(cloudbtl-site 백로그). 그 전까지는 --batch <id> 로 명시된 배치만 폴링.
• 큐: 로컬 SQLite/JSON 큐로 재시작에 견디게. 동시성 --concurrency 2. 실패는 백오프 후 재시도 3회, 그 뒤 POST …/jobs failed.
• 로그: 문서 id·producer·소요시간·상태를 JSON-lines 로. cloudbtl watch status 로 큐/최근 처리 확인.

완료 기준

• land 로 pptx 하나를 올리면 사람 개입 없이 1분 안에 clip.embedding 이 생긴다.
• 데몬을 죽이고 다시 켜도 처리 중이던 문서가 유실되지 않는다.
• 서명이 틀린 웹훅은 무시되고 로그에 남는다.