Logo

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

이 부록에서는 "병렬 청크 + 재개 가능한 전송 + 멱등성 재시도"에 대한 최소한의 데이터 구조 권장 사항을 제공합니다. 목표는 복잡한 트랜잭션 없이 높은 처리량의 동시성과 장애 발생 후 안정적인 복구를 지원하는 것입니다.

일반 원칙

  • 큰 개체와 작은 상태: 청크/매니페스트는 객체 저장소에 저장된 대형 객체입니다. 상태는 작으며 상태 저장소에 저장됩니다.
  • 고유 키 및 멱등성: 멱등성 재전송을 위해 청크는 (transferId, fileId, ChunkIndex)에 의해 고유하게 주소 지정이 가능해야 합니다.
  • Recoverability: 상태는 복구가 완료된 부분을 건너뛸 수 있도록 "완료된 세트"를 표현해야 합니다.
  • 민감한 누출 없음: 객체 키와 상태는 이메일이나 원본 파일 이름과 같은 민감한 필드를 삽입하지 않아야 합니다(암호화 여부는 개인정보 보호정책에 따라 다름).

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

매니페스트는 다운로드 및 재조립을 위한 수신기의 "단일 진입점"입니다. 최소 권장사항:

  • manifestVersion: 반드시 해야 합니다. 호환성 업그레이드에 사용됩니다(예: 1).
  • transferId: 반드시 해야 합니다. 고유한 전송 세션 식별자입니다.
  • 생성 시간/만료 시간: 해야 한다. 수명 주기 처리 및 UI 힌트용입니다.
  • policy: 해야 한다. 정책 요약(다운로드 횟수 제한, 비밀번호 요구 사항, 완료 전 공유 허용 여부 등)
  • 파일[]: 반드시 해야 합니다. 파일 목록 설명(최소 파일 크기 및 청크 범위)
  • chunking: 반드시 해야 합니다. ChunkSize 및 ChunkCount 계산 방법 또는 파일별 ChunkCount를 포함합니다.
  • objectKeyRule: 반드시 해야 합니다. (transferId, fileId, ChunkIndex)에서 객체 키를 파생하거나 명시적인 매핑 테이블을 제공합니다.

A.1.1 최소 files[] 필드

  • fileId: 반드시 해야 합니다. 고유한 파일 식별자(파일 이름을 고유 키로 사용하지 않음)
  • size: 반드시 해야 합니다. 크기(바이트)입니다.
  • mime: 5월. 표시 및 다운로드 제안용입니다.
  • name: 5월. 엄격한 무지식/최소 누출을 원한다면 생략하세요. name 또는 암호화된 이름을 저장하세요.
  • chunkCount: 반드시 해야 합니다. 이 파일의 청크 수입니다.
  • chunkOffset: 5월. 여러 파일이 전역 파일을 공유하는 경우 chunkIndex, 오프셋이 필요합니다. 그렇지 않으면 생략할 수 있습니다.

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

  • 덩어리해시[]: 해야 한다. 청크별 검증(해시/길이/etag 중 하나 또는 조합)
  • fileHash: 5월. 전체 파일 체크섬(다운로드 후 확인)
  • ciphertextLength: 5월. 암호문 수준 길이 일관성 검사(일반 텍스트 필요 없음)

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

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

A.2.1 객체 키 규칙(예)

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

제약조건: 객체 키는 다음을 통한 대량 정리를 지원해야 합니다. transferId 접두사; 객체 키는 민감한 비즈니스 정보를 전달하지 않아야 합니다(SHOULD).

A.3 상태 기록: 최소 필드

상태는 "업로드/다운로드 진행 및 복구"라고 대답합니다. 작고 읽기/쓰기 속도가 빨라야 합니다.

  • transferId：반드시입니다.
  • status: 반드시 해야 합니다. 제안된 값: UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet: 반드시 해야 합니다. 완성된 청크 세트; 비트맵/범위 집합으로 압축해야 합니다(SHOULD).
  • uploadedBytes: 해야 한다. 진행률 표시 및 할당량 확인용(청크에서 파생될 수 있지만 유지하는 것이 더 빠릅니다).
  • downloadCount: 5월. 다운로드 횟수 제한을 적용하는 경우 원자적으로 기록하고 업데이트해야 합니다(세부 사항은 저장소에 따라 다름).
  • expiresAt: 해야 한다. 만료 시행 및 백그라운드 정리를 위해.

A.3.1 복구 API에 대한 최소 출력

재개 가능한 전송의 경우 서버는 다음을 반환할 수 있어야 합니다.

  • 전송 상태(업로드 중/준비/삭제/만료됨)
  • UploadSet(완성된 청크 세트)
  • 정책 요약(예: 할당량 초과, 만료, 계속 업로드 허용 여부)

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

  • 이 부록에서는 전송/저장에 필요한 "구조 및 제약"에 대해서만 설명합니다.
  • 암호화 필드, 키 자료가 전달/파생되는 방법, 인증 실패 시 페일클로즈 동작에 대해서는 보안 및 개인 정보 보호 백서를 참조하세요.