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.
Algorithmen
Abschnitt betitelt „Algorithmen“| Algorithmus | Kompressionsverhältnis | CPU-Kosten | Wann |
|---|---|---|---|
zstd | Am besten | Niedrig–moderat (Decode sehr schnell) | Große State-Blobs — bestes Verhältnis bei konkurrenzfähiger Geschwindigkeit. |
gzip | Gut (typisch 50-70 %) | Moderat | Universeller Default — node:zlib, läuft auf jedem Runtime. |
none | Keine | Null | Bereits 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
brotliund keindeflate— nurnone,gzipundzstd.
Konfiguration
Abschnitt betitelt „Konfiguration“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.
Runtime-Unterstützung
Abschnitt betitelt „Runtime-Unterstützung“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 optionalefzstd-Peer-Dependency kann nur dekomprimieren.zstdauf 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 optionalefzstd-Peer-Dependency, sodass ein Runtime ohne natives zstd anderswo geschriebene zstd-Bodies trotzdem lesen kann, sobaldfzstdinstalliert 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.
Wie es funktioniert
Abschnitt betitelt „Wie es funktioniert“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 → deserialisierenJeder 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.
Dekompressions-Limit (Bomb-Schutz)
Abschnitt betitelt „Dekompressions-Limit (Bomb-Schutz)“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 outwithMaxDecompressedBytes 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).
Level wechseln
Abschnitt betitelt „Level wechseln“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.
Kompression + Serialisierung
Abschnitt betitelt „Kompression + Serialisierung“serialisieren → JSON-Bytes → compress → [verschlüsseln] → speichernKompression 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.
Wann was verwenden
Abschnitt betitelt „Wann was verwenden“| Szenario | Algorithmus |
|---|---|
| Großer text-lastiger State (großes JSON, lange Beschreibungen) | zstd |
| Gemischt Text + Zahlen | zstd oder gzip |
| Maximale Portabilität, natives zstd nicht garantiert | gzip |
| Bereits verschlüsselte / komprimierte Bytes | none (kein Nutzen) |
| Storage-Kosten-begrenzt, Write-once-Read-many | zstd (Level 15-19) |
| CPU-begrenzter Write-Pfad | gzip Level 1 oder zstd Level 1 |
CPU-Kosten (grobe Richtwerte)
Abschnitt betitelt „CPU-Kosten (grobe Richtwerte)“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.
Per-Actor-Override
Abschnitt betitelt „Per-Actor-Override“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.
Wie geht’s weiter
Abschnitt betitelt „Wie geht’s weiter“- Object Storage im Überblick — das größere Bild.
- Verschlüsselung — das komplementäre At-Rest-Feature.
- Per-Actor-Policies — Kompression pro Actor konfigurieren.
