Zum Inhalt springen
Deutsch

Kompression

Object Storage unterstützt At-Rest-Kompression — Bodies werden vor dem Put komprimiert, beim Get dekomprimiert. Drei Modi; wähle den CPU-gegen-Größe-Kompromiss, der zum Payload passt.

import {
ObjectStorageDurableStateStore,
ObjectStorageDurableStateStoreOptions,
S3ObjectStorageBackend,
S3ObjectStorageOptions,
} from 'actor-ts/persistence';
const objectStorageDurableStateStoreOptions = ObjectStorageDurableStateStoreOptions.create()
.withBackend(new S3ObjectStorageBackend(S3ObjectStorageOptions.create() /* .withRegion(...).withBucket(...) */))
.withCompression({
algorithm: 'zstd',
level: 6, // optional; zstd 1–22 (Default 3)
});
const store = new ObjectStorageDurableStateStore(objectStorageDurableStateStoreOptions);

Jetzt wird jeder persistierte State vor dem Upload zstd-komprimiert. Reads dekomprimieren transparent.

AlgorithmusKompressionsverhältnisCPU-KostenWann
zstdAm bestenNiedrig–moderat (Decode sehr schnell)Große State-Blobs — bestes Verhältnis bei konkurrenzfähiger Geschwindigkeit.
gzipGut (typisch 50-70 %)ModeratUniverseller Default — node:zlib, läuft auf jedem Runtime.
noneKeineNullBereits komprimiert oder winzige Payloads (siehe Hinweis unten).

Der Store-Default ist gzip — es braucht keine native Runtime-Unterstützung und keine Zusatz-Dependency. Für text-lastigen State (JSON) erreichen gzip und zstd beide ~70 % Reduktion; zstd kommt schneller dahin und dekomprimiert flotter. Für bereits komprimierte Daten (verschlüsselte Bytes, Image-Daten) bringt Kompression fast keinen Wert und verschwendet CPU — nimm none.

Es gibt kein brotli und kein deflate — nur none, gzip und zstd.

type CompressionAlgo = 'none' | 'gzip' | 'zstd';
type CompressionConfig = {
algorithm: CompressionAlgo;
level?: number; // algorithmus-spezifisch; geclamped; undefined = Default
};

Level sind algorithmus-spezifisch. Out-of-range-Werte werden geclamped; ohne level gilt der Implementierungs-Default:

  • gzip: 0 (keine Kompression) – 9 (am besten). Default 6.
  • zstd: 1 (am schnellsten) – 22 (am besten). Default 3.
  • none: ignoriert.

Für die meisten Workloads sind die Defaults in Ordnung — dreh nur hoch, wenn Storage-Kosten dominieren.

zstd-Support unterscheidet sich je Richtung:

  • Compress (Write) — nur nativ: Bun (Bun.zstdCompress) oder Node (zlib.zstdCompress). Es gibt keinen Pure-JS-Fallback fürs Schreiben; die optionale fzstd-Peer-Dependency kann nur dekomprimieren. zstd auf einem Runtime ohne native Unterstützung schlägt früh fehl — eager bei der Plugin-Registrierung, nicht kryptisch beim ersten Persist.
  • Decompress (Read) — zuerst node:zlib (die einzige zstd-Implementierung, die eine Output-Grenze zur Allokationszeit entgegennimmt — siehe Dekompressions-Limit), dann Buns Global, dann die optionale fzstd-Peer-Dependency, sodass ein Runtime ohne natives zstd anderswo geschriebene zstd-Bodies trotzdem lesen kann, sobald fzstd installiert ist.

Die nativen Kandidaten — die Compressoren ebenso wie die beiden nativen Decompressoren — werden gewählt, indem sie aufgerufen werden, nicht indem geprüft wird, ob die Funktion existiert. Auf Deno fällt beides auseinander: node:zlib exportiert dort zstd-Einsprungpunkte, hinter denen kein Binding steht. So bekommt ein Runtime ohne funktionierendes zstd die Meldung des Frameworks, die die fehlende Fähigkeit benennt, und der fzstd-Fallback darunter bleibt erreichbar. Die fzstd-Stufe ist die eine, die nicht per Aufruf geprüft wird, und das bewusst: reines JavaScript, kein natives Binding, das fehlen könnte — ein erfolgreicher Import beantwortet also schon, was der Aufruf fragen würde.

