feat(uploads): per-user file count, total size and retention in a multi-user deployment

[Eomdahyeon]

Closes #1045

kpubdata#812 §3 의 업로드 결정을 구현한다: 다중 사용자 배포에서 사용자별 파일 50개 / 합계 1 GiB / 보관 30일, 셋 다 환경변수로 바꿀 수 있고, 단일 사용자 배포에는 걸지 않는다. 파일당 20 MiB 는 그대로다.

리뷰에서 볼 곳: 보관 기간은 데이터를 지운다. 30일이 지난 업로드는 삭제되고, 그것을 가리키는 저장 스펙의 다음 빌드는 업로드를 찾지 못한다. 결정이 정한 동작이지만 되돌릴 수 없는 종류라 제가 머지하지 않는다.

변경

• service/upload_limits.py (새 파일): 세 한도와 그 환경변수. multi_user_mode() 가 아니면 한도 자체가 없다(None). 0 은 그 한도를 끈다. 숫자가 아니거나 음수면 기본값으로 떨어진다.
• uploads/store.py: usage_for_owner (개수·합계), purge_created_before (기준 시각 이전 업로드와 그 payload 파일 삭제 — 한 소유자 또는 전체).
• service/uploads_service.py create_upload:
  1. 그 소유자의 보관 기간 지난 업로드를 먼저 지운다 — 지난 것은 한도에 세지 않는다.
  2. 개수나 합계를 넘기면 409 upload_quota_exceeded, 아무것도 저장하지 않는다. 본문이 어느 한도인지(limit: max_files / max_total_bytes), 그 값(limit_value), 지금 쓰는 양(used)을 말한다.
  3. 확인과 저장은 잠금 하나 안에서 한다 — 동시에 온 두 업로드가 한 자리에 함께 들어가지 않게.
