Logo

부록: 최소 데이터 구조(매니페스트/청크/상태)

이 부록은 "병렬 청크 분할 + 이어서 전송 + 멱등적 재시도"를 위한 최소한의 데이터 구조를 권장합니다. 복잡한 트랜잭션 없이도 높은 처리량의 동시성과 장애 후의 안정적인 복구를 가능하게 하는 것이 목표입니다.

일반 원칙

  • 큰 객체와 작은 상태: 청크/매니페스트는 객체 스토리지에 저장하는 큰 객체이고, 상태는 크기가 작아 상태 저장소에 저장합니다.
  • 고유 키와 멱등성: 멱등적 재전송을 위해 청크는 (transferId, fileId, chunkIndex)로 고유하게 지정할 수 있어야 합니다(MUST).
  • 복구 가능성: 복구 시 완료된 부분을 건너뛸 수 있도록 상태는 "완료된 집합"을 표현해야 합니다(MUST).
  • 민감 정보 유출 방지: 객체 키와 상태에는 이메일이나 원본 파일명 같은 민감한 필드를 넣지 않는 것이 좋습니다(SHOULD). 이를 암호화할지 여부는 개인정보 보호 정책에 따라 달라집니다.

A.1 매니페스트 최소 필드

매니페스트는 수신자가 다운로드하고 재조립할 때 사용하는 "단일 진입점"입니다. 최소 권장 사항은 다음과 같습니다.

  • manifestVersion: MUST. 호환성 업그레이드에 사용합니다(예: 1).
  • transferId: MUST. 전송 세션의 고유 식별자입니다.
  • createdAt / expiresAt: SHOULD. 수명 주기 처리와 UI 안내에 사용합니다.
  • policy: SHOULD. 정책 요약입니다(다운로드 횟수 제한, 비밀번호 요구 여부, 업로드 완료 전 공유 허용 여부 등).
  • files[]: MUST. 파일 목록 설명입니다(최소한 파일 크기와 청크 범위).
  • chunking: MUST. chunkSize와 chunkCount를 계산하는 방법, 또는 파일별 chunkCount를 포함합니다.
  • objectKeyRule: MUST. (transferId, fileId, chunkIndex)에서 객체 키를 도출하거나, 명시적인 매핑 테이블을 제공합니다.

A.1.1 files[]의 최소 필드

  • fileId: MUST. 고유한 파일 식별자입니다(파일명을 고유 키로 사용하지 마세요).
  • size: MUST. 바이트 단위의 크기입니다.
  • mime: MAY. 표시 및 다운로드 제안에 사용합니다.
  • name: MAY. 엄격한 영지식 / 최소 유출을 원한다면 name을 생략하거나 암호화된 이름을 저장하세요.
  • chunkCount: MUST. 이 파일의 청크 수입니다.
  • chunkOffset: MAY. 여러 파일이 전역 chunkIndex를 공유한다면 오프셋이 필요하고, 그렇지 않으면 생략할 수 있습니다.

A.1.2 무결성 및 검증 필드(선택 사항이지만 권장)

  • chunkHashes[]: SHOULD. 청크별 검증입니다(해시/길이/etag 중 하나 또는 조합).
  • fileHash: MAY. 파일 전체의 체크섬입니다(다운로드 후 검증).
  • ciphertextLength: MAY. 암호문 수준의 길이 일관성 검사입니다(평문이 필요하지 않음).

A.2 청크 객체: 최소 제약

  • 고유한 주소 지정: 청크는 (transferId, fileId, chunkIndex)로 고유하게 지정할 수 있어야 합니다(MUST).
  • 멱등적 업로드: 같은 청크를 다시 업로드해도 최종 상태가 깨져서는 안 됩니다(MUST NOT). 덮어쓰거나 거부할 수 있지만 동작은 일관되어야 합니다.
  • 최소한의 메타데이터: 서버는 관측 가능성과 문제 해결을 위해 암호문 길이, 기록 시각, etag/버전 등만 기록할 수 있습니다(MAY).

A.2.1 객체 키 규칙(예시)

  • /transfers/{transferId}/chunks/{fileId}/{chunkIndex}
  • /transfers/{transferId}/manifest

제약: 객체 키는 transferId 접두사 기준의 일괄 정리를 지원해야 하며(MUST), 민감한 업무 정보를 담지 않는 것이 좋습니다(SHOULD).

A.3 상태 레코드: 최소 필드

상태는 "업로드/다운로드 진행 상황과 복구"에 답합니다. 크기가 작고 읽고 쓰기가 빨라야 합니다.

  • transferId: MUST.
  • status: MUST. 권장 값: UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet: MUST. 완료된 청크 집합이며, 비트맵 / 범위 집합으로 압축하는 것이 좋습니다(SHOULD).
  • uploadedBytes: SHOULD. 진행률 표시와 할당량 확인에 사용합니다(청크에서 도출할 수도 있지만 따로 유지하는 편이 더 빠릅니다).
  • downloadCount: MAY. 다운로드 횟수 제한을 적용한다면 기록하고 원자적으로 갱신해야 합니다(세부 사항은 저장소에 따라 다름).
  • expiresAt: SHOULD. 만료 처리와 백그라운드 정리에 사용합니다.

A.3.1 복구 API의 최소 출력

이어서 전송하려면 서버는 다음을 반환할 수 있어야 합니다(SHOULD).

  • 전송 상태(UPLOADING/READY/DELETED/EXPIRED)
  • uploadedSet(완료된 청크 집합)
  • 정책 요약(예: 할당량 초과, 만료, 업로드를 계속할 수 있는지 여부)

참고: 보안 및 개인정보 보호 백서와의 경계

  • 이 부록은 전송/저장에 필요한 "구조와 제약"만 설명합니다.
  • 암호화 필드, 키 자료의 전달/도출 방식, 인증 실패 시 안전하게 거부(fail closed)하는 동작은 보안 및 개인정보 보호 백서를 참조하세요.