Logo

Annexe : Structures de données minimales (manifeste/morceau/état)

Cette annexe fournit des recommandations minimales en matière de structure de données pour « le regroupement parallèle + le transfert pouvant être repris + les tentatives idempotentes ». L’objectif est de permettre une simultanéité à haut débit et une récupération fiable après des pannes, sans transactions complexes.

Principes généraux

  • Grands objets vs petit État : les morceaux/manifestes sont de gros objets stockés dans le stockage d'objets ; l'état est petit et stocké dans un magasin d'État.
  • Clés uniques et idempotence : un fragment DOIT être adressable de manière unique par (transferId, fileId, chunkIndex) pour les retransmissions idempotentes.
  • Recoverability: l'état DOIT exprimer « l'ensemble terminé » afin que la récupération puisse ignorer les parties terminées.
  • Aucune fuite sensible : les clés d'objet et l'état DEVRAIENT éviter d'intégrer des champs sensibles tels que l'e-mail ou les noms de fichiers originaux (le fait que ceux-ci soient cryptés dépend de votre politique de confidentialité).

A.1 Champs minimaux du manifeste

Le manifeste est le « point d’entrée unique » du destinataire pour le téléchargement et le réassemblage. Recommandations minimales :

  • manifestVersion: DOIT. Utilisé pour les mises à niveau de compatibilité (par exemple, 1).
  • transferId: DOIT. Identifiant unique de la session de transfert.
  • créé à / expire à: DEVRAIT. Pour la gestion du cycle de vie et les conseils d’interface utilisateur.
  • policy: DEVRAIT. Un résumé de la politique (limites du nombre de téléchargements, exigence de mot de passe, si le partage avant la fin est autorisé, etc.).
  • fichiers[]: DOIT. Description de la liste de fichiers (avec tailles de fichiers et plages de morceaux minimales).
  • chunking: DOIT. Inclut chunkSize et la façon dont chunkCount est calculé, ou chunkCount par fichier.
  • objectKeyRule: DOIT. Dérivez les clés d'objet à partir de (transferId, fileId, chunkIndex) ou fournissez une table de mappage explicite.

A.1.1 Champs minimaux de fichiers[]

  • fileId: DOIT. Identificateur de fichier unique (n'utilisez pas le nom de fichier comme clé unique).
  • size: DOIT. Taille en octets.
  • mime: MAI. Pour des suggestions d’affichage et de téléchargement.
  • name: MAI. Si vous souhaitez une connaissance nulle et une fuite minimale, omettez name ou stocker un nom crypté.
  • chunkCount: DOIT. Nombre de fragments pour ce fichier.
  • chunkOffset: MAI. Si plusieurs fichiers partagent un fichier global chunkIndex, un décalage est nécessaire ; sinon, il peut être omis.

A.1.2 Champs d'intégrité et de vérification (facultatif mais recommandé)

  • chunkHashes[]: DEVRAIT. Vérification par fragment (un ou une combinaison de hachage/longueur/etag).
  • fileHash: MAI. Somme de contrôle du fichier entier (vérifier après le téléchargement).
  • ciphertextLength: MAI. Vérifications de cohérence de la longueur du texte chiffré (aucun texte en clair n'est nécessaire).

A.2 Objets Chunk : contraintes minimales

  • Adressage unique : un morceau DOIT être adressable de manière unique par (transferId, fileId, chunkIndex).
  • Téléchargement idempotent : le nouveau téléchargement du même morceau NE DOIT PAS rompre l'état final (il peut être écrasé ou rejeté, mais le comportement doit être cohérent).
  • Métadonnées minimales : le serveur PEUT enregistrer uniquement la longueur du texte chiffré, l'heure d'écriture, l'étiquette/version, etc., à des fins d'observabilité et de dépannage.

A.2.1 Règle de clé d'objet (exemple)

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

Contrainte : les clés d'objet DOIVENT prendre en charge le nettoyage en masse en transferId préfixe; les clés d'objet DEVRAIENT éviter de transporter des informations commerciales sensibles.

A.3 Enregistrements d'état : champs minimaux

L’État répond « progression et récupération du téléchargement/téléchargement ». Il doit être petit et rapide en lecture/écriture.

  • transferId：DOIT。
  • status: DOIT. Valeurs suggérées : UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet: DOIT. Ensemble de morceaux terminé ; DEVRAIT être compressé avec un bitmap/range-set.
  • uploadedBytes: DEVRAIT. Pour l'affichage de la progression et les contrôles de quotas (peut être dérivé de morceaux, mais sa maintenance est plus rapide).
  • downloadCount: MAI. Si vous appliquez des limites de nombre de téléchargements, ceux-ci doivent être enregistrés et mis à jour de manière atomique (les détails dépendent de votre stockage).
  • expiresAt: DEVRAIT. Pour le respect des expirations et le nettoyage en arrière-plan.

A.3.1 Résultat minimal pour une API de récupération

Pour les transferts pouvant être repris, le serveur DEVRAIT être capable de renvoyer :

  • Statut du transfert (UPLOADING/READY/DELETED/EXPIRED)
  • uploadedSet (ensemble de morceaux terminé)
  • Résumé de la politique (par exemple, dépassement du quota, expiration, si la poursuite du téléchargement est autorisée)

Remarque : limite par rapport au livre blanc sur la sécurité et la confidentialité

  • Cette annexe décrit uniquement les « structures et contraintes » nécessaires au transfert/stockage.
  • Pour les champs de chiffrement, la manière dont les éléments de clé sont transportés/dérivés et le comportement de fermeture en cas d'échec d'authentification, reportez-vous au livre blanc sur la sécurité et la confidentialité.