• 서비스가 뜰 때(serve) 모든 소유자의 지난 업로드를 지운다. 업로드를 한 번도 받지 않은 작업 공간에는 그 때문에 저장소 파일을 만들지 않는다(feat(source): Public API, File and URL source contract and ingestion integration #498 의 lazy 생성 유지).
• 계약 1.84.0 (additive): createUpload 에 409. 이름 붙은 예시는 더하지 않았다 — Studio 의 drift 검사에 선행 변경이 필요 없다(Studio main 을 이 계약으로 돌려 577 passed).
• docs/deployment.md, .env.app.example, compose 통과(값은 비워 둠 → 코드 기본값), CHANGELOG.

상태 코드를 409 로 한 이유

413 은 이 라우트에서 "이 요청의 본문이 너무 크다"로 이미 쓰인다. 한도 초과는 요청이 아니라 계정이 이미 가진 것 때문이고, 하나를 지우면 같은 요청이 통과한다 — 그래서 409 다. 다른 코드가 맞다고 보시면 바꾸겠다.

테스트 (tests/unit/test_upload_limits.py, 16개)

• 기본값이 50 / 1 GiB / 30일이고, 각각 바꿀 수 있고, 0 이 끄고, 잘못된 값은 기본값으로 간다. 단일 사용자 배포에서는 한도가 없다.
• 개수: 한도를 넘는 파일은 409(본문 전체를 고정) — 하나 지우면 다시 들어간다. 한 사용자의 업로드는 다른 사용자의 한도에 세지 않는다.
• 합계: 합계를 넘기는 업로드는 409, 그 뒤 더 작은 것은 들어간다. 정확히 한도에 닿는 업로드는 들어간다.
• 보관: 31일 된 업로드는 그 사용자의 다음 업로드 때 사라지고(404) 한도에 세지 않는다. 29일 된 것은 남는다. 기동 시 정리는 모든 소유자의 지난 업로드를 지우고 디스크의 payload 파일도 함께 지운다(파일로 내려간 payload 3개 → 1개). 업로드가 없는 작업 공간에는 저장소가 생기지 않는다. 보관을 끄면 400일 된 것도 남는다.
• 단일 사용자: 한도 변수를 1 로 줘도 두 번째 업로드가 들어가고 오래된 것도 남는다.

"오래됨"은 테스트가 created_at 을 직접 과거로 고쳐서 만든다.

검증

• pytest tests/unit → 4385 passed, 9 skipped (8분).
• check_contract_compat.py --base origin/main → contract compatible with origin/main: 1.83.0 -> 1.84.0. fixture 는 생성기로 다시 만들었다.
• ruff, mypy src, mkdocs build --strict 통과. # type: ignore 없음.
• 실제 다중 사용자 배포에서 돌려 보지 않았다. 1 GiB 근처의 실제 크기로 올려 보지도 않았다 — 테스트는 한도를 몇 바이트로 낮춰서 본다.

알아 둘 것

• fix(api): refuse an interrupted run's id to its submitter too #1043 이 먼저 들어가 1.83.0 을 썼으므로 이 PR 은 1.84.0 으로 올렸다.
• 세 숫자는 docs: point title rules at kpubdata POLICY 2.1.3 and drop the [#issue] PR title rule #812 가 "측정 없이 고른 출발값"이라고 적은 그대로다.
• 보관 정리는 업로드할 때와 기동할 때만 돈다. 오래 떠 있는 서비스에서 업로드를 하지 않는 사용자의 지난 파일은 다음 기동까지 남는다. 주기적으로 도는 정리는 넣지 않았다.
• 한도에 걸린 업로드도 본문은 이미 서버가 다 받은 뒤다(형식 검증이 한도 확인보다 먼저다). 받기 전에 끊는 것은 하지 않았다.
• 사용자가 자기 사용량을 볼 방법(목록 라우트, Studio 화면)은 이슈의 Non-goal 이다. 409 의 used 가 지금 유일한 안내다.

🤖 Generated with Claude Code

[yeongseon]

리뷰 (코멘트 — 승인은 계약 버전을 맞추고 CI 가 녹색인 뒤에).

#1043 이 방금 머지돼서 1.83.0 이 쓰였습니다. 본문대로 이 PR 을 1.84.0 으로 올려 주세요.

diff 는 읽었고 걸리는 로직은 없습니다.

• 한도는 다중 사용자 배포에서만 걸리고, 0 이 끄고, 잘못된 값은 기본값으로 갑니다. 단일 사용자 배포에서 한도 변수를 줘도 걸리지 않는다는 테스트가 있습니다.
• 확인과 저장이 잠금 하나 안에 있어 동시에 온 두 업로드가 한 자리에 함께 들어가지 않습니다.
• 지난 업로드를 먼저 지우고 나서 한도를 세는 순서가 맞습니다. 기동 시 정리가 디스크의 payload 파일까지 지우는 것을 테스트가 확인합니다.
• 409 를 고른 이유(413 은 "이 요청의 본문이 크다" 로 이미 쓰인다, 하나를 지우면 같은 요청이 통과한다)에 동의합니다.

"보관 기간은 데이터를 지운다" 에 대해: 결정(kpubdata#812)이 정한 동작이고 그대로 갑니다. 지금은 다중 사용자 배포가 하나도 없어서 이 PR 이 머지되는 순간 지워질 업로드는 없습니다. 다만 사용자가 언제 지워지는지 미리 알 방법이 없습니다 — 업로드 메타데이터에 만료 시각을 싣고 Studio 가 보여 주는 것을 후속 이슈로 올려 주세요. 그것이 들어가기 전에 첫 배포를 한다면 그 배포에서는 KPUBDATA_BUILDER_UPLOAD_RETENTION_DAYS=0 으로 시작하는 것이 안전합니다.

본문이 남긴 나머지 — 주기적 정리가 없다, 한도에 걸린 업로드도 본문은 이미 다 받은 뒤다 — 는 알아 두는 것으로 충분합니다. 뒤의 것은 10-06 계획의 "인증 전에 대용량 본문 전체를 읽지 않도록" 항목과 함께 다룰 일입니다.

[Eomdahyeon]

계약 버전은 1.84.0 으로 올려 두었습니다 (5a56d32, check_contract_compat.py: 1.83.0 -> 1.84.0). CI 는 녹색입니다. 만료 시각을 메타데이터에 싣고 Studio 가 보여 주는 후속 이슈는 바로 올리겠습니다.

[yeongseon]

계약 버전이 1.84.0 으로 맞춰진 것을 확인했습니다. 그 밖의 diff 는 앞서 읽은 것과 같고 CLEAN 입니다. 승인합니다. 만료 시각을 알리는 후속 이슈(#1047)도 확인했습니다.