Die beiden Punkte oben lesen sich unabhängig voneinander und sind es nicht, deshalb sei die Folge ausdrücklich genannt: Ein Runtime ohne natives zstd kann zstd-Bodies lesen, aber es lässt sich nicht auf zstd konfigurieren. Die Wahl eines Algorithmus drückt Schreibabsicht aus, also prüft die Registrierung den Compress-Pfad — eine Deno-Replika, die zstd einstellt, um zu den Bun-Writern zu passen, denen sie folgt, startet damit nicht. Konfiguriere einen solchen Leser stattdessen mit gzip (oder none): Der konfigurierte Algorithmus entscheidet nur, was der Store schreibt, während jeder Read gemäß dem ATS1-Flag des Bodys selbst dekodiert — ein auf gzip konfigurierter Store liest die zstd-Bodies seiner Peers also unverändert.

gzip nutzt node:zlib und läuft überall (Bun, Node, Deno) ohne Zusatz-Dependency.

Beide Algorithmen rufen die asynchronen Formen der Runtime auf — zlib.gzip, nicht gzipSync; zlib.zstdCompress, nicht zstdCompressSync —, damit ein Kompressor, der aus dem Turn eines Actors heraus aufgerufen wird, nicht den Thread hält, auf dem jeder andere Actor läuft. Wo diese CPU tatsächlich landet, unterscheidet sich je Runtime; siehe CPU-Kosten.

Beim Put:
Wert serialisieren → JSON-Bytes → compress(bytes) → [verschlüsseln] →
mit ATS1-Manifest rahmen → backend.put(framed)
Beim Get:
backend.get → gerahmte Bytes → ATS1-Manifest lesen → [entschlüsseln] →
gemäß Algorithmus-Flag dekomprimieren → JSON → deserialisieren

Jeder Body trägt einen kleinen ATS1-Manifest-Header; ein 2-Bit-Feld im Flags-Byte hält den Kompressions-Algorithmus fest (none / gzip / zstd). Die Dekompression wird ausschließlich von diesem Flag gesteuert — nicht von einem HTTP-Header. (Auf S3 setzt das Framework zusätzlich Content-Encoding als Marker, aber das ist nie die Quelle der Wahrheit fürs Decoding.)

Weil jeder Body seinen Algorithmus selbst beschreibt, funktioniert das Mischen von none / gzip / zstd im selben Bucket — jedes Objekt dekodiert gemäß seinem eigenen Manifest.

