Logo

Appendice: strutture dati minime (manifest/chunk/stato)

Questa appendice fornisce raccomandazioni minime sulla struttura dei dati per "chunking parallelo + trasferimento ripristinabile + tentativi idempotenti". L'obiettivo è consentire una concorrenza ad alto rendimento e un ripristino affidabile dopo gli errori, senza transazioni complesse.

Principi generali

  • Oggetti grandi vs. piccolo stato: i blocchi/manifest sono oggetti di grandi dimensioni archiviati nell'archivio oggetti; state è piccola e memorizzata in un archivio statale.
  • Chiavi univoche e idempotenza: un pezzo DEVE essere indirizzabile in modo univoco da (transferId, fileId, ChunkIndex) per ritrasmissioni idempotenti.
  • Recoverability: lo stato DEVE esprimere il "set completato" in modo che il ripristino possa saltare le parti completate.
  • Nessuna perdita sensibile: le chiavi degli oggetti e lo stato DOVREBBERO evitare di incorporare campi sensibili come email o nomi di file originali (se questi siano crittografati dipende dalla tua politica sulla privacy).

A.1 Campi minimi manifesti

Il manifest è il "punto di accesso unico" del ricevitore per il download e il riassemblaggio. Raccomandazioni minime:

  • manifestVersion: DEVE. Utilizzato per aggiornamenti di compatibilità (ad es. 1).
  • transferId: DEVE. Identificatore univoco della sessione di trasferimento.
  • creatoAt / scadeAt: DOVREBBE. Per la gestione del ciclo di vita e i suggerimenti dell'interfaccia utente.
  • policy: DOVREBBE. Un riepilogo delle politiche (limiti del numero di download, requisiti della password, se è consentita la condivisione prima del completamento, ecc.).
  • file[]: DEVE. Descrizione dell'elenco dei file (con dimensioni minime dei file e intervalli di blocchi).
  • chunking: DEVE. Include ChunkSize e il modo in cui viene calcolato ChunkCount o ChunkCount per file.
  • objectKeyRule: DEVE. Deriva le chiavi dell'oggetto da (transferId, fileId, ChunkIndex) o fornisce una tabella di mappatura esplicita.

A.1.1 File minimi[] campi

  • fileId: DEVE. Identificatore univoco del file (non utilizzare il nome file come chiave univoca).
  • size: DEVE. Dimensioni in byte.
  • mime: MAGGIO. Per suggerimenti di visualizzazione e download.
  • name: MAGGIO. Se vuoi una rigorosa conoscenza zero/perdita minima, ometti name o memorizzare un nome crittografato.
  • chunkCount: DEVE. Conteggio dei blocchi per questo file.
  • chunkOffset: MAGGIO. Se più file condividono un file global chunkIndex, è necessario un offset; altrimenti può essere omesso.

A.1.2 Campi di integrità e verifica (facoltativi ma consigliati)

  • ChunkHash[]: DOVREBBE. Verifica per blocco (una o una combinazione di hash/lunghezza/etag).
  • fileHash: MAGGIO. Checksum dell'intero file (verificare dopo il download).
  • ciphertextLength: MAGGIO. Controlli di coerenza della lunghezza a livello di testo cifrato (non è necessario testo in chiaro).

A.2 Oggetti Chunk: vincoli minimi

  • Indirizzamento univoco: un pezzo DEVE essere indirizzabile in modo univoco da (transferId, fileId, ChunkIndex).
  • Caricamento idempotente: ricaricare lo stesso pezzo NON DEVE interrompere lo stato finale (potrebbe sovrascrivere o essere rifiutato, ma il comportamento deve essere coerente).
  • Metadati minimi: il server PUÒ registrare solo la lunghezza del testo cifrato, il tempo di scrittura, l'etag/versione, ecc., per l'osservabilità e la risoluzione dei problemi.

A.2.1 Regola chiave oggetto (esempio)

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

Vincolo: le chiavi degli oggetti DEVONO supportare la pulizia di massa entro transferId prefisso; le chiavi degli oggetti DOVREBBERO evitare di trasportare informazioni aziendali riservate.

A.3 Anagrafe statale: campi minimi

Lo Stato risponde “avanzamento e ripristino caricamento/download”. Dovrebbe essere piccolo e veloce da leggere/scrivere.

  • transferId: DEVE.
  • status: DEVE. Valori suggeriti: UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet: DEVE. Set di pezzi completato; DOVREBBE essere compresso con una bitmap/range-set.
  • uploadedBytes: DOVREBBE. Per la visualizzazione dell'avanzamento e il controllo delle quote (può essere derivato da blocchi, ma mantenerlo è più veloce).
  • downloadCount: MAGGIO. Se applichi limiti di conteggio dei download, è necessario registrarli e aggiornarli in modo atomico (i dettagli dipendono dallo spazio di archiviazione).
  • expiresAt: DOVREBBE. Per l'applicazione della scadenza e la pulizia dello sfondo.

A.3.1 Output minimo per un'API di ripristino

Per i trasferimenti ripristinabili, il server DOVREBBE essere in grado di restituire:

  • Stato del trasferimento (IN CARICAMENTO/PRONTO/ELIMINATO/SCADUTO)
  • uploadedSet (insieme di blocchi completato)
  • Riepilogo delle norme (ad es. quota eccessiva, scaduta, se è consentito continuare il caricamento)

Nota: confine rispetto al Whitepaper su sicurezza e privacy

  • Questa appendice descrive solo le “strutture e vincoli” necessari per il trasferimento/stoccaggio.
  • Per i campi di crittografia, il modo in cui il materiale della chiave viene trasportato/derivato e il comportamento di chiusura in caso di errori di autenticazione, fare riferimento al Whitepaper su sicurezza e privacy.