Logo

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

Questa appendice fornisce indicazioni minime sulle strutture dati per “suddivisione in chunk in parallelo + trasferimento ripristinabile + nuovi tentativi idempotenti”. L'obiettivo è consentire una concorrenza ad alto throughput e un recupero affidabile dopo i guasti, senza transazioni complesse.

Principi generali

  • Oggetti grandi vs. stato piccolo: i chunk e il manifest sono oggetti grandi archiviati nell'object storage; lo stato è piccolo e viene conservato in uno state store.
  • Chiavi univoche e idempotenza: un chunk DEVE essere indirizzabile in modo univoco tramite (transferId, fileId, chunkIndex) per consentire ritrasmissioni idempotenti.
  • Recuperabilità: lo stato DEVE esprimere l'“insieme dei completati”, in modo che il recupero possa saltare le parti già completate.
  • Nessuna fuga di dati sensibili: le chiavi degli oggetti e lo stato DOVREBBERO evitare di incorporare campi sensibili come l'e-mail o i nomi originali dei file (se questi siano cifrati dipende dalla tua policy sulla privacy).

A.1 Campi minimi del manifest

Il manifest è l'“unico punto di ingresso” del destinatario per il download e il riassemblaggio. Indicazioni minime:

  • manifestVersion: DEVE. Serve per gli aggiornamenti di compatibilità (ad es. 1).
  • transferId: DEVE. Identificatore univoco della sessione di trasferimento.
  • createdAt / expiresAt: DOVREBBE. Per la gestione del ciclo di vita e i suggerimenti nell'interfaccia.
  • policy: DOVREBBE. Un riepilogo delle policy (limiti al numero di download, obbligo di password, se la condivisione prima del completamento è consentita, ecc.).
  • files[]: DEVE. Descrizione dell'elenco dei file (come minimo dimensioni dei file e intervalli di chunk).
  • chunking: DEVE. Include chunkSize e il modo in cui si calcola chunkCount, oppure un chunkCount per ogni file.
  • objectKeyRule: DEVE. Ricava le chiavi degli oggetti da (transferId, fileId, chunkIndex) oppure fornisce una tabella di corrispondenza esplicita.

A.1.1 Campi minimi di files[]

  • fileId: DEVE. Identificatore univoco del file (non usare il nome del file come chiave univoca).
  • size: DEVE. Dimensione in byte.
  • mime: PUÒ. Per la visualizzazione e i suggerimenti di download.
  • name: PUÒ. Se vuoi uno zero-knowledge rigoroso / una fuga minima di informazioni, ometti name o memorizza un nome cifrato.
  • chunkCount: DEVE. Numero di chunk di questo file.
  • chunkOffset: PUÒ. Se più file condividono un chunkIndex globale serve un offset; altrimenti si può omettere.

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

  • chunkHashes[]: DOVREBBE. Verifica per singolo chunk (uno o una combinazione di hash/lunghezza/etag).
  • fileHash: PUÒ. Checksum dell'intero file (da verificare dopo il download).
  • ciphertextLength: PUÒ. Controlli di coerenza della lunghezza a livello di testo cifrato (non serve il testo in chiaro).

A.2 Oggetti chunk: vincoli minimi

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

A.2.1 Regola per le chiavi degli oggetti (esempio)

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

Vincolo: le chiavi degli oggetti DEVONO consentire la pulizia in blocco tramite il prefisso transferId; le chiavi degli oggetti DOVREBBERO evitare di contenere informazioni commerciali sensibili.

A.3 Record di stato: campi minimi

Lo stato risponde a “avanzamento e recupero di caricamento/download”. Dovrebbe essere piccolo e veloce da leggere/scrivere.

  • transferId: DEVE.
  • status: DEVE. Valori suggeriti: UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet: DEVE. Insieme dei chunk completati; DOVREBBE essere compresso con una bitmap / range-set.
  • uploadedBytes: DOVREBBE. Per mostrare l'avanzamento e controllare le quote (si può ricavare dai chunk, ma mantenerlo è più veloce).
  • downloadCount: PUÒ. Se applichi limiti al numero di download, va registrato e aggiornato in modo atomico (i dettagli dipendono dal tuo storage).
  • expiresAt: DOVREBBE. Per applicare la scadenza e per la pulizia in background.

A.3.1 Output minimo di un'API di recupero

Per i trasferimenti ripristinabili, il server DOVREBBE poter restituire:

  • Stato del trasferimento (UPLOADING/READY/DELETED/EXPIRED)
  • uploadedSet (insieme dei chunk completati)
  • Riepilogo delle policy (ad es. quota superata, scaduto, se è consentito proseguire il caricamento)

Nota: confine rispetto al Whitepaper su sicurezza e privacy

  • Questa appendice descrive solo le “strutture e i vincoli” necessari per il trasferimento e l'archiviazione.
  • Per i campi di crittografia, per il modo in cui il materiale delle chiavi viene trasportato/derivato e per il comportamento fail-closed in caso di errori di autenticazione, fai riferimento al Whitepaper su sicurezza e privacy.