Logo

附錄：最小資料結構（清單/區塊/狀態）

本附錄為「並行分塊+可恢復傳輸+冪等重試」提供了最小的資料結構建議。 目標是實現高吞吐量並發和故障後的可靠恢復，而無需複雜的事務。

一般原則

  • 大物件與小狀態： chunks/manifest 是儲存在物件儲存中的大物件；狀態很小並儲存在狀態儲存中。
  • 唯一鍵和冪等性： 對於冪等重傳，區塊必須可以透過（transferId、fileId、chunkIndex）唯一尋址。
  • Recoverability: 狀態必須表達“已完成的集合”，以便恢復可以跳過已完成的部分。
  • 無敏感洩漏： 物件金鑰和狀態應該避免嵌入敏感字段，例如電子郵件或原始文件名（這些字段是否加密取決於您的隱私策略）。

A.1 顯式最小字段

清單是接收者用於下載和重組的「單一入口點」。最低限度的建議：

  • manifestVersion： 必須。用於相容性升級（例如， 1).
  • transferId： 必須。唯一的傳輸會話識別碼。
  • 創建時間/過期時間： 應該。用於生命週期處理和 UI 提示。
  • policy： 應該。策略摘要（下載計數限制、密碼要求、是否允許完成前共享等）。
  • 文件[]： 必須。文件列表描述（最小檔案大小和區塊範圍）。
  • chunking： 必須。包括 chunkSize 以及 chunkCount 的計算方式，或每個檔案的 chunkCount。
  • objectKeyRule： 必須。從 (transferId, fileId, chunkIndex) 派生物件鍵，或提供明確映射表。

A.1.1 最小文件[]字段

  • fileId： 必須。唯一檔案識別碼（不要使用檔案名稱作為唯一鍵）。
  • size： 必須。大小（以位元組為單位）。
  • mime： 可能。用於顯示和下載建議。
  • name： 可能。如果您想要嚴格的零知識/最小洩漏，請省略 name 或儲存加密的名稱。
  • chunkCount： 必須。該文件的區塊計數。
  • chunkOffset： 可能。如果多個檔案共享一個全域 chunkIndex，需要偏移量；否則可以省略。

A.1.2 完整性和驗證欄位（可選但建議）

  • 區塊哈希[]： 應該。每區塊驗證（哈希/長度/etag 之一或組合）。
  • fileHash： 可能。整個文件校驗和（下載後驗證）。
  • ciphertextLength： 可能。密文級長度一致性檢查（不需要明文）。

A.2 區塊物件：最小約束

  • 唯一尋址： 區塊必須可以透過（transferId、fileId、chunkIndex）唯一尋址。
  • 冪等上傳： 重新上傳相同的區塊不得破壞最終狀態（它可能會覆蓋或被拒絕，但行為必須一致）。
  • 最少的元資料： 伺服器可以僅記錄密文長度、寫入時間、etag/版本等，以便於觀察和故障排除。

A.2.1 物件鍵規則（範例）

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

約束：物件鍵必須支援批次清理 transferId 前綴；物件鍵應避免攜帶敏感的業務資訊。

A.3 狀態記錄：最小字段

狀態回答“上傳/下載進度和恢復”。它應該小且讀/寫速度快。

  • transferId：必須。
  • status： 必須。建議值： UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet： 必須。完成的區塊集；應使用位圖/範圍集進行壓縮。
  • uploadedBytes： 應該。用於進度顯示和配額檢查（可以從區塊派生，但維護速度更快）。
  • downloadCount： 可能。如果您強制執行下載計數限制，則必須以原子方式記錄和更新（詳細資訊取決於您的儲存）。
  • expiresAt： 應該。用於到期執行和後台清理。

A.3.1 恢復 API 的最小輸出

對於可恢復傳輸，伺服器應該能夠返回：

  • 傳輸狀態（上傳/就緒/已刪除/已過期）
  • uploadedSet（已完成的區塊集）
  • 政策摘要（例如：超配額、過期、是否允許繼續上傳）

注意：邊界與安全與隱私白皮書

  • 本附錄僅描述傳輸/儲存所需的「結構和限制」。
  • 有關加密欄位、金鑰材料如何攜帶/派生以及身份驗證失敗時的失敗關閉行為，請參閱安全性和隱私白皮書。