Logo

Anhang: Minimale Datenstrukturen (Manifest/Chunk/State)

Dieser Anhang enthält minimale Empfehlungen für Datenstrukturen für „paralleles Chunking + fortsetzbare Übertragung + idempotente Wiederholungen“. Ziel ist es, Nebenläufigkeit mit hohem Durchsatz und eine zuverlässige Wiederherstellung nach Fehlern zu ermöglichen – ohne komplexe Transaktionen.

Allgemeine Grundsätze

  • Große Objekte vs. kleiner Zustand: Chunks/Manifest sind große Objekte, die im Objektspeicher liegen; der Zustand (State) ist klein und liegt in einem State-Store.
  • Eindeutige Schlüssel und Idempotenz: Ein Chunk MUSS über (transferId, fileId, chunkIndex) eindeutig adressierbar sein, damit erneute Übertragungen idempotent sind.
  • Wiederherstellbarkeit: Der Zustand MUSS die „Menge der abgeschlossenen Teile“ ausdrücken, damit die Wiederherstellung abgeschlossene Teile überspringen kann.
  • Keine Preisgabe sensibler Daten: Objektschlüssel und Zustand SOLLTEN keine sensiblen Felder wie E-Mail-Adressen oder ursprüngliche Dateinamen enthalten (ob diese verschlüsselt werden, hängt von Ihrer Datenschutzrichtlinie ab).

A.1 Minimale Felder des Manifests

Das Manifest ist der „einzige Einstiegspunkt“ des Empfängers für Download und Zusammensetzen. Minimale Empfehlungen:

  • manifestVersion: MUSS. Dient Kompatibilitäts-Upgrades (z. B. 1).
  • transferId: MUSS. Eindeutige Kennung der Übertragungssitzung.
  • createdAt / expiresAt: SOLLTE. Für die Behandlung des Lebenszyklus und Hinweise in der Oberfläche.
  • policy: SOLLTE. Eine Zusammenfassung der Richtlinie (Limits für die Anzahl der Downloads, Passwortpflicht, ob Teilen vor Abschluss erlaubt ist usw.).
  • files[]: MUSS. Beschreibung der Dateiliste (mindestens Dateigrößen und Chunk-Bereiche).
  • chunking: MUSS. Enthält chunkSize und die Berechnung von chunkCount oder chunkCount pro Datei.
  • objectKeyRule: MUSS. Objektschlüssel aus (transferId, fileId, chunkIndex) ableiten oder eine explizite Zuordnungstabelle bereitstellen.

A.1.1 Minimale Felder von files[]

  • fileId: MUSS. Eindeutige Dateikennung (den Dateinamen nicht als eindeutigen Schlüssel verwenden).
  • size: MUSS. Größe in Bytes.
  • mime: KANN. Für Anzeige und Download-Vorschläge.
  • name: KANN. Wenn Sie striktes Zero-Knowledge bzw. minimale Preisgabe wünschen, lassen Sie name weg oder speichern Sie einen verschlüsselten Namen.
  • chunkCount: MUSS. Anzahl der Chunks dieser Datei.
  • chunkOffset: KANN. Wenn sich mehrere Dateien einen globalen chunkIndex teilen, wird ein Offset benötigt; andernfalls kann er entfallen.

A.1.2 Felder für Integrität und Verifizierung (optional, aber empfohlen)

  • chunkHashes[]: SOLLTE. Prüfung pro Chunk (eines oder eine Kombination aus Hash/Länge/ETag).
  • fileHash: KANN. Prüfsumme der gesamten Datei (nach dem Download prüfen).
  • ciphertextLength: KANN. Prüfung der Längenkonsistenz auf Chiffretext-Ebene (kein Klartext nötig).

A.2 Chunk-Objekte: minimale Randbedingungen

  • Eindeutige Adressierung: Ein Chunk MUSS über (transferId, fileId, chunkIndex) eindeutig adressierbar sein.
  • Idempotenter Upload: Das erneute Hochladen desselben Chunks DARF den Endzustand NICHT beschädigen (er darf überschrieben oder abgelehnt werden, das Verhalten muss aber konsistent sein).
  • Minimale Metadaten: Der Server KANN zur Beobachtbarkeit und Fehlersuche nur Chiffretext-Länge, Schreibzeitpunkt, ETag/Version usw. erfassen.

A.2.1 Regel für Objektschlüssel (Beispiel)

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

Randbedingung: Objektschlüssel MÜSSEN die gebündelte Bereinigung über das Präfix transferId unterstützen; Objektschlüssel SOLLTEN keine sensiblen Geschäftsinformationen enthalten.

A.3 State-Datensätze: minimale Felder

Der Zustand beantwortet „Fortschritt von Upload/Download und Wiederherstellung“. Er sollte klein und schnell les- und schreibbar sein.

  • transferId: MUSS.
  • status: MUSS. Empfohlene Werte: UPLOADING / READY / DELETED / EXPIRED.
  • uploadedSet: MUSS. Menge der abgeschlossenen Chunks; SOLLTE mit einer Bitmap / einem Range-Set komprimiert werden.
  • uploadedBytes: SOLLTE. Für Fortschrittsanzeige und Kontingentprüfungen (lässt sich aus den Chunks ableiten, aber ihn mitzuführen ist schneller).
  • downloadCount: KANN. Wenn Sie Limits für die Anzahl der Downloads durchsetzen, muss er erfasst und atomar aktualisiert werden (Details hängen von Ihrem Speicher ab).
  • expiresAt: SOLLTE. Für die Durchsetzung des Ablaufs und die Bereinigung im Hintergrund.

A.3.1 Minimale Ausgabe einer Wiederherstellungs-API

Für fortsetzbare Übertragungen SOLLTE der Server Folgendes zurückgeben können:

  • Übertragungsstatus (UPLOADING/READY/DELETED/EXPIRED)
  • uploadedSet (Menge der abgeschlossenen Chunks)
  • Zusammenfassung der Richtlinie (z. B. Kontingent überschritten, abgelaufen, ob ein Fortsetzen des Uploads erlaubt ist)

Hinweis: Abgrenzung zum Whitepaper zu Sicherheit und Datenschutz

  • Dieser Anhang beschreibt nur die „Strukturen und Randbedingungen“, die für Übertragung und Speicherung nötig sind.
  • Zu Verschlüsselungsfeldern, zur Weitergabe/Ableitung von Schlüsselmaterial und zum Fail-Closed-Verhalten bei Authentifizierungsfehlern siehe das Whitepaper zu Sicherheit und Datenschutz.