Die Dekompression beim Lesen ist standardmäßig auf 512 MiB Output begrenzt, damit ein manipulierter oder bösartiger komprimierter Body (wenige KB, die sich auf viele GB aufblähen) beim Recovery nicht den Speicher sprengt (security audit #3).

gzip und zstd reichen die Grenze an den Decoder durch — über zlibs maxOutputLength —, sodass ein Body über dem Limit abgelehnt wird, bevor sein Output allokiert ist: Die Bombe bekommt den Speicher, für den sie gebaut wurde, gar nicht erst. Jeder Pfad prüft zusätzlich die dekodierte Größe, und genau das begrenzt die beiden Pfade, die die Option nicht entgegennehmen können (Buns Bun.zstdDecompress, das nur auf einem Bun ohne zstd in node:zlib überhaupt drankommt, und der fzstd-Fallback). Dort gilt das Limit weiterhin, aber erst, wenn der Output existiert — auf einem Runtime, das auf einen der beiden zurückfällt, ist die Grenze also eher eine Korrektheitsprüfung als ein Bomb-Schutz.

So oder so scheitert der Read mit einem Fehler, statt den Prozess mit OOM zu beenden, und der Fehler benennt die Grenze (maxOutputBytes=…), damit klar ist, an welcher Einstellung zu drehen ist. Snapshots / Durable-State sind in der Praxis weit kleiner; wer legitim größere Bodies speichert, hebt das Limit mit withMaxDecompressedBytes auf den Store- (oder Plugin-)Optionen an:

const objectStorageDurableStateStoreOptions = ObjectStorageDurableStateStoreOptions.create()
.withBackend(backend)
.withMaxDecompressedBytes(2 * 1024 * 1024 * 1024); // 2 GiB; Infinity opts out

withMaxDecompressedBytes gibt es auf den Snapshot-Store-, Durable-State-Store- und Plugin-Optionen; der Wert wird beim Konstruieren validiert (ein nicht- positiver / nicht-ganzzahliger Cap wirft OptionsError).

Das Level ist eine reine Encoder-Einstellung. Es wird nicht auf dem Wire gespeichert (das Manifest hält den Algorithmus fest, nicht das Level), und der Decompressor braucht es nie — gzip- und zstd-Frames sind selbst-beschreibend.

Daher braucht ein Level-Wechsel keine Migration: Bodies, die mit dem alten Level geschrieben wurden, dekodieren weiter, neue Bodies nutzen das neue Level, und beide mischen sich problemlos. Du kannst das Level auch jederzeit per Actor anheben oder senken, ohne bestehende Daten anzufassen.

serialisieren → JSON-Bytes → compress → [verschlüsseln] → speichern

Kompression läuft nach der Serialisierung und vor der Verschlüsselung — Ciphertext zu komprimieren ist sinnlos (hochentrop), und die feste Reihenfolge vermeidet zudem CRIME-artige Seitenkanäle. Für maximale Größenreduktion bei großem text-lastigem State ist zstd auf höherem Level meist der beste einzelne Hebel.

SzenarioAlgorithmus
Großer text-lastiger State (großes JSON, lange Beschreibungen)zstd
Gemischt Text + Zahlenzstd oder gzip
Maximale Portabilität, natives zstd nicht garantiertgzip
Bereits verschlüsselte / komprimierte Bytesnone (kein Nutzen)
Storage-Kosten-begrenzt, Write-once-Read-manyzstd (Level 15-19)
CPU-begrenzter Write-Pfadgzip Level 1 oder zstd Level 1

Single-Thread, ~100 KB Blob — nur Größenordnung; echte Zahlen hängen von Payload und Runtime ab:

  • gzip Level 6 — ~1-3 ms Encode, ~0,5 ms Decode.
  • gzip Level 1 — ~0,5 ms Encode, schnelles Decode.
  • zstd Level 3 (Default) — Encode vergleichbar mit gzip, besseres Verhältnis, sehr schnelles Decode.
  • zstd Level 19 — spürbar langsamer beim Encode, Decode weiter schnell.
  • zstd Level 20-22 (ultra) — deutlich langsamer beim Encode für marginalen Gewinn; reserviere es für Write-once-Read-many-Bulk-Daten.

zstds Asymmetrie (günstiges Decode auf jedem Level) macht es zu einem starken Default für lese-lastigen State. Für typische State-Store-Workloads (kleine Objekte, moderate Schreibrate) sind die CPU-Kosten unsichtbar.

Wo diese CPU landet, unterscheidet sich je Runtime, und das wiegt schwerer als die Frage, wie viel davon es ist. Die Komprimierung wird aus dem Turn eines Actors heraus aufgerufen, und das Framework ruft die asynchronen zlib-Formen der Runtime (zlib.gzip, zlib.zstdCompress, …) statt der *Sync-Varianten. Auf Bun und Node läuft das Deflate dann auf dem libuv-Thread-Pool, und das Actor-System läuft weiter: Gemessen an einem 24-MiB-Body feuerte ein 1-ms-Timer während des Aufrufs 30–115-mal, wo die Sync-Formen ihn null-mal feuern ließen. Auf Deno 2.6 schieben die asynchronen Formen den Aufruf auf und führen ihn dann als einen Block auf dem Main-Thread aus — korrekt, aber nicht lebendiger als gzipSync —, sodass ein großer Body auf Deno Arbeit der Stufe 2 für den OffloadPool ist; die Persistenzschicht leitet von sich aus bewusst nicht dorthin um. Der Pure-JS-Lese-Fallback fzstd hat keine asynchrone Form und dekodiert auf jeder Runtime auf dem Main-Thread.

Der Tausch, den die asynchronen Formen eingehen, ist Durchsatz gegen Lebendigkeit: Der Streaming-Pfad kostet pro Aufruf mehr — auf Node lief ein asynchrones gunzip desselben Bodys zwei- bis dreimal länger als das synchrone —, während die Event-Loop die ganze Zeit frei bleibt. Für einen State-Store ist das die richtige Seite des Tauschs: Die zusätzlichen Millisekunden landen bei dem einen Actor, der den Write angestoßen hat, nicht im p99 jedes Actors im Prozess.

class SmallStateActor extends DurableStateActor<...> {
protected compression() { return { algorithm: 'none' as const }; }
}
class LogStateActor extends DurableStateActor<...> {
protected compression() { return { algorithm: 'zstd' as const, level: 19 }; }
}

Überschreibe den Store-Level-Default pro Actor. Nützlich, wenn:

  • Die meisten Actors kleinen State haben (keine Kompression nötig).
  • Einige großen text-lastigen State haben (hohe Kompression).

Siehe Per-Actor-Policies.