테넌트 범위의 재개 가능한 업로드 세션을 정의하며, 파트 체크섬, 만료, 해시 일치 시에만 완료, 중단 시 정리 기능을 포함하여 대용량 파일이 고아 파트나 테넌트 간 키 충돌 없이 재개될 수 있도록 합니다.
패키지 상태: 참조 컨텍스트로서 인간 검토 준비 완료. 계약 및 테스트 시나리오는 완성되었으나, 이를 통과한 구현체가 있다고 주장하지는 않습니다.
결정 사항
대용량 업로드는 테넌트 범위의 객체 키, 만료 시간, 선언된 크기, 클라이언트가 제공한 객체 다이제스트로 세션을 생성합니다. 클라이언트는 파트 번호가 매겨진 파트를 각 파트별 체크섬과 함께 PUT 합니다. 완료는 파트가 연속적이고 protocol.yaml의 제한을 준수하며, 연결된 다이제스트가 일치할 때만 성공합니다. 중단 또는 만료 시 파트를 삭제하여 불완전한 데이터가 다운로드 가능한 객체가 되지 않도록 합니다. 세션 식별자는 테넌트 간에 사용할 수 없습니다. 게시된 객체에 대한 악성코드 스캔은 완료 후 관련 검증 단계이며, 게시된 객체의 권한 있는 다운로드는 관련 차단 단계입니다.
범위
- 세션 수명 주기, 파트 제한, 체크섬, 완료, 중단, 정리자(sweeper).
- 한 테넌트 내 대용량 파일 업로드에 대한 API 동작.
- 키 레이아웃
{tenant_id}/uploads/{session_id}.
이 블록에 포함되지 않는 항목
- 게시된 객체에 대한 바이트 범위 GET.
- 게시 후 바이러스 스캔 및 콘텐츠 유형 정책.
- 특정 클라우드 공급자의 멀티파트 프로토콜(프로파일 번호를 넘어선 부분).
계약
- 세션은
protocol.yaml에 명시된 상태로 존재하며, 허용되지 않은 메서드는 실패 처리됩니다. min_part_bytes/max_part_bytes범위를 벗어난 파트(마지막 파트 제외)는 거부됩니다; 이 프로파일에서max_parts는 10000입니다.- 잘못된
checksum_crc32c를 가진 파트는 보존되지 않습니다. POST_complete는 파트가 연속적이고 SHA-256이object_sha256과 일치할 때만 게시하며, 그렇지 않으면upload_checksum_mismatch오류를 반환하고 상태를 열림으로 되돌립니다.- 외부 테넌트 세션 ID는 파트 목록 없이
not_found로 처리됩니다. - 중단 및 만료 정리자는 파트를 삭제하고 키가 완료된 객체로 제공되는 것을 방지합니다.
구현 지침
- 테넌트 검사는 객체 키만으로 추론하지 않고 세션 메타데이터에서 수행합니다.
- 상태 응답에 파트 번호와 체크섬을 반영합니다. 중단 없이도
expires_at을 정리합니다.
실패 처리 및 안전장치
- 다이제스트 불일치 상태에서 완료는 완료 상태가 되지 않습니다.
object_sha256이 없으면 시작을 거부합니다. - 만료는 저장소 시계를 사용합니다.
검증 및 운영
- 테스트: 만료, 파트 체크섬, 객체 해시, 테넌트 간 숨김, 중단 정리.
session_ttl_seconds보다 오래된 세션에 대해 경고. 프로파일 크기는 공급자 기본값이 아닙니다.
이 패키지 내 실행 가능한 예제들은 픽스처 및 수용 계약입니다. 컬렉션 루트에서 python tools/validate.py를 실행하여 패키지 구조와 메타데이터를 확인한 후, 대상 저장소에서 시나리오를 구현하고 실행하세요.
도입 가정
example.yaml의 이름과 숫자 값은 도입 프로파일이며, 보편적 기본값이 아닙니다.- 도입 팀은 행위자, 데이터 클래스, 오류 어휘, 소유권을 자사 시스템에 맞게 매핑해야 합니다.
참고 문헌
- 외부 규범적 출처는 필요하지 않으며, 이 패키지는 프로젝트 결정을 정의합